@nysds/components 1.12.0 → 1.13.0

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

@@ -1,19 +1,36 @@
 import { LitElement } from "lit";
 import "./nys-accordionitem";
 /**
- * The "nys-accordion" is the wrapper that groups individual accordion items within it.
- * The items within is called "nys-accordionitem"
+ * `<nys-accordion>` groups one or more `<nys-accordionitem>` elements.
+ *
+ * Features:
+ * - Optionally enforces single-expanded-item behavior via `singleSelect`.
+ * - Propagates shared visual `bordered` property to child items.
+ * - Generates a stable unique identifier if none is provided.
+ *
+ * @slot default - Place one or more `<nys-accordionitem>` components here.
+ *
+ * @fires nys-accordionitem-toggle - Fired when a child `<nys-accordionitem>` is toggled.
+ *   Event detail includes `{ id: string, heading: string, expanded: boolean }`.
  */
 export declare class NysAccordion extends LitElement {
     static styles: import("lit").CSSResult;
     id: string;
     singleSelect: boolean;
     bordered: boolean;
+    /**
+     * Lifecycle methods
+     * --------------------------------------------------------------------------
+     */
     constructor();
     connectedCallback(): void;
     updated(changedProperties: Map<string, any>): void;
+    /**
+     * Functions
+     * --------------------------------------------------------------------------
+     */
     private _generateUniqueId;
-    private _getAccordions;
+    private _getAccordionItems;
     private _onAccordionToggle;
     private _applyBordered;
     render(): import("lit-html").TemplateResult<1>;

package/dist/packages/nys-accordion/src/nys-accordionitem.d.ts

@@ -1,14 +1,34 @@
 import { LitElement } from "lit";
+/**
+ * `<nys-accordionitem>` represents a single collapsible item inside a `<nys-accordion>`.
+ *
+ * @slot - Default slot for the content inside the accordion panel.
+ *
+ * @event nys-accordionitem-toggle - Fired when the item is expanded or collapsed.
+ *   @type {CustomEvent<{id: string, heading: string, expanded: boolean}>}
+ *
+ * Features:
+ * - Click or keyboard (Enter/Space) toggles expansion.
+ * - Animates height changes when expanding/collapsing.
+ */
 export declare class NysAccordionItem extends LitElement {
     static styles: import("lit").CSSResult;
     id: string;
     heading: string;
     expanded: boolean;
     bordered: boolean;
+    /**
+     * Lifecycle methods
+     * --------------------------------------------------------------------------
+     */
     constructor();
     connectedCallback(): void;
     firstUpdated(): void;
     updated(changedProperties: Map<string, any>): void;
+    /**
+     * Functions
+     * --------------------------------------------------------------------------
+     */
     private _generateUniqueId;
     private _dispatchEvent;
     private _handleExpand;

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

@@ -1,4 +1,18 @@
 import { LitElement } from "lit";
+/**
+ * `<nys-alert>` renders an informational, success, warning, or error alert.
+ *
+ * @slot - Default slot for additional alert content.
+ *
+ * @event nys-close - Fired when alert is dismissed (manual or timeout).
+ *   @type {CustomEvent<{id: string, type: string, label: string}>}
+ *
+ * Features:
+ * - Accessible ARIA roles and live-region announcements.
+ * - Auto-close via `duration`.
+ * - Handles default slot content or fallback `text`.
+ * - Optional dismiss button.
+ */
 export declare class NysAlert extends LitElement {
     static styles: import("lit").CSSResult;
     id: string;
@@ -14,18 +28,42 @@ export declare class NysAlert extends LitElement {
     type: "base" | "info" | "success" | "warning" | "danger" | "emergency";
     private _alertClosed;
     private _slotHasContent;
+    /**
+     * Returns ARIA role and label based on alert type.
+     * - 'alert' => assertive live region (implied)
+     * - 'status' => polite live region
+     * - 'region' => generic, requires aria-label
+     */
     get ariaAttributes(): {
         role: "alert" | "status" | "region";
         ariaLabel: string;
     };
+    /**
+     * Returns live-region type for screen readers if applicable.
+     * - 'polite' for status role
+     * - undefined for alert (since it's implicitly assertive) or region
+     */
+    get liveRegion(): "polite" | undefined;
+    /**
+     * Lifecycle methods
+     * --------------------------------------------------------------------------
+     */
     private _timeoutId;
     connectedCallback(): void;
     disconnectedCallback(): void;
     firstUpdated(): void;
+    /**
+     * Functions
+     * --------------------------------------------------------------------------
+     */
     private _generateUniqueId;
-    private _getIconName;
+    private _resolveIconName;
     private _checkAltNaming;
     private _closeAlert;
+    /**
+     * Checks whether the default slot has content.
+     * Updates `_slotHasContent` accordingly.
+     */
     private _checkSlotContent;
     render(): import("lit-html").TemplateResult<1>;
 }

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

@@ -1,4 +1,15 @@
 import { LitElement } from "lit";
+/**
+ * `<nys-avatar>` displays a user avatar as an image, initials, or icon.
+ *
+ * @slot - Default slot for custom icon content. Fallback icon is used if slot is empty.
+ *
+ * Features:
+ * - Computes foreground color for sufficient contrast based on background.
+ * - Supports interactive avatars with button role.
+ * - Fallback to icon when image or initials are missing.
+ * - Lazy loading for performance optimization.
+ */
 export declare class NysAvatar extends LitElement {
     static styles: import("lit").CSSResult;
     id: string;
@@ -11,8 +22,22 @@ export declare class NysAvatar extends LitElement {
     disabled: boolean;
     lazy: boolean;
     private _slotHasContent;
+    /**
+     * Lifecycle methods
+     * --------------------------------------------------------------------------
+     */
     connectedCallback(): void;
     private _handleSlotChange;
+    /**
+     * Functions
+     * --------------------------------------------------------------------------
+     */
+    /**
+     * Computes the appropriate foreground color (icon or initials)
+     * based on the avatar's background color for sufficient contrast.
+     *
+     * @returns CSS color string for foreground
+     */
     private getContrastForeground;
     render(): import("lit-html").TemplateResult<1>;
 }

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

@@ -1,4 +1,15 @@
 import { LitElement } from "lit";
+/**
+ * `<nys-backtotop>` renders a button that scrolls the page to the top.
+ *
+ * Features:
+ * - Automatically appears after scrolling past 1.5 viewport heights
+ *   if the page is at least 4 screens tall.
+ * - Adapts to mobile screens (renders as a circle button when narrow).
+ * - Can be explicitly shown with the `visible` attribute.
+ *
+ * @fires nys-click - Fired when the button is clicked (scrolls page to top).
+ */
 export declare class NysBacktotop extends LitElement {
     static styles: import("lit").CSSResult;
     position: string;
@@ -6,9 +17,17 @@ export declare class NysBacktotop extends LitElement {
     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,4 +1,11 @@
 import { LitElement } from "lit";
+/**
+ * `<nys-badge>` displays a badge with optional prefix/suffix icons and labels.
+ *
+ * Features:
+ * - Conveys an intent (`neutral`, `error`, `success`, `warning`) which affects default icons and styling.
+ * - Supports custom prefix and suffix icons.
+ */
 export declare class NysBadge extends LitElement {
     static styles: import("lit").CSSResult;
     id: string;
@@ -13,8 +20,21 @@ export declare class NysBadge extends LitElement {
     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,4 +1,16 @@
 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`)
+ *
+ * @fires nys-click - Fired on button click
+ * @fires nys-focus - Fired when button receives focus
+ * @fires nys-blur - Fired when button loses focus
+ */
 export declare class NysButton extends LitElement {
     static styles: import("lit").CSSResult;
     id: string;
@@ -24,11 +36,23 @@ export declare class NysButton extends LitElement {
     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,5 +1,21 @@
 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>`.
+ *
+ * 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)
+ *
+ * @fires nys-change - Fired when checkbox value changes
+ * @fires nys-focus - Fired on focus
+ * @fires nys-blur - Fired on blur
+ *
+ * @slot description - Slot to provide a custom description element
+ */
 export declare class NysCheckbox extends LitElement {
     static styles: import("lit").CSSResult;
     checked: boolean;
@@ -20,19 +36,35 @@ export declare class NysCheckbox extends LitElement {
     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,4 +1,21 @@
 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.
+ *
+ * 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
+ *
+ * @slot default - Slot for child `<nys-checkbox>` elements
+ * @slot description - Slot for custom description content
+ *
+ * @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
+ */
 export declare class NysCheckboxgroup extends LitElement {
     static styles: import("lit").CSSResult;
     id: string;
@@ -16,12 +33,20 @@ export declare class NysCheckboxgroup extends LitElement {
     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;
@@ -32,6 +57,10 @@ export declare class NysCheckboxgroup extends LitElement {
     private _updateCheckboxForm;
     private _getSlotDescriptionForAria;
     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,4 +1,8 @@
 import { LitElement } from "lit";
+/**
+ * `<nys-divider>` renders a horizontal rule `<hr>` element with optional styling.
+ * Can be inverted for dark backgrounds.
+ */
 export declare class NysDivider extends LitElement {
     static styles: import("lit").CSSResult;
     inverted: boolean;

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

@@ -1,10 +1,19 @@
 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.
+ */
 export declare class NysErrorMessage extends LitElement {
     static styles: import("lit").CSSResult;
     showError: boolean;
     errorMessage: string;
     showDivider: boolean;
     private _internals;
+    /**
+     * Lifecycle methods
+     * --------------------------------------------------------------------------
+     */
     static formAssociated: boolean;
     constructor();
     render(): import("lit-html").TemplateResult<1>;

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

@@ -1,5 +1,22 @@
 import { LitElement } from "lit";
 import "./nys-fileitem";
+/**
+ * `<nys-fileinput>` provides accessible file selection with optional
+ * drag-and-drop support, progress tracking, validation, and form submission.
+ *
+ * Features:
+ * - Supports single or multiple file uploads
+ * - Optional drag-and-drop dropzone
+ * - File type validation and upload progress
+ * - Form-associated with native validation behavior
+ * - Keyboard and screen reader accessible
+ *
+ * @slot description - Custom description content under the label
+ *
+ * @fires nys-change - Fired when files are added or removed
+ *
+ * @returns {boolean} checkValidity - Returns validity state for form validation
+ */
 export declare class NysFileinput extends LitElement {
     static styles: import("lit").CSSResult;
     id: string;
@@ -25,23 +42,39 @@ export declare class NysFileinput extends LitElement {
     private get _buttonAriaDescription();
     private get _innerNysButton();
     private _internals;
+    /**
+     * Lifecycle methods
+     * --------------------------------------------------------------------------
+     */
     static formAssociated: boolean;
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
     firstUpdated(): void;
+    /**
+     * Form Integration
+     * --------------------------------------------------------------------------
+     */
     private _setValue;
     private _manageRequire;
     private _setValidityMessage;
     private _validate;
     checkValidity(): boolean;
     private _handleInvalid;
+    /**
+     * Functions
+     * --------------------------------------------------------------------------
+     */
     private _saveSelectedFiles;
     private _processFile;
     private _dispatchChangeEvent;
     private _openFileDialog;
     private _handlePostFileSelectionFocus;
     private _focusFirstFileItemIfSingleMode;
+    /**
+     * Event Handlers
+     * --------------------------------------------------------------------------
+     */
     private _handleFileChange;
     private _handleFileRemove;
     private _onDragOver;

package/dist/packages/nys-fileinput/src/nys-fileitem.d.ts

@@ -1,4 +1,8 @@
 import { LitElement } from "lit";
+/**
+ * `<nys-fileitem>` displays an individual file in a file input component.
+ * It shows the file name, upload status, progress bar, and error messages.
+ */
 export declare class NysFileItem extends LitElement {
     static styles: import("lit").CSSResult;
     filename: string;

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

@@ -1,10 +1,30 @@
 import { LitElement } from "lit";
+/**
+ * `<nys-globalfooter>` renders a New York State–style global footer.
+ *
+ * Displays an agency name with an optional homepage link and supports
+ * structured footer content via slots.
+ *
+ * @slot default - Footer content such as headings, links, or groups
+ *
+ * Layout behavior:
+ * - Multiple `<h4>` elements trigger a multi-column layout
+ * - Single group content renders in a compact layout
+ */
 export declare class NysGlobalFooter extends LitElement {
     static styles: import("lit").CSSResult;
     agencyName: string;
     homepageLink: string;
     private slotHasContent;
+    /**
+     * Lifecycle Methods
+     * --------------------------------------------------------------------------
+     */
     firstUpdated(): void;
+    /**
+     * Functions
+     * --------------------------------------------------------------------------
+     */
     private _handleSlotChange;
     render(): import("lit-html").TemplateResult<1>;
 }