@nysds/components 1.18.1 → 1.19.0

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

@@ -160,6 +160,8 @@ export declare class NysButton extends LitElement {
      */
     target: "_self" | "_blank" | "_parent" | "_top" | "framename";
     private _internals;
+    private _hasPrefixSlot;
+    private _hasSuffixSlot;
     /**
      * Lifecycle methods
      * --------------------------------------------------------------------------
@@ -172,6 +174,8 @@ export declare class NysButton extends LitElement {
      * --------------------------------------------------------------------------
      */
     private _generateUniqueId;
+    private _onPrefixSlotChange;
+    private _onSuffixSlotChange;
     private _manageFormAction;
     /**
      * Event Handlers
@@ -181,6 +185,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-divider/src/nys-divider.d.ts

@@ -18,6 +18,8 @@ export declare class NysDivider extends LitElement {
     static styles: import("lit").CSSResult;
     /** Adjusts colors for dark backgrounds. */
     inverted: boolean;
+    /** If true, the divider will use a lighter color. */
+    subtle: boolean;
     constructor();
     connectedCallback(): void;
     /**

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-icon/src/icon-cache.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Icon Cache
+ *
+ * Shared SVG fetch and parse cache. Deduplicates concurrent requests
+ * for the same icon URL. Each consumer gets a cloned SVGElement via
+ * `cloneNode(true)` so DOM nodes are never shared.
+ */
+/** Fetch and parse an SVG from a URL. Returns a cloned SVGElement (safe for multiple consumers). */
+export declare function fetchIcon(url: string): Promise<SVGElement>;
+/** Clear one or all entries from the cache. */
+export declare function clearIconCache(url?: string): void;

package/dist/packages/nys-icon/src/icon-library-registry.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Icon Library Registry
+ *
+ * Global registry for icon libraries. The "default" library resolves
+ * NYSDS icons from colocated SVG files extracted at build time.
+ * Custom libraries (Font Awesome, Material Icons, etc.) can be
+ * registered at runtime via `registerIconLibrary()`.
+ *
+ * The registry and watcher maps are stored on `window` so that even
+ * when bundlers (Storybook Vite, etc.) create duplicate module
+ * instances, every copy shares a single source of truth.
+ */
+export interface IconLibrary {
+    /** Given an icon name, return the URL to its SVG file. Return undefined if not found. */
+    resolver: (name: string) => string | undefined;
+    /** Optional post-fetch transform applied to the parsed SVGElement. */
+    mutator?: (svg: SVGElement) => void;
+}
+export interface NysIconWatcher {
+    redraw(): void;
+}
+interface NysIconGlobals {
+    __nysIconRegistry: Map<string, IconLibrary>;
+    __nysIconWatchers: Map<string, Set<NysIconWatcher>>;
+}
+declare global {
+    interface Window extends NysIconGlobals {
+    }
+}
+/** Register or replace a named icon library. All watching icons using this library will redraw.
+ * @example Register a Font Awesome library with a custom resolver:
+ * ```ts
+ * registerIconLibrary("fa", {
+ *   resolver: (name) => `https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/svg/${name}.svg`
+ * });
+ * ```
+ */
+export declare function registerIconLibrary(name: string, library: IconLibrary): void;
+/** Remove a registered icon library. All watching icons using this library will redraw. */
+export declare function unregisterIconLibrary(name: string): void;
+/** Get a registered icon library by name. */
+export declare function getIconLibrary(name: string): IconLibrary | undefined;
+/** Subscribe an icon instance to library change notifications. */
+export declare function watchIconLibrary(name: string, watcher: NysIconWatcher): void;
+/** Unsubscribe an icon instance from library change notifications. */
+export declare function unwatchIconLibrary(name: string, watcher: NysIconWatcher): void;
+export {};

package/dist/packages/nys-icon/src/index.d.ts

@@ -1 +1,4 @@
 export * from "./nys-icon";
+export { registerIconLibrary, unregisterIconLibrary, } from "./icon-library-registry";
+export type { IconLibrary } from "./icon-library-registry";
+export { clearIconCache } from "./icon-cache";

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

@@ -1,27 +1,39 @@
 import { LitElement } from "lit";
+import { NysIconWatcher } from "./icon-library-registry";
 /**
- * Renders SVG icons from the NYSDS icon library (Material Symbols). Decorative by default (`aria-hidden`).
+ * Renders SVG icons from a registered icon library. The built-in NYSDS icon
+ * library (Material Symbols) is the default. Custom libraries (Font Awesome,
+ * Material Icons, etc.) can be registered via `registerIconLibrary()`.
  *
- * Pass `name` to select an icon from the library. Use `ariaLabel` to make the icon accessible
- * (removes `aria-hidden`). Supports size presets, rotation, flipping, and custom colors.
+ * Pass `name` to select an icon. Use `library` to choose a registered library
+ * (defaults to `"default"` for NYSDS icons). Use `ariaLabel` to make the icon
+ * accessible (removes `aria-hidden`). Supports size presets, rotation,
+ * flipping, and custom colors.
  *
- * @summary SVG icon from Material Symbols library with size, rotation, and color options.
+ * @summary SVG icon with swappable library support, size, rotation, and color options.
  * @element nys-icon
  *
- * @example Basic icon
+ * @example Basic icon (default NYSDS library)
  * ```html
  * <nys-icon name="check_circle" size="lg"></nys-icon>
  * ```
  *
+ * @example Font Awesome icon
+ * ```html
+ * <nys-icon name="house" library="fa" size="lg"></nys-icon>
+ * ```
+ *
  * @example Accessible icon with label
  * ```html
  * <nys-icon name="warning" ariaLabel="Warning" color="var(--nys-color-warning)"></nys-icon>
  * ```
  */
-export declare class NysIcon extends LitElement {
+export declare class NysIcon extends LitElement implements NysIconWatcher {
     static styles: import("lit").CSSResult;
-    /** Icon name from Material Symbols library. Required. */
+    /** Icon name to resolve from the selected library. Required. */
     name: string;
+    /** Which registered icon library to use. Defaults to the built-in NYSDS library. */
+    library: string;
     /** Accessible label. When set, removes `aria-hidden` and adds `aria-label` to the SVG. */
     ariaLabel: string;
     /** Rotation in degrees. Applied via CSS `rotate`. */
@@ -35,11 +47,28 @@ export declare class NysIcon extends LitElement {
      * @default "md"
      */
     size: "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "5xl" | "12" | "14" | "16" | "18" | "20" | "24" | "32" | "40" | "50";
+    private _svg;
+    /** Monotonically increasing token so stale async fetches are discarded. */
+    private _loadSeq;
+    /** Promise for the in-flight icon load. */
+    private _loadPromise;
+    /** Resolves when the current icon load (if any) is complete. */
+    get updateComplete(): Promise<boolean>;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /** Called by the icon library registry when the current library changes. */
+    redraw(): void;
     /**
-     * Retrieves the SVG element for the given icon name and applies
-     * accessibility, rotation, flip, color, and size classes.
-     * @returns SVGElement | null
+     * Lit calls firstUpdated after the first render, once all reactive
+     * properties (including those set from the template) are resolved.
+     * This guarantees the initial _loadIcon runs with the correct name
+     * and library values, avoiding the race where updated() might not
+     * fire for properties that equal their defaults.
      */
-    private getIcon;
+    firstUpdated(): void;
+    private static _validName;
+    updated(changedProps: Map<string, unknown>): void;
+    private _loadIcon;
+    private _applyAttributes;
     render(): import("lit-html").TemplateResult<1> | null;
 }

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-radiobutton/src/nys-radiobutton.d.ts

@@ -1,12 +1,11 @@
 import { LitElement } from "lit";
-import "./nys-radiogroup";
 /**
  * A radio button for single selection within a `nys-radiogroup`. Only one radio with the same `name` can be selected.
  *
  * Use within `nys-radiogroup` for 2-6 mutually exclusive options. For 7+ options, use `nys-select`.
  * For multiple selections, use `nys-checkbox`.
  *
- * @summary Radio button for single selection from mutually exclusive options.
+ * @summary Radio button for single selection from mutually exclusive options. This is a READONLY data component.
  * @element nys-radiobutton
  *
  * @slot description - Custom HTML description content.
@@ -26,14 +25,6 @@ import "./nys-radiogroup";
  */
 export declare class NysRadiobutton extends LitElement {
     static styles: import("lit").CSSResult;
-    static shadowRootOptions: {
-        delegatesFocus: boolean;
-        clonable?: boolean;
-        customElementRegistry?: CustomElementRegistry;
-        mode: ShadowRootMode;
-        serializable?: boolean;
-        slotAssignment?: SlotAssignmentMode;
-    };
     /** Whether this radio is selected. Only one per group can be checked. */
     checked: boolean;
     /** Prevents interaction. */
@@ -61,38 +52,10 @@ export declare class NysRadiobutton extends LitElement {
     tile: boolean;
     other: boolean;
     showOtherError: boolean;
-    private isMobile;
-    private _hasUserInteracted;
-    static buttonGroup: Record<string, NysRadiobutton>;
     /**
      * Lifecycle methods
      * --------------------------------------------------------------------------
      */
     connectedCallback(): void;
-    disconnectedCallback(): void;
-    updated(changedProperties: Map<string | number | symbol, unknown>): void;
-    /**
-     * Functions
-     * --------------------------------------------------------------------------
-     */
-    getInputElement(): Promise<HTMLInputElement | null>;
-    formResetUpdate(): void;
-    private _handleResize;
-    private _clearOtherState;
-    private _dispatchClearErrorEvent;
-    /**
-     * Event Handlers
-     * --------------------------------------------------------------------------
-     */
-    private _emitChangeEvent;
-    private _emitOtherInputEvent;
-    private _handleChange;
-    private _handleFocus;
-    private _handleBlur;
-    private _callInputHandling;
-    private _handleTextInput;
-    private _handleTextInputBlur;
-    private _validateOtherAndEmitError;
-    private _handleOtherKeydown;
     render(): import("lit-html").TemplateResult<1>;
 }

package/dist/packages/nys-radiobutton/src/nys-radiogroup.d.ts

@@ -58,8 +58,14 @@ export declare class NysRadiogroup extends LitElement {
      * @default "md"
      */
     size: "sm" | "md";
+    _showOtherError: boolean;
     private selectedValue;
     private _slottedDescriptionText;
+    private _radios;
+    private _mobileQuery;
+    private isMobile;
+    private _hasUserInteracted;
+    private _childObserver?;
     private _internals;
     /**
      * Lifecycle methods
@@ -88,20 +94,24 @@ export declare class NysRadiogroup extends LitElement {
      * Functions
      * --------------------------------------------------------------------------
      */
+    private _handleMobileQuery;
+    private _handleSlotChange;
     private _initializeChildAttributes;
     private _updateRadioButtonsSize;
-    private _updateRadioButtonsTile;
-    private _updateRadioButtonsShowError;
-    private _updateRadioButtonsForm;
+    private _selectRadio;
     private _getSlotDescriptionForAria;
     /**
      * Event Handlers
      * --------------------------------------------------------------------------
      */
-    private _handleRadioButtonChange;
     private _handleInvalid;
-    private _handleChildError;
-    private _handleChildErrorClear;
-    private _handleOtherInput;
+    private _handleTextInput;
+    private _handleTextInputBlur;
+    private _validateOtherAndEmitError;
+    private _handleOtherKeydown;
+    private _handleGroupFocusout;
+    private _handleRadiobtnClick;
+    private _handleRadiobtnFocus;
+    private _handleRadiobtnBlur;
     render(): import("lit-html").TemplateResult<1>;
 }

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;