@nysds/components 1.19.3 → 1.20.0-alpha-3

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

@@ -11,66 +11,12 @@ import { LitElement } from "lit";
  * @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
- * ```html
- * <nys-globalheader appName="User Registration Form" agencyName="Office of Information Technology Services"></nys-globalheader>
- * ```
- *
- * @example Homepage Link
- * ```html
- * <nys-globalheader
- *   agencyName="Office of Information Technology Services"
- *   homepageLink="https://its.ny.gov"
- * ></nys-globalheader>
- * ```
- *
- * @example Only Agency Name
- * ```html
- * <nys-globalheader agencyName="Office of Information Technology Services"></nys-globalheader>
- * ```
- *
- * @example Only App Name
+ * @example Basic header
  * ```html
- * <nys-globalheader appName="User Registration Form"></nys-globalheader>
- * ```
- *
- * @example With Links
- * ```html
- * <nys-globalheader agencyName="Office of Information Technology Services">
- *   <ul>
- *     <li><a href="https://its.ny.gov/services">Services</a></li>
- *     <li><a href="https://its.ny.gov/get-help">Help Center</a></li>
- *     <li><a href="https://its.ny.gov/cybersecurity">Cybersecurity</a></li>
- *     <li><a href="https://its.ny.gov/policies">Policies and Laws</a></li>
- *     <li><a href="https://its.ny.gov/procurement">Procurement</a></li>
- *     <li><a href="https://its.ny.gov/about-us">About Us</a></li>
- *   </ul>
+ * <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>
  * ```
- * @example User Actions
- * ```html
- * <nys-globalheader agencyName="Office of Information Technology Services">
- *   <nys-button slot="user-actions" label="Log out">
- *     <nys-avatar
- *       slot="prefix-icon"
- *       ariaLabel="User avatar"
- *       initials="NY"
- *     ></nys-avatar>
- *   </nys-button>
- * </nys-globalheader>
- * <nys-dropdownmenu id="dropdownmenu" for="my-action-slot">
- *   <nys-dropdownmenuitem label="Profile" href="/profile"></nys-dropdownmenuitem>
- *   <nys-dropdownmenuitem label="Repositories & Github Pages" href="/repos"></nys-dropdownmenuitem>
- *   <nys-dropdownmenuitem label="Organizations" href="/organizations" disabled></nys-dropdownmenuitem>
- *   <nys-dropdownmenuitem label="Sign out" href="/logout"></nys-dropdownmenuitem>
- * </nys-dropdownmenu>
- * ```
- *
- * @example With NYS Logo
- * ```html
- * <nys-globalheader nysLogo appName="Admin Dashboard"></nys-globalheader>
- * ```
  */
 export declare class NysGlobalHeader extends LitElement {
     static styles: import("lit").CSSResult;

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-icon/src/nys-icon.d.ts

@@ -13,96 +13,19 @@ import { NysIconWatcher } from "./icon-library-registry";
  * @summary SVG icon with swappable library support, size, rotation, and color options.
  * @element nys-icon
  *
- * @example Basic
+ * @example Basic icon (default NYSDS library)
  * ```html
- * <nys-icon name="check_circle"></nys-icon>
+ * <nys-icon name="check_circle" size="lg"></nys-icon>
  * ```
  *
- * @example ARIA Label
+ * @example Font Awesome icon
  * ```html
- * <nys-icon
- *   name="edit_square"
- *   ariaLabel="Edit content"
- * ></nys-icon>
+ * <nys-icon name="house" library="fa" size="lg"></nys-icon>
  * ```
  *
- * @example Size relative
+ * @example Accessible icon with label
  * ```html
- * <nys-icon
- *   name="edit_square"
- *   size="4xl"
- * ></nys-icon>
- * ```
- *
- * @example Size literal
- * ```html
- * <nys-icon
- *   name="edit_square"
- *   size="24"
- * ></nys-icon>
- * ```
- *
- * @example Color
- * ```html
- * <nys-icon
- *   name="edit_square"
- *   color="#db117d"
- * ></nys-icon>
- * ```
- *
- * @example Rotate
- * ```html
- * <nys-icon
- *   name="edit_square"
- *   rotate="20"
- * ></nys-icon>
- * ```
- *
- * @example Flip
- * ```html
- * <nys-icon
- *   name="edit_square"
- *   flip="vertical"
- * ></nys-icon>
- * ```
- *
- * @example External Library - Font Awesome
- * ```html
- * <nys-icon name="heart" library="fa"></nys-icon>
- * ```
- *
- * @render External Library - Font Awesome
- * ```html
- * <nys-icon name="heart" library="fa"></nys-icon>
- * <script data-scope="module">
- * registerIconLibrary("fa", {
- *   resolver: (name) =>
- *     `https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@6/svgs/solid/${name}.svg`,
- *   mutator: (svg) => {
- *     svg.setAttribute("fill", "currentColor");
- *   },
- * });
- * </script>
- * ```
- *
- *  @example External Library - Material
- * ```html
- * <nys-icon name="favorite" library="material"></nys-icon>
- * ```
- *
- *
- *  @render External Library - Material
- * ```html
- * <nys-icon name="favorite" library="material"></nys-icon>
- * <script data-scope="module">
- * registerIconLibrary("material", {
- *   resolver: (name) =>
- *     `https://fonts.gstatic.com/s/i/short-term/release/materialsymbolsoutlined/${name}/default/24px.svg`,
- *   mutator: (svg) => {
- *     svg.setAttribute("fill", "currentColor");
- *   },
- * });
- * </script>
+ * <nys-icon name="warning" ariaLabel="Warning" color="var(--nys-color-warning)"></nys-icon>
  * ```
  */
 export declare class NysIcon extends LitElement implements NysIconWatcher {

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

@@ -5,38 +5,8 @@ import { LitElement } from "lit";
  * 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.
  *
- * @example Basic
- * ```html
- * <nys-label label="This is a basic nys-label"></nys-label>
- * ```
- *
- * @example Required
- * ```html
- * <nys-label label="This form is required" flag="required"></nys-label>
- * ```
- *
- * @example Optional
- * ```html
- * <nys-label label="This form is required" flag="optional"></nys-label>
- * ```
- *
- * @example Description
- * ```html
- * <nys-label label="Label Text" description="Description text"></nys-label>
- * ```
- *
- * @example Description Slot
- * ```html
- * <nys-label label="Label Text">
- *   <p slot="description">Rich text description passed in <strong>HERE</strong></p>
- * </nys-label>
- * ```
- *
- * @example With Tooltip
- * ```html
- * <nys-label id="label-id" label="This label has a tooltip"></nys-label>
- * <nys-tooltip for="label-id" text="Tooltip text in here"></nys-tooltip>
- * ```
+ * @summary Internal label component for form fields with flag and tooltip support.
+ * @element nys-label
  *
  * @slot description - Custom HTML description content below the label.
  */

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

@@ -14,141 +14,16 @@ import { LitElement } from "lit";
  * @fires nys-open - Fired when modal opens. Detail: `{id}`.
  * @fires nys-close - Fired when modal closes. Detail: `{id}`.
  *
- * @example Basic
+ * @example Basic modal
  * ```html
- * <nys-modal
- *   id="modal1"
- *   heading="Update Available"
- * >
- *   <p>
- *     Would you like to install the latest version? Albany ipsum dolor sit
- *     Empire, Hudson consectetur Adirondack elit, sed do MetroCard tempor
- *     incididunt ut Capitol et Broadway magna Niagara. Ut enim ad Erie
- *     veniam, quis nostrud Catskill ullamco Bronx nisi ut LongIsland ex ea
- *     Cuomo consequat.
- *   </p>
- * </nys-modal>
- * ```
- *
- * @render Basic
- * ```html
- * <div id="modal-wrapper1">
- *   <nys-button label="Open Modal" onclick="document.querySelector('.modal1').open = true; document.getElementById('modal-wrapper1').style.padding = '100px 0'"></nys-button>
- *   <nys-modal
- *     class="modal1"
- *     id="modal1"
- *     heading="Update Available"
- *   >
- *     <p>
- *       Would you like to install the latest version? Albany ipsum dolor sit
- *       Empire, Hudson consectetur Adirondack elit, sed do MetroCard tempor
- *       incididunt ut Capitol et Broadway magna Niagara. Ut enim ad Erie
- *       veniam, quis nostrud Catskill ullamco Bronx nisi ut LongIsland ex ea
- *       Cuomo consequat.
- *     </p>
- *   </nys-modal>
- * </div>
- * ```
- *
-
- * @example Subheading
- * ```html
- * <nys-modal
- *   id="modal-subheading"
- *   heading="Before you continue"
- *   subheading="Your progress has been saved automatically."
- * >
- *   <p>You can safely leave this page and return later to pick up where you left off.</p>
- * </nys-modal>
- * ```
- *
- * @render Subheading
- * ```html
- * <div id="modal-wrapper-subheading">
- *   <nys-button label="Open Modal" onclick="document.querySelector('.modal-subheading').open = true; document.getElementById('modal-wrapper-subheading').style.padding = '100px 0'"></nys-button>
- *   <nys-modal
- *     class="modal-subheading"
- *     id="modal-subheading"
- *     heading="Before you continue"
- *     subheading="Your progress has been saved automatically."
- *   >
- *     <p>You can safely leave this page and return later to pick up where you left off.</p>
- *   </nys-modal>
- * </div>
- * ```
- *
- * @example Actions Slot
- * ```html
- * <nys-modal id="modal3" heading="Update password?">
- *   <p>
- *     Would you like to install the latest version? Albany ipsum dolor sit
- *     Empire, Hudson consectetur Adirondack elit, sed do MetroCard tempor
- *     incididunt ut Capitol et Broadway magna Niagara. Ut enim ad Erie
- *     veniam, quis nostrud Catskill ullamco Bronx nisi ut LongIsland ex ea
- *     Cuomo consequat.
- *   </p>
+ * <nys-modal id="confirm-modal" heading="Confirm action" open>
+ *   <p>Are you sure you want to proceed?</p>
  *   <div slot="actions">
- *     <nys-button label="Not now" variant="outline"></nys-button>
- *     <nys-button label="Update"></nys-button>
+ *     <nys-button label="Cancel" variant="outline"></nys-button>
+ *     <nys-button label="Confirm" variant="filled"></nys-button>
  *   </div>
  * </nys-modal>
  * ```
- *
- * @render Actions Slot
- * ```html
- * <div id="modal-wrapper3">
- *   <nys-button label="Open Modal" onclick="document.querySelector('.modal3').open = true; document.getElementById('modal-wrapper3').style.padding = '100px 0'"></nys-button>
- *   <nys-modal
- *     class="modal3"
- *     id="modal3"
- *     heading="Update password?"
- *   >
- *   <p>
- *     Would you like to install the latest version? Albany ipsum dolor sit
- *     Empire, Hudson consectetur Adirondack elit, sed do MetroCard tempor
- *     incididunt ut Capitol et Broadway magna Niagara. Ut enim ad Erie
- *     veniam, quis nostrud Catskill ullamco Bronx nisi ut LongIsland ex ea
- *     Cuomo consequat.
- *   </p>
- *     <div slot="actions">
- *       <nys-button label="Not now" variant="outline" onclick="document.querySelector('.modal3').open = false; document.getElementById('modal-wrapper3').style.padding = '0'"></nys-button>
- *       <nys-button label="Update" onclick="alert('Mock Alert: Changes saved!'); document.querySelector('.modal3').open = false; document.getElementById('modal-wrapper3').style.padding = '0'"></nys-button>
- *     </div>
- *   </nys-modal>
- * </div>
- * ```
- *
- * @example Mandatory Action
- * ```html
- * <nys-modal
- *   id="modal4"
- *   heading="There is no way to X out of here"
- *   subheading="Don't use this prop unless you add in the actions slot so the user does not get stuck in here."
- *   mandatory
- * >
- *   <div slot="actions">
- *     <nys-button label="Get me out"></nys-button>
- *   </div>
- * </nys-modal>
- * ```
- *
- * @render Mandatory Action
- * ```html
- * <div id="modal-wrapper4">
- *   <nys-button label="Open Modal" onclick="document.querySelector('.modal4').open = true; document.getElementById('modal-wrapper4').style.padding = '100px 0'"></nys-button>
- *   <nys-modal
- *     class="modal4"
- *     id="modal4"
- *     heading="There is no way to X out of here"
- *     subheading="Don't use this prop unless you add in the actions slot so the user does not get stuck in here."
- *     mandatory
- *   >
- *     <div slot="actions">
- *       <nys-button label="Get me out" onclick="alert('Ok, ok. You can go now.'); document.querySelector('.modal4').open = false; document.getElementById('modal-wrapper4').style.padding = '0'"></nys-button>
- *     </div>
- *   </nys-modal>
- * </div>
- * ```
  */
 export declare class NysModal extends LitElement {
     static styles: import("lit").CSSResult;

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

@@ -10,20 +10,10 @@ import { LitElement, TemplateResult } from "lit";
  *
  * @fires nys-change - Fired when page changes. Detail: `{page}`.
  *
- * @example Basic
- * ```html
- * <nys-pagination currentPage="5" totalPages="10"></nys-pagination>
- * ```
- *
- * @example First Page
+ * @example Basic pagination
  * ```html
  * <nys-pagination currentPage="1" totalPages="10"></nys-pagination>
  * ```
- *
- * @example Last Page
- * ```html
- * <nys-pagination currentPage="10" totalPages="10"></nys-pagination>
- * ```
  */
 export declare class NysPagination extends LitElement {
     static styles: import("lit").CSSResult;

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

@@ -15,11 +15,10 @@ import { LitElement } from "lit";
  * @fires nys-blur - Fired when radio loses focus.
  * @fires nys-other-input - Fired when "other" text input value changes. Detail: `{id, name, value}`.
  *
- *
- * @example Pre-selected
+ * @example Radio group
  * ```html
- * <nys-radiogroup label="Select borough">
- *   <nys-radiobutton name="borough" value="bronx" label="The Bronx" checked></nys-radiobutton>
+ * <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>
  * ```

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

@@ -12,7 +12,7 @@ import { LitElement } from "lit";
  * @slot - Default slot for `nys-radiobutton` elements.
  * @slot description - Custom HTML description content.
  *
- * @example Basic
+ * @example Basic radio group
  * ```html
  * <nys-radiogroup label="Select borough" required>
  *   <nys-radiobutton name="borough" value="bronx" label="The Bronx"></nys-radiobutton>
@@ -20,79 +20,6 @@ import { LitElement } from "lit";
  *   <nys-radiobutton name="borough" value="manhattan" label="Manhattan"></nys-radiobutton>
  * </nys-radiogroup>
  * ```
- *
- * @example Tile
- * ```html
- * <nys-radiogroup label="Select borough" tile>
- *   <nys-radiobutton name="borough" value="bronx" label="The Bronx"></nys-radiobutton>
- *   <nys-radiobutton name="borough" value="brooklyn" label="Brooklyn"></nys-radiobutton>
- * </nys-radiogroup>
- * ```
- *
- * @example Required
- * ```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>
- * ```
- *
- * @example Optional
- * ```html
- * <nys-radiogroup label="Select borough" optional>
- *   <nys-radiobutton name="borough" value="bronx" label="The Bronx"></nys-radiobutton>
- *   <nys-radiobutton name="borough" value="brooklyn" label="Brooklyn"></nys-radiobutton>
- * </nys-radiogroup>
- * ```
- *
- * @example Disabled
- * ```html
- * <nys-radiogroup label="Select borough">
- *   <nys-radiobutton name="borough" value="bronx" label="The Bronx" disabled></nys-radiobutton>
- *   <nys-radiobutton name="borough" value="brooklyn" label="Brooklyn" disabled></nys-radiobutton>
- * </nys-radiogroup>
- * ```
- *
- * @example Size Small
- * ```html
- * <nys-radiogroup label="Select borough" size="sm">
- *   <nys-radiobutton name="borough" value="bronx" label="The Bronx"></nys-radiobutton>
- *   <nys-radiobutton name="borough" value="brooklyn" label="Brooklyn"></nys-radiobutton>
- * </nys-radiogroup>
- * ```
- *
- * @example Other Option
- * ```html
- * <nys-radiogroup label="Select borough">
- *   <nys-radiobutton name="borough" value="bronx" label="The Bronx"></nys-radiobutton>
- *   <nys-radiobutton name="borough" value="" label="Other" other></nys-radiobutton>
- * </nys-radiogroup>
- * ```
- *
- * @example Error Message
- * ```html
- * <nys-radiogroup label="Select borough" showError errorMessage="Please select a borough">
- *   <nys-radiobutton name="borough" value="bronx" label="The Bronx"></nys-radiobutton>
- *   <nys-radiobutton name="borough" value="brooklyn" label="Brooklyn"></nys-radiobutton>
- * </nys-radiogroup>
- * ```
- *
- * @example Description
- * ```html
- * <nys-radiogroup label="Select borough" description="Your primary residence in NYC.">
- *   <nys-radiobutton name="borough" value="bronx" label="The Bronx"></nys-radiobutton>
- *   <nys-radiobutton name="borough" value="brooklyn" label="Brooklyn"></nys-radiobutton>
- * </nys-radiogroup>
- * ```
- *
- * @example Description Slot
- * ```html
- * <nys-radiogroup label="Select borough">
- *   <div slot="description">Your primary <strong>residence</strong> in NYC.</div>
- *   <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 NysRadiogroup extends LitElement {
     static styles: import("lit").CSSResult;

package/dist/packages/nys-select/src/nys-option.d.ts

@@ -9,6 +9,14 @@ import { LitElement } from "lit";
  * @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. */