@nysds/components 1.13.0 → 1.14.0

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

@@ -1,19 +1,45 @@
 import { LitElement } from "lit";
 /**
- * `<nys-badge>` displays a badge with optional prefix/suffix icons and labels.
+ * A compact label for status, counts, or categorization. Supports semantic intents with auto-selected icons.
  *
- * Features:
- * - Conveys an intent (`neutral`, `error`, `success`, `warning`) which affects default icons and styling.
- * - Supports custom prefix and suffix 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);

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

@@ -1,38 +1,155 @@
 import { LitElement } from "lit";
 /**
- * `<nys-button>` is a versatile button component supporting:
- * - Multiple variants (`filled`, `outline`, `ghost`, `text`)
- * - Sizes (`sm`, `md`, `lg`) and full-width layout
- * - Icons (prefix, suffix, or circle) and optional labels
- * - Native `<button>` or link `<a>` behavior with form association
- * - Keyboard and accessibility support (`aria-label`, `aria-controls`, `aria-description`)
+ * A button for actions like saving, submitting, or navigating. Form-associated with full keyboard support.
  *
- * @fires nys-click - Fired on button click
- * @fires nys-focus - Fired when button receives focus
- * @fires nys-blur - Fired when button loses focus
+ * 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;

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

@@ -1,39 +1,75 @@
 import { LitElement } from "lit";
 import "./nys-checkboxgroup";
 /**
- * `<nys-checkbox>` is an accessible, form-associated checkbox component.
- * Can be used standalone or within a `<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.
  *
- * Features:
- * - Supports labels, descriptions, and tooltips
- * - Displays error messages with `showError` and `errorMessage`
- * - Keyboard interaction with spacebar toggle
- * - Form integration via ElementInternals (`checked` value submitted)
+ * 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`.
  *
- * @fires nys-change - Fired when checkbox value changes
- * @fires nys-focus - Fired on focus
- * @fires nys-blur - Fired on blur
+ * @summary Checkbox for binary choices or multi-select options.
+ * @element nys-checkbox
  *
- * @slot description - Slot to provide a custom description element
+ * @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";
+    other: boolean;
+    showOtherError: boolean;
+    private isMobile;
+    private _hasUserInteracted;
     getInputElement(): Promise<HTMLInputElement | null>;
     private _internals;
     /**
@@ -61,6 +97,8 @@ export declare class NysCheckbox extends LitElement {
     checkValidity(): boolean;
     private _handleInvalid;
     private _manageLabelClick;
+    get _hasDescription(): boolean;
+    private _handleResize;
     /**
      * Event Handlers
      * --------------------------------------------------------------------------
@@ -69,6 +107,10 @@ export declare class NysCheckbox extends LitElement {
     private _handleChange;
     private _handleFocus;
     private _handleBlur;
+    private _handleTextInputBlur;
     private _handleKeydown;
+    private _handleTextInput;
+    private _validateOtherAndEmitError;
+    private _dispatchClearError;
     render(): import("lit-html").TemplateResult<1>;
 }

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

@@ -1,37 +1,59 @@
 import { LitElement } from "lit";
 /**
- * `<nys-checkboxgroup>` is a form-associated container for multiple `<nys-checkbox>` components.
- * Handles grouping, validation, required constraints, form submission, and accessibility.
+ * A container for grouping multiple `nys-checkbox` components as a single form control.
+ * Handles validation, required constraints, and submits comma-separated values.
  *
- * Features:
- * - Manages multiple checkboxes as a single form field
- * - Supports required/optional flags and error messages
- * - Propagates size, tile, and inverted styling to child checkboxes
- * - Keyboard and screen reader accessible via fieldset/legend
+ * 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.
  *
- * @slot default - Slot for child `<nys-checkbox>` elements
- * @slot description - Slot for custom description content
+ * @summary Container for grouping checkboxes as a single form control.
+ * @element nys-checkboxgroup
  *
- * @fires nys-change - Fired when any child checkbox changes
- * @fires nys-focus - Fired when any child checkbox gains focus
- * @fires nys-blur - Fired when any child checkbox loses focus
+ * @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 _hasOtherError;
+    private _otherErrorCheckbox;
     private _internals;
     /**
      * Lifecycle methods
@@ -47,20 +69,26 @@ export declare class NysCheckboxgroup extends LitElement {
      * Functions
      * --------------------------------------------------------------------------
      */
+    private _hasAtLeastOneChecked;
     private _setGroupExist;
     private _setupCheckboxRequired;
     private _manageRequire;
+    private _setCustomOtherError;
     private _updateCheckboxSize;
     private _updateCheckboxTile;
     private _updateCheckboxInvert;
     private _updateCheckboxShowError;
     private _updateCheckboxForm;
     private _getSlotDescriptionForAria;
+    formResetCallback(): void;
     private _handleInvalid;
     /**
      * Event Handlers
      * --------------------------------------------------------------------------
      */
     private _handleCheckboxChange;
+    private _handleChildError;
+    private _handleChildErrorClear;
+    private _checkOtherInputs;
     render(): import("lit-html").TemplateResult<1>;
 }

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

@@ -1,35 +1,89 @@
 import { LitElement } from "lit";
 /**
- * `<nys-datepicker>` is a form-associated, accessible date picker component.
- * Optionally wraps a `<wc-datepicker>` for custom calendar UI.
+ * Date picker with calendar popup and form validation. Falls back to native date input
+ * on Safari and mobile.
  *
- * Events:
- * @fires nys-blur - Dispatched when input or calendar loses focus
- * @fires nys-input - Dispatched when user selects or types a valid date
+ * @summary Date picker with calendar popup and native fallback.
+ * @element nys-datepicker
  *
- * Notes:
- * - Uses native date input on Safari or mobile devices (custom calendar removed for these scenarios)
+ * @fires nys-blur - Fired when input or calendar loses focus. Triggers validation.
+ * @fires nys-input - Fired on date selection. Detail: `{id, value}`.
+ *
+ * @example Basic date picker
+ * ```html
+ * <nys-datepicker label="Birth Date" required></nys-datepicker>
+ * ```
+ *
+ * @example With width and description
+ * ```html
+ * <nys-datepicker
+ *   label="Event Date"
+ *   description="Select the date of your event"
+ *   width="lg">
+ * </nys-datepicker>
+ * ```
+ *
+ * @example Hide buttons, set start date
+ * ```html
+ * <nys-datepicker
+ *   label="Appointment"
+ *   hideTodayButton
+ *   hideClearButton
+ *   startDate="2024-01-01">
+ * </nys-datepicker>
+ * ```
+ *
+ * @example With validation error message
+ * ```html
+ * <nys-datepicker
+ *   label="Start Date"
+ *   required
+ *   errorMessage="Please select a valid start date">
+ * </nys-datepicker>
+ * ```
  */
 export declare class NysDatepicker extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Unique identifier. Auto-generated if not provided. */
     id: string;
+    /** Name for form submission. */
     name: string;
+    /**
+     * Input width: `md` (200px), `lg` (384px), `full` (100%).
+     * @default "md"
+     */
     width: "md" | "lg" | "full";
+    /** Hide the "Today" button in calendar popup. */
     hideTodayButton: boolean;
+    /** Hide the "Clear" button in calendar popup. */
     hideClearButton: boolean;
+    /** Disable interaction. */
     disabled: boolean;
+    /** Mark as required. Shows "Required" flag and validates on blur. */
     required: boolean;
+    /** Show "Optional" flag. Use when most fields are required. */
     optional: boolean;
+    /** Show error state. */
     showError: boolean;
+    /** Error message text. */
     errorMessage: string;
+    /** Form `id` to associate with when input is outside form. */
     form: string | null;
+    /** Tooltip text on info icon hover. */
     tooltip: string;
+    /** Input type. Currently only supports `date`. */
     type: string;
+    /** Label text. Required for accessibility. */
     label: string;
+    /** Helper text below label. */
     description: string;
+    /** Initial date when calendar opens (YYYY-MM-DD). */
     startDate: string;
+    /** Dark background mode. */
     inverted: boolean;
+    /** Selected date. Accepts Date object or ISO string (YYYY-MM-DD). */
     value: string | Date | undefined;
+    private datepickerIsOpen;
     private _hasUserInteracted;
     private _internals;
     /**
@@ -84,6 +138,8 @@ export declare class NysDatepicker extends LitElement {
     private _replaceButtonSVG;
     private _addMonthDropdownIcon;
     private _parseLocalDate;
+    private _setTodayDate;
+    private _setFocusOnTodayDate;
     /**
      * Event Handlers
      * --------------------------------------------------------------------------
@@ -91,6 +147,7 @@ export declare class NysDatepicker extends LitElement {
     private _handleInputKeydown;
     private _handleBlur;
     private _onDocumentClick;
+    private _onKeydownEsc;
     private _toggleDatepicker;
     private _openDatepicker;
     private _handleDateChange;
@@ -98,6 +155,7 @@ export declare class NysDatepicker extends LitElement {
     private _handleClearClick;
     private _handleInputChange;
     private _getValidDateFromInput;
+    private _handleFocusTrap;
     private _isSafari;
     /**
      * Determines whether the current device uses a coarse pointer.

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

@@ -1,11 +1,29 @@
 import { LitElement } from "lit";
 /**
- * `<nys-divider>` renders a horizontal rule `<hr>` element with optional styling.
- * Can be inverted for dark backgrounds.
+ * 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,13 +1,20 @@
 import { LitElement } from "lit";
 /**
- * THIS IS A PRIVATE COMPONENT!
- * `<nys-errormessage>` displays an error message for form elements.
- * Can optionally show a divider and supports native form validation messages.
+ * **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;
     /**