@nysds/components 1.19.3-alpha-1 → 1.19.3

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

@@ -10,17 +10,60 @@ import { LitElement } from "lit";
  *
  * @slot - Footer content (links, contact info). Use `<h4>` for column headings.
  *
- * @example Simple footer
+ * @example Basic
+ * ```html
+ * <nys-globalfooter agencyName="Office of Information Technology Services"></nys-globalfooter>
+ * ```
+ *
+ * @example Homepage Link
  * ```html
  * <nys-globalfooter
- *    agencyName="Department of Health"
- *    homepageLink="/"
- *    agencySubheading="Protecting and Promoting the Health of New Yorkers"
- * >
- *   <span>123 Main St, Albany NY</span>
- *   <span>info@health.ny.gov</span>
+ *   agencyName="Office of Information Technology Services"
+ *   homepageLink="https://its.ny.gov"
+ * ></nys-globalfooter>
+ * ```
+ *
+ * @example Menu Links
+ * ```html
+ * <nys-globalfooter agencyName="Office of Information Technology Services">
+ *   <ul>
+ *     <li><a href="https://its.ny.gov">ITS Home</a></li>
+ *     <li><a href="https://its.ny.gov/about-us">About ITS</a></li>
+ *   </ul>
+ * </nys-globalfooter>
+ * ```
+ *
+ * @example Column Links
+ * ```html
+ * <nys-globalfooter agencyName="Office of Information Technology Services">
+ *   <ul>
+ *     <li>
+ *       <span>About</span>
+ *       <ul>
+ *         <li><a href="https://its.ny.gov/about-us">About ITS</a></li>
+ *         <li><a href="https://its.ny.gov/contact-us">Contact</a></li>
+ *         <li><a href="https://its.ny.gov/policies">Policies</a></li>
+ *       </ul>
+ *     </li>
+ *     <li>
+ *       <span>Resources</span>
+ *       <ul>
+ *         <li><a href="https://its.ny.gov/resources">Developer Tools</a></li>
+ *         <li><a href="https://its.ny.gov/accessibility">Accessibility</a></li>
+ *         <li><a href="https://its.ny.gov/privacy">Privacy</a></li>
+ *       </ul>
+ *     </li>
+ *   </ul>
  * </nys-globalfooter>
  * ```
+ *
+ * @example Subheading
+ * ```html
+ * <nys-globalfooter
+ *   agencyName="Office of Information Technology Services"
+ *   agencySubheading="Innovating Technology for a Better New York"
+ * ></nys-globalfooter>
+ * ```
  */
 export declare class NysGlobalFooter extends LitElement {
     static styles: import("lit").CSSResult;

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

@@ -9,12 +9,67 @@ 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
+ *
+ * @example Basic
+ * ```html
+ * <nys-globalheader appName="User Registration Form" agencyName="Office of Information Technology Services"></nys-globalheader>
+ * ```
+ *
+ * @example Homepage Link
  * ```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
+ *   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
+ * ```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>
+ * ```
+ * @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 {
@@ -25,7 +80,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,11 +1,18 @@
 /**
  * Icon Cache
  *
- * 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.
+ * 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.
  */
 /** Fetch and parse an SVG from a URL. Returns a cloned SVGElement (safe for multiple consumers). */
 export declare function fetchIcon(url: string): Promise<SVGElement>;
-/** Clear one or all entries from the cache. */
+/**
+ * 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. */
 export declare function clearIconCache(url?: string): void;

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

@@ -1,33 +1,51 @@
 /**
  * Icon Library Registry
  *
- * 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()`.
+ * 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.
  *
- * The registry and watcher maps are stored on `window` so that even
+ * The registry and watcher maps are stored on `globalThis` so that even
  * when bundlers (Storybook Vite, etc.) create duplicate module
- * instances, every copy shares a single source of truth.
+ * 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.
  */
+/**
+ * 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 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. */
+    /** 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. */
     mutator?: (svg: SVGElement) => void;
 }
 export interface NysIconWatcher {
     redraw(): void;
 }
-interface NysIconGlobals {
-    __nysIconRegistry: Map<string, IconLibrary>;
-    __nysIconWatchers: Map<string, Set<NysIconWatcher>>;
-}
 declare global {
-    interface Window extends NysIconGlobals {
-    }
+    var __nysIconRegistry: Map<string, IconLibrary> | undefined;
+    var __nysIconWatchers: Map<string, Set<NysIconWatcher>> | undefined;
+    var __nysIconDefaultRegistered: boolean | undefined;
 }
 /** 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", {
@@ -44,4 +62,3 @@ 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, } from "./icon-library-registry";
-export type { IconLibrary } from "./icon-library-registry";
+export { registerIconLibrary, unregisterIconLibrary, getIconLibrary, } from "./icon-library-registry";
+export type { IconLibrary, IconResolution } from "./icon-library-registry";
 export { clearIconCache } from "./icon-cache";

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

@@ -13,19 +13,96 @@ import { NysIconWatcher } from "./icon-library-registry";
  * @summary SVG icon with swappable library support, size, rotation, and color options.
  * @element nys-icon
  *
- * @example Basic icon (default NYSDS library)
+ * @example Basic
  * ```html
- * <nys-icon name="check_circle" size="lg"></nys-icon>
+ * <nys-icon name="check_circle"></nys-icon>
  * ```
  *
- * @example Font Awesome icon
+ * @example ARIA Label
  * ```html
- * <nys-icon name="house" library="fa" size="lg"></nys-icon>
+ * <nys-icon
+ *   name="edit_square"
+ *   ariaLabel="Edit content"
+ * ></nys-icon>
  * ```
  *
- * @example Accessible icon with label
+ * @example Size relative
  * ```html
- * <nys-icon name="warning" ariaLabel="Warning" color="var(--nys-color-warning)"></nys-icon>
+ * <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>
  * ```
  */
 export declare class NysIcon extends LitElement implements NysIconWatcher {

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

@@ -5,8 +5,38 @@ 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.
  *
- * @summary Internal label component for form fields with flag and tooltip support.
- * @element nys-label
+ * @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>
+ * ```
  *
  * @slot description - Custom HTML description content below the label.
  */

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

@@ -14,16 +14,141 @@ import { LitElement } from "lit";
  * @fires nys-open - Fired when modal opens. Detail: `{id}`.
  * @fires nys-close - Fired when modal closes. Detail: `{id}`.
  *
- * @example Basic modal
+ * @example Basic
  * ```html
- * <nys-modal id="confirm-modal" heading="Confirm action" open>
- *   <p>Are you sure you want to proceed?</p>
+ * <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>
  *   <div slot="actions">
- *     <nys-button label="Cancel" variant="outline"></nys-button>
- *     <nys-button label="Confirm" variant="filled"></nys-button>
+ *     <nys-button label="Not now" variant="outline"></nys-button>
+ *     <nys-button label="Update"></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,10 +10,20 @@ import { LitElement, TemplateResult } from "lit";
  *
  * @fires nys-change - Fired when page changes. Detail: `{page}`.
  *
- * @example Basic pagination
+ * @example Basic
+ * ```html
+ * <nys-pagination currentPage="5" totalPages="10"></nys-pagination>
+ * ```
+ *
+ * @example First Page
  * ```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,10 +15,11 @@ 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 Radio group
+ *
+ * @example Pre-selected
  * ```html
- * <nys-radiogroup label="Select borough" required>
- *   <nys-radiobutton name="borough" value="bronx" label="The Bronx"></nys-radiobutton>
+ * <nys-radiogroup label="Select borough">
+ *   <nys-radiobutton name="borough" value="bronx" label="The Bronx" checked></nys-radiobutton>
  *   <nys-radiobutton name="borough" value="brooklyn" label="Brooklyn"></nys-radiobutton>
  * </nys-radiogroup>
  * ```