@celestia-island/hikari 0.55.207 → 0.55.208

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.207",
+  "version": "0.55.208",
   "private": false,
   "type": "module",
   "description": "Hikari UI library, Vue 3 runtime — one design system for Vue 3 and Rust/WASM applications",

package/src/components/HkTreemap.scss

@@ -0,0 +1,88 @@
+.hk-treemap {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  min-height: 0;
+}
+
+.hk-treemap__legend {
+  display: flex;
+  flex: 0 0 auto;
+  flex-wrap: wrap;
+  gap: 0.375rem 0.875rem;
+  margin: 0 0 0.625rem;
+  padding: 0;
+  list-style: none;
+  font-size: var(--text-xs, 0.75rem);
+  line-height: 1.4;
+  color: rgb(var(--color-text, 32 32 32));
+}
+
+.hk-treemap__legend-item {
+  display: inline-flex;
+  align-items: center;
+  min-width: 0;
+  gap: 0.3rem;
+}
+
+.hk-treemap__legend-swatch {
+  flex: 0 0 auto;
+  width: 0.625rem;
+  height: 0.625rem;
+  border-radius: 0.1875rem;
+}
+
+.hk-treemap__legend-label {
+  max-width: 14rem;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.hk-treemap__legend-value {
+  color: rgb(var(--color-muted, 108 108 108));
+  font-variant-numeric: tabular-nums;
+}
+
+.hk-treemap__legend-percent {
+  color: rgb(var(--color-muted, 108 108 108));
+  font-variant-numeric: tabular-nums;
+}
+
+.hk-treemap__body {
+  position: relative;
+  flex: 1 1 auto;
+  width: 100%;
+  min-height: 0;
+}
+
+.hk-treemap__chart {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+}
+
+.hk-treemap__empty {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  padding: 1rem;
+  color: rgb(var(--color-muted, 108 108 108));
+  font-size: var(--text-sm, 0.8125rem);
+  text-align: center;
+}
+
+.hk-treemap__a11y-summary {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}

package/src/components/HkTreemap.test.tsx

@@ -0,0 +1,452 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, reactive } from "vue";
+
+const H = vi.hoisted(() => {
+  class FakeChart {
+    static instances: FakeChart[] = [];
+    readonly options: unknown[] = [];
+    clearCount = 0;
+    resizeCount = 0;
+    disposed = false;
+
+    constructor(readonly element: HTMLElement) {
+      FakeChart.instances.push(this);
+    }
+
+    setOption(option: unknown): void {
+      this.options.push(option);
+    }
+
+    clear(): void {
+      this.clearCount += 1;
+    }
+
+    resize(): void {
+      this.resizeCount += 1;
+    }
+
+    dispose(): void {
+      this.disposed = true;
+    }
+  }
+
+  return {
+    FakeChart,
+    init: vi.fn(),
+    use: vi.fn(),
+    importGate: null as Promise<void> | null,
+  };
+});
+
+vi.mock("echarts/core", () => ({
+  init: H.init,
+  use: H.use,
+}));
+
+vi.mock("echarts/charts", async () => {
+  if (H.importGate) await H.importGate;
+  return { TreemapChart: { name: "TreemapChart" } };
+});
+
+vi.mock("echarts/components", () => ({
+  TooltipComponent: { name: "TooltipComponent" },
+}));
+
+vi.mock("echarts/renderers", () => ({
+  CanvasRenderer: { name: "CanvasRenderer" },
+}));
+
+import HkTreemap, {
+  HK_TREEMAP_DEFAULT_COLORS,
+  buildHkTreemapLayout,
+  contrastTextColor,
+  createHkTreemapOption,
+  createHkTreemapSummary,
+  formatHkTreemapPercent,
+  type HkTreemapNode,
+} from "./HkTreemap";
+
+class FakeResizeObserver {
+  static instances: FakeResizeObserver[] = [];
+  readonly observed: Element[] = [];
+  disconnected = false;
+
+  constructor(readonly callback: () => void) {
+    FakeResizeObserver.instances.push(this);
+  }
+
+  observe(element: Element): void {
+    this.observed.push(element);
+  }
+
+  disconnect(): void {
+    this.disconnected = true;
+  }
+}
+
+const originalResizeObserver = globalThis.ResizeObserver;
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+const NODES: HkTreemapNode[] = [
+  {
+    id: "group",
+    label: "Group",
+    value: 999,
+    children: [
+      { id: "a", label: "Alpha", value: 2 },
+      { id: "b", label: "Beta", value: 4 },
+    ],
+  },
+  { id: "other", label: "Other", value: 4 },
+];
+
+function mountTreemap(initialProps: Record<string, unknown> = { nodes: NODES }) {
+  const props = reactive<Record<string, unknown>>({ ...initialProps });
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp(
+    defineComponent({
+      setup() {
+        return () => h(HkTreemap, { ...props });
+      },
+    }),
+  );
+  app.mount(container);
+  const mounted = { app, container };
+  mounts.push(mounted);
+  return {
+    ...mounted,
+    update(next: Record<string, unknown>) {
+      Object.assign(props, next);
+    },
+  };
+}
+
+function unmount(mounted: { app: ReturnType<typeof createApp>; container: HTMLElement }) {
+  const index = mounts.findIndex((item) => item.app === mounted.app);
+  if (index >= 0) mounts.splice(index, 1);
+  mounted.app.unmount();
+  mounted.container.remove();
+}
+
+async function waitForChart(): Promise<void> {
+  await vi.waitFor(() => expect(H.FakeChart.instances).toHaveLength(1));
+  await nextTick();
+}
+
+function lastOption(): any {
+  const chart = H.FakeChart.instances[0]!;
+  return chart.options[chart.options.length - 1];
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  H.FakeChart.instances = [];
+  H.importGate = null;
+  H.init.mockImplementation((element: HTMLElement) => new H.FakeChart(element));
+  FakeResizeObserver.instances = [];
+  globalThis.ResizeObserver = FakeResizeObserver as unknown as typeof ResizeObserver;
+});
+
+afterEach(() => {
+  for (const mounted of mounts.splice(0)) {
+    mounted.app.unmount();
+    mounted.container.remove();
+  }
+  globalThis.ResizeObserver = originalResizeObserver;
+});
+
+describe("HkTreemap pure layout input", () => {
+  it("sums nested groups from leaves and ignores caller-provided parent values", () => {
+    const layout = buildHkTreemapLayout([
+      {
+        id: "root",
+        label: "Root",
+        value: 1000,
+        children: [
+          { id: "leaf", label: "Leaf", value: 2 },
+          {
+            id: "nested",
+            label: "Nested",
+            value: 900,
+            children: [{ id: "deep", label: "Deep", value: 3 }],
+          },
+        ],
+      },
+      { id: "top", label: "Top", value: 5 },
+    ]);
+
+    expect(layout.total).toBe(10);
+    expect(layout.nodes[0]!.value).toBe(5);
+    expect(layout.nodes[0]!.children![1]!.value).toBe(3);
+    expect(layout.nodes[1]!.value).toBe(5);
+  });
+
+  it("filters zero, negative and non-finite values before calculating totals", () => {
+    const layout = buildHkTreemapLayout([
+      {
+        id: "valid",
+        label: "Valid",
+        value: 0,
+        children: [
+          { id: "zero", label: "Zero", value: 0 },
+          { id: "negative", label: "Negative", value: -2 },
+          { id: "nan", label: "NaN", value: Number.NaN },
+          { id: "infinite", label: "Infinite", value: Number.POSITIVE_INFINITY },
+          { id: "neg-infinite", label: "Negative infinite", value: Number.NEGATIVE_INFINITY },
+          { id: "kept", label: "Kept", value: 4 },
+        ],
+      },
+      {
+        id: "invalid-group",
+        label: "Invalid group",
+        value: 500,
+        children: [{ id: "invalid-leaf", label: "Invalid", value: 0 }],
+      },
+    ]);
+
+    expect(layout.nodes).toHaveLength(1);
+    expect(layout.nodes[0]!.children!.map((node) => node.id)).toEqual(["kept"]);
+    expect(layout.nodes[0]!.value).toBe(4);
+    expect(layout.total).toBe(4);
+  });
+
+  it("uses all visible leaves in the chart as the percentage denominator", () => {
+    const layout = buildHkTreemapLayout(NODES);
+    const group = layout.nodes[0]!;
+    const alpha = group.children![0]!;
+    const beta = group.children![1]!;
+    const other = layout.nodes[1]!;
+
+    expect(layout.total).toBe(10);
+    expect(group.percent).toBe(60);
+    expect(alpha.percent).toBe(20);
+    expect(beta.percent).toBe(40);
+    expect(other.percent).toBe(40);
+    expect(alpha.percent + beta.percent + other.percent).toBe(100);
+  });
+
+  it("assigns deterministic top-level palette colors and honors opaque overrides", () => {
+    const nodes: HkTreemapNode[] = [
+      { id: "first", label: "First", value: 1 },
+      {
+        id: "custom",
+        label: "Custom",
+        value: 1,
+        color: "#123456",
+        children: [{ id: "child", label: "Child", value: 1 }],
+      },
+      { id: "third", label: "Third", value: 1 },
+    ];
+    const first = buildHkTreemapLayout(nodes);
+    const second = buildHkTreemapLayout(nodes);
+
+    expect(first).toEqual(second);
+    // Host hex overrides normalize to an opaque canvas-paintable rgb() form.
+    expect(first.nodes.map((node) => node.color)).toEqual([
+      HK_TREEMAP_DEFAULT_COLORS[0],
+      "rgb(18 52 86)",
+      HK_TREEMAP_DEFAULT_COLORS[2],
+    ]);
+    expect(first.nodes[1]!.children![0]!.color).toBe("rgb(18 52 86)");
+  });
+
+  it("returns a genuinely empty model for absent or entirely invalid data", () => {
+    expect(buildHkTreemapLayout([])).toEqual({ nodes: [], total: 0 });
+    expect(
+      buildHkTreemapLayout([
+        { id: "zero", label: "Zero", value: 0 },
+        { id: "nan", label: "NaN", value: Number.NaN },
+      ]),
+    ).toEqual({ nodes: [], total: 0 });
+  });
+
+  it("chooses readable label colours across pale, mid-tone and dark backgrounds", () => {
+    const option = createHkTreemapOption(buildHkTreemapLayout([
+      { id: "pale", label: "Pale", value: 1, color: "#edc948" },
+      { id: "dark", label: "Dark", value: 1, color: "#4e79a7" },
+      { id: "mid", label: "Mid", value: 1, color: "#76b7b2" },
+      { id: "rgb", label: "RGB", value: 1, color: "rgb(242, 142, 43)" },
+      { id: "invalid", label: "Invalid", value: 1, color: "var(--x)" },
+    ])) as any;
+    const data = option.series[0].data;
+    expect(data[0].label.color).toBe("#0b1220");
+    expect(data[0].upperLabel.color).toBe("#0b1220");
+    expect(data[1].label.color).toBe("#fff");
+    expect(data[2].label.color).toBe("#0b1220");
+    expect(data[3].label.color).toBe("#0b1220");
+    // An unparseable/translucent override falls back to the palette colour
+    // (inherited #e15759) instead of corrupting the canvas fill.
+    expect(data[4].label.color).toBe(contrastTextColor("#e15759"));
+    expect(contrastTextColor("#abc")).toBe("#0b1220");
+    expect(contrastTextColor("hsl(0, 0%, 100%)")).toBe("#0b1220");
+    expect(contrastTextColor("not-a-color")).toBe("#fff");
+    // Every default palette member must clear WCAG AA with its chosen text.
+    for (const color of HK_TREEMAP_DEFAULT_COLORS) {
+      expect(["#fff", "#0b1220"]).toContain(contrastTextColor(color));
+    }
+  });
+
+  it("paints group title bands with the same colour the title contrast describes", () => {
+    const option = createHkTreemapOption(buildHkTreemapLayout([
+      {
+        id: "group",
+        label: "Group",
+        value: 0,
+        color: "#76b7b2",
+        children: [{ id: "leaf", label: "Leaf", value: 1 }],
+      },
+    ])) as any;
+    const series = option.series[0];
+    const group = series.data[0];
+
+    expect(series.animation).toBe(false);
+    expect(series.levels[0].upperLabel.show).toBe(false);
+    expect(series.levels[0].itemStyle.borderColor).toBe("transparent");
+    const normalized = "rgb(118 183 178)";
+    expect(group.itemStyle.color).toBe(normalized);
+    expect(group.itemStyle.borderColor).toBe(normalized);
+    expect(group.upperLabel.color).toBe(contrastTextColor(normalized));
+    // A light group title on a mid-tone band would be unreadable.
+    expect(group.upperLabel.color).toBe("#0b1220");
+  });
+
+  it("feeds real values and percentages to leaf, group and tooltip formatters", () => {
+    const option = createHkTreemapOption(buildHkTreemapLayout(NODES), (value) => `${value} units`) as any;
+    const series = option.series[0];
+    const group = series.data[0];
+    const leaf = group.children[0];
+
+    expect(series.nodeClick).toBe(false);
+    expect(series.roam).toBe(false);
+    expect(series.breadcrumb.show).toBe(false);
+    expect(series.label.formatter({ data: leaf })).toBe("Alpha\n2 units · 20%");
+    expect(series.upperLabel.formatter({ data: group })).toBe("Group · 6 units · 60%");
+    expect(option.tooltip.formatter({ data: leaf })).toBe(
+      "<strong>Alpha</strong><br/>2 units · 20%",
+    );
+  });
+
+  it("escapes HTML in tooltip labels and formatted values", () => {
+    const option = createHkTreemapOption(
+      buildHkTreemapLayout([{ id: "html", label: "<unsafe>", value: 1 }]),
+      () => "<b>1</b>",
+    ) as any;
+    const datum = option.series[0].data[0];
+
+    expect(option.tooltip.formatter({ data: datum })).toBe(
+      "<strong>&lt;unsafe&gt;</strong><br/>&lt;b&gt;1&lt;/b&gt; · 100%",
+    );
+  });
+
+  it("builds an accessible leaf-path summary from the same layout", () => {
+    const summary = createHkTreemapSummary(buildHkTreemapLayout(NODES), (value) => `${value}u`);
+    expect(summary).toBe("Group / Alpha: 2u (20%); Group / Beta: 4u (40%); Other: 4u (40%)");
+    expect(formatHkTreemapPercent(0.04)).toBe("<0.1%");
+  });
+});
+
+describe("HkTreemap component lifecycle", () => {
+  it("mounts lazily and renders legend, formatted values and accessible text", async () => {
+    const mounted = mountTreemap({
+      nodes: NODES,
+      ariaLabel: "Resource usage",
+      valueFormatter: (value: number) => `${value} units`,
+    });
+    await waitForChart();
+
+    expect(H.init).toHaveBeenCalledTimes(1);
+    expect(H.use).toHaveBeenCalledTimes(1);
+    expect(H.FakeChart.instances[0]!.options).toHaveLength(1);
+    expect(mounted.container.querySelector<HTMLElement>(".hk-treemap")!.style.height).toBe("320px");
+    expect(mounted.container.querySelectorAll(".hk-treemap__legend-item")).toHaveLength(2);
+    expect(mounted.container.textContent).toContain("6 units");
+
+    const chart = mounted.container.querySelector<HTMLElement>(".hk-treemap__chart")!;
+    expect(chart.getAttribute("role")).toBe("img");
+    expect(chart.getAttribute("aria-label")).toBe("Resource usage");
+    expect(chart.getAttribute("aria-hidden")).toBe("false");
+    const summaryId = chart.getAttribute("aria-describedby")!;
+    expect(mounted.container.querySelector(`#${summaryId}`)!.textContent).toBe(
+      "Group / Alpha: 2 units (20%); Group / Beta: 4 units (40%); Other: 4 units (40%)",
+    );
+  });
+
+  it("calls setOption when data or value formatting changes", async () => {
+    const mounted = mountTreemap();
+    await waitForChart();
+    const chart = H.FakeChart.instances[0]!;
+    expect(chart.options).toHaveLength(1);
+
+    mounted.update({ nodes: [{ id: "new", label: "New", value: 7 }] });
+    await vi.waitFor(() => expect(chart.options).toHaveLength(2));
+    expect(lastOption().series[0].data[0]).toMatchObject({ id: "new", value: 7 });
+
+    mounted.update({ valueFormatter: (value: number) => `${value} updated` });
+    await vi.waitFor(() => expect(chart.options).toHaveLength(3));
+    expect(lastOption().series[0].data[0].hkTreemap.valueText).toBe("7 updated");
+  });
+
+  it("resizes with its container and window, then disconnects and disposes", async () => {
+    const mounted = mountTreemap();
+    await waitForChart();
+    const chart = H.FakeChart.instances[0]!;
+    const observer = FakeResizeObserver.instances[0]!;
+    const chartElement = mounted.container.querySelector(".hk-treemap__chart")!;
+
+    expect(observer.observed).toEqual([chartElement]);
+    observer.callback();
+    window.dispatchEvent(new Event("resize"));
+    expect(chart.resizeCount).toBe(2);
+
+    unmount(mounted);
+    expect(chart.disposed).toBe(true);
+    expect(observer.disconnected).toBe(true);
+    observer.callback();
+    window.dispatchEvent(new Event("resize"));
+    expect(chart.resizeCount).toBe(2);
+  });
+
+  it("shows an honest empty state and clears stale options across updates", async () => {
+    const mounted = mountTreemap({ nodes: [], emptyText: "Nothing visible" });
+    await waitForChart();
+    const chart = H.FakeChart.instances[0]!;
+
+    expect(mounted.container.querySelector(".hk-treemap__empty")!.textContent).toBe("Nothing visible");
+    expect(mounted.container.querySelector(".hk-treemap__legend")).toBeNull();
+    expect(mounted.container.querySelector(".hk-treemap__chart")!.getAttribute("aria-hidden")).toBe("true");
+    expect(chart.clearCount).toBe(1);
+
+    mounted.update({ nodes: NODES });
+    await vi.waitFor(() => expect(chart.options).toHaveLength(1));
+    expect(mounted.container.querySelector(".hk-treemap__empty")).toBeNull();
+
+    mounted.update({ nodes: [] });
+    await vi.waitFor(() => expect(chart.clearCount).toBe(2));
+    expect(mounted.container.querySelector(".hk-treemap__empty")!.textContent).toBe("Nothing visible");
+  });
+
+  it("supports hiding the legend and numeric pixel heights", async () => {
+    const mounted = mountTreemap({ showLegend: false, height: 280 });
+    await waitForChart();
+
+    expect(mounted.container.querySelector(".hk-treemap__legend")).toBeNull();
+    expect(mounted.container.querySelector<HTMLElement>(".hk-treemap")!.style.height).toBe("280px");
+  });
+
+  it("does not init a detached element when async imports finish after unmount", async () => {
+    let releaseImports!: () => void;
+    H.importGate = new Promise<void>((resolve) => {
+      releaseImports = resolve;
+    });
+    const mounted = mountTreemap();
+    await nextTick();
+
+    unmount(mounted);
+    releaseImports();
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(H.init).not.toHaveBeenCalled();
+    expect(H.FakeChart.instances).toHaveLength(0);
+  });
+});

package/src/components/HkTreemap.tsx

@@ -0,0 +1,567 @@
+import {
+  computed,
+  defineComponent,
+  onMounted,
+  onUnmounted,
+  ref,
+  useId,
+  watch,
+  type PropType,
+} from "vue";
+
+// Keep echarts out of the initial bundle. Only the type imports are static;
+// the renderer and the treemap implementation are loaded after mount.
+import type { ECharts, EChartsCoreOption } from "echarts/core";
+
+import "./HkTreemap.scss";
+
+export interface HkTreemapNode {
+  id: string;
+  label: string;
+  value: number;
+  /** Optional opaque sRGB colour: #rgb/#rrggbb/#rrggbbaa, rgb()/rgba() or
+   *  hsl()/hsla(). Canvas cannot resolve CSS custom properties or named
+   *  colours reliably; unsupported/translucent values fall back to the
+   *  inherited palette colour instead of corrupting the next cell. */
+  color?: string;
+  children?: HkTreemapNode[];
+}
+
+export type HkTreemapValueFormatter = (value: number) => string;
+
+/** A sanitized node. `percent` is a 0–100 percentage of all visible leaves. */
+export interface HkTreemapLayoutNode {
+  id: string;
+  label: string;
+  value: number;
+  color: string;
+  percent: number;
+  children?: HkTreemapLayoutNode[];
+}
+
+export interface HkTreemapLayout {
+  nodes: HkTreemapLayoutNode[];
+  total: number;
+}
+
+type RgbaChannels = [number, number, number, number];
+
+function parseHexColor(raw: string): RgbaChannels | null {
+  const value = raw.slice(1);
+  if (![3, 6, 8].includes(value.length) || !/^[0-9a-f]+$/i.test(value)) return null;
+  const expanded = value.length === 3
+    ? value.split("").map((char) => char + char).join("")
+    : value;
+  return [
+    Number.parseInt(expanded.slice(0, 2), 16),
+    Number.parseInt(expanded.slice(2, 4), 16),
+    Number.parseInt(expanded.slice(4, 6), 16),
+    value.length === 8 ? Number.parseInt(expanded.slice(6, 8), 16) / 255 : 1,
+  ];
+}
+
+function numericChannel(raw: string): number | null {
+  if (raw.endsWith("%")) {
+    const percent = Number.parseFloat(raw.slice(0, -1));
+    return Number.isFinite(percent) ? Math.min(255, Math.max(0, (percent / 100) * 255)) : null;
+  }
+  const value = Number.parseFloat(raw);
+  return Number.isFinite(value) ? Math.min(255, Math.max(0, value)) : null;
+}
+
+function hueToRgb(hue: number, saturation: number, lightness: number): [number, number, number] {
+  const chroma = (1 - Math.abs(2 * lightness - 1)) * saturation;
+  const sector = ((hue % 360) + 360) % 360 / 60;
+  const x = chroma * (1 - Math.abs((sector % 2) - 1));
+  const [red, green, blue] = sector < 1
+    ? [chroma, x, 0]
+    : sector < 2
+      ? [x, chroma, 0]
+      : sector < 3
+        ? [0, chroma, x]
+        : sector < 4
+          ? [0, x, chroma]
+          : sector < 5
+            ? [x, 0, chroma]
+            : [chroma, 0, x];
+  const match = lightness - chroma / 2;
+  return [(red + match) * 255, (green + match) * 255, (blue + match) * 255];
+}
+
+function alphaComponent(raw: string | undefined): number | null {
+  if (raw == null || raw === "") return 1;
+  if (raw.endsWith("%")) {
+    const percent = Number.parseFloat(raw.slice(0, -1));
+    return Number.isFinite(percent) ? Math.min(1, Math.max(0, percent / 100)) : null;
+  }
+  const value = Number.parseFloat(raw);
+  return Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : null;
+}
+
+function parseCssColor(raw: string): RgbaChannels | null {
+  const value = raw.trim();
+  if (value.startsWith("#")) return parseHexColor(value);
+  const rgb = /^rgba?\((.*)\)$/i.exec(value);
+  if (rgb) {
+    const parts = rgb[1]!.split(/[\s,/]+/).filter((part) => part && part !== "none");
+    if (parts.length < 3) return null;
+    const channels = parts.slice(0, 3).map(numericChannel);
+    if (channels.some((channel) => channel === null)) return null;
+    const alpha = alphaComponent(parts[3]);
+    if (alpha === null) return null;
+    return [...(channels as [number, number, number]), alpha];
+  }
+  const hsl = /^hsla?\((.*)\)$/i.exec(value);
+  if (hsl) {
+    const parts = hsl[1]!.split(/[\s,/]+/).filter((part) => part && part !== "none");
+    if (parts.length < 3) return null;
+    const hue = Number.parseFloat(parts[0]!);
+    const saturation = Number.parseFloat(parts[1]!);
+    const lightness = Number.parseFloat(parts[2]!);
+    if (![hue, saturation, lightness].every(Number.isFinite)) return null;
+    const alpha = alphaComponent(parts[3]);
+    if (alpha === null) return null;
+    return [
+      ...hueToRgb(
+        hue,
+        Math.min(1, Math.max(0, saturation / 100)),
+        Math.min(1, Math.max(0, lightness / 100)),
+      ),
+      alpha,
+    ];
+  }
+  return null;
+}
+
+function resolveOpaqueColor(raw: string, fallback: string): string {
+  const channels = parseCssColor(raw);
+  if (!channels || channels[3] < 0.999) return fallback;
+  return `rgb(${Math.round(channels[0])} ${Math.round(channels[1])} ${Math.round(channels[2])})`;
+}
+
+/** Pick the higher-contrast label colour for an opaque CSS background. */
+export function contrastTextColor(background: string): string {
+  const channels = parseCssColor(background);
+  if (!channels || channels[3] < 0.999) return "#fff";
+  // sRGB relative luminance, with the standard gamma expansion. The two
+  // candidate text colours (#fff / #0b1220) cross at luminance ~= 0.193.
+  const linear = (channel: number) => {
+    const value = channel / 255;
+    return value <= 0.03928 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+  };
+  const luminance =
+    0.2126 * linear(channels[0]) +
+    0.7152 * linear(channels[1]) +
+    0.0722 * linear(channels[2]);
+  return luminance > 0.193 ? "#0b1220" : "#fff";
+}
+
+export const HK_TREEMAP_DEFAULT_COLORS = [
+  "#4e79a7",
+  "#f28e2b",
+  "#e15759",
+  "#76b7b2",
+  "#59a14f",
+  "#edc948",
+  "#b07aa1",
+  "#ff9da7",
+  "#9c755f",
+  "#bab0ab",
+] as const;
+
+const defaultValueFormatter: HkTreemapValueFormatter = (value) => String(value);
+
+interface NumericLayoutNode {
+  id: string;
+  label: string;
+  value: number;
+  color: string;
+  children?: NumericLayoutNode[];
+}
+
+function isVisibleValue(value: number): boolean {
+  return Number.isFinite(value) && value > 0;
+}
+
+/**
+ * A node with a non-empty children array is a group: its own value is never
+ * trusted, and it survives only when at least one valid descendant leaf does.
+ * An empty children array is equivalent to no children and therefore a leaf.
+ */
+function normalizeNode(
+  node: HkTreemapNode,
+  inheritedColor: string,
+): NumericLayoutNode | null {
+  const color = node.color
+    ? resolveOpaqueColor(node.color, inheritedColor)
+    : inheritedColor;
+  if (node.children && node.children.length > 0) {
+    const children = node.children
+      .map((child) => normalizeNode(child, color))
+      .filter((child): child is NumericLayoutNode => child !== null);
+    if (children.length === 0) return null;
+
+    const value = children.reduce((sum, child) => sum + child.value, 0);
+    // Finite inputs can still overflow when summed. Such a group cannot be
+    // represented truthfully, so omit it rather than emitting Infinity/NaN.
+    if (!isVisibleValue(value)) return null;
+    return { id: node.id, label: node.label, value, color, children };
+  }
+
+  if (!isVisibleValue(node.value)) return null;
+  return { id: node.id, label: node.label, value: node.value, color };
+}
+
+function visitLeaves(nodes: NumericLayoutNode[], visit: (leaf: NumericLayoutNode) => void): void {
+  for (const node of nodes) {
+    if (node.children) visitLeaves(node.children, visit);
+    else visit(node);
+  }
+}
+
+/**
+ * Converts caller input into the only numeric model used by the chart, legend,
+ * tooltip and accessible summary. Invalid leaves are removed before any sums
+ * or percentages are calculated; caller-provided parent values are ignored.
+ */
+export function buildHkTreemapLayout(nodes: readonly HkTreemapNode[]): HkTreemapLayout {
+  const normalized = nodes
+    .map((node, index) =>
+      normalizeNode(
+        node,
+        HK_TREEMAP_DEFAULT_COLORS[index % HK_TREEMAP_DEFAULT_COLORS.length]!,
+      ),
+    )
+    .filter((node): node is NumericLayoutNode => node !== null);
+
+  let total = 0;
+  visitLeaves(normalized, (leaf) => {
+    total += leaf.value;
+  });
+  if (!isVisibleValue(total)) return { nodes: [], total: 0 };
+
+  function addPercentages(node: NumericLayoutNode): HkTreemapLayoutNode {
+    return {
+      ...node,
+      percent: (node.value / total) * 100,
+      children: node.children?.map(addPercentages),
+    };
+  }
+
+  return { nodes: normalized.map(addPercentages), total };
+}
+
+/** One decimal place, trimmed for whole numbers, without rounding tiny shares to zero. */
+export function formatHkTreemapPercent(percent: number): string {
+  if (!Number.isFinite(percent) || percent <= 0) return "0%";
+  if (percent < 0.1) return "<0.1%";
+  return `${Number(percent.toFixed(1))}%`;
+}
+
+interface HkTreemapChartMeta {
+  label: string;
+  valueText: string;
+  percentText: string;
+}
+
+interface HkTreemapChartDatum {
+  id: string;
+  name: string;
+  value: number;
+  itemStyle: { color: string; borderColor?: string };
+  label: { color: string; textBorderColor: string };
+  upperLabel: { color: string; textBorderColor: string };
+  hkTreemap: HkTreemapChartMeta;
+  children?: HkTreemapChartDatum[];
+}
+
+function toChartData(
+  node: HkTreemapLayoutNode,
+  formatValue: HkTreemapValueFormatter,
+): HkTreemapChartDatum {
+  const labelColor = contrastTextColor(node.color);
+  const textBorderColor = labelColor === "#0b1220"
+    ? "rgba(255, 255, 255, 0.6)"
+    : "rgba(0, 0, 0, 0.45)";
+  const isGroup = Boolean(node.children?.length);
+  return {
+    id: node.id,
+    name: node.label,
+    value: node.value,
+    // ECharts paints a group's upperLabel band with the group's BORDER
+    // colour. Keep that band the group's own colour so the contrast choice
+    // above describes the pixels under the title (the series default is
+    // white, which would produce white-on-white titles).
+    itemStyle: isGroup
+      ? { color: node.color, borderColor: node.color }
+      : { color: node.color },
+    label: { color: labelColor, textBorderColor },
+    upperLabel: { color: labelColor, textBorderColor },
+    hkTreemap: {
+      label: node.label,
+      valueText: formatValue(node.value),
+      percentText: formatHkTreemapPercent(node.percent),
+    },
+    children: node.children?.map((child) => toChartData(child, formatValue)),
+  };
+}
+
+function chartMeta(params: unknown): HkTreemapChartMeta | null {
+  const data = (params as { data?: Partial<HkTreemapChartDatum> } | null)?.data;
+  return data?.hkTreemap ?? null;
+}
+
+function leafLabelFormatter(params: unknown): string {
+  const meta = chartMeta(params);
+  return meta ? `${meta.label}\n${meta.valueText} · ${meta.percentText}` : "";
+}
+
+function groupLabelFormatter(params: unknown): string {
+  const meta = chartMeta(params);
+  return meta ? `${meta.label} · ${meta.valueText} · ${meta.percentText}` : "";
+}
+
+function escapeHtml(value: string): string {
+  return value.replace(/[&<>"']/g, (char) => {
+    switch (char) {
+      case "&": return "&amp;";
+      case "<": return "&lt;";
+      case ">": return "&gt;";
+      case '"': return "&quot;";
+      default: return "&#39;";
+    }
+  });
+}
+
+function tooltipFormatter(params: unknown): string {
+  const meta = chartMeta(params);
+  if (!meta) return "";
+  return `<strong>${escapeHtml(meta.label)}</strong><br/>${escapeHtml(meta.valueText)} · ${escapeHtml(meta.percentText)}`;
+}
+
+/** Pure echarts option construction, exported for focused contract tests. */
+export function createHkTreemapOption(
+  layout: HkTreemapLayout,
+  formatValue: HkTreemapValueFormatter = defaultValueFormatter,
+): EChartsCoreOption {
+  return {
+    animation: false,
+    tooltip: {
+      trigger: "item",
+      confine: true,
+      formatter: tooltipFormatter,
+    },
+    series: [
+      {
+        type: "treemap",
+        // TreemapView reads SERIES animation, not the top-level option.
+        animation: false,
+        data: layout.nodes.map((node) => toChartData(node, formatValue)),
+        left: 0,
+        right: 0,
+        top: 0,
+        bottom: 0,
+        width: "100%",
+        height: "100%",
+        roam: false,
+        nodeClick: false,
+        // ECharts defaults to hiding cells below 10px²; our legend and
+        // accessible summary describe every leaf, so the chart must too.
+        visibleMin: 0,
+        breadcrumb: { show: false },
+        label: {
+          show: true,
+          formatter: leafLabelFormatter,
+          color: "#fff",
+          fontSize: 12,
+          lineHeight: 17,
+          overflow: "truncate",
+          textBorderColor: "rgba(0, 0, 0, 0.35)",
+          textBorderWidth: 2,
+        },
+        upperLabel: {
+          show: true,
+          formatter: groupLabelFormatter,
+          color: "#fff",
+          fontSize: 12,
+          fontWeight: 600,
+          height: 24,
+          overflow: "truncate",
+          textBorderColor: "rgba(0, 0, 0, 0.35)",
+          textBorderWidth: 2,
+        },
+        itemStyle: {
+          borderColor: "#fff",
+          borderWidth: 1,
+          gapWidth: 1,
+        },
+        levels: [
+          {
+            // The virtual root is not a visible group: without this, ECharts
+            // reserves a 24px white upperLabel band above the whole chart.
+            upperLabel: { show: false },
+            itemStyle: { borderWidth: 0, gapWidth: 0, borderColor: "transparent" },
+          },
+          { itemStyle: { borderWidth: 2, gapWidth: 3 } },
+          { itemStyle: { borderWidth: 1, gapWidth: 2 } },
+          { itemStyle: { borderWidth: 1, gapWidth: 1 } },
+        ],
+      },
+    ],
+  };
+}
+
+/** Flattened leaf-path text exposes nested data that a canvas cannot announce. */
+export function createHkTreemapSummary(
+  layout: HkTreemapLayout,
+  formatValue: HkTreemapValueFormatter = defaultValueFormatter,
+): string {
+  const entries: string[] = [];
+  function walk(nodes: HkTreemapLayoutNode[], parents: string[]): void {
+    for (const node of nodes) {
+      const path = [...parents, node.label];
+      if (node.children) walk(node.children, path);
+      else {
+        entries.push(
+          `${path.join(" / ")}: ${formatValue(node.value)} (${formatHkTreemapPercent(node.percent)})`,
+        );
+      }
+    }
+  }
+  walk(layout.nodes, []);
+  return entries.join("; ");
+}
+
+export default defineComponent({
+  name: "HkTreemap",
+  props: {
+    nodes: { type: Array as PropType<HkTreemapNode[]>, default: () => [] },
+    height: { type: [String, Number], default: "320px" },
+    showLegend: { type: Boolean, default: true },
+    valueFormatter: { type: Function as PropType<HkTreemapValueFormatter>, default: undefined },
+    emptyText: { type: String, default: "No data" },
+    ariaLabel: { type: String, default: "Treemap" },
+  },
+  setup(props) {
+    const chartEl = ref<HTMLElement>();
+    // useId is SSR-safe and unique per component instance; a module counter
+    // drifts between server and client hydration.
+    const summaryId = `hk-treemap-summary-${useId()}`;
+    let chart: ECharts | null = null;
+    let resizeCleanup: (() => void) | undefined;
+    let unmounted = false;
+
+    const layout = computed(() => buildHkTreemapLayout(props.nodes));
+    const hasData = computed(() => layout.value.nodes.length > 0);
+    const formatValue = (value: number) =>
+      (props.valueFormatter ?? defaultValueFormatter)(value);
+    const summary = computed(() => createHkTreemapSummary(layout.value, formatValue));
+    const rootStyle = computed(() => ({
+      width: "100%",
+      height: typeof props.height === "number" ? `${props.height}px` : props.height,
+    }));
+
+    function renderChart() {
+      if (!chart) return;
+      if (!hasData.value) {
+        // Data can become empty during a streaming update. Remove the previous
+        // option so a later reveal can never expose stale rectangles.
+        chart.clear();
+        return;
+      }
+      chart.setOption(createHkTreemapOption(layout.value, formatValue), { notMerge: true });
+    }
+
+    function onResize() {
+      chart?.resize();
+    }
+
+    onMounted(async () => {
+      const el = chartEl.value;
+      if (!el) return;
+
+      const [echarts, { TreemapChart }, { TooltipComponent }, { CanvasRenderer }] =
+        await Promise.all([
+          import("echarts/core"),
+          import("echarts/charts"),
+          import("echarts/components"),
+          import("echarts/renderers"),
+        ]);
+
+      // Dynamic imports may resolve after the host has unmounted. Never init
+      // against a detached (or subsequently replaced) element.
+      if (unmounted || chartEl.value !== el) return;
+
+      echarts.use([TreemapChart, TooltipComponent, CanvasRenderer]);
+      chart = echarts.init(el);
+      renderChart();
+
+      window.addEventListener("resize", onResize);
+      let observer: ResizeObserver | undefined;
+      if (typeof ResizeObserver !== "undefined") {
+        observer = new ResizeObserver(onResize);
+        observer.observe(el);
+      }
+      resizeCleanup = () => {
+        window.removeEventListener("resize", onResize);
+        observer?.disconnect();
+      };
+    });
+
+    onUnmounted(() => {
+      unmounted = true;
+      resizeCleanup?.();
+      resizeCleanup = undefined;
+      chart?.dispose();
+      chart = null;
+    });
+
+    watch([layout, () => props.valueFormatter], renderChart);
+
+    return () => (
+      <div class="hk-treemap" style={rootStyle.value}>
+        {props.showLegend && hasData.value && (
+          <ul class="hk-treemap__legend">
+            {layout.value.nodes.map((node) => {
+              const valueText = formatValue(node.value);
+              const percentText = formatHkTreemapPercent(node.percent);
+              return (
+                <li
+                  class="hk-treemap__legend-item"
+                  key={node.id}
+                  title={`${node.label}: ${valueText} (${percentText})`}
+                >
+                  <span
+                    class="hk-treemap__legend-swatch"
+                    style={{ backgroundColor: node.color }}
+                    aria-hidden="true"
+                  />
+                  <span class="hk-treemap__legend-label">{node.label}</span>
+                  <span class="hk-treemap__legend-value">{valueText}</span>
+                  <span class="hk-treemap__legend-percent">{percentText}</span>
+                </li>
+              );
+            })}
+          </ul>
+        )}
+        <div class="hk-treemap__body">
+          <div
+            ref={chartEl}
+            class="hk-treemap__chart"
+            role="img"
+            aria-label={props.ariaLabel}
+            aria-describedby={hasData.value ? summaryId : undefined}
+            aria-hidden={!hasData.value}
+            style={{ visibility: hasData.value ? "visible" : "hidden" }}
+          />
+          {!hasData.value && <div class="hk-treemap__empty">{props.emptyText}</div>}
+        </div>
+        {hasData.value && (
+          <p id={summaryId} class="hk-treemap__a11y-summary">
+            {summary.value}
+          </p>
+        )}
+      </div>
+    );
+  },
+});

package/src/index.ts

@@ -150,6 +150,7 @@ export { default as HMinimap } from "./components/HkMinimap";
 
 // Charts
 export { default as HTrendChart } from "./components/HkTrendChart";
+export { default as HTreemap } from "./components/HkTreemap";
 
 export { default as HErrorBoundary } from "./components/HkErrorBoundary";
 export {
@@ -230,6 +231,7 @@ export {
   type LightingRigOptions,
 } from "./scene3d/lighting";
 export { type TrendPen, type TrendPoint, type AlarmThresholds } from "./components/HkTrendChart";
+export { type HkTreemapNode, type HkTreemapValueFormatter } from "./components/HkTreemap";
 
 // ── Theme decor (theme-provided decorative widgets, host-placed) ──────────
 export { default as HkThemeDecor, type HkThemeDecorSize } from "./components/HkThemeDecor";
@@ -725,6 +727,7 @@ export {
 } from "./components/HkBoard3D";
 export { default as HkMinimap3D } from "./components/HkMinimap3D";
 export { default as HkTrendChart } from "./components/HkTrendChart";
+export { default as HkTreemap } from "./components/HkTreemap";
 export { default as HkErrorBoundary } from "./components/HkErrorBoundary";
 export { default as HkDraggableList } from "./components/HkDraggableList";
 export { default as HkDraggableGrid } from "./components/HkDraggableGrid";