@nysds/components 1.19.3-alpha-1 → 1.19.3

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

@@ -13,16 +13,78 @@ declare global {
  *
  * For use with YouTube URLs only. Component renders nothing if the URL is invalid.
  *
+ * @accessibility
+ * - Title text is announced to screen readers when the video is not yet loaded.
+ * - When the video loads, the iframe title and aria-label are set to the `titleText`.
+ * - Live region announces playback state ("Video is playing", "Advertisement is playing").
+ * - Play button is properly labeled and keyboard accessible.
+ * - Disabled state prevents play button interaction.
+ * - Focus is transferred to the iframe once the video is loaded (for keyboard users).
+ *
  * @summary YouTube video player with thumbnail preview and accessibility announcements.
  * @element nys-video
  *
  * @fires nys-video-play - Fired when the user clicks the thumbnail to load the player.
  *
- * @example Basic usage
+ * @example Basic
+ * ```html
+ * <nys-video
+ *   videourl="https://www.youtube.com/watch?v=TBfFzt0150Q"
+ *   titleText="IT'S a Tech Podcast, Episode 3: Human-Centered Design"
+ * ></nys-video>
+ * ```
+ *
+ * @example Thumbnail
+ * ```html
+ * <nys-video
+ *  videourl="https://www.youtube.com/watch?v=TBfFzt0150Q"
+ *  titleText="IT'S a Tech Podcast, Episode 3: Human-Centered Design"
+ *  thumbnail="https://designsystem.ny.gov/assets/img/homepage-grid-3.svg"
+ * ></nys-video>
+ * ```
+ *
+ * @example Autoplay
+ * ```html
+ * <nys-video
+ *   videourl="https://www.youtube.com/watch?v=TBfFzt0150Q"
+ *   titleText="IT'S a Tech Podcast, Episode 3: Human-Centered Design"
+ *   autoplay
+ * ></nys-video>
+ * ```
+ *
+ * @example Start Time
+ * ```html
+ * <nys-video
+ *   videourl="https://www.youtube.com/watch?v=TBfFzt0150Q"
+ *   titleText="IT'S a Tech Podcast, Episode 3: Human-Centered Design"
+ *   starttime="43"
+ * ></nys-video>
+ * ```
+ *
+ * @example Disabled
+ * ```html
+ * <nys-video
+ *   videourl="https://www.youtube.com/watch?v=TBfFzt0150Q"
+ *   titleText="IT'S a Tech Podcast, Episode 3: Human-Centered Design"
+ *   disabled
+ * ></nys-video>
+ * ```
+ *
+ * @example Size full
+ * ```html
+ * <nys-video
+ *   size="full"
+ *   videourl="https://www.youtube.com/watch?v=TBfFzt0150Q"
+ *   titleText="Small (width: 320-439px)"
+ * ></nys-video>
+ * ```
+ *
+ * @example Size small
  * ```html
  * <nys-video
- *   videourl="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
- *   titleText="Video Title"
+ *   size="sm"
+ *   videourl="https://www.youtube.com/watch?v=TBfFzt0150Q"
+ *   titleText="Small (width: 320-439px)"
  * ></nys-video>
  * ```
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nysds/components",
-  "version": "1.19.3-alpha-1",
+  "version": "1.19.3",
   "description": "New York State's design system and code component library.",
   "type": "module",
   "workspaces": [
@@ -29,12 +29,14 @@
   "scripts": {
     "dev": "vite",
     "gen": "plop",
+    "gen-stories": "npm run cem && node src/scripts/generate-stories.mjs",
+    "gen-stories:component": "npm run cem && sh -c 'node src/scripts/generate-stories.mjs \"$@\" && npm run lint:fix' --",
     "build": "tsc --emitDeclarationOnly && vite build",
     "build:umd": "cross-env BUILD_FORMAT=umd vite build",
     "tsc:packages": "tsc -b tsconfig.build.json",
     "build:packages": "npm run tsc:packages && turbo run build --filter='./packages/*' --log-order=grouped",
     "build:root": "cross-env NODE_ENV=production npm run build && cross-env NODE_ENV=production npm run build:umd",
-    "build:all": "npm run clean:dist && npm run lint && npm run lit-analyze || true && cross-env NODE_ENV=production npm run build:packages && npm run build:root && npm run cem && npm run build:mcp",
+    "build:all": "npm run clean:dist && npm run lit-analyze || true && cross-env NODE_ENV=production npm run build:packages && npm run build:root && npm run cem && npm run gen-stories && npm run build:mcp && npm run lint:fix",
     "build:mcp": "npm run build -w @nysds/mcp-server",
     "build:link": "npm run build:all && npm link && cd packages/styles && npm link",
     "lint": "eslint --cache --cache-strategy=content --cache-location node_modules/.cache/eslint && (stylelint \"**/*.scss\" || true)",
@@ -47,7 +49,8 @@
     "release:zip": "npm run build:all && node src/scripts/create-release-zip.js",
     "pretest": "playwright install",
     "test": "wtr --node-resolve",
-    "test:ssr": "node scripts/test-ssr.mjs",
+    "test:ssr": "node src/scripts/test-ssr.mjs && npm run audit:dist",
+    "audit:dist": "node src/scripts/audit-dist.mjs",
     "test:build": "npm run build:all && npm run test",
     "test:compact": "export NYSDS_TEST_OUTPUT=compact && wtr --node-resolve",
     "test:ai": "export NYSDS_TEST_OUTPUT=ai && wtr --node-resolve",
@@ -62,7 +65,7 @@
     "clean:cache": "rm -rf node_modules/.cache",
     "clean:all": "npm run clean:dist && npm run clean:node && npm run clean:cache && find packages -name '*.tsbuildinfo' -delete 2>/dev/null || true && npm run clean:turbo",
     "code-connect": "dotenv -- npx figma connect publish",
-    "cem": "npx cem analyze --config ./custom-elements-manifest.config.mjs && cp ./custom-elements.json dist/ && node src/scripts/patch-react-utils.js"
+    "cem": "npx cem analyze --config src/scripts/custom-elements-manifest.config.mjs && cp ./custom-elements.json dist/ && node src/scripts/patch-react-utils.js"
   },
   "repository": {
     "type": "git",
@@ -136,5 +139,8 @@
     "dompurify": "^3.4.7",
     "wc-datepicker": "^0.10.0"
   },
-  "sideEffects": true
+  "sideEffects": true,
+  "peerDependencies": {
+    "lit": "^3.3.1"
+  }
 }

package/packages/react/NysBreadcrumbs.d.ts

@@ -84,6 +84,6 @@ Override when multiple crumbs exist on the same page. */
  * - **nys-breadcrumbs-expand** - Fired when the user clicks the ellipsis to expand the trail.
  *
  * ### **Slots:**
- *  - _default_ - One or more `nys-breadcrumbitem` elements defining the trail.
+ *  - _default_ - One or more `li` elements defining the trail.
  */
 export const NysBreadcrumbs: React.ForwardRefExoticComponent<NysBreadcrumbsProps>;

package/packages/react/NysButton.d.ts

@@ -123,7 +123,8 @@ export interface NysButtonProps extends Pick<
  * - **nys-click** - Fired when the button is clicked (mouse or keyboard). Not fired when disabled.
  *
  * ### **Slots:**
- *  - **prefix-icon** - Icon before label. Not shown for `text` variant.
+ *  - _default_ - Button label text. Use as fallback when `label` prop is not provided.
+ * - **prefix-icon** - Icon before label. Not shown for `text` variant.
  * - **suffix-icon** - Icon after label. Not shown for `text` variant.
  * - **circle-icon** - Icon for circle mode. Overrides `icon` prop.
  *

package/packages/react/NysDropdownMenu.d.ts

@@ -50,7 +50,7 @@ export interface NysDropdownMenuProps extends Pick<
 }
 
 /**
- *
+ * Action menu with auto-positioning, keyboard support, and screen reader integration.
  * ---
  *
  */

package/packages/react/NysFileinput.d.ts

@@ -1,10 +1,11 @@
 import React from "react";
 import {
   NysFileinput as NysFileinputElement,
+  Event,
   CustomEvent,
 } from "../../dist/nysds.es.js";
 
-export type { NysFileinputElement, CustomEvent };
+export type { NysFileinputElement, Event, CustomEvent };
 
 export interface NysFileinputProps extends Pick<
   React.AllHTMLAttributes<HTMLElement>,
@@ -90,6 +91,20 @@ export interface NysFileinputProps extends Pick<
   /** Allows developers to make HTML elements focusable, allow or prevent them from being sequentially focusable (usually with the `Tab` key, hence the name) and determine their relative ordering for sequential focus navigation. */
   tabIndex?: number;
 
+  /** The currently selected files. Read to get the current selection; set to
+replace it (e.g. rehydrating state after navigation, or binding from a
+framework form model). Property-only — a `File[]` cannot round-trip through
+an HTML attribute. Setting this is silent (does not emit `nys-change`),
+matching native input behavior and avoiding feedback loops in two-way bindings. */
+  files?: NysFileinputElement["files"];
+
+  /** Single-file convenience accessor (parity with `nys-textinput`'s `value`).
+Reads the first selected file (or `null`); setting replaces the selection. */
+  value?: NysFileinputElement["value"];
+
+  /** Fired when focus leaves the component. Triggers validation. */
+  onNysBlur?: (event: CustomEvent) => void;
+
   /** Fired when files are added or removed. Detail: `{id, files}`. */
   onNysChange?: (event: CustomEvent) => void;
 }
@@ -100,7 +115,14 @@ export interface NysFileinputProps extends Pick<
  *
  *
  * ### **Events:**
- *  - **nys-change** - Fired when files are added or removed. Detail: `{id, files}`.
+ *  - **nys-blur** - Fired when focus leaves the component. Triggers validation.
+ * - **nys-change** - Fired when files are added or removed. Detail: `{id, files}`.
+ *
+ * ### **Methods:**
+ *  - **setFiles(incoming: _File[]_): _Promise<void>_** - Programmatically set the selection and await async validation/processing.
+ * Same as assigning `files`, but resolves once every file has finished its
+ * magic-byte validation and read — use when you need to read `checkValidity()`
+ * or the settled selection immediately after.
  *
  * ### **Slots:**
  *  - **description** - Custom HTML description content.

package/packages/react/NysFileinput.js

@@ -1,6 +1,6 @@
 import React, { forwardRef, useRef, useEffect } from "react";
 import "../../dist/nysds.es.js";
-import { useEventListener } from "./react-utils.js";
+import { useEventListener, useProperties } from "./react-utils.js";
 
 export const NysFileinput = forwardRef((props, forwardedRef) => {
   const ref = useRef(null);
@@ -21,12 +21,19 @@ export const NysFileinput = forwardRef((props, forwardedRef) => {
     accept,
     errorMessage,
     width,
+    files,
+    value,
     ...filteredProps
   } = props;
 
   /** Event listeners - run once */
+  useEventListener(ref, "nys-blur", props.onNysBlur);
   useEventListener(ref, "nys-change", props.onNysChange);
 
+  /** Properties - run whenever a property has changed */
+  useProperties(ref, "files", props.files);
+  useProperties(ref, "value", props.value);
+
   return React.createElement(
     "nys-fileinput",
     {

package/packages/react/NysGlobalHeader.d.ts

@@ -18,7 +18,11 @@ export interface NysGlobalHeaderProps extends Pick<
   | "onFocus"
   | "onBlur"
 > {
-  /** Toggles the NYS brand mark */
+  /** Displays the NYS brand mark in the header. Off by default.
+
+Enable only for internal, state-employee (back-office) applications that omit
+`nys-unavheader`. Any resident-facing app — even one requiring login — should
+keep `nys-unavheader` for trust and leave this off. */
   nysLogo?: boolean;
 
   /** Application name displayed prominently. */
@@ -59,5 +63,6 @@ export interface NysGlobalHeaderProps extends Pick<
  *
  * ### **Slots:**
  *  - _default_ - Navigation content (typically `<ul>` with `<li><a>` links). Auto-sanitized.
+ * - **user-actions** - User-account controls (e.g. profile link, settings, log-out button) shown in the header.
  */
 export const NysGlobalHeader: React.ForwardRefExoticComponent<NysGlobalHeaderProps>;

package/packages/react/NysLabel.d.ts

@@ -65,7 +65,10 @@ export interface NysLabelProps extends Pick<
 }
 
 /**
- * Internal label component for form fields with flag and tooltip support.
+ * **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.
  * ---
  *
  *

package/packages/react/NysTextarea.d.ts

@@ -25,7 +25,7 @@ export interface NysTextareaProps extends Pick<
   /** Prevents interaction. */
   disabled?: boolean;
 
-  /** Makes textarea read-only but focusable. */
+  /** Makes textarea readonly but focusable. */
   readonly?: boolean;
 
   /** Marks as required. Shows "Required" flag and validates on blur. */

package/packages/react/NysUnavHeader.d.ts

@@ -62,11 +62,21 @@ export interface NysUnavHeaderProps extends Pick<
 
   /** Allows developers to make HTML elements focusable, allow or prevent them from being sequentially focusable (usually with the `Tab` key, hence the name) and determine their relative ordering for sequential focus navigation. */
   tabIndex?: number;
+
+  /** Fired when a language is selected. Detail: `{language: {code, label, url?}}`. Cancelable; `preventDefault()` overrides the default Smartling redirect. */
+  onNysLanguageSelect?: (event: CustomEvent) => void;
+
+  /** Fired when a search is submitted. Detail: `{query}`. Cancelable; `preventDefault()` overrides the default search redirect. */
+  onNysSearchSubmit?: (event: CustomEvent) => void;
 }
 
 /**
- *
+ * Universal NYS header with trust bar, search, and translation. Required site-wide.
  * ---
  *
+ *
+ * ### **Events:**
+ *  - **nys-language-select** - Fired when a language is selected. Detail: `{language: {code, label, url?}}`. Cancelable; `preventDefault()` overrides the default Smartling redirect.
+ * - **nys-search-submit** - Fired when a search is submitted. Detail: `{query}`. Cancelable; `preventDefault()` overrides the default search redirect.
  */
 export const NysUnavHeader: React.ForwardRefExoticComponent<NysUnavHeaderProps>;

package/packages/react/NysUnavHeader.js

@@ -1,7 +1,9 @@
-import React, { forwardRef } from "react";
+import React, { forwardRef, useRef, useEffect } from "react";
 import "../../dist/nysds.es.js";
+import { useEventListener } from "./react-utils.js";
 
 export const NysUnavHeader = forwardRef((props, forwardedRef) => {
+  const ref = useRef(null);
   const {
     trustbarVisible,
     searchDropdownVisible,
@@ -14,9 +16,21 @@ export const NysUnavHeader = forwardRef((props, forwardedRef) => {
     ...filteredProps
   } = props;
 
+  /** Event listeners - run once */
+  useEventListener(ref, "nys-language-select", props.onNysLanguageSelect);
+  useEventListener(ref, "nys-search-submit", props.onNysSearchSubmit);
+
   return React.createElement(
     "nys-unavheader",
     {
+      ref: (node) => {
+        ref.current = node;
+        if (typeof forwardedRef === "function") {
+          forwardedRef(node);
+        } else if (forwardedRef) {
+          forwardedRef.current = node;
+        }
+      },
       ...filteredProps,
       searchUrl: props.searchUrl,
       languages: props.languages,

package/packages/react/nysds-jsx.d.ts

@@ -180,7 +180,7 @@ export type NysBreadcrumbsProps = {
 Override when multiple crumbs exist on the same page. */
   ariaLabel?: string;
   /** Controls the visual size of the breadcrumb text and spacing: `sm` for dense layouts, `md` (default) for standard use. */
-  size?: "sm" | "md" | "";
+  size?: "sm" | "md";
   /** On mobile, renders the trail as a single back-to-parent link pointing to the item before the current page.
 Has no effect on desktop or when only one item is present (which always renders as a back link). */
   backToParent?: boolean;
@@ -287,6 +287,8 @@ export type NysCheckboxProps = {
   showOtherError?: boolean;
   /**  */
   _hasDescription?: string;
+  /**  */
+  _isStandalone?: string;
   /** Fired when checked state changes. Detail: `{id, checked, name, value}`. */
   "onnys-change"?: (e: CustomEvent<CustomEvent>) => void;
   /** Fired when "other" text input value changes. Detail: `{id, name, value}`. */
@@ -496,7 +498,17 @@ export type NysFileinputProps = {
   width?: "lg" | "full";
   /** Adjusts colors for dark backgrounds. */
   inverted?: boolean;
-
+  /** The currently selected files. Read to get the current selection; set to
+replace it (e.g. rehydrating state after navigation, or binding from a
+framework form model). Property-only — a `File[]` cannot round-trip through
+an HTML attribute. Setting this is silent (does not emit `nys-change`),
+matching native input behavior and avoiding feedback loops in two-way bindings. */
+  files?: File[];
+  /** Single-file convenience accessor (parity with `nys-textinput`'s `value`).
+Reads the first selected file (or `null`); setting replaces the selection. */
+  value?: File | null;
+  /** Fired when focus leaves the component. Triggers validation. */
+  "onnys-blur"?: (e: CustomEvent<Event>) => void;
   /** Fired when files are added or removed. Detail: `{id, files}`. */
   "onnys-change"?: (e: CustomEvent<CustomEvent>) => void;
 };
@@ -531,7 +543,11 @@ export type NysGlobalHeaderProps = {
   agencyName?: string;
   /** URL for the header title link. If empty, title is not clickable. */
   homepageLink?: string;
-  /** Toggles the NYS brand mark */
+  /** Displays the NYS brand mark in the header. Off by default.
+
+Enable only for internal, state-employee (back-office) applications that omit
+`nys-unavheader`. Any resident-facing app — even one requiring login — should
+keep `nys-unavheader` for trust and leave this off. */
   nysLogo?: boolean;
 };
 
@@ -862,7 +878,7 @@ export type NysTextareaProps = {
   value?: string;
   /** Prevents interaction. */
   disabled?: boolean;
-  /** Makes textarea read-only but focusable. */
+  /** Makes textarea readonly but focusable. */
   readonly?: boolean;
   /** Marks as required. Shows "Required" flag and validates on blur. */
   required?: boolean;
@@ -1019,6 +1035,11 @@ export type NysUnavHeaderProps = {
   searchUrl?: string;
   /** The list of languages this site can be translated to, default to use Smartling */
   languages?: Language[];
+
+  /** Fired when a language is selected. Detail: `{language: {code, label, url?}}`. Cancelable; `preventDefault()` overrides the default Smartling redirect. */
+  "onnys-language-select"?: (e: CustomEvent<never>) => void;
+  /** Fired when a search is submitted. Detail: `{query}`. Cancelable; `preventDefault()` overrides the default search redirect. */
+  "onnys-search-submit"?: (e: CustomEvent<never>) => void;
 };
 
 export type NysVideoProps = {
@@ -1123,7 +1144,7 @@ export type CustomElements = {
    * - **nys-breadcrumbs-expand** - Fired when the user clicks the ellipsis to expand the trail.
    *
    * ### **Slots:**
-   *  - _default_ - One or more `nys-breadcrumbitem` elements defining the trail.
+   *  - _default_ - One or more `li` elements defining the trail.
    */
   "nys-breadcrumbs": Partial<NysBreadcrumbsProps & BaseProps & BaseEvents>;
 
@@ -1138,7 +1159,8 @@ export type CustomElements = {
    * - **nys-click** - Fired when the button is clicked (mouse or keyboard). Not fired when disabled.
    *
    * ### **Slots:**
-   *  - **prefix-icon** - Icon before label. Not shown for `text` variant.
+   *  - _default_ - Button label text. Use as fallback when `label` prop is not provided.
+   * - **prefix-icon** - Icon before label. Not shown for `text` variant.
    * - **suffix-icon** - Icon after label. Not shown for `text` variant.
    * - **circle-icon** - Icon for circle mode. Overrides `icon` prop.
    *
@@ -1240,7 +1262,7 @@ export type CustomElements = {
   "nys-divider": Partial<NysDividerProps & BaseProps & BaseEvents>;
 
   /**
-   *
+   * Action menu with auto-positioning, keyboard support, and screen reader integration.
    * ---
    *
    */
@@ -1269,7 +1291,14 @@ export type CustomElements = {
    *
    *
    * ### **Events:**
-   *  - **nys-change** - Fired when files are added or removed. Detail: `{id, files}`.
+   *  - **nys-blur** - Fired when focus leaves the component. Triggers validation.
+   * - **nys-change** - Fired when files are added or removed. Detail: `{id, files}`.
+   *
+   * ### **Methods:**
+   *  - **setFiles(incoming: _File[]_): _Promise<void>_** - Programmatically set the selection and await async validation/processing.
+   * Same as assigning `files`, but resolves once every file has finished its
+   * magic-byte validation and read — use when you need to read `checkValidity()`
+   * or the settled selection immediately after.
    *
    * ### **Slots:**
    *  - **description** - Custom HTML description content.
@@ -1303,6 +1332,7 @@ export type CustomElements = {
    *
    * ### **Slots:**
    *  - _default_ - Navigation content (typically `<ul>` with `<li><a>` links). Auto-sanitized.
+   * - **user-actions** - User-account controls (e.g. profile link, settings, log-out button) shown in the header.
    */
   "nys-globalheader": Partial<NysGlobalHeaderProps & BaseProps & BaseEvents>;
 
@@ -1317,7 +1347,10 @@ export type CustomElements = {
   "nys-icon": Partial<NysIconProps & BaseProps & BaseEvents>;
 
   /**
-   * Internal label component for form fields with flag and tooltip support.
+   * **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.
    * ---
    *
    *
@@ -1596,9 +1629,13 @@ export type CustomElements = {
   "nys-unavfooter": Partial<NysUnavFooterProps & BaseProps & BaseEvents>;
 
   /**
-   *
+   * Universal NYS header with trust bar, search, and translation. Required site-wide.
    * ---
    *
+   *
+   * ### **Events:**
+   *  - **nys-language-select** - Fired when a language is selected. Detail: `{language: {code, label, url?}}`. Cancelable; `preventDefault()` overrides the default Smartling redirect.
+   * - **nys-search-submit** - Fired when a search is submitted. Detail: `{query}`. Cancelable; `preventDefault()` overrides the default search redirect.
    */
   "nys-unavheader": Partial<NysUnavHeaderProps & BaseProps & BaseEvents>;