@celestia-island/hikari 0.55.321 → 0.55.323

package/package.json

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

package/src/components/HkAvatar.scss

@@ -50,6 +50,34 @@
   font-weight: 600;
 }
 
+/* Optical vertical centering for the single-glyph fallback (2026-11-08
+ * user report: 头像首字母偏下). Flex centers the LINE box, but a capital
+ * glyph sits on the baseline — below the line box's geometric center on
+ * every UI font whose ascent exceeds its descent (Noto Sans CJK ≈0.065em,
+ * Windows Segoe UI ≈0.064em: ≈1px at md's 16px, visible in a circle).
+ * `text-box: trim-both cap alphabetic` trims the line box to
+ * [cap-top, baseline], so the centered box hugs the glyph ink — the
+ * avatar-initial case the property was designed for. Trim only reaches
+ * BLOCK-container line boxes (Chromium ignores it on a flex container's
+ * anonymous text block — verified headless), so under the guard the span
+ * swaps flex for block + align-content/text-align centering: same box,
+ * the trimmed line is centered on the block axis instead. Engines without
+ * text-box (pre-133 Chromium / pre-18.2 Safari / pre-154 Firefox) fail
+ * @supports and keep the flex anatomy unchanged — zero regression.
+ * CJK initials stay centered: the ideograph ink center lands on the
+ * [cap, baseline] band center (德 verified side by side, headless
+ * Chrome). Support note: the guard tests the `text-box` SHORTHAND,
+ * which Chromium parses from 133 (the longhands land in 128) — engines
+ * older than that fail @supports and keep the flex anatomy. */
+@supports (text-box: trim-both cap alphabetic) {
+  .hk-avatar-fallback {
+    display: block;
+    align-content: center;
+    text-align: center;
+    text-box: trim-both cap alphabetic;
+  }
+}
+
 [data-theme="dark"] .hk-avatar {
   background-color: var(--hi-surface);
   color: var(--hi-color-text-secondary, rgba(102,102,102,0.6));

package/src/components/HkAvatarFallback.centering.styles.test.ts

@@ -0,0 +1,147 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { compile } from "sass";
+import { describe, expect, it } from "vitest";
+
+/**
+ * Compiled-stylesheet guard for the avatar letter-fallback optical
+ * centering (2026-11-08 user report: 头像首字母偏下).
+ *
+ * Flex centering centers the LINE box, but a capital glyph sits on the
+ * baseline — below the line box's geometric center on every UI font
+ * whose ascent exceeds its descent (Noto Sans CJK ≈0.065em, Windows
+ * Segoe UI ≈0.064em). The fix trims the line box to [cap-top, baseline]
+ * with `text-box: trim-both cap alphabetic` under an @supports guard
+ * (trim only reaches BLOCK-container line boxes — Chromium ignores it on
+ * a flex container's anonymous text block, verified headless — so the
+ * height:100% fallbacks swap flex for block + align-content centering
+ * under the guard; the auto-height menu fallback only adds the trim).
+ *
+ * Vitest stubs CSS, so the runtime suite can never catch a lost rule;
+ * this guard pins the COMPILED sheets. All three sheets are mirrored
+ * verbatim into the Rust crate (vue-mirror drift tests), which catches
+ * one-sided edits — this file catches the block disappearing from BOTH
+ * copies at once. Supported engines: Chromium 133+, Safari 18.2+,
+ * Firefox 154+ (the guard tests the text-box shorthand; the longhands
+ * exist in Chromium from 128) — anything older fails @supports and keeps
+ * the flex anatomy (the pre-fix behavior), which is why the base rules
+ * below are also pinned to keep their flex centering.
+ */
+
+const componentDir = resolve(dirname(fileURLToPath(import.meta.url)));
+
+const SUPPORTS_PREAMBLE = "@supports (text-box: trim-both cap alphabetic)";
+
+const css = {
+  avatar: compile(resolve(componentDir, "HkAvatar.scss"), { style: "expanded" }).css,
+  menuIdentity: compile(resolve(componentDir, "HkMenuIdentityItem.scss"), { style: "expanded" }).css,
+  adminTokens: compile(resolve(componentDir, "../styles/admin-tokens.scss"), { style: "expanded" }).css,
+};
+
+/** The body of the FIRST @supports block with exactly `preamble`, brace-matched. */
+function supportsBody(sheetCss: string, preamble: string, label: string): string {
+  const start = sheetCss.indexOf(preamble);
+  expect(start, `${label}: ${preamble} block present in the compiled sheet`).toBeGreaterThanOrEqual(0);
+  let depth = 0;
+  let open = -1;
+  for (let at = start + preamble.length; at < sheetCss.length; at += 1) {
+    const ch = sheetCss[at];
+    if (ch === "{") {
+      if (open < 0) open = at;
+      depth += 1;
+    } else if (ch === "}") {
+      depth -= 1;
+      if (depth === 0) return sheetCss.slice(open + 1, at);
+    }
+  }
+  throw new Error(`${label}: unterminated @supports block`);
+}
+
+/** The prelude of the FIRST rule inside the first `@supports` block with
+ *  exactly `preamble` — the selector the guard actually targets. */
+function guardedSelector(sheetCss: string, preamble: string, label: string): string {
+  const body = supportsBody(sheetCss, preamble, label);
+  const open = body.indexOf("{");
+  return body.slice(0, open).trim();
+}
+
+/** The body of the top-level rule whose prelude is exactly `selector`. */
+function ruleFor(sheetCss: string, selector: string, label: string): string {
+  const needle = `${selector} {`;
+  const start = sheetCss.indexOf(needle);
+  expect(start, `${label}: ${selector} rule present in the compiled sheet`).toBeGreaterThanOrEqual(0);
+  const close = sheetCss.indexOf("}", start);
+  return sheetCss.slice(start, close + 1);
+}
+
+describe("avatar letter-fallback optical centering (text-box guard)", () => {
+  it("positive control: the extractor finds the known base anatomy", () => {
+    // If this stops matching, ruleFor/supportsBody are broken — fix the
+    // extractor, not the assertions below.
+    expect(ruleFor(css.avatar, ".hk-avatar", "avatar")).toContain("align-items: center");
+    expect(ruleFor(css.adminTokens, ".s-user-avatar", "admin-tokens")).toContain("display: flex");
+  });
+
+  it("hk-avatar-fallback: guard block swaps flex for block + centered trimmed line", () => {
+    const body = supportsBody(css.avatar, SUPPORTS_PREAMBLE, "avatar");
+    expect(guardedSelector(css.avatar, SUPPORTS_PREAMBLE, "avatar")).toBe(".hk-avatar-fallback");
+    expect(body).toContain("display: block");
+    expect(body).toContain("align-content: center");
+    expect(body).toContain("text-align: center");
+    expect(body).toContain("text-box: trim-both cap alphabetic");
+  });
+
+  it("hk-avatar-fallback: base rule keeps the flex anatomy (no-trim engines)", () => {
+    const rule = ruleFor(css.avatar, ".hk-avatar-fallback", "avatar");
+    expect(rule).toContain("display: flex");
+    expect(rule).toContain("align-items: center");
+    expect(rule).toContain("justify-content: center");
+  });
+
+  it("s-user-avatar: guard block swaps flex for block + centered trimmed line", () => {
+    const body = supportsBody(css.adminTokens, SUPPORTS_PREAMBLE, "admin-tokens");
+    expect(guardedSelector(css.adminTokens, SUPPORTS_PREAMBLE, "admin-tokens")).toBe(".s-user-avatar");
+    expect(body).toContain("display: block");
+    expect(body).toContain("align-content: center");
+    expect(body).toContain("text-align: center");
+    expect(body).toContain("text-box: trim-both cap alphabetic");
+  });
+
+  it("s-user-avatar: base rule keeps the flex anatomy (no-trim engines)", () => {
+    const rule = ruleFor(css.adminTokens, ".s-user-avatar", "admin-tokens");
+    expect(rule).toContain("display: flex");
+    expect(rule).toContain("align-items: center");
+    expect(rule).toContain("justify-content: center");
+  });
+
+  it("menu identity fallback: trim only — auto-height flex item needs no anatomy swap", () => {
+    const body = supportsBody(css.menuIdentity, SUPPORTS_PREAMBLE, "menu-identity");
+    expect(guardedSelector(css.menuIdentity, SUPPORTS_PREAMBLE, "menu-identity")).toBe(
+      ".hk-menu-identity-item__fallback",
+    );
+    expect(body).toContain("text-box: trim-both cap alphabetic");
+    expect(body).not.toContain("display:");
+  });
+});
+
+describe("avatar letter-fallback sheets stay mirrored", () => {
+  // The Rust crate compiles vendored copies of these sheets; the drift
+  // tests over there fail on one-sided edits. This re-reads the SOURCE
+  // files to pin the mirror files' presence next to the pinned behavior,
+  // so deleting the guard from BOTH copies cannot slip through silently
+  // (drift tests compare copies — they stay green when both sides lose
+  // the block together).
+  it("vendored mirror copies still carry the guard (double-sided delete tripwire)", () => {
+    const crateRoot = resolve(componentDir, "../../../components/src/styles/vue-mirror");
+    for (const rel of [
+      "components/HkAvatar.scss",
+      "components/HkMenuIdentityItem.scss",
+      "styles/admin-tokens.scss",
+    ]) {
+      const mirror = readFileSync(resolve(crateRoot, rel), "utf8");
+      expect(mirror, `${rel} mirror carries the guard`).toContain("text-box: trim-both cap alphabetic");
+    }
+  });
+});

package/src/components/HkCardList.tsx

@@ -1,4 +1,4 @@
-import { computed, defineComponent, h, onBeforeUnmount, onMounted, ref, type Component, type PropType } from "vue";
+import { computed, defineComponent, h, inject, onBeforeUnmount, onMounted, ref, type Component, type PropType } from "vue";
 import { MoreHorizontal } from "lucide-vue-next";
 
 import HkCard from "./HkCard";
@@ -9,6 +9,7 @@ import HkTooltip from "./HkTooltip";
 import { hasRenderedContent } from "../runtime/hasRenderedContent";
 import { useMediaQuery } from "../runtime/useMediaQuery";
 import type { StatTone } from "./HkStatCard";
+import { HK_SCROLL_PROGRESS_REGISTRAR, type HkScrollProgressHandle } from "./HkScrollProgress";
 import "./HkCardList.scss";
 
 /**
@@ -43,7 +44,43 @@ const renderedRows = hasRenderedContent;
  */
 export const HkCardList = defineComponent({
   name: "HkCardList",
-  setup(_props, { slots }) {
+  props: {
+    /** Authoritative row total the scroll-progress pill uses as its
+     *  denominator (the server count behind a windowed/infinite list).
+     *  Forwarded to the nearest enclosing HkScrollContainer with
+     *  `scrollProgress` on, exactly like HkAdminTablePage's `total`.
+     *  Omitted: the pill falls back to counting the delivered DOM rows
+     *  (right for fully-delivered lists, drifting low for windowed
+     *  ones — pass the server count there). */
+    total: { type: Number, default: undefined },
+  },
+  setup(props, { slots }) {
+    // Scroll-progress registration (the HkTable precedent): the NEAREST
+    // enclosing HkScrollContainer with `scrollProgress` on provides the
+    // registrar — provide/inject scoping resolves the admin shell's
+    // viewport for console pages and keeps a list registered against an
+    // inner container out of the shell. The handle hands the pill the
+    // list element as the row root, the `total` prop live, and the
+    // rendered HkListRow elements as the rows (a card list's rows ARE
+    // its data rows — no section-band caveat).
+    const listRef = ref<HTMLElement | null>(null);
+    const progressRegistrar = inject(HK_SCROLL_PROGRESS_REGISTRAR, null);
+    const progressHandle: HkScrollProgressHandle = {
+      getRoot: () => listRef.value,
+      getTotal: () => props.total,
+      getRows: () =>
+        listRef.value
+          ? Array.from(listRef.value.children).filter((el) =>
+              el.classList.contains("hk-list-row"),
+            )
+          : [],
+    };
+    onMounted(() => {
+      progressRegistrar?.register(progressHandle);
+    });
+    onBeforeUnmount(() => {
+      progressRegistrar?.unregister(progressHandle);
+    });
     return () => {
       const rows = slots.default?.();
       return (
@@ -51,7 +88,7 @@ export const HkCardList = defineComponent({
           {slots.empty && !renderedRows(rows) ? (
             slots.empty()
           ) : (
-            <div class="hk-card-list" role="list">
+            <div class="hk-card-list" role="list" ref={listRef}>
               {rows}
             </div>
           )}

package/src/components/HkMenuIdentityItem.scss

@@ -42,6 +42,16 @@
   color: rgb(var(--color-primary) / 70%);
 }
 
+/* The fallback span is a blockified flex item with auto height, so flex
+   centering of the trimmed box is exact — no anatomy swap needed here
+   (the height:100% fallbacks swap flex for block under the same guard;
+   full rationale: HkAvatar.scss). */
+@supports (text-box: trim-both cap alphabetic) {
+  .hk-menu-identity-item__fallback {
+    text-box: trim-both cap alphabetic;
+  }
+}
+
 .hk-menu-identity-item__text {
   display: flex;
   flex-direction: column;

package/src/components/HkScrollProgress.test.tsx

@@ -12,7 +12,12 @@ import { createApp, defineComponent, h, inject, nextTick, onMounted, onUnmounted
 import HkScrollContainer from "./HkScrollContainer";
 import { HkAdminTablePage } from "./HkAdminTablePage";
 import HTable from "./HkTable";
-import { HK_SCROLL_PROGRESS_REGISTRAR, type HkScrollProgressRegistrar } from "./HkScrollProgress";
+import { HkCardList, HkListRow } from "./HkCardList";
+import {
+  HK_SCROLL_PROGRESS_REGISTRAR,
+  type HkScrollProgressHandle,
+  type HkScrollProgressRegistrar,
+} from "./HkScrollProgress";
 
 const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
 const rects: Array<ReturnType<typeof vi.spyOn>> = [];
@@ -485,6 +490,149 @@ describe("HkAdminTablePage scroll-progress registration", () => {
 });
 
 
+describe("HkCardList scroll-progress registration", () => {
+  it("registers its list root, rows and total with the provided registrar", async () => {
+    const registered: Array<{ getRoot: () => HTMLElement | null; getTotal: () => number | undefined; getRows?: () => readonly Element[] | undefined }> = [];
+    const unregistered: unknown[] = [];
+    const registrar: HkScrollProgressRegistrar = {
+      register: (handle) => registered.push(handle),
+      unregister: (handle) => unregistered.push(handle),
+    };
+    const Provider = defineComponent({
+      setup() {
+        provide(HK_SCROLL_PROGRESS_REGISTRAR, registrar);
+        return () =>
+          h(HkCardList, { total: 42 }, {
+            default: () => [
+              h(HkListRow, { key: "a", title: "a" }),
+              h(HkListRow, { key: "b", title: "b" }),
+              // A non-row child (a bare div a host slipped in) must not
+              // count as a data row — getRows filters to .hk-list-row.
+              h("div", { key: "spacer", class: "h-2" }),
+            ],
+          });
+      },
+    });
+    const container = mountTree(h(Provider));
+    expect(registered.length).toBe(1);
+    expect(registered[0].getTotal()).toBe(42);
+    // The list element is the row root — the element containing the rows.
+    const root = registered[0].getRoot()!;
+    expect(root).not.toBeNull();
+    expect(root.classList.contains("hk-card-list")).toBe(true);
+    expect(root.querySelectorAll(".hk-list-row")).toHaveLength(2);
+    // getRows hands the pill the HkListRow children only (the spacer
+    // div is excluded) — the section-band precision HkTable carries,
+    // mirrored for card lists.
+    const rows = registered[0].getRows!();
+    expect(rows).toBeDefined();
+    expect(rows!).toHaveLength(2);
+    expect(rows!.every((el) => el.classList.contains("hk-list-row"))).toBe(true);
+
+    // Unmount unregisters the SAME handle.
+    mounts[0].app.unmount();
+    expect(unregistered.length).toBe(1);
+    expect(unregistered[0]).toBe(registered[0]);
+  });
+
+  it("keeps the handle honest across the empty-slot lifecycle (rows→empty→rows)", async () => {
+    // The list element unmounts when the empty slot renders: the handle
+    // must read a NULL root (the pill's hidden precondition — never a
+    // stale detached element), and a re-render must recover a fresh
+    // connected list under the SAME handle.
+    const registered: Array<HkScrollProgressHandle> = [];
+    const registrar: HkScrollProgressRegistrar = {
+      register: (handle) => registered.push(handle),
+      unregister: () => {},
+    };
+    const hasRows = ref(true);
+    const Provider = defineComponent({
+      setup() {
+        provide(HK_SCROLL_PROGRESS_REGISTRAR, registrar);
+        return () =>
+          h(HkCardList, { total: 9 }, {
+            default: () => (hasRows.value ? [h(HkListRow, { key: "a", title: "a" })] : []),
+            empty: () => h("div", {}, "empty"),
+          });
+      },
+    });
+    mountTree(h(Provider));
+    const handle = registered[0]!;
+    expect(handle.getRoot()).not.toBeNull();
+    expect(handle.getRows!()).toHaveLength(1);
+
+    // Rows → empty: the ref clears with the element (no stale root).
+    hasRows.value = false;
+    await nextTick();
+    expect(handle.getRoot()).toBeNull();
+    expect(handle.getRows!()).toHaveLength(0);
+    expect(handle.getTotal()).toBe(9); // the prop stays live
+
+    // Empty → rows: the same handle recovers a fresh connected list.
+    hasRows.value = true;
+    await nextTick();
+    const root = handle.getRoot()!;
+    expect(root).not.toBeNull();
+    expect(root.isConnected).toBe(true);
+    expect(root.classList.contains("hk-card-list")).toBe(true);
+    expect(handle.getRows!()).toHaveLength(1);
+  });
+
+  it("renders its rows into the shell viewport's pill denominator end-to-end", async () => {
+    // The real provide/inject path: a card list inside a
+    // scrollProgress-on container registers itself, and the pill's
+    // denominator is the list's declared total (not the delivered rows)
+    // — the same end-to-end contract the table page carries.
+    const list = h(HkCardList, {
+      total: 500,
+    }, {
+      default: () => Array.from({ length: 30 }, (_, i) =>
+        h(HkListRow, { key: i, title: `r${i}` })),
+    });
+    const instance = ref<{ refresh: () => void } | null>(null);
+    let scrollTop = 0;
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkScrollContainer, { ref: instance as never, scrollProgress: true }, { default: () => list });
+      },
+    });
+    const container = mountTree(h(Wrapper));
+    const viewport = container.querySelector<HTMLElement>(".hk-scroll-container-viewport")!;
+    Object.defineProperties(viewport, {
+      scrollHeight: { configurable: true, get: () => 4000 },
+      clientHeight: { configurable: true, get: () => 400 },
+      scrollWidth: { configurable: true, get: () => 300 },
+      clientWidth: { configurable: true, get: () => 300 },
+      scrollLeft: { configurable: true, get: () => 0 },
+      scrollTop: { configurable: true, get: () => scrollTop },
+    });
+    rects.push(vi.spyOn(viewport, "getBoundingClientRect").mockReturnValue({
+      left: 0, top: 0, right: 300, bottom: 400, width: 300, height: 400, x: 0, y: 0,
+    } as DOMRect));
+    const listRoot = container.querySelector<HTMLElement>(".hk-card-list")!;
+    expect(listRoot).not.toBeNull();
+    rects.push(vi.spyOn(listRoot, "getBoundingClientRect").mockReturnValue({
+      left: 0, top: -200, right: 300, bottom: 3800, width: 300, height: 4000, x: 0, y: -200,
+    } as DOMRect));
+    container.querySelectorAll<HTMLElement>(".hk-list-row").forEach((row, i) => {
+      const top = i * 40 - 200;
+      rects.push(vi.spyOn(row, "getBoundingClientRect").mockReturnValue({
+        left: 0, top, right: 300, bottom: top + 40, width: 300, height: 40, x: 0, y: top,
+      } as DOMRect));
+    });
+    scrollTop = 200;
+    instance.value!.refresh();
+    await nextTick();
+    const pill = container.querySelector<HTMLElement>(".hk-scroll-progress-pill");
+    expect(pill).not.toBeNull();
+    // First visible row #6 over the DECLARED total — the delivered 30
+    // rows never override the list's server count.
+    expect(pill!.textContent).toBe("6 / 500");
+  });
+});
+
+
 // ── SCSS contract (textual pins — happy-dom does not lay out) ────────
 // The house style pins sheet claims with readFileSync probes
 // (HkButton.test.tsx icon-only precedent): these guard the paint

package/src/styles/admin-tokens.scss

@@ -897,6 +897,22 @@
   letter-spacing: 0.02em;
 }
 
+/* Optical vertical centering for the letter fallback (2026-11-08 user
+   report: 头像首字母偏下) — same mechanism and guard as HkAvatar.scss:
+   flex centers the line box while the capital sits on the baseline
+   (≈0.065em low on CJK-metric fonts), and trim only reaches block
+   containers, so under @supports the span swaps flex for
+   block + align-content/text-align centering; unsupported engines keep
+   the flex anatomy unchanged. */
+@supports (text-box: trim-both cap alphabetic) {
+  .s-user-avatar {
+    display: block;
+    align-content: center;
+    text-align: center;
+    text-box: trim-both cap alphabetic;
+  }
+}
+
 .s-user-avatar-img {
   width: 100%;
   height: 100%;