@nysds/components 1.13.0 → 1.14.0

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

@@ -1,39 +1,64 @@
 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.
+ * A file input for uploading files with support for multiple files, drag-and-drop, and progress tracking.
+ * Validates file types via magic bytes (not just extension). Form-associated via ElementInternals.
  *
- * 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
+ * Use for document uploads, image uploads, or any file submission. Enable `dropzone` for drag-and-drop UI.
  *
- * @slot description - Custom description content under the label
+ * @summary File input with drag-and-drop, validation, and progress tracking.
+ * @element nys-fileinput
  *
- * @fires nys-change - Fired when files are added or removed
+ * @slot description - Custom HTML description content.
  *
- * @returns {boolean} checkValidity - Returns validity state for form validation
+ * @fires nys-change - Fired when files are added or removed. Detail: `{id, files}`.
+ *
+ * @example Single file upload
+ * ```html
+ * <nys-fileinput label="Upload document" accept=".pdf,.doc" required></nys-fileinput>
+ * ```
+ *
+ * @example Multiple files with dropzone
+ * ```html
+ * <nys-fileinput label="Upload images" accept="image/*" multiple dropzone></nys-fileinput>
+ * ```
  */
 export declare class NysFileinput 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. */
     label: string;
+    /** Helper text below label. Use slot for custom HTML. */
     description: string;
+    /** Allows selecting multiple files. */
     multiple: boolean;
+    /** Form `id` to associate with. */
     form: string | null;
+    /** Tooltip text shown on hover/focus of info icon. */
     tooltip: string;
+    /** Accepted file types. Use MIME types (`image/*`) or extensions (`.pdf`). Validated via magic bytes. */
     accept: string;
+    /** Prevents interaction. */
     disabled: boolean;
+    /** Requires at least one file to be uploaded. */
     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;
+    /** Enables drag-and-drop zone UI. */
     dropzone: boolean;
+    /**
+     * Component width: `lg` (384px) or `full` (100%, default).
+     * @default "full"
+     */
     width: "lg" | "full";
+    /** Adjusts colors for dark backgrounds. */
     inverted: boolean;
     private _selectedFiles;
     private _dragActive;
@@ -60,6 +85,7 @@ export declare class NysFileinput extends LitElement {
     private _setValidityMessage;
     private _validate;
     checkValidity(): boolean;
+    formResetCallback(): void;
     private _handleInvalid;
     /**
      * Functions

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

@@ -1,13 +1,27 @@
 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.
+ * **Internal component.** Displays an individual file within `nys-fileinput` with status and progress.
+ *
+ * Rendered automatically by `nys-fileinput` for each selected file. Shows filename, upload status
+ * (pending/processing/done/error), progress bar during upload, and error messages. Remove button emits event.
+ *
+ * @summary Internal file item display with status, progress bar, and remove action.
+ * @element nys-fileitem
+ *
+ * @fires nys-fileRemove - Fired when remove button is clicked. Detail: `{filename}`.
  */
 export declare class NysFileItem extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Name of the file being displayed. */
     filename: string;
+    /**
+     * Upload status: `pending` (queued), `processing` (uploading), `done` (complete), `error` (failed).
+     * @default "pending"
+     */
     status: "pending" | "processing" | "done" | "error";
+    /** Upload progress percentage (0-100). Only shown when status is `processing`. */
     progress: number;
+    /** Error message displayed when status is `error`. */
     errorMessage: string;
     private _handleRemove;
     private splitFilename;

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

@@ -1,19 +1,28 @@
 import { LitElement } from "lit";
 /**
- * `<nys-globalfooter>` renders a New York State–style global footer.
+ * Agency-branded footer with agency name and slotted content sections. Auto-layouts based on content structure.
  *
- * Displays an agency name with an optional homepage link and supports
- * structured footer content via slots.
+ * Place above `nys-unavfooter`. Slot contact info, links, or other content. Use `<h4>` elements
+ * to create multi-column layouts; without `<h4>`, renders as compact single section.
  *
- * @slot default - Footer content such as headings, links, or groups
+ * @summary Agency footer with auto-layout for contact info and link sections.
+ * @element nys-globalfooter
  *
- * Layout behavior:
- * - Multiple `<h4>` elements trigger a multi-column layout
- * - Single group content renders in a compact layout
+ * @slot - Footer content (links, contact info). Use `<h4>` for column headings.
+ *
+ * @example Simple footer
+ * ```html
+ * <nys-globalfooter agencyName="Department of Health" homepageLink="/">
+ *   <span>123 Main St, Albany NY</span>
+ *   <span>info@health.ny.gov</span>
+ * </nys-globalfooter>
+ * ```
  */
 export declare class NysGlobalFooter extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Agency name displayed as the footer heading. */
     agencyName: string;
+    /** URL for the agency name link. If empty, name is not clickable. */
     homepageLink: string;
     private slotHasContent;
     /**

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

@@ -1,23 +1,29 @@
 import { LitElement } from "lit";
 /**
- * `<nys-globalheader>` renders a New York State–style global header.
+ * Agency-branded header with app/agency name, navigation, and responsive mobile menu.
  *
- * Displays an optional application name, agency name, and homepage link.
- * Supports slotted navigation content with automatic active-link detection
- * and a responsive mobile menu.
+ * Place below `nys-unavheader`. Slot navigation links as `<ul><li><a>` elements; active links
+ * are auto-highlighted based on current URL. Mobile menu toggles automatically on narrow screens.
  *
- * @slot default - Primary navigation list, typically a `<ul>` with links
- * @slot user-actions - Optional user action elements such as login or profile
+ * @summary Agency header with navigation, mobile menu, and active link highlighting.
+ * @element nys-globalheader
  *
- * Behavior:
- * - Automatically highlights the best matching link based on the current URL
- * - Duplicates navigation content for desktop and mobile layouts
- * - Provides a toggleable mobile menu when navigation content exists
+ * @slot - Navigation content (typically `<ul>` with `<li><a>` links). Auto-sanitized.
+ *
+ * @example Basic header
+ * ```html
+ * <nys-globalheader appName="My App" agencyName="Department of Health" homepageLink="/">
+ *   <ul><li><a href="/about">About</a></li><li><a href="/contact">Contact</a></li></ul>
+ * </nys-globalheader>
+ * ```
  */
 export declare class NysGlobalHeader extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Application name displayed prominently. */
     appName: string;
+    /** Agency name displayed below app name (or as main title if no appName). */
     agencyName: string;
+    /** URL for the header title link. If empty, title is not clickable. */
     homepageLink: string;
     private isMobileMenuOpen;
     private hasLinkContent;

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

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

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

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

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

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

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

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

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

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

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

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