@pega/cosmos-react-work 10.0.0-build.4.2 → 10.0.0-build.4.21

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

@@ -1,6 +1,6 @@
-import styled, { css } from 'styled-components';
-import { transparentize } from 'polished';
-import { calculateFontSize, DateTimeDisplay, defaultThemeProp, Icon, Text, StyledIcon, calculateForegroundColor } from '@pega/cosmos-react-core';
+import styled, { css, keyframes } from 'styled-components';
+import { transparentize, darken } from 'polished';
+import { calculateFontSize, DateTimeDisplay, defaultThemeProp, Icon, Text, StyledIcon, calculateForegroundColor, tryCatch } from '@pega/cosmos-react-core';
 const stageClipPath = (leftNotch, rightPoint, mirrored = false) => {
     if (mirrored) {
         // RTL: mirror the LTR clip-path polygon
@@ -30,6 +30,20 @@ const stageClipPath = (leftNotch, rightPoint, mirrored = false) => {
     }
     return `clip-path: polygon(${points.join(', ')});`;
 };
+const segmentedConfig = {
+    width: 'calc(0.8 * var(--chevron-spacing))',
+    coarseWidth: 'calc(1.0 * var(--chevron-spacing))'
+};
+const segmentedClipPath = (leftCut, rightCut, mirrored = false) => {
+    if (mirrored) {
+        const topRight = rightCut ? 'calc(100% - var(--segmented-width)) 0%' : '100% 0%';
+        const bottomLeft = leftCut ? 'var(--segmented-width) 100%' : '0% 100%';
+        return `clip-path: polygon(0% 0%, ${topRight}, 100% 100%, ${bottomLeft});`;
+    }
+    const topLeft = leftCut ? 'var(--segmented-width) 0%' : '0% 0%';
+    const bottomRight = rightCut ? 'calc(100% - var(--segmented-width)) 100%' : '100% 100%';
+    return `clip-path: polygon(${topLeft}, 100% 0%, ${bottomRight}, 0% 100%);`;
+};
 // === Chevron Configuration ===
 // Centralizes spacing and border thickness via CSS custom properties set at StyledStages
 const chevronConfig = {
@@ -50,8 +64,15 @@ const chevronConfig = {
     // 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))'
+    // coarseOffsetLeft must satisfy: coarseSquareSize = 2 × coarseWidth + coarseOffsetLeft
+    // (5 = 2 × 1.797 + 1.406) so that ::before and ::after co-locate on coarse devices.
+    coarseOffsetLeft: 'calc(1.406 * var(--chevron-spacing))',
+    coarseOffsetRight: 'calc(1.797 * var(--chevron-spacing))',
+    // Pre-computed flat positions for ::before notch and ::after point.
+    notchInsetStart: 'calc(-2.305 * var(--chevron-spacing))',
+    // 3.203 = exact alignment (coarseSquareSize - coarseWidth); slightly overdone default clears sub-pixel rounding on 3× displays.
+    coarseNotchInsetStart: 'calc(-1 * var(--stages-coarse-notch-correction) * var(--chevron-spacing))',
+    pointInsetEnd: '0'
 };
 // === Chevron Helpers ===
 // After team discussion we decided to use logical properties throughout — `inset-block-start`
@@ -81,11 +102,11 @@ const createChevronBaseStyles = (config, borderThicknessVar) => css `
   }
 
   &:not(:nth-of-type(-n + 2))::before {
-    inset-inline-start: calc(-1 * ${config.width} - ${config.offsetLeft});
+    inset-inline-start: ${config.notchInsetStart};
   }
 
   &:not(:nth-last-of-type(-n + 2))::after {
-    inset-inline-end: calc(-1 * ${config.width} + ${config.offsetRight});
+    inset-inline-end: ${config.pointInsetEnd};
   }
 `;
 const createChevronInteractiveStates = (config, borderThicknessVar, includeHover = true) => css `
@@ -137,6 +158,14 @@ export const StyledStagesWrapper = styled.div(({ theme }) => {
       --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,
@@ -154,6 +183,14 @@ export const StyledStagesWrapper = styled.div(({ theme }) => {
     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,
@@ -170,6 +207,13 @@ export const StyledStagesWrapper = styled.div(({ theme }) => {
 
     @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)),
@@ -182,6 +226,13 @@ export const StyledStagesWrapper = styled.div(({ theme }) => {
       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)),
@@ -195,13 +246,18 @@ export const StyledStagesWrapper = styled.div(({ theme }) => {
 });
 StyledStagesWrapper.defaultProps = defaultThemeProp;
 /**
- * Scrollable `<ol>` containing all stage chevron items. Sets the `--chevron-spacing`
- * and `--chevron-border-thickness` custom properties consumed by child elements.
+ * Scrollable `<ol>` containing all stage chevron items. Sets the `--chevron-spacing`,
+ * `--chevron-border-thickness`, and `--segmented-border-thickness` custom properties
+ * consumed by child elements.
  */
-export const StyledStages = styled.ol(({ theme }) => {
+export const StyledStages = styled.ol(({ theme, variant }) => {
+    const isMilestone = variant === 'milestone';
     return css `
     --chevron-spacing: ${theme.base.spacing};
     --chevron-border-thickness: ${theme.components.button['border-width']};
+    --segmented-border-thickness: calc(2 * ${theme.components.button['border-width']});
+    --segmented-width: ${segmentedConfig.width};
+    background: ${theme.components.card.background};
     border-radius: ${theme.components.card['border-radius']};
     display: flex;
     padding: 0;
@@ -212,6 +268,17 @@ export const StyledStages = styled.ol(({ theme }) => {
     scrollbar-width: thin;
     scrollbar-color: transparent transparent;
 
+    ${isMilestone &&
+        css `
+      --milestone-size: calc(4 * ${theme.base.spacing});
+      --milestone-pulse-min: calc(var(--milestone-size) * 0.1);
+      --milestone-pulse-start: ${transparentize(0.5, theme.base.palette.interactive)};
+      --milestone-pulse-spread: calc(var(--milestone-size) * 0.25);
+      --milestone-pulse-end: ${transparentize(0.75, theme.base.palette.interactive)};
+      padding-block: ${theme.base.spacing};
+      padding-inline: calc(var(--milestone-size) * 0.25);
+    `}
+
     &:hover,
     &:focus-within {
       scrollbar-color: var(
@@ -226,6 +293,8 @@ export const StyledStages = styled.ol(({ theme }) => {
     }
 
     @media (pointer: coarse) {
+      /* 3.203 = exact alignment; slightly overdone default to clear sub-pixel rounding on 3× displays */
+      --stages-coarse-notch-correction: 3.35;
       scrollbar-width: none;
 
       &::-webkit-scrollbar {
@@ -299,11 +368,58 @@ export const StyledInnerStage = styled.span(({ theme, ellipsis }) => {
   `;
 });
 StyledInnerStage.defaultProps = defaultThemeProp;
+const stageButtonChevronStyles = (theme) => css `
+  padding-inline-start: calc(2 * var(--chevron-spacing));
+  padding-inline-end: var(--chevron-spacing);
+  width: calc(100% + ${chevronConfig.width});
+  --stage-chevron-width: ${chevronConfig.width};
+
+  ${StyledInnerStage} {
+    transform: translateX(calc(-0.25 * var(--chevron-spacing)));
+    opacity: ${theme.base.transparency['transparent-2']};
+  }
+
+  ${stageClipPath(true, true)}
+
+  [dir='rtl'] & ${StyledInnerStage} {
+    transform: translateX(calc(0.25 * var(--chevron-spacing)));
+  }
+
+  [dir='rtl'] & {
+    ${stageClipPath(true, true, true)}
+  }
+
+  @media (pointer: coarse) {
+    padding-inline-start: calc(2.25 * var(--chevron-spacing));
+    width: calc(100% + ${chevronConfig.coarseWidth});
+    --stage-chevron-width: ${chevronConfig.coarseWidth};
+  }
+`;
+const stageButtonSegmentedStyles = (theme) => css `
+  width: 100%;
+  padding-inline-start: calc(var(--segmented-width) + var(--chevron-spacing));
+  padding-inline-end: calc(var(--segmented-width) + var(--chevron-spacing));
+
+  ${StyledInnerStage} {
+    opacity: ${theme.base.transparency['transparent-2']};
+  }
+
+  ${segmentedClipPath(true, true)}
+
+  [dir='rtl'] & {
+    ${segmentedClipPath(true, true, true)}
+  }
+`;
+const stageButtonVariants = {
+    chevron: stageButtonChevronStyles,
+    segmented: stageButtonSegmentedStyles,
+    milestone: () => css ``
+};
 /**
  * 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 }) => {
+export const StyledStage = styled.button(({ theme, theme: { base: { palette, 'hit-area': hitArea, transparency, 'font-weight': fontWeight }, components: { 'case-view': { stages } } }, status, readOnly, variant: shape }) => {
     const stageForeground = calculateForegroundColor(stages.status[status].background, stages.status[status]['foreground-color']);
     return css `
       background: ${stages.status[status].background};
@@ -318,26 +434,10 @@ export const StyledStage = styled.button(({ theme: { base: { palette, 'hit-area'
        * 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(5 * var(--chevron-spacing) + 0.0625rem);
-      padding-inline-start: calc(2 * var(--chevron-spacing));
-      padding-inline-end: var(--chevron-spacing);
       margin-inline-start: 0;
       margin-inline-end: 0;
-      width: calc(100% + ${chevronConfig.width});
-      --stage-chevron-width: ${chevronConfig.width};
 
-      ${StyledInnerStage} {
-        transform: translateX(calc(-0.25 * var(--chevron-spacing)));
-        opacity: ${transparency['transparent-2']};
-      }
-      ${stageClipPath(true, true)}
-
-      [dir='rtl'] & ${StyledInnerStage} {
-        transform: translateX(calc(0.25 * var(--chevron-spacing)));
-      }
-
-      [dir='rtl'] & {
-        ${stageClipPath(true, true, true)}
-      }
+      ${stageButtonVariants[shape](theme)}
 
       ${!readOnly &&
         css `
@@ -376,9 +476,6 @@ export const StyledStage = styled.button(({ theme: { base: { palette, 'hit-area'
 
       @media (pointer: coarse) {
         min-height: ${hitArea['finger-min']};
-        padding-inline-start: calc(2.25 * var(--chevron-spacing));
-        width: calc(100% + ${chevronConfig.coarseWidth});
-        --stage-chevron-width: ${chevronConfig.coarseWidth};
       }
     `;
 });
@@ -400,195 +497,439 @@ 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 }) => {
+const stageContainerChevronStyles = (theme, readOnly) => {
+    const includeHover = !readOnly;
     return css `
-      display: flex;
-      position: relative;
-      margin-inline-start: calc(-1 * ${chevronConfig.width});
+    /* Chevron: negative-margin overlap so consecutive stages share a boundary */
+    margin-inline-start: calc(-1 * ${chevronConfig.width});
 
-      &:nth-of-type(2) {
-        margin-inline-start: 0;
-      }
+    &:nth-of-type(2) {
+      margin-inline-start: 0;
+    }
 
-      /* Resting z-index: for same-z siblings, DOM order determines paint order.
-       * 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.
+    /* Chevron boundary indicators via ::before (left notch) and ::after (right point) pseudo-elements */
+    &:not(:nth-of-type(-n + 2))::before {
+      ${createChevronPseudo('calc(2 * var(--chevron-border-thickness))', theme.base.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
+       * button, making it only partially visible through the clip-path notch window. This
+       * 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.
        */
-      &:not(:nth-last-of-type(-n + 2)) {
-        z-index: 1;
-      }
+      z-index: 1;
+    }
 
-      &:has(button:focus-visible),
-      &:has(button:active) {
-        z-index: 2;
+    &:not(:nth-last-of-type(-n + 2))::after {
+      ${createChevronPseudo('calc(2 * var(--chevron-border-thickness))', theme.base.palette['border-line'], chevronConfig.squareSize)}
+    }
+
+    [dir='rtl'] &::before,
+    [dir='rtl'] &::after {
+      transform: rotateZ(-45deg) skew(-15deg, -15deg);
+    }
+
+    /* Chevron positioning: 45° rotated squares create visual tips via offsets:
+     * left ≈ 0.86 × spacing, right ≈ 1.445 × spacing (accounts for skew correction)
+     */
+    ${createChevronBaseStyles(chevronConfig, 'var(--chevron-border-thickness)')}
+    ${createChevronInteractiveStates(chevronConfig, 'var(--chevron-border-thickness)', includeHover)}
+
+    /* 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.
+     */
+    ${includeHover &&
+        css `
+      &:has(button:hover)::before,
+      &:has(button:hover)::after {
+        border-color: ${theme.base.palette['border-line']};
       }
+    `}
 
-      ${!readOnly &&
+    &:has(button:focus-visible)::before,
+    &:has(button:focus-visible)::after {
+      border-color: ${theme.base.palette.interactive};
+    }
+
+    &:has(button:active)::before,
+    &:has(button:active)::after {
+      border-color: ${theme.base.palette.interactive};
+    }
+
+    /* First stage: no left notch, extended width to cover the full left edge */
+    &:nth-of-type(2):not(:nth-last-of-type(2)) > ${StyledStage} {
+      --stage-chevron-width: ${chevronConfig.width};
+      width: calc(100% + (2 * var(--stage-chevron-width)));
+      padding-inline-start: calc(var(--chevron-spacing));
+      ${stageClipPath(false, true)}
+
+      ${includeHover &&
         css `
-        &:has(button:hover) {
-          z-index: 3;
+        /* Inline-start interactive indicator via inset shadow — avoids border-color bleeding through gradient backgrounds */
+        &:hover {
+          box-shadow: inset calc(2 * var(--chevron-border-thickness)) 0 0
+            ${theme.base.palette['border-line']};
+
+          [dir='rtl'] & {
+            box-shadow: inset calc(-2 * var(--chevron-border-thickness)) 0 0
+              ${theme.base.palette['border-line']};
+          }
         }
       `}
 
+      &:focus-visible,
+      &:active {
+        box-shadow: inset calc(2 * var(--chevron-border-thickness)) 0 0
+          ${theme.base.palette.interactive};
+
+        [dir='rtl'] & {
+          box-shadow: inset calc(-2 * var(--chevron-border-thickness)) 0 0
+            ${theme.base.palette.interactive};
+        }
+      }
+
       @media (pointer: coarse) {
-        margin-inline-start: calc(-1 * ${chevronConfig.coarseWidth});
+        --stage-chevron-width: ${chevronConfig.coarseWidth};
+        width: calc(100% + (2 * var(--stage-chevron-width)));
       }
+    }
 
-      &: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
-         * button, making it only partially visible through the clip-path notch window. This
-         * 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.
-         */
-        z-index: 1;
+    /* Last stage: no right point */
+    &:nth-last-of-type(2):not(:nth-of-type(2)) > ${StyledStage} {
+      --stage-chevron-width: ${chevronConfig.width};
+      padding-inline-end: 0;
+      width: 100%;
+      ${stageClipPath(true, false)}
+
+      ${includeHover &&
+        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
+            ${theme.base.palette['border-line']};
+
+          [dir='rtl'] & {
+            box-shadow: inset calc(2 * var(--chevron-border-thickness)) 0 0
+              ${theme.base.palette['border-line']};
+          }
+        }
+      `}
+
+      &:focus-visible,
+      &:active {
+        box-shadow: inset calc(-2 * var(--chevron-border-thickness)) 0 0
+          ${theme.base.palette.interactive};
+
+        [dir='rtl'] & {
+          box-shadow: inset calc(2 * var(--chevron-border-thickness)) 0 0
+            ${theme.base.palette.interactive};
+        }
       }
 
-      &:not(:nth-last-of-type(-n + 2))::after {
-        ${createChevronPseudo('calc(2 * var(--chevron-border-thickness))', palette['border-line'], chevronConfig.squareSize)}
+      @media (pointer: coarse) {
+        --stage-chevron-width: ${chevronConfig.coarseWidth};
       }
+    }
 
-      /* Chevron positioning: 45° rotated squares create visual tips via offsets:
-       * left ≈ 0.86 × spacing, right ≈ 1.445 × spacing (accounts for skew correction)
-       */
+    /* RTL: flip clip-paths for first and last stages */
+    [dir='rtl'] &:nth-of-type(2):not(:nth-last-of-type(2)) > ${StyledStage} {
+      ${stageClipPath(true, false, true)}
+    }
 
-      [dir='rtl'] &::before,
-      [dir='rtl'] &::after {
-        transform: rotateZ(-45deg) skew(-15deg, -15deg);
-      }
+    [dir='rtl'] &:nth-last-of-type(2):not(:nth-of-type(2)) > ${StyledStage} {
+      ${stageClipPath(false, true, true)}
+    }
 
-      /* 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.
-       */
-      ${createChevronBaseStyles(chevronConfig, 'var(--chevron-border-thickness)')}
-      ${createChevronInteractiveStates(chevronConfig, 'var(--chevron-border-thickness)', !readOnly)}
-        ${!readOnly &&
+    /* Single stage: plain rectangle — no clip-path notch, inset shadows on both sides */
+    &:nth-of-type(2):nth-last-of-type(2) > ${StyledStage} {
+      --stage-chevron-width: ${chevronConfig.width};
+      clip-path: none;
+      padding-inline-start: calc(var(--chevron-spacing));
+
+      ${includeHover &&
         css `
-        &:has(button:hover)::before,
-        &:has(button:hover)::after {
-          border-color: ${palette['border-line']};
+        &:hover {
+          box-shadow:
+            inset calc(2 * var(--chevron-border-thickness)) 0 0 ${theme.base.palette['border-line']},
+            inset calc(-2 * var(--chevron-border-thickness)) 0 0
+              ${theme.base.palette['border-line']};
         }
       `}
-        &:has(button:focus-visible)::before,
-      &:has(button:focus-visible)::after {
-        border-color: ${palette.interactive};
-      }
 
-      &:has(button:active)::before,
-      &:has(button:active)::after {
-        border-color: ${palette.interactive};
+      &:focus-visible,
+      &:active {
+        box-shadow:
+          inset calc(2 * var(--chevron-border-thickness)) 0 0 ${theme.base.palette.interactive},
+          inset calc(-2 * var(--chevron-border-thickness)) 0 0 ${theme.base.palette.interactive};
       }
 
       @media (pointer: coarse) {
-        &: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};
-        }
+        --stage-chevron-width: ${chevronConfig.coarseWidth};
+      }
+    }
 
-        &:not(:nth-of-type(-n + 2))::before {
-          inset-inline-start: calc(
-            -1 * ${chevronConfig.coarseWidth} - ${chevronConfig.coarseOffsetLeft}
-          );
-        }
+    @media (pointer: coarse) {
+      margin-inline-start: calc(-1 * ${chevronConfig.coarseWidth});
 
-        &:not(:nth-last-of-type(-n + 2))::after {
-          inset-inline-end: calc(
-            -1 * ${chevronConfig.coarseWidth} + ${chevronConfig.coarseOffsetRight}
-          );
-        }
+      &: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};
+        border-inline-end-width: calc(2 * var(--chevron-border-thickness));
+        border-block-start-width: calc(2 * var(--chevron-border-thickness));
       }
 
-      &:nth-of-type(2) > ${StyledStage} {
-        --stage-chevron-width: ${chevronConfig.width};
-        border-start-start-radius: ${borderRadius};
-        border-end-start-radius: ${borderRadius};
-        width: calc(100% + (2 * var(--stage-chevron-width)));
-        padding-inline-start: calc(var(--chevron-spacing));
-        ${stageClipPath(false, true)}
+      &:not(:nth-of-type(-n + 2))::before {
+        inset-inline-start: ${chevronConfig.coarseNotchInsetStart};
+      }
 
-        ${!readOnly &&
+      &:not(:nth-last-of-type(-n + 2))::after {
+        inset-inline-end: 0;
+      }
+    }
+  `;
+};
+const stageContainerSegmentedStyles = (theme, readOnly) => {
+    const includeHover = !readOnly;
+    return css `
+    --segmented-edge-thickness: var(--chevron-border-thickness);
+
+    /* Segmented: stages overlap by --segmented-width so parallelogram edges meet flush */
+    margin-inline-start: calc(-1 * var(--segmented-width));
+
+    &:nth-of-type(2) {
+      margin-inline-start: 0;
+    }
+
+    /* Left segmented border strip: diagonal clip-path on each stage's inline-start edge (stages 2..N).
+     * The strip goes from (segmented-width, 0%) at top to (0%, 100%) at bottom of the pseudo,
+     * matching the parallelogram's inline-start clip edge exactly.
+     */
+    &:not(:nth-of-type(-n + 2))::before {
+      content: '';
+      position: absolute;
+      inset-block: 0;
+      inset-inline-start: 0;
+      width: calc(var(--segmented-width) + var(--segmented-edge-thickness));
+      clip-path: polygon(
+        var(--segmented-width) 0%,
+        calc(var(--segmented-width) + var(--segmented-edge-thickness)) 0%,
+        var(--segmented-edge-thickness) 100%,
+        0% 100%
+      );
+      background: ${theme.base.palette['border-line']};
+      pointer-events: none;
+      z-index: 1;
+    }
+
+    /* Right segmented border strip: diagonal clip-path on each stage's inline-end edge (stages 1..N-1). */
+    &:not(:nth-last-of-type(-n + 2))::after {
+      content: '';
+      position: absolute;
+      inset-block: 0;
+      inset-inline-end: 0;
+      width: calc(var(--segmented-width) + var(--segmented-edge-thickness));
+      clip-path: polygon(
+        var(--segmented-width) 0%,
+        calc(var(--segmented-width) + var(--segmented-edge-thickness)) 0%,
+        var(--segmented-edge-thickness) 100%,
+        0% 100%
+      );
+      background: ${theme.base.palette['border-line']};
+      pointer-events: none;
+      z-index: 2;
+    }
+
+    /* Interactive states: update pseudo background to signal hover/focus/active */
+    ${includeHover &&
         css `
-          /* Inline-start 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']};
+      &:has(button:hover) {
+        --segmented-edge-thickness: var(--segmented-border-thickness);
+      }
 
-            [dir='rtl'] & {
-              box-shadow: inset calc(-2 * var(--chevron-border-thickness)) 0 0
-                ${palette['border-line']};
-            }
-          }
-        `}
+      &:has(button:hover)::before,
+      &:has(button:hover)::after {
+        background: ${theme.base.palette['border-line']};
+      }
+    `}
 
-        &:focus-visible,
-        &:active {
-          box-shadow: inset calc(2 * var(--chevron-border-thickness)) 0 0 ${palette.interactive};
+    &:has(button:focus-visible),
+    &:has(button:active) {
+      --segmented-edge-thickness: var(--segmented-border-thickness);
+    }
+
+    &:has(button:focus-visible)::before,
+    &:has(button:focus-visible)::after,
+    &:has(button:active)::before,
+    &:has(button:active)::after {
+      background: ${theme.base.palette.interactive};
+    }
+
+    /* First stage (no inline-start cut): flat left edge + inset shadow edge indicator */
+    &:nth-of-type(2):not(:nth-last-of-type(2)) > ${StyledStage} {
+      ${segmentedClipPath(false, true)}
+
+      ${includeHover &&
+        css `
+        &:hover {
+          box-shadow: inset var(--segmented-border-thickness) 0 0
+            ${theme.base.palette['border-line']};
 
           [dir='rtl'] & {
-            box-shadow: inset calc(-2 * var(--chevron-border-thickness)) 0 0 ${palette.interactive};
+            box-shadow: inset calc(-1 * var(--segmented-border-thickness)) 0 0
+              ${theme.base.palette['border-line']};
           }
         }
+      `}
+
+      &:focus-visible,
+      &:active {
+        box-shadow: inset var(--segmented-border-thickness) 0 0 ${theme.base.palette.interactive};
 
-        @media (pointer: coarse) {
-          --stage-chevron-width: ${chevronConfig.coarseWidth};
-          width: calc(100% + (2 * var(--stage-chevron-width)));
+        [dir='rtl'] & {
+          box-shadow: inset calc(-1 * var(--segmented-border-thickness)) 0 0
+            ${theme.base.palette.interactive};
         }
       }
+    }
 
-      &:nth-last-of-type(2) > ${StyledStage} {
-        --stage-chevron-width: ${chevronConfig.width};
-        border-start-end-radius: ${borderRadius};
-        border-end-end-radius: ${borderRadius};
-        padding-inline-end: 0;
-        width: 100%;
-        ${stageClipPath(true, false)}
+    /* Last stage (no inline-end cut): flat right edge + inset shadow edge indicator */
+    &:nth-last-of-type(2):not(:nth-of-type(2)) > ${StyledStage} {
+      ${segmentedClipPath(true, false)}
 
-        ${!readOnly &&
+      ${includeHover &&
         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']};
+        &:hover {
+          box-shadow: inset calc(-1 * var(--segmented-border-thickness)) 0 0
+            ${theme.base.palette['border-line']};
 
-            [dir='rtl'] & {
-              box-shadow: inset calc(2 * var(--chevron-border-thickness)) 0 0
-                ${palette['border-line']};
-            }
+          [dir='rtl'] & {
+            box-shadow: inset var(--segmented-border-thickness) 0 0
+              ${theme.base.palette['border-line']};
           }
-        `}
+        }
+      `}
 
-        &:focus-visible,
-        &:active {
-          box-shadow: inset calc(-2 * var(--chevron-border-thickness)) 0 0 ${palette.interactive};
+      &:focus-visible,
+      &:active {
+        box-shadow: inset calc(-1 * var(--segmented-border-thickness)) 0 0
+          ${theme.base.palette.interactive};
 
-          [dir='rtl'] & {
-            box-shadow: inset calc(2 * var(--chevron-border-thickness)) 0 0 ${palette.interactive};
-          }
+        [dir='rtl'] & {
+          box-shadow: inset var(--segmented-border-thickness) 0 0 ${theme.base.palette.interactive};
         }
+      }
+    }
+
+    /* RTL: flip clip-paths for first and last stage buttons */
+    [dir='rtl'] &:nth-of-type(2):not(:nth-last-of-type(2)) > ${StyledStage} {
+      ${segmentedClipPath(true, false, true)}
+    }
+
+    [dir='rtl'] &:nth-last-of-type(2):not(:nth-of-type(2)) > ${StyledStage} {
+      ${segmentedClipPath(false, true, true)}
+    }
+
+    /* Single stage: plain rectangle — no diagonal cuts, inset shadows on both sides */
+    &:nth-of-type(2):nth-last-of-type(2) > ${StyledStage} {
+      clip-path: none;
+      padding-inline-start: calc(var(--chevron-spacing));
+      padding-inline-end: calc(var(--chevron-spacing));
+
+      ${includeHover &&
+        css `
+        &:hover {
+          box-shadow:
+            inset var(--segmented-border-thickness) 0 0 ${theme.base.palette['border-line']},
+            inset calc(-1 * var(--segmented-border-thickness)) 0 0
+              ${theme.base.palette['border-line']};
+        }
+      `}
+
+      &:focus-visible,
+      &:active {
+        box-shadow:
+          inset var(--segmented-border-thickness) 0 0 ${theme.base.palette.interactive},
+          inset calc(-1 * var(--segmented-border-thickness)) 0 0 ${theme.base.palette.interactive};
+      }
+    }
+
+    /* RTL: mirror the pseudo clip-paths.
+     * In LTR the strip goes top-right → bottom-left (polygon A 0%, A+B 0%, B 100%, 0% 100%).
+     * In RTL the pseudo is positioned at the opposite physical edge via logical inset properties,
+     * so the strip must go top-left → bottom-right to stay aligned with the flipped slant.
+     */
+    [dir='rtl'] &:not(:nth-of-type(-n + 2))::before,
+    [dir='rtl'] &:not(:nth-last-of-type(-n + 2))::after {
+      clip-path: polygon(
+        0% 0%,
+        var(--segmented-edge-thickness) 0%,
+        calc(var(--segmented-width) + var(--segmented-edge-thickness)) 100%,
+        var(--segmented-width) 100%
+      );
+    }
+
+    @media (pointer: coarse) {
+      /* A single CSS custom property update propagates to all margin and clip-path consumers */
+      --segmented-width: ${segmentedConfig.coarseWidth};
+    }
+  `;
+};
+const stageContainerVariants = {
+    chevron: stageContainerChevronStyles,
+    segmented: stageContainerSegmentedStyles,
+    milestone: () => css ``
+};
+/**
+ * `<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, theme: { components: { card: { 'border-radius': borderRadius } } }, readOnly, variant: shape }) => {
+    return css `
+      display: flex;
+      position: relative;
+
+      /* Resting z-index: for same-z siblings, DOM order determines paint order.
+       * 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(:nth-last-of-type(-n + 2)) {
+        z-index: 1;
+      }
 
-        @media (pointer: coarse) {
-          --stage-chevron-width: ${chevronConfig.coarseWidth};
+      &:has(button:focus-visible),
+      &:has(button:active) {
+        z-index: 2;
+      }
+
+      ${!readOnly &&
+        css `
+        &:has(button:hover) {
+          z-index: 3;
         }
+      `}
+
+      /* Corner radii are shared across all shape variants */
+      &:nth-of-type(2):not(:nth-last-of-type(2)) > ${StyledStage} {
+        border-start-start-radius: ${borderRadius};
+        border-end-start-radius: ${borderRadius};
       }
 
-      [dir='rtl'] &:nth-of-type(2) > ${StyledStage} {
-        ${stageClipPath(true, false, true)}
+      &:nth-last-of-type(2):not(:nth-of-type(2)) > ${StyledStage} {
+        border-start-end-radius: ${borderRadius};
+        border-end-end-radius: ${borderRadius};
       }
 
-      [dir='rtl'] &:nth-last-of-type(2) > ${StyledStage} {
-        ${stageClipPath(false, true, true)}
+      &:nth-of-type(2):nth-last-of-type(2) > ${StyledStage} {
+        border-radius: ${borderRadius};
+        width: 100%;
       }
+
+      ${stageContainerVariants[shape](theme, readOnly)}
     `;
 });
 StyledStageContainer.defaultProps = defaultThemeProp;
@@ -651,6 +992,195 @@ export const StyledStageGlimpse = styled.div(({ theme }) => {
   `;
 });
 StyledStageGlimpse.defaultProps = defaultThemeProp;
+const milestonePulse = keyframes `
+  0%, 100% {
+    box-shadow: 0 0 0 var(--milestone-pulse-min) var(--milestone-pulse-start);
+  }
+  60% {
+    box-shadow: 0 0 0 var(--milestone-pulse-spread) var(--milestone-pulse-end);
+  }
+`;
+export const StyledMilestoneLabel = styled.span(({ theme }) => {
+    return css `
+    color: ${theme.base.palette['foreground-color']};
+    line-height: ${theme.base['line-height']};
+    text-align: center;
+    align-self: stretch;
+    overflow-wrap: break-word;
+    padding-inline: calc(0.25 * ${theme.base.spacing});
+  `;
+});
+StyledMilestoneLabel.defaultProps = defaultThemeProp;
+/**
+ * `<li>` container for a single stage item in the 'milestone' shape variant.
+ * Renders column-flex layout (milestone above, label below) and draws the
+ * horizontal connector as a single line from this milestone's centre to the next
+ * milestone's centre (::after), sized so every connector has an identical length.
+ */
+export const StyledMilestoneStageContainer = styled.li(({ theme, nextCompleted, status }) => {
+    const { base: { palette: { interactive, 'border-line': borderLine }, spacing } } = theme;
+    const fontSize = calculateFontSize(theme.base['font-size'], theme.base['font-scale']);
+    const connectorFilled = nextCompleted;
+    return css `
+    --connector-height: ${connectorFilled ? '0.25rem' : '0.125rem'};
+    --connector-display: block;
+    --connector-start: 50%;
+    --connector-width: 100%;
+    --connector-bg: ${connectorFilled ? interactive : borderLine};
+    --connector-forced-bg: ${connectorFilled ? 'Highlight' : 'CanvasText'};
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    flex: 1 0 0;
+    font-size: ${fontSize.xs};
+    font-weight: ${status === 'current'
+        ? theme.base['font-weight']['semi-bold']
+        : theme.base['font-weight'].normal};
+    min-width: 15ch;
+    position: relative;
+    gap: ${spacing};
+    z-index: 1;
+
+    &:nth-of-type(2):not(:nth-last-of-type(2)) {
+      --connector-start: calc(var(--milestone-size) / 2);
+      --connector-width: calc(200% - var(--milestone-size));
+      align-items: flex-start;
+      flex: 0.5 0 calc(var(--milestone-size) / 2);
+      min-width: calc(7.5ch + var(--milestone-size) / 2);
+
+      ${StyledMilestoneLabel} {
+        text-align: start;
+      }
+    }
+
+    &:nth-last-of-type(2):not(:nth-of-type(2)) {
+      --connector-display: none;
+      align-items: flex-end;
+      flex: 0.5 0 calc(var(--milestone-size) / 2);
+      min-width: calc(7.5ch + var(--milestone-size) / 2);
+
+      ${StyledMilestoneLabel} {
+        text-align: end;
+      }
+    }
+
+    &:nth-of-type(2):nth-last-of-type(2) {
+      --connector-display: none;
+      align-items: center;
+      flex: 1 0 0;
+    }
+
+    &::after {
+      content: '';
+      display: var(--connector-display);
+      position: absolute;
+      inset-block-start: calc(var(--milestone-size) / 2 - var(--connector-height) / 2);
+      inset-inline-start: var(--connector-start);
+      width: var(--connector-width);
+      height: var(--connector-height);
+      background: var(--connector-bg);
+      pointer-events: none;
+
+      @media (forced-colors: active) {
+        background: var(--connector-forced-bg);
+      }
+    }
+  `;
+});
+StyledMilestoneStageContainer.defaultProps = defaultThemeProp;
+export const StyledMilestoneButton = styled.button(({ theme, status, readOnly }) => {
+    const { base: { 'hit-area': hitArea, animation: { speed: animationSpeed, timing: { ease: animationTiming } }, shadow: { focus: focusShadow } }, components: { button: { 'border-width': borderWidth }, 'case-view': { stages } } } = theme;
+    const stageForeground = calculateForegroundColor(stages.status[status].background, stages.status[status]['foreground-color']);
+    const fontSize = calculateFontSize(theme.base['font-size'], theme.base['font-scale']);
+    const completedBorderColor = status === 'completed'
+        ? tryCatch(() => darken(0.12, stages.status.completed.background), () => 'transparent')
+        : '';
+    return css `
+    position: relative;
+    z-index: 1;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    flex-shrink: 0;
+    border-radius: 50%;
+    width: var(--milestone-size);
+    height: var(--milestone-size);
+    background: ${stages.status[status].background};
+    color: ${stageForeground};
+    font-size: ${fontSize.s};
+    font-weight: ${status === 'current'
+        ? theme.base['font-weight']['semi-bold']
+        : theme.base['font-weight'].normal};
+    outline: none;
+    border: none;
+    cursor: ${readOnly ? 'default' : 'pointer'};
+    transition: box-shadow calc(2 * ${animationSpeed}) ${animationTiming};
+
+    ${status === 'completed' &&
+        css `
+      box-shadow: inset 0 0 0 calc(2 * ${borderWidth}) ${completedBorderColor};
+    `}
+
+    &:focus-visible {
+      box-shadow: ${focusShadow};
+
+      @media (forced-colors: active) {
+        outline: 0.125rem solid Highlight;
+        outline-offset: 0.125rem;
+      }
+    }
+
+    ${!readOnly &&
+        css `
+      &:hover {
+        filter: brightness(0.85);
+      }
+
+      &:active {
+        filter: brightness(0.85);
+      }
+    `}
+
+    ${status === 'current' &&
+        !readOnly &&
+        css `
+      &::before {
+        content: '';
+        position: absolute;
+        inset: 0;
+        border-radius: 50%;
+        pointer-events: none;
+        animation: ${milestonePulse} 2s ease-out infinite;
+
+        @media (prefers-reduced-motion: reduce) {
+          animation: none;
+        }
+      }
+    `}
+
+    /* Expanded hit area */
+    &::after {
+      content: '';
+      position: absolute;
+      width: ${hitArea['mouse-min']};
+      height: ${hitArea['mouse-min']};
+      inset-block-start: calc((${hitArea['mouse-min']} - var(--milestone-size)) / -2);
+      inset-inline-start: calc((${hitArea['mouse-min']} - var(--milestone-size)) / -2);
+
+      @media (pointer: coarse) {
+        width: ${hitArea['finger-min']};
+        height: ${hitArea['finger-min']};
+        inset-block-start: calc((${hitArea['finger-min']} - var(--milestone-size)) / -2);
+        inset-inline-start: calc((${hitArea['finger-min']} - var(--milestone-size)) / -2);
+      }
+    }
+
+    @media (forced-colors: active) {
+      border: 0.125rem solid ButtonText;
+    }
+  `;
+});
+StyledMilestoneButton.defaultProps = defaultThemeProp;
 /**
  * Visually hidden `<p>` providing an accessible description for the stages list,
  * announced by screen readers but not displayed on screen.