@celestia-island/hikari 0.55.321 → 0.55.322

package/package.json

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

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/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