docs(elements): update images and summaries (#1007)

* feat: update all screenshots for /elements

* docs: update element summaries

* docs: update subnav summary

* fix: missed pagination summary

* fix: card summary coming from JSDoc

* docs: update feedback snippet

* fix: filter should first try to return alias

* fix: linting errors

* feat: add alias for subnav

* style: remove border from gray bg example

* chore: rename asset

* feat: update make a request verbiage

* fix: account for elements that don't have a docsPage

* feat: include coming soon items

* docs: remove subnavigation from docs site

* Revert "docs: remove subnavigation from docs site"

This reverts commit 3f35bcf.

* refactor: moving screenshots to individual element docs

---------

Co-authored-by: Benny Powers <bennypowers@users.noreply.github.com>

.pfe.config.json

@@ -6,7 +6,8 @@
     "rh-cta": "Call to Action",
     "rh-stat": "Statistic",
     "rh-navigation": "Navigation (primary)",
-    "rh-navigation-secondary": "Navigation (secondary)"
+    "rh-navigation-secondary": "Navigation (secondary)",
+    "rh-subnav": "Subnavigation"
   },
   "site": {
     "title": "Red Hat Design System",

docs/_data/comingSoonItems.yaml

@@ -0,0 +1,2 @@
+- rh-breadcrumb
+- rh-footnote

docs/_includes/component/header.njk

@@ -127,9 +127,12 @@
                 {%- set slug = fst.slug -%}
                 {%- set href = '/elements/' + slug + '/' -%}
                 {%- set linkTitle = fst.alias or (slug | deslugify) -%}
-                <li class="site-navigation__sub-menu__item">
-                  {{ menuLink(linkTitle, href, 'site-navigation__sub-menu__link') }}
-                </li>
+                {%- set comingSoon = tagName in comingSoonItems  -%}
+                {% if not comingSoon %}
+                  <li class="site-navigation__sub-menu__item">
+                    {{ menuLink(linkTitle, href, 'site-navigation__sub-menu__link') }}
+                  </li>
+                {% endif %}                
               {%- endfor -%}
             </ul>
           </details>

docs/_includes/feedback.html

@@ -10,11 +10,8 @@ <h2>Related elements or patterns</h2>
         </li>{% endfor %}
       </ul>
     {% else %}
-      <h2>Foundations</h2>
-      <p>
-        To learn how to use our other components in your designs,
-        visit the <a href="{{ '/elements/' | url }}">Elements</a> section.
-      </p>
+      <h2>Patterns</h2>
+      <p>To learn how to use our patterns in your designs, visit the <a href="{{ '/patterns/' | url }}">Patterns</a> section.</p>
     {% endif %}
   {% endsection %}
 

docs/_plugins/rhds.cjs

@@ -159,7 +159,8 @@ module.exports = function(eleventyConfig, { tagsToAlphabetize }) {
   eleventyConfig.addTransform('demo-lightdom-css', lightdomCss);
 
   eleventyConfig.addFilter('getTitleFromDocs', function(docs) {
-    return docs.find(x => x.docsPage?.title)?.docsPage?.title ??
+    return docs.find(x => x.docsPage?.title)?.alias ??
+      docs[0]?.alias ??
       docs[0]?.docsPage?.title ??
       eleventyConfig.getFilter('deslugify')(docs[0]?.slug);
   });
@@ -221,7 +222,7 @@ module.exports = function(eleventyConfig, { tagsToAlphabetize }) {
           pageSlug === 'overview' ? `/elements/${slug}/index.html`
         : `/elements/${slug}/${pageSlug}/index.html`;
       const href = permalink.replace('index.html', '');
-      const screenshotPath = `/elements/${slug}/screenshot.svg`;
+      const screenshotPath = `/elements/${slug}/screenshot.png`;
       /** urls for related links */
       return {
         tagName,

docs/_plugins/shortcodes/example.cjs

@@ -57,14 +57,15 @@ module.exports = function(eleventyConfig) {
      * An example image or component
      *
      * @param {object}    options
-     * @param {string}    [options.alt]             Image alt text
-     * @param {string}    [options.src]             Image url
-     * @param {number}    [options.width]           width of the img
-     * @param {string}    [options.style]           styles for the wrapper
-     * @param {string}    [options.wrapperClass]    class names for container element
-     * @param {string}    [options.headline]        Text to go in the heading
-     * @param {string}    [options.palette='light'] Palette to apply, or none for an unpadded image without background or border, e.g. lightest, light see components/_section.scss
-     * @param {2|3|4|5|6} [options.headingLevel=3]          The heading level
+     * @param {string}    [options.alt]               Image alt text
+     * @param {string}    [options.src]               Image url
+     * @param {number}    [options.width]             width of the img
+     * @param {string}    [options.style]             styles for the wrapper
+     * @param {string}    [options.wrapperClass]      class names for container element
+     * @param {string}    [options.headline]          Text to go in the heading
+     * @param {string}    [options.palette='light']   Palette to apply, e.g. lightest, light see components/_section.scss
+     * @param {2|3|4|5|6} [options.headingLevel=3]    The heading level
+     * @param {boolean}   [options.srcAbsolute=false] If true, doesn't include the page url in the img src
      * @this {EleventyContext}
      */
     async function example({
@@ -75,9 +76,10 @@ module.exports = function(eleventyConfig) {
       wrapperClass = '',
       palette = 'light',
       headingLevel = 3,
+      srcAbsolute = false
     } = {}) {
       const { page } = this.ctx || {};
-      const srcHref = path.join('_site', page?.url, src);
+      const srcHref = path.join('_site', !srcAbsolute ? page?.url : '', src);
       const slugify = eleventyConfig.getFilter('slugify');
       const imgDir = srcHref.replace(/\/[^/]+$/, '/');
       const urlPath = imgDir.replace(/^_site/, '');

docs/elements/index.md

@@ -2,12 +2,13 @@
 layout: layout-basic.njk
 title: Elements
 summaries:
-  audio-player: Plays and controls audio clips in a web browser
-  card: Organizes content or media in various container sizes
-  jump-links: Moves a user to specific content when a link is selected
+  audio-player: Plays audio clips and includes other features
+  jump-links: Moves users to specific content when a link is selected
   navigation-primary: Organizes content representing global web properties
-  popover: Displays a small overlay of content when triggered
-  progress-steps: Guides a user through a task with sequential steps
+  popover: Overlays an area of information without blocking users
+  progress-steps: Guides users through a task with sequential steps
+  breadcrumb: Keeps track of location as users move through pages
+  footnote: Provides additional information or a source for content
 ---
 
 {# NOTE: all images in this view need to be 340 by 200 px in order to maintain same ratio. #}
@@ -25,36 +26,39 @@ summaries:
 {%- for tagName, docs in collections.elementDocs | groupby('tagName') -%}
   {%- set doc = docs[0] -%}
   {%- set slug = doc.slug -%}
-  {%- set linkTitle = doc.alias or (slug | deslugify) -%}
+  {%- set title = docs | getTitleFromDocs -%}
+  {%- set comingSoon = tagName in comingSoonItems  -%}
+  {% if comingSoon %}
+    {%- set title = [title, "(coming soon)"] | join(" ") -%}
+  {% endif %}
   {%- set summary = doc.docsPage.summary -%}
   {% if not summary %}
     {%- set summary = summaries[slug] -%}
   {% endif %}
 
   {%- set wrapperClass = '' -%}
-  {% if linkTitle in ['Dialog'] %}
+  {% if title in ['Dialog'] %}
     {%- set wrapperClass = 'gray-bg' -%}
   {% endif %}
 
   <div class="padding-stacked">
-    <a href="{{ doc.href | url }}">
+    {% if not comingSoon %}<a href="{{ doc.href | url }}">{% endif %}
       {% example palette="descriptive",
                  width=340,
                  alt=linkTitle,
                  wrapperClass=wrapperClass,
+                 srcAbsolute=true,
                  src=doc.screenshotPath %}
-    </a>
-
-    <h3>{{ docs | getTitleFromDocs }}</h3>
+    {% if not comingSoon %}</a>{% endif %}
+    <h3>{{ title }}</h3>
     <p>{{ summary }}</p>
   </div>
 {% endfor %}
 </div>
 
 {% section %}
   ## Make a request
-  To request a new element or if updates need to be made to an existing element, 
-  [contact us](mailto:digital-design-system@redhat.com).
+  To request a new element or if updates need to be made to an existing element, <a href="https://github.com/RedHat-UX/red-hat-design-system/issues/new/choose" target="_blank">create a GitHub issue</a>.
 {% endsection %}
 
 {% include 'feedback.html' %}

docs/scss/components/_example.scss

@@ -207,6 +207,7 @@ rh-alert + .example {
 .example--palette-descriptive {
   &.gray-bg {
     background-color: rgb(var(--rh-color-gray-90-rgb, 21 21 21) / var(--rh-opacity-60, 60%));
+    border: none;
   }
 }
 

elements/rh-accordion/rh-accordion.ts

@@ -18,7 +18,7 @@ import './rh-accordion-panel.js';
 /**
  * An accordion is a stacked list of panels which allows users to expand or collapse information when selected. They feature panels that consist of a section text label and a caret icon that collapses or expands to reveal more information.
  *
- * @summary Stacked list of panels which allows users to expand or collapse information when selected.
+ * @summary Expands or collapses a stacked list of panels
  *
  * @fires {AccordionExpandEvent} expand - when a panel expands
  * @fires {AccordionCollapseEvent} collapse - when a panel collapses

elements/rh-badge/rh-badge.ts

@@ -14,7 +14,7 @@ import styles from './rh-badge.css';
  * - **important**: Indicates an error
  * - **critical**: Indicates danger or something critical
  *
- * @summary Annotates other information like a label or an object name.
+ * @summary Annotates information like a label or object
  *
  * @cssprop --rh-border-radius-pill
  * @cssprop --rh-color-accent-base-on-light

elements/rh-blockquote/rh-blockquote.ts

@@ -11,7 +11,7 @@ import styles from './rh-blockquote.css';
 /**
  * A blockquote for displaying quote, author, and author title.
  *
- * @summary  Styles a customer quote and includes attribution
+ * @summary  Highlights quotations and citations with text styles
  *
  * @slot         - Provide a quote for the blockquote
  * @slot author  - Provide an author for the blockquote

elements/rh-button/rh-button.ts

@@ -13,6 +13,7 @@ import styles from './rh-button.css';
  * A button is clickable text or an icon that triggers an action on the page or in the background. Depending on the action, content, and hierarchy, a button can be used on its own or grouped with other buttons.
  *
  * @summary Triggers actions on the page or in the background
+ * @summary Triggers actions on the page or in the background
  * @csspart icon - Container for the icon slot
  * @slot icon - Contains the button's icon or state indicator, e.g. a spinner.
  * @slot - Contains button text

elements/rh-card/rh-card.ts

@@ -9,7 +9,7 @@ import { colorContextProvider, type ColorPalette } from '../../lib/context/color
 import styles from './rh-card.css';
 /**
  * Cards are flexible surfaces used to group information in a small layout. They give small previews of information or provide secondary content in relation to the content it's near. Several cards can be used together to group related information.
- * @summary Organizes content or media in various container sizes
+ * @summary     Arranges content and interactive elements in a layout
  * @slot        header
  *              If this slot is used, we expect a heading level tag (h1, h2, h3, h4, h5, h6).
  *              An icon, svg, or use of the icon component are also valid in this region.

elements/rh-cta/rh-cta.ts

@@ -39,7 +39,7 @@ function isButton(element: Element): element is HTMLButtonElement {
 /**
  * Call to action stands out from regular hypertext links, and is used for linking users to webpages.
  *
- * @summary Directs a user to other pages or displays extra content
+ * @summary Directs users to other pages or displays extra content
  *
  * @slot - We expect an anchor tag, `<a>` with an `href`, to be the first child inside `rh-cta` element. Less preferred but allowed for specific use-cases include: `<button>` (note however that the `button` tag is not supported for the default CTA styles).
  *

elements/rh-dialog/rh-dialog.ts

@@ -26,7 +26,7 @@ function openChanged(this: RhDialog, oldValue: unknown) {
 
 /**
  * A dialog displays important information to users without requiring them to navigate away from the page.
- * @summary Displays important information to users without requiring them to navigate away from the page
+ * @summary Communicates information requiring user input or action
  *
  * @cssprop {<color>} --rh-dialog-close-button-color
  *           Sets the dialog close button color.

elements/rh-navigation-secondary/rh-navigation-secondary.ts

@@ -37,7 +37,7 @@ import { state } from 'lit/decorators/state.js';
 /**
  * The Secondary navigation is used to connect a series of pages together. It displays wayfinding content and links relevant to the page it is placed on. It should be used in conjunction with the [primary navigation](../navigation-primary).
  *
- * @summary  Connects a series of pages across web properties
+ * @summary  Guides users through a task with sequential steps
  *
  * @slot logo           - Logo added to the main nav bar, expects `<a>Text</a> | <a><svg/></a> | <a><img/></a>` element
  * @slot nav            - Navigation list added to the main nav bar, expects `<ul>` element

elements/rh-pagination/rh-pagination.ts

@@ -25,7 +25,7 @@ const L2 = html`
 /**
  * A paginator allows users to navigate between pages of related content.
  *
- * @summary Allows users to navigate between pages of related content.
+ * @summary Allows users to navigate content divided into pages
  *
  * @slot            - An ordered list of links
  * @slot go-to-page - "Go to page" text

elements/rh-spinner/rh-spinner.ts

@@ -21,6 +21,8 @@ export type SpinnerSize = (
  * It appears as an animated circle over the section that is loading,
  * and it may include a text label
  *
+ * @summary Notifies users their action is being processed or loaded
+ *
  * @slot - Optional text label below the animated circle.
  *
  * @cssprop --rh-color-accent-base-on-dark

elements/rh-stat/rh-stat.ts

@@ -17,6 +17,8 @@ import { ifDefined } from 'lit/directives/if-defined.js';
  *
  * @summary Displays a statistic with an optional icon, title, statistic, and call to action.
  *
+ * @summary Showcases a data point or quick fact visually
+ *
  * @slot icon - Optional icon
  * @slot title - Statistic title
  * @slot statistic - Statistic data

elements/rh-subnav/rh-subnav.ts

@@ -17,6 +17,9 @@ import styles from './rh-subnav.css';
 
 /**
  * Subnav provides a tabs-like navigation experience
+ *
+ * @summary Organizes content into sections using tabbed pages
+ *
  * @slot - Place navigation links here, expects collection of `<a>`
  *
  * @csspart container - container, <div> element

elements/rh-tabs/rh-tabs.ts

@@ -19,7 +19,7 @@ export { RhTab };
 
 /**
  * Tabs
- * @summary Arranges content in a contained view on the same page
+ * @summary Organizes content into sections in a contained view
  */
 @customElement('rh-tabs')
 export class RhTabs extends BaseTabs {

elements/rh-tag/rh-tag.ts

@@ -25,7 +25,7 @@ export type TagColor = (
 /**
  * A tag is a caption added to an element for better clarity and user convenience.
  *
- * @summary  Displays a tag with a label and optional icon for additional context.
+ * @summary  Highlights an element to add clarity or draw attention
  * @cssprop  {<length>} --rh-tag-margin-inline-end
  *           The margin at the end of the direction parallel to the flow of the text.
  *           {@default 4px}