@nysds/nys-icon 1.19.4 → 1.20.0

package/dist/icon-cache.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+/** 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. */
+export declare function clearIconCache(url?: string): void;

package/dist/icon-library-registry.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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.
+ *
+ * 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. `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 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;
+}
+declare global {
+    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", {
+ *   resolver: (name) => `https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/svg/${name}.svg`
+ * });
+ * ```
+ */
+export declare function registerIconLibrary(name: string, library: IconLibrary): void;
+/** Remove a registered icon library. All watching icons using this library will redraw. */
+export declare function unregisterIconLibrary(name: string): void;
+/** Get a registered icon library by name. */
+export declare function getIconLibrary(name: string): IconLibrary | undefined;
+/** Subscribe an icon instance to library change notifications. */
+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;

package/dist/index.d.ts

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

package/dist/nys-icon.d.ts

@@ -0,0 +1,164 @@
+import { NysElement } from "@nysds/internals";
+import { NysIconWatcher } from "./icon-library-registry";
+/**
+ * Renders SVG icons from a registered icon library. The built-in NYSDS icon
+ * library (Material Symbols) is the default. Custom libraries (Font Awesome,
+ * Material Icons, etc.) can be registered via `registerIconLibrary()`.
+ *
+ * Pass `name` to select an icon. Use `library` to choose a registered library
+ * (defaults to `"default"` for NYSDS icons). Use `ariaLabel` to make the icon
+ * accessible (removes `aria-hidden`). Supports size presets, rotation,
+ * flipping, and custom colors.
+ *
+ * @summary SVG icon with swappable library support, size, rotation, and color options.
+ * @element nys-icon
+ *
+ * @example Basic
+ * ```html
+ * <nys-icon name="check_circle"></nys-icon>
+ * ```
+ *
+ * @example ARIA Label
+ * ```html
+ * <nys-icon
+ *   name="edit_square"
+ *   ariaLabel="Edit content"
+ * ></nys-icon>
+ * ```
+ *
+ * @example Size relative
+ * ```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>
+ * ```
+ */
+export declare class NysIcon extends NysElement implements NysIconWatcher {
+    static styles: import("lit").CSSResult;
+    /** Icon name to resolve from the selected library. Required. */
+    name: string;
+    /** Which registered icon library to use. Defaults to the built-in NYSDS library. */
+    library: string;
+    /** Accessible label. When set, removes `aria-hidden` and adds `aria-label` to the SVG. */
+    ariaLabel: string;
+    /** Rotation in degrees. Applied via CSS `rotate`. */
+    rotate: string;
+    /** Flip direction: `horizontal`, `vertical`, or empty for none. */
+    flip: string;
+    /** Icon color. Accepts any CSS color value. Defaults to `currentcolor`. */
+    color: string;
+    /**
+     * Icon size. Semantic sizes: `xs`-`5xl`. Pixel sizes: `12`-`50`.
+     * @default "md"
+     */
+    size: "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "5xl" | "12" | "14" | "16" | "18" | "20" | "24" | "32" | "40" | "50";
+    private _svg;
+    /** Monotonically increasing token so stale async fetches are discarded. */
+    private _loadSeq;
+    /** Promise for the in-flight icon load. */
+    private _loadPromise;
+    /** Resolves when the current icon load (if any) is complete. */
+    get updateComplete(): Promise<boolean>;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /** Called by the icon library registry when the current library changes. */
+    redraw(): void;
+    /**
+     * Lit calls firstUpdated after the first render, once all reactive
+     * properties (including those set from the template) are resolved.
+     * This guarantees the initial _loadIcon runs with the correct name
+     * and library values, avoiding the race where updated() might not
+     * fire for properties that equal their defaults.
+     */
+    firstUpdated(): void;
+    private static _validName;
+    updated(changedProps: Map<string, unknown>): void;
+    private _loadIcon;
+    private _applyAttributes;
+    /**
+     * Reflects the icon's accessible state onto the host:
+     * - Labeled icon  -> role="img" + aria-label, no aria-hidden.
+     * - Decorative    -> aria-hidden="true", no role/label.
+     *
+     * These are reflected as host *attributes* (rather than via
+     * ElementInternals) on purpose: aria-hidden / role / aria-label in
+     * attribute form have universal, consistent assistive-technology support,
+     * whereas AT support for these states set through ElementInternals is still
+     * uneven across browser/screen-reader combinations. The host role/label
+     * therefore depend on runtime state (ariaLabel), so defaultRole stays null.
+     */
+    private _reflectHostSemantics;
+    render(): import("lit-html").TemplateResult<1> | null;
+}

package/dist/nys-icon.figma.d.ts

@@ -0,0 +1 @@
+export {};