@pega/cosmos-react-work 9.10.1 → 9.12.0

package/lib/components/Stages/Stages.styles.js

@@ -1,4 +1,5 @@
 import styled, { css } from 'styled-components';
+import { transparentize } from 'polished';
 import { calculateFontSize, DateTimeDisplay, defaultThemeProp, Icon, Text, StyledIcon, calculateForegroundColor } from '@pega/cosmos-react-core';
 const stageClipPath = (leftNotch, rightPoint, mirrored = false) => {
     if (mirrored) {
@@ -32,14 +33,25 @@ const stageClipPath = (leftNotch, rightPoint, mirrored = false) => {
 // === Chevron Configuration ===
 // Centralizes spacing and border thickness via CSS custom properties set at StyledStages
 const chevronConfig = {
-    width: 'calc(1.156 * var(--chevron-spacing))',
-    coarseWidth: 'calc(1.4375 * var(--chevron-spacing))',
-    squareSize: 'calc(3 * var(--chevron-spacing))',
-    coarseSquareSize: 'calc(3.5 * var(--chevron-spacing))',
-    offsetLeft: 'calc(0.688 * var(--chevron-spacing))',
-    offsetRight: 'calc(1.156 * var(--chevron-spacing))',
-    coarseOffsetLeft: 'calc(0.688 * var(--chevron-spacing))',
-    coarseOffsetRight: 'calc(1.5 * var(--chevron-spacing))'
+    // Horizontal projection of the rotated border-square forming the chevron point (fine pointer).
+    // Derived from the border-square size × cos(45° + skew). Tuned to visually align with the stage height.
+    // All values scaled by 1.25× relative to the original 4× spacing design (now 5× spacing height).
+    width: 'calc(1.445 * var(--chevron-spacing))',
+    // Same horizontal projection for coarse/touch pointer (larger square, proportionally wider point).
+    coarseWidth: 'calc(1.797 * var(--chevron-spacing))',
+    // Side length of the rotated border-square forming the chevron (fine pointer: 3.75× base spacing).
+    squareSize: 'calc(3.75 * var(--chevron-spacing))',
+    // Side length of the rotated border-square for coarse/touch pointer (5× base spacing).
+    coarseSquareSize: 'calc(5 * var(--chevron-spacing))',
+    // Distance to inset the ::before notch from the left edge of the stage (fine pointer).
+    // 0.86 ≈ width − half-border-overlap, keeps the notch flush with the preceding chevron point.
+    offsetLeft: 'calc(0.86 * var(--chevron-spacing))',
+    // Distance to inset the ::after point from the right edge of the stage (fine pointer).
+    // Equal to `width` so the point extends exactly one chevron-width beyond the stage boundary.
+    offsetRight: 'calc(1.445 * var(--chevron-spacing))',
+    // Coarse-pointer equivalents of offsetLeft/offsetRight, scaled to match coarseWidth/coarseSquareSize.
+    coarseOffsetLeft: 'calc(1.2875 * var(--chevron-spacing))',
+    coarseOffsetRight: 'calc(1.797 * var(--chevron-spacing))'
 };
 // === Chevron Helpers ===
 // After team discussion we decided to use logical properties throughout — `inset-block-start`
@@ -62,17 +74,17 @@ const createChevronPseudo = (borderWidth, borderColor, size) => `
   pointer-events: none;
 `;
 const createChevronBaseStyles = (config, borderThicknessVar) => css `
-  &:not(:first-of-type)::before,
-  &:not(:last-of-type)::after {
+  &:not(:nth-of-type(-n + 2))::before,
+  &:not(:nth-last-of-type(-n + 2))::after {
     border-inline-end-width: calc(1.5 * ${borderThicknessVar});
     border-block-start-width: calc(1.5 * ${borderThicknessVar});
   }
 
-  &:not(:first-of-type)::before {
+  &:not(:nth-of-type(-n + 2))::before {
     inset-inline-start: calc(-1 * ${config.width} - ${config.offsetLeft});
   }
 
-  &:not(:last-of-type)::after {
+  &:not(:nth-last-of-type(-n + 2))::after {
     inset-inline-end: calc(-1 * ${config.width} + ${config.offsetRight});
   }
 `;
@@ -93,30 +105,224 @@ const createChevronInteractiveStates = (config, borderThicknessVar, includeHover
     border-block-start-width: calc(2 * ${borderThicknessVar});
   }
 `;
+/**
+ * Outer wrapper `<div>` for the stages bar. Applies layered scroll-fade masks and
+ * reserves scrollbar space so the fade gradient does not overlap the scrollbar track.
+ */
+export const StyledStagesWrapper = styled.div(({ theme }) => {
+    return css `
+    --stages-fade-width: calc(${theme.base.spacing} * 2);
+    --stages-fade-start: 0;
+    --stages-fade-end: 0;
+    --stages-scrollbar-reserve: calc(${theme.base.spacing} * 0.25);
+
+    /* Places gradient stops one physical pixel outside the element boundary,
+     * preventing browser anti-aliasing from creating a semi-transparent seam
+     * at mask edges. 1px is the correct unit here: it must be exactly one CSS pixel
+     * (independent of font-size), so the mask boundary doesn't introduce a seam at the
+     * element edge due to anti-aliasing.
+     * See also StyledSentinel, which uses 1px for the same reason.
+     */
+    /* stylelint-disable-next-line unit-allowed-list -- 1px is intentional; see comment above */
+    --mask-edge-overhang: 1px;
+    position: relative;
+    width: 100%;
+    overflow: hidden;
+    border-radius: ${theme.components.card['border-radius']};
+    border-end-start-radius: var(
+      --stages-wrapper-bottom-radius,
+      ${theme.components.card['border-radius']}
+    );
+    border-end-end-radius: var(
+      --stages-wrapper-bottom-radius,
+      ${theme.components.card['border-radius']}
+    );
+    -webkit-mask-image: linear-gradient(black, black),
+      linear-gradient(
+        to right,
+        transparent calc(-1 * var(--mask-edge-overhang)),
+        black var(--stages-fade-start),
+        black calc(100% - var(--stages-fade-end)),
+        transparent calc(100% + var(--mask-edge-overhang))
+      );
+    mask-image: linear-gradient(black, black),
+      linear-gradient(
+        to right,
+        transparent calc(-1 * var(--mask-edge-overhang)),
+        black var(--stages-fade-start),
+        black calc(100% - var(--stages-fade-end)),
+        transparent calc(100% + var(--mask-edge-overhang))
+      );
+    mask-size:
+      100% var(--stages-scrollbar-reserve),
+      100% calc(100% - var(--stages-scrollbar-reserve));
+    mask-position:
+      0 100%,
+      0 0;
+    mask-repeat: no-repeat, no-repeat;
+
+    [dir='rtl'] & {
+      -webkit-mask-image: linear-gradient(black, black),
+        linear-gradient(
+          to right,
+          transparent calc(-1 * var(--mask-edge-overhang)),
+          black var(--stages-fade-end),
+          black calc(100% - var(--stages-fade-start)),
+          transparent calc(100% + var(--mask-edge-overhang))
+        );
+      mask-image: linear-gradient(black, black),
+        linear-gradient(
+          to right,
+          transparent calc(-1 * var(--mask-edge-overhang)),
+          black var(--stages-fade-end),
+          black calc(100% - var(--stages-fade-start)),
+          transparent calc(100% + var(--mask-edge-overhang))
+        );
+    }
+
+    &:has(:focus-visible) {
+      box-shadow: ${theme.base.shadow['focus-group']};
+    }
+
+    @media (pointer: coarse) {
+      --stages-fade-width: calc(${theme.base.spacing} * 3);
+      -webkit-mask-image: linear-gradient(
+        to right,
+        transparent calc(-1 * var(--mask-edge-overhang)),
+        black var(--stages-fade-start),
+        black calc(100% - var(--stages-fade-end)),
+        transparent calc(100% + var(--mask-edge-overhang))
+      );
+      mask-image: linear-gradient(
+        to right,
+        transparent calc(-1 * var(--mask-edge-overhang)),
+        black var(--stages-fade-start),
+        black calc(100% - var(--stages-fade-end)),
+        transparent calc(100% + var(--mask-edge-overhang))
+      );
+      mask-size: 100% 100%;
+      mask-position: 0 0;
+      mask-repeat: no-repeat;
+
+      [dir='rtl'] & {
+        -webkit-mask-image: linear-gradient(
+          to right,
+          transparent calc(-1 * var(--mask-edge-overhang)),
+          black var(--stages-fade-end),
+          black calc(100% - var(--stages-fade-start)),
+          transparent calc(100% + var(--mask-edge-overhang))
+        );
+        mask-image: linear-gradient(
+          to right,
+          transparent calc(-1 * var(--mask-edge-overhang)),
+          black var(--stages-fade-end),
+          black calc(100% - var(--stages-fade-start)),
+          transparent calc(100% + var(--mask-edge-overhang))
+        );
+      }
+    }
+  `;
+});
+StyledStagesWrapper.defaultProps = defaultThemeProp;
+/**
+ * Scrollable `<ol>` containing all stage chevron items. Sets the `--chevron-spacing`
+ * and `--chevron-border-thickness` custom properties consumed by child elements.
+ */
 export const StyledStages = styled.ol(({ theme }) => {
     return css `
     --chevron-spacing: ${theme.base.spacing};
     --chevron-border-thickness: ${theme.components.button['border-width']};
-    background-color: ${theme.base.palette['primary-background']};
+    background: ${theme.components.card.background};
     border-radius: ${theme.components.card['border-radius']};
     display: flex;
     padding: 0;
     width: 100%;
-    overflow: hidden;
+    overflow-x: auto;
+    overflow-y: hidden;
     list-style: none;
+    scrollbar-width: thin;
+    scrollbar-color: transparent transparent;
+
+    &:hover,
+    &:focus-within {
+      scrollbar-color: var(
+          --stages-scrollbar-thumb,
+          ${transparentize(0.4, theme.base.palette['border-line'])}
+        )
+        var(--stages-scrollbar-track, transparent);
+    }
 
-    &:has(:focus-visible) {
-      box-shadow: ${theme.base.shadow['focus-group']};
+    &::-webkit-scrollbar {
+      height: 0.25rem;
+    }
+
+    @media (pointer: coarse) {
+      scrollbar-width: none;
+
+      &::-webkit-scrollbar {
+        display: none;
+      }
     }
   `;
 });
 StyledStages.defaultProps = defaultThemeProp;
-export const StyledInnerStage = styled.span(props => {
+/**
+ * A sentinel is an invisible 1 px <li> placed at each end of the scrollable stage list.
+ * It is observed by an IntersectionObserver; when it scrolls out of view, the component sets
+ * --stages-fade-start or --stages-fade-end to show a gradient fade indicating more stages
+ * are reachable by scrolling. When it comes back into view the property is reset to 0.
+ *
+ * Sentinel elements carry aria-hidden="true" so they are valid list items semantically.
+ * Because styled-components scopes all CSS to a generated class, the chevron and layout rules
+ * in StyledStageContainer never apply to these elements — they carry a different class.
+ * CSS type-based selectors (:nth-of-type, :nth-last-of-type) in StyledStageContainer are
+ * offset by 1 at each end to skip the sentinels and target only real stage items.
+ */
+export const StyledSentinel = styled.li `
+  flex-shrink: 0;
+
+  /* NOTE: the sentinel must occupy
+   * a single physical pixel so IntersectionObserver can detect it at threshold 0 while having
+   * negligible layout impact. A rem value could collapse to zero at small font sizes.
+   */
+  /* stylelint-disable-next-line unit-allowed-list -- 1px is intentional */
+  width: 1px;
+  /* stylelint-disable-next-line unit-allowed-list -- 1px is intentional */
+  height: 1px;
+  padding: 0;
+  margin: 0;
+  pointer-events: none;
+
+  /* Collapse the sentinel's layout footprint to zero on the side facing the stages.
+   * Without this, each 1px sentinel creates a visible gap between the stage buttons
+   * and the left/right edges of the wrapper. The sentinel remains in flow (required
+   * for IntersectionObserver scroll detection) but no longer displaces stage content.
+   */
+  &:first-of-type {
+    /* stylelint-disable-next-line unit-allowed-list -- 1px matches sentinel width */
+    margin-inline-end: -1px;
+  }
+
+  &:last-of-type {
+    /* stylelint-disable-next-line unit-allowed-list -- 1px matches sentinel width */
+    margin-inline-start: -1px;
+  }
+`;
+StyledSentinel.defaultProps = defaultThemeProp;
+/**
+ * Inner `<span>` holding stage label content. Optionally applies `text-overflow: ellipsis`
+ * for stages with long labels.
+ */
+export const StyledInnerStage = styled.span(({ theme, ellipsis }) => {
     return css `
-    display: inline-block;
+    display: inline-flex;
+    align-items: center;
+    gap: calc(0.25 * ${theme.base.spacing});
     text-align: center;
     white-space: nowrap;
-    ${props.ellipsis &&
+    padding-inline-start: calc(0.875 * ${theme.base.spacing});
+    padding-inline-end: calc(1.125 * ${theme.base.spacing});
+    ${ellipsis &&
         css `
       overflow: hidden;
       text-overflow: ellipsis;
@@ -124,6 +330,10 @@ export const StyledInnerStage = styled.span(props => {
   `;
 });
 StyledInnerStage.defaultProps = defaultThemeProp;
+/**
+ * Clickable `<button>` for a single stage. Renders the chevron clip-path shape and
+ * applies status-based background and foreground colours.
+ */
 export const StyledStage = styled.button(({ theme: { base: { palette, 'hit-area': hitArea, transparency, 'font-weight': fontWeight }, components: { 'case-view': { stages } } }, status, readOnly }) => {
     const stageForeground = calculateForegroundColor(stages.status[status].background, stages.status[status]['foreground-color']);
     return css `
@@ -138,7 +348,7 @@ export const StyledStage = styled.button(({ theme: { base: { palette, 'hit-area'
       /* Browsers do not reliably apply flex align-items: stretch to <button> elements.
        * Adding 0.0625rem (1px at default font size) to min-height compensates so the button fills its <li> container,
        * keeping the clipped chevron background flush with the top and bottom borders. */
-      min-height: calc(4 * var(--chevron-spacing) + 0.0625rem);
+      min-height: calc(5 * var(--chevron-spacing) + 0.0625rem);
       padding-inline-start: calc(2 * var(--chevron-spacing));
       padding-inline-end: var(--chevron-spacing);
       margin-inline-start: 0;
@@ -146,12 +356,12 @@ export const StyledStage = styled.button(({ theme: { base: { palette, 'hit-area'
       width: calc(100% + ${chevronConfig.width});
       --stage-chevron-width: ${chevronConfig.width};
 
-      ${StyledIcon}, ${StyledInnerStage} {
+      ${StyledInnerStage} {
         transform: translateX(calc(-0.25 * var(--chevron-spacing)));
+        opacity: ${transparency['transparent-2']};
       }
       ${stageClipPath(true, true)}
 
-      [dir='rtl'] & ${StyledIcon},
       [dir='rtl'] & ${StyledInnerStage} {
         transform: translateX(calc(0.25 * var(--chevron-spacing)));
       }
@@ -201,19 +411,12 @@ export const StyledStage = styled.button(({ theme: { base: { palette, 'hit-area'
         width: calc(100% + ${chevronConfig.coarseWidth});
         --stage-chevron-width: ${chevronConfig.coarseWidth};
       }
-
-      ${StyledIcon} {
-        & ~ ${StyledInnerStage} {
-          margin-inline-start: 0.25rem;
-        }
-      }
-
-      ${StyledInnerStage} {
-        opacity: ${transparency['transparent-2']};
-      }
     `;
 });
 StyledStage.defaultProps = defaultThemeProp;
+/**
+ * Checkmark icon shown inside completed stages, tinted to match the stage foreground colour.
+ */
 export const StyledStageCompleteIcon = styled(Icon)(({ theme: { components: { 'case-view': { stages: { status: { completed: { 'foreground-color': foregroundColor, background } } } } } } }) => {
     const stageForeground = calculateForegroundColor(background, foregroundColor);
     return css `
@@ -221,17 +424,24 @@ export const StyledStageCompleteIcon = styled(Icon)(({ theme: { components: { 'c
   `;
 });
 StyledStageCompleteIcon.defaultProps = defaultThemeProp;
+/**
+ * Stage label text. Renders in bold weight when the stage is the current active stage.
+ */
 export const StyledStageText = styled(Text)(({ theme, isCurrent }) => css `
     font-weight: ${isCurrent ? theme.base['font-weight'].bold : theme.base['font-weight'].normal};
   `);
 StyledStageText.defaultProps = defaultThemeProp;
+/**
+ * `<li>` container for a single stage item. Manages negative-margin chevron overlap,
+ * pseudo-element positioning, and z-index stacking for interactive states.
+ */
 export const StyledStageContainer = styled.li(({ theme: { base: { palette }, components: { card: { 'border-radius': borderRadius } } }, readOnly }) => {
     return css `
       display: flex;
       position: relative;
       margin-inline-start: calc(-1 * ${chevronConfig.width});
 
-      &:first-of-type {
+      &:nth-of-type(2) {
         margin-inline-start: 0;
       }
 
@@ -239,8 +449,9 @@ export const StyledStageContainer = styled.li(({ theme: { base: { palette }, com
        * All non-last <li>s have z-index:1 so the later (right) <li>'s ::before paints on top
        * at internal boundaries; the last <li> has no z-index so its left neighbor's ::after
        * wins at the final boundary. On hover/focus/active, the interacting <li> gains z:2/3
-       * and its own pseudo-element surfaces for that boundary, regardless of which side. */
-      &:not(:last-of-type) {
+       * and its own pseudo-element surfaces for that boundary, regardless of which side.
+       */
+      &:not(:nth-last-of-type(-n + 2)) {
         z-index: 1;
       }
 
@@ -260,7 +471,7 @@ export const StyledStageContainer = styled.li(({ theme: { base: { palette }, com
         margin-inline-start: calc(-1 * ${chevronConfig.coarseWidth});
       }
 
-      &:not(:first-of-type)::before {
+      &:not(:nth-of-type(-n + 2))::before {
         ${createChevronPseudo('calc(2 * var(--chevron-border-thickness))', palette['border-line'], chevronConfig.squareSize)}
         /* Elevate ::before above the button so it renders via the same pathway as ::after.
          * Without z-index, ::before (first in DOM) is painted first and then covered by the
@@ -268,16 +479,18 @@ export const StyledStageContainer = styled.li(({ theme: { base: { palette }, com
          * causes thicker interactive-state borders (3×) to look thinner on the left boundary
          * than on the right (::after, which paints last and is always fully visible).
          * The ::before tip's rightmost extent is at --stage-chevron-width from the <li> start,
-         * which is before the stage text (padding-inline-start: 2 × spacing), so no content overlap. */
+         * which is before the stage text (padding-inline-start: 2 × spacing), so no content overlap.
+         */
         z-index: 1;
       }
 
-      &:not(:last-of-type)::after {
+      &:not(:nth-last-of-type(-n + 2))::after {
         ${createChevronPseudo('calc(2 * var(--chevron-border-thickness))', palette['border-line'], chevronConfig.squareSize)}
       }
 
       /* Chevron positioning: 45° rotated squares create visual tips via offsets:
-       * left ≈ 0.688 × spacing, right ≈ 1.15 × spacing (accounts for skew correction) */
+       * left ≈ 0.86 × spacing, right ≈ 1.445 × spacing (accounts for skew correction)
+       */
 
       [dir='rtl'] &::before,
       [dir='rtl'] &::after {
@@ -285,19 +498,18 @@ export const StyledStageContainer = styled.li(({ theme: { base: { palette }, com
       }
 
       /* Thicken chevrons to visually match button top/bottom border on any colored state.
-       * At 45° rotation, border appears 1/sin(45°) ≈ 0.707× thinner, so 2× border ≈ 1.4× horizontal border weight. */
+       *  At 45° rotation, border appears 1/sin(45°) ≈ 0.707× thinner, so 2× border ≈ 1.4× horizontal border weight.
+       */
       ${createChevronBaseStyles(chevronConfig, 'var(--chevron-border-thickness)')}
       ${createChevronInteractiveStates(chevronConfig, 'var(--chevron-border-thickness)', !readOnly)}
-
-      ${!readOnly &&
+        ${!readOnly &&
         css `
         &:has(button:hover)::before,
         &:has(button:hover)::after {
           border-color: ${palette['border-line']};
         }
       `}
-
-      &:has(button:focus-visible)::before,
+        &:has(button:focus-visible)::before,
       &:has(button:focus-visible)::after {
         border-color: ${palette.interactive};
       }
@@ -308,27 +520,27 @@ export const StyledStageContainer = styled.li(({ theme: { base: { palette }, com
       }
 
       @media (pointer: coarse) {
-        &:not(:first-of-type)::before,
-        &:not(:last-of-type)::after {
+        &:not(:nth-of-type(-n + 2))::before,
+        &:not(:nth-last-of-type(-n + 2))::after {
           inset-block-start: calc(50% - ${chevronConfig.coarseSquareSize} / 2);
           width: ${chevronConfig.coarseSquareSize};
           height: ${chevronConfig.coarseSquareSize};
         }
 
-        &:not(:first-of-type)::before {
+        &:not(:nth-of-type(-n + 2))::before {
           inset-inline-start: calc(
             -1 * ${chevronConfig.coarseWidth} - ${chevronConfig.coarseOffsetLeft}
           );
         }
 
-        &:not(:last-of-type)::after {
+        &:not(:nth-last-of-type(-n + 2))::after {
           inset-inline-end: calc(
             -1 * ${chevronConfig.coarseWidth} + ${chevronConfig.coarseOffsetRight}
           );
         }
       }
 
-      &:first-of-type > ${StyledStage} {
+      &:nth-of-type(2):not(:nth-last-of-type(2)) > ${StyledStage} {
         --stage-chevron-width: ${chevronConfig.width};
         border-start-start-radius: ${borderRadius};
         border-end-start-radius: ${borderRadius};
@@ -365,30 +577,77 @@ export const StyledStageContainer = styled.li(({ theme: { base: { palette }, com
         }
       }
 
-      &:last-of-type > ${StyledStage} {
+      &:nth-last-of-type(2):not(:nth-of-type(2)) > ${StyledStage} {
         --stage-chevron-width: ${chevronConfig.width};
         border-start-end-radius: ${borderRadius};
         border-end-end-radius: ${borderRadius};
-        border-inline-end-width: calc(2 * var(--chevron-border-thickness));
         padding-inline-end: 0;
         width: 100%;
         ${stageClipPath(true, false)}
 
+        ${!readOnly &&
+        css `
+          /* Inline-end interactive indicator via inset shadow — avoids border-color bleeding through gradient backgrounds */
+          &:hover {
+            box-shadow: inset calc(-2 * var(--chevron-border-thickness)) 0 0
+              ${palette['border-line']};
+
+            [dir='rtl'] & {
+              box-shadow: inset calc(2 * var(--chevron-border-thickness)) 0 0
+                ${palette['border-line']};
+            }
+          }
+        `}
+
+        &:focus-visible,
+        &:active {
+          box-shadow: inset calc(-2 * var(--chevron-border-thickness)) 0 0 ${palette.interactive};
+
+          [dir='rtl'] & {
+            box-shadow: inset calc(2 * var(--chevron-border-thickness)) 0 0 ${palette.interactive};
+          }
+        }
+
         @media (pointer: coarse) {
           --stage-chevron-width: ${chevronConfig.coarseWidth};
         }
       }
 
-      [dir='rtl'] &:first-of-type > ${StyledStage} {
+      [dir='rtl'] &:nth-of-type(2):not(:nth-last-of-type(2)) > ${StyledStage} {
         ${stageClipPath(true, false, true)}
       }
 
-      [dir='rtl'] &:last-of-type > ${StyledStage} {
+      [dir='rtl'] &:nth-last-of-type(2):not(:nth-of-type(2)) > ${StyledStage} {
         ${stageClipPath(false, true, true)}
       }
+
+      &:nth-of-type(2):nth-last-of-type(2) > ${StyledStage} {
+        border-radius: ${borderRadius};
+        width: 100%;
+        ${stageClipPath(false, false)}
+
+        ${!readOnly &&
+        css `
+          &:hover {
+            box-shadow:
+              inset calc(2 * var(--chevron-border-thickness)) 0 0 ${palette['border-line']},
+              inset calc(-2 * var(--chevron-border-thickness)) 0 0 ${palette['border-line']};
+          }
+        `}
+
+        &:focus-visible,
+        &:active {
+          box-shadow:
+            inset calc(2 * var(--chevron-border-thickness)) 0 0 ${palette.interactive},
+            inset calc(-2 * var(--chevron-border-thickness)) 0 0 ${palette.interactive};
+        }
+      }
     `;
 });
 StyledStageContainer.defaultProps = defaultThemeProp;
+/**
+ * `<ol>` list of sub-step items displayed below the stages bar when a stage is expanded.
+ */
 export const StyledStepsContainer = styled.ol(({ theme }) => {
     return css `
     list-style-type: none;
@@ -400,6 +659,9 @@ export const StyledStepsContainer = styled.ol(({ theme }) => {
   `;
 });
 StyledStepsContainer.defaultProps = defaultThemeProp;
+/**
+ * Individual step `<li>` within a stage. Dims text and icon at reduced opacity when completed.
+ */
 export const StyledStep = styled.li(({ completed, theme }) => {
     const textOpacity = completed ? theme.base.transparency['transparent-2'] : 1;
     return css `
@@ -421,6 +683,10 @@ export const StyledStep = styled.li(({ completed, theme }) => {
   `;
 });
 StyledStep.defaultProps = defaultThemeProp;
+/**
+ * Small datetime label rendered beneath a step. Displayed at the `xs` font size
+ * and reduced opacity.
+ */
 export const StyledDateTimeDisplay = styled(DateTimeDisplay)(({ theme }) => {
     const fontSize = calculateFontSize(theme.base['font-size'], theme.base['font-scale']);
     return css `
@@ -429,12 +695,19 @@ export const StyledDateTimeDisplay = styled(DateTimeDisplay)(({ theme }) => {
   `;
 });
 StyledDateTimeDisplay.defaultProps = defaultThemeProp;
+/**
+ * Container `<div>` for the stage glimpse preview panel, constrained to a small max-width.
+ */
 export const StyledStageGlimpse = styled.div(({ theme }) => {
     return css `
     max-width: ${theme.base['content-width'].sm};
   `;
 });
 StyledStageGlimpse.defaultProps = defaultThemeProp;
+/**
+ * Visually hidden `<p>` providing an accessible description for the stages list,
+ * announced by screen readers but not displayed on screen.
+ */
 export const StyledStagesDescription = styled.p `
   display: none;
 `;