@nysds/components 1.20.0-alpha-2 → 1.20.0-alpha-3

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

@@ -6,12 +6,17 @@ import "./nys-fileitem";
  *
  * Use for document uploads, image uploads, or any file submission. Enable `dropzone` for drag-and-drop UI.
  *
+ * Read or write the current selection via the `files` (`File[]`) and `value` (`File | null`)
+ * properties — useful for rehydrating state or binding from a framework form model.
+ * Setting them is silent (does not emit `nys-change`).
+ *
  * @summary File input with drag-and-drop, validation, and progress tracking.
  * @element nys-fileinput
  *
  * @slot description - Custom HTML description content.
  *
  * @fires nys-change - Fired when files are added or removed. Detail: `{id, files}`.
+ * @fires nys-blur - Fired when focus leaves the component. Triggers validation.
  *
  * @example Single file upload
  * ```html
@@ -69,6 +74,28 @@ export declare class NysFileinput extends LitElement {
     /** Adjusts colors for dark backgrounds. */
     inverted: boolean;
     private _selectedFiles;
+    /**
+     * 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.
+     */
+    get files(): File[];
+    set files(incoming: File[]);
+    /**
+     * Single-file convenience accessor (parity with `nys-textinput`'s `value`).
+     * Reads the first selected file (or `null`); setting replaces the selection.
+     */
+    get value(): File | null;
+    set value(file: File | null);
+    /**
+     * 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.
+     */
+    setFiles(incoming: File[]): Promise<void>;
     private _dragActive;
     private get _isDropDisabled();
     private get _buttonAriaLabel();
@@ -101,6 +128,7 @@ export declare class NysFileinput extends LitElement {
      */
     private _saveSelectedFiles;
     private _processFile;
+    private _handleBlur;
     private _dispatchChangeEvent;
     private _openFileDialog;
     private _handlePostFileSelectionFocus;

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

@@ -9,6 +9,7 @@ import { LitElement } from "lit";
  * @element nys-globalheader
  *
  * @slot - Navigation content (typically `<ul>` with `<li><a>` links). Auto-sanitized.
+ * @slot user-actions - User-account controls (e.g. profile link, settings, log-out button) shown in the header.
  *
  * @example Basic header
  * ```html
@@ -25,7 +26,13 @@ export declare class NysGlobalHeader extends LitElement {
     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;
     /** Internal state to track mobile menu open/closed status. */
     private _isMobileMenuOpen;

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

@@ -1,18 +1,11 @@
 /**
  * Icon Cache
  *
- * Shared SVG sanitize/parse pipeline and caches. URL-based icons (custom
- * libraries) are fetched once per URL; inline SVG sources (the built-in
- * NYSDS set) are parsed once per source string. Each consumer gets a
- * cloned SVGElement via `cloneNode(true)` so DOM nodes are never shared.
+ * Shared SVG fetch and parse cache. Deduplicates concurrent requests
+ * for the same icon URL. Each consumer gets a cloned SVGElement via
+ * `cloneNode(true)` so DOM nodes are never shared.
  */
 /** Fetch and parse an SVG from a URL. Returns a cloned SVGElement (safe for multiple consumers). */
 export declare function fetchIcon(url: string): Promise<SVGElement>;
-/**
- * Parse an inline SVG source string. Results are cached by source content,
- * so repeated renders of the same icon sanitize/parse once. Returns a
- * cloned SVGElement (safe for multiple consumers).
- */
-export declare function parseIcon(source: string): SVGElement;
-/** Clear one URL entry, or all cached icons (URL and inline) when no URL is given. */
+/** Clear one or all entries from the cache. */
 export declare function clearIconCache(url?: string): void;

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

@@ -1,51 +1,33 @@
 /**
  * Icon Library Registry
  *
- * Global registry for icon libraries. The "default" library resolves the
- * standard NYSDS icon set from an inline SVG map shipped as JavaScript
- * (`nys-icon.library.ts`), loaded lazily as a separate chunk — no base-URL
- * discovery, no per-icon fetch, no browser globals. Custom libraries
- * (Font Awesome, Material Icons, etc.) register at runtime via
- * `registerIconLibrary()` and typically resolve to URLs.
+ * Global registry for icon libraries. The "default" library resolves
+ * NYSDS icons from colocated SVG files extracted at build time.
+ * Custom libraries (Font Awesome, Material Icons, etc.) can be
+ * registered at runtime via `registerIconLibrary()`.
  *
- * The registry and watcher maps are stored on `globalThis` so that even
+ * The registry and watcher maps are stored on `window` so that even
  * when bundlers (Storybook Vite, etc.) create duplicate module
- * instances, every copy shares a single source of truth. `globalThis`
- * (rather than `window`) keeps module import side-effect-safe in
- * Node/SSR environments, where `window` does not exist.
+ * instances, every copy shares a single source of truth.
  */
-/**
- * How a resolver locates an icon: a URL string (legacy shorthand for
- * `{ type: "url" }`), an explicit URL, or inline SVG source. Resolvers may
- * return synchronously or via a Promise.
- */
-export type IconResolution = string | {
-    type: "url";
-    href: string;
-} | {
-    type: "svg";
-    content: string;
-};
 export interface IconLibrary {
-    /** Given an icon name, return where/what its SVG is. Return undefined if not found. */
-    resolver: (name: string) => IconResolution | undefined | Promise<IconResolution | undefined>;
-    /** Optional post-parse transform applied to the SVGElement. */
+    /** Given an icon name, return the URL to its SVG file. Return undefined if not found. */
+    resolver: (name: string) => string | undefined;
+    /** Optional post-fetch transform applied to the parsed SVGElement. */
     mutator?: (svg: SVGElement) => void;
 }
 export interface NysIconWatcher {
     redraw(): void;
 }
+interface NysIconGlobals {
+    __nysIconRegistry: Map<string, IconLibrary>;
+    __nysIconWatchers: Map<string, Set<NysIconWatcher>>;
+}
 declare global {
-    var __nysIconRegistry: Map<string, IconLibrary> | undefined;
-    var __nysIconWatchers: Map<string, Set<NysIconWatcher>> | undefined;
-    var __nysIconDefaultRegistered: boolean | undefined;
+    interface Window extends NysIconGlobals {
+    }
 }
 /** Register or replace a named icon library. All watching icons using this library will redraw.
- *
- * Intended for custom/external libraries — the standard NYSDS set is
- * built in and needs no registration. Registering under `"default"`
- * replaces the built-in set (escape hatch).
- *
  * @example Register a Font Awesome library with a custom resolver:
  * ```ts
  * registerIconLibrary("fa", {
@@ -62,3 +44,4 @@ export declare function getIconLibrary(name: string): IconLibrary | undefined;
 export declare function watchIconLibrary(name: string, watcher: NysIconWatcher): void;
 /** Unsubscribe an icon instance from library change notifications. */
 export declare function unwatchIconLibrary(name: string, watcher: NysIconWatcher): void;
+export {};

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

@@ -1,4 +1,4 @@
 export * from "./nys-icon";
-export { registerIconLibrary, unregisterIconLibrary, getIconLibrary, } from "./icon-library-registry";
-export type { IconLibrary, IconResolution } from "./icon-library-registry";
+export { registerIconLibrary, unregisterIconLibrary, } from "./icon-library-registry";
+export type { IconLibrary } from "./icon-library-registry";
 export { clearIconCache } from "./icon-cache";

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

@@ -8,6 +8,10 @@ import { LitElement } from "lit";
  *
  * @summary Universal NYS header with trust bar, search, and translation. Required site-wide.
  * @element nys-unavheader
+ *
+ * @fires nys-language-select - Fired when a language is selected. Detail: `{language: {code, label, url?}}`. Cancelable; `preventDefault()` overrides the default Smartling redirect.
+ * @fires nys-search-submit - Fired when a search is submitted. Detail: `{query}`. Cancelable; `preventDefault()` overrides the default search redirect.
+
  *
  * @example Standard usage
  * ```html

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nysds/components",
-  "version": "1.20.0-alpha-2",
+  "version": "1.20.0-alpha-3",
   "description": "New York State's design system and code component library.",
   "type": "module",
   "workspaces": [
@@ -47,8 +47,7 @@
     "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 && node scripts/audit-dist.mjs",
-    "audit:dist": "node scripts/audit-dist.mjs",
+    "test:ssr": "node scripts/test-ssr.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",
@@ -137,5 +136,8 @@
     "dompurify": "^3.4.7",
     "wc-datepicker": "^0.10.0"
   },
-  "sideEffects": true
+  "sideEffects": true,
+  "peerDependencies": {
+    "lit": "^3.3.1"
+  }
 }

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/nysds-jsx.d.ts

@@ -498,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;
 };
@@ -533,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;
 };
 
@@ -1271,7 +1285,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.
@@ -1305,6 +1326,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>;