@nysds/components 1.12.0 → 1.13.1

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

@@ -1,14 +1,43 @@
 import { LitElement } from "lit";
+/**
+ * A floating "Back to top" button that appears after scrolling. Smooth-scrolls to page top when clicked.
+ *
+ * Auto-shows after scrolling 1.5 viewports on pages 4+ screens tall. Set `visible` to force display.
+ * Renders as circle button on mobile. Position with `position` prop (`left` or `right`).
+ *
+ * @summary Floating back-to-top button with auto-show behavior and smooth scroll.
+ * @element nys-backtotop
+ *
+ * @example Auto-appearing button
+ * ```html
+ * <nys-backtotop></nys-backtotop>
+ * ```
+ *
+ * @example Always visible, left position
+ * ```html
+ * <nys-backtotop visible position="left"></nys-backtotop>
+ * ```
+ */
 export declare class NysBacktotop extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Horizontal position: `left` or `right`. */
     position: string;
+    /** Force button visibility. Overrides auto-show scroll behavior. */
     visible: boolean;
     private isMobile;
     private forceVisible;
     private mediaQuery;
+    /**
+     * Lifecycle methods
+     * --------------------------------------------------------------------------
+     */
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /**
+     * Functions
+     * --------------------------------------------------------------------------
+     */
     private _handleScroll;
     private _scrollToTop;
     private _handleResize;

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

@@ -1,20 +1,66 @@
 import { LitElement } from "lit";
+/**
+ * A compact label for status, counts, or categorization. Supports semantic intents with auto-selected icons.
+ *
+ * Use badges to highlight metadata like status ("Approved"), counts ("3 new"), or categories.
+ * Set `intent` to apply semantic meaning. Add `prefixIcon` or `suffixIcon` as boolean for default icons,
+ * or pass icon name strings for custom icons.
+ *
+ * @summary Compact label for status, counts, or categorization with semantic styling.
+ * @element nys-badge
+ *
+ * @example Status badge
+ * ```html
+ * <nys-badge intent="success" label="Approved" prefixIcon></nys-badge>
+ * ```
+ *
+ * @example Count badge
+ * ```html
+ * <nys-badge prefixLabel="Messages" label="12"></nys-badge>
+ * ```
+ */
 export declare class NysBadge extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Unique identifier. */
     id: string;
+    /** Name attribute for form association. */
     name: string;
+    /**
+     * Badge size: `sm` (smaller text) or `md` (default).
+     * @default "md"
+     */
     size: "sm" | "md";
+    /**
+     * Semantic intent affecting color: `neutral`, `error`, `success`, or `warning`.
+     * @default "neutral"
+     */
     intent: "neutral" | "error" | "success" | "warning";
+    /** Secondary label displayed before the main label. */
     prefixLabel: string;
+    /** Primary label text displayed in the badge. */
     label: string;
+    variant: "strong" | "";
     private _prefixIcon;
     get prefixIcon(): string | boolean;
     set prefixIcon(value: string | boolean);
     private _suffixIcon;
     get suffixIcon(): string | boolean;
     set suffixIcon(value: string | boolean);
+    /**
+     * Lifecycle methods
+     * --------------------------------------------------------------------------
+     */
     connectedCallback(): void;
+    /**
+     * Functions
+     * --------------------------------------------------------------------------
+     */
     private static readonly DEFAULT_ICONS;
+    /**
+     * Resolves which icon should be rendered.
+     * @param icon The icon property value (string or boolean)
+     * @returns Icon name or null if no icon should be rendered
+     */
     private resolveIcon;
     render(): import("lit-html").TemplateResult<1>;
 }

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

@@ -1,34 +1,175 @@
 import { LitElement } from "lit";
+/**
+ * A button for actions like saving, submitting, or navigating. Form-associated with full keyboard support.
+ *
+ * Use `filled` for primary actions (one per section), `outline` for secondary, `ghost` for tertiary,
+ * `text` for inline. Set `href` to render as a navigation link.
+ *
+ * @summary Button for actions and CTAs with variants, sizes, and icon support.
+ * @element nys-button
+ *
+ * @slot prefix-icon - Icon before label. Not shown for `text` variant.
+ * @slot suffix-icon - Icon after label. Not shown for `text` variant.
+ * @slot circle-icon - Icon for circle mode. Overrides `icon` prop.
+ *
+ * @cssprop [--nys-button-color] - Text color of the button label.
+ * @cssprop [--nys-button-color--hover] - Text color when hovered.
+ * @cssprop [--nys-button-color--active] - Text color when active/pressed.
+ * @cssprop [--nys-button-background-color] - Background color of the button.
+ * @cssprop [--nys-button-background-color--hover] - Background color when hovered.
+ * @cssprop [--nys-button-background-color--active] - Background color when active/pressed.
+ * @cssprop [--nys-button-border-color] - Border color of the button.
+ * @cssprop [--nys-button-border-color--hover] - Border color when hovered.
+ * @cssprop [--nys-button-border-color--active] - Border color when active/pressed.
+ *
+ * @fires nys-click - Fired when the button is clicked (mouse or keyboard). Not fired when disabled.
+ * @fires nys-focus - Fired when the button receives focus.
+ * @fires nys-blur - Fired when the button loses focus.
+ *
+ * @example Basic filled button
+ * ```html
+ * <nys-button label="Submit" variant="filled"></nys-button>
+ * ```
+ *
+ * @example Secondary outline button
+ * ```html
+ * <nys-button label="Cancel" variant="outline"></nys-button>
+ * ```
+ *
+ * @example Button with icons
+ * ```html
+ * <nys-button label="Previous" prefixIcon="chevron_left"></nys-button>
+ * <nys-button label="Next" suffixIcon="chevron_right"></nys-button>
+ * ```
+ *
+ * @example Circle icon button
+ * ```html
+ * <nys-button circle icon="close" label="Close dialog"></nys-button>
+ * ```
+ *
+ * @example Link-style button for navigation
+ * ```html
+ * <nys-button label="Visit NY.gov" href="https://www.ny.gov/" target="_blank" suffixIcon="open_in_new"></nys-button>
+ * ```
+ *
+ * @example Form submit button
+ * ```html
+ * <nys-button type="submit" label="Save Changes" variant="filled"></nys-button>
+ * ```
+ */
 export declare class NysButton extends LitElement {
     static styles: import("lit").CSSResult;
+    /**
+     * Unique identifier. Auto-generated if not provided.
+     */
     id: string;
+    /**
+     * Name for form submission.
+     */
     name: string;
+    /**
+     * Button height: `sm` (40px) for dense UIs, `md` (48px, default) for standard use, `lg` (56px) for prominent CTAs.
+     * @default "md"
+     */
     size: "sm" | "md" | "lg";
+    /**
+     * Expands button to fill container width. Use for mobile layouts or stacked button groups.
+     * @default false
+     */
     fullWidth: boolean;
+    /**
+     * Visual style: `filled` for primary (one per section), `outline` for secondary, `ghost` for tertiary, `text` for inline actions. Avoid `text` for navigation.
+     * @default "filled"
+     */
     variant: "filled" | "outline" | "ghost" | "text";
+    /**
+     * Adjusts colors for dark backgrounds.
+     * @default false
+     */
     inverted: boolean;
+    /**
+     * Visible button text. Use sentence case, action-oriented text (e.g., "Save Draft"). Becomes aria-label in `circle` mode.
+     */
     label: string;
+    /**
+     * Screen reader label. Required for icon-only buttons if `label` is not set.
+     */
     ariaLabel: string;
+    /**
+     * ID of controlled element (e.g., dropdown or modal). Sets `aria-controls`.
+     */
     ariaControls: string;
+    /**
+     * Material Symbol icon before label. Not shown for `text` variant or `circle` mode.
+     */
     prefixIcon: string;
+    /**
+     * Material Symbol icon after label. Use `chevron_down` for dropdowns, `open_in_new` for external links. Not shown for `text` variant or `circle` mode.
+     */
     suffixIcon: string;
+    /**
+     * Renders circular icon-only button. Requires `icon` prop. `label` becomes aria-label.
+     * @default false
+     */
     circle: boolean;
+    /**
+     * Icon for circle mode. Required when `circle` is true. Scales with size (sm=24px, md=32px, lg=40px).
+     */
     icon: string;
+    /**
+     * Prevents interaction. Avoid disabling without explanation—show validation errors instead.
+     * @default false
+     */
     disabled: boolean;
+    /**
+     * Form `id` to associate with. Use when button is outside the form element.
+     */
     form: string | null;
+    /**
+     * Value submitted with form data. Only used when `type="submit"`.
+     */
     value: string;
+    /**
+     * Additional screen reader description. Sets `aria-description`.
+     */
     ariaDescription: string;
+    /**
+     * Form behavior: `button` (default, no form action), `submit` (submits form), `reset` (resets form). Always set explicitly to avoid unintended submissions.
+     * @default "button"
+     */
     type: "submit" | "reset" | "button";
+    /**
+     * Click handler. Use instead of `@click` to ensure keyboard accessibility.
+     */
     onClick: ((event: Event) => void) | null;
+    /**
+     * URL to navigate to. Renders as `<a>` tag. Omit for action buttons.
+     */
     href: string;
+    /**
+     * Link target: `_self` (same tab), `_blank` (new tab—add `suffixIcon="open_in_new"`), `_parent`, `_top`, or frame name.
+     * @default "_self"
+     */
     target: "_self" | "_blank" | "_parent" | "_top" | "framename";
     getButtonElement(): Promise<HTMLElement | null>;
     private _internals;
+    /**
+     * Lifecycle methods
+     * --------------------------------------------------------------------------
+     */
     static formAssociated: boolean;
     constructor();
     connectedCallback(): void;
+    /**
+     * Functions
+     * --------------------------------------------------------------------------
+     */
     private _generateUniqueId;
     private _manageFormAction;
+    /**
+     * Event Handlers
+     * --------------------------------------------------------------------------
+     */
     private _handleFocus;
     private _handleBlur;
     private _handleClick;

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

@@ -1,38 +1,102 @@
 import { LitElement } from "lit";
 import "./nys-checkboxgroup";
+/**
+ * A checkbox input for binary choices or multi-select lists. Can be used standalone or in a `nys-checkboxgroup`.
+ * Form-associated with validation via ElementInternals.
+ *
+ * Use for binary decisions (agree/disagree) or selecting multiple options from a list.
+ * For single selection from 2-6 options, use `nys-radiobutton`. For immediate state changes, use `nys-toggle`.
+ *
+ * @summary Checkbox for binary choices or multi-select options.
+ * @element nys-checkbox
+ *
+ * @slot description - Custom HTML description content.
+ *
+ * @fires nys-change - Fired when checked state changes. Detail: `{id, checked, name, value}`.
+ * @fires nys-focus - Fired when checkbox gains focus.
+ * @fires nys-blur - Fired when checkbox loses focus.
+ *
+ * @example Single checkbox
+ * ```html
+ * <nys-checkbox label="I agree to the terms" name="terms" required></nys-checkbox>
+ * ```
+ *
+ * @example Checkbox group
+ * ```html
+ * <nys-checkboxgroup label="Select landmarks">
+ *   <nys-checkbox name="landmarks" value="adirondacks" label="Adirondacks"></nys-checkbox>
+ *   <nys-checkbox name="landmarks" value="niagara" label="Niagara Falls"></nys-checkbox>
+ * </nys-checkboxgroup>
+ * ```
+ */
 export declare class NysCheckbox extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Whether checkbox is checked. */
     checked: boolean;
+    /** Prevents interaction. */
     disabled: boolean;
+    /** Marks as required. Validates that checkbox is checked. */
     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;
+    /** Name for form submission. Use same name for grouped checkboxes. */
     name: string;
+    /** Value submitted when checked. */
     value: string;
+    /** Form `id` to associate with when checkbox is outside form element. */
     form: string | null;
+    /** Shows error message when true. */
     showError: boolean;
+    /** Error message text. Shown only when `showError` is true. */
     errorMessage: string;
+    /** Internal: Set by parent checkboxgroup. Do not set manually. */
     groupExist: boolean;
+    /** Renders as tile with larger clickable area. Apply to group for consistency. */
     tile: boolean;
+    /** Adjusts colors for dark backgrounds. */
     inverted: boolean;
+    /** Tooltip text shown on hover/focus of info icon. */
     tooltip: string;
+    /**
+     * Checkbox size: `sm` (24px) or `md` (32px, default).
+     * @default "md"
+     */
     size: "sm" | "md";
     getInputElement(): Promise<HTMLInputElement | null>;
     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;
     private _manageLabelClick;
+    /**
+     * Event Handlers
+     * --------------------------------------------------------------------------
+     */
     private _emitChangeEvent;
     private _handleChange;
     private _handleFocus;

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

@@ -1,27 +1,72 @@
 import { LitElement } from "lit";
+/**
+ * A container for grouping multiple `nys-checkbox` components as a single form control.
+ * Handles validation, required constraints, and submits comma-separated values.
+ *
+ * Use to allow users to select multiple options from a list. Apply `tile`, `size`, and `inverted` to the group
+ * and all children inherit these styles automatically.
+ *
+ * @summary Container for grouping checkboxes as a single form control.
+ * @element nys-checkboxgroup
+ *
+ * @slot - Default slot for `nys-checkbox` elements.
+ * @slot description - Custom HTML description content.
+ *
+ * @example Basic checkbox group
+ * ```html
+ * <nys-checkboxgroup label="Select landmarks" required>
+ *   <nys-checkbox name="landmarks" value="adirondacks" label="Adirondacks"></nys-checkbox>
+ *   <nys-checkbox name="landmarks" value="niagara" label="Niagara Falls"></nys-checkbox>
+ * </nys-checkboxgroup>
+ * ```
+ */
 export declare class NysCheckboxgroup extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Unique identifier. Auto-generated if not provided. */
     id: string;
+    /** Name for form submission. Set on group, not individual checkboxes. */
     name: string;
+    /** Requires at least one checkbox to be checked. */
     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 checkboxes 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;
+    /**
+     * Checkbox size for all children: `sm` (24px) or `md` (32px, default).
+     * @default "md"
+     */
     size: "sm" | "md";
     private _slottedDescriptionText;
     private _internals;
+    /**
+     * Lifecycle methods
+     * --------------------------------------------------------------------------
+     */
     static formAssociated: boolean;
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
     firstUpdated(): void;
     updated(changedProperties: Map<string | symbol, unknown>): void;
+    /**
+     * Functions
+     * --------------------------------------------------------------------------
+     */
     private _setGroupExist;
     private _setupCheckboxRequired;
     private _manageRequire;
@@ -31,7 +76,12 @@ export declare class NysCheckboxgroup extends LitElement {
     private _updateCheckboxShowError;
     private _updateCheckboxForm;
     private _getSlotDescriptionForAria;
+    formResetCallback(): void;
     private _handleInvalid;
+    /**
+     * Event Handlers
+     * --------------------------------------------------------------------------
+     */
     private _handleCheckboxChange;
     render(): import("lit-html").TemplateResult<1>;
 }

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

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

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

@@ -0,0 +1,116 @@
+import { LitElement } from "lit";
+/**
+ * `<nys-datepicker>` is a form-associated, accessible date picker component.
+ * Optionally wraps a `<wc-datepicker>` for custom calendar UI.
+ *
+ * Events:
+ * @fires nys-blur - Dispatched when input or calendar loses focus
+ * @fires nys-input - Dispatched when user selects or types a valid date
+ *
+ * Notes:
+ * - Uses native date input on Safari or mobile devices (custom calendar removed for these scenarios)
+ */
+export declare class NysDatepicker extends LitElement {
+    static styles: import("lit").CSSResult;
+    id: string;
+    name: string;
+    width: "md" | "lg" | "full";
+    hideTodayButton: boolean;
+    hideClearButton: boolean;
+    disabled: boolean;
+    required: boolean;
+    optional: boolean;
+    showError: boolean;
+    errorMessage: string;
+    form: string | null;
+    tooltip: string;
+    type: string;
+    label: string;
+    description: string;
+    startDate: string;
+    inverted: boolean;
+    value: string | Date | undefined;
+    private _hasUserInteracted;
+    private _internals;
+    /**
+     * Lifecycle methods
+     * --------------------------------------------------------------------------
+     */
+    static formAssociated: boolean;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    firstUpdated(): Promise<void>;
+    private _whenWcDatepickerReady;
+    /**
+     * Form Integration
+     * --------------------------------------------------------------------------
+     */
+    /**
+     * Form helper methods:
+     * - _setValue: set internal value and trigger validation
+     * - _manageRequire: handle required state
+     * - _validate: actively validate and show errors
+     * - checkValidity: passive boolean check without UI
+     * - _setValidityMessage: sync validation message with UI and internals
+     * - _handleInvalid: handle form invalid event and focus first invalid field
+     */
+    private _setValue;
+    private _manageRequire;
+    /**
+     * Actively validates the component:
+     * - Updates internal validity state
+     * - Updates UI (e.g. showError)
+     * - Called on blur/change or form submission
+     */
+    private _validate;
+    /**
+     * Passive check of validity:
+     * - Returns true/false
+     * - Does NOT update UI or show errors
+     * - Used in form submission checks
+     */
+    checkValidity(): boolean;
+    private _setValidityMessage;
+    private _handleInvalid;
+    /**
+     * Functions
+     * --------------------------------------------------------------------------
+     */
+    /**
+     * Replaces the default wc-datepicker month navigation buttons
+     * with NYS icon components for previous and next month.
+     */
+    private _replaceButtonSVG;
+    private _addMonthDropdownIcon;
+    private _parseLocalDate;
+    /**
+     * Event Handlers
+     * --------------------------------------------------------------------------
+     */
+    private _handleInputKeydown;
+    private _handleBlur;
+    private _onDocumentClick;
+    private _toggleDatepicker;
+    private _openDatepicker;
+    private _handleDateChange;
+    private _handleTodayClick;
+    private _handleClearClick;
+    private _handleInputChange;
+    private _getValidDateFromInput;
+    private _isSafari;
+    /**
+     * Determines whether the current device uses a coarse pointer.
+     * A coarse pointer usually means touch-based input where precise pointing
+     * is not expected, such as fingers on phones and most tablets.
+     *
+     * Note: This is not a guarantee of a mobile device.
+     * Some non-mobile devices may also report a coarse pointer,
+     * and some mobile devices may not.
+     *
+     * @returns `true` if the device reports a coarse pointer, otherwise `false`.
+     */
+    private _isMobile;
+    private _shouldUseNativeDatepicker;
+    render(): import("lit-html").TemplateResult<1>;
+}

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

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

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

@@ -1,7 +1,29 @@
 import { LitElement } from "lit";
+/**
+ * A horizontal rule for visual separation between content sections. Renders a semantic `<hr>` element.
+ *
+ * Use to separate distinct content areas within a page. Set `inverted` for use on dark backgrounds.
+ *
+ * @summary Horizontal divider for visual separation of content sections.
+ * @element nys-divider
+ *
+ * @example Basic divider
+ * ```html
+ * <p>Section one content</p>
+ * <nys-divider></nys-divider>
+ * <p>Section two content</p>
+ * ```
+ */
 export declare class NysDivider extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Adjusts colors for dark backgrounds. */
     inverted: boolean;
     constructor();
+    connectedCallback(): void;
+    /**
+     * Functions
+     * --------------------------------------------------------------------------
+     */
+    private _generateUniqueId;
     render(): import("lit-html").TemplateResult<1>;
 }

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

@@ -1,10 +1,26 @@
 import { LitElement } from "lit";
+/**
+ * **Internal component.** Displays error messages for form validation with icon and ARIA alert role.
+ *
+ * Used internally by form components. Not intended for direct use. Shows error icon and message
+ * when `showError` is true. Integrates with ElementInternals for native form validation messages.
+ *
+ * @summary Internal error message display with icon and ARIA alert support.
+ * @element nys-errormessage
+ */
 export declare class NysErrorMessage extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Whether to display the error message. */
     showError: boolean;
+    /** Error text to display. Falls back to native validation message if available. */
     errorMessage: string;
+    /** Shows a divider line above the error message. */
     showDivider: boolean;
     private _internals;
+    /**
+     * Lifecycle methods
+     * --------------------------------------------------------------------------
+     */
     static formAssociated: boolean;
     constructor();
     render(): import("lit-html").TemplateResult<1>;