@celestia-island/hikari 0.40.10 → 0.40.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.40.10",
+  "version": "0.40.11",
   "private": false,
   "type": "module",
   "description": "Hikari Vue 3 component library — production-grade UI components based on shittim-chest design system",

package/src/components/HkDrawer.tsx

@@ -292,7 +292,7 @@ export default defineComponent({
                       aria-label={t("hikari::drawer.close", "Close")}
                       onClick={close}
                     >
-                      <HIcon name="X" size={16} />
+                      <HIcon name="close" size={16} />
                     </HIconButton>
                   ) : null}
                 </div>

package/src/components/HkIcon.functional.test.ts

@@ -0,0 +1,101 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h } from "vue";
+import { ChevronLeft, X } from "lucide-vue-next";
+
+import HkIcon from "./HkIcon";
+import {
+  functionalIconComponent,
+  functionalIconSvg,
+  hasFunctionalIconOverride,
+  registerFunctionalIconPack,
+  sanitizeSvg,
+} from "../composables/iconRegistry";
+
+const mounts: Array<ReturnType<typeof createApp>> = [];
+
+function mountIcon(name: string): HTMLElement {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp(
+    defineComponent({ setup: () => () => h(HkIcon, { name, size: 16 }) }),
+  );
+  mounts.push(app);
+  app.mount(container);
+  return container;
+}
+
+afterEach(() => {
+  for (const app of mounts.splice(0)) app.unmount();
+  registerFunctionalIconPack(null);
+});
+
+describe("functional icon aliases and material packs", () => {
+  it("maps the semantic keys to the built-in family by default", () => {
+    // Identity with the lucide entries the aliases point at (lucide
+    // components carry no `.name` — identity is the honest check).
+    expect(functionalIconComponent("close")).toBe(X);
+    expect(functionalIconComponent("back")).toBe(ChevronLeft);
+    expect(hasFunctionalIconOverride("close")).toBe(false);
+    expect(functionalIconSvg("close")).toBeNull();
+  });
+
+  it("renders the alias glyph through HkIcon without a pack", () => {
+    const c = mountIcon("close");
+    // lucide X renders as .lucide-x inside the .hk-icon wrapper.
+    expect(c.querySelector(".lucide-x")).not.toBeNull();
+  });
+
+  it("renders a registered material-pack override instead of the alias", () => {
+    registerFunctionalIconPack({
+      close: '<svg viewBox="0 0 24 24" class="pack-close-mark"><path d="M4 4h16v16H4z"/></svg>',
+    });
+    expect(hasFunctionalIconOverride("close")).toBe(true);
+    const c = mountIcon("close");
+    expect(c.querySelector(".pack-close-mark")).not.toBeNull();
+    expect(c.querySelector(".lucide-x")).toBeNull();
+  });
+
+  it("leaves back untouched when the pack only carries close", () => {
+    registerFunctionalIconPack({
+      close: "<svg/>",
+    });
+    expect(hasFunctionalIconOverride("back")).toBe(false);
+    const c = mountIcon("back");
+    expect(c.querySelector(".lucide-chevron-left")).not.toBeNull();
+  });
+
+  it("sanitizes scripts and inline handlers out of pack markup", () => {
+    const dirty =
+      '<svg onload="alert(1)" onclick="x()"><script>alert(2)</script><path d="M4 4" onmouseover="y()"/></svg>';
+    const clean = sanitizeSvg(dirty);
+    expect(clean).not.toContain("script");
+    expect(clean).not.toContain("onload");
+    expect(clean).not.toContain("onclick");
+    expect(clean).not.toContain("onmouseover");
+    expect(clean).toContain("<path");
+    // sanitize applies on the functional render path too.
+    registerFunctionalIconPack({ close: dirty });
+    const c = mountIcon("close");
+    expect(c.querySelector("script")).toBeNull();
+  });
+
+  // Round-2 review vectors (slash separators, unquoted schemes, SMIL).
+  it("neutralizes the round-2 evasion vectors", () => {
+    expect(sanitizeSvg("<svg/onload=alert(1)>")).not.toContain("onload");
+    expect(sanitizeSvg('<svg onload=alert(1)>')).not.toContain("onload");
+    expect(sanitizeSvg('<a href=javascript:alert(1)>t</a>')).not.toContain("javascript:");
+    expect(sanitizeSvg('<a href="javascript:alert(1)">t</a>')).not.toContain("javascript:");
+    expect(sanitizeSvg('<animate attributeName="href" values="javascript:alert(1)"/>')).not.toContain("animate");
+    expect(sanitizeSvg('<set attributeName="onmouseover" to="alert(1)"/>')).not.toContain("set");
+    expect(sanitizeSvg('<iframe src="javascript:alert(1)"></iframe>')).not.toContain("iframe");
+    expect(sanitizeSvg('<foreignObject><body onload="x()"></body></foreignObject>')).not.toContain("foreignObject");
+  });
+
+  it("clearing the pack restores the built-in family", () => {
+    registerFunctionalIconPack({ close: '<svg class="pack"/><svg class="pack"/>' });
+    registerFunctionalIconPack(null);
+    expect(hasFunctionalIconOverride("close")).toBe(false);
+    const c = mountIcon("close");
+    expect(c.querySelector(".lucide-x")).not.toBeNull();
+  });
+});

package/src/components/HkIcon.scss

@@ -26,6 +26,21 @@
   }
 }
 
+// ------
+// Functional icon-button glyph weight (theme-context driven)
+// ------
+// Inside the HkIconButton family — the HIGHLY FUNCTIONAL controls (window
+// close/back, compact action buttons) — the THEME CONTEXT decides how the
+// glyph is drawn, per user direction 2026-09-05: Blue Archive-styled themes
+// keep the bold small default (stroke 2, no scaling) while thin-stroke
+// themes (e.g. Endfield) publish --hk-func-icon-stroke-width / --hk-func-icon-scale
+// from their own layer. A CSS rule here overrides lucide's inline
+// stroke-width PRESENTATION ATTRIBUTE; scoping to .hk-icon-button keeps
+// every plain HkIcon elsewhere untouched.
+.hk-icon-button .hk-icon svg {
+  stroke-width: var(--hk-func-icon-stroke-width, 2);
+}
+
 // ------
 // Icon Size Variants
 // ------

package/src/components/HkIcon.tsx

@@ -1,7 +1,14 @@
 import { defineComponent, type PropType } from "vue";
-import { iconByName } from "../composables/iconRegistry";
+import {
+  functionalIconComponent,
+  functionalIconSvg,
+  iconByName,
+} from "../composables/iconRegistry";
 import "./HkIcon.scss";
 
+/** Semantic functional keys resolved through the alias/pack pipeline. */
+const FUNCTIONAL_KEYS = new Set(["close", "back"]);
+
 export default defineComponent({
   name: "HkIcon",
   props: {
@@ -17,9 +24,25 @@ export default defineComponent({
         props.color ? `hk-icon-${props.color}` : "",
       ];
 
-      // Resolve through the explicit registry: a wildcard import of
-      // lucide-vue-next here defeated tree-shaking and shipped the whole
-      // ~1500-icon library in the shared bundle of every consumer.
+      // Functional keys ("close", "back") resolve through the material-pack
+      // pipeline FIRST (a host theme layer can swap the whole glyph family
+      // at runtime — sanitized raw SVG from the registered pack), then fall
+      // back to the alias's lucide component (close→X, back→ChevronLeft).
+      // Everything else resolves through the explicit lucide registry: a
+      // wildcard import of lucide-vue-next here defeated tree-shaking and
+      // shipped the whole ~1500-icon library in the shared bundle of every
+      // consumer.
+      if (FUNCTIONAL_KEYS.has(props.name)) {
+        const svg = functionalIconSvg(props.name);
+        if (svg) {
+          return (
+            <span class={cls} v-html={svg} />
+          );
+        }
+        const FuncComp = functionalIconComponent(props.name) as any;
+        return <span class={cls}><FuncComp /></span>;
+      }
+
       const IconComp = iconByName(props.name) as any;
       return <span class={cls}><IconComp /></span>;
     };

package/src/components/HkIconButton.scss

@@ -151,6 +151,13 @@
       height: var(--hi-icon-button-icon-size);
       display: block;
     }
+
+    // Theme-context glyph size (user direction 2026-09-05): BA themes keep
+    // scale 1; thin-stroke themes publish a >1 scale for their slightly
+    // larger functional glyphs. transform keeps the 32px hit box intact.
+    .hk-icon {
+      transform: scale(var(--hk-func-icon-scale, 1));
+    }
   }
 
   // Active state for icon

package/src/components/HkImageLightbox.tsx

@@ -75,7 +75,7 @@ export default defineComponent({
             aria-label={t("hikari::imageLightbox.close", "Close")}
             onClick={close}
           >
-            <HIcon name="X" size={16} />
+            <HIcon name="close" size={16} />
           </HIconButton>
         </div>
       </HModal>

package/src/components/HkModal.tsx

@@ -752,7 +752,7 @@ export default defineComponent({
                             aria-label={t("hikari::modal.close", "Close")}
                             onClick={close}
                           >
-                            <HIcon name="X" size={16} />
+                            <HIcon name="close" size={16} />
                           </HIconButton>
                         )}
                       </div>

package/src/components/HkPopover.tsx

@@ -593,7 +593,7 @@ export default defineComponent({
                       aria-label={t("hikari::modal.close", "Close")}
                       onClick={close}
                     >
-                      <HIcon name="X" size={16} />
+                      <HIcon name="close" size={16} />
                     </HIconButton>
                   </div>
                 )}

package/src/components/HkSelectPanel.tsx

@@ -563,7 +563,7 @@ export default defineComponent({
                       aria-label={t("hikari::modal.close", "Close")}
                       onClick={close}
                     >
-                      <HIcon name="X" size={16} />
+                      <HIcon name="close" size={16} />
                     </HIconButton>
                   </div>
                   <div class="hk-select-sheet-body" ref={sheetBodyRef}>

package/src/components/func-icon-theme.contract.test.ts

@@ -0,0 +1,44 @@
+/**
+ * Source contract for the theme-context-driven functional icon rendering
+ * (user direction 2026-09-05: the close/back functional controls are drawn
+ * BY THE THEME CONTEXT — Blue Archive themes keep the bold small default,
+ * thin-stroke themes like Endfield publish their own weight/size/motion).
+ *
+ * The mechanism is a pure custom-property family: a theme layer publishes
+ * --hk-func-icon-* on any root and every HkIconButton glyph + window-close
+ * hover picks it up. No JS plumbing, no per-theme component forks.
+ *
+ * Pinned here so the consumption points cannot silently disappear (the
+ * same "looks themed but never shipped" failure class as the sheet-dock
+ * contracts).
+ */
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const read = (f: string): string => readFileSync(join(here, f), "utf-8");
+
+describe("functional icon theme-context contract", () => {
+  it("draws icon-button glyphs with the theme stroke width", () => {
+    const css = read("HkIcon.scss");
+    // Scoped to the functional family: plain HkIcons elsewhere must keep
+    // the lucide default weight.
+    expect(css).toContain(".hk-icon-button .hk-icon svg");
+    expect(css).toContain("var(--hk-func-icon-stroke-width, 2)");
+  });
+
+  it("scales icon-button glyphs with the theme size factor", () => {
+    const css = read("HkIconButton.scss");
+    expect(css).toContain("var(--hk-func-icon-scale, 1)");
+  });
+
+  it("expresses the window-close hover motion through the var family", () => {
+    const css = read("window-close.scss");
+    expect(css).toContain("var(--hk-func-icon-hover-duration, 0.15s)");
+    expect(css).toContain("var(--hk-func-icon-hover-ease, ease)");
+    expect(css).toContain("--hk-func-icon-hover-bg,");
+    expect(css).toContain("--hk-func-icon-hover-color,");
+  });
+});

package/src/components/window-close.contract.test.ts

@@ -28,14 +28,16 @@ const WINDOW_FILES = [
 ];
 
 describe("unified window-close contract", () => {
-  it("renders every close control as HkIconButton + the X glyph", () => {
+  it("renders every close control as HkIconButton + the functional close key", () => {
     for (const f of WINDOW_FILES) {
       const src = readFileSync(join(here, f), "utf-8");
       expect(src, `${f} must carry the shared grammar class`).toContain(
         "hk-window-close",
       );
-      expect(src, `${f} must render the registry X glyph`).toContain(
-        'HIcon name="X"',
+      // Semantic key: the theme context's material pack can swap the glyph
+      // family at runtime (iconRegistry resolves close → X by default).
+      expect(src, `${f} must render the functional close key`).toContain(
+        'HIcon name="close"',
       );
       expect(src, `${f} must close via HkIconButton`).toContain("HIconButton");
     }

package/src/components/window-close.scss

@@ -13,19 +13,46 @@
 // gets the hover tint HkIconButton intentionally leaves to the Glow
 // wrapper (window headers render no Glow). The `--hk-modal-close-hover-*`
 // custom properties stay the shared host tunables for that tint.
+//
+// THE THEME CONTEXT DECIDES THE MOTION (user direction 2026-09-05): the
+// hover choreography is expressed entirely through the --hk-func-icon-*
+// custom properties, so a theme layer restyles every functional control
+// without touching this file:
+//   --hk-func-icon-stroke-width   glyph weight (consumed in HkIcon.scss)
+//   --hk-func-icon-scale          glyph size scale (HkIconButton.scss)
+//   --hk-func-icon-hover-duration hover transition length
+//   --hk-func-icon-hover-ease     hover transition curve
+//   --hk-func-icon-hover-bg       hover background (transparent = snap)
+//   --hk-func-icon-hover-color    hover glyph color
+// Defaults below are the Blue Archive grammar: soft tint fade. A thin-
+// stroke theme (Endfield) publishes a transparent background, a snap
+// duration and an accent glyph color instead.
 // ------
 .hk-icon-button.hk-window-close {
   user-select: none;
   -webkit-user-select: none;
+  transition:
+    background
+      var(--hk-func-icon-hover-duration, 0.15s)
+      var(--hk-func-icon-hover-ease, ease),
+    color
+      var(--hk-func-icon-hover-duration, 0.15s)
+      var(--hk-func-icon-hover-ease, ease);
 
   &:hover {
     background: var(
-      --hk-modal-close-hover-bg,
-      var(--hi-secondary-bg, rgba(0, 0, 0, 0.06))
+      --hk-func-icon-hover-bg,
+      var(
+        --hk-modal-close-hover-bg,
+        var(--hi-secondary-bg, rgba(0, 0, 0, 0.06))
+      )
     );
     color: var(
-      --hk-modal-close-hover-color,
-      var(--hi-color-text-primary, #333)
+      --hk-func-icon-hover-color,
+      var(
+        --hk-modal-close-hover-color,
+        var(--hi-color-text-primary, #333)
+      )
     );
   }
 }

package/src/composables/iconRegistry.ts

@@ -125,3 +125,103 @@ export function iconByName(name: string | undefined | null): Component {
   }
   return Info;
 }
+
+// ------
+// Functional icon aliases + host-provided material packs (材质包).
+//
+// Window chrome renders SEMANTIC names ("close", "back") instead of
+// literal lucide names, so a host theme layer can swap the whole glyph
+// family at runtime — user direction 2026-09-05. Resolution order in
+// functionalIconSvg():
+//   1. host material-pack override for the semantic key (raw SVG string,
+//      sanitized at render time),
+//   2. the semantic alias's default lucide component,
+//   3. `Info` (never reached for the built-in keys).
+// `registerFunctionalIconPack(null)` clears the pack and restores the
+// built-in family. Packs ride the module singleton: applications register
+// once at theme-apply time, exactly like the CSS-var publication.
+// ------
+
+/** Semantic key → default lucide component for the built-in family. */
+const FUNCTIONAL_ALIASES: Record<string, Component> = {
+  close: X,
+  back: ChevronLeft,
+};
+
+let functionalPack: Record<string, string> | null = null;
+
+/**
+ * Install (or clear with `null`) the host's material pack: semantic key →
+ * raw SVG markup. The SVG string is sanitized when rendered (script blocks
+ * and event-handler attributes stripped); callers own upload validation.
+ */
+export function registerFunctionalIconPack(
+  pack: Record<string, string> | null,
+): void {
+  functionalPack = pack && Object.keys(pack).length > 0 ? pack : null;
+}
+
+/** True when a material pack carries an override for `key`. */
+export function hasFunctionalIconOverride(key: string): boolean {
+  return !!functionalPack && !!functionalPack[key];
+}
+
+/**
+ * Hardened sanitizer for host-provided SVG markup (render path is v-html).
+ *
+ * Deterministic + synchronous by design — the render path cannot await a
+ * lazy DOMPurify chunk. Hardened against the classic evasion classes
+ * (round-2 review vectors): slash-separated event attributes
+ * (`<svg/onload=…>`), unquoted `javascript:` URLs, dangerous element
+ * families (script/iframe/object/embed/foreignObject/animate/set/base/
+ * meta/form) and SMIL attribute-mutation primitives. NOT an HTML/SVG
+ * allowlist parser: material packs are user-local configuration today —
+ * if they ever become shareable files, switch to the DOMPurify allowlist
+ * (the dependency already ships for HkMarkdownRenderer) before doing so.
+ */
+const SVG_DENIED_TAGS =
+  /<(\/?)(script|iframe|object|embed|foreignObject|animate|set|base|meta|form)\b[^>]*>/gi;
+const SVG_SCRIPT_BLOCKS = /<script\b[\s\S]*?<\/script\s*>/gi;
+// Value groups deliberately STOP at their own closing quote — a greedy
+// any-char alternation would swallow the rest of the tag and let later
+// event attributes survive.
+const SVG_EVENT_ATTRS =
+  /[\s/]on[a-z-]+\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi;
+const SVG_SCHEME_ATTRS =
+  /(\s(?:xlink:)?(?:href|src)\s*=\s*)("[^"]*"|'[^']*'|[^\s>]+)/gi;
+const SVG_DANGEROUS_SCHEME = /^\s*(?:javascript|vbscript|data:text\/html)/i;
+
+export function sanitizeSvg(svg: string): string {
+  // 1. Script blocks and whole dangerous element families are removed
+  //    (SMIL mutation primitives like <animate>/<set> included).
+  // 2. Event handler attributes — slash separators included — are renamed
+  //    to an inert attribute; the handler can never fire again.
+  // 3. URL-carrying attributes with script-ish schemes are dropped whole.
+  let out = svg
+    .replace(SVG_SCRIPT_BLOCKS, "")
+    .replace(SVG_DENIED_TAGS, "<$1nothing>");
+  out = out.replace(SVG_EVENT_ATTRS, (_m, value: string) => ` data-stripped=${value}`);
+  out = out.replace(SVG_SCHEME_ATTRS, (match, _prefix: string, value: string) =>
+    SVG_DANGEROUS_SCHEME.test(value.replace(/^["']/, "").replace(/["']$/, ""))
+      ? ""
+      : match,
+  );
+  return out;
+}
+
+/**
+ * Render payload for a functional icon key: a raw-SVG string when the
+ * material pack overrides it, `null` when the caller should fall back to
+ * the alias's lucide component.
+ */
+export function functionalIconSvg(key: string): string | null {
+  if (functionalPack && functionalPack[key]) {
+    return sanitizeSvg(functionalPack[key]);
+  }
+  return null;
+}
+
+/** Default lucide component for a functional key (alias lookup). */
+export function functionalIconComponent(key: string): Component {
+  return FUNCTIONAL_ALIASES[key] ?? Info;
+}

package/src/index.ts

@@ -269,7 +269,12 @@ export type { HealthProbeBody, HealthProbeResult } from "./utils/healthProbe";
 
 export { highlight, useHighlight } from "./composables/useHighlight";
 export { LANGUAGE_LOADERS } from "./composables/highlightLanguages";
-export { iconByName } from "./composables/iconRegistry";
+export {
+  iconByName,
+  registerFunctionalIconPack,
+  functionalIconSvg,
+  sanitizeSvg,
+} from "./composables/iconRegistry";
 export { useMessaging, registerTransport, registerNativeBridge } from "./composables/messaging";
 export type { MessagePayload, MessageSeverity, MessageTransport, NotifyOptions, TransportName } from "./composables/messaging";