@nysds/components 1.13.0 → 1.13.1

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

@@ -1,36 +1,79 @@
 import { LitElement } from "lit";
 /**
- * `<nys-textarea>` is a form-enabled textarea with validation, accessibility support,
- * and live error messages. Integrates with forms via ElementInternals.
+ * A multi-line text input for collecting longer responses like comments, descriptions, or feedback.
+ * Form-associated with validation support via ElementInternals.
  *
- * @slot description - Optional slot for custom description content below the label.
+ * Use for detailed responses needing multiple lines. For single-line input, use `nys-textinput`.
+ * For predefined options, use `nys-select`, `nys-radiobutton`, or `nys-checkbox`.
  *
- * @fires nys-input - Fired on input, detail: `{ id, value }`
- * @fires nys-focus - Fired on focus.
- * @fires nys-blur - Fired on blur.
- * @fires nys-select - Fired on text selection, detail: `{ id, value }`
- * @fires nys-selectionchange - Fired on selection change, detail: `{ id, value }`
+ * @summary Multi-line text input for comments, descriptions, and feedback.
+ * @element nys-textarea
+ *
+ * @slot description - Custom HTML description content below the label.
+ *
+ * @fires nys-input - Fired on input change. Detail: `{id, value}`.
+ * @fires nys-focus - Fired when textarea gains focus.
+ * @fires nys-blur - Fired when textarea loses focus. Triggers validation.
+ * @fires nys-select - Fired when user selects text. Detail: `{id, value}`.
+ *
+ * @example Basic textarea
+ * ```html
+ * <nys-textarea label="Comments" rows="4"></nys-textarea>
+ * ```
+ *
+ * @example Required with description
+ * ```html
+ * <nys-textarea label="Describe the incident" description="Please provide details" required></nys-textarea>
+ * ```
  */
 export declare class NysTextarea extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Unique identifier. Auto-generated if not provided. */
     id: string;
+    /** Name for form submission. */
     name: string;
+    /** Visible label text. Required for accessibility. */
     label: string;
+    /** Helper text below label. Use slot for custom HTML. */
     description: string;
+    /** Placeholder text. Don't use as label replacement. */
     placeholder: string;
+    /** Current textarea value. */
     value: string;
+    /** Prevents interaction. */
     disabled: boolean;
+    /** Makes textarea read-only but focusable. */
     readonly: boolean;
+    /** Marks as required. Shows "Required" flag and validates on blur. */
     required: boolean;
+    /** Shows "Optional" flag. Use when most fields are required. */
     optional: boolean;
+    /** Tooltip text shown on hover/focus of info icon. */
     tooltip: string;
+    /** Adjusts colors for dark backgrounds. */
     inverted: boolean;
+    /** Form `id` to associate with when textarea is outside form element. */
     form: string | null;
+    /** Maximum character length. */
     maxlength: number | null;
+    /**
+     * Textarea width: `sm` (88px), `md` (200px), `lg` (384px), `full` (100%, default).
+     * @default "full"
+     */
     width: "sm" | "md" | "lg" | "full";
+    /**
+     * Visible height in lines.
+     * @default 4
+     */
     rows: number;
+    /**
+     * Resize behavior: `vertical` (default, user can resize height), `none` (fixed size).
+     * @default "vertical"
+     */
     resize: "vertical" | "none";
+    /** Shows error message when true. Set by validation or manually. */
     showError: boolean;
+    /** Error message text. Shown only when `showError` is true. */
     errorMessage: string;
     updated(changedProperties: Map<string | number | symbol, unknown>): Promise<void>;
     private _hasUserInteracted;

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

@@ -1,40 +1,95 @@
 import { LitElement } from "lit";
 /**
- * `<nys-textinput>` is a form-enabled text input with validation, optional
- * masking, password toggle, accessibility support, and live error messages.
- * Works with forms via ElementInternals.
+ * A text input for collecting short, single-line data. Supports validation, input masking (tel),
+ * password visibility toggle, and live error messaging. Form-associated via ElementInternals.
  *
- * @slot description - Optional custom description content below the label.
- * @slot startButton - Slot for a single <nys-button> at the start of the input.
- * @slot endButton - Slot for a single <nys-button> at the end of the input.
+ * Use for names, emails, passwords, phone numbers. For multi-line input, use `nys-textarea` instead.
+ * For predefined options, use `nys-select`, `nys-radiobutton`, or `nys-checkbox`.
  *
- * @fires nys-input - Fired on input change. Detail: `{ id, value }`.
- * @fires nys-focus - Fired when input receives focus.
- * @fires nys-blur - Fired when input loses focus.
+ * @summary Text input for short single-line data with validation and masking support.
+ * @element nys-textinput
+ *
+ * @slot description - Custom HTML description content below the label.
+ * @slot startButton - Button at input start. Use single `nys-button` only.
+ * @slot endButton - Button at input end. Use single `nys-button` only.
+ *
+ * @fires nys-input - Fired on input change. Detail: `{id, value}`.
+ * @fires nys-focus - Fired when input gains focus.
+ * @fires nys-blur - Fired when input loses focus. Triggers validation.
+ *
+ * @example Basic text input
+ * ```html
+ * <nys-textinput label="Full Name" required></nys-textinput>
+ * ```
+ *
+ * @example Email with validation
+ * ```html
+ * <nys-textinput type="email" label="Email Address" required></nys-textinput>
+ * ```
+ *
+ * @example Phone with masking
+ * ```html
+ * <nys-textinput type="tel" label="Phone Number"></nys-textinput>
+ * ```
+ *
+ * @example Search with button
+ * ```html
+ * <nys-textinput type="search" placeholder="Search">
+ *   <nys-button slot="endButton" label="Search" prefixIcon="search"></nys-button>
+ * </nys-textinput>
+ * ```
  */
 export declare class NysTextinput extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Unique identifier. Auto-generated if not provided. */
     id: string;
+    /** Name for form submission. */
     name: string;
+    /**
+     * Input type: `text` (default), `email`, `number`, `password`, `search`, `tel` (auto-masked), `url`.
+     * @default "text"
+     */
     type: "email" | "number" | "password" | "search" | "tel" | "text" | "url";
+    /** Visible label text. Required for accessibility. */
     label: string;
+    /** Helper text below label. Use slot for custom HTML. */
     description: string;
+    /** Placeholder text. Don't use as label replacement. */
     placeholder: string;
+    /** Current input value. */
     value: string;
+    /** Prevents interaction. */
     disabled: boolean;
+    /** Makes input read-only but focusable. */
     readonly: boolean;
+    /** Marks as required. Shows "Required" flag and validates on blur. */
     required: boolean;
+    /** Shows "Optional" flag. Use when most fields are required. */
     optional: boolean;
+    /** Tooltip text shown on hover/focus of info icon. */
     tooltip: string;
+    /** Form `id` to associate with when input is outside form element. */
     form: string | null;
+    /** Regex pattern for validation. Shows error on mismatch. */
     pattern: string;
+    /** Maximum character length. */
     maxlength: number | null;
+    /**
+     * Input width: `sm` (88px), `md` (200px), `lg` (384px), `full` (100%, default).
+     * @default "full"
+     */
     width: "sm" | "md" | "lg" | "full";
+    /** Step increment for `type="number"`. */
     step: number | null;
+    /** Minimum value for `type="number"`. */
     min: number | null;
+    /** Maximum value for `type="number"`. */
     max: number | null;
+    /** Adjusts colors for dark backgrounds. */
     inverted: boolean;
+    /** Shows error message when true. Set by validation or manually. */
     showError: boolean;
+    /** Error message text. Shown only when `showError` is true. */
     errorMessage: string;
     private showPassword;
     private _originalErrorMessage;

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

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

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

@@ -1,25 +1,34 @@
 import { LitElement } from "lit";
 /**
- * `<nys-tooltip>` is a custom tooltip component for NYS design system elements.
- * It supports dynamic positioning, screen-reader accessibility, keyboard interaction,
- * and viewport overflow handling.
+ * Shows contextual help text on hover/focus. Auto-positions to stay within viewport and supports keyboard dismiss.
  *
- * The tooltip automatically positions itself relative to a target element specified
- * via the `for` attribute, but can also respect a user-defined position.
+ * Link to a trigger element via `for` attribute matching the trigger's `id`. Tooltip appears on hover or focus
+ * and dismisses on blur, mouse leave, or Escape key. Use for supplementary info only—not critical content.
  *
- * @fires nys-focus - Dispatched when the reference element receives focus (via keyboard or programmatically).
- * @fires nys-blur - Dispatched when the reference element loses focus or mouse leaves the tooltip.
+ * @summary Contextual tooltip with auto-positioning, keyboard support, and screen reader integration.
+ * @element nys-tooltip
  *
- * Notes:
- * - Tooltip visibility is automatically managed on hover/focus of the reference element.
- * - The component adjusts position dynamically to prevent overflow off-screen.
- * - Supports keyboard dismissal with the Escape key.
+ * @example Tooltip for button
+ * ```html
+ * <nys-button id="help-btn" label="Help" circle icon="help"></nys-button>
+ * <nys-tooltip for="help-btn" text="Click for assistance"></nys-tooltip>
+ * ```
+ *
+ * @example Positioned tooltip
+ * ```html
+ * <nys-icon id="info-icon" name="info"></nys-icon>
+ * <nys-tooltip for="info-icon" text="Additional details" position="right"></nys-tooltip>
+ * ```
  */
 export declare class NysTooltip extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Unique identifier. Auto-generated if not provided. */
     id: string;
+    /** Tooltip content text. Required. */
     text: string;
+    /** Adjusts colors for dark backgrounds. */
     inverted: boolean;
+    /** ID of the trigger element to attach this tooltip to. Required. */
     for: string;
     private _active;
     private _userHasSetPosition;
@@ -27,6 +36,10 @@ export declare class NysTooltip extends LitElement {
     private _internallyUpdatingPosition;
     private _hideTimeout;
     private _position;
+    /**
+     * Preferred position relative to trigger. Auto-adjusts if space is insufficient.
+     * @default null (auto-positioned based on available space)
+     */
     get position(): "right" | "top" | "bottom" | "left" | null;
     set position(value: "right" | "top" | "bottom" | "left" | null);
     /**

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

@@ -1,11 +1,18 @@
 import { LitElement } from "lit";
 /**
- * `<nys-unavfooter>` is a footer component for New York State websites.
- * It displays the official NYS logo linking to ny.gov and a set of primary navigation links.
+ * Universal NYS footer with logo and statewide navigation links. Required on all NYS sites.
  *
- * Features:
- * - Renders the NYS logo as an inline SVG linking to https://www.ny.gov
- * - Provides key navigation links
+ * Place as the last element before `</body>`. Displays NY.gov logo and links to Agencies,
+ * App Directory, Counties, Events, Programs, and Services. No configuration needed.
+ *
+ * @summary Universal NYS footer with logo and statewide links. Required site-wide.
+ * @element nys-unavfooter
+ *
+ * @example Standard usage
+ * ```html
+ * <nys-globalfooter>...</nys-globalfooter>
+ * <nys-unavfooter></nys-unavfooter>
+ * ```
  */
 export declare class NysUnavFooter extends LitElement {
     static styles: import("lit").CSSResult;

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

@@ -1,22 +1,40 @@
 import { LitElement } from "lit";
 /**
- * `<nys-unavheader>` is a universal header for New York State websites.
+ * Universal NYS header with trust bar, logo, search, and language translation. Required on all NYS sites.
  *
- * Features:
- * - Trust bar indicating official NYS site status, with expandable details
- * - NYS logo linking to the homepage
- * - Search bar with dropdown behavior for mobile and desktop
- * - Language translation dropdown supporting multiple languages
- * - Accessible interactions with ARIA attributes and keyboard handling
+ * Place as the first element in `<body>`. Includes "official site" trust indicator, NY.gov logo,
+ * site search (searches ny.gov), and 14-language translation dropdown. Use `hideSearch` or `hideTranslate`
+ * to remove features if not applicable.
+ *
+ * @summary Universal NYS header with trust bar, search, and translation. Required site-wide.
+ * @element nys-unavheader
+ *
+ * @example Standard usage
+ * ```html
+ * <nys-unavheader></nys-unavheader>
+ * <nys-globalheader>...</nys-globalheader>
+ * ```
+ *
+ * @example Without search
+ * ```html
+ * <nys-unavheader hideSearch></nys-unavheader>
+ * ```
  */
 export declare class NysUnavHeader extends LitElement {
     static styles: import("lit").CSSResult;
+    /** Internal: Whether trust bar panel is expanded. */
     trustbarVisible: boolean;
+    /** Internal: Whether search dropdown is visible (mobile). */
     searchDropdownVisible: boolean;
+    /** Internal: Whether language dropdown is visible. */
     languageVisible: boolean;
+    /** Internal: Whether search input is focused. */
     isSearchFocused: boolean;
+    /** Hides the translation dropdown. */
     hideTranslate: boolean;
+    /** Hides the search functionality. */
     hideSearch: boolean;
+    searchUrl: string;
     private languages;
     /**
      * Lifecycle Methods

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nysds/components",
-  "version": "1.13.0",
+  "version": "1.13.1",
   "description": "New York State's design system and code component library.",
   "type": "module",
   "workspaces": [
@@ -8,7 +8,7 @@
   ],
   "files": [
     "dist/",
-    "!nys-stepper/"
+    "custom-elements.json"
   ],
   "main": "dist/nysds.js",
   "module": "dist/nysds.es.js",
@@ -20,31 +20,33 @@
       "require": "./dist/nysds.js"
     }
   },
+  "customElements": "custom-elements.json",
   "scripts": {
     "dev": "vite",
     "gen": "plop",
     "build": "tsc --emitDeclarationOnly && vite build",
     "build:umd": "tsc --emitDeclarationOnly && vite build --config vite.config.umd.js",
     "build:packages": "node src/scripts/build-order.js",
-    "build:all": "npm run clean:dist && npm run lit-analyze && npm run lint && NODE_ENV=production npm run build:packages && NODE_ENV=production npm run build && NODE_ENV=production npm run build:umd && npm run cem",
+    "build:all": "npm run clean:dist && npm run lint && cross-env NODE_ENV=production npm run build:packages && cross-env NODE_ENV=production npm run build && cross-env NODE_ENV=production npm run build:umd && npm run lit-analyze || true && npm run cem && npm run cem:copy",
     "build:link": "npm run build:all && npm link",
     "lint": "eslint",
     "lint:fix": "eslint --fix",
-    "lit-analyze": "lit-analyzer $(find ./packages -name '*.ts' ! -name '*.figma.*')",
-    "release": "NODE_ENV=production npm run build:all && NODE_ENV=production npm run test && npm run cem && NODE_ENV=production npm publish --workspaces --access public && NODE_ENV=production npm publish --access public",
-    "release:dry-run": "NODE_ENV=production npm run build:all && NODE_ENV=production npm run test && npm run cem && node src/scripts/publish-dry-run.js",
+    "lit-analyze": "find ./packages/nys-*/ -name '*.ts' ! -name '*.figma.*' | xargs lit-analyzer {}",
+    "release": "cross-env NODE_ENV=production npm run build:all && cross-env NODE_ENV=production npm run test && npm run cem && cross-env NODE_ENV=production npm publish --workspaces --access public && cross-env NODE_ENV=production npm publish --access public",
+    "release:dry-run": "cross-env NODE_ENV=production npm run build:all && cross-env NODE_ENV=production npm run test && npm run cem && node src/scripts/publish-dry-run.js",
     "release:alpha": "npm run build && npm run build:umd && npm publish --tag next",
     "test": "npx playwright install && wtr --node-resolve",
     "test:build": "npm run build:all && npm run test",
-    "storybook": "NODE_ENV=production storybook dev -p 6006",
-    "storybook:build:all": "NODE_ENV=production npm run build:all && npm run storybook",
+    "storybook": "cross-env NODE_ENV=production storybook dev -p 6006",
+    "storybook:build:all": "cross-env NODE_ENV=production npm run build:all && npm run storybook",
     "build-storybook": "npm run build:packages && storybook build",
     "storybook:cibuild": "storybook build",
     "clean:node": "rm -rf node_modules && rm -rf packages/*/node_modules && rm -rf packages/**/*/node_modules",
     "clean:dist": "rm -rf storybook-static && rm -rf coverage && rm -rf packages/*/coverage && rm -rf dist && rm -rf packages/*/dist && rm -rf packages/**/*/dist",
     "clean:all": "npm run clean:dist && npm run clean:node",
     "code-connect": "dotenv -- npx figma connect publish",
-    "cem": "npx cem analyze --config 'custom-elements-manifest.config.mjs'"
+    "cem": "npx cem analyze --config ./custom-elements-manifest.config.mjs",
+    "cem:copy": "cp ./custom-elements.json dist/"
   },
   "repository": {
     "type": "git",
@@ -74,6 +76,7 @@
     "@web/test-runner": "^0.20.2",
     "@web/test-runner-commands": "^0.9.0",
     "@web/test-runner-playwright": "^0.11.1",
+    "cross-env": "^10.1.0",
     "custom-element-react-wrappers": "^1.7.3",
     "custom-element-vs-code-integration": "^1.5.0",
     "dotenv-cli": "^10.0.0",
@@ -103,7 +106,6 @@
   "overrides": {
     "storybook": "$storybook"
   },
-  "customElements": "dist/custom-elements.json",
   "dependencies": {
     "wc-datepicker": "^0.9.2"
   }