@ds-mo/ui 2.9.0 → 2.10.0

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/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.0",
   "description": "CompoMo — composable web components styled with TokoMo design tokens",
   "keywords": [
     "web-components",
@@ -69,7 +69,7 @@
     "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",
     "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",

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() {

package/src/wc/components/Icon/flag-icon-catalog.ts

@@ -1,68 +1,36 @@
 /** Auto-generated by scripts/generate-icon-catalog.mjs — do not edit. */
-import { FlagAustria } from '@ds-mo/icons/svg/flags/FlagAustria';
-import { FlagBelgium } from '@ds-mo/icons/svg/flags/FlagBelgium';
-import { FlagBulgaria } from '@ds-mo/icons/svg/flags/FlagBulgaria';
-import { FlagCanada } from '@ds-mo/icons/svg/flags/FlagCanada';
-import { FlagCroatia } from '@ds-mo/icons/svg/flags/FlagCroatia';
-import { FlagCyprus } from '@ds-mo/icons/svg/flags/FlagCyprus';
-import { FlagCzechRepublic } from '@ds-mo/icons/svg/flags/FlagCzechRepublic';
-import { FlagDenmark } from '@ds-mo/icons/svg/flags/FlagDenmark';
-import { FlagEU } from '@ds-mo/icons/svg/flags/FlagEU';
-import { FlagEstonia } from '@ds-mo/icons/svg/flags/FlagEstonia';
-import { FlagFinland } from '@ds-mo/icons/svg/flags/FlagFinland';
-import { FlagFrance } from '@ds-mo/icons/svg/flags/FlagFrance';
-import { FlagGermany } from '@ds-mo/icons/svg/flags/FlagGermany';
-import { FlagGreece } from '@ds-mo/icons/svg/flags/FlagGreece';
-import { FlagHungary } from '@ds-mo/icons/svg/flags/FlagHungary';
-import { FlagIreland } from '@ds-mo/icons/svg/flags/FlagIreland';
-import { FlagItaly } from '@ds-mo/icons/svg/flags/FlagItaly';
-import { FlagLatvia } from '@ds-mo/icons/svg/flags/FlagLatvia';
-import { FlagLithuania } from '@ds-mo/icons/svg/flags/FlagLithuania';
-import { FlagLuxembourg } from '@ds-mo/icons/svg/flags/FlagLuxembourg';
-import { FlagMalta } from '@ds-mo/icons/svg/flags/FlagMalta';
-import { FlagMexico } from '@ds-mo/icons/svg/flags/FlagMexico';
-import { FlagNetherlands } from '@ds-mo/icons/svg/flags/FlagNetherlands';
-import { FlagPoland } from '@ds-mo/icons/svg/flags/FlagPoland';
-import { FlagPortugal } from '@ds-mo/icons/svg/flags/FlagPortugal';
-import { FlagRomania } from '@ds-mo/icons/svg/flags/FlagRomania';
-import { FlagSlovakia } from '@ds-mo/icons/svg/flags/FlagSlovakia';
-import { FlagSlovenia } from '@ds-mo/icons/svg/flags/FlagSlovenia';
-import { FlagSpain } from '@ds-mo/icons/svg/flags/FlagSpain';
-import { FlagSweden } from '@ds-mo/icons/svg/flags/FlagSweden';
-import { FlagUnitedKingdom } from '@ds-mo/icons/svg/flags/FlagUnitedKingdom';
-import { FlagUnitedStates } from '@ds-mo/icons/svg/flags/FlagUnitedStates';
 
-export const flagIconCatalog: Record<string, string> = {
-  FlagAustria,
-  FlagBelgium,
-  FlagBulgaria,
-  FlagCanada,
-  FlagCroatia,
-  FlagCyprus,
-  FlagCzechRepublic,
-  FlagDenmark,
-  FlagEU,
-  FlagEstonia,
-  FlagFinland,
-  FlagFrance,
-  FlagGermany,
-  FlagGreece,
-  FlagHungary,
-  FlagIreland,
-  FlagItaly,
-  FlagLatvia,
-  FlagLithuania,
-  FlagLuxembourg,
-  FlagMalta,
-  FlagMexico,
-  FlagNetherlands,
-  FlagPoland,
-  FlagPortugal,
-  FlagRomania,
-  FlagSlovakia,
-  FlagSlovenia,
-  FlagSpain,
-  FlagSweden,
-  FlagUnitedKingdom,
-  FlagUnitedStates,
+export const flagIconLoaders: Record<string, () => Promise<string>> = {
+  FlagAustria: () => import('@ds-mo/icons/svg/flags/FlagAustria').then(m => m.FlagAustria),
+  FlagBelgium: () => import('@ds-mo/icons/svg/flags/FlagBelgium').then(m => m.FlagBelgium),
+  FlagBulgaria: () => import('@ds-mo/icons/svg/flags/FlagBulgaria').then(m => m.FlagBulgaria),
+  FlagCanada: () => import('@ds-mo/icons/svg/flags/FlagCanada').then(m => m.FlagCanada),
+  FlagCroatia: () => import('@ds-mo/icons/svg/flags/FlagCroatia').then(m => m.FlagCroatia),
+  FlagCyprus: () => import('@ds-mo/icons/svg/flags/FlagCyprus').then(m => m.FlagCyprus),
+  FlagCzechRepublic: () => import('@ds-mo/icons/svg/flags/FlagCzechRepublic').then(m => m.FlagCzechRepublic),
+  FlagDenmark: () => import('@ds-mo/icons/svg/flags/FlagDenmark').then(m => m.FlagDenmark),
+  FlagEU: () => import('@ds-mo/icons/svg/flags/FlagEU').then(m => m.FlagEU),
+  FlagEstonia: () => import('@ds-mo/icons/svg/flags/FlagEstonia').then(m => m.FlagEstonia),
+  FlagFinland: () => import('@ds-mo/icons/svg/flags/FlagFinland').then(m => m.FlagFinland),
+  FlagFrance: () => import('@ds-mo/icons/svg/flags/FlagFrance').then(m => m.FlagFrance),
+  FlagGermany: () => import('@ds-mo/icons/svg/flags/FlagGermany').then(m => m.FlagGermany),
+  FlagGreece: () => import('@ds-mo/icons/svg/flags/FlagGreece').then(m => m.FlagGreece),
+  FlagHungary: () => import('@ds-mo/icons/svg/flags/FlagHungary').then(m => m.FlagHungary),
+  FlagIreland: () => import('@ds-mo/icons/svg/flags/FlagIreland').then(m => m.FlagIreland),
+  FlagItaly: () => import('@ds-mo/icons/svg/flags/FlagItaly').then(m => m.FlagItaly),
+  FlagLatvia: () => import('@ds-mo/icons/svg/flags/FlagLatvia').then(m => m.FlagLatvia),
+  FlagLithuania: () => import('@ds-mo/icons/svg/flags/FlagLithuania').then(m => m.FlagLithuania),
+  FlagLuxembourg: () => import('@ds-mo/icons/svg/flags/FlagLuxembourg').then(m => m.FlagLuxembourg),
+  FlagMalta: () => import('@ds-mo/icons/svg/flags/FlagMalta').then(m => m.FlagMalta),
+  FlagMexico: () => import('@ds-mo/icons/svg/flags/FlagMexico').then(m => m.FlagMexico),
+  FlagNetherlands: () => import('@ds-mo/icons/svg/flags/FlagNetherlands').then(m => m.FlagNetherlands),
+  FlagPoland: () => import('@ds-mo/icons/svg/flags/FlagPoland').then(m => m.FlagPoland),
+  FlagPortugal: () => import('@ds-mo/icons/svg/flags/FlagPortugal').then(m => m.FlagPortugal),
+  FlagRomania: () => import('@ds-mo/icons/svg/flags/FlagRomania').then(m => m.FlagRomania),
+  FlagSlovakia: () => import('@ds-mo/icons/svg/flags/FlagSlovakia').then(m => m.FlagSlovakia),
+  FlagSlovenia: () => import('@ds-mo/icons/svg/flags/FlagSlovenia').then(m => m.FlagSlovenia),
+  FlagSpain: () => import('@ds-mo/icons/svg/flags/FlagSpain').then(m => m.FlagSpain),
+  FlagSweden: () => import('@ds-mo/icons/svg/flags/FlagSweden').then(m => m.FlagSweden),
+  FlagUnitedKingdom: () => import('@ds-mo/icons/svg/flags/FlagUnitedKingdom').then(m => m.FlagUnitedKingdom),
+  FlagUnitedStates: () => import('@ds-mo/icons/svg/flags/FlagUnitedStates').then(m => m.FlagUnitedStates),
 };

package/src/wc/components/Icon/icon-cache.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared SVG glyph cache for ds-icon.
+ *
+ * Keyed on a global symbol so every module instance (the compiled Stencil chunk
+ * inside dist/components and any direct source import, e.g. via `@ds-mo/ui/utils`)
+ * reads and writes the same cache. Without this, `registerIcons` called from an
+ * app would fill a different Map than the one ds-icon resolves from.
+ */
+const CACHE_KEY = Symbol.for('ds-mo.icon-svg-cache');
+
+type IconCacheMap = Map<string, string>;
+
+type GlobalWithIconCache = { [CACHE_KEY]?: IconCacheMap };
+
+export function iconCacheKey(name: string, flag: boolean): string {
+  return flag ? `flag:${name}` : `system:${name}`;
+}
+
+export function iconCache(): IconCacheMap {
+  const g = globalThis as GlobalWithIconCache;
+  return (g[CACHE_KEY] ??= new Map());
+}
+
+/**
+ * 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 function registerIcons(icons: Record<string, string>, options?: { flag?: boolean }): void {
+  const cache = iconCache();
+  const flag = options?.flag === true;
+  for (const [name, svg] of Object.entries(icons)) {
+    cache.set(iconCacheKey(name, flag), svg);
+  }
+}

package/src/wc/components/Icon/icon-svg.ts

@@ -0,0 +1,73 @@
+/**
+ * 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>;
+}
+
+/** Elements that can execute or embed foreign content — never valid in a glyph. */
+const FORBIDDEN_ELEMENTS = new Set([
+  'script',
+  'foreignobject',
+  'iframe',
+  'object',
+  'embed',
+  'animation', // SVG 1.2 external-content element (distinct from animate/animateTransform)
+]);
+
+function isValidIconSvgElement(el: IconSvgElementLike): boolean {
+  if (FORBIDDEN_ELEMENTS.has(el.localName.toLowerCase())) return false;
+
+  for (const attr of el.getAttributeNames()) {
+    const lower = attr.toLowerCase();
+    // Event handler attributes (onclick, onload, …) — any casing.
+    if (lower.startsWith('on')) return false;
+    // References must stay internal (#gradient-id); rejects javascript:, data:,
+    // and external URLs on <use>, <a>, <image>, …
+    if (lower === 'href' || lower === 'xlink:href') {
+      const value = el.getAttribute(attr) ?? '';
+      if (!value.startsWith('#')) return false;
+    }
+  }
+
+  for (let i = 0; i < el.children.length; i++) {
+    if (!isValidIconSvgElement(el.children[i])) return false;
+  }
+
+  return true;
+}
+
+/** True when `root` is an `<svg>` whose whole tree passes validation. */
+export function isValidIconSvgRoot(root: IconSvgElementLike | null): boolean {
+  return root != null && root.localName === 'svg' && isValidIconSvgElement(root);
+}
+
+/**
+ * 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 function parseIconSvg(svg: string): SVGElement | null {
+  if (typeof DOMParser === 'undefined') return null;
+
+  const doc = new DOMParser().parseFromString(svg, 'image/svg+xml');
+  // Malformed XML yields a parsererror document (root or nested, per browser).
+  if (doc.querySelector('parsererror')) return null;
+
+  const root = doc.documentElement as unknown as IconSvgElementLike;
+  if (!isValidIconSvgRoot(root)) return null;
+
+  return doc.documentElement as unknown as SVGElement;
+}