@nysds/components 1.13.0 → 1.13.1

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

@@ -1,17 +1,39 @@
 import { LitElement } from "lit";
 /**
- * `<nys-icon>` renders an SVG icon from the internal icon library.
+ * Renders SVG icons from the NYSDS icon library (Material Symbols). Decorative by default (`aria-hidden`).
  *
- * Icons are inline SVGs and support sizing, rotation, flipping, color,
- * and accessibility labeling.
+ * 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.
+ *
+ * @summary SVG icon from Material Symbols library with size, rotation, and color options.
+ * @element nys-icon
+ *
+ * @example Basic icon
+ * ```html
+ * <nys-icon name="check_circle" 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 {
     static styles: import("lit").CSSResult;
+    /** Icon name from Material Symbols library. Required. */
     name: string;
+    /** Accessible label. When set, removes `aria-hidden` and adds `aria-label` to the SVG. */
     ariaLabel: string;
+    /** Rotation in degrees. Applied via CSS `rotate`. */
     rotate: string;
+    /** Flip direction: `horizontal`, `vertical`, or empty for none. */
     flip: string;
+    /** Icon color. Accepts any CSS color value. Defaults to `currentcolor`. */
     color: string;
+    /**
+     * Icon size. Semantic sizes: `xs`-`5xl`. Pixel sizes: `12`-`50`.
+     * @default "md"
+     */
     size: "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "5xl" | "12" | "14" | "16" | "18" | "20" | "24" | "32" | "40" | "50";
     /**
      * Retrieves the SVG element for the given icon name and applies

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

@@ -1,16 +1,28 @@
 import { LitElement } from "lit";
 /**
- * THIS IS A PRIVATE COMPONENT!
- * `NysLabel` is a component for rendering form labels with optional
- * descriptions, flags (required/optional), and tooltips.
+ * **Internal component.** Renders form labels with description, required/optional flag, and tooltip.
+ *
+ * Used internally by form components (textinput, select, checkbox, etc.). Not intended for direct use.
+ * Handles label association via `for`, displays asterisk for required fields, and integrates tooltips.
+ *
+ * @summary Internal label component for form fields with flag and tooltip support.
+ * @element nys-label
+ *
+ * @slot description - Custom HTML description content below the label.
  */
 export declare class NysLabel extends LitElement {
     static styles: import("lit").CSSResult;
+    /** ID of the form element this label is associated with. */
     for: string;
+    /** Label text displayed above the form field. */
     label: string;
+    /** Helper text displayed below the label. */
     description: string;
+    /** Flag type: `required` shows asterisk, `optional` shows "(Optional)". */
     flag: string;
+    /** Adjusts colors for dark backgrounds. */
     inverted: boolean;
+    /** Tooltip text shown on hover/focus of info icon next to label. */
     get tooltip(): string;
     set tooltip(value: string);
     private _tooltip;

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

@@ -1,23 +1,46 @@
 import { LitElement } from "lit";
 /**
- * `<nys-modal>` renders an accessible modal dialog.
+ * An accessible modal dialog with focus trapping, keyboard navigation, and scroll management.
  *
- * Supports headings, optional subheading, body content, and action buttons.
- * Manages focus trapping, escape key handling, and body scroll locking.
+ * Set `open` to show the modal. Content goes in the default slot; action buttons in the `actions` slot.
+ * Dismisses via close button or Escape key unless `mandatory` is set. Focus returns to trigger on close.
  *
- * @slot - Modal body content
- * @slot actions - Action buttons shown in the footer
+ * @summary Accessible modal dialog with focus trap, keyboard support, and action slots.
+ * @element nys-modal
  *
- * @fires nys-open - Emitted when the modal opens
- * @fires nys-close - Emitted when the modal closes
+ * @slot - Default slot for body content.
+ * @slot actions - Action buttons displayed in footer. Buttons auto-resize on mobile.
+ *
+ * @fires nys-open - Fired when modal opens. Detail: `{id}`.
+ * @fires nys-close - Fired when modal closes. Detail: `{id}`.
+ *
+ * @example Basic modal
+ * ```html
+ * <nys-modal id="confirm-modal" heading="Confirm action" open>
+ *   <p>Are you sure you want to proceed?</p>
+ *   <div slot="actions">
+ *     <nys-button label="Cancel" variant="outline"></nys-button>
+ *     <nys-button label="Confirm" variant="filled"></nys-button>
+ *   </div>
+ * </nys-modal>
+ * ```
  */
 export declare class NysModal extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Unique identifier. Auto-generated if not provided. */
     id: string;
+    /** Modal heading text. Required for accessibility. */
     heading: string;
+    /** Secondary heading below the main heading. */
     subheading: string;
+    /** Controls modal visibility. Set to `true` to show. */
     open: boolean;
+    /** Prevents dismissal via close button or Escape key. User must take an action. */
     mandatory: boolean;
+    /**
+     * Modal width: `sm` (400px), `md` (600px), or `lg` (800px).
+     * @default "md"
+     */
     width: "sm" | "md" | "lg";
     private _actionButtonSlot;
     private _prevFocusedElement;

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

@@ -1,19 +1,31 @@
 import { LitElement, TemplateResult } from "lit";
 /**
- * `<nys-pagination>` renders page navigation controls.
+ * Page navigation with Previous/Next buttons and numbered page links. Auto-collapses with ellipses for many pages.
  *
- * Displays previous and next buttons, page numbers, and ellipses
- * when pages are skipped. Handles page bounds automatically.
+ * Set `totalPages` and `currentPage` to control state. Listen to `nys-change` for page selection.
+ * Hidden automatically when `totalPages` is 1. Responsive: shows compact controls on mobile.
  *
- * @fires nys-change - Fired when the page changes
- *   detail: { page: number }
+ * @summary Page navigation with numbered links, prev/next buttons, and responsive layout.
+ * @element nys-pagination
+ *
+ * @fires nys-change - Fired when page changes. Detail: `{page}`.
+ *
+ * @example Basic pagination
+ * ```html
+ * <nys-pagination currentPage="1" totalPages="10"></nys-pagination>
+ * ```
  */
 export declare class NysPagination extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Unique identifier. Auto-generated if not provided. */
     id: string;
+    /** Name attribute for form association. */
     name: string;
+    /** Currently active page (1-indexed). Clamped to valid range. */
     currentPage: number;
+    /** Total number of pages. Must be at least 1. */
     totalPages: number;
+    /** Internal state for layout adjustments near the end. */
     _twoBeforeLast: boolean;
     /**
      * Lifecycle Methods

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

@@ -1,36 +1,57 @@
 import { LitElement } from "lit";
 import "./nys-radiogroup";
 /**
- * `<nys-radiobutton>` represents a single radio button for use in a `<nys-radiogroup>`.
+ * A radio button for single selection within a `nys-radiogroup`. Only one radio with the same `name` can be selected.
  *
- * Features:
- * - Single selection per group
- * - Supports labels, descriptions, tile layout, inverted style, and size variants
- * - Integrates with forms and dispatches `nys-change` events on selection
+ * Use within `nys-radiogroup` for 2-6 mutually exclusive options. For 7+ options, use `nys-select`.
+ * For multiple selections, use `nys-checkbox`.
  *
- * @slot description - Optional description text announced to screen readers
+ * @summary Radio button for single selection from mutually exclusive options.
+ * @element nys-radiobutton
  *
- * @fires nys-change - Fired when the radio is selected or deselected
- *   detail: { id: string, checked: boolean, name: string, value: string }
- * @fires nys-focus - Fired when the radio gains focus
- * @fires nys-blur - Fired when the radio loses focus
+ * @slot description - Custom HTML description content.
+ *
+ * @fires nys-change - Fired when selection changes. Detail: `{id, checked, name, value}`.
+ * @fires nys-focus - Fired when radio gains focus.
+ * @fires nys-blur - Fired when radio loses focus.
+ *
+ * @example Radio group
+ * ```html
+ * <nys-radiogroup label="Select borough" required>
+ *   <nys-radiobutton name="borough" value="bronx" label="The Bronx"></nys-radiobutton>
+ *   <nys-radiobutton name="borough" value="brooklyn" label="Brooklyn"></nys-radiobutton>
+ * </nys-radiogroup>
+ * ```
  */
 export declare class NysRadiobutton extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Whether this radio is selected. Only one per group can be checked. */
     checked: boolean;
+    /** Prevents interaction. */
     disabled: boolean;
+    /** Marks group as required. Set on radiogroup, not individual radios. */
     required: boolean;
+    /** Visible label text. Required for accessibility. */
     label: string;
+    /** Helper text below label. Use slot for custom HTML. */
     description: string;
+    /** Unique identifier. Auto-generated if not provided. */
     id: string;
+    /** Group name. Radios with same name are mutually exclusive. */
     name: string;
+    /** Value submitted when this radio is selected. */
     value: string;
+    /** Adjusts colors for dark backgrounds. */
     inverted: boolean;
+    /** Form `id` to associate with. */
     form: string | null;
+    /**
+     * Radio size: `sm` (24px) or `md` (32px, default).
+     * @default "md"
+     */
     size: "sm" | "md";
+    /** Renders as tile with larger clickable area. */
     tile: boolean;
-    getInputElement(): Promise<HTMLInputElement | null>;
-    formResetUpdate(): void;
     static buttonGroup: Record<string, NysRadiobutton>;
     /**
      * Lifecycle methods
@@ -43,7 +64,8 @@ export declare class NysRadiobutton extends LitElement {
      * Functions
      * --------------------------------------------------------------------------
      */
-    checkValidity(): boolean;
+    getInputElement(): Promise<HTMLInputElement | null>;
+    formResetUpdate(): void;
     /**
      * Event Handlers
      * --------------------------------------------------------------------------

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

@@ -1,31 +1,56 @@
 import { LitElement } from "lit";
 /**
- * `<nys-radiogroup>` groups `<nys-radiobutton>` elements into a single
- * selectable control.
+ * A container for grouping `nys-radiobutton` elements as a single form control with enforced single selection.
+ * Handles keyboard navigation (arrow keys), validation, required constraints, and form integration.
  *
- * Supports keyboard navigation, validation, and native form submission
- * through ElementInternals.
+ * Use to let users select exactly one option from 2-6 choices. Apply `tile`, `size`, and `inverted` to the group
+ * and all children inherit these styles automatically. For 7+ options, use `nys-select`.
  *
- * @slot default - One or more `<nys-radiobutton>` elements
- * @slot description - Optional descriptive text announced to screen readers
+ * @summary Container for grouping radio buttons as a single form control.
+ * @element nys-radiogroup
  *
- * @fires nys-change - Fired when selection changes
- *   detail: { name: string; value: string }
+ * @slot - Default slot for `nys-radiobutton` elements.
+ * @slot description - Custom HTML description content.
+ *
+ * @example Basic radio group
+ * ```html
+ * <nys-radiogroup label="Select borough" required>
+ *   <nys-radiobutton name="borough" value="bronx" label="The Bronx"></nys-radiobutton>
+ *   <nys-radiobutton name="borough" value="brooklyn" label="Brooklyn"></nys-radiobutton>
+ *   <nys-radiobutton name="borough" value="manhattan" label="Manhattan"></nys-radiobutton>
+ * </nys-radiogroup>
+ * ```
  */
 export declare class NysRadiogroup extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Unique identifier. Auto-generated if not provided. */
     id: string;
+    /** Name for form submission. Auto-populated from child radiobuttons. */
     name: string;
+    /** Requires a selection before form submission. */
     required: boolean;
+    /** Shows "Optional" flag. */
     optional: boolean;
+    /** Shows error message when true. */
     showError: boolean;
+    /** Error message text. Shown only when `showError` is true. */
     errorMessage: string;
+    /** Visible label text for the group. */
     label: string;
+    /** Helper text below label. Use slot for custom HTML. */
     description: string;
+    /** Renders all radiobuttons as tiles with larger clickable area. */
     tile: boolean;
+    /** Tooltip text shown on hover/focus of info icon. */
     tooltip: string;
+    /** Adjusts colors for dark backgrounds. Applied to all children. */
     inverted: boolean;
+    /** Form `id` to associate with. Applied to all children. */
     form: string | null;
+    /**
+     * Radio size for all children: `sm` (24px) or `md` (32px, default).
+     * @default "md"
+     */
     size: "sm" | "md";
     private selectedValue;
     private _slottedDescriptionText;

package/dist/packages/nys-select/src/nys-option.d.ts

@@ -1,9 +1,33 @@
 import { LitElement } from "lit";
+/**
+ * An option item for use within `nys-select`. Wraps a native `<option>` element.
+ *
+ * Place inside `nys-select`. Set `value` for form submission and `label` for display text.
+ * Alternatively, slot text content which auto-populates the label.
+ *
+ * @summary Option item for nys-select dropdown.
+ * @element nys-option
+ *
+ * @slot - Option label text. Auto-populates the `label` prop if provided.
+ *
+ * @example Basic options
+ * ```html
+ * <nys-select>
+ *   <nys-option value="ny">New York</nys-option>
+ *   <nys-option value="ca" disabled>California</nys-option>
+ * </nys-select>
+ * ```
+ */
 export declare class NysOption extends LitElement {
+    /** Prevents selection of this option. */
     disabled: boolean;
+    /** Pre-selects this option. */
     selected: boolean;
+    /** Value submitted when this option is selected. */
     value: string;
+    /** Display text for the option. Auto-populated from slot content if not set. */
     label: string;
+    /** Hides the option from the dropdown list. */
     hidden: boolean;
     firstUpdated(): void;
     render(): import("lit-html").TemplateResult<1>;

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

@@ -1,36 +1,72 @@
 import { LitElement } from "lit";
 /**
- * `<nys-select>` is a custom select/dropdown component.
+ * A dropdown for selecting a single option from a list. Supports native `<option>` and `<optgroup>` elements.
+ * Form-associated with validation via ElementInternals.
  *
- * Features:
- * - Supports slotted `<nys-option>` elements, native `<option>` and `<optgroup>`
- * - Integrates with forms via ElementInternals
- * - Handles validation, error messages, and required/optional states
- * - Inverted style and width variants supported
+ * Use when users must choose one option from 7+ items. For fewer options, consider `nys-radiobutton`.
+ * For multiple selections, use `nys-checkbox` group instead.
  *
- * @slot description - Optional description text announced to screen readers
- * @slot default - Options (<nys-option>, <option>, <optgroup>) to populate the dropdown
+ * @summary Dropdown select for choosing one option from a list.
+ * @element nys-select
  *
- * @fires nys-change - Fired when the selected value changes
- *   detail: { id: string, value: string }
- * @fires nys-focus - Fired when the select gains focus
- * @fires nys-blur - Fired when the select loses focus
+ * @slot - Default slot for `<option>` and `<optgroup>` elements.
+ * @slot description - Custom HTML description content below the label.
+ *
+ * @fires nys-change - Fired when selection changes. Detail: `{id, value}`.
+ * @fires nys-focus - Fired when select gains focus.
+ * @fires nys-blur - Fired when select loses focus. Triggers validation.
+ *
+ * @example Basic select
+ * ```html
+ * <nys-select label="Select borough">
+ *   <option value="bronx">The Bronx</option>
+ *   <option value="brooklyn">Brooklyn</option>
+ *   <option value="manhattan">Manhattan</option>
+ * </nys-select>
+ * ```
+ *
+ * @example With option groups
+ * ```html
+ * <nys-select label="Select service">
+ *   <optgroup label="Transportation">
+ *     <option value="mta">MTA</option>
+ *     <option value="dmv">DMV</option>
+ *   </optgroup>
+ * </nys-select>
+ * ```
  */
 export declare class NysSelect extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Unique identifier. Auto-generated if not provided. */
     id: string;
+    /** Name for form submission. */
     name: string;
+    /** Visible label text. Required for accessibility. */
     label: string;
+    /** Helper text below label. Use slot for custom HTML. */
     description: string;
+    /** Currently selected option value. */
     value: string;
+    /** Prevents interaction. */
     disabled: boolean;
+    /** Marks as required. Shows "Required" flag and validates on blur. */
     required: boolean;
+    /** Shows "Optional" flag. Use when most fields are required. */
     optional: boolean;
+    /** Tooltip text shown on hover/focus of info icon. */
     tooltip: string;
+    /** Form `id` to associate with when select is outside form element. */
     form: string | null;
+    /** Adjusts colors for dark backgrounds. */
     inverted: boolean;
+    /** Shows error message when true. Set by validation or manually. */
     showError: boolean;
+    /** Error message text. Shown only when `showError` is true. */
     errorMessage: string;
+    /**
+     * Select width: `sm` (88px), `md` (200px), `lg` (384px), `full` (100%, default).
+     * @default "full"
+     */
     width: "sm" | "md" | "lg" | "full";
     private _originalErrorMessage;
     private _hasUserInteracted;

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

@@ -1,16 +1,29 @@
 import { LitElement } from "lit";
 /**
- * `<nys-skipnav>` provides an accessible skip navigation link for keyboard
- * and screen reader users to jump directly to the main content of a page.
+ * An accessible "Skip to main content" link for keyboard and screen reader users. Visually hidden until focused.
  *
- * Features:
- * - Default target is `#main-content` if `href` is not provided
- * - Link becomes visible on focus and hides on blur
- * - Ensures the target element is focusable for accessibility
+ * Place as the first focusable element in the document. Links to `#main-content` by default, or specify `href`
+ * for a custom target. The target element receives focus when activated for proper screen reader announcement.
+ *
+ * @summary Skip navigation link for keyboard accessibility. Hidden until focused.
+ * @element nys-skipnav
+ *
+ * @example Default skip link
+ * ```html
+ * <nys-skipnav></nys-skipnav>
+ * <main id="main-content">...</main>
+ * ```
+ *
+ * @example Custom target
+ * ```html
+ * <nys-skipnav href="#content-area"></nys-skipnav>
+ * ```
  */
 export declare class NysSkipnav extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Unique identifier. Auto-generated if not provided. */
     id: string;
+    /** Target element ID (with `#`). Defaults to `#main-content`. */
     href: string;
     constructor();
     connectedCallback(): void;

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

@@ -0,0 +1,2 @@
+export * from "./nys-stepper";
+export * from "./nys-step";

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

@@ -0,0 +1,37 @@
+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.
+ *
+ * @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.
+ *
+ * @example Step with navigation
+ * ```html
+ * <nys-step label="Personal Info" href="/step-1"></nys-step>
+ * ```
+ */
+export declare class NysStep extends LitElement {
+    static styles: import("lit").CSSResult;
+    /** Whether this step is currently being viewed. Set by parent stepper. */
+    selected: boolean;
+    /** Marks the furthest reached step. 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. */
+    href: string;
+    /** Internal: Whether parent stepper's compact view is expanded. */
+    isCompactExpanded: boolean;
+    /** Custom click handler. Called before `nys-step-click` event. */
+    onClick?: (e: Event) => void;
+    /** Step number (1-indexed). Auto-assigned by parent stepper. */
+    stepNumber: number;
+    private _handleActivate;
+    private _handleKeydown;
+    render(): import("lit-html").TemplateResult<1>;
+}

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

@@ -0,0 +1,48 @@
+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 progress; previous steps become
+ * navigable. Compact view on mobile expands to show all steps. Use `actions` slot for navigation buttons.
+ *
+ * @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>`.
+ *
+ * @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>
+ * ```
+ */
+export declare class NysStepper extends LitElement {
+    static styles: import("lit").CSSResult;
+    /** Unique identifier. */
+    id: string;
+    /** Name attribute for form association. */
+    name: string;
+    /** Title displayed above the step counter. */
+    label: string;
+    /** Progress text (e.g., "Step 2 of 5"). Auto-updated based on selection. */
+    counterText: string;
+    /** Whether compact mobile view is expanded to show all steps. */
+    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/packages/nys-stepper/src/nys-stepper.figma.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -26,7 +26,8 @@ export declare class NysTable extends LitElement {
     /******************** Functions ********************/
     firstUpdated(): void;
     _handleSlotChange(): void;
-    _normalizeTable(table: HTMLTableElement): void;
+    _normalizeTableDOM(table: HTMLTableElement): void;
+    willUpdate(): void;
     _addSortIcons(table: HTMLTableElement): void;
     _updateSortIcons(table: HTMLTableElement): void;
     _onSortClick(columnIndex: number, table: HTMLTableElement): void;