@nysds/nys-stepper 1.19.1 → 1.19.2

package/dist/nys-step.d.ts

@@ -0,0 +1,124 @@
+import { LitElement } from "lit";
+/**
+ * A single step within `nys-stepper`. Represents one stage in a multi-step process.
+ *
+ * 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
+ *
+ * Three boolean attributes control step appearance and behavior:
+ *
+ * - **`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.
+ *
+ * - **`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 parent stepper to every step before `current`. Do not set this
+ *   manually. Steps with `previous` are clickable and fire `nys-step-click`.
+ *
+ * ## `nys-step-click` firing conditions
+ *
+ * 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>
+ * ```
+ *
+ * **User completed step 1, now on step 2:**
+ * ```html
+ * <nys-step label="Step 1"></nys-step>
+ * <nys-step label="Step 2" current></nys-step>
+ * ```
+ *
+ * **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>
+ * ```
+ *
+ * @summary Individual step for use within nys-stepper with navigation support.
+ * @element nys-step
+ *
+ * @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 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;
+    /**
+     * 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;
+    /** 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 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 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;
+    /** Optional function called before `nys-step-click` is dispatched. Use for pre-navigation logic. */
+    onClick?: (e: Event) => void;
+    /** @internal 1-indexed position. Auto-assigned by the parent stepper on first render. Do not set manually. */
+    stepNumber: number;
+    private _handleActivate;
+    private _handleKeydown;
+    render(): import("lit-html").TemplateResult<1>;
+}

package/dist/nys-stepper.d.ts

@@ -0,0 +1,158 @@
+import { LitElement } from "lit";
+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 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. 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
+ * <nys-stepper label="Application Progress">
+ *   <nys-step label="Personal Info" current></nys-step>
+ *   <nys-step label="Contact Details"></nys-step>
+ *   <nys-step label="Review"></nys-step>
+ * </nys-stepper>
+ * ```
+ *
+ * @example Grid layout with sidebar placement
+ * Use NYSDS grid utilities to position the stepper as a sidebar alongside form content.
+ * **Layout requirements:**
+ * - Wrap in `nys-grid-container` > `nys-grid-row`
+ * - Use mobile-first classes: `nys-grid-col-12` (stacks on mobile) plus `nys-desktop:nys-grid-col-*`
+ * - Columns must total 12 (e.g., 3+9 or 4+8)
+ * - Recommended: stepper 3-4 cols, content 8-9 cols
+ * ```html
+ * <div class="nys-grid-container">
+ *   <div class="nys-grid-row">
+ *     <nys-stepper label="Application" class="nys-grid-col-12 nys-desktop:nys-grid-col-3">
+ *       <nys-step label="Personal Info"></nys-step>
+ *       <nys-step label="Contact" current></nys-step>
+ *       <nys-step label="Review"></nys-step>
+ *     </nys-stepper>
+ *     <main class="nys-grid-col-12 nys-desktop:nys-grid-col-9" id="main-content">
+ *       <!-- Form content for current step -->
+ *       <nys-textinput label="Email" required></nys-textinput>
+ *       <nys-textinput label="Phone"></nys-textinput>
+ *     </main>
+ *   </div>
+ * </div>
+ * ```
+ *
+ * @example Navigation buttons in actions slot
+ * Add Previous/Next buttons using the actions slot. Wrap buttons in a `<div>`.
+ * ```html
+ * <nys-stepper label="Application">
+ *   <nys-step label="Step 1"></nys-step>
+ *   <nys-step label="Step 2" current></nys-step>
+ *   <nys-step label="Step 3"></nys-step>
+ *   <div slot="actions">
+ *     <nys-button label="Save and Exit" variant="outline" size="sm" fullWidth></nys-button>
+ *   </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. Auto-generated as `nys-stepper-{n}-{timestamp}` if not provided. */
+    id: string;
+    /** Name attribute for form association. */
+    name: string;
+    /** Title displayed above the step list and compact counter. */
+    label: string;
+    /** 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. Toggled by clicking the counter. */
+    isCompactExpanded: boolean;
+    private _stepsNumbered;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private _validateSteps;
+    private _validateButtonSlot;
+    private _onStepClick;
+    private _updateCounter;
+    willUpdate(): void;
+    private _toggleCompact;
+    private _handleCounterKeydown;
+    render(): import("lit-html").TemplateResult<1>;
+}

package/dist/nys-stepper.js

@@ -5,7 +5,7 @@ import { property as i } from "lit/decorators.js";
    * █ █ █  █▄▄▄█  ▀▀▀▄▄  █   █ ▀▀▀▄▄
    * █  ▀█    █    █▄▄▄█  █▄▄▀  █▄▄▄█
    *
-   * Stepper Component v1.19.1
+   * Stepper Component v1.19.2
    * Part of the New York State Design System
    * Repository: https://github.com/its-hcd/nysds
    * License: MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nysds/nys-stepper",
-  "version": "1.19.1",
+  "version": "1.19.2",
   "description": "The Stepper component from the NYS Design System.",
   "module": "dist/nys-stepper.js",
   "types": "dist/index.d.ts",
@@ -23,7 +23,7 @@
     "lit-analyze": "lit-analyzer '**/*.ts'"
   },
   "dependencies": {
-    "@nysds/nys-button": "^1.19.1"
+    "@nysds/nys-button": "^1.19.2"
   },
   "devDependencies": {
     "lit": "^3.3.1",
@@ -40,5 +40,6 @@
     "forms"
   ],
   "author": "New York State Design System Team",
-  "license": "MIT"
+  "license": "MIT",
+  "sideEffects": true
 }