@celestia-island/hikari 0.55.226 → 0.55.228

package/package.json

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

package/src/components/HkAdminHeader.tsx

@@ -1,8 +1,9 @@
-import { computed, defineComponent, ref, type PropType, type VNode } from "vue";
+import { computed, defineComponent, ref, watch, type PropType, type VNode } from "vue";
 import { Camera, ExternalLink, Languages, LogOut, Menu } from "lucide-vue-next";
 import { HBadge, HButton, HSpinner } from "@celestia-island/hikari";
 import { useI18n } from "../i18n/context";
 import HkMenu, { type HkMenuItem } from "./HkMenu";
+import { HkAvatarButton } from "./HkAvatarButton";
 
 export interface LocaleOption {
   code: string;
@@ -93,7 +94,16 @@ export const HkAdminHeader = defineComponent({
     const userMenuOpen = ref(false);
     const userTriggerRef = ref<HTMLElement>();
     const avatarModalOpen = ref(false);
-    const avatarFailed = ref(false);
+    // The DROPDOWN identity image's own failed-load latch, with the same
+    // URL-change reset the trigger's latch has inside HkAvatarButton —
+    // an avatar re-upload or account switch must heal BOTH faces (R2's
+    // S2 on #909: without the reset, the trigger showed the new image
+    // while the chip stayed on its letter fallback forever).
+    const menuAvatarFailed = ref(false);
+    watch(
+      () => props.avatarUrl,
+      () => { menuAvatarFailed.value = false; },
+    );
 
     // The identity cluster is INJECTED, not assumed (2026-10-24): the
     // trigger renders only when the host actually supplied an identity
@@ -219,35 +229,14 @@ export const HkAdminHeader = defineComponent({
             </HButton>
           )}
           {identityMounted.value && (
-            <button
-              class="s-admin-header-avatar"
-              aria-label={props.avatarTriggerLabel ?? t("hikari::adminHeader.avatarTrigger", "Account menu")}
-              aria-haspopup={props.avatarAction === "drawer" ? "dialog" : "menu"}
-              aria-expanded={props.avatarAction === "menu" ? userMenuOpen.value : undefined}
+            <HkAvatarButton
+              avatarUrl={props.avatarUrl}
+              username={props.username}
+              label={props.avatarTriggerLabel ?? t("hikari::adminHeader.avatarTrigger", "Account menu")}
+              popup={props.avatarAction === "drawer" ? "dialog" : "menu"}
+              expanded={props.avatarAction === "menu" ? userMenuOpen.value : undefined}
               onClick={onAvatarClick}
-            >
-              {/* Deliberately NO hover veil here: the trigger opens the user
-               *  MENU (the avatar edit lives one row down as the Camera
-               *  item), so a camera overlay would promise click-to-change
-               *  and lie (user report 2026-09-16). */}
-              {props.avatarUrl && !avatarFailed.value ? (
-                <img
-                  src={props.avatarUrl}
-                  alt={props.username}
-                  class="s-admin-header-avatar-img"
-                  onError={() => { avatarFailed.value = true; }}
-                />
-              ) : (
-                // Letter fallback on the shared avatar primitive — the
-                // same filled-circle grammar as the chat frontend's
-                // trigger. The old border-2 ring made the console's
-                // avatar read as a different control (user report
-                // 2026-09-12: 前后台头像不一致).
-                <span class="s-user-avatar">
-                  {props.username?.charAt(0).toUpperCase() || "?"}
-                </span>
-              )}
-            </button>
+            />
           )}
           {/* The reserved workspace-switcher slot (drawer face only).
               The chat header's left wing is avatar + ws-trigger button,
@@ -292,6 +281,13 @@ export const HkAdminHeader = defineComponent({
                   <HSpinner size="sm" />
                   <div class="s-user-header-email">{props.signingInLabel ?? t("hikari::adminHeader.signingIn", "Signing in…")}</div>
                 </div>
+              ) : slots.identity ? (
+                // Host-owned identity block (shell-unify wave 7): hosts
+                // with a richer identity vocabulary (localized group
+                // names, account-type badges, copy badges) inject their
+                // ONE component here; the built-in block below stays for
+                // hosts without one.
+                slots.identity()
               ) : (
                 // Identity block FIRST — avatar, nickname, login email,
                 // permission badges — the same grammar the chat
@@ -299,12 +295,12 @@ export const HkAdminHeader = defineComponent({
                 // s-user-header profile variant).
                 <div class="s-user-header s-user-header--profile">
                   <span class="s-user-avatar-chip" aria-hidden="true">
-                    {props.avatarUrl && !avatarFailed.value ? (
+                    {props.avatarUrl && !menuAvatarFailed.value ? (
                       <img
                         src={props.avatarUrl}
                         alt=""
                         class="s-user-avatar-img"
-                        onError={() => { avatarFailed.value = true; }}
+                        onError={() => { menuAvatarFailed.value = true; }}
                       />
                     ) : (
                       <span class="s-user-avatar">

package/src/components/HkAvatarButton.test.tsx

@@ -0,0 +1,155 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import { HkAvatarButton } from "./HkAvatarButton";
+import { HkAdminHeader } from "./HkAdminHeader";
+
+/**
+ * HkAvatarButton — the extracted avatar trigger (shell-unify wave 7).
+ *
+ * What this file pins:
+ * 1. The shared grammar: --space-28 round trigger class, the image with
+ *    letter fallback, and the failed-load latch that RESETS when the URL
+ *    changes (an account switch deserves a fresh attempt).
+ * 2. Attr fallthrough: a host's data-* attribute lands on the button so
+ *    host CSS keyed on it keeps working.
+ * 3. The aria bindings the menu engines read (haspopup/expanded).
+ * 4. HkAdminHeader renders it internally — and its new `identity` slot
+ *    replaces the built-in dropdown identity block while the pending
+ *    branch stays built-in.
+ *
+ * (Repo test convention: raw createApp + container queries, no
+ * @vue/test-utils dependency.)
+ */
+
+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;
+}
+
+afterEach(() => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+});
+
+function trigger(c: HTMLElement): HTMLButtonElement {
+  return c.querySelector("button.s-admin-header-avatar") as HTMLButtonElement;
+}
+
+describe("HkAvatarButton", () => {
+  it("renders the letter fallback when no URL is given", () => {
+    const c = mount(h(HkAvatarButton, { username: "yuzu", label: "Account menu" }));
+    const btn = trigger(c);
+    expect(btn).toBeTruthy();
+    expect(btn.getAttribute("aria-label")).toBe("Account menu");
+    expect(btn.querySelector(".s-user-avatar")?.textContent).toBe("Y");
+    expect(btn.querySelector("img")).toBeNull();
+  });
+
+  it("renders the image when a URL is given, with the username as alt", () => {
+    const c = mount(h(HkAvatarButton, { username: "yuzu", avatarUrl: "/a.png" }));
+    const img = trigger(c).querySelector("img.s-admin-header-avatar-img") as HTMLImageElement;
+    expect(img).toBeTruthy();
+    expect(img.getAttribute("src")).toBe("/a.png");
+    expect(img.getAttribute("alt")).toBe("yuzu");
+  });
+
+  it("falls back to the letter when the image fails, and a URL change on the SAME instance retries", async () => {
+    // Same-instance reactive update (R3 M1 on #909): remounting proves
+    // nothing (a fresh instance starts unlatched), so the host re-renders
+    // the button with a new URL while it stays mounted — the reset watch
+    // is what must bring the image back.
+    const url = ref("/a.png");
+    const Host = defineComponent({
+      setup: () => () => h(HkAvatarButton, { username: "yuzu", avatarUrl: url.value }),
+    });
+    const c = mount(h(Host));
+    const firstImg = trigger(c).querySelector("img") as HTMLImageElement;
+    firstImg.dispatchEvent(new Event("error"));
+    await nextTick();
+    expect(trigger(c).querySelector(".s-user-avatar")?.textContent).toBe("Y");
+    url.value = "/b.png";
+    await nextTick();
+    await nextTick();
+    const retryImg = trigger(c).querySelector("img") as HTMLImageElement | null;
+    expect(retryImg, "the latch reset — the new URL gets a fresh attempt").toBeTruthy();
+    expect(retryImg!.getAttribute("src")).toBe("/b.png");
+  });
+
+  it("forwards extra attrs onto the button (host data-* keys keep working)", () => {
+    const c = mount(h(HkAvatarButton, { username: "y", "data-image": "/a.png" } as never));
+    expect(trigger(c).getAttribute("data-image")).toBe("/a.png");
+  });
+
+  it("emits click and binds the menu aria pair", async () => {
+    let fired = 0;
+    const c = mount(h(HkAvatarButton, {
+      username: "yuzu",
+      label: "Account menu",
+      popup: "menu",
+      expanded: false,
+      onClick: () => { fired += 1; },
+    }));
+    const btn = trigger(c);
+    expect(btn.getAttribute("aria-haspopup")).toBe("menu");
+    expect(btn.getAttribute("aria-expanded")).toBe("false");
+    btn.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await nextTick();
+    expect(fired).toBe(1);
+  });
+});
+
+describe("HkAdminHeader × HkAvatarButton / identity slot", () => {
+  it("never renders aria-expanded when no expanded prop is given (drawer-mode contract)", () => {
+    // R2 S3-2: menu engines read this pair; a drawer-mode trigger has no
+    // open state, so the attribute must be ABSENT (not "false").
+    const c = mount(h(HkAvatarButton, { username: "y", label: "Open drawer", popup: "dialog" }));
+    expect(trigger(c).hasAttribute("aria-expanded")).toBe(false);
+  });
+
+  it("renders the shared trigger internally (behavior parity with the inline past)", () => {
+    const c = mount(h(HkAdminHeader, { username: "yuzu", title: "Dashboard" }));
+    const btn = trigger(c);
+    expect(btn).toBeTruthy();
+    expect(btn.querySelector(".s-user-avatar")?.textContent).toBe("Y");
+    // The wing keeps the ws-slot reservation contract on the drawer face.
+    expect(c.querySelector(".s-admin-header-user")).toBeTruthy();
+  });
+
+  it("an identity slot replaces the built-in dropdown block; the pending branch stays built-in", async () => {
+    const opened = h(HkAdminHeader, {
+      username: "yuzu",
+      userEmail: "y@zu",
+      title: "D",
+    }, {
+      identity: () => h("div", { class: "host-identity" }, "HOST-IDENTITY"),
+    });
+    // Open the dropdown by clicking the trigger.
+    const c = mount(opened);
+    trigger(c).dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await nextTick();
+    await nextTick();
+    const host = document.body.querySelector(".host-identity");
+    expect(host, "the host identity block renders in the open menu").toBeTruthy();
+    expect(document.body.querySelector(".s-user-header--profile")).toBeNull();
+
+    // Pending identity (no username/email): built-in spinner branch —
+    // the host slot is for identity PRESENTATION, not the fetch race.
+    const c2 = mount(h(HkAdminHeader, {
+      signingInLabel: "Signing in…",
+      onForceSignOut: () => {},
+    }));
+    trigger(c2).dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await nextTick();
+    await nextTick();
+    expect(document.body.querySelector(".s-user-header--pending")).toBeTruthy();
+  });
+});

package/src/components/HkAvatarButton.tsx

@@ -0,0 +1,77 @@
+import { defineComponent, ref, watch, type PropType } from "vue";
+
+/**
+ * HkAvatarButton — the avatar trigger button, ONE component for every
+ * face (extracted from HkAdminHeader, shell-unify wave 7, 2026-10-29).
+ *
+ * The button owns the shared avatar grammar: the `--space-28` round
+ * trigger, the image with its graceful letter fallback, and the
+ * failed-load latch that resets when the URL changes (an account switch
+ * or avatar upload deserves a fresh attempt). HkAdminHeader renders it
+ * internally; hosts with their own header chrome (the chat frontend's
+ * left wing) render it directly — the geometry has exactly one
+ * definition (`.s-admin-header-avatar` in admin-tokens) instead of one
+ * per face.
+ *
+ * Deliberately NO hover veil: every face's trigger opens the user MENU
+ * (the avatar edit lives one row down as the Camera item), so a camera
+ * overlay would promise click-to-change and lie (user report
+ * 2026-09-16).
+ *
+ * Extra attrs (data-image, testids, …) fall through to the button
+ * element (single root, default inheritAttrs) so host CSS keyed on them
+ * keeps working.
+ */
+export const HkAvatarButton = defineComponent({
+  name: "HkAvatarButton",
+  props: {
+    /** Avatar image URL; empty renders the letter fallback. */
+    avatarUrl: { type: String, default: "" },
+    /** Signed-in name: the fallback letter, and the image's alt. */
+    username: { type: String, default: "" },
+    /** Accessible label for the trigger (what it opens, not who it is). */
+    label: { type: String, default: undefined },
+    /** `aria-haspopup` value: "menu" (dropdown) or "dialog" (drawer). */
+    popup: { type: String as PropType<"menu" | "dialog" | undefined>, default: undefined },
+    /** `aria-expanded`; omit for drawer-mode triggers (no open state). */
+    expanded: { type: Boolean, default: undefined },
+  },
+  emits: {
+    click: (_e: MouseEvent) => true,
+  },
+  setup(props, { emit }) {
+    const avatarFailed = ref(false);
+    // A new URL deserves a fresh attempt (account switch, avatar upload)
+    // — the same self-heal the identity chips apply.
+    watch(
+      () => props.avatarUrl,
+      () => { avatarFailed.value = false; },
+    );
+
+    return () => (
+      <button
+        class="s-admin-header-avatar"
+        aria-label={props.label}
+        aria-haspopup={props.popup}
+        aria-expanded={props.expanded}
+        onClick={(e: MouseEvent) => { emit("click", e); }}
+      >
+        {props.avatarUrl && !avatarFailed.value ? (
+          <img
+            src={props.avatarUrl}
+            alt={props.username}
+            class="s-admin-header-avatar-img"
+            onError={() => { avatarFailed.value = true; }}
+          />
+        ) : (
+          // Letter fallback on the shared avatar primitive — the same
+          // filled-circle grammar on every face (user report 2026-09-12:
+          // 前后台头像不一致).
+          <span class="s-user-avatar">
+            {props.username?.charAt(0).toUpperCase() || "?"}
+          </span>
+        )}
+      </button>
+    );
+  },
+});

package/src/components/HkPopupSelect.mobile.test.tsx

@@ -31,6 +31,10 @@ afterEach(() => {
 
 const OPTIONS = [{ value: "a1", label: "Agent One" }];
 
+const DESCRIBED_OPTIONS = [
+  { value: "a1", label: "Agent One", description: "Personal · /srv/one" },
+];
+
 describe("HkPopupSelect (mobile sheet)", () => {
   it("hideLabel keeps the sheet's breadcrumb title on the field's name", async () => {
     // hideLabel only suppresses the INLINE caption; the sheet header
@@ -47,4 +51,18 @@ describe("HkPopupSelect (mobile sheet)", () => {
     expect(title, "the sheet renders a title band").toBeTruthy();
     expect(title!.textContent).toBe("Agent");
   });
+
+  it("described options keep their second line inside the sheet", async () => {
+    const c = mount(
+      h(HkPopupSelect, { modelValue: "", options: DESCRIBED_OPTIONS }),
+    );
+    const trigger = c.querySelector<HTMLButtonElement>(".hk-popup-select-trigger")!;
+    trigger.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await Promise.resolve();
+    await Promise.resolve();
+    const desc = document.body.querySelector(
+      ".hk-popover-panel .hk-popup-select-item-desc",
+    );
+    expect(desc?.textContent).toBe("Personal · /srv/one");
+  });
 });

package/src/components/HkPopupSelect.scss

@@ -149,6 +149,38 @@
   @include mi.item;
 }
 
+/* Two-line option rows, rendered ONLY for options that carry a
+ * description — a stock row keeps the bare label span (wrap allowed, no
+ * optical shift) so existing consumers see byte-identical geometry (R2).
+ * The body owns the row's flex growth so both lines ellipsis against the
+ * same edge. */
+.hk-popup-select-item-body {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+}
+
+.hk-popup-select-item-label {
+  @include mi.label;
+}
+
+/* The secondary line inherits the row color (hover/checked tints flow
+ * through) and steps down via opacity + the caption size, so it stays
+ * clearly meta against both the plain and the primary checked face. */
+.hk-popup-select-item-desc {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: var(--text-xs);
+  font-weight: 400;
+  color: inherit;
+  opacity: 0.62;
+  /* Same italic-overhang clipping room the label mixin reserves. */
+  padding-inline-end: var(--hk-menu-item-label-cushion);
+}
+
 /* Keyboard highlight face yields to checked/active; the hover face comes
  * from mi.item's own guarded :hover (identical values, higher specificity). */
 .hk-popup-select-item[data-highlighted]:not([data-checked]):not([data-active]) {

package/src/components/HkPopupSelect.test.tsx

@@ -81,4 +81,51 @@ describe("HkPopupSelect", () => {
     const c = mount(h(HkPopupSelect, { modelValue: "a1", label: "Agent", options: OPTIONS }));
     expect(c.querySelector(".hk-popup-select-trigger")!.getAttribute("aria-label")).toBeNull();
   });
+
+  it("an option description renders its own muted line under the label", async () => {
+    const c = mount(
+      h(HkPopupSelect, {
+        modelValue: "",
+        options: [{ value: "a1", label: "Agent One", description: "Personal · /srv/one" }],
+      }),
+    );
+    // Open the popout — option rows live in the anchored panel, which
+    // mounts across a microtask (the mobile sheet tests await the same).
+    c.querySelector<HTMLButtonElement>(".hk-popup-select-trigger")!
+      .dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await Promise.resolve();
+    await Promise.resolve();
+    const item = document.body.querySelector(".hk-popup-select-item")!;
+    expect(item.textContent).toContain("Agent One");
+    const desc = item.querySelector(".hk-popup-select-item-desc");
+    expect(desc?.textContent).toBe("Personal · /srv/one");
+    // The label sits in its own span so the two lines never merge.
+    expect(item.querySelector(".hk-popup-select-item-label")?.textContent).toBe("Agent One");
+  });
+
+  it("no description → the exact stock DOM: bare label span, no body wrapper", async () => {
+    const c = mount(h(HkPopupSelect, { modelValue: "", options: OPTIONS }));
+    c.querySelector<HTMLButtonElement>(".hk-popup-select-trigger")!
+      .dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await Promise.resolve();
+    await Promise.resolve();
+    const item = document.body.querySelector(".hk-popup-select-item")!;
+    // R2 contract: description-less rows render the pre-description DOM —
+    // no two-line anatomy, so no mi.label ellipsis/optical spec applies.
+    expect(item.querySelector(".hk-popup-select-item-body")).toBeNull();
+    expect(item.querySelector(".hk-popup-select-item-label")).toBeNull();
+    expect(item.querySelector("span")?.textContent).toBe("Agent One");
+  });
+
+  it("the collapsed trigger shows the label only, never the description", () => {
+    const c = mount(
+      h(HkPopupSelect, {
+        modelValue: "a1",
+        options: [{ value: "a1", label: "Agent One", description: "secret-meta" }],
+      }),
+    );
+    const value = c.querySelector(".hk-popup-select-value")!;
+    expect(value.textContent).toBe("Agent One");
+    expect(value.textContent).not.toContain("secret-meta");
+  });
 });

package/src/components/HkPopupSelect.tsx

@@ -9,6 +9,15 @@ import "./HkPopupSelect.scss";
 export interface HkPopupSelectOption {
   value: string;
   label: string;
+  /** Secondary line under the label, inside the same option row — a
+   * muted, single-line ellipsis strip for meta text (a row's owner,
+   * address, type) that must stay visible without leaking into the
+   * collapsed trigger, which keeps showing `label` alone. Absent → the
+   * row renders the EXACT stock DOM (bare label span, wrap allowed, no
+   * optical shift): the two-line anatomy exists only when there is a
+   * second line to show (R2: the mi.label ellipsis + 0.5px spec is a
+   * behavior change stock rows must not inherit silently). */
+  description?: string;
 }
 
 const activePopupId = ref<string | null>(null);
@@ -232,7 +241,16 @@ export default defineComponent({
                     onClick={() => select(opt.value)}
                     onPointerenter={() => { highlightedIndex.value = i; }}
                   >
-                    <span>{opt.label}</span>
+                    {opt.description ? (
+                      <span class="hk-popup-select-item-body">
+                        <span class="hk-popup-select-item-label">{opt.label}</span>
+                        <span class="hk-popup-select-item-desc">{opt.description}</span>
+                      </span>
+                    ) : (
+                      // Stock rows keep the exact pre-description DOM: no
+                      // body wrapper, no mi.label spec — the R2 contract.
+                      <span>{opt.label}</span>
+                    )}
                   </div>
                 ))}
           </HkScrollContainer>

package/src/index.ts

@@ -760,6 +760,7 @@ export { HkErrorReportingOverlay as HkErrorReportingOverlay } from "./errorRepor
 export { HkAdminShell as HkAdminShell } from "./components/HkAdminShell";
 export { HkFaceShell as HkFaceShell } from "./components/HkFaceShell";
 export { HkAdminHeader as HkAdminHeader } from "./components/HkAdminHeader";
+export { HkAvatarButton as HkAvatarButton } from "./components/HkAvatarButton";
 export { HkNavSidebar as HkNavSidebar } from "./components/HkNavSidebar";
 export { HkThemeToggle as HkThemeToggle } from "./components/HkThemeToggle";
 export { HkThemePanelContent as HkThemePanelContent } from "./components/HkThemePanelContent";