@nysds/components 1.12.0 → 1.13.1

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,105 @@
 import { LitElement } from "lit";
+/**
+ * A dropdown for selecting a single option from a list. Supports native `<option>` and `<optgroup>` elements.
+ * Form-associated with validation via ElementInternals.
+ *
+ * Use when users must choose one option from 7+ items. For fewer options, consider `nys-radiobutton`.
+ * For multiple selections, use `nys-checkbox` group instead.
+ *
+ * @summary Dropdown select for choosing one option from a list.
+ * @element nys-select
+ *
+ * @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;
     private _internals;
+    /**
+     * Lifecycle methods
+     * --------------------------------------------------------------------------
+     */
     static formAssociated: boolean;
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
     firstUpdated(): void;
-    formResetCallback(): void;
     private _handleSlotChange;
+    /**
+     * Form Integration
+     * --------------------------------------------------------------------------
+     */
     private _setValue;
     private _manageRequire;
     private _setValidityMessage;
     private _validate;
+    formResetCallback(): void;
+    /**
+     * Functions
+     * --------------------------------------------------------------------------
+     */
     checkValidity(): boolean;
     private _handleInvalid;
+    /**
+     * Event Handlers
+     * --------------------------------------------------------------------------
+     */
     private _handleChange;
     private _handleFocus;
     private _handleBlur;

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

@@ -1,10 +1,36 @@
 import { LitElement } from "lit";
+/**
+ * An accessible "Skip to main content" link for keyboard and screen reader users. Visually hidden until focused.
+ *
+ * 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;
+    /**
+     * Event Handlers
+     * --------------------------------------------------------------------------
+     */
     private _handleFocus;
     private _handleBlur;
     private _handleClick;

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/index.d.ts

@@ -0,0 +1 @@
+export * from "./nys-table";

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

@@ -0,0 +1,39 @@
+import { LitElement } from "lit";
+/**
+ * `<nys-table>` is a responsive table component that can display native HTML tables,
+ * supports striped and bordered styling, sortable columns, and CSV download.
+ *
+ * @slot - Accepts a `<table>` element. Only the first table is rendered.
+ *
+ * @fires nys-click - Fired when the download button or sortable headers are clicked.
+ *
+ * @method downloadFile - Triggers download of the CSV file if `download` is set.
+ */
+export declare class NysTable extends LitElement {
+    static styles: import("lit").CSSResult;
+    id: string;
+    name: string;
+    striped: boolean;
+    sortable: boolean;
+    bordered: boolean;
+    download: string;
+    private _sortColumn;
+    private _sortDirection;
+    private _captionText;
+    /**************** Lifecycle Methods ****************/
+    constructor();
+    connectedCallback(): void;
+    /******************** Functions ********************/
+    firstUpdated(): void;
+    _handleSlotChange(): void;
+    _normalizeTableDOM(table: HTMLTableElement): void;
+    willUpdate(): void;
+    _addSortIcons(table: HTMLTableElement): void;
+    _updateSortIcons(table: HTMLTableElement): void;
+    _onSortClick(columnIndex: number, table: HTMLTableElement): void;
+    _sortTable(table: HTMLTableElement, columnIndex: number, direction: "asc" | "desc"): void;
+    _updateSortedColumnStyles(table: HTMLTableElement): void;
+    downloadFile(): void;
+    /****************** Event Handlers ******************/
+    render(): import("lit-html").TemplateResult<1>;
+}

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

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

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

@@ -1,40 +1,111 @@
 import { LitElement } from "lit";
+/**
+ * A multi-line text input for collecting longer responses like comments, descriptions, or feedback.
+ * Form-associated with validation support via ElementInternals.
+ *
+ * Use for detailed responses needing multiple lines. For single-line input, use `nys-textinput`.
+ * For predefined options, use `nys-select`, `nys-radiobutton`, or `nys-checkbox`.
+ *
+ * @summary Multi-line text input for comments, descriptions, and feedback.
+ * @element nys-textarea
+ *
+ * @slot description - Custom HTML description content below the label.
+ *
+ * @fires nys-input - Fired on input change. Detail: `{id, value}`.
+ * @fires nys-focus - Fired when textarea gains focus.
+ * @fires nys-blur - Fired when textarea loses focus. Triggers validation.
+ * @fires nys-select - Fired when user selects text. Detail: `{id, value}`.
+ *
+ * @example Basic textarea
+ * ```html
+ * <nys-textarea label="Comments" rows="4"></nys-textarea>
+ * ```
+ *
+ * @example Required with description
+ * ```html
+ * <nys-textarea label="Describe the incident" description="Please provide details" required></nys-textarea>
+ * ```
+ */
 export declare class NysTextarea 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;
+    /** Placeholder text. Don't use as label replacement. */
     placeholder: string;
+    /** Current textarea value. */
     value: string;
+    /** Prevents interaction. */
     disabled: boolean;
+    /** Makes textarea read-only but focusable. */
     readonly: 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;
+    /** Adjusts colors for dark backgrounds. */
     inverted: boolean;
+    /** Form `id` to associate with when textarea is outside form element. */
     form: string | null;
+    /** Maximum character length. */
     maxlength: number | null;
+    /**
+     * Textarea width: `sm` (88px), `md` (200px), `lg` (384px), `full` (100%, default).
+     * @default "full"
+     */
     width: "sm" | "md" | "lg" | "full";
+    /**
+     * Visible height in lines.
+     * @default 4
+     */
     rows: number;
+    /**
+     * Resize behavior: `vertical` (default, user can resize height), `none` (fixed size).
+     * @default "vertical"
+     */
     resize: "vertical" | "none";
+    /** Shows error message when true. Set by validation or manually. */
     showError: boolean;
+    /** Error message text. Shown only when `showError` is true. */
     errorMessage: string;
     updated(changedProperties: Map<string | number | symbol, unknown>): Promise<void>;
     private _hasUserInteracted;
     private _internals;
+    /**
+     * Lifecycle methods
+     * --------------------------------------------------------------------------
+     */
     static formAssociated: boolean;
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
     firstUpdated(): void;
-    formResetCallback(): void;
+    /**
+     * Form Integration
+     * --------------------------------------------------------------------------
+     */
     private _setValue;
     private _manageRequire;
     private _setValidityMessage;
     private _validate;
+    formResetCallback(): void;
+    /**
+     * Functions
+     * --------------------------------------------------------------------------
+     */
     checkValidity(): boolean;
     private _handleInvalid;
+    /**
+     * Event Handlers
+     * --------------------------------------------------------------------------
+     */
     private _handleInput;
     private _handleFocus;
     private _handleBlur;

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

@@ -1,49 +1,133 @@
 import { LitElement } from "lit";
+/**
+ * A text input for collecting short, single-line data. Supports validation, input masking (tel),
+ * password visibility toggle, and live error messaging. Form-associated via ElementInternals.
+ *
+ * Use for names, emails, passwords, phone numbers. For multi-line input, use `nys-textarea` instead.
+ * For predefined options, use `nys-select`, `nys-radiobutton`, or `nys-checkbox`.
+ *
+ * @summary Text input for short single-line data with validation and masking support.
+ * @element nys-textinput
+ *
+ * @slot description - Custom HTML description content below the label.
+ * @slot startButton - Button at input start. Use single `nys-button` only.
+ * @slot endButton - Button at input end. Use single `nys-button` only.
+ *
+ * @fires nys-input - Fired on input change. Detail: `{id, value}`.
+ * @fires nys-focus - Fired when input gains focus.
+ * @fires nys-blur - Fired when input loses focus. Triggers validation.
+ *
+ * @example Basic text input
+ * ```html
+ * <nys-textinput label="Full Name" required></nys-textinput>
+ * ```
+ *
+ * @example Email with validation
+ * ```html
+ * <nys-textinput type="email" label="Email Address" required></nys-textinput>
+ * ```
+ *
+ * @example Phone with masking
+ * ```html
+ * <nys-textinput type="tel" label="Phone Number"></nys-textinput>
+ * ```
+ *
+ * @example Search with button
+ * ```html
+ * <nys-textinput type="search" placeholder="Search">
+ *   <nys-button slot="endButton" label="Search" prefixIcon="search"></nys-button>
+ * </nys-textinput>
+ * ```
+ */
 export declare class NysTextinput extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Unique identifier. Auto-generated if not provided. */
     id: string;
+    /** Name for form submission. */
     name: string;
+    /**
+     * Input type: `text` (default), `email`, `number`, `password`, `search`, `tel` (auto-masked), `url`.
+     * @default "text"
+     */
     type: "email" | "number" | "password" | "search" | "tel" | "text" | "url";
+    /** Visible label text. Required for accessibility. */
     label: string;
+    /** Helper text below label. Use slot for custom HTML. */
     description: string;
+    /** Placeholder text. Don't use as label replacement. */
     placeholder: string;
+    /** Current input value. */
     value: string;
+    /** Prevents interaction. */
     disabled: boolean;
+    /** Makes input read-only but focusable. */
     readonly: 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 input is outside form element. */
     form: string | null;
+    /** Regex pattern for validation. Shows error on mismatch. */
     pattern: string;
+    /** Maximum character length. */
     maxlength: number | null;
+    /**
+     * Input width: `sm` (88px), `md` (200px), `lg` (384px), `full` (100%, default).
+     * @default "full"
+     */
     width: "sm" | "md" | "lg" | "full";
+    /** Step increment for `type="number"`. */
     step: number | null;
+    /** Minimum value for `type="number"`. */
     min: number | null;
+    /** Maximum value for `type="number"`. */
     max: number | 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;
     private showPassword;
     private _originalErrorMessage;
     private _hasUserInteracted;
     private _internals;
     private _maskPatterns;
+    /**
+     * Lifecycle methods
+     * --------------------------------------------------------------------------
+     */
     static formAssociated: boolean;
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
     firstUpdated(): void;
     updated(changedProperties: Map<string | number | symbol, unknown>): Promise<void>;
-    formResetCallback(): void;
+    /**
+     * Form Integration
+     * --------------------------------------------------------------------------
+     */
     private _setValue;
     private _manageRequire;
     private _setValidityMessage;
     private _validate;
+    formResetCallback(): void;
+    /**
+     * Functions
+     * --------------------------------------------------------------------------
+     */
     checkValidity(): boolean;
     private _handleInvalid;
     private _togglePasswordVisibility;
     private _updateOverlay;
     private _applyMask;
+    /**
+     * Event Handlers
+     * --------------------------------------------------------------------------
+     */
     private _handleInput;
     private _handleFocus;
     private _handleBlur;

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

@@ -1,22 +1,74 @@
 import { LitElement } from "lit";
+/**
+ * A toggle switch for binary settings with immediate effect. Form-associated via ElementInternals.
+ *
+ * Use when changing a setting takes effect immediately (e.g., dark mode, notifications).
+ * For binary choices in forms that submit later, use `nys-checkbox` instead.
+ *
+ * @summary Toggle switch for binary settings with immediate effect.
+ * @element nys-toggle
+ *
+ * @slot description - Custom HTML description content.
+ *
+ * @fires nys-change - Fired when toggle state changes. Detail: `{id, checked}`.
+ * @fires nys-focus - Fired when toggle gains focus.
+ * @fires nys-blur - Fired when toggle loses focus.
+ *
+ * @example Basic toggle
+ * ```html
+ * <nys-toggle label="Enable notifications" name="notifications"></nys-toggle>
+ * ```
+ *
+ * @example Dark mode toggle
+ * ```html
+ * <nys-toggle label="Dark mode" description="Adjust display for low light" checked></nys-toggle>
+ * ```
+ */
 export declare class NysToggle extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Unique identifier. Auto-generated if not provided. */
     id: string;
+    /** Name for form submission. */
     name: string;
+    /** Value submitted when toggle is on. */
     value: string;
+    /** Visible label text. */
     label: string;
+    /** Helper text below label. Use slot for custom HTML. */
     description: string;
+    /** Form `id` to associate with. */
     form: string | null;
+    /** Whether toggle is on. */
     checked: boolean;
+    /** Prevents interaction. */
     disabled: boolean;
+    /** Hides check/close icon inside toggle knob. */
     noIcon: boolean;
+    /** Adjusts colors for dark backgrounds. */
     inverted: boolean;
+    /**
+     * Toggle size: `sm` or `md` (default).
+     * @default "md"
+     */
     size: "sm" | "md";
     private _internals;
+    /**
+     * Lifecycle methods
+     * --------------------------------------------------------------------------
+     */
     static formAssociated: boolean;
     constructor();
     connectedCallback(): void;
+    /**
+     * Form Integration
+     * --------------------------------------------------------------------------
+     */
     updated(changedProperties: Map<string, any>): void;
+    formResetCallback(): void;
+    /**
+     * Event Handlers
+     * --------------------------------------------------------------------------
+     */
     private _emitChangeEvent;
     private _handleFocus;
     private _handleBlur;