@nysds/components 1.18.0 → 1.18.3

package/dist/packages/mcp-server/src/lib/token-parser.d.ts

@@ -9,15 +9,6 @@
  * - Alias references become var() expressions
  * - Layer prefixes (primitive, applied) are stripped
  */
-/**
- * Legacy interface for backward compatibility
- */
-export interface DesignToken {
-    name: string;
-    value: string;
-    category: string;
-    description?: string;
-}
 /**
  * CSS-centric token info aligned with tokens.css output
  */
@@ -47,10 +38,6 @@ export interface TokenGraphNode {
     referencesVariable?: string;
     usedBy: string[];
 }
-export interface TokenGroup {
-    category: string;
-    tokens: DesignToken[];
-}
 /**
  * Get the path to tokens.json file
  * Uses ESM-compatible path resolution with fallbacks for different contexts
@@ -94,14 +81,6 @@ export declare function getCSSTokens(): CSSTokenInfo[];
  * Get CSS tokens filtered by category
  */
 export declare function getCSSTokensByCategory(category: string): CSSTokenInfo[];
-/**
- * Get CSS tokens filtered by layer
- */
-export declare function getCSSTokensByLayer(layer: string): CSSTokenInfo[];
-/**
- * Search CSS tokens by variable name, value, or description
- */
-export declare function searchCSSTokens(query: string): CSSTokenInfo[];
 /**
  * Get a single token by CSS variable name
  */
@@ -118,21 +97,30 @@ export declare function getCSSTokenCategories(): {
  */
 export declare function getTokensCSS(): string | null;
 /**
- * Load all design tokens (legacy format)
- */
-export declare function getAllTokens(): DesignToken[];
-/**
- * Get tokens filtered by category (legacy format)
+ * Get recommended tokens for everyday use.
+ *
+ * Excludes color primitive tokens (the ~150 palette ramps like neutral-*, red-*,
+ * blue-*) which are low-level raw values. For font tokens, applied aliases
+ * (body-*, h*, ui-*) are sorted before primitives so the most useful tokens
+ * appear first.
  */
-export declare function getTokensByCategory(category: string): DesignToken[];
+export declare function getRecommendedTokens(): CSSTokenInfo[];
 /**
- * Search tokens by name or value (legacy format)
+ * Get only primitive (raw value) tokens across all categories.
  */
-export declare function searchTokens(query: string): DesignToken[];
+export declare function getPrimitiveTokens(): CSSTokenInfo[];
 /**
- * Get available token categories (legacy format)
+ * Get alternative tokens in the same category that share the same name prefix.
+ *
+ * First looks for child variants (tokens starting with this token's name + "-"):
+ *   --nys-color-text  →  finds --nys-color-text-weak, --nys-color-text-reverse, etc.
+ *
+ * If no children exist, looks for siblings (tokens sharing the same parent prefix):
+ *   --nys-color-text-weak  →  parent: --nys-color-text  →  finds text, text-weaker, etc.
+ *
+ * Returns an array of cssVariable strings (empty if none found).
  */
-export declare function getTokenCategories(): string[];
+export declare function getAlternativeTokens(token: CSSTokenInfo): string[];
 /**
  * Clear all cached tokens (useful for testing)
  */

package/dist/packages/mcp-server/src/tools/token-tools.d.ts

@@ -4,9 +4,8 @@
  * MCP tools for working with NYSDS design tokens.
  *
  * Tools:
- * - get_tokens: Get tokens, categories, or themes
- * - find_tokens: Search tokens by CSS variable, value, or description
- * - get_token_info: Get detailed token info with optional context validation
+ * - find_tokens: Search or browse tokens (discovery)
+ * - get_token: Get full details for a specific token (deep dive)
  * - get_token_graph: Get token dependency graph
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

package/dist/packages/nys-avatar/src/nys-avatar.d.ts

@@ -51,6 +51,8 @@ export declare class NysAvatar extends LitElement {
      * Functions
      * --------------------------------------------------------------------------
      */
+    private get _cleanAriaLabel();
+    private _colorStyle;
     /**
      * Computes the appropriate foreground color (icon or initials)
      * based on the avatar's background color for sufficient contrast.

package/dist/packages/nys-backtotop/src/nys-backtotop.d.ts

@@ -9,9 +9,9 @@ import { LitElement } from "lit";
  * If no footer exists, place at the bottom of the body tag (after main content). Floating
  * positioning allows it to overlay content without taking up layout space.
  *
- * **Focus Management:** When clicked, after scrolling to the top, focus is automatically moved
- * to the `<main>` element (if present), the first heading (`<h1>` or `<h2>`), or the document element.
- * This ensures keyboard navigation continues naturally from the top of the page.
+ * **Focus Management:** When clicked, after scrolling to the top, focus is moved to `<body>`.
+ * This places the user before the skip-navigation link so they can re-use it to jump directly
+ * back to main content — and works regardless of whether the page uses `<main>` or heading landmarks.
  *
  * @summary Floating back-to-top button with auto-show behavior, smooth scroll, and focus management.
  * @element nys-backtotop

package/dist/packages/nys-button/src/nys-button.d.ts

@@ -181,6 +181,7 @@ export declare class NysButton extends LitElement {
     private _handleBlur;
     private _handleClick;
     private _handleKeydown;
+    private _handleKeyup;
     /**
      * A Solution to the Vanilla JS & Native HTML keydown:
      *

package/dist/packages/nys-checkbox/src/nys-checkbox.d.ts

@@ -75,6 +75,7 @@ export declare class NysCheckbox extends LitElement {
     size: "sm" | "md";
     other: boolean;
     showOtherError: boolean;
+    private _mobileQuery;
     private isMobile;
     private _hasUserInteracted;
     getInputElement(): Promise<HTMLInputElement | null>;
@@ -105,11 +106,11 @@ export declare class NysCheckbox extends LitElement {
     private _handleInvalid;
     private _manageLabelClick;
     get _hasDescription(): boolean;
-    private _handleResize;
     /**
      * Event Handlers
      * --------------------------------------------------------------------------
      */
+    private _handleMobileQuery;
     private _emitChangeEvent;
     private _emitOtherInputEvent;
     private _handleChange;

package/dist/packages/nys-dropdownmenu/src/nys-dropdownmenu.d.ts

@@ -40,6 +40,7 @@ export declare class NysDropdownMenu extends LitElement {
     private _ariaTarget;
     private _lastFocusedIndex;
     private readonly GAP;
+    private _resizeObserver;
     /**
      * Lifecycle Methods
      * --------------------------------------------------------------------------
@@ -105,7 +106,6 @@ export declare class NysDropdownMenu extends LitElement {
     private _handleMenuClick;
     private _handleTriggerKeydown;
     private _handleMenuKeydown;
-    private _handleWindowResize;
     private _handleWindowScroll;
     render(): import("lit-html").TemplateResult<1>;
 }

package/dist/packages/nys-globalheader/src/nys-globalheader.d.ts

@@ -36,6 +36,7 @@ export declare class NysGlobalHeader extends LitElement {
      * --------------------------------------------------------------------------
      */
     firstUpdated(): void;
+    disconnectedCallback(): void;
     /**
      * Functions
      * --------------------------------------------------------------------------
@@ -47,5 +48,7 @@ export declare class NysGlobalHeader extends LitElement {
     private _listenLinkClicks;
     private _renderBrandMark;
     private _getNysLogo;
+    private _boundClickOutside;
+    private _boundKeyDown;
     render(): import("lit-html").TemplateResult<1>;
 }

package/dist/packages/nys-modal/src/nys-modal.d.ts

@@ -45,6 +45,7 @@ export declare class NysModal extends LitElement {
     private _actionButtonSlot;
     private _prevFocusedElement;
     private _originalBodyOverflow;
+    private _mobileMedia;
     private hasBodySlots;
     private hasActionSlots;
     /**

package/dist/packages/nys-stepper/src/nys-step.d.ts

@@ -2,27 +2,55 @@ import { LitElement } from "lit";
 /**
  * A single step within `nys-stepper`. Represents one stage in a multi-step process.
  *
- * Mark as `current` to indicate active progress point. Previous steps become clickable for navigation.
- * Set `href` for page-based navigation or listen to `nys-step-click` for SPA routing.
+ * Mark as `current` to indicate the active progress point. Previous steps become clickable for navigation.
+ * Set `href` for page-based navigation, or omit it and listen to `nys-step-click` for SPA/framework routing.
  *
- * ## Step States
+ * ## Step states
  *
- * Understanding the three step states is critical for proper stepper usage:
+ * Three boolean attributes control step appearance and behavior:
  *
- * - **`selected`** - Which step is currently being displayed/viewed. This controls which step's
- *   content is shown. Defaults to `current` if not set. Cannot be set on a step after `current`.
- *   Users can click previous steps to change `selected` without changing `current`.
+ * - **`current`** — The furthest step the user has reached (the progress boundary). Only one step should
+ *   have `current` at a time; if multiple are set the parent stepper keeps the first and removes the rest.
+ *   Steps after `current` are not navigable and do not fire `nys-step-click`. Update `current` in your
+ *   application state when the user advances.
  *
- * - **`current`** - The furthest step the user has reached. This is the progress boundary.
- *   Update this as the user completes steps and advances. Steps after `current` are not navigable.
- *   Only one step should have `current` at a time.
+ * - **`selected`** — Which step's content is currently displayed. Defaults to the `current` step if not
+ *   explicitly set. If `selected` is placed on a step after `current`, the stepper silently corrects it
+ *   to match `current`. When managing state from a framework, always set `selected` explicitly — without
+ *   it the stepper's fallback will reset in-sidebar navigation on every state update.
  *
- * - **`previous`** - Auto-applied by the stepper to all steps before `current`. Do not set manually.
- *   Steps with `previous` are clickable and allow the user to navigate back.
+ * - **`previous`** — Auto-applied by the parent stepper to every step before `current`. Do not set this
+ *   manually. Steps with `previous` are clickable and fire `nys-step-click`.
  *
- * ## Common Patterns
+ * ## `nys-step-click` firing conditions
  *
- * **Initial state:** Set `current` on the first step. `selected` will default to it.
+ * The event fires only when ALL of the following are true:
+ * 1. The step has `previous` or `current` (i.e. it is navigable).
+ * 2. The step does NOT already have `selected` (clicking the already-viewed step is a no-op).
+ *
+ * Steps that are neither `previous` nor `current` (future steps) never fire the event.
+ *
+ * ## `href` and navigation
+ *
+ * If `href` is set, the stepper calls `window.location.href = href` after dispatching `nys-step-click`
+ * — but only if the event was **not canceled**. To handle navigation yourself (SPA routing, fetch, etc.),
+ * always call `e.preventDefault()` in your listener. Omitting `href` entirely is simpler for SPAs.
+ *
+ * ## `onClick` vs `nys-step-click`
+ *
+ * The `onClick` property (a function reference, not a DOM attribute) is called **before** the
+ * `nys-step-click` event is dispatched. Use it for imperative pre-navigation logic. In React, pass it
+ * as the `onClick` prop on `NysStep`.
+ *
+ * ## Accessibility
+ * - The step label renders with `role="button"` and is keyboard-focusable (`tabindex="0"`) for navigable
+ *   steps (`current`, `previous`). Future steps get `tabindex="-1"` and are not reachable by keyboard.
+ * - Enter and Space activate the step (same as click).
+ * - `aria-label` is set to `"{label} Step"` for screen reader announcement.
+ *
+ * ## Common patterns
+ *
+ * **Initial state:** Set `current` on the first step. `selected` defaults to it.
  * ```html
  * <nys-step label="Step 1" current></nys-step>
  * <nys-step label="Step 2"></nys-step>
@@ -34,7 +62,7 @@ import { LitElement } from "lit";
  * <nys-step label="Step 2" current></nys-step>
  * ```
  *
- * **User went back to review step 1 (but progress is still at step 2):**
+ * **User went back to review step 1 (progress still at step 2):**
  * ```html
  * <nys-step label="Step 1" selected></nys-step>
  * <nys-step label="Step 2" current></nys-step>
@@ -43,28 +71,52 @@ import { LitElement } from "lit";
  * @summary Individual step for use within nys-stepper with navigation support.
  * @element nys-step
  *
- * @fires nys-step-click - Fired when a navigable step is clicked. Detail: `{href, label}`. Cancelable.
+ * @fires nys-step-click - Fired when a navigable (`previous` or `current`) non-selected step is clicked
+ *   or activated by keyboard. Detail: `{ href: string, label: string }`. Cancelable — call
+ *   `e.preventDefault()` to suppress `window.location.href` navigation.
  *
- * @example Step with navigation
+ * @example Step with page navigation
  * ```html
  * <nys-step label="Personal Info" href="/step-1"></nys-step>
  * ```
+ *
+ * @example Step with SPA navigation (no href)
+ * ```js
+ * step.addEventListener('nys-step-click', (e) => {
+ *   e.preventDefault(); // no href set, but good practice
+ *   showStepContent(e.detail.label);
+ * });
+ * ```
  */
 export declare class NysStep extends LitElement {
     static styles: import("lit").CSSResult;
-    /** Whether this step is currently being viewed. Set by parent stepper. */
+    /**
+     * Which step is currently being displayed. If not set, defaults to the `current` step.
+     * Setting this on a step after `current` is silently corrected to match `current`.
+     * When controlling state from a framework, always set this explicitly.
+     */
     selected: boolean;
-    /** Marks the furthest reached step. Steps before this are navigable. */
+    /** The furthest step the user has reached (progress boundary). Steps before this are navigable. */
     current: boolean;
     /** Step label text displayed alongside the step number. */
     label: string;
-    /** URL for page navigation when step is clicked. Optional for SPA routing. */
+    /**
+     * URL navigated to when the step is activated, via `window.location.href`.
+     * Navigation is suppressed if the `nys-step-click` listener calls `e.preventDefault()`.
+     * Omit for SPA/framework routing and handle navigation in the event listener instead.
+     */
     href: string;
-    /** Internal: Whether parent stepper's compact view is expanded. */
+    /**
+     * @internal Auto-applied by `nys-stepper` to every step that comes before `current`.
+     * Marks the step as navigable and clickable. Do not set this manually — the parent stepper
+     * adds and removes it on every render based on which step has `current`.
+     */
+    previous: boolean;
+    /** @internal Propagated by the parent stepper. Do not set manually. */
     isCompactExpanded: boolean;
-    /** Custom click handler. Called before `nys-step-click` event. */
+    /** Optional function called before `nys-step-click` is dispatched. Use for pre-navigation logic. */
     onClick?: (e: Event) => void;
-    /** Step number (1-indexed). Auto-assigned by parent stepper. */
+    /** @internal 1-indexed position. Auto-assigned by the parent stepper on first render. Do not set manually. */
     stepNumber: number;
     private _handleActivate;
     private _handleKeydown;

package/dist/packages/nys-stepper/src/nys-stepper.d.ts

@@ -3,15 +3,50 @@ import "./nys-step";
 /**
  * A multi-step progress indicator for forms or wizards. Manages `nys-step` children with selection and navigation.
  *
- * Add `nys-step` elements as children. Mark one step as `current` to indicate progress; previous steps become
- * navigable. Compact view on mobile expands to show all steps. Use `actions` slot for navigation buttons.
- * Do not place the stepper inside a form element.
+ * Add `nys-step` elements as children. Mark one step as `current` to indicate the progress boundary; all steps
+ * before it become navigable. Compact view on mobile expands to show all steps. Use the `actions` slot for
+ * persistent navigation buttons (e.g., Save & Exit). Do not place the stepper inside a `<form>` element —
+ * put form fields in the main content area alongside it.
+ *
+ * ## When to use
+ * - Linear, ordered forms or wizards with more than 2 sections.
+ *
+ * ## When not to use
+ * - Forms with only 1 or 2 sections — use a simpler layout.
+ * - Non-linear forms where sections can be completed in any order.
+ *
+ * ## Compact mode (mobile)
+ * On small screens the stepper collapses to a compact view: step labels are hidden and progress
+ * is shown as a bar indicator with a "Step x of y" counter. Clicking or pressing Enter/Space on
+ * the counter expands the full step list (counter text changes to "Back to Form"). Collapsing
+ * again returns the user to the form view.
+ *
+ * ## actions slot constraints
+ * The `actions` slot must contain exactly one `<div>` as its direct child. That `<div>` may only
+ * contain `<nys-button>` elements — any other element is removed with a console warning.
+ * The stepper automatically forces `size="sm"` on every button in the slot. Buttons with the
+ * `fullWidth` attribute get `flex: 1 1 0` injected so they share available width equally.
+ *
+ * ## Multiple `current` conflict
+ * If more than one `nys-step` has the `current` attribute, only the first one is kept; the rest
+ * are silently removed. Always mark exactly one step as `current`.
+ *
+ * ## id auto-generation
+ * If no `id` is provided, a unique id is generated automatically in the form
+ * `nys-stepper-{n}-{timestamp}`.
+ *
+ * ## Accessibility
+ * - The compact counter is rendered as a `role="button"` with `aria-expanded` and a descriptive
+ *   `aria-label` that announces the current step (e.g., "Expand step navigation. You are on Step 2 of 4").
+ * - Keyboard: Enter or Space toggles the compact view.
+ * - Each `nys-step` label is keyboard-focusable and activatable for navigable steps.
+ * - Visual focus indicators are provided on all interactive elements.
  *
  * @summary Multi-step progress indicator with navigation and mobile-friendly compact view.
  * @element nys-stepper
  *
- * @slot - Default slot for `nys-step` elements.
- * @slot actions - Navigation buttons (e.g., Back, Continue). Must be wrapped in a `<div>`.
+ * @slot - Default slot for `nys-step` elements. Only `nys-step` children are accepted; others are removed.
+ * @slot actions - Persistent navigation buttons. Must contain exactly one `<div>` wrapping only `<nys-button>` elements.
  *
  * @example Basic stepper
  * ```html
@@ -58,18 +93,55 @@ import "./nys-step";
  *   </div>
  * </nys-stepper>
  * ```
+ *
+ * @example SPA / programmatic navigation
+ * Two state variables drive the stepper in any framework or vanilla JS:
+ * - `currentStep` (progress boundary) → set `current` on the matching step
+ * - `viewingStep` (displayed content) → set `selected` on the matching step
+ *
+ * Always set both explicitly. Always call `e.preventDefault()` in the
+ * `nys-step-click` listener to suppress href navigation. Do NOT nest inside a
+ * `<form>` element.
+ * ```js
+ * let currentStep = 0; // furthest reached
+ * let viewingStep = 0; // currently displayed
+ *
+ * function updateStepper(steps) {
+ *   steps.forEach((step, i) => {
+ *     step.toggleAttribute('current', i === currentStep);
+ *     step.toggleAttribute('selected', i === viewingStep);
+ *   });
+ * }
+ *
+ * document.querySelector('nys-stepper').addEventListener('nys-step-click', (e) => {
+ *   e.preventDefault();
+ *   const steps = Array.from(document.querySelectorAll('nys-step'));
+ *   const clicked = e.composedPath().find(el => el.tagName?.toLowerCase() === 'nys-step');
+ *   const index = steps.indexOf(clicked);
+ *   if (index !== -1) { viewingStep = index; updateStepper(steps); }
+ * });
+ *
+ * // Advance to next step (call on form submit / "Continue" click)
+ * function advance(steps) {
+ *   if (currentStep < steps.length - 1) {
+ *     currentStep++;
+ *     viewingStep = currentStep;
+ *     updateStepper(steps);
+ *   }
+ * }
+ * ```
  */
 export declare class NysStepper extends LitElement {
     static styles: import("lit").CSSResult;
-    /** Unique identifier. */
+    /** Unique identifier. Auto-generated as `nys-stepper-{n}-{timestamp}` if not provided. */
     id: string;
     /** Name attribute for form association. */
     name: string;
-    /** Title displayed above the step counter. */
+    /** Title displayed above the step list and compact counter. */
     label: string;
-    /** Progress text (e.g., "Step 2 of 5"). Auto-updated based on selection. */
+    /** Progress text displayed in compact mode (e.g., "Step 2 of 5"). Auto-managed — do not set manually. */
     counterText: string;
-    /** Whether compact mobile view is expanded to show all steps. */
+    /** Whether compact mobile view is expanded to show all steps. Toggled by clicking the counter. */
     isCompactExpanded: boolean;
     private _stepsNumbered;
     constructor();

package/dist/packages/nys-tab/src/nys-tabgroup.d.ts

@@ -101,6 +101,7 @@ export declare class NysTabgroup extends LitElement {
      *   is resized.
      */
     firstUpdated(): void;
+    disconnectedCallback(): void;
     /**
      * Reads the current scroll state of `_tabsEl` and toggles the `is-visible`
      * class on the left and right shadow overlays accordingly.
@@ -153,9 +154,11 @@ export declare class NysTabgroup extends LitElement {
      *
      * Iterates over all assigned elements and moves each `<nys-tab>` into
      * `.nys-tabgroup__tabs` and each `<nys-tabpanel>` into
-     * `.nys-tabgroup__panels`, preserving relative order. After sorting,
-     * calls `_applySelection` using the first element that already has a
-     * `selected` attribute, or index `0` if none is found.
+     * `.nys-tabgroup__panels`. If a panel has an `aria-labelledby` attribute,
+     * it is explicitly paired with the tab it references; otherwise panels are
+     * paired with tabs by index order. After sorting, calls `_applySelection`
+     * using the first element that already has a `selected` attribute, or
+     * index `0` if none is found.
      *
      * @param e - The `Event` fired by the `<slot>` element on slot change.
      * @returns void

package/dist/packages/nys-tooltip/src/nys-tooltip.d.ts

@@ -36,6 +36,7 @@ export declare class NysTooltip extends LitElement {
     private _internallyUpdatingPosition;
     private _hideTimeout;
     private _position;
+    private _resizeObserver;
     /**
      * Preferred position relative to trigger. Auto-adjusts if space is insufficient.
      * @default null (auto-positioned based on available space)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nysds/components",
-  "version": "1.18.0",
+  "version": "1.18.3",
   "description": "New York State's design system and code component library.",
   "type": "module",
   "workspaces": [
@@ -46,6 +46,8 @@
     "release:zip": "npm run build:all && node src/scripts/create-release-zip.js",
     "test": "npx playwright install && wtr --node-resolve",
     "test:build": "npm run build:all && npm run test",
+    "test:compact": "export NYSDS_TEST_OUTPUT=compact && npx playwright install && wtr --node-resolve",
+    "test:ai": "export NYSDS_TEST_OUTPUT=ai && npx playwright install && wtr --node-resolve",
     "storybook": "cross-env NODE_ENV=production storybook dev -p 6006",
     "storybook:build:all": "cross-env NODE_ENV=production npm run build:all && npm run storybook",
     "build-storybook": "npm run build:packages && storybook build",

package/packages/react/NysStep.d.ts

@@ -18,24 +18,22 @@ export interface NysStepProps extends Pick<
   | "onFocus"
   | "onBlur"
 > {
-  /** Whether this step is currently being viewed. Set by parent stepper. */
+  /** Which step is currently being displayed. If not set, defaults to the `current` step.
+Setting this on a step after `current` is silently corrected to match `current`.
+When controlling state from a framework, always set this explicitly. */
   selected?: boolean;
 
-  /** Marks the furthest reached step. Steps before this are navigable. */
+  /** The furthest step the user has reached (progress boundary). Steps before this are navigable. */
   current?: boolean;
 
-  /** Internal: Whether parent stepper's compact view is expanded. */
-  isCompactExpanded?: boolean;
-
   /** Step label text displayed alongside the step number. */
   label?: NysStepElement["label"];
 
-  /** URL for page navigation when step is clicked. Optional for SPA routing. */
+  /** URL navigated to when the step is activated, via `window.location.href`.
+Navigation is suppressed if the `nys-step-click` listener calls `e.preventDefault()`.
+Omit for SPA/framework routing and handle navigation in the event listener instead. */
   href?: NysStepElement["href"];
 
-  /** Step number (1-indexed). Auto-assigned by parent stepper. */
-  stepNumber?: NysStepElement["stepNumber"];
-
   /** A space-separated list of the classes of the element. Classes allows CSS and JavaScript to select and access specific elements via the class selectors or functions like the method `Document.getElementsByClassName()`. */
   className?: string;
 
@@ -57,10 +55,10 @@ export interface NysStepProps extends Pick<
   /** Allows developers to make HTML elements focusable, allow or prevent them from being sequentially focusable (usually with the `Tab` key, hence the name) and determine their relative ordering for sequential focus navigation. */
   tabIndex?: number;
 
-  /** Custom click handler. Called before `nys-step-click` event. */
+  /** Optional function called before `nys-step-click` is dispatched. Use for pre-navigation logic. */
   onClick?: NysStepElement["onClick"];
 
-  /** Fired when a navigable step is clicked. Detail: `{href, label}`. Cancelable. */
+  /** Fired when a navigable (`previous` or `current`) non-selected step is clicked or activated by keyboard. Detail: `{ href: string, label: string }`. Cancelable — call `e.preventDefault()` to suppress `window.location.href` navigation. */
   onNysStepClick?: (event: CustomEvent) => void;
 }
 
@@ -70,6 +68,6 @@ export interface NysStepProps extends Pick<
  *
  *
  * ### **Events:**
- *  - **nys-step-click** - Fired when a navigable step is clicked. Detail: `{href, label}`. Cancelable.
+ *  - **nys-step-click** - Fired when a navigable (`previous` or `current`) non-selected step is clicked or activated by keyboard. Detail: `{ href: string, label: string }`. Cancelable — call `e.preventDefault()` to suppress `window.location.href` navigation.
  */
 export const NysStep: React.ForwardRefExoticComponent<NysStepProps>;

package/packages/react/NysStep.js

@@ -4,16 +4,7 @@ import { useEventListener, useProperties } from "./react-utils.js";
 
 export const NysStep = forwardRef((props, forwardedRef) => {
   const ref = useRef(null);
-  const {
-    selected,
-    current,
-    isCompactExpanded,
-    label,
-    href,
-    stepNumber,
-    onClick,
-    ...filteredProps
-  } = props;
+  const { selected, current, label, href, onClick, ...filteredProps } = props;
 
   /** Event listeners - run once */
   useEventListener(ref, "nys-step-click", props.onNysStepClick);
@@ -35,7 +26,6 @@ export const NysStep = forwardRef((props, forwardedRef) => {
       ...filteredProps,
       label: props.label,
       href: props.href,
-      stepNumber: props.stepNumber,
       class: props.className,
       exportparts: props.exportparts,
       for: props.htmlFor,
@@ -43,7 +33,6 @@ export const NysStep = forwardRef((props, forwardedRef) => {
       tabindex: props.tabIndex,
       selected: props.selected ? true : undefined,
       current: props.current ? true : undefined,
-      isCompactExpanded: props.isCompactExpanded ? true : undefined,
       style: { ...props.style },
     },
     props.children,

package/packages/react/NysStepper.d.ts

@@ -18,19 +18,19 @@ export interface NysStepperProps extends Pick<
   | "onFocus"
   | "onBlur"
 > {
-  /** Whether compact mobile view is expanded to show all steps. */
+  /** Whether compact mobile view is expanded to show all steps. Toggled by clicking the counter. */
   isCompactExpanded?: boolean;
 
-  /** Unique identifier. */
+  /** Unique identifier. Auto-generated as `nys-stepper-{n}-{timestamp}` if not provided. */
   id?: NysStepperElement["id"];
 
   /** Name attribute for form association. */
   name?: NysStepperElement["name"];
 
-  /** Title displayed above the step counter. */
+  /** Title displayed above the step list and compact counter. */
   label?: NysStepperElement["label"];
 
-  /** Progress text (e.g., "Step 2 of 5"). Auto-updated based on selection. */
+  /** Progress text displayed in compact mode (e.g., "Step 2 of 5"). Auto-managed — do not set manually. */
   counterText?: NysStepperElement["counterText"];
 
   /** A space-separated list of the classes of the element. Classes allows CSS and JavaScript to select and access specific elements via the class selectors or functions like the method `Document.getElementsByClassName()`. */
@@ -61,7 +61,7 @@ export interface NysStepperProps extends Pick<
  *
  *
  * ### **Slots:**
- *  - _default_ - Default slot for `nys-step` elements.
- * - **actions** - Navigation buttons (e.g., Back, Continue). Must be wrapped in a `<div>`.
+ *  - _default_ - Default slot for `nys-step` elements. Only `nys-step` children are accepted; others are removed.
+ * - **actions** - Persistent navigation buttons. Must contain exactly one `<div>` wrapping only `<nys-button>` elements.
  */
 export const NysStepper: React.ForwardRefExoticComponent<NysStepperProps>;