@celestia-island/hikari 0.55.214 → 0.55.216

package/package.json

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

package/src/components/HkIconButton.scss

@@ -21,6 +21,10 @@
   align-items: center;
   justify-content: center;
   flex-shrink: 0;
+  // The status dot's anchor layer (.hk-icon-button-dot below) — a
+  // relative button keeps the mark INSIDE the control's own silhouette
+  // no matter what wrappers or flex rows do around it.
+  position: relative;
   padding: 0;
   line-height: 0;
 
@@ -141,3 +145,25 @@
     transition: none;
   }
 }
+
+// ------
+// Button-owned status dot (dot prop)
+// ------
+
+/* The mark lives INSIDE the button's own box (bottom-right inset), not
+ * straddling a wrapper corner: on a borderless ghost trigger inside a
+ * centered flex row, the corner-straddling badge read as a stray dot
+ * floating below the glyph (2026-10-28 user report). Tone channels come
+ * from HkCornerBadge's variant classes (one badge grammar); the surface
+ * ring keeps the dot legible on any button fill. */
+.hk-icon-button-dot {
+  position: absolute;
+  right: var(--hk-icon-button-dot-inset, 2px);
+  bottom: var(--hk-icon-button-dot-inset, 2px);
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--hk-badge-bg, rgb(var(--color-success)));
+  box-shadow: 0 0 0 1.5px rgb(var(--color-surface) / 85%);
+  pointer-events: none;
+}

package/src/components/HkIconButton.test.tsx

@@ -151,3 +151,78 @@ describe("HkIconButton glyph step", () => {
     expect(block24).toContain("var(--hi-icon-size-xs)");
   });
 });
+
+describe("HkIconButton status dot", () => {
+  it("renders no dot by default", () => {
+    const c = mountComp(() =>
+      h(HkIconButton, { "aria-label": "Filter" }, { icon: () => h("span", "x") }),
+    );
+    expect(c.querySelector(".hk-icon-button-dot")).toBeNull();
+  });
+
+  it("dot renders inside the button with the tone class and stays decorative", () => {
+    const c = mountComp(() =>
+      h(HkIconButton, { dot: true, "aria-label": "Filter" }, { icon: () => h("span", "x") }),
+    );
+    const dot = c.querySelector(".hk-icon-button-dot")!;
+    expect(dot).not.toBeNull();
+    // Tone channels ride HkCornerBadge's variant classes (one grammar).
+    expect(dot.classList.contains("hk-corner-badge-success")).toBe(true);
+    // Decorative by default: the button's own label carries the state.
+    expect(dot.getAttribute("aria-hidden")).toBe("true");
+    expect(dot.getAttribute("role")).toBeNull();
+    // Inside the button's own silhouette — never a detached wrapper mark.
+    expect(dot.closest("button")).not.toBeNull();
+    expect(dot.closest(".hk-corner-badge-anchor")).toBeNull();
+  });
+
+  it("dotVariant switches the tone class", () => {
+    const c = mountComp(() =>
+      h(HkIconButton, { dot: true, dotVariant: "error", "aria-label": "Fail" }, { icon: () => h("span", "x") }),
+    );
+    expect(c.querySelector(".hk-icon-button-dot")!.classList.contains("hk-corner-badge-error")).toBe(true);
+  });
+
+  it("dotLabel promotes the dot to a named mark", () => {
+    const c = mountComp(() =>
+      h(HkIconButton, { dot: true, dotLabel: "Filter engaged", "aria-label": "Filter" }, { icon: () => h("span", "x") }),
+    );
+    const dot = c.querySelector(".hk-icon-button-dot")!;
+    expect(dot.getAttribute("aria-hidden")).toBeNull();
+    expect(dot.getAttribute("role")).toBe("img");
+    expect(dot.getAttribute("aria-label")).toBe("Filter engaged");
+  });
+});
+
+/**
+ * Compiled-stylesheet guard for the button-owned status dot (R3-style
+ * contract, HkCornerBadge.styles.test.ts pattern): the button is the
+ * anchor layer (position: relative) and the dot is an absolutely
+ * positioned INSET mark with pointer-events off — the declarations are
+ * the contract where happy-dom has no cascade.
+ */
+describe("HkIconButton status dot stylesheet contract", () => {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const scss = readFileSync(join(here, "HkIconButton.scss"), "utf8");
+
+  it("the button is the dot's anchor layer (position: relative)", () => {
+    const start = scss.indexOf(".hk-icon-button {");
+    const close = scss.indexOf("}", start);
+    expect(scss.slice(start, close + 1)).toContain("position: relative");
+  });
+
+  it("the dot is an absolute inset mark with pointer-events off and a round cutout ring", () => {
+    const start = scss.indexOf(".hk-icon-button-dot {");
+    const close = scss.indexOf("}", start);
+    const rule = scss.slice(start, close + 1);
+    expect(rule).toContain("position: absolute");
+    expect(rule).toContain("right: var(--hk-icon-button-dot-inset");
+    expect(rule).toContain("bottom: var(--hk-icon-button-dot-inset");
+    expect(rule).toContain("pointer-events: none");
+    expect(rule).toContain("border-radius: 50%");
+    expect(rule).toContain("box-shadow: 0 0 0 1.5px");
+    // Tone rides HkCornerBadge's variant classes; the declaration (not
+    // just the class) is pinned so a tone swap cannot slip silently.
+    expect(rule).toContain("background: var(--hk-badge-bg");
+  });
+});

package/src/components/HkIconButton.tsx

@@ -1,7 +1,12 @@
 import { computed, defineComponent, type PropType } from "vue";
 import "./HkIconButton.scss";
 import "./HkIconButtonVars.scss";
+// The status dot borrows HkCornerBadge's tone channels (--hk-badge-bg)
+// so the mark on the button and the badge family stay one grammar; the
+// bundler dedupes the sheet (single source of tones).
+import "./HkCornerBadge.scss";
 import HIcon from "./HkIcon";
+import type { CornerBadgeVariant } from "./HkCornerBadge";
 
 export default defineComponent({
   name: "HkIconButton",
@@ -16,6 +21,21 @@ export default defineComponent({
     // (user report 2026-09-28: 前台全局搜索与主题切换按钮不同尺寸).
     size: { type: Number as PropType<16 | 24 | 28 | 32 | 36 | 40>, default: 32 },
     disabled: { type: Boolean, default: false },
+    /** Button-owned status dot (2026-10-28 user direction: 改进图标按钮
+     *  本身). The former pattern — HkCornerBadge wrapped AROUND the
+     *  trigger — anchors to the WRAPPER's corner (translate 50% straddles
+     *  the box edge), which on a borderless ghost trigger inside a
+     *  centered flex row reads as a stray mark floating below the glyph.
+     *  This dot is laid out INSIDE the button's own box (bottom-right
+     *  inset), so the mark and the control are one silhouette. Intended
+     *  for the ≥24 chrome steps — at 16 the 8px dot would crowd the
+     *  glyph (R2 note; no such consumer today). */
+    dot: { type: Boolean, default: false },
+    /** Tone of the status dot (same variant names as HkCornerBadge). */
+    dotVariant: { type: String as PropType<CornerBadgeVariant>, default: "success" },
+    /** Accessible name for the dot (without it the dot is aria-hidden
+     *  decoration for state the button already announces). */
+    dotLabel: { type: String, default: undefined },
   },
   emits: {
     click: (_e: MouseEvent) => true,
@@ -59,6 +79,14 @@ export default defineComponent({
                   </svg>
                 )}
         </span>
+        {props.dot && (
+          <span
+            class={["hk-icon-button-dot", `hk-corner-badge-${props.dotVariant}`]}
+            aria-hidden={props.dotLabel ? undefined : "true"}
+            role={props.dotLabel ? "img" : undefined}
+            aria-label={props.dotLabel}
+          />
+        )}
       </button>
     );
   },

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/index.ts

@@ -383,6 +383,7 @@ export {
   type OverlayHandle,
   type PopupHandle,
   type PopupKind,
+  type ToastAction,
   type ToastItem,
   type ToastMessage,
   type ToastType,

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,
     });
   }