@celestia-island/hikari 0.55.213 → 0.55.215

package/package.json

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

package/src/components/HkContextMenuProvider.content.test.tsx

@@ -0,0 +1,222 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, nextTick, ref } from "vue";
+
+import HkContextMenuProvider from "./HkContextMenuProvider";
+import HkTagDotRow from "./HkTagDotRow";
+import {
+  useContextMenu,
+  type ContextMenuApi,
+} from "../composables/useContextMenu";
+
+/** Mount into a detached div appended to the body (the menu panels
+ *  teleport; assertions see them through document.querySelectorAll). */
+function mountToDom(component: ReturnType<typeof defineComponent>): HTMLElement {
+  const el = document.createElement("div");
+  document.body.appendChild(el);
+  createApp(component).mount(el);
+  return el;
+}
+
+const popouts = () =>
+  Array.from(document.querySelectorAll(".hk-select-popout")) as HTMLElement[];
+
+const menuRows = () =>
+  Array.from(document.querySelectorAll(".hk-menu-row")) as HTMLButtonElement[];
+
+const headSlot = () => document.querySelector(".hk-menu-slot--head");
+const footSlot = () => document.querySelector(".hk-menu-slot--foot");
+
+/** The provider host, exposing the injected API to the test. */
+function makeHost(): { Component: ReturnType<typeof defineComponent>; api: () => ContextMenuApi } {
+  let held: ContextMenuApi | null = null;
+  const Inner = defineComponent({
+    name: "ContentInner",
+    setup() {
+      held = useContextMenu();
+      return () => <button class="open-btn">open</button>;
+    },
+  });
+  const Component = defineComponent({
+    name: "ContentHost",
+    setup() {
+      return () => (
+        <HkContextMenuProvider>
+          <Inner />
+        </HkContextMenuProvider>
+      );
+    },
+  });
+  return { Component, api: () => held! };
+}
+
+afterEach(() => {
+  document
+    .querySelectorAll(
+      ".hk-select-popout, .hk-select-sheet-panel, .hk-select-sheet-scrim, .open-btn",
+    )
+    .forEach((el) => el.remove());
+  window.history.replaceState(null, "");
+});
+
+/** nextTick + a macrotask + nextTick — panels mount/unmount through
+ *  transitions and history, so a single nextTick races them. */
+async function settle(): Promise<void> {
+  await nextTick();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  await nextTick();
+}
+
+/** Wait until pred() holds (panel teardown settles asynchronously). */
+async function until(pred: () => boolean, ms = 500): Promise<void> {
+  const deadline = Date.now() + ms;
+  while (!pred() && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    await nextTick();
+  }
+}
+
+describe("HkContextMenuProvider — custom content regions", () => {
+  it("renders header and footer regions around the item rows", async () => {
+    const { Component, api } = makeHost();
+    mountToDom(Component);
+    api().open({
+      x: 100,
+      y: 80,
+      title: "Menu",
+      items: [{ key: "copy", label: "Copy" }],
+      header: () => (
+        <HkTagDotRow
+          tags={[{ key: "red", color: "#e5484d", label: "Red", active: true }]}
+          label="tags"
+          onToggle={() => {}}
+        />
+      ),
+      footer: () => <div class="content-foot">F</div>,
+      onSelect: () => {},
+      onClose: () => {},
+    });
+    await settle();
+    expect(popouts()).toHaveLength(1);
+
+    // The header hosts the tag strip; the footer its own node.
+    expect(headSlot()?.querySelector(".hk-tag-dot")).toBeTruthy();
+    expect(footSlot()?.querySelector(".content-foot")).toBeTruthy();
+
+    // Band order: header region → item rows → footer region.
+    const level = document.querySelector(".hk-menu-level")!;
+    const kinds = Array.from(level.children).map((el) =>
+      el.classList.contains("hk-menu-slot") && el.classList.contains("hk-menu-slot--head")
+        ? "head"
+        : el.classList.contains("hk-menu-slot") && el.classList.contains("hk-menu-slot--foot")
+          ? "foot"
+          : "row",
+    );
+    expect(kinds).toEqual(["head", "row", "foot"]);
+  });
+
+  it("keeps the menu open across clicks inside the header region", async () => {
+    const picked: string[] = [];
+    const closed = vi.fn();
+    const { Component, api } = makeHost();
+    mountToDom(Component);
+    api().open({
+      x: 100,
+      y: 80,
+      title: "Menu",
+      items: [{ key: "copy", label: "Copy" }],
+      header: () => (
+        <HkTagDotRow
+          tags={[
+            { key: "red", color: "#e5484d", label: "Red" },
+            { key: "yellow", color: "#ffd400", label: "Yellow" },
+          ]}
+          label="tags"
+          onToggle={() => {}}
+        />
+      ),
+      onSelect: (key) => picked.push(key),
+      onClose: closed,
+    });
+    await settle();
+    const dot = document.querySelector(".hk-tag-dot") as HTMLButtonElement;
+    dot.click();
+    await settle();
+    // An inside-region click toggles, it never dismisses…
+    expect(popouts()).toHaveLength(1);
+    expect(picked).toEqual([]);
+    expect(closed).not.toHaveBeenCalled();
+    // …and an item pick after it still resolves normally.
+    menuRows()[0].click();
+    await settle();
+    expect(picked).toEqual(["copy"]);
+    await until(() => popouts().length === 0);
+  });
+
+  it("keeps the header region live while the menu is open", async () => {
+    const { Component, api } = makeHost();
+    mountToDom(Component);
+    const count = ref(0);
+    api().open({
+      x: 100,
+      y: 80,
+      items: [{ key: "copy", label: "Copy" }],
+      header: () => <div class="content-hdr">n{count.value}</div>,
+      onSelect: () => {},
+      onClose: () => {},
+    });
+    await settle();
+    expect(headSlot()?.textContent).toContain("n0");
+    count.value = 3;
+    await settle();
+    expect(headSlot()?.textContent).toContain("n3");
+  });
+
+  it("renders no region wrappers when the request carries none", async () => {
+    const { Component, api } = makeHost();
+    mountToDom(Component);
+    api().open({
+      x: 100,
+      y: 80,
+      items: [{ key: "copy", label: "Copy" }],
+      onSelect: () => {},
+      onClose: () => {},
+    });
+    await settle();
+    expect(popouts()).toHaveLength(1);
+    expect(headSlot()).toBeNull();
+    expect(footSlot()).toBeNull();
+    expect(menuRows()).toHaveLength(1);
+    api().close();
+    await until(() => popouts().length === 0);
+  });
+
+  it("swaps the regions when a second open replaces the menu", async () => {
+    const { Component, api } = makeHost();
+    mountToDom(Component);
+    api().open({
+      x: 100,
+      y: 80,
+      items: [{ key: "a", label: "A" }],
+      header: () => <div class="content-a">A</div>,
+      onSelect: () => {},
+      onClose: () => {},
+    });
+    await settle();
+    expect(headSlot()?.querySelector(".content-a")).toBeTruthy();
+    api().open({
+      x: 120,
+      y: 90,
+      items: [{ key: "b", label: "B" }],
+      header: () => <div class="content-b">B</div>,
+      onSelect: () => {},
+      onClose: () => {},
+    });
+    await settle();
+    // The epoch remount drops the stale region and its rows wholesale.
+    expect(headSlot()?.querySelector(".content-a")).toBeNull();
+    expect(headSlot()?.querySelector(".content-b")).toBeTruthy();
+    expect(menuRows().map((r) => r.textContent)).toEqual(["B"]);
+    api().close();
+    await until(() => popouts().length === 0);
+  });
+});

package/src/components/HkContextMenuProvider.tsx

@@ -110,6 +110,22 @@ export default defineComponent({
       quadrantPlacement(request.value?.x ?? 0, request.value?.y ?? 0),
     );
 
+    /** The request's custom regions become HkMenu's level-0 header/
+     *  footer slots (object children = slots in Vue JSX). Only the
+     *  keys that exist are handed over, so a request without custom
+     *  content renders exactly as before. The slot closures re-read
+     *  the CURRENT request through the shallowRef, and each open
+     *  bumps menuEpoch — a fresh HkMenu mounts with fresh slots, and
+     *  the region's own reactive reads (host state) keep it live
+     *  while the menu stays open. */
+    const menuSlots = () => {
+      const req = request.value;
+      return {
+        ...(req?.header ? { header: () => req.header!() } : {}),
+        ...(req?.footer ? { footer: () => req.footer!() } : {}),
+      };
+    };
+
     return () => (
       <>
         {slots.default?.()}
@@ -136,7 +152,9 @@ export default defineComponent({
           anchorRef={anchor.value}
           placement={placement.value}
           title={request.value?.title ?? ""}
-        />
+        >
+          {menuSlots()}
+        </HkMenu>
       </>
     );
   },

package/src/components/HkTagDotRow.scss

@@ -0,0 +1,64 @@
+/* ── HkTagDotRow — the Finder-style tag strip ────────────────────
+ * A horizontal row of toggleable colored dots with captions beneath
+ * (the macOS file-tag picker pattern): one dot per tag, a click
+ * toggles, several tags flip in one visit. Metrics and states come
+ * from the unified menu-item spec (see ./_menu-item.scss), so the
+ * strip keeps menu rhythm inside HkMenu header/footer slots,
+ * HkMenuPanel or any popover, and grows with the sheet tokens inside
+ * mobile sheets (registered in the spec's sheet-context list). This
+ * sheet owns only what is the strip's own: the even column layout,
+ * the dot itself, and the caption rhythm. */
+
+@use "./menu-item" as mi;
+
+.hk-tag-dot-row {
+  @include mi.item-tokens;
+  display: flex;
+  flex-direction: row;
+  align-items: stretch;
+  gap: var(--hk-menu-item-gap);
+  /* A band of its own inside the slot wrapper: rows above and below
+   * keep their rhythm, the strip reads as one control. */
+  padding-block: var(--hk-menu-item-pad-y);
+}
+
+.hk-tag-dot {
+  @include mi.item;
+  flex: 1 1 0;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+  gap: calc(var(--hk-menu-item-gap) / 2);
+  min-width: 0;
+  text-align: center;
+}
+
+.hk-tag-dot__dot {
+  flex: none;
+  width: calc(var(--hk-menu-item-icon-box) * 0.65);
+  height: calc(var(--hk-menu-item-icon-box) * 0.65);
+  border-radius: var(--radius-full, 9999px);
+  background: var(--hk-tag-color, rgb(var(--color-primary)));
+  transition: box-shadow 0.12s ease, opacity 0.12s ease;
+}
+
+/* Unapplied tags recede; the applied dot carries a soft ring of its
+ * own ink so the COLOR — not just the button wash — reads as on. */
+.hk-tag-dot:not([data-active]) .hk-tag-dot__dot {
+  opacity: 0.4;
+}
+
+.hk-tag-dot[data-active] .hk-tag-dot__dot {
+  box-shadow: 0 0 0 2px
+    color-mix(in srgb, var(--hk-tag-color, rgb(var(--color-primary))) 30%, transparent);
+}
+
+/* The caption is secondary to the dot: the row grammar above sets
+ * size/weight; captions only keep their own line rhythm and may wrap
+ * (three short columns, never a wide table). */
+.hk-tag-dot__label {
+  min-width: 0;
+  max-width: 100%;
+  overflow-wrap: anywhere;
+  line-height: var(--hk-menu-item-lh);
+}

package/src/components/HkTagDotRow.test.tsx

@@ -0,0 +1,95 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent } from "vue";
+
+import HkTagDotRow, { type HkTagDot } from "./HkTagDotRow";
+
+/** Mount into a detached div appended to the body — the family's
+ *  mount pattern (assertions go through document.querySelectorAll). */
+function mountRow(tags: HkTagDot[], onToggle: (key: string) => void, label?: string): void {
+  const el = document.createElement("div");
+  document.body.appendChild(el);
+  createApp(
+    defineComponent({
+      name: "TagDotRowHost",
+      setup() {
+        return () => <HkTagDotRow tags={tags} label={label} onToggle={onToggle} />;
+      },
+    }),
+  ).mount(el);
+}
+
+const dots = () =>
+  Array.from(document.querySelectorAll(".hk-tag-dot")) as HTMLButtonElement[];
+
+const dotByAria = (name: string) =>
+  dots().find((b) => b.getAttribute("aria-label") === name);
+
+afterEach(() => {
+  dots().forEach((b) => b.remove());
+  document.querySelectorAll(".hk-tag-dot-row").forEach((el) => el.remove());
+});
+
+describe("HkTagDotRow", () => {
+  it("renders one toggle per tag: dot ink, caption, pressed state", () => {
+    mountRow(
+      [
+        { key: "red", color: "#e5484d", label: "Red" },
+        { key: "yellow", color: "#ffd400", active: true },
+        { key: "purple", color: "#a855f7" },
+      ],
+      () => {},
+      "Tags",
+    );
+    const row = document.querySelector(".hk-tag-dot-row")!;
+    expect(row.getAttribute("role")).toBe("group");
+    expect(row.getAttribute("aria-label")).toBe("Tags");
+
+    expect(dots()).toHaveLength(3);
+    // Dot ink rides the per-tag custom property on the dot itself…
+    const red = dotByAria("Red")!;
+    const redDot = red.querySelector(".hk-tag-dot__dot") as HTMLElement;
+    expect(redDot.style.getPropertyValue("--hk-tag-color")).toBe("#e5484d");
+    expect(red.querySelector(".hk-tag-dot__label")?.textContent).toBe("Red");
+    expect(red.getAttribute("aria-pressed")).toBe("false");
+    expect(red.hasAttribute("data-active")).toBe(false);
+
+    // …the applied tag carries the selected face and pressed state.
+    const yellow = dotByAria("yellow")!;
+    expect(yellow.getAttribute("aria-pressed")).toBe("true");
+    expect(yellow.hasAttribute("data-active")).toBe(true);
+    // A labelless tag falls back to its key for the accessible name
+    // and renders no caption span.
+    expect(yellow.querySelector(".hk-tag-dot__label")).toBeNull();
+  });
+
+  it("emits toggle with the tag key on click", () => {
+    const toggled: string[] = [];
+    mountRow(
+      [
+        { key: "red", color: "#e5484d", label: "Red" },
+        { key: "purple", color: "#a855f7", label: "Purple" },
+      ],
+      (key) => toggled.push(key),
+    );
+    dotByAria("Red")!.click();
+    dotByAria("Purple")!.click();
+    expect(toggled).toEqual(["red", "purple"]);
+  });
+
+  it("keeps a disabled tag inert", () => {
+    const toggled = vi.fn();
+    mountRow(
+      [
+        { key: "red", color: "#e5484d", label: "Red", disabled: true },
+        { key: "purple", color: "#a855f7", label: "Purple" },
+      ],
+      toggled,
+    );
+    const red = dotByAria("Red")!;
+    expect(red.disabled).toBe(true);
+    red.click(); // happy-dom honors disabled on click dispatch
+    expect(toggled).not.toHaveBeenCalled();
+    dotByAria("Purple")!.click();
+    expect(toggled).toHaveBeenCalledWith("purple");
+  });
+});

package/src/components/HkTagDotRow.tsx

@@ -0,0 +1,65 @@
+import { defineComponent, type PropType } from "vue";
+
+import "./HkTagDotRow.scss";
+
+/** One toggleable tag of a HkTagDotRow. */
+export interface HkTagDot {
+  /** Stable identity emitted by `toggle`. */
+  key: string;
+  /** Dot color — any CSS color (hex, rgb(), a var() reference…). */
+  color: string;
+  /** Caption under the dot; the host i18n's it. */
+  label?: string;
+  /** Whether the tag is currently applied (the row's selected face). */
+  active?: boolean;
+  /** Inert: rendered dimmed, clicks never toggle it. */
+  disabled?: boolean;
+}
+
+/**
+ * HkTagDotRow — a horizontal strip of toggleable colored dots, the
+ * macOS Finder tag-editor pattern: one dot per tag, the caption
+ * beneath it, one click toggles. Tags are domain-free {key, color,
+ * label} triples — the host owns the vocabulary (and its i18n), the
+ * row owns only the geometry and states.
+ *
+ * Speaks the unified menu-item spec (see ./_menu-item.scss), so it
+ * drops straight into menu surfaces — HkMenu's header/footer slots,
+ * HkMenuPanel, a popover — and keeps menu rhythm there, growing with
+ * the sheet tokens inside mobile sheets; it works anywhere else a
+ * compact tag picker belongs (settings rows, card footers). Clicking
+ * a dot never closes a surrounding menu: it emits `toggle` only, and
+ * the host decides what to do (menus stay open across toggles so
+ * several tags can be flipped in one visit).
+ */
+export default defineComponent({
+  name: "HkTagDotRow",
+  props: {
+    tags: { type: Array as PropType<HkTagDot[]>, required: true },
+    /** Accessible name for the whole group (aria-label). */
+    label: { type: String, default: undefined },
+  },
+  emits: ["toggle"],
+  setup(props, { emit }) {
+    return () => (
+      <div class="hk-tag-dot-row" role="group" aria-label={props.label}>
+        {props.tags.map((tag) => (
+          <button
+            key={tag.key}
+            type="button"
+            class="hk-tag-dot"
+            data-active={tag.active || undefined}
+            disabled={tag.disabled}
+            aria-pressed={tag.active ? "true" : "false"}
+            aria-label={tag.label ?? tag.key}
+            title={tag.label}
+            onClick={() => emit("toggle", tag.key)}
+          >
+            <span class="hk-tag-dot__dot" style={{ "--hk-tag-color": tag.color }} />
+            {tag.label ? <span class="hk-tag-dot__label">{tag.label}</span> : null}
+          </button>
+        ))}
+      </div>
+    );
+  },
+});

package/src/components/HkToast.scss

@@ -128,6 +128,39 @@
   to { transform: rotate(360deg); }
 }
 
+/* Inline action (e.g. Undo): a compact text pill in the toast chrome,
+ *  between the body and the icon buttons. Sits in the same ghost-button
+ *  family as copy/close, but reads as an affordance. */
+.hk-toast-action {
+  flex: none;
+  align-self: center;
+  margin-inline-start: var(--space-4, 4px);
+  padding: var(--space-2, 2px) var(--space-8, 8px);
+  border: 1px solid rgb(var(--color-border, 100 100 100) / 30%);
+  border-radius: var(--radius-sm, 4px);
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  font-size: var(--text-sm, 0.8125rem);
+  font-weight: 600;
+  line-height: 1.4;
+  cursor: pointer;
+  white-space: nowrap;
+  opacity: 0.92;
+  transition: opacity var(--duration-fast, 0.15s) ease,
+    border-color var(--duration-fast, 0.15s) ease;
+}
+
+.hk-toast-action:hover {
+  opacity: 1;
+  border-color: rgb(var(--color-border, 100 100 100) / 55%);
+}
+
+.hk-toast-action:focus-visible {
+  outline: 2px solid rgb(var(--color-primary));
+  outline-offset: 2px;
+}
+
 .hk-toast-copy-btn,
 .hk-toast-close {
   display: flex;

package/src/components/HkToast.test.tsx

@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { createApp, h, nextTick } from "vue";
 
 import HkToast from "./HkToast";
@@ -262,4 +262,75 @@ describe("HkToast live-region semantics", () => {
       expect(el.getAttribute("aria-live"), type).toBe("polite");
     }
   });
+
+  it("renders an inline action button that dismisses first, then runs", async () => {
+    mountHost();
+    const toast = useToast();
+    let slotGoneAtClick = false;
+    toast.show("Player removed", {
+      type: "success",
+      duration: 8000,
+      action: {
+        label: "Undo",
+        onClick: () => {
+          // The dismissal is synchronous and precedes the handler.
+          slotGoneAtClick = !toast.toasts.some((t) => t.type === "success");
+        },
+      },
+    });
+    await settle();
+
+    const item = items()[0];
+    const button = item.querySelector<HTMLButtonElement>(".hk-toast-action");
+    expect(button).not.toBeNull();
+    expect(button!.textContent).toBe("Undo");
+
+    button!.click();
+    await settle();
+    expect(slotGoneAtClick).toBe(true);
+    expect(items().length).toBe(0); // the action dismisses the toast
+  });
+
+  it("runs the action at most once (the leaving item stays clickable)", async () => {
+    mountHost();
+    const toast = useToast();
+    const undone = vi.fn();
+    toast.show("Player removed", {
+      type: "success",
+      duration: 8000,
+      action: { label: "Undo", onClick: undone },
+    });
+    await settle();
+    const button = items()[0].querySelector<HTMLButtonElement>(".hk-toast-action")!;
+    button.click();
+    button.click(); // the leave transition keeps the node clickable briefly
+    await settle();
+    expect(undone).toHaveBeenCalledTimes(1);
+  });
+
+  it("renders no action button for plain toasts", async () => {
+    mountHost();
+    const toast = useToast();
+    toast.success("Saved");
+    await settle();
+    expect(items()[0].querySelector(".hk-toast-action")).toBeNull();
+  });
+
+  it("keeps the toast dismissed even when the action handler throws", async () => {
+    mountHost();
+    const toast = useToast();
+    toast.show("Player removed", {
+      type: "success",
+      action: {
+        label: "Undo",
+        onClick: () => {
+          throw new Error("undo failed");
+        },
+      },
+    });
+    await settle();
+    items()[0].querySelector<HTMLButtonElement>(".hk-toast-action")!.click();
+    await settle();
+    expect(items().length).toBe(0);
+  });
 });

package/src/components/HkToast.tsx

@@ -100,6 +100,24 @@ const HkToastItem = defineComponent({
       emit("remove", props.toast.id);
     }
 
+    /** The inline action (e.g. Undo) dismisses the toast and runs the
+     *  host's handler; a thrown handler must not keep the toast alive.
+     *  Single-shot: the leaving item stays clickable for the leave
+     *  transition, and a double-click must not run an undo twice. */
+    let actionFired = false;
+    function handleAction() {
+      if (actionFired) return;
+      actionFired = true;
+      const action = props.toast.action;
+      emit("remove", props.toast.id);
+      try {
+        action?.onClick?.();
+      } catch {
+        // A throwing undo handler must not resurrect a dismissed toast
+        // (or break the toast stack's render for every other slot).
+      }
+    }
+
     return () => {
       const msg = displayedMessage.value;
       const text = msg?.text ?? "";
@@ -138,6 +156,18 @@ const HkToastItem = defineComponent({
               <span class="hk-toast-count">{renderCountLabel(count, t("hikari::toast.msgs", "msgs"))}</span>
             )}
           </div>
+          {props.toast.action && (
+            <button
+              class="hk-toast-action"
+              title={props.toast.action.label}
+              onClick={(e: MouseEvent) => {
+                e.stopPropagation();
+                handleAction();
+              }}
+            >
+              {props.toast.action.label}
+            </button>
+          )}
           {props.toast.copyable && (
             <button
               class="hk-toast-copy-btn"

package/src/components/_menu-item.scss

@@ -2,8 +2,8 @@
  *
  * Every selectable list row the library renders — cascade menu rows,
  * action rows, select options, popup-select items, theme pills, admin
- * header rows, nav rows, breadcrumb dropdown items — shares this exact
- * grammar. Desktop (anchored popouts) and mobile (bottom sheets) are
+ * header rows, nav rows, breadcrumb dropdown items, tag strips —
+ * shares this exact grammar. Desktop (anchored popouts) and mobile (bottom sheets) are
  * the same spec at two token sets; a sheet context merely swaps the
  * tokens, so every row inside ANY sheet gets the touch geometry
  * without per-component media queries.
@@ -89,7 +89,9 @@
   .s-popup-menu-item,
   .hk-popup-menu-item,
   .hk-breadcrumb-dropdown-item,
-  .hk-menu-divider {
+  .hk-menu-divider,
+  .hk-tag-dot-row,
+  .hk-tag-dot {
     @include item-sheet-tokens;
   }
 }
@@ -108,7 +110,9 @@
     .s-theme-item-btn,
     .s-popup-menu-item,
     .hk-popup-menu-item,
-    .hk-menu-divider {
+    .hk-menu-divider,
+    .hk-tag-dot-row,
+    .hk-tag-dot {
       @include item-sheet-tokens;
     }
   }

package/src/composables/useContextMenu.test.tsx

@@ -550,3 +550,89 @@ describe("useContextMenu + HkContextMenuProvider", () => {
     expect(which).toEqual([el1, el2]); // el1 unbound, el2 bound
   });
 });
+
+describe("bindContextMenu layering — a delegating outer binding defers to inner ones", () => {
+  it("suppresses the outer open when an inner binding already claimed the event", () => {
+    const inner = mockApi();
+    const outer = mockApi();
+    const outerEl = document.createElement("div");
+    outerEl.setAttribute("data-bind-target", "");
+    const innerEl = document.createElement("div");
+    innerEl.setAttribute("data-bind-target", "");
+    outerEl.appendChild(innerEl);
+    document.body.appendChild(outerEl);
+
+    const unbindOuter = bindContextMenu(outerEl, outer.api, (point) =>
+      // The delegating contract: an inner binding consumed the native
+      // event, so its menu stands — this one steps aside.
+      point.defaultPrevented
+        ? null
+        : { x: point.x, y: point.y, items: [{ key: "outer", label: "Outer" }] },
+    );
+    const unbindInner = bindContextMenu(innerEl, inner.api, () => ({
+      x: 1,
+      y: 2,
+      items: [{ key: "inner", label: "Inner" }],
+    }));
+
+    innerEl.dispatchEvent(
+      new MouseEvent("contextmenu", { bubbles: true, cancelable: true, clientX: 5, clientY: 6 }),
+    );
+    expect(inner.opens).toHaveLength(1);
+    expect(outer.opens).toHaveLength(0);
+
+    unbindOuter();
+    unbindInner();
+    outerEl.remove();
+  });
+
+  it("still opens the outer menu for events the inner binding never sees", () => {
+    const inner = mockApi();
+    const outer = mockApi();
+    const outerEl = document.createElement("div");
+    outerEl.setAttribute("data-bind-target", "");
+    const innerEl = document.createElement("div");
+    innerEl.setAttribute("data-bind-target", "");
+    outerEl.appendChild(innerEl);
+    document.body.appendChild(outerEl);
+
+    const unbindOuter = bindContextMenu(outerEl, outer.api, (point) =>
+      point.defaultPrevented
+        ? null
+        : { x: point.x, y: point.y, items: [{ key: "outer", label: "Outer" }] },
+    );
+    const unbindInner = bindContextMenu(innerEl, inner.api, () => ({
+      x: 1,
+      y: 2,
+      items: [{ key: "inner", label: "Inner" }],
+    }));
+
+    outerEl.dispatchEvent(
+      new MouseEvent("contextmenu", { bubbles: true, cancelable: true, clientX: 7, clientY: 8 }),
+    );
+    expect(inner.opens).toHaveLength(0);
+    expect(outer.opens).toHaveLength(1);
+
+    unbindOuter();
+    unbindInner();
+    outerEl.remove();
+  });
+
+  it("reports defaultPrevented on the trigger point (false before this binding acts)", () => {
+    const target = document.createElement("div");
+    target.setAttribute("data-bind-target", "");
+    document.body.appendChild(target);
+    const { api } = mockApi();
+    const seen: (boolean | undefined)[] = [];
+    const unbind = bindContextMenu(target, api, (point) => {
+      seen.push(point.defaultPrevented);
+      return { x: point.x, y: point.y, items: [{ key: "a", label: "A" }] };
+    });
+    const event = new MouseEvent("contextmenu", { bubbles: true, cancelable: true });
+    target.dispatchEvent(event);
+    // Read BEFORE this binding's own preventDefault runs.
+    expect(seen).toEqual([false]);
+    expect(event.defaultPrevented).toBe(true);
+    unbind();
+  });
+});

package/src/composables/useContextMenu.ts

@@ -24,7 +24,14 @@
  * after a long touch do not open the menu twice.
  */
 
-import { inject, onBeforeUnmount, watch, type InjectionKey, type Ref } from "vue";
+import {
+  inject,
+  onBeforeUnmount,
+  watch,
+  type InjectionKey,
+  type Ref,
+  type VNodeChild,
+} from "vue";
 
 import type { HkMenuItem } from "../components/HkMenu";
 
@@ -36,6 +43,21 @@ export interface ContextMenuRequest {
   items: HkMenuItem[];
   /** Sheet header on mobile / popout a11y label on desktop. */
   title?: string;
+  /** Custom region pinned ABOVE the item rows (the root level only,
+   *  exactly like HkMenu's header slot, which this forwards to). The
+   *  menu chrome — popout/sheet, flipping, z-stack, outside-click,
+   *  Escape — stays the panel's; the region is a normal interactive
+   *  island inside it: clicks on it do NOT close the menu, so several
+   *  toggles can happen in one visit. State must live in the HOST'S
+   *  scope (the menu remounts on every open — see the provider's
+   *  menuEpoch); the render function reading reactive sources keeps
+   *  the region live while the menu is open. Conditionally render
+   *  NOTHING by returning an empty array ([]) — a null/undefined
+   *  return still mounts the slot wrapper and its flex gap. */
+  header?: () => VNodeChild;
+  /** Custom region pinned BELOW the item rows — the footer twin of
+   *  the header field (HkMenu's footer slot). */
+  footer?: () => VNodeChild;
   /** Called with the picked item's key. The menu closes itself. */
   onSelect?: (key: string, item: HkMenuItem) => void;
   /** Called when the menu closes without a selection (outside click,
@@ -83,6 +105,14 @@ export interface ContextTriggerPoint {
   kind: "pointer" | "longpress" | "keyboard";
   /** The element the trigger landed on (event.target). */
   target: EventTarget | null;
+  /** True when the underlying native event was already consumed
+   *  (preventDefault) by an INNER binding's handler before this one
+   *  ran — listeners fire innermost-first, so a DELEGATING (outer)
+   *  binding sees it only after an inner binding opened its menu. An
+   *  outer binding must defer: return null so the inner menu stands.
+   *  Absent for long-press opens (no native context event rides the
+   *  timer; an outer binding resolves by target instead). */
+  defaultPrevented?: boolean;
 }
 
 /**
@@ -149,6 +179,7 @@ export function bindContextMenu(
       y: event.clientY,
       kind: "pointer",
       target: event.target,
+      defaultPrevented: event.defaultPrevented,
     });
     if (opened) event.preventDefault();
     // Not opened: let it bubble to an outer binding untouched.
@@ -184,6 +215,7 @@ export function bindContextMenu(
       y: rect.bottom,
       kind: "keyboard",
       target: event.target,
+      defaultPrevented: event.defaultPrevented,
     });
     if (opened) event.preventDefault();
   };

package/src/index.ts

@@ -79,6 +79,7 @@ export { HkLocalizedInput as HLocalizedInput, type HkLocaleOption } from "./comp
 export { default as HMenuPanel } from "./components/HkMenuPanel";
 export { default as HMenuActionItem } from "./components/HkMenuActionItem";
 export { default as HMenuIdentityItem } from "./components/HkMenuIdentityItem";
+export { default as HTagDotRow, type HkTagDot } from "./components/HkTagDotRow";
 export { default as HPopupSelect, isAnyPopupOpen, closeAllPopups, type HkPopupSelectOption } from "./components/HkPopupSelect";
 export { default as HProgressBar } from "./components/HkProgressBar";
 export { default as HProgressDialog } from "./components/HkProgressDialog";
@@ -382,6 +383,7 @@ export {
   type OverlayHandle,
   type PopupHandle,
   type PopupKind,
+  type ToastAction,
   type ToastItem,
   type ToastMessage,
   type ToastType,
@@ -669,6 +671,7 @@ export { default as HkContextMenuProvider } from "./components/HkContextMenuProv
 export { default as HkMenuPanel } from "./components/HkMenuPanel";
 export { default as HkMenuActionItem } from "./components/HkMenuActionItem";
 export { default as HkMenuIdentityItem } from "./components/HkMenuIdentityItem";
+export { default as HkTagDotRow } from "./components/HkTagDotRow";
 export { default as HkRowActions } from "./components/HkRowActions";
 export { default as HkPopupSelect } from "./components/HkPopupSelect";
 export { default as HkProgressBar } from "./components/HkProgressBar";

package/src/runtime/index.ts

@@ -80,7 +80,7 @@ export {
   type PopupHandle,
   type PopupKind,
 } from "./usePopupManager";
-export { useToast, TOAST_DURATION, type ToastItem, type ToastMessage, type ToastType } from "./useToast";
+export { useToast, TOAST_DURATION, type ToastAction, type ToastItem, type ToastMessage, type ToastType } from "./useToast";
 export { useConfirm } from "./useConfirm";
 export { useBlockingToast, showBlockingToast, resolveBlockingToast, clearBlockingToasts, type BlockingToastItem, type BlockingToastOptions, type BlockingToastVariant } from "./useBlockingToast";
 export { useBreakpoint } from "./useBreakpoint";

package/src/runtime/useToast.test.ts

@@ -88,3 +88,47 @@ describe("useToast stacking and dedupe", () => {
     expect(toast.toasts.some((t) => t.type === "info")).toBe(true);
   });
 });
+
+describe("useToast inline actions", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    clearAll();
+  });
+  afterEach(() => {
+    clearAll();
+    vi.useRealTimers();
+  });
+
+  it("carries the action on the slot", () => {
+    const toast = useToast();
+    const run = vi.fn();
+    toast.show("Player removed", {
+      type: "success",
+      duration: 8000,
+      action: { label: "Undo", onClick: run },
+    });
+    const slot = toast.toasts.find((t) => t.type === "success")!;
+    expect(slot.action?.label).toBe("Undo");
+    expect(slot.action?.onClick).toBe(run);
+  });
+
+  it("the latest push owns the action (a plain message clears it)", () => {
+    const toast = useToast();
+    toast.show("Player removed", {
+      type: "success",
+      action: { label: "Undo", onClick: () => {} },
+    });
+    toast.success("Saved");
+    expect(toast.toasts.find((t) => t.type === "success")!.action).toBeUndefined();
+  });
+
+  it("re-passing the action keeps it on the shared slot", () => {
+    const toast = useToast();
+    const first = { label: "Undo", onClick: () => {} };
+    const second = { label: "Retry", onClick: () => {} };
+    toast.show("Player removed", { type: "success", action: first });
+    toast.show("Player removed again", { type: "success", action: second });
+    // Reactive slots wrap the object — compare by value, not identity.
+    expect(toast.toasts.find((t) => t.type === "success")!.action).toEqual(second);
+  });
+});

package/src/runtime/useToast.ts

@@ -26,12 +26,27 @@ export interface ToastMessage {
   text: string;
 }
 
+/** One inline action button on a toast (e.g. "Undo" after a delete).
+ *  The action belongs to the CURRENT slot state: every push sets or
+ *  clears it, so the latest message decides what the button offers. */
+export interface ToastAction {
+  /** Button label (the caller i18n's it). */
+  label: string;
+  /** Runs when the button is clicked. The toast dismisses FIRST, then
+   *  this handler runs — a throwing handler can never keep the toast
+   *  alive. The button itself is single-shot: a second click during the
+   *  leave transition is ignored. */
+  onClick?: () => void;
+}
+
 export interface ToastItem {
   id: number;
   type: ToastType;
   messages: ToastMessage[];
   duration?: number;
   copyable?: boolean;
+  /** Inline action button — see ToastAction. */
+  action?: ToastAction;
 }
 
 /** Hard cap on stacked messages per toast slot. Beyond it the oldest
@@ -96,7 +111,7 @@ function findSlot(type: ToastType): ToastItem | undefined {
 function push(
   type: ToastType,
   text: string,
-  options: { duration?: number; copyable?: boolean } = {},
+  options: { duration?: number; copyable?: boolean; action?: ToastAction } = {},
 ): number {
   let slot = findSlot(type);
   if (!slot) {
@@ -106,10 +121,16 @@ function push(
       messages: [],
       duration: options.duration ?? TOAST_DURATION[type],
       copyable: options.copyable ?? defaultCopyable(type),
+      action: options.action,
     };
     state.toasts.push(slot);
-  } else if (options.copyable === true && !slot.copyable) {
-    slot.copyable = true;
+  } else {
+    if (options.copyable === true && !slot.copyable) {
+      slot.copyable = true;
+    }
+    // Latest push owns the action: re-passing it keeps the button, a
+    // plain message (no action) clears it off the shared slot.
+    slot.action = options.action;
   }
   let msgId: number;
   const last = slot.messages[slot.messages.length - 1];
@@ -141,6 +162,7 @@ export function useToast() {
     return push(type, message, {
       duration: options.duration,
       copyable: options.copyable,
+      action: options.action,
     });
   }