Add Media options, add Media Summary component, deprecate Event Summa…

…ry component (#1954)

* Add element class properties to media object

* Add Media Summary component

* Add deprecation statuses

.changeset/lovely-pans-rush.md

@@ -0,0 +1,5 @@
+---
+'@cloudfour/patterns': patch
+---
+
+Deprecated the Button Swap component

.changeset/short-clouds-buy.md

@@ -0,0 +1,6 @@
+---
+'@cloudfour/patterns': minor
+---
+
+- Add Media Summary component, extending the Media object for linked content summaries (events, books, projects, etc.)
+- Deprecated the Event Summary component

.changeset/tricky-poems-hide.md

@@ -0,0 +1,5 @@
+---
+'@cloudfour/patterns': minor
+---
+
+Add `object_class` and `content_class` properties to the Media object template to make it more extensible

.storybook/main.js

@@ -19,9 +19,11 @@ module.exports = {
       },
     },
     '@storybook/addon-a11y',
-    'storybook-mobile',
+    // Disabling these two until they are fixed upstream
+    // 'storybook-mobile',
+    // '@whitespace/storybook-addon-html',
     'storybook-addon-outline',
-    '@whitespace/storybook-addon-html',
+    '@etchteam/storybook-addon-status',
     '@storybook/addon-postcss',
   ],
   managerHead: (head) => {

package.json

@@ -49,6 +49,7 @@
     "@changesets/changelog-github": "0.4.5",
     "@changesets/cli": "2.23.1",
     "@cloudfour/eslint-plugin": "20.0.2",
+    "@etchteam/storybook-addon-status": "^4.2.1",
     "@rollup/plugin-babel": "5.3.1",
     "@rollup/plugin-node-resolve": "13.3.0",
     "@storybook/addon-a11y": "6.5.9",

src/components/button-swap/button-swap.stories.mdx

@@ -4,6 +4,7 @@ import buttonSwap from './button-swap.twig';
 
 <Meta
   title="Components/Button Swap"
+  parameters={{ status: { type: 'deprecated' } }}
   argTypes={{
     content_start_icon: {
       options: ['bell', 'magnifying-glass'],
@@ -19,6 +20,8 @@ import buttonSwap from './button-swap.twig';
 
 # Button Swap
 
+**Note:** This component has been deprecated and will be removed in a future update.
+
 The Button Swap component was built with the article Push Notifications use case in mind. It has two buttons that are swapped on click representing two visual states accompanied with visually hidden text for a more inclusive experience.
 
 You have the ability to pass `initialCallback` and `swappedCallback` callback functions to the `initButtonSwap` initialization function to add custom actions for when each of the buttons is clicked.

src/components/event-summary/event-summary.stories.mdx

@@ -1,10 +1,15 @@
 import { Canvas, Meta, Story } from '@storybook/addon-docs';
 import template from './event-summary.twig';
 
-<Meta title="Components/Event Summary" />
+<Meta
+  title="Components/Event Summary"
+  parameters={{ status: { type: 'deprecated' } }}
+/>
 
 # Event Summary
 
+**Note:** This component has been deprecated, please use the [Media Summary component](/docs/components-media-summary--event) instead.
+
 Combines the [Media object](/docs/objects-media--image) and [Calendar Date component](/docs/components-calendar-date--basic) to display information for an upcoming speaking event.
 
 <Canvas>

src/components/media-summary/demo/book.twig

@@ -0,0 +1,14 @@
+{% embed '@cloudfour/components/media-summary/media-summary.twig' with {
+  heading: "Progressive Web Apps",
+  href: "https://cloudfour.com/thinks/progressive-web-apps-book-now-available/",
+  reverse_markup: true,
+  align_start: true,
+  class: 'o-media--1-by-2@l',
+} only %}
+  {% block object %}
+    <img src="/media/home-page/bookicon.png" width="730" height="992" alt="" style="width: 7em;">
+  {% endblock %}
+  {% block content %}
+    <p>Progressive web apps represent the next big digital opportunity: they look and feel like native apps, they work offline, and they’re available to anyone—no app store required.</p>
+  {% endblock %}
+{% endembed %}

src/components/media-summary/demo/event.twig

@@ -0,0 +1,16 @@
+{% embed '@cloudfour/components/media-summary/media-summary.twig' with {
+  heading: "Smashing Magazine",
+  href: "https://cloudfour.com",
+  reverse_markup: true,
+} only %}
+  {% block object %}
+    {% include '@cloudfour/components/calendar-date/calendar-date.twig' with {
+      "datetime": "2022-07-14T23:25:59.626Z",
+      "note": "3-day event"
+    } only %}
+  {% endblock %}
+  {% block content %}
+    <p>New York, NY</p>
+    <p>Speakers: Megan, Aileen</p>
+  {% endblock %}
+{% endembed %}

src/components/media-summary/media-summary.scss

@@ -0,0 +1,59 @@
+@use '../../compiled/tokens/scss/brightness';
+@use '../../compiled/tokens/scss/color';
+@use '../../compiled/tokens/scss/ease';
+@use '../../compiled/tokens/scss/scale';
+@use '../../compiled/tokens/scss/size';
+@use '../../compiled/tokens/scss/transition';
+@use '../../mixins/focus';
+
+/// The focus outline feels a little snug directly on the outer edge, but we
+/// don't want to extend _too_ far out for fear of colliding with adjacent
+/// content. Doubling the size of the focus edge felt like a nice compromise.
+///
+/// @type Number
+/// @access private
+
+$_focus-overflow: (size.$edge-large * -1);
+
+.c-media-summary {
+  position: relative;
+}
+
+.c-media-summary__link {
+  // Keyboard focus styles take inspiration from buttons and similar elements
+  @include focus.focus-visible {
+    &::after {
+      box-shadow: 0 0 0 size.$edge-large color.$brand-primary-lighter;
+    }
+  }
+
+  // Only show the underline on hover.
+  &:not(:hover) {
+    text-decoration: none;
+  }
+
+  // Cover the entire component with an absolute positioned pseudo element. This
+  // is easier to use for assistive devices than a block-level link or multiple
+  // redundant links and requires no JavaScript. It does sacrifice ease of text
+  // selection, but that shouldn't be a huge issue assuming these components are
+  // linking to a full information source.
+  &::after {
+    border-radius: size.$border-radius-medium;
+    content: '';
+    inset: $_focus-overflow;
+    position: absolute;
+    z-index: 1;
+  }
+}
+
+.c-media-summary__object {
+  transition: filter transition.$slow ease.$out;
+
+  .c-media-summary--with-link:hover & {
+    filter: brightness(brightness.$control-brighten);
+  }
+
+  .c-media-summary--with-link:active & {
+    filter: brightness(brightness.$control-dim);
+  }
+}

src/components/media-summary/media-summary.stories.mdx

@@ -0,0 +1,63 @@
+import { Canvas, Meta, Story } from '@storybook/addon-docs';
+import bookDemo from './demo/book.twig';
+import eventDemo from './demo/event.twig';
+// The '!!raw-loader!' syntax is a non-standard, Webpack-specific, syntax.
+// See: https://github.com/webpack-contrib/raw-loader#examples
+// For now, it seems likely Storybook is pretty tied to Webpack, therefore, we are
+// okay with the following Webpack-specific raw loader syntax. It's better to leave
+// the ESLint rule enabled globally, and only thoughtfully disable as needed (e.g.
+// within a Storybook docs page and not within an actual component).
+// This can be revisited in the future if Storybook no longer relies on Webpack.
+// eslint-disable-next-line @cloudfour/import/no-webpack-loader-syntax
+import bookDemoSource from '!!raw-loader!./demo/book.twig';
+// eslint-disable-next-line @cloudfour/import/no-webpack-loader-syntax
+import eventDemoSource from '!!raw-loader!./demo/event.twig';
+
+<Meta title="Components/Media Summary" />
+
+# Media Summary
+
+The Media Summary components extends [the Media object](/docs/objects-media--image) with functionality specific to linked content summaries.
+
+## Examples
+
+An event summary with [a Calendar Date component](/docs/components-calendar-date--basic) as its object:
+
+<Canvas>
+  <Story
+    name="Event"
+    parameters={{ docs: { source: { code: eventDemoSource } } }}
+  >
+    {(args) => eventDemo(args)}
+  </Story>
+</Canvas>
+
+A book summary that uses [Media object properties](/docs/objects-media--image) to adjust its layout:
+
+<Canvas>
+  <Story
+    name="Book"
+    parameters={{ docs: { source: { code: bookDemoSource } } }}
+  >
+    {(args) => bookDemo(args)}
+  </Story>
+</Canvas>
+
+## Template Properties
+
+All [Media object](/docs/objects-media--image) properties are supported, along with the following unique properties:
+
+- `heading` (string): Content for the heading. Also available as a block.
+- `heading_class` (string): Sets the `class` property of [the Heading component](/docs/components-heading--example).
+- `heading_id` (string): Sets the `id` property of [the Heading component](/docs/components-heading--example).
+- `heading_level` (string, default `3`): Sets the `level` property of [the Heading component](/docs/components-heading--example).
+- `heading_tag_name` (string): Sets the `tag_name` property of [the Heading component](/docs/components-heading--example).
+- `heading_weight` (string): Sets the `weight` property of [the Heading component](/docs/components-heading--example).
+- `href` (string): The URL to link to if the heading has content.
+- `rhythm` (string, default `"compact"`): Sets the amount of [vertical rhythm](/docs/objects-rhythm--example) for the heading and content.
+
+## Template Blocks
+
+All [Media object](/docs/objects-media--image) blocks are supported, along with the following unique blocks:
+
+- `heading`: Content for the heading. Also available as a property.

src/components/media-summary/media-summary.twig

@@ -0,0 +1,67 @@
+{% set _heading_level = heading_level|default(3) %}
+{% set _rhythm = rhythm ?? 'compact' %}
+
+{% set _class -%}
+  c-media-summary
+  {% if href %}c-media-summary--with-link{% endif %}
+  {{class}}
+{%- endset %}
+
+{% set _object_class -%}
+  c-media-summary__object {{object_class}}
+{%- endset %}
+
+{% set _content_class -%}
+  {% if _rhythm %}
+    o-rhythm o-rhythm--{{_rhythm}}
+  {% endif %}
+  {{content_class}}
+{%- endset %}
+
+{% set _heading_value -%}
+  {% block heading %}{{heading}}{% endblock %}
+{%- endset %}
+
+{% set _heading_content -%}
+  {% if _heading_value %}
+    {% if href %}
+      <a class="c-media-summary__link"
+        href="{{href}}">
+      {{_heading_value}}
+      </a>
+    {% else %}
+      {{_heading_value}}
+    {% endif %}
+  {% endif %}
+{%- endset %}
+
+{% set _object %}{% block object %}{% endblock %}{% endset %}
+{% set _content %}{% block content %}{% endblock %}{% endset %}
+
+{% set _heading %}
+  {% if _heading_content %}
+    {% include '@cloudfour/components/heading/heading.twig' with {
+      content: _heading_content,
+      level: heading_level|default(3),
+      id: heading_id,
+      tag_name: heading_tag_name,
+      weight: heading_weight,
+      class: heading_class,
+    } only %}
+  {% endif %}
+{% endset %}
+
+{% embed '@cloudfour/objects/media/media.twig' with {
+  class: _class,
+  content_class: _content_class,
+  object_class: _object_class,
+  _object: _object,
+  _heading: _heading,
+  _content: _content,
+} %}
+  {% block object %}{{_object}}{% endblock %}
+  {% block content %}
+    {{_heading}}
+    {{_content}}
+  {% endblock %}
+{% endembed %}

src/objects/media/media.stories.mdx

@@ -86,6 +86,8 @@ const imageDemoTransformSource = (_src, storyContext) => {
     },
     text: { type: { name: 'string' } },
     class: { type: { name: 'string' } },
+    content_class: { type: { name: 'string' } },
+    object_class: { type: { name: 'string' } },
     reverse: { type: { name: 'boolean' } },
   }}
 />
@@ -256,6 +258,8 @@ of the same name](/docs/objects-deck--block-alignment).
 ## Template Properties
 
 - `class` (string): Appends to the CSS class of the root element
+- `object_class` (string): Appends to the CSS class of the media object element
+- `content_class` (string): Appends to the CSS class of the media content element
 - `tag_name` (string, default `'div'`): The root tag for the component
 - `inner_tag_name` (string, default `'div'`): The tag for both the media content and media object elements
 - `object_tag_name` (string, default `inner_tag_name`): The tag for the media object element

src/objects/media/media.twig

@@ -17,7 +17,7 @@
 #}
 {% if 'o-media__object' not in object_block %}
   {% set object_block %}
-    <{{ object_tag_name }} class="o-media__object">
+    <{{ object_tag_name }} class="o-media__object {{object_class}}">
       {{ object_block }}
     </{{ object_tag_name }}>
   {% endset %}
@@ -30,7 +30,7 @@
   {% if not reverse_markup %}
     {{ object_block }}
   {% endif %}
-  <{{ content_tag_name }} class="o-media__content">
+  <{{ content_tag_name }} class="o-media__content {{content_class}}">
     {% block content %}
     {% endblock %}
   </{{ content_tag_name }}>