@ds-mo/ui 2.9.0 → 2.10.1

package/dist/lib/utils/index.js

@@ -0,0 +1,188 @@
+// src/wc/components/Icon/icon-cache.ts
+var CACHE_KEY = /* @__PURE__ */ Symbol.for("ds-mo.icon-svg-cache");
+function iconCacheKey(name, flag) {
+  return flag ? `flag:${name}` : `system:${name}`;
+}
+function iconCache() {
+  const g = globalThis;
+  return g[CACHE_KEY] ?? (g[CACHE_KEY] = /* @__PURE__ */ new Map());
+}
+function registerIcons(icons, options) {
+  const cache = iconCache();
+  const flag = options?.flag === true;
+  for (const [name, svg] of Object.entries(icons)) {
+    cache.set(iconCacheKey(name, flag), svg);
+  }
+}
+
+// src/wc/utils/resolve-css-length-px.ts
+var lengthPxCache = /* @__PURE__ */ new Map();
+var probeEl = null;
+function getProbeElement() {
+  if (typeof document === "undefined") return null;
+  if (!probeEl) {
+    probeEl = document.createElement("div");
+    probeEl.setAttribute("aria-hidden", "true");
+    probeEl.style.cssText = "position:absolute;visibility:hidden;pointer-events:none;top:0;left:0;width:0;height:0;overflow:hidden;";
+    document.documentElement.appendChild(probeEl);
+  }
+  return probeEl;
+}
+function clearCssLengthPxCache() {
+  lengthPxCache.clear();
+}
+function resolveCssLengthPx(value, fallback) {
+  const resolved = value === void 0 || value === null || value === "" ? fallback : value;
+  if (typeof resolved === "number") return resolved;
+  const trimmed = resolved.trim();
+  if (!trimmed) return resolveCssLengthPx(fallback, 0);
+  const cached = lengthPxCache.get(trimmed);
+  if (cached !== void 0) return cached;
+  if (/^-?\d+(\.\d+)?$/.test(trimmed)) {
+    const n = Number(trimmed);
+    lengthPxCache.set(trimmed, n);
+    return n;
+  }
+  const pxMatch = trimmed.match(/^(-?\d+(\.\d+)?)px$/);
+  if (pxMatch) {
+    const px2 = parseFloat(pxMatch[1]);
+    lengthPxCache.set(trimmed, px2);
+    return px2;
+  }
+  const cssLength = /^--[\w-]+$/.test(trimmed) ? `var(${trimmed})` : trimmed;
+  const probe = getProbeElement();
+  if (!probe) {
+    return typeof fallback === "number" ? fallback : 0;
+  }
+  probe.style.width = cssLength;
+  const px = probe.getBoundingClientRect().width;
+  probe.style.width = "";
+  lengthPxCache.set(trimmed, px);
+  return px;
+}
+
+// src/wc/utils/resolve-css-time-ms.ts
+function parseCssTimeMs(value, fallback) {
+  const firstToken = value.trim().split(/\s+/)[0] ?? "";
+  const num = parseFloat(firstToken);
+  if (Number.isNaN(num)) return fallback;
+  if (/ms\s*$/.test(firstToken)) return num;
+  if (/s\s*$/.test(firstToken)) return num * 1e3;
+  return num;
+}
+function extractCssCustomProp(ref) {
+  const varMatch = ref.match(/^var\(\s*(--[^),]+)/);
+  if (varMatch) return varMatch[1].trim();
+  if (ref.startsWith("--")) return ref.trim();
+  return null;
+}
+function readTokenTimeMs(token, fallback) {
+  if (typeof document === "undefined") return fallback;
+  const prop = extractCssCustomProp(token);
+  if (!prop) return parseCssTimeMs(token, fallback);
+  const raw = getComputedStyle(document.documentElement).getPropertyValue(prop).trim();
+  return parseCssTimeMs(raw, fallback);
+}
+function resolveCssTimeMs(value, fallbackToken) {
+  if (typeof value === "number") return value;
+  const token = typeof value === "string" && value.trim() ? value.trim() : fallbackToken;
+  const prop = extractCssCustomProp(token);
+  if (prop) {
+    return readTokenTimeMs(token, readTokenTimeMs(fallbackToken, 200));
+  }
+  return parseCssTimeMs(token, readTokenTimeMs(fallbackToken, 200));
+}
+
+// src/wc/utils/scroll-edge-fade.ts
+var SCROLL_EDGE_FADE_SIZE_VAR = "--ds-scroll-edge-fade-size";
+var SCROLL_EDGE_FADE_DEFAULT_SIZE = "var(--dimension-size-600)";
+var SIZE_REF = `var(${SCROLL_EDGE_FADE_SIZE_VAR}, ${SCROLL_EDGE_FADE_DEFAULT_SIZE})`;
+function scrollEdgeFadeMaskImage(edge) {
+  switch (edge) {
+    case "top":
+      return `linear-gradient(to bottom, #000 0, #000 50%, transparent 100%)`;
+    case "bottom":
+      return `linear-gradient(to bottom, #000 0, #000 calc(100% - ${SIZE_REF}), transparent 100%)`;
+    case "left":
+      return `linear-gradient(to right, #000 0, #000 calc(100% - ${SIZE_REF}), transparent 100%)`;
+    case "right":
+      return `linear-gradient(to left, #000 0, #000 calc(100% - ${SIZE_REF}), transparent 100%)`;
+  }
+}
+function scrollEdgeFadeMaskStyle(edge) {
+  const mask = scrollEdgeFadeMaskImage(edge);
+  return {
+    [SCROLL_EDGE_FADE_SIZE_VAR]: SCROLL_EDGE_FADE_DEFAULT_SIZE,
+    WebkitMaskImage: mask,
+    maskImage: mask,
+    WebkitMaskSize: "100% 100%",
+    maskSize: "100% 100%"
+  };
+}
+
+// src/wc/utils/token-defaults.ts
+import {
+  dimensionIconographyMd,
+  dimensionIconographySm,
+  dimensionIconographyXs,
+  dimensionMenuWidthXs,
+  dimensionPanelWidth2xs,
+  dimensionPanelWidthLg,
+  dimensionPanelWidthMd,
+  dimensionSize300,
+  dimensionSize600,
+  dimensionSize800,
+  dimensionSpace050,
+  dimensionSpace200,
+  effectAnimationDelayLong2,
+  effectAnimationDelayMedium1,
+  effectAnimationDelayShort2,
+  effectAnimationDurationMedium1,
+  effectAnimationDurationShort3,
+  effectMotionShort2,
+  effectMotionShort3
+} from "@ds-mo/tokens/ts";
+var TOKEN_DEFAULTS = {
+  space050: dimensionSpace050,
+  space200: dimensionSpace200,
+  size300: dimensionSize300,
+  size600: dimensionSize600,
+  size800: dimensionSize800,
+  iconographyMd: dimensionIconographyMd,
+  iconographySm: dimensionIconographySm,
+  iconographyXs: dimensionIconographyXs,
+  panelWidth2xs: dimensionPanelWidth2xs,
+  panelWidthMd: dimensionPanelWidthMd,
+  panelWidthLg: dimensionPanelWidthLg,
+  menuWidthXs: dimensionMenuWidthXs,
+  motionShort2: effectMotionShort2,
+  motionShort3: effectMotionShort3,
+  animationDurationShort3: effectAnimationDurationShort3,
+  animationDurationMedium1: effectAnimationDurationMedium1,
+  animationDelayMedium1: effectAnimationDelayMedium1,
+  animationDelayShort2: effectAnimationDelayShort2,
+  animationDelayLong2: effectAnimationDelayLong2,
+  /** Unmeasured menu height fallback: 20× base (160px at default scale). */
+  menuFallbackHeight: "calc(var(--dimension-size-base) * 20)",
+  /** Unmeasured tooltip width fallback: size-800 + size-200 (80px). */
+  tooltipFallbackWidth: "calc(var(--dimension-size-800) + var(--dimension-size-200))"
+};
+var TOKEN_CSS_LENGTHS = {
+  space050: `var(${dimensionSpace050})`,
+  space200: `var(${dimensionSpace200})`,
+  menuWidthXs: `var(${dimensionMenuWidthXs})`
+};
+export {
+  SCROLL_EDGE_FADE_DEFAULT_SIZE,
+  SCROLL_EDGE_FADE_SIZE_VAR,
+  TOKEN_CSS_LENGTHS,
+  TOKEN_DEFAULTS,
+  clearCssLengthPxCache,
+  parseCssTimeMs,
+  registerIcons,
+  resolveCssLengthPx,
+  resolveCssTimeMs,
+  scrollEdgeFadeMaskImage,
+  scrollEdgeFadeMaskStyle
+};
+//# sourceMappingURL=index.js.map

package/dist/lib/utils/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/wc/components/Icon/icon-cache.ts", "../../../src/wc/utils/resolve-css-length-px.ts", "../../../src/wc/utils/resolve-css-time-ms.ts", "../../../src/wc/utils/scroll-edge-fade.ts", "../../../src/wc/utils/token-defaults.ts"],
+  "sourcesContent": ["/**\n * Shared SVG glyph cache for ds-icon.\n *\n * Keyed on a global symbol so every module instance (the compiled Stencil chunk\n * inside dist/components and any direct source import, e.g. via `@ds-mo/ui/utils`)\n * reads and writes the same cache. Without this, `registerIcons` called from an\n * app would fill a different Map than the one ds-icon resolves from.\n */\nconst CACHE_KEY = Symbol.for('ds-mo.icon-svg-cache');\n\ntype IconCacheMap = Map<string, string>;\n\ntype GlobalWithIconCache = { [CACHE_KEY]?: IconCacheMap };\n\nexport function iconCacheKey(name: string, flag: boolean): string {\n  return flag ? `flag:${name}` : `system:${name}`;\n}\n\nexport function iconCache(): IconCacheMap {\n  const g = globalThis as GlobalWithIconCache;\n  return (g[CACHE_KEY] ??= new Map());\n}\n\n/**\n * Pre-register glyphs so ds-icon renders them synchronously \u2014 no lazy-chunk\n * fetch, no first-paint pop-in. Import the SVG strings from `@ds-mo/icons`\n * in the app (statically, so they ship in the app's own bundle):\n *\n * ```ts\n * import { Bell } from '@ds-mo/icons/svg/Bell';\n * import { US } from '@ds-mo/icons/svg/flags/US';\n * import { registerIcons } from '@ds-mo/ui/utils';\n *\n * registerIcons({ Bell });\n * registerIcons({ US }, { flag: true });\n * ```\n *\n * Icons that are not registered still work \u2014 they lazy-load on first render\n * and stay cached afterwards.\n */\nexport function registerIcons(icons: Record<string, string>, options?: { flag?: boolean }): void {\n  const cache = iconCache();\n  const flag = options?.flag === true;\n  for (const [name, svg] of Object.entries(icons)) {\n    cache.set(iconCacheKey(name, flag), svg);\n  }\n}\n", "const lengthPxCache = new Map<string, number>();\n\nlet probeEl: HTMLElement | null = null;\n\nfunction getProbeElement(): HTMLElement | null {\n  if (typeof document === 'undefined') return null;\n\n  if (!probeEl) {\n    probeEl = document.createElement('div');\n    probeEl.setAttribute('aria-hidden', 'true');\n    probeEl.style.cssText =\n      'position:absolute;visibility:hidden;pointer-events:none;top:0;left:0;width:0;height:0;overflow:hidden;';\n    document.documentElement.appendChild(probeEl);\n  }\n\n  return probeEl;\n}\n\n/** Clear session cache (tests only). */\nexport function clearCssLengthPxCache(): void {\n  lengthPxCache.clear();\n}\n\n/**\n * Resolve a CSS length to pixels for layout math.\n * Numbers pass through; `var(--dimension-*)`, `calc(...)`, and `16px` resolve via a hidden probe.\n */\nexport function resolveCssLengthPx(\n  value: number | string | undefined,\n  fallback: number | string,\n): number {\n  const resolved = value === undefined || value === null || value === '' ? fallback : value;\n  if (typeof resolved === 'number') return resolved;\n\n  const trimmed = resolved.trim();\n  if (!trimmed) return resolveCssLengthPx(fallback, 0);\n\n  const cached = lengthPxCache.get(trimmed);\n  if (cached !== undefined) return cached;\n\n  if (/^-?\\d+(\\.\\d+)?$/.test(trimmed)) {\n    const n = Number(trimmed);\n    lengthPxCache.set(trimmed, n);\n    return n;\n  }\n\n  const pxMatch = trimmed.match(/^(-?\\d+(\\.\\d+)?)px$/);\n  if (pxMatch) {\n    const px = parseFloat(pxMatch[1]);\n    lengthPxCache.set(trimmed, px);\n    return px;\n  }\n\n  const cssLength = /^--[\\w-]+$/.test(trimmed) ? `var(${trimmed})` : trimmed;\n\n  const probe = getProbeElement();\n  if (!probe) {\n    return typeof fallback === 'number' ? fallback : 0;\n  }\n\n  probe.style.width = cssLength;\n  const px = probe.getBoundingClientRect().width;\n  probe.style.width = '';\n  lengthPxCache.set(trimmed, px);\n  return px;\n}\n", "/** Parse a CSS <time> value (or motion shorthand's first token) to milliseconds. */\nexport function parseCssTimeMs(value: string, fallback: number): number {\n  const firstToken = value.trim().split(/\\s+/)[0] ?? '';\n  const num = parseFloat(firstToken);\n  if (Number.isNaN(num)) return fallback;\n  if (/ms\\s*$/.test(firstToken)) return num;\n  if (/s\\s*$/.test(firstToken)) return num * 1000;\n  return num;\n}\n\nfunction extractCssCustomProp(ref: string): string | null {\n  const varMatch = ref.match(/^var\\(\\s*(--[^),]+)/);\n  if (varMatch) return varMatch[1].trim();\n  if (ref.startsWith('--')) return ref.trim();\n  return null;\n}\n\nfunction readTokenTimeMs(token: string, fallback: number): number {\n  if (typeof document === 'undefined') return fallback;\n\n  const prop = extractCssCustomProp(token);\n  if (!prop) return parseCssTimeMs(token, fallback);\n\n  const raw = getComputedStyle(document.documentElement).getPropertyValue(prop).trim();\n  return parseCssTimeMs(raw, fallback);\n}\n\n/**\n * Resolve a duration to milliseconds for JS timers aligned with CSS motion tokens.\n * Accepts numbers (ms), raw times (`200ms`, `0.75s`), or `var(--effect-*)` references.\n */\nexport function resolveCssTimeMs(\n  value: number | string | undefined,\n  fallbackToken: string,\n): number {\n  if (typeof value === 'number') return value;\n\n  const token = typeof value === 'string' && value.trim() ? value.trim() : fallbackToken;\n  const prop = extractCssCustomProp(token);\n\n  if (prop) {\n    return readTokenTimeMs(token, readTokenTimeMs(fallbackToken, 200));\n  }\n\n  return parseCssTimeMs(token, readTokenTimeMs(fallbackToken, 200));\n}\n", "/** CSS custom property for scroll-edge fade depth (dimension token or length). */\nexport const SCROLL_EDGE_FADE_SIZE_VAR = '--ds-scroll-edge-fade-size';\n\nexport const SCROLL_EDGE_FADE_DEFAULT_SIZE = 'var(--dimension-size-600)';\n\nexport type ScrollEdgeFadeEdge = 'top' | 'bottom' | 'left' | 'right';\n\nconst SIZE_REF = `var(${SCROLL_EDGE_FADE_SIZE_VAR}, ${SCROLL_EDGE_FADE_DEFAULT_SIZE})`;\n\n/**\n * Alpha mask for a scroll container edge \u2014 content fades to transparent so\n * textured backgrounds (gradients, images) show through. Prefer over painted\n * `ds-fade` overlays on non-flat surfaces.\n */\nexport function scrollEdgeFadeMaskImage(edge: ScrollEdgeFadeEdge): string {\n  switch (edge) {\n    case 'top':\n      return `linear-gradient(to bottom, #000 0, #000 50%, transparent 100%)`;\n    case 'bottom':\n      return `linear-gradient(to bottom, #000 0, #000 calc(100% - ${SIZE_REF}), transparent 100%)`;\n    case 'left':\n      return `linear-gradient(to right, #000 0, #000 calc(100% - ${SIZE_REF}), transparent 100%)`;\n    case 'right':\n      return `linear-gradient(to left, #000 0, #000 calc(100% - ${SIZE_REF}), transparent 100%)`;\n  }\n}\n\n/** Inline style map for a masked scroll region. */\nexport function scrollEdgeFadeMaskStyle(edge: ScrollEdgeFadeEdge): Record<string, string> {\n  const mask = scrollEdgeFadeMaskImage(edge);\n  return {\n    [SCROLL_EDGE_FADE_SIZE_VAR]: SCROLL_EDGE_FADE_DEFAULT_SIZE,\n    WebkitMaskImage: mask,\n    maskImage: mask,\n    WebkitMaskSize: '100% 100%',\n    maskSize: '100% 100%',\n  };\n}\n", "import {\n  dimensionIconographyMd,\n  dimensionIconographySm,\n  dimensionIconographyXs,\n  dimensionMenuWidthXs,\n  dimensionPanelWidth2xs,\n  dimensionPanelWidthLg,\n  dimensionPanelWidthMd,\n  dimensionSize300,\n  dimensionSize600,\n  dimensionSize800,\n  dimensionSpace050,\n  dimensionSpace200,\n  effectAnimationDelayLong2,\n  effectAnimationDelayMedium1,\n  effectAnimationDelayShort2,\n  effectAnimationDurationMedium1,\n  effectAnimationDurationShort3,\n  effectMotionShort2,\n  effectMotionShort3,\n} from '@ds-mo/tokens/ts';\n\n/** TokoMo CSS custom-property names for shared component defaults (runtime resolution). */\nexport const TOKEN_DEFAULTS = {\n  space050: dimensionSpace050,\n  space200: dimensionSpace200,\n  size300: dimensionSize300,\n  size600: dimensionSize600,\n  size800: dimensionSize800,\n  iconographyMd: dimensionIconographyMd,\n  iconographySm: dimensionIconographySm,\n  iconographyXs: dimensionIconographyXs,\n  panelWidth2xs: dimensionPanelWidth2xs,\n  panelWidthMd: dimensionPanelWidthMd,\n  panelWidthLg: dimensionPanelWidthLg,\n  menuWidthXs: dimensionMenuWidthXs,\n  motionShort2: effectMotionShort2,\n  motionShort3: effectMotionShort3,\n  animationDurationShort3: effectAnimationDurationShort3,\n  animationDurationMedium1: effectAnimationDurationMedium1,\n  animationDelayMedium1: effectAnimationDelayMedium1,\n  animationDelayShort2: effectAnimationDelayShort2,\n  animationDelayLong2: effectAnimationDelayLong2,\n  /** Unmeasured menu height fallback: 20\u00D7 base (160px at default scale). */\n  menuFallbackHeight: 'calc(var(--dimension-size-base) * 20)',\n  /** Unmeasured tooltip width fallback: size-800 + size-200 (80px). */\n  tooltipFallbackWidth: 'calc(var(--dimension-size-800) + var(--dimension-size-200))',\n} as const;\n\nexport type TokenDefaultKey = keyof typeof TOKEN_DEFAULTS;\n\n/** Valid CSS length strings for overlay offset props \u2014 bind on `sideOffset` / `alignOffset` in hosts. */\nexport const TOKEN_CSS_LENGTHS = {\n  space050: `var(${dimensionSpace050})`,\n  space200: `var(${dimensionSpace200})`,\n  menuWidthXs: `var(${dimensionMenuWidthXs})`,\n} as const;\n"],
+  "mappings": "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",
+  "names": ["px"]
+}

package/dist/lib/utils/resolve-css-length-px.d.ts

@@ -0,0 +1,7 @@
+/** Clear session cache (tests only). */
+export declare function clearCssLengthPxCache(): void;
+/**
+ * Resolve a CSS length to pixels for layout math.
+ * Numbers pass through; `var(--dimension-*)`, `calc(...)`, and `16px` resolve via a hidden probe.
+ */
+export declare function resolveCssLengthPx(value: number | string | undefined, fallback: number | string): number;

package/dist/lib/utils/resolve-css-time-ms.d.ts

@@ -0,0 +1,7 @@
+/** Parse a CSS <time> value (or motion shorthand's first token) to milliseconds. */
+export declare function parseCssTimeMs(value: string, fallback: number): number;
+/**
+ * Resolve a duration to milliseconds for JS timers aligned with CSS motion tokens.
+ * Accepts numbers (ms), raw times (`200ms`, `0.75s`), or `var(--effect-*)` references.
+ */
+export declare function resolveCssTimeMs(value: number | string | undefined, fallbackToken: string): number;

package/dist/lib/utils/scroll-edge-fade.d.ts

@@ -0,0 +1,12 @@
+/** CSS custom property for scroll-edge fade depth (dimension token or length). */
+export declare const SCROLL_EDGE_FADE_SIZE_VAR = "--ds-scroll-edge-fade-size";
+export declare const SCROLL_EDGE_FADE_DEFAULT_SIZE = "var(--dimension-size-600)";
+export type ScrollEdgeFadeEdge = 'top' | 'bottom' | 'left' | 'right';
+/**
+ * Alpha mask for a scroll container edge — content fades to transparent so
+ * textured backgrounds (gradients, images) show through. Prefer over painted
+ * `ds-fade` overlays on non-flat surfaces.
+ */
+export declare function scrollEdgeFadeMaskImage(edge: ScrollEdgeFadeEdge): string;
+/** Inline style map for a masked scroll region. */
+export declare function scrollEdgeFadeMaskStyle(edge: ScrollEdgeFadeEdge): Record<string, string>;

package/dist/lib/utils/token-defaults.d.ts

@@ -0,0 +1,33 @@
+/** TokoMo CSS custom-property names for shared component defaults (runtime resolution). */
+export declare const TOKEN_DEFAULTS: {
+    readonly space050: "--dimension-space-050";
+    readonly space200: "--dimension-space-200";
+    readonly size300: "--dimension-size-300";
+    readonly size600: "--dimension-size-600";
+    readonly size800: "--dimension-size-800";
+    readonly iconographyMd: "--dimension-iconography-md";
+    readonly iconographySm: "--dimension-iconography-sm";
+    readonly iconographyXs: "--dimension-iconography-xs";
+    readonly panelWidth2xs: "--dimension-panel-width-2xs";
+    readonly panelWidthMd: "--dimension-panel-width-md";
+    readonly panelWidthLg: "--dimension-panel-width-lg";
+    readonly menuWidthXs: "--dimension-menu-width-xs";
+    readonly motionShort2: "--effect-motion-short-2";
+    readonly motionShort3: "--effect-motion-short-3";
+    readonly animationDurationShort3: "--effect-animation-duration-short-3";
+    readonly animationDurationMedium1: "--effect-animation-duration-medium-1";
+    readonly animationDelayMedium1: "--effect-animation-delay-medium-1";
+    readonly animationDelayShort2: "--effect-animation-delay-short-2";
+    readonly animationDelayLong2: "--effect-animation-delay-long-2";
+    /** Unmeasured menu height fallback: 20× base (160px at default scale). */
+    readonly menuFallbackHeight: "calc(var(--dimension-size-base) * 20)";
+    /** Unmeasured tooltip width fallback: size-800 + size-200 (80px). */
+    readonly tooltipFallbackWidth: "calc(var(--dimension-size-800) + var(--dimension-size-200))";
+};
+export type TokenDefaultKey = keyof typeof TOKEN_DEFAULTS;
+/** Valid CSS length strings for overlay offset props — bind on `sideOffset` / `alignOffset` in hosts. */
+export declare const TOKEN_CSS_LENGTHS: {
+    readonly space050: "var(--dimension-space-050)";
+    readonly space200: "var(--dimension-space-200)";
+    readonly menuWidthXs: "var(--dimension-menu-width-xs)";
+};

package/dist/types/components/Badge/Badge.d.ts

@@ -15,7 +15,11 @@ export declare class Badge {
     /**
      * Ring samples the shell gradient stack (base fill + wash) instead of a flat
      * `box-shadow`. Auto-enabled in `componentDidLoad` under `ds-app-shell[gradient]`;
-     * set `on-gradient-background` to opt in/out explicitly.
+     * set `gradient-background` to opt in/out explicitly.
+     *
+     * The attribute must NOT start with `on` — Stencil's setAccessor routes any
+     * unknown `on*` member down the event-listener path during attribute
+     * reflection, calling addEventListener with a non-listener and throwing.
      */
     gradientBackground: boolean;
     /** Deprecated alias for selected counter styling. Prefer context-specific color in the parent. */

package/dist/types/components/Icon/Icon.d.ts

@@ -13,7 +13,20 @@ export declare class Icon {
     label: string | undefined;
     /** Set `true` to look up from the flag icon set instead of the system icon set. */
     flag: boolean;
-    private get svgString();
+    /** Resolved SVG markup — set synchronously on cache hit, async after a lazy load. */
+    private svg;
+    /** Guards against out-of-order async resolutions when `name`/`flag` change quickly. */
+    private loadToken;
+    /**
+     * Cache hit → render synchronously (pre-registered via `registerIcons` or
+     * previously loaded). Miss → fire the per-icon lazy loader; the glyph pops in
+     * when the (tiny, per-icon) chunk resolves and stays cached for every other
+     * ds-icon instance.
+     */
+    private resolveSvg;
+    componentWillLoad(): void;
+    /** Last markup injected into the DOM — skips redundant re-parse on unrelated re-renders. */
+    private renderedSvg;
     private updateSvg;
     onIconChange(): void;
     componentDidRender(): void;

package/dist/types/components/Icon/flag-icon-catalog.d.ts

@@ -1,2 +1,3 @@
-export declare const flagIconCatalog: Record<string, string>;
+/** Auto-generated by scripts/generate-icon-catalog.mjs — do not edit. */
+export declare const flagIconLoaders: Record<string, () => Promise<string>>;
 //# sourceMappingURL=flag-icon-catalog.d.ts.map

package/dist/types/components/Icon/icon-cache.d.ts

@@ -0,0 +1,25 @@
+type IconCacheMap = Map<string, string>;
+export declare function iconCacheKey(name: string, flag: boolean): string;
+export declare function iconCache(): IconCacheMap;
+/**
+ * Pre-register glyphs so ds-icon renders them synchronously — no lazy-chunk
+ * fetch, no first-paint pop-in. Import the SVG strings from `@ds-mo/icons`
+ * in the app (statically, so they ship in the app's own bundle):
+ *
+ * ```ts
+ * import { Bell } from '@ds-mo/icons/svg/Bell';
+ * import { US } from '@ds-mo/icons/svg/flags/US';
+ * import { registerIcons } from '@ds-mo/ui/utils';
+ *
+ * registerIcons({ Bell });
+ * registerIcons({ US }, { flag: true });
+ * ```
+ *
+ * Icons that are not registered still work — they lazy-load on first render
+ * and stay cached afterwards.
+ */
+export declare function registerIcons(icons: Record<string, string>, options?: {
+    flag?: boolean;
+}): void;
+export {};
+//# sourceMappingURL=icon-cache.d.ts.map

package/dist/types/components/Icon/icon-svg.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Glyph markup validation + Trusted-Types-safe parsing for ds-icon.
+ *
+ * Glyphs normally come from the trusted @ds-mo/icons build pipeline, but
+ * `registerIcons` accepts arbitrary app-provided strings and injection is a
+ * sink — so every glyph is validated at the render boundary. Injection uses
+ * parsed DOM nodes (never innerHTML), which keeps ds-icon working under a
+ * strict CSP with `require-trusted-types-for 'script'`.
+ */
+/** Structural view of an element so the walk is unit-testable without a DOM. */
+export interface IconSvgElementLike {
+    localName: string;
+    getAttributeNames(): string[];
+    getAttribute(name: string): string | null;
+    children: ArrayLike<IconSvgElementLike>;
+}
+/** True when `root` is an `<svg>` whose whole tree passes validation. */
+export declare function isValidIconSvgRoot(root: IconSvgElementLike | null): boolean;
+/**
+ * Parse + validate glyph markup. Returns a detached `<svg>` element ready to
+ * append (appending adopts it into the document), or `null` when the markup
+ * is not well-formed XML, not rooted at `<svg>`, or fails validation —
+ * ds-icon renders an empty fixed-size box in that case.
+ */
+export declare function parseIconSvg(svg: string): SVGElement | null;
+//# sourceMappingURL=icon-svg.d.ts.map

package/dist/types/components/Icon/system-icon-catalog.d.ts

@@ -1,2 +1,3 @@
-export declare const systemIconCatalog: Record<string, string>;
+/** Auto-generated by scripts/generate-icon-catalog.mjs — do not edit. */
+export declare const systemIconLoaders: Record<string, () => Promise<string>>;
 //# sourceMappingURL=system-icon-catalog.d.ts.map

package/dist/types/components.d.ts

@@ -135,7 +135,7 @@ export namespace Components {
          */
         "count": number;
         /**
-          * Ring samples the shell gradient stack (base fill + wash) instead of a flat `box-shadow`. Auto-enabled in `componentDidLoad` under `ds-app-shell[gradient]`; set `on-gradient-background` to opt in/out explicitly.
+          * Ring samples the shell gradient stack (base fill + wash) instead of a flat `box-shadow`. Auto-enabled in `componentDidLoad` under `ds-app-shell[gradient]`; set `gradient-background` to opt in/out explicitly.  The attribute must NOT start with `on` — Stencil's setAccessor routes any unknown `on*` member down the event-listener path during attribute reflection, calling addEventListener with a non-listener and throwing.
           * @default false
          */
         "gradientBackground": boolean;
@@ -1800,7 +1800,7 @@ declare namespace LocalJSX {
          */
         "count"?: number;
         /**
-          * Ring samples the shell gradient stack (base fill + wash) instead of a flat `box-shadow`. Auto-enabled in `componentDidLoad` under `ds-app-shell[gradient]`; set `on-gradient-background` to opt in/out explicitly.
+          * Ring samples the shell gradient stack (base fill + wash) instead of a flat `box-shadow`. Auto-enabled in `componentDidLoad` under `ds-app-shell[gradient]`; set `gradient-background` to opt in/out explicitly.  The attribute must NOT start with `on` — Stencil's setAccessor routes any unknown `on*` member down the event-listener path during attribute reflection, calling addEventListener with a non-listener and throwing.
           * @default false
          */
         "gradientBackground"?: boolean;

package/dist/types/nav/index.d.ts

@@ -7,7 +7,7 @@ export type { ShellGradientLayout, ShellViewportDimensions } from './shell-gradi
 export type { MenuPlacement } from '../components/Menu/menu-placement';
 export { PANEL_NAV_USER_MENU_PLACEMENT, } from '../components/Menu/menu-placement';
 export type { ShellGradientPreset } from './shell-gradient-presets';
-export { DEFAULT_SHELL_GRADIENT_PRESET, SHELL_GRADIENT_PRESETS, SHELL_GRADIENT_PRESET_LABELS, buildShellRadialGradientForPreset, isShellGradientPreset, shellGradientPresetStopToken, } from './shell-gradient-presets';
+export { DEFAULT_SHELL_GRADIENT_PRESET, SHELL_GRADIENT_PRESETS, SHELL_GRADIENT_PRESET_LABELS, buildShellRadialGradientForPreset, isShellGradientPreset, normalizeShellGradientPreset, shellGradientPresetStopToken, } from './shell-gradient-presets';
 export type { ChromeTransitionDetail, ChromeTransitionSource } from './chrome-transition';
 export { CHROME_TRANSITION_END, CHROME_TRANSITION_START, ChromeTransitionDepth, createRafCoalescer, readChromeTransitionSource, readChromeTransitionPhase, } from './chrome-transition';
 export { barGradientPositionFromPanelWidth, isPanelNavCollapsed, panelWidthPxFromTokens, readCssVarWidthPx, readPanelNavWidthTokens, } from './shell-chrome-metrics';

package/dist/types/nav/shell-gradient-presets.d.ts

@@ -8,6 +8,14 @@ export declare const DEFAULT_SHELL_GRADIENT_PRESET: ShellGradientPreset;
 export declare const SHELL_GRADIENT_PRESET_LABELS: Record<ShellGradientPreset, string>;
 export declare function shellGradientPresetStopToken(preset: ShellGradientPreset): string | null;
 export declare function isShellGradientPreset(value: string): value is ShellGradientPreset;
+/**
+ * Coerce unknown/absent presets to the default. Runtime values escape the
+ * type: removing the reflected `gradient-preset` attribute (e.g. an Angular
+ * `[attr.gradient-preset]="null"` binding) drives the prop to null past its
+ * field default — without normalization the stop lookup interpolates the
+ * literal string "undefined" into CSS and the wash silently disappears.
+ */
+export declare function normalizeShellGradientPreset(value: string | null | undefined): ShellGradientPreset;
 /** Radial wash for a preset — transparent at top-left into the intent stop. `none` returns no image. */
 export declare function buildShellRadialGradientForPreset(preset: ShellGradientPreset): string;
 //# sourceMappingURL=shell-gradient-presets.d.ts.map

package/dist/types/utils/index.d.ts

@@ -1,3 +1,4 @@
+export { registerIcons } from '../components/Icon/icon-cache';
 export { clearCssLengthPxCache, resolveCssLengthPx } from './resolve-css-length-px';
 export { parseCssTimeMs, resolveCssTimeMs } from './resolve-css-time-ms';
 export { SCROLL_EDGE_FADE_DEFAULT_SIZE, SCROLL_EDGE_FADE_SIZE_VAR, scrollEdgeFadeMaskImage, scrollEdgeFadeMaskStyle, } from './scroll-edge-fade';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ds-mo/ui",
-  "version": "2.9.0",
+  "version": "2.10.1",
   "description": "CompoMo — composable web components styled with TokoMo design tokens",
   "keywords": [
     "web-components",
@@ -42,12 +42,12 @@
       "import": "./dist/components/index.js"
     },
     "./nav": {
-      "types": "./src/wc/nav/index.ts",
-      "import": "./src/wc/nav/index.ts"
+      "types": "./dist/lib/nav/index.d.ts",
+      "import": "./dist/lib/nav/index.js"
     },
     "./utils": {
-      "types": "./src/wc/utils/index.ts",
-      "import": "./src/wc/utils/index.ts"
+      "types": "./dist/lib/utils/index.d.ts",
+      "import": "./dist/lib/utils/index.js"
     },
     "./dist/components/*": "./dist/components/*"
   },
@@ -67,9 +67,9 @@
     "prebuild": "node scripts/generate-icon-catalog.mjs",
     "pretypecheck": "node scripts/generate-icon-catalog.mjs",
     "pretest": "node scripts/generate-icon-catalog.mjs",
-    "build": "stencil build && node scripts/patch-index-types.mjs && node scripts/patch-components-d-exports.mjs && node scripts/verify-icons-externalized.mjs && node scripts/write-build-stamp.mjs",
+    "build": "stencil build && node scripts/patch-index-types.mjs && node scripts/patch-components-d-exports.mjs && node scripts/verify-icons-externalized.mjs && node scripts/write-build-stamp.mjs && node scripts/build-lib-exports.mjs",
     "verify:pack": "node scripts/verify-npm-pack.mjs && node scripts/verify-nav-import.mjs",
-    "test": "node --import tsx/esm --test tests/panel-nav-utils.test.ts tests/panel-tools.test.ts tests/shell-shortcuts.test.ts tests/shell-gradient-presets.test.ts tests/shell-view-transition.test.ts tests/shell-gradient.test.ts tests/shell-chrome-metrics.test.ts tests/shell-chrome-layer.test.ts tests/chrome-transition.test.ts tests/bar-nav-overflow-hysteresis.test.ts tests/badge-gradient-ring.test.ts tests/scroll-edge-fade.test.ts tests/resolve-css-length-px.test.ts tests/resolve-css-time-ms.test.ts tests/overlay-positioning.test.ts tests/menu-position.test.ts tests/menu-placement.test.ts tests/bar-nav-utils.test.ts tests/bar-nav-tabs-menu-utils.test.ts tests/bar-nav-dom-utils.test.ts tests/icon-catalog.test.ts",
+    "test": "node --import tsx/esm --test tests/panel-nav-utils.test.ts tests/panel-tools.test.ts tests/shell-shortcuts.test.ts tests/shell-gradient-presets.test.ts tests/shell-view-transition.test.ts tests/shell-gradient.test.ts tests/shell-chrome-metrics.test.ts tests/shell-chrome-layer.test.ts tests/chrome-transition.test.ts tests/bar-nav-overflow-hysteresis.test.ts tests/badge-gradient-ring.test.ts tests/scroll-edge-fade.test.ts tests/resolve-css-length-px.test.ts tests/resolve-css-time-ms.test.ts tests/overlay-positioning.test.ts tests/menu-position.test.ts tests/menu-placement.test.ts tests/bar-nav-utils.test.ts tests/bar-nav-tabs-menu-utils.test.ts tests/bar-nav-dom-utils.test.ts tests/icon-catalog.test.ts tests/icon-cache.test.ts tests/icon-svg.test.ts",
     "test:e2e": "npm run build && playwright test",
     "test:e2e:install": "playwright install chromium",
     "build:docs": "stencil build --docs",
@@ -130,7 +130,8 @@
     "typescript": "~6.0.3",
     "typescript-eslint": "^8.59.1",
     "vite": "^8.0.16",
-    "zod": "^4.4.3"
+    "zod": "^4.4.3",
+    "esbuild": "^0.28.0"
   },
   "engines": {
     "node": "^20.19.0 || >=22.12.0"

package/src/wc/components/Badge/Badge.tsx

@@ -52,9 +52,13 @@ export class Badge {
   /**
    * Ring samples the shell gradient stack (base fill + wash) instead of a flat
    * `box-shadow`. Auto-enabled in `componentDidLoad` under `ds-app-shell[gradient]`;
-   * set `on-gradient-background` to opt in/out explicitly.
+   * set `gradient-background` to opt in/out explicitly.
+   *
+   * The attribute must NOT start with `on` — Stencil's setAccessor routes any
+   * unknown `on*` member down the event-listener path during attribute
+   * reflection, calling addEventListener with a non-listener and throwing.
    */
-  @Prop({ attribute: 'on-gradient-background', reflect: true }) gradientBackground: boolean = false;
+  @Prop({ attribute: 'gradient-background', reflect: true }) gradientBackground: boolean = false;
 
   /** Deprecated alias for selected counter styling. Prefer context-specific color in the parent. */
   @Prop() isSelected: boolean = false;

package/src/wc/components/Icon/Icon.tsx

@@ -1,6 +1,8 @@
-import { Component, Prop, Element, Watch, h, Host } from '@stencil/core';
-import { flagIconCatalog } from './flag-icon-catalog';
-import { systemIconCatalog } from './system-icon-catalog';
+import { Component, Prop, Element, State, Watch, h, Host } from '@stencil/core';
+import { flagIconLoaders } from './flag-icon-catalog';
+import { systemIconLoaders } from './system-icon-catalog';
+import { iconCache, iconCacheKey } from './icon-cache';
+import { parseIconSvg } from './icon-svg';
 
 export type IconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';
 
@@ -47,36 +49,94 @@ export class Icon {
   /** Set `true` to look up from the flag icon set instead of the system icon set. */
   @Prop() flag: boolean = false;
 
-  private get svgString(): string {
-    const source = this.flag ? flagIconCatalog : systemIconCatalog;
-    return source[this.name] ?? '';
+  /** Resolved SVG markup — set synchronously on cache hit, async after a lazy load. */
+  @State() private svg: string = '';
+
+  /** Guards against out-of-order async resolutions when `name`/`flag` change quickly. */
+  private loadToken = 0;
+
+  /**
+   * Cache hit → render synchronously (pre-registered via `registerIcons` or
+   * previously loaded). Miss → fire the per-icon lazy loader; the glyph pops in
+   * when the (tiny, per-icon) chunk resolves and stays cached for every other
+   * ds-icon instance.
+   */
+  private resolveSvg() {
+    const flag = this.flag;
+    const key = iconCacheKey(this.name, flag);
+    const token = ++this.loadToken;
+
+    const cached = iconCache().get(key);
+    if (cached !== undefined) {
+      this.svg = cached;
+      return;
+    }
+
+    // Own-key lookup only: names resolve by exact canonical IcoMo export key —
+    // never meta.json aliases (not in the maps) and never inherited prototype
+    // keys ('constructor', 'toString', …) that a bare index access would hit.
+    const loaders = flag ? flagIconLoaders : systemIconLoaders;
+    const loader = Object.prototype.hasOwnProperty.call(loaders, this.name)
+      ? loaders[this.name]
+      : undefined;
+    if (!loader) {
+      this.svg = '';
+      return;
+    }
+
+    loader()
+      .then(svg => {
+        iconCache().set(key, svg);
+        if (token === this.loadToken) this.svg = svg;
+      })
+      .catch(() => {
+        if (token === this.loadToken) this.svg = '';
+      });
   }
 
+  componentWillLoad() {
+    // Fire-and-forget: do not return the promise — a cache miss must not block
+    // the parent render tree on a network fetch.
+    this.resolveSvg();
+  }
+
+  /** Last markup injected into the DOM — skips redundant re-parse on unrelated re-renders. */
+  private renderedSvg: string | null = null;
+
   private updateSvg() {
     const container = this.el.querySelector<HTMLElement>('.icon__svg');
     if (!container) return;
-    container.innerHTML = this.svgString;
-    // Stencil's scoped CSS cannot reach innerHTML-injected elements (no sc-* class).
-    // Apply width/height as inline styles so sizing works regardless of scope class.
-    const svg = container.querySelector<SVGElement>('svg');
-    if (svg) {
-      svg.removeAttribute('width');
-      svg.removeAttribute('height');
-      // Prevent SVG from being natively focusable (Firefox/IE default) while
-      // sitting inside an aria-hidden parent — fixes aria-hidden-focus violation.
-      svg.setAttribute('focusable', 'false');
-      svg.setAttribute('aria-hidden', 'true');
-      svg.style.display = 'block';
-      svg.style.flexShrink = '0';
-      svg.style.width = '100%';
-      svg.style.height = '100%';
+    if (this.svg === this.renderedSvg) return;
+    this.renderedSvg = this.svg;
+
+    // Validate + inject as parsed DOM nodes — never innerHTML. Keeps ds-icon
+    // Trusted-Types compatible and rejects executable/foreign content in
+    // glyph strings (registerIcons accepts app-provided markup).
+    const svg = this.svg ? parseIconSvg(this.svg) : null;
+    if (!svg) {
+      container.replaceChildren();
+      return;
     }
+
+    // Stencil's scoped CSS cannot reach injected elements (no sc-* class).
+    // Apply width/height as inline styles so sizing works regardless of scope class.
+    svg.removeAttribute('width');
+    svg.removeAttribute('height');
+    // Prevent SVG from being natively focusable (Firefox/IE default) while
+    // sitting inside an aria-hidden parent — fixes aria-hidden-focus violation.
+    svg.setAttribute('focusable', 'false');
+    svg.setAttribute('aria-hidden', 'true');
+    svg.style.display = 'block';
+    svg.style.flexShrink = '0';
+    svg.style.width = '100%';
+    svg.style.height = '100%';
+    container.replaceChildren(svg);
   }
 
   @Watch('name')
   @Watch('flag')
   onIconChange() {
-    this.updateSvg();
+    this.resolveSvg();
   }
 
   componentDidRender() {