@juspay/svelte-ui-components 2.134.1 → 2.136.0

package/dist/Modal/Modal.svelte

@@ -3,7 +3,7 @@
   import { onMount, onDestroy } from 'svelte';
   import ModalAnimation from '../Animations/ModalAnimation.svelte';
   import OverlayAnimation from '../Animations/OverlayAnimation.svelte';
-  import { createDebouncer } from '../utils';
+  import { createDebouncer, lockBodyScroll, unlockBodyScroll } from '../utils';
   import Button from '../Button/Button.svelte';
   import Img from '../Img/Img.svelte';
 
@@ -122,7 +122,7 @@
 
   onMount(() => {
     if (lockScroll) {
-      document.body.style.overflow = 'hidden';
+      lockBodyScroll();
     }
     if (typeof autoDismissAfter === 'number') {
       dismissTimer = setTimeout(() => onclose?.(), autoDismissAfter);
@@ -139,7 +139,7 @@
     }
     if (typeof window !== 'undefined') {
       if (lockScroll) {
-        document.body.style.overflow = '';
+        unlockBodyScroll();
       }
       if (supportHardwareBackPress) {
         if (!backPressed) {

package/dist/Pill/Pill.svelte

@@ -8,6 +8,7 @@
     dismissible = false,
     disabled = false,
     testId,
+    title,
     dismissIcon,
     leadingIcon,
     onclick,
@@ -52,6 +53,7 @@
   tabindex={interactive ? 0 : null}
   aria-disabled={interactive && disabled ? true : null}
   data-pw={typeof testId === 'string' ? testId : null}
+  title={title ?? null}
   testID={typeof testId === 'string' ? testId : null}
 >
   {#if typeof leadingIcon === 'function'}

package/dist/Pill/properties.d.ts

@@ -7,6 +7,7 @@ export type OptionalPillProperties = {
     dismissible?: boolean;
     disabled?: boolean;
     testId?: string;
+    title?: string;
     dismissIcon?: Snippet;
     /**
      * A Svelte snippet rendered immediately before the text label inside a

package/dist/Sheet/Sheet.svelte

@@ -1,27 +1,7 @@
-<script lang="ts" module>
-  // Reference-counted so two Sheets open at once (or a Sheet nested inside
-  // another scroll-locking surface) don't have the second one's close clobber
-  // the first one's still-needed lock.
-  let scrollLockCount = 0;
-
-  function lockScroll() {
-    if (scrollLockCount === 0) {
-      document.body.style.overflow = 'hidden';
-    }
-    scrollLockCount += 1;
-  }
-
-  function unlockScroll() {
-    scrollLockCount = Math.max(0, scrollLockCount - 1);
-    if (scrollLockCount === 0) {
-      document.body.style.overflow = '';
-    }
-  }
-</script>
-
 <script lang="ts">
   import type { SheetProperties } from './properties';
   import { fly, fade } from 'svelte/transition';
+  import { lockBodyScroll, unlockBodyScroll } from '../utils';
   import { tick } from 'svelte';
   import Button from '../Button/Button.svelte';
 
@@ -97,7 +77,7 @@
   }
 
   function scrollLockAction(_node: HTMLElement) {
-    lockScroll();
+    lockBodyScroll();
     tick().then(() => {
       if (sheetPanel !== null) {
         sheetPanel.focus();
@@ -105,7 +85,7 @@
     });
     return {
       destroy() {
-        unlockScroll();
+        unlockBodyScroll();
       }
     };
   }

package/dist/StatCard/StatCard.svelte

@@ -185,6 +185,8 @@
           <div class="statcard-row-value-line">
             <div
               class="statcard-value"
+              class:statcard-value-success={row.valueVariant === 'success'}
+              class:statcard-value-warning={row.valueVariant === 'warning'}
               data-pw={typeof testId === 'string' ? `${testId}-value-${rowIndex}` : null}
               testID={typeof testId === 'string' ? `${testId}-value-${rowIndex}` : null}
             >
@@ -217,9 +219,25 @@
               </div>
             {/if}
             {#if typeof row.additionalContent === 'string' && row.additionalContent.length > 0}
-              <div class="statcard-row-additional">{row.additionalContent}</div>
+              <div
+                class="statcard-row-additional"
+                class:statcard-row-additional-break={row.additionalContentBreak === true}
+                data-pw={typeof testId === 'string' ? `${testId}-additional-${rowIndex}` : null}
+                testID={typeof testId === 'string' ? `${testId}-additional-${rowIndex}` : null}
+              >
+                {row.additionalContent}
+              </div>
             {/if}
           </div>
+          {#if typeof row.subtitle === 'string' && row.subtitle.length > 0}
+            <div
+              class="statcard-row-subtitle"
+              data-pw={typeof testId === 'string' ? `${testId}-subtitle-${rowIndex}` : null}
+              testID={typeof testId === 'string' ? `${testId}-subtitle-${rowIndex}` : null}
+            >
+              {row.subtitle}
+            </div>
+          {/if}
           {#if Array.isArray(row.breakdown) && row.breakdown.length > 0}
             {#if typeof row.breakdownHeading === 'string' && row.breakdownHeading.length > 0}
               <div class="statcard-breakdown-heading">{row.breakdownHeading}</div>
@@ -421,6 +439,24 @@
     line-height: var(--statcard-value-line-height, 1.2);
   }
 
+  .statcard-value-success {
+    color: var(--statcard-value-success-color, #16a34a);
+  }
+
+  .statcard-value-warning {
+    color: var(--statcard-value-warning-color, #f59e0b);
+  }
+
+  /* Per-row value typography override — falls back to the card-level value
+     tokens so an unset row matches today's shared appearance exactly, then to
+     the same literals as the last resort. Scoped to the row's value line so
+     the single (non-rows) card value is unaffected. Mirrors the fallback
+     shape of --statcard-row-subtitle-font-size below. */
+  .statcard-row-value-line .statcard-value {
+    font-size: var(--statcard-row-value-font-size, var(--statcard-value-font-size, 24px));
+    font-weight: var(--statcard-row-value-font-weight, var(--statcard-value-font-weight, 600));
+  }
+
   .statcard-delta {
     font-size: var(--statcard-delta-font-size, 13px);
     font-weight: var(--statcard-delta-font-weight, 500);
@@ -458,6 +494,23 @@
     line-height: var(--statcard-subtitle-line-height, 1.4);
   }
 
+  /* Per-row subtitle — falls back to the card-level subtitle tokens so a
+     consumer that already themes `.statcard-subtitle` gets a matching look
+     with no extra wiring, then to the same literals as the last resort. */
+  .statcard-row-subtitle {
+    order: var(--statcard-row-subtitle-order, 0);
+    font-size: var(--statcard-row-subtitle-font-size, var(--statcard-subtitle-font-size, 12px));
+    font-weight: var(
+      --statcard-row-subtitle-font-weight,
+      var(--statcard-subtitle-font-weight, 400)
+    );
+    color: var(--statcard-row-subtitle-color, var(--statcard-subtitle-color, #9ca3af));
+    line-height: var(
+      --statcard-row-subtitle-line-height,
+      var(--statcard-subtitle-line-height, 1.4)
+    );
+  }
+
   /* Multi-row layout */
   .statcard-rows {
     order: var(--statcard-rows-order, 0);
@@ -498,6 +551,7 @@
   }
 
   .statcard-row-heading-wrap {
+    order: var(--statcard-row-heading-order, 0);
     display: flex;
     align-items: center;
   }
@@ -516,6 +570,7 @@
   }
 
   .statcard-row-value-line {
+    order: var(--statcard-row-value-line-order, 0);
     display: flex;
     align-items: baseline;
     gap: var(--statcard-row-value-gap, 8px);
@@ -523,12 +578,20 @@
   }
 
   .statcard-row-additional {
+    /* Default: flows inline in the wrapping flex row and only breaks if it
+       does not fit — matches short unit suffixes like "%" or "ms". */
     font-size: var(--statcard-row-additional-font-size, 12px);
     font-weight: var(--statcard-row-additional-font-weight, 400);
     color: var(--statcard-row-additional-color, #9ca3af);
     line-height: 1.4;
   }
 
+  .statcard-row-additional-break {
+    /* Opt-in: forces its own line regardless of available width, for
+       descriptive text that should never sit beside the value/delta. */
+    flex-basis: var(--statcard-row-additional-flex-basis, 100%);
+  }
+
   /* Breakdown grid */
   .statcard-breakdown-heading {
     font-size: var(--statcard-breakdown-heading-font-size, 11px);

package/dist/StatCard/properties.d.ts

@@ -43,15 +43,57 @@ export type StatCardRow = {
     change?: number | null;
     /** Invert delta colors for lower-is-better metrics on this row. */
     invertChangeColors?: boolean;
-    /** Additional descriptive text rendered after the delta. */
+    /**
+     * Additional descriptive text rendered after the value/delta. By default it
+     * flows inline and only wraps if it does not fit (e.g. a short unit suffix
+     * like "%" or "ms"). Set `additionalContentBreak` to force it onto its own
+     * line regardless of available width.
+     */
     additionalContent?: string;
+    /**
+     * Forces `additionalContent` onto its own line below the value/delta,
+     * regardless of available width. Omit to keep the default inline flow.
+     */
+    additionalContentBreak?: boolean;
+    /** Tints this row's value text for a warning or success state. Omit for the default color. */
+    valueVariant?: 'success' | 'warning';
+    /**
+     * Secondary label rendered below this row's value line (e.g. a per-row
+     * comparison-period caption). Independent of the card-level `subtitle` —
+     * both may be set at once, e.g. when different rows compare against
+     * different baselines.
+     *
+     * Renders after the value line by default (heading → value → subtitle in
+     * markup order). A consumer that needs title → subtitle → value can
+     * reorder without touching markup via `--statcard-row-subtitle-order` /
+     * `--statcard-row-value-line-order` — see `testId` below.
+     */
+    subtitle?: string;
     /** Tooltip shown on the row heading. */
     tooltip?: StatCardTooltip;
     /** Heading rendered above the breakdown grid. */
     breakdownHeading?: string;
     /** Breakdown items rendered in a grid below the row value. */
     breakdown?: StatCardBreakdownItem[];
-    /** Test selector for the row root element. */
+    /**
+     * Test selector for the row root element, rendered as `data-pw`/`testID`.
+     * Also the CSS scoping anchor for per-row typography and layout: target
+     * `[data-pw="<testId>"]` to set `--statcard-row-value-font-size`,
+     * `--statcard-row-value-font-weight`, `--statcard-row-heading-font-size`,
+     * `--statcard-row-heading-font-weight`, or the row's flex `order` overrides
+     * (`--statcard-row-heading-order`, `--statcard-row-value-line-order`,
+     * `--statcard-row-subtitle-order`) for just this row, independent of its
+     * siblings — see the CSS Variables table in the component docs.
+     *
+     * The row's three sub-elements (heading wrap, value line, subtitle) render
+     * in that markup order and each default to `order: 0`, so an untouched row
+     * is byte-identical to today. Set the three order hooks to reorder them —
+     * e.g. subtitle before the value line for a title → subtitle → value
+     * layout — the same pattern the card-level `--statcard-subtitle-order` /
+     * `--statcard-value-row-order` hooks already use for the card's own
+     * sections. `.statcard-row` is a `display: flex; flex-direction: column`
+     * container, so `order` applies directly with no other CSS needed.
+     */
     testId?: string;
 };
 export type OptionalStatCardProperties = {

package/dist/Status/Status.svelte

@@ -6,6 +6,7 @@
   let {
     statusIcon = 'icons/order-success-icon.svg',
     statusText = '',
+    statusTextTag = 'div',
     statusDescription = '',
     buttonProperties,
     classes,
@@ -30,7 +31,7 @@
         <Img inlineSvg src={statusIcon} alt="status" />
       {/if}
     </div>
-    <div class="status-text">{statusText}</div>
+    <svelte:element this={statusTextTag} class="status-text">{statusText}</svelte:element>
     <div class="status-description">
       {#if typeof descriptionSnippet === 'function'}
         {@render descriptionSnippet()}

package/dist/Status/properties.d.ts

@@ -4,6 +4,16 @@ export type StatusProperties = StatusEventProperties & {
     statusIcon?: string;
     statusText: string;
     statusDescription: string;
+    /**
+     * Element `statusText` renders as. Defaults to `'div'`, matching every existing
+     * consumer's render output exactly. Reach for `'h1'`..`'h6'` when `statusText`
+     * carries a real page/section heading: an app that wires typography to semantic
+     * tags (rather than setting `font-size` in component styles) can only pick up
+     * that tag's size, weight and colour, and only a heading tag joins the
+     * document outline for assistive tech — a `div` does neither, no matter what
+     * CSS targets it.
+     */
+    statusTextTag?: 'div' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
     buttonProperties?: ButtonProperties;
     classes?: string;
     /**

package/dist/Stepper/Step.svelte

@@ -10,6 +10,8 @@
     orientation = 'horizontal',
     classes,
     ariaLabel,
+    testId,
+    suppressRoleAndTabindex,
     onclick,
     onkeydown
   }: StepProperties = $props();
@@ -33,12 +35,29 @@
   );
 </script>
 
+<!-- role and tabindex are suppressed together by suppressRoleAndTabindex, so this
+     can never end up non-interactive with a tab stop; matches ListItem's precedent. -->
+<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+<!-- The per-status colour tokens are remapped by Stepper's own `.status-<name>` wrapper.
+     A Step used on its own — outside a Stepper — never gets that wrapper, so every status
+     rendered identically at the neutral default and the component could not express its
+     own state. Carrying the same classes here lets a bare Step theme itself; inside a
+     Stepper both set the same custom properties to the same values, so nothing about an
+     existing consumer changes. These are `class:` directives rather than an interpolated
+     string so the compiler can see the selectors are used and does not prune the rules. -->
 <div
   class={stepClass}
+  class:status-completed={status === 'completed'}
+  class:status-active={status === 'active'}
+  class:status-failure={status === 'failure'}
+  class:status-in-progress={status === 'in-progress'}
+  class:status-muted={status === 'muted'}
+  data-pw={typeof testId === 'string' ? testId : null}
+  testID={typeof testId === 'string' ? testId : null}
   onclick={handleStepClick}
   onkeydown={handleKeydown}
-  role="button"
-  tabindex="0"
+  role={suppressRoleAndTabindex ? null : 'button'}
+  tabindex={suppressRoleAndTabindex ? null : 0}
   aria-label={ariaLabel ?? null}
   aria-labelledby={ariaLabel ? null : `step-label-${stepIndex}`}
   aria-current={status === 'active' ? 'step' : null}
@@ -98,6 +117,10 @@
     display: flex;
     flex-direction: var(--step-flex-direction, row);
     align-items: center;
+    /* Lets a step's own box grow to fill a --step-container-flex share of the
+       Stepper row — a prerequisite for the separator below to have any free
+       space to grow into. Default 0 keeps a step sized to its content. */
+    flex-grow: var(--step-flex-grow, 0);
   }
 
   .step-vertical {
@@ -105,6 +128,63 @@
     align-items: flex-start;
   }
 
+  /* Mirrors Stepper.svelte's per-status remapping so a bare Step themes itself. Only the
+     tokens Step actually renders are set here; the separator is Stepper's to draw. Each
+     chain terminates in the same literal Stepper uses, so the two agree by construction. */
+  .status-completed {
+    --step-text-color: var(--step-text-completed-color, #24aa5a);
+    --step-index-container-background-color: var(
+      --step-index-container-completed-background-color,
+      #24aa5a
+    );
+    --step-index-container-border: var(--step-index-container-completed-border, none);
+  }
+
+  .status-active {
+    --step-text-color: var(--step-text-active-color, #2f3841);
+    --step-index-container-background-color: var(
+      --step-index-container-active-background-color,
+      #2f3841
+    );
+    --step-index-container-border: var(--step-index-container-active-border, none);
+  }
+
+  .status-failure {
+    --step-text-color: var(--step-text-failure-color, #e53935);
+    --step-index-container-background-color: var(
+      --step-index-container-failure-background-color,
+      var(--stepper-status-failure-color, #e53935)
+    );
+    --step-index-container-border: var(--step-index-container-failure-border, none);
+  }
+
+  .status-in-progress {
+    --step-text-color: var(--step-text-in-progress-color, #f59e0b);
+    --step-index-container-background-color: var(
+      --step-index-container-in-progress-background-color,
+      var(--stepper-status-in-progress-color, #f59e0b)
+    );
+    --step-index-container-border: var(--step-index-container-in-progress-border, none);
+  }
+
+  .status-muted {
+    --step-text-color: var(--step-text-muted-color, #667080);
+    --step-index-container-background-color: var(
+      --step-index-container-muted-background-color,
+      #c9d2db
+    );
+    /* The circle is pale, so the numeral cannot inherit the white used on every other
+       status — that measured 1.53:1. #2f3841 is the same literal the active status
+       already uses for text, and reads at 7.79:1 here. */
+    --step-index-color: var(--step-index-muted-color, #2f3841);
+    --step-index-container-border: var(--step-index-container-muted-border, none);
+    --step-index-container-height: var(--step-index-container-muted-height, 20px);
+    --step-index-container-width: var(--step-index-container-muted-width, 20px);
+    --step-index-font-size: var(--step-index-muted-font-size, 10px);
+  }
+
+  /* status-pending sets nothing — it is the neutral default already in .step-index-container. */
+
   .step-index-container {
     display: flex;
     justify-content: center;
@@ -113,6 +193,11 @@
     width: var(--step-index-container-width, 30px);
     border-radius: var(--step-index-container-radius, 50%);
     background-color: var(--step-index-container-background-color, #798fa5cc);
+    /* No border today, so the fallback is `none` — an existing consumer that sets
+       nothing renders byte-identically. Shared with .step-icon-container below so
+       a status override (see Stepper.svelte) themes the circle whichever of the
+       two mutually-exclusive renders is showing. */
+    border: var(--step-index-container-border, none);
     color: var(--step-index-color, white);
     flex-shrink: 0;
   }
@@ -125,6 +210,7 @@
     width: var(--step-index-container-width, 30px);
     border-radius: var(--step-index-container-radius, 50%);
     background-color: var(--step-index-container-background-color, #798fa5cc);
+    border: var(--step-index-container-border, none);
     flex-shrink: 0;
     overflow: hidden;
   }
@@ -154,6 +240,9 @@
     display: var(--stepper-separator-display, var(--separator-display, block));
     height: var(--stepper-separator-height, var(--separator-height, 1px));
     width: var(--stepper-separator-width, var(--separator-width, 50px));
+    /* 0 keeps the separator pinned to its width above; set alongside --step-flex-grow
+       and --step-container-flex to let it stretch into a card's remaining width. */
+    flex-grow: var(--stepper-separator-flex-grow, 0);
     margin: var(--stepper-separator-margin, var(--separator-margin, 0px 12px 0px 12px));
     background-image: var(
       --stepper-separator-background-image,
@@ -200,6 +289,10 @@
   .step-text {
     margin: var(--step-text-margin, 0px 0px 0px 12px);
     font-size: var(--step-text-font-size, 12px);
+    /* No font-weight is set today, so the div inherits the browser default
+       `normal` — that is the literal fallback, keeping an existing consumer
+       byte-identical. */
+    font-weight: var(--step-text-font-weight, normal);
     color: var(--step-text-color, #798fa5cc);
   }
 

package/dist/Stepper/Stepper.svelte

@@ -8,6 +8,8 @@
     orientation = 'horizontal',
     classes,
     testId,
+    suppressRoleAndTabindex,
+    suppressContainerTestId,
     onstepclick,
     onhandleStepClick
   }: StepperProperties = $props();
@@ -28,6 +30,12 @@
   // Support the deprecated onhandleStepClick alias — onstepclick takes priority.
   const effectiveStepClick = $derived(onstepclick ?? onhandleStepClick);
 
+  // Per-step ids always derive from testId, even when the container itself is
+  // opted out of claiming it — only the container's own data-pw/testID is suppressed.
+  const containerTestId = $derived(
+    typeof testId === 'string' && !suppressContainerTestId ? testId : null
+  );
+
   let containerClass = $derived(
     ['container', orientation === 'vertical' ? 'container-vertical' : '', classes ?? '']
       .filter((c) => c.length > 0)
@@ -35,14 +43,11 @@
   );
 </script>
 
-<div
-  class={containerClass}
-  data-pw={typeof testId === 'string' ? testId : null}
-  testID={typeof testId === 'string' ? testId : null}
-  role="list"
->
+<div class={containerClass} data-pw={containerTestId} testID={containerTestId} role="list">
   {#each steps as currentStep, stepIndex (stepIndex)}
     {@const effectiveStatus = resolveStatus(stepIndex, currentStep.status ?? null)}
+    {@const stepTestId =
+      currentStep.testId ?? (typeof testId === 'string' ? `${testId}-step-${stepIndex + 1}` : null)}
     <div
       role="listitem"
       class="step-container status-{effectiveStatus} {effectiveStatus === 'active'
@@ -56,7 +61,9 @@
         stepIndex={stepIndex + 1}
         status={effectiveStatus}
         badge={currentStep.badge}
+        testId={stepTestId}
         {orientation}
+        {suppressRoleAndTabindex}
       />
     </div>
   {/each}
@@ -66,6 +73,7 @@
   .container {
     display: flex;
     flex-direction: var(--container-flex-direction, row);
+    flex-wrap: var(--container-flex-wrap, nowrap);
     align-items: center;
   }
 
@@ -81,6 +89,7 @@
   .step-container {
     display: flex;
     align-items: center;
+    flex: var(--step-container-flex, 0 1 auto);
   }
 
   /* status-completed */
@@ -94,6 +103,10 @@
       --step-index-container-completed-background-color,
       #24aa5a
     );
+    /* No border existed for any status before this, so every one of these
+       per-status hooks falls back to `none` — byte-identical for a consumer
+       that sets nothing. */
+    --step-index-container-border: var(--step-index-container-completed-border, none);
   }
 
   /* status-active */
@@ -107,9 +120,10 @@
       --step-index-container-active-background-color,
       #2f3841
     );
+    --step-index-container-border: var(--step-index-container-active-border, none);
   }
 
-  /* status-pending: no override — falls through to #798fa5cc grey default in Step.svelte */
+  /* status-pending: no override — falls through to #798fa5cc grey (and no border) default in Step.svelte */
 
   /* status-failure */
   .status-failure {
@@ -122,6 +136,7 @@
       --step-index-container-failure-background-color,
       var(--stepper-status-failure-color, #e53935)
     );
+    --step-index-container-border: var(--step-index-container-failure-border, none);
   }
 
   /* status-in-progress */
@@ -135,6 +150,36 @@
       --step-index-container-in-progress-background-color,
       var(--stepper-status-in-progress-color, #f59e0b)
     );
+    --step-index-container-border: var(--step-index-container-in-progress-border, none);
+  }
+
+  /* status-muted: a smaller, subtly-tinted marker for a de-emphasized or
+     supplementary step (e.g. an informational marker riding alongside a
+     primary rail). New opt-in status value — none of the statuses above are
+     touched, and a step only reaches these rules by setting status:'muted'
+     explicitly (resolveStatus never derives it). Reuses the same
+     --step-index-container-height/-width/-background-color, --step-text-color,
+     --stepper-separator-background-image-color and --step-index-container-border
+     hooks the other statuses already theme through, so a call site can further
+     override any of them the same way. */
+  .status-muted {
+    --step-text-color: var(--step-text-muted-color, #667080);
+    --stepper-separator-background-image-color: var(
+      --stepper-separator-background-image-muted-color,
+      #c9d2db
+    );
+    --step-index-container-background-color: var(
+      --step-index-container-muted-background-color,
+      #c9d2db
+    );
+    /* The circle is pale, so the numeral cannot inherit the white used on every other
+       status — that measured 1.53:1. #2f3841 is the same literal the active status
+       already uses for text, and reads at 7.79:1 here. */
+    --step-index-color: var(--step-index-muted-color, #2f3841);
+    --step-index-container-border: var(--step-index-container-muted-border, none);
+    --step-index-container-height: var(--step-index-container-muted-height, 20px);
+    --step-index-container-width: var(--step-index-container-muted-width, 20px);
+    --step-index-font-size: var(--step-index-muted-font-size, 10px);
   }
 
   :global([theme='dark']) .status-failure {

package/dist/Stepper/properties.d.ts

@@ -1,5 +1,12 @@
 import type { Snippet } from 'svelte';
-export type StepStatus = 'completed' | 'active' | 'pending' | 'failure' | 'in-progress';
+/**
+ * `muted` is an opt-in, purely additive status: a smaller, subtly-tinted circle
+ * for a de-emphasized or supplementary step (e.g. an informational marker
+ * riding alongside a primary rail). It is only ever reached by setting a
+ * step's `status` explicitly — `resolveStatus` in Stepper.svelte never derives
+ * it from `currentStepIndex` — so no existing step changes how it renders.
+ */
+export type StepStatus = 'completed' | 'active' | 'pending' | 'failure' | 'in-progress' | 'muted';
 export type Step = {
     label: string;
     /**
@@ -15,6 +22,13 @@ export type Step = {
      * "New" label.
      */
     badge?: Snippet;
+    /**
+     * Test selector for this step's root element, rendered as `data-pw`. When
+     * omitted and the Stepper itself has a `testId`, falls back to
+     * `${stepperTestId}-step-${n}` (1-based). When neither is set, no attribute
+     * is rendered.
+     */
+    testId?: string;
 };
 export type MandatoryStepperProperties = {
     steps: Array<Step>;
@@ -24,6 +38,18 @@ export type OptionalStepperProperties = {
     orientation?: 'horizontal' | 'vertical';
     classes?: string;
     testId?: string;
+    /**
+     * Removes every Step's synthetic role and tab stop while retaining its mouse handlers.
+     * Opt in when an ancestor or consumer supplies the semantic interactive control.
+     */
+    suppressRoleAndTabindex?: boolean;
+    /**
+     * Stops the Stepper's own root element from rendering `testId` as `data-pw`/`testID`,
+     * while per-step ids still derive from `testId` (`${testId}-step-${n}`) exactly as
+     * before. Opt in when the element wrapping the Stepper already carries the same
+     * `data-pw` value, which would otherwise leave two elements matching that selector.
+     */
+    suppressContainerTestId?: boolean;
 };
 export type StepperEventProperties = {
     onstepclick?: (event: {
@@ -40,6 +66,13 @@ export type OptionalStepProperties = {
     status?: StepStatus;
     badge?: Snippet;
     classes?: string;
+    /** Test selector for the step's root element, rendered as `data-pw`. */
+    testId?: string | null;
+    /**
+     * Removes Step's synthetic role and tab stop while retaining its mouse handlers.
+     * Opt in when an ancestor or consumer supplies the semantic interactive control.
+     */
+    suppressRoleAndTabindex?: boolean;
 };
 export type StepEventProperties = {
     onclick?: (event: {