@celestia-island/hikari 0.40.34 → 0.40.35

package/package.json

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

package/src/components/HkButton.test.tsx

@@ -0,0 +1,159 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h } from "vue";
+
+import HkButton from "./HkButton";
+
+/**
+ * HkButton contract tests:
+ * - variant / size / block / loading class mapping on the root <button>
+ * - the native disabled attribute is the click guard (disabled OR loading)
+ * - loading renders the spinner INSTEAD of the icon and flags aria-busy
+ * - default-slot text, aria-label (icon-only usage), suffix, shortcut kbd
+ * - attr fallthrough: inheritAttrs is false, the component MUST spread
+ *   $attrs itself (type / data-* / class merging)
+ *
+ * House style: raw createApp mounts on a shared container list torn down
+ * after each case; DOM assertions via document queries.
+ */
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mount(node: ReturnType<typeof h>) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render: () => node });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+function button(c: HTMLElement): HTMLButtonElement {
+  return c.querySelector("button")!;
+}
+
+afterEach(() => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+});
+
+describe("HkButton class mapping", () => {
+  it("renders the default primary/md classes with default-slot text and type=button", () => {
+    const c = mount(h(HkButton, () => "Deploy"));
+    const btn = button(c);
+    expect(btn).not.toBeNull();
+    expect(btn.className).toBe("hk-btn hk-btn-primary hk-btn-md");
+    expect(btn.getAttribute("type")).toBe("button");
+    expect(btn.textContent).toContain("Deploy");
+  });
+
+  it("maps variant and size props to modifier classes", () => {
+    const c = mount(h(HkButton, { variant: "danger", size: "sm" }, () => "Delete"));
+    const cls = button(c).className;
+    expect(cls).toContain("hk-btn-danger");
+    expect(cls).toContain("hk-btn-sm");
+    expect(cls).not.toContain("hk-btn-primary");
+    expect(cls).not.toContain("hk-btn-md");
+  });
+
+  it("adds the block modifier only when block is set", () => {
+    const blocked = mount(h(HkButton, { block: true }, () => "wide"));
+    expect(button(blocked).className).toContain("hk-btn-block");
+    const plain = mount(h(HkButton, () => "narrow"));
+    expect(button(plain).className).not.toContain("hk-btn-block");
+  });
+});
+
+describe("HkButton click guard", () => {
+  it("emits the declared click event on activation", async () => {
+    let clicks = 0;
+    const c = mount(h(HkButton, { onClick: () => { clicks += 1; } }, () => "go"));
+    button(c).click();
+    await Promise.resolve();
+    expect(clicks).toBe(1);
+  });
+
+  it("suppresses the click emit while disabled", async () => {
+    let clicks = 0;
+    const c = mount(h(HkButton, { disabled: true, onClick: () => { clicks += 1; } }, () => "no"));
+    // The guard is the NATIVE disabled attribute: the platform (and
+    // happy-dom) fires no click listeners on a disabled button.
+    expect(button(c).disabled).toBe(true);
+    button(c).click();
+    await Promise.resolve();
+    expect(clicks).toBe(0);
+  });
+
+  it("disables the button and suppresses clicks while loading", async () => {
+    let clicks = 0;
+    const c = mount(h(HkButton, { loading: true, onClick: () => { clicks += 1; } }, () => "busy"));
+    const btn = button(c);
+    expect(btn.disabled).toBe(true); // loading implies disabled
+    expect(btn.className).toContain("hk-btn-loading");
+    expect(btn.getAttribute("aria-busy")).toBe("true");
+    btn.click();
+    await Promise.resolve();
+    expect(clicks).toBe(0);
+  });
+
+  it("clears the loading state back to a clickable button (aria-busy drops off)", () => {
+    const busy = mount(h(HkButton, { loading: true }, () => "x"));
+    expect(busy.querySelector(".hk-spinner")).not.toBeNull();
+    const idle = mount(h(HkButton, () => "x"));
+    const btn = button(idle);
+    expect(idle.querySelector(".hk-spinner")).toBeNull();
+    expect(btn.disabled).toBe(false);
+    expect(btn.getAttribute("aria-busy")).toBeNull();
+    expect(btn.className).not.toContain("hk-btn-loading");
+  });
+});
+
+describe("HkButton content slots", () => {
+  it("renders the leading icon only when NOT loading", () => {
+    const idle = mount(h(HkButton, { icon: "close" }, () => "x"));
+    expect(idle.querySelector(".hk-btn-icon")).not.toBeNull();
+    expect(idle.querySelector(".hk-spinner")).toBeNull();
+
+    // Loading swaps the icon out for the spinner — never both.
+    const busy = mount(h(HkButton, { icon: "close", loading: true }, () => "x"));
+    expect(busy.querySelector(".hk-btn-icon")).toBeNull();
+    expect(busy.querySelector(".hk-spinner")).not.toBeNull();
+  });
+
+  it("renders the suffix icon slot", () => {
+    const c = mount(h(HkButton, { suffix: "close" }, () => "Open"));
+    expect(c.querySelector(".hk-btn-suffix")).not.toBeNull();
+  });
+
+  it("renders the shortcut kbd and its marker class", () => {
+    const c = mount(h(HkButton, { shortcut: "Ctrl+Enter" }, () => "Send"));
+    const btn = button(c);
+    expect(btn.className).toContain("hk-btn-has-shortcut");
+    const kbd = c.querySelector("kbd.hk-kbd")!;
+    expect(kbd).not.toBeNull();
+    expect(kbd.textContent).toContain("Ctrl");
+    expect(kbd.textContent).toContain("Enter");
+  });
+
+  it("exposes aria-label for icon-only usage", () => {
+    const c = mount(h(HkButton, { icon: "close", ariaLabel: "Close inspector" }));
+    expect(button(c).getAttribute("aria-label")).toBe("Close inspector");
+  });
+});
+
+describe("HkButton attr fallthrough (inheritAttrs: false)", () => {
+  it("spreads extra attrs and honors an explicit type", () => {
+    const c = mount(h(HkButton, { type: "submit", "data-test": "probe" }, () => "Save"));
+    const btn = button(c);
+    expect(btn.getAttribute("type")).toBe("submit");
+    expect(btn.getAttribute("data-test")).toBe("probe");
+  });
+
+  it("merges a fallthrough class onto its own class list", () => {
+    const c = mount(h(HkButton, { class: "extra-class" }, () => "x"));
+    const cls = button(c).className;
+    expect(cls).toContain("hk-btn");
+    expect(cls).toContain("extra-class");
+  });
+});

package/src/components/HkCheckbox.test.tsx

@@ -0,0 +1,202 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import HkCheckbox from "./HkCheckbox";
+
+/**
+ * HkCheckbox contract tests:
+ * - tri-state model wiring: false → unlit box, true → check icon (or dot
+ *   in radio mode), null → indeterminate dash (checkbox mode only)
+ * - the label shell is a real <label> wrapping the native input, so
+ *   clicking the TEXT forwards to the input and toggles (label association)
+ * - change events carry the input's NEW checked value; disabled drops them
+ * - the data-animating pulse is set on change and cleared by the 300ms
+ *   cron one-shot
+ *
+ * House style: raw createApp mounts on a shared container list torn down
+ * after each case; DOM assertions via document queries.
+ */
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mount(node: ReturnType<typeof h>) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render: () => node });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+/** v-model harness: mirrors consumer usage, records every emitted value. */
+function mountVModel(initial: boolean | null, props: Record<string, unknown> = {}) {
+  const model = ref<boolean | null>(initial);
+  const emitted: Array<boolean> = [];
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp(defineComponent({
+    setup: () => () =>
+      h(HkCheckbox, {
+        ...props,
+        modelValue: model.value as boolean,
+        "onUpdate:modelValue": (v: boolean) => {
+          model.value = v;
+          emitted.push(v);
+        },
+      }),
+  }));
+  app.mount(container);
+  mounts.push({ app, container });
+  const input = () => container.querySelector<HTMLInputElement>("input")!;
+  const box = () => container.querySelector<HTMLElement>(".hk-checkbox-box")!;
+  const root = () => container.querySelector<HTMLElement>("label")!;
+  return { container, model, emitted, input, box, root };
+}
+
+afterEach(() => {
+  vi.useRealTimers();
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+});
+
+describe("HkCheckbox model states", () => {
+  it("renders an unlit box and an unchecked native checkbox by default", () => {
+    const c = mount(h(HkCheckbox));
+    const root = c.querySelector<HTMLElement>("label")!;
+    expect(root.className).toBe("hk-checkbox hk-checkbox-md");
+    expect(root.getAttribute("data-type")).toBe("checkbox");
+    const input = c.querySelector<HTMLInputElement>("input")!;
+    expect(input.type).toBe("checkbox");
+    expect(input.checked).toBe(false);
+    const box = c.querySelector<HTMLElement>(".hk-checkbox-box")!;
+    expect(box.hasAttribute("data-checked")).toBe(false);
+    expect(box.hasAttribute("data-indeterminate")).toBe(false);
+    expect(c.querySelector(".hk-checkbox-icon")).toBeNull();
+    expect(c.querySelector(".hk-checkbox-indeterminate")).toBeNull();
+  });
+
+  it("maps modelValue=true to the checked box with the check icon", () => {
+    const c = mount(h(HkCheckbox, { modelValue: true }));
+    const box = c.querySelector<HTMLElement>(".hk-checkbox-box")!;
+    expect(box.getAttribute("data-checked")).toBe("");
+    expect(c.querySelector<HTMLInputElement>("input")!.checked).toBe(true);
+    // The glyph is the lucide Check svg itself (lucide puts the class on
+    // its root <svg>), not the radio dot.
+    expect(c.querySelector("svg.hk-checkbox-icon")).not.toBeNull();
+    expect(c.querySelector(".hk-checkbox-dot")).toBeNull();
+  });
+
+  it("maps modelValue=null to the indeterminate dash without checking the input", () => {
+    const c = mount(h(HkCheckbox, { modelValue: null as unknown as boolean }));
+    const box = c.querySelector<HTMLElement>(".hk-checkbox-box")!;
+    expect(box.getAttribute("data-indeterminate")).toBe("");
+    expect(box.hasAttribute("data-checked")).toBe(false);
+    // null is NOT true: the native input stays unchecked.
+    expect(c.querySelector<HTMLInputElement>("input")!.checked).toBe(false);
+    expect(c.querySelector(".hk-checkbox-indeterminate")).not.toBeNull();
+    expect(c.querySelector(".hk-checkbox-icon")).toBeNull();
+  });
+
+  it("radio mode swaps the check icon for the dot and drops the indeterminate dash", () => {
+    const checked = mount(h(HkCheckbox, { modelValue: true, type: "radio" }));
+    expect(checked.querySelector("label")!.getAttribute("data-type")).toBe("radio");
+    expect(checked.querySelector<HTMLInputElement>("input")!.type).toBe("radio");
+    expect(checked.querySelector(".hk-checkbox-dot")).not.toBeNull();
+    expect(checked.querySelector(".hk-checkbox-icon")).toBeNull();
+
+    // null in radio mode: no dash — indeterminate is checkbox-only.
+    const unset = mount(h(HkCheckbox, { modelValue: null as unknown as boolean, type: "radio" }));
+    expect(unset.querySelector(".hk-checkbox-indeterminate")).toBeNull();
+    expect(unset.querySelector(".hk-checkbox-dot")).toBeNull();
+  });
+
+  it("maps the size prop to the shell modifier", () => {
+    const c = mount(h(HkCheckbox, { size: "sm" }));
+    expect(c.querySelector("label")!.className).toContain("hk-checkbox-sm");
+  });
+});
+
+describe("HkCheckbox label", () => {
+  it("renders the label prop through the HkLabel shell", () => {
+    const c = mount(h(HkCheckbox, { label: "Remember login" }));
+    const label = c.querySelector<HTMLElement>(".hk-label")!;
+    expect(label).not.toBeNull();
+    expect(label.textContent).toBe("Remember login");
+  });
+
+  it("prefers default-slot content over the label prop", () => {
+    const c = mount(
+      h(HkCheckbox, { label: "plain" }, () => ["rich ", h("b", "text")]),
+    );
+    expect(c.querySelector(".hk-label")!.textContent).toBe("rich text");
+  });
+
+  it("renders no label shell without label prop or slot", () => {
+    const c = mount(h(HkCheckbox));
+    expect(c.querySelector(".hk-label")).toBeNull();
+  });
+});
+
+describe("HkCheckbox change wiring", () => {
+  it("round-trips v-model through native input activation", async () => {
+    const t = mountVModel(false);
+    t.input().click();
+    await nextTick();
+    expect(t.emitted).toEqual([true]);
+    expect(t.model.value).toBe(true);
+    expect(t.input().checked).toBe(true);
+    expect(t.box().getAttribute("data-checked")).toBe("");
+
+    t.input().click();
+    await nextTick();
+    expect(t.emitted).toEqual([true, false]);
+    expect(t.box().hasAttribute("data-checked")).toBe(false);
+  });
+
+  it("toggles through the label text — the shell is a real <label>", async () => {
+    const t = mountVModel(false, { label: "Remember login" });
+    // Clicking the TEXT (not the input): the platform forwards the click
+    // to the first labelable descendant — the checkbox input — which
+    // toggles and fires the change the component listens to.
+    (t.container.querySelector(".hk-label") as HTMLElement).click();
+    await nextTick();
+    expect(t.emitted).toEqual([true]);
+    expect(t.input().checked).toBe(true);
+  });
+
+  it("emits the post-click indeterminate resolution as a plain boolean", async () => {
+    // null (indeterminate) + click → the input lands checked → emits true.
+    const t = mountVModel(null);
+    t.input().click();
+    await nextTick();
+    expect(t.emitted).toEqual([true]);
+    expect(t.box().getAttribute("data-checked")).toBe("");
+    expect(t.box().hasAttribute("data-indeterminate")).toBe(false);
+  });
+
+  it("pulses data-animating on change and clears it after the 300ms cron", async () => {
+    vi.useFakeTimers();
+    const t = mountVModel(false);
+    t.input().click();
+    await nextTick();
+    expect(t.root().getAttribute("data-animating")).toBe("");
+
+    vi.advanceTimersByTime(300);
+    await nextTick();
+    expect(t.root().hasAttribute("data-animating")).toBe(false);
+  });
+
+  it("drops change events entirely while disabled", async () => {
+    const t = mountVModel(false, { disabled: true });
+    expect(t.input().disabled).toBe(true);
+    expect(t.root().getAttribute("data-disabled")).toBe("");
+    // The platform fires no activation on a disabled input.
+    t.input().click();
+    t.container.querySelector<HTMLElement>(".hk-checkbox-box")!.click();
+    await nextTick();
+    expect(t.emitted).toEqual([]);
+    expect(t.input().checked).toBe(false);
+  });
+});

package/src/components/HkRadio.test.tsx

@@ -0,0 +1,206 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import HkRadio, { type HkRadioOption } from "./HkRadio";
+
+/**
+ * HkRadio contract tests:
+ * - option selection semantics: the model value matches option VALUES
+ *   (strict, type-preserving — a numeric option emits a number), and the
+ *   checked markers (box data-checked, dot, native radio checked) follow
+ *   the matching option only
+ * - direction / size group modifiers
+ * - each option is a real <label> wrapping its native radio input, so
+ *   clicking an option's TEXT selects it; re-activating the already
+ *   selected option fires no platform change (and thus no emit)
+ * - disabled: whole group or per option; disabled inputs swallow clicks
+ *
+ * The component wires no custom keyboard handlers (no roving tabindex /
+ * arrow-key code exists) — keyboard behavior is whatever the native
+ * inputs provide, so no keyboard case is asserted here.
+ *
+ * House style: raw createApp mounts on a shared container list torn
+ * down after each case; DOM assertions via document queries.
+ */
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mount(node: ReturnType<typeof h>) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render: () => node });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+const OPTS = [
+  { value: "a", label: "Alpha" },
+  { value: "b", label: "Beta" },
+];
+
+const NUM_OPTS = [
+  { value: 1, label: "One" },
+  { value: 2, label: "Two" },
+];
+
+/** v-model harness: mirrors consumer usage, records every emitted value. */
+function mountVModel(initial: string | number | null, props: Record<string, unknown> = {}) {
+  const model = ref<string | number | null>(initial);
+  const emitted: Array<string | number> = [];
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp(defineComponent({
+    setup: () => () =>
+      h(HkRadio, {
+        ...props,
+        modelValue: model.value as string | number,
+        "onUpdate:modelValue": (v: string | number) => {
+          model.value = v;
+          emitted.push(v);
+        },
+      } as never),
+  }));
+  app.mount(container);
+  mounts.push({ app, container });
+  const group = () => container.querySelector<HTMLElement>(".hk-radio-group")!;
+  const items = () => Array.from(container.querySelectorAll<HTMLElement>("label.hk-radio"));
+  const inputs = () => Array.from(container.querySelectorAll<HTMLInputElement>("input"));
+  return { container, model, emitted, group, items, inputs };
+}
+
+afterEach(() => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+});
+
+describe("HkRadio group shell", () => {
+  it("renders the horizontal/md group by default with one option per label", () => {
+    const c = mount(h(HkRadio, { options: OPTS }));
+    const group = c.querySelector<HTMLElement>(".hk-radio-group")!;
+    expect(group).not.toBeNull();
+    expect(group.className).toBe("hk-radio-group hk-radio-group-horizontal hk-radio-group-md");
+    const items = c.querySelectorAll("label.hk-radio");
+    expect(items.length).toBe(2);
+    // Option labels render through the HkLabel shell.
+    const labels = Array.from(c.querySelectorAll<HTMLElement>(".hk-label"));
+    expect(labels.map((l) => l.textContent)).toEqual(["Alpha", "Beta"]);
+    const inputs = c.querySelectorAll("input");
+    expect(inputs.length).toBe(2);
+    expect(Array.from(inputs).every((i) => i.type === "radio")).toBe(true);
+  });
+
+  it("maps direction and size props to group modifiers", () => {
+    const c = mount(h(HkRadio, { options: OPTS, direction: "vertical", size: "lg" }));
+    const cls = c.querySelector(".hk-radio-group")!.className;
+    expect(cls).toContain("hk-radio-group-vertical");
+    expect(cls).toContain("hk-radio-group-lg");
+    expect(cls).not.toContain("hk-radio-group-horizontal");
+    expect(c.querySelector("label.hk-radio")!.getAttribute("data-size")).toBe("lg");
+  });
+
+  it("lets the label slot override the option text", () => {
+    const c = mount(h(HkRadio, {
+      options: OPTS,
+    }, {
+      label: ({ option }: { option: HkRadioOption }) => h("span", { class: "custom-opt" }, `#${option.label}`),
+    }));
+    const customs = Array.from(c.querySelectorAll<HTMLElement>(".custom-opt"));
+    expect(customs.map((el) => el.textContent)).toEqual(["#Alpha", "#Beta"]);
+  });
+});
+
+describe("HkRadio selection semantics", () => {
+  it("marks only the option whose value matches the model", () => {
+    const c = mount(h(HkRadio, { options: OPTS, modelValue: "b" }));
+    const boxes = Array.from(c.querySelectorAll<HTMLElement>(".hk-radio-box"));
+    expect(boxes[0]!.hasAttribute("data-checked")).toBe(false);
+    expect(boxes[1]!.getAttribute("data-checked")).toBe("");
+    // The dot renders in the selected option only.
+    expect(c.querySelectorAll(".hk-radio-dot").length).toBe(1);
+    expect(boxes[1]!.querySelector(".hk-radio-dot")).not.toBeNull();
+    const inputs = Array.from(c.querySelectorAll<HTMLInputElement>("input"));
+    expect(inputs[0]!.checked).toBe(false);
+    expect(inputs[1]!.checked).toBe(true);
+  });
+
+  it("emits the clicked option's value and moves the selection", async () => {
+    const t = mountVModel("a", { options: OPTS });
+    t.inputs()[1]!.click();
+    await nextTick();
+    expect(t.emitted).toEqual(["b"]);
+    expect(t.model.value).toBe("b");
+    // Selection moved: dot and data-checked follow the new option.
+    const boxes = Array.from(t.container.querySelectorAll<HTMLElement>(".hk-radio-box"));
+    expect(boxes[0]!.hasAttribute("data-checked")).toBe(false);
+    expect(boxes[1]!.getAttribute("data-checked")).toBe("");
+  });
+
+  it("emits the option value type-preserving (number stays number)", async () => {
+    const t = mountVModel(1, { options: NUM_OPTS });
+    t.inputs()[1]!.click();
+    await nextTick();
+    expect(t.emitted).toEqual([2]);
+    expect(t.emitted[0]).toBe(2);
+    expect(typeof t.emitted[0]).toBe("number");
+    // Strict matching against the numeric model still selects.
+    expect(
+      Array.from(t.container.querySelectorAll<HTMLInputElement>("input"))[1]!.checked,
+    ).toBe(true);
+  });
+
+  it("selects through the option label text (native label→input forwarding)", async () => {
+    const t = mountVModel("a", { options: OPTS });
+    (t.container.querySelectorAll(".hk-label")[1] as HTMLElement).click();
+    await nextTick();
+    expect(t.emitted).toEqual(["b"]);
+    expect(t.inputs()[1]!.checked).toBe(true);
+  });
+
+  it("fires no emit when re-activating the already selected option", async () => {
+    const t = mountVModel("a", { options: OPTS });
+    t.inputs()[0]!.click(); // already checked: the platform fires no change
+    await nextTick();
+    expect(t.emitted).toEqual([]);
+    expect(t.model.value).toBe("a");
+  });
+
+  it("leaves every option unselected with a null model", () => {
+    const c = mount(h(HkRadio, { options: OPTS }));
+    expect(c.querySelector(".hk-radio-dot")).toBeNull();
+    expect(Array.from(c.querySelectorAll(".hk-radio-box")).every((b) => !b.hasAttribute("data-checked"))).toBe(true);
+  });
+});
+
+describe("HkRadio disabled", () => {
+  it("disables every option from the group prop", () => {
+    const c = mount(h(HkRadio, { options: OPTS, disabled: true }));
+    const items = Array.from(c.querySelectorAll<HTMLElement>("label.hk-radio"));
+    expect(items.every((el) => el.getAttribute("data-disabled") === "")).toBe(true);
+    expect(Array.from(c.querySelectorAll<HTMLInputElement>("input")).every((i) => i.disabled)).toBe(true);
+  });
+
+  it("disables a single option without touching its siblings", () => {
+    const c = mount(h(HkRadio, {
+      options: [{ value: "a", label: "Alpha" }, { value: "b", label: "Beta", disabled: true }],
+    }));
+    const items = Array.from(c.querySelectorAll<HTMLElement>("label.hk-radio"));
+    expect(items[0]!.hasAttribute("data-disabled")).toBe(false);
+    expect(items[1]!.getAttribute("data-disabled")).toBe("");
+    const inputs = Array.from(c.querySelectorAll<HTMLInputElement>("input"));
+    expect(inputs[0]!.disabled).toBe(false);
+    expect(inputs[1]!.disabled).toBe(true);
+  });
+
+  it("swallows clicks on a disabled option", async () => {
+    const t = mountVModel("a", {
+      options: [{ value: "a", label: "Alpha" }, { value: "b", label: "Beta", disabled: true }],
+    });
+    t.inputs()[1]!.click();
+    await nextTick();
+    expect(t.emitted).toEqual([]);
+    expect(t.model.value).toBe("a");
+  });
+});

package/src/components/HkSwitch.test.tsx

@@ -0,0 +1,174 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import HkSwitch from "./HkSwitch";
+
+/**
+ * HkSwitch contract tests:
+ * - role: the interactive control is a NATIVE <input type="checkbox">
+ *   inside a real <label> — keyboard interaction (Space) rides the
+ *   platform checkbox for free, so the tests exercise the input's
+ *   activation, which is exactly what a Space keypress produces
+ *   (happy-dom does not synthesize Space → click, so dispatching a raw
+ *   KeyboardEvent would assert nothing real)
+ * - model flip on activation emits !modelValue exactly once — the track
+ *   handler calls preventDefault() so the label's native click-forwarding
+ *   cannot produce a second toggle; that dedup is pinned here
+ * - data-checked / data-disabled state markers, size/color modifiers,
+ *   checked/unchecked track contents, label shell
+ *
+ * House style: raw createApp mounts on a shared container list torn down
+ * after each case; DOM assertions via document queries.
+ */
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mount(node: ReturnType<typeof h>) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render: () => node });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+/** v-model harness: mirrors consumer usage, records every emitted value. */
+function mountVModel(initial: boolean, props: Record<string, unknown> = {}) {
+  const model = ref<boolean>(initial);
+  const emitted: Array<boolean> = [];
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp(defineComponent({
+    setup: () => () =>
+      h(HkSwitch, {
+        ...props,
+        modelValue: model.value,
+        "onUpdate:modelValue": (v: boolean) => {
+          model.value = v;
+          emitted.push(v);
+        },
+      }),
+  }));
+  app.mount(container);
+  mounts.push({ app, container });
+  const input = () => container.querySelector<HTMLInputElement>("input")!;
+  const root = () => container.querySelector<HTMLElement>("label")!;
+  const track = () => container.querySelector<HTMLElement>(".hk-switch-track")!;
+  return { container, model, emitted, input, root, track };
+}
+
+afterEach(() => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+});
+
+describe("HkSwitch rendering", () => {
+  it("exposes a native checkbox inside the label with md/primary defaults", () => {
+    const c = mount(h(HkSwitch));
+    const root = c.querySelector<HTMLElement>("label")!;
+    expect(root).not.toBeNull();
+    expect(root.className).toBe("hk-switch hk-switch-md hk-switch-primary");
+    expect(root.hasAttribute("data-checked")).toBe(false);
+    const input = c.querySelector<HTMLInputElement>("input")!;
+    expect(input.type).toBe("checkbox");
+    expect(input.checked).toBe(false);
+    expect(c.querySelector(".hk-switch-track")).not.toBeNull();
+    expect(c.querySelector(".hk-switch-thumb")).not.toBeNull();
+  });
+
+  it("maps modelValue=true to the checked markers on root and input", () => {
+    const c = mount(h(HkSwitch, { modelValue: true }));
+    expect(c.querySelector<HTMLElement>("label")!.getAttribute("data-checked")).toBe("");
+    expect(c.querySelector<HTMLInputElement>("input")!.checked).toBe(true);
+  });
+
+  it("maps size and color props to modifiers", () => {
+    const c = mount(h(HkSwitch, { size: "sm", color: "danger" }));
+    const cls = c.querySelector("label")!.className;
+    expect(cls).toContain("hk-switch-sm");
+    expect(cls).toContain("hk-switch-danger");
+    expect(cls).not.toContain("hk-switch-md");
+    expect(cls).not.toContain("hk-switch-primary");
+  });
+
+  it("swaps the track contents with the checked state", () => {
+    const off = mount(h(HkSwitch, {
+      checkedContent: "on-text",
+      uncheckedContent: "off-text",
+    }));
+    const offContent = off.querySelector<HTMLElement>(".hk-switch-content")!;
+    expect(offContent.className).toContain("hk-switch-content-off");
+    expect(offContent.textContent).toBe("off-text");
+    expect(off.querySelector(".hk-switch-content-on")).toBeNull();
+
+    const on = mount(h(HkSwitch, {
+      modelValue: true,
+      checkedContent: "on-text",
+      uncheckedContent: "off-text",
+    }));
+    const onContent = on.querySelector<HTMLElement>(".hk-switch-content")!;
+    expect(onContent.className).toContain("hk-switch-content-on");
+    expect(onContent.textContent).toBe("on-text");
+    expect(on.querySelector(".hk-switch-content-off")).toBeNull();
+  });
+
+  it("renders the label prop through the HkLabel shell", () => {
+    const c = mount(h(HkSwitch, { label: "Dark mode" }));
+    expect(c.querySelector(".hk-label")!.textContent).toBe("Dark mode");
+  });
+});
+
+describe("HkSwitch toggling", () => {
+  it("flips the model exactly once per track click (preventDefault dedup)", async () => {
+    const t = mountVModel(false);
+    t.track().click();
+    await nextTick();
+    // The track handler toggles AND calls preventDefault so the wrapping
+    // label cannot forward a second click to the native input — without
+    // that guard one tap would emit twice and net-zero the flip.
+    expect(t.emitted).toEqual([true]);
+    expect(t.model.value).toBe(true);
+    expect(t.root().getAttribute("data-checked")).toBe("");
+
+    t.track().click();
+    await nextTick();
+    expect(t.emitted).toEqual([true, false]);
+  });
+
+  it("toggles through the label text via native label→input forwarding", async () => {
+    const t = mountVModel(false, { label: "Dark mode" });
+    (t.container.querySelector(".hk-label") as HTMLElement).click();
+    await nextTick();
+    expect(t.emitted).toEqual([true]);
+    // The forwarded click natively flipped the input's checkedness.
+    expect(t.input().checked).toBe(true);
+  });
+
+  it("flips via the native checkbox activation (the Space-key path)", async () => {
+    const t = mountVModel(true);
+    // A real Space keypress on a focused checkbox produces exactly this
+    // input activation (checked flip + change event); the component owns
+    // no custom key handlers, so the platform control IS the keyboard
+    // story. Enter is not a checkbox activation key — nothing to assert.
+    t.input().click();
+    await nextTick();
+    expect(t.emitted).toEqual([false]);
+    expect(t.input().checked).toBe(false);
+  });
+
+  it("drops every toggle path while disabled", async () => {
+    const t = mountVModel(false, { disabled: true });
+    expect(t.root().getAttribute("data-disabled")).toBe("");
+    expect(t.input().disabled).toBe(true);
+    t.track().click();
+    t.input().click();
+    // Also the label-forwarding path: the platform drops clicks on a
+    // disabled input, so the forwarded activation dies too.
+    (t.container.querySelector(".hk-switch-thumb") as HTMLElement).click();
+    await nextTick();
+    expect(t.emitted).toEqual([]);
+    expect(t.model.value).toBe(false);
+  });
+});

package/src/components/HkTooltip.test.tsx

@@ -0,0 +1,226 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, h, nextTick } from "vue";
+
+import HkTooltip from "./HkTooltip";
+import { POPUP_Z_BANDS, POPUP_Z_STEP, usePopupManager } from "../runtime/usePopupManager";
+
+/**
+ * HkTooltip contract tests:
+ * - popup-manager registration: every mounted tooltip registers ONE
+ *   entry of kind "tooltip" in the real singleton registry (read back
+ *   through usePopupManager), stacked in the tooltip z band (above the
+ *   window/dropdown bands, below toasts), never scroll-locking; the
+ *   entry leaves the registry on unmount
+ * - the band z lands INLINE on the teleported popup element
+ * - show/hide: anchor mouseenter shows after the delay (default 300ms),
+ *   mouseleave hides and cancels a pending show; focusin/focusout ride
+ *   the same path
+ * - anchoring: placement drives the popup class, the wrapper
+ *   data-position and the measured offset style (happy-dom reports a
+ *   zero rect, so the numbers pin the 8px gap and per-placement
+ *   transform)
+ *
+ * House style: raw createApp mounts on a shared container list torn
+ * down after each case; the popup-manager singleton is REAL state, so
+ * afterEach sweeps it the way usePopupManager.test.ts does.
+ */
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mount(props: Record<string, unknown> = {}) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({
+    render: () =>
+      h(HkTooltip, props as never, () => h("span", { class: "anchor-probe" }, "anchor")),
+  });
+  app.mount(container);
+  mounts.push({ app, container });
+  return { app, container };
+}
+
+const manager = usePopupManager();
+
+function tooltipEntries() {
+  return [...manager.registry.value.values()].filter((e) => e.kind === "tooltip");
+}
+
+function popup(): HTMLElement {
+  return document.querySelector<HTMLElement>(".hk-tooltip-popup")!;
+}
+
+function wrapper(c: HTMLElement): HTMLElement {
+  return c.querySelector<HTMLElement>(".hk-tooltip-wrapper")!;
+}
+
+/** real-timer settle: covers the show setTimeout(0) + the rAF position pass */
+async function settle() {
+  await new Promise((r) => setTimeout(r, 20));
+  await nextTick();
+}
+
+function enter(c: HTMLElement) {
+  wrapper(c).dispatchEvent(new MouseEvent("mouseenter"));
+}
+
+function leave(c: HTMLElement) {
+  wrapper(c).dispatchEvent(new MouseEvent("mouseleave"));
+}
+
+afterEach(() => {
+  vi.useRealTimers();
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+  // The registry is a module singleton — sweep leftovers so tests do not
+  // leak z state (same discipline as usePopupManager.test.ts).
+  for (const entry of [...manager.registry.value.values()]) {
+    manager.unregister(entry.id);
+  }
+  document.querySelectorAll(".hk-tooltip-popup").forEach((el) => el.remove());
+});
+
+describe("HkTooltip popup-manager registration", () => {
+  it("registers one tooltip-kind entry at the tooltip band and stamps its z inline", async () => {
+    mount({ text: "hello" });
+    const entries = tooltipEntries();
+    expect(entries.length).toBe(1);
+    expect(entries[0]!.kind).toBe("tooltip");
+    expect(entries[0]!.zIndex).toBe(POPUP_Z_BANDS.tooltip);
+    // Tooltips are transient annotations — they never lock scroll.
+    expect(entries[0]!.locksScroll).toBe(false);
+    expect(document.body.style.overflow).not.toBe("hidden");
+    // The band z lands on the teleported popup element (set from
+    // onMounted, so the patch flushes on the next tick), overriding the
+    // --hi-z-tooltip SCSS fallback.
+    await nextTick();
+    expect(popup().style.zIndex).toBe(String(POPUP_Z_BANDS.tooltip));
+  });
+
+  it("stacks a second tooltip one step above within the band", () => {
+    mount({ text: "one" });
+    mount({ text: "two" });
+    const entries = tooltipEntries();
+    expect(entries.length).toBe(2);
+    const zs = entries.map((e) => e.zIndex).sort((a, b) => a - b);
+    expect(zs[1]).toBe(zs[0] + POPUP_Z_STEP);
+    expect(zs[0]).toBeGreaterThanOrEqual(POPUP_Z_BANDS.tooltip);
+  });
+
+  it("removes its registry entry on unmount", () => {
+    const { app } = mount({ text: "bye" });
+    expect(tooltipEntries().length).toBe(1);
+    app.unmount();
+    expect(tooltipEntries().length).toBe(0);
+  });
+
+  it("keeps a single registration across show/hide cycles", async () => {
+    const { container } = mount({ text: "stable", delay: 0 });
+    enter(container);
+    await settle();
+    leave(container);
+    await nextTick();
+    enter(container);
+    await settle();
+    expect(tooltipEntries().length).toBe(1);
+  });
+});
+
+describe("HkTooltip show/hide", () => {
+  it("teleports the popup to body, hidden, with the text content", () => {
+    const { container } = mount({ text: "the tip" });
+    const el = popup();
+    expect(document.body.contains(el)).toBe(true);
+    expect(el.parentElement).toBe(document.body);
+    expect(el.className).not.toContain("hk-tooltip-visible");
+    expect(el.querySelector(".hk-tooltip-content")!.textContent).toBe("the tip");
+    // The anchor slot renders inside the wrapper's trigger span.
+    expect(wrapper(container).querySelector(".hk-tooltip-trigger .anchor-probe")).not.toBeNull();
+  });
+
+  it("waits out the default 300ms delay before showing", async () => {
+    vi.useFakeTimers();
+    const { container } = mount({ text: "delayed" });
+    enter(container);
+    await vi.advanceTimersByTimeAsync(299);
+    await nextTick();
+    expect(popup().className).not.toContain("hk-tooltip-visible");
+
+    await vi.advanceTimersByTimeAsync(1);
+    await nextTick();
+    expect(popup().className).toContain("hk-tooltip-visible");
+  });
+
+  it("shows on anchor enter and hides on leave (delay 0)", async () => {
+    const { container } = mount({ text: "quick", delay: 0 });
+    enter(container);
+    await settle();
+    expect(popup().className).toContain("hk-tooltip-visible");
+
+    leave(container);
+    await nextTick();
+    expect(popup().className).not.toContain("hk-tooltip-visible");
+  });
+
+  it("cancels a pending show when the anchor is left before the delay elapses", async () => {
+    vi.useFakeTimers();
+    const { container } = mount({ text: "cancelled", delay: 200 });
+    enter(container);
+    await vi.advanceTimersByTimeAsync(100);
+    leave(container);
+    await vi.advanceTimersByTimeAsync(1000);
+    await nextTick();
+    expect(popup().className).not.toContain("hk-tooltip-visible");
+  });
+
+  it("shows on focusin and hides on focusout like hover", async () => {
+    const { container } = mount({ text: "focused", delay: 0 });
+    container
+      .querySelector(".hk-tooltip-trigger")!
+      .dispatchEvent(new FocusEvent("focusin", { bubbles: true }));
+    await settle();
+    expect(popup().className).toContain("hk-tooltip-visible");
+
+    container
+      .querySelector(".hk-tooltip-trigger")!
+      .dispatchEvent(new FocusEvent("focusout", { bubbles: true }));
+    await nextTick();
+    expect(popup().className).not.toContain("hk-tooltip-visible");
+  });
+});
+
+describe("HkTooltip anchoring", () => {
+  it("places the popup above the anchor with the top placement (gap + transform)", async () => {
+    const { container } = mount({ text: "up", delay: 0, placement: "top" });
+    enter(container);
+    await settle();
+    const el = popup();
+    expect(el.className).toContain("hk-tooltip-top");
+    expect(wrapper(container).getAttribute("data-position")).toBe("top");
+    // happy-dom reports a zero anchor rect: top = 0 - 8 gap, left = the
+    // anchor center, transform flips the popup above that point.
+    expect(el.style.top).toBe("-8px");
+    expect(el.style.left).toBe("0px");
+    expect(el.style.transform).toBe("translate(-50%, -100%)");
+  });
+
+  it("places the popup beside the anchor with the right placement", async () => {
+    const { container } = mount({ text: "side", delay: 0, placement: "right" });
+    enter(container);
+    await settle();
+    const el = popup();
+    expect(el.className).toContain("hk-tooltip-right");
+    expect(wrapper(container).getAttribute("data-position")).toBe("right");
+    expect(el.style.top).toBe("0px");
+    expect(el.style.left).toBe("8px");
+    expect(el.style.transform).toBe("translate(0, -50%)");
+  });
+
+  it("carries the maxWidth prop onto the popup style", async () => {
+    const { container } = mount({ text: "wide", delay: 0, maxWidth: "220px" });
+    enter(container);
+    await settle();
+    expect(popup().style.maxWidth).toBe("220px");
+  });
+});