@celestia-island/hikari 0.55.324 → 0.55.326

package/package.json

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

package/src/components/HkAdminShell.test.tsx

@@ -81,7 +81,14 @@ const setWidth = (w: number) => {
 function paddingInner(container: HTMLElement): HTMLElement | null | undefined {
   const viewport = container.querySelector(".hk-scroll-container-viewport")
     ?? container.querySelector(".hk-scroll-container");
-  return viewport?.firstElementChild as HTMLElement | null | undefined;
+  // The shell's fallback scroll-progress dock (2026-11-09) wraps the
+  // content with a display:contents scope — descend through it, the
+  // padding wrapper is still the viewport's only layout box.
+  let inner = viewport?.firstElementChild as HTMLElement | null | undefined;
+  if (inner?.classList.contains("hk-scroll-progress-dock-scope")) {
+    inner = inner.firstElementChild as HTMLElement;
+  }
+  return inner;
 }
 
 function mobileInnerPadding(container: HTMLElement): string {
@@ -240,10 +247,9 @@ describe("HkAdminShell", () => {
       { header: () => null, sidebar: NAV, content: CONTENT },
     ));
     // The padded inner wrapper exists INSIDE the scroll viewport (not as
-    // padding on the container itself).
-    const viewport = c.querySelector(".hk-scroll-container-viewport")
-      ?? c.querySelector(".hk-scroll-container");
-    const inner = viewport?.firstElementChild as HTMLElement | null | undefined;
+    // padding on the container itself) — behind the fallback dock's
+    // display:contents scope (see paddingInner).
+    const inner = paddingInner(c);
     expect(inner).toBeTruthy();
     expect(inner?.style.padding).toBe("2rem");
   });

package/src/components/HkAdminTablePage.tsx

@@ -1,6 +1,7 @@
 import { defineComponent, type Component, type PropType } from "vue";
 import { HAlert, HCard, HEmptyState, HSpinner, HTable, useI18n } from "@celestia-island/hikari";
 import HkCrossfade from "./HkCrossfade";
+import HkScrollProgressDock from "./HkScrollProgressDock";
 import { HkPageHeader } from "./HkPageHeader";
 import type { HkRowManageGate } from "./HkTable";
 
@@ -80,6 +81,24 @@ export const HkAdminTablePage = defineComponent({
      *  zero so a fresh or empty list shows no "共 0 条" flash. Pages
      *  that render their own count elsewhere set this false. */
     countReadout: { type: Boolean, default: true },
+    /** The page's own scroll-progress DOCK (user direction 2026-11-09:
+     *  the list large-component uses the dock itself). DEFAULT ON — the
+     *  page mounts an HkScrollProgressDock around the body crossfade so
+     *  the table (or a body-slot roster) self-registers against it and
+     *  the pill floats over the scrolling viewport; the crossfade's
+     *  generation swaps happen INSIDE the dock, so the registration
+     *  survives every exchange. A page under a shell fallback dock has
+     *  its OWN dock stand down automatically (the nested-dock rule
+     *  serves the outermost enabled dock — the fallback keeps the
+     *  pill); set `false` to demote the page — lists then fall through
+     *  to the nearest enabled dock above, if any. Layering: the shell
+     *  master switch (HkFaceShell `scrollProgress`) > this prop > the
+     *  dock's own `disabled`. Like every dock gate, the layering is
+     *  RESOLVED
+     *  ONCE at the dock's setup — hosts pass these statically, and a
+     *  runtime flip needs a remount (the HkScrollContainer prop
+     *  precedent). */
+    progressDock: { type: Boolean, default: true },
   },
   emits: {
     reorder: (_fromIndex: number, _toIndex: number) => true,
@@ -151,48 +170,55 @@ export const HkAdminTablePage = defineComponent({
               every host dissolves between them instead of popping. The
               key collapses loading-vs-empty into one "placeholder"
               generation: spinner → empty is a data arrival, not a slot
-              identity change worth animating. */}
-          <HkCrossfade
-            swapKey={
-              props.error ? "error"
-                : props.loading && !props.rows.length ? "placeholder"
-                  : !props.rows.length ? "placeholder"
-                    : "content"
-            }
-          >
-            {props.error ? (
-              <HAlert message={props.error} />
-            ) : props.loading && !props.rows.length ? (
-              <HSpinner center />
-            ) : !props.rows.length ? (
-              <HEmptyState
-                boxed
-                title={emptyTitle}
-                description={props.emptyDescription}
-              >
-                {emptySlots}
-              </HEmptyState>
-            ) : slots.body ? (
-              <div class="hk-admin-table-page-body">{slots.body()}</div>
-            ) : (
-              <HCard padded={false}>
-                <HTable
-                  columns={props.columns}
-                  rows={props.rows}
-                  rowKey={props.rowKey}
-                  total={props.total}
-                  draggable={props.draggable}
-                  manageable={props.manageable}
-                  onReorder={(from: number, to: number) => emit("reorder", from, to)}
-                  onManage={(row: Record<string, unknown>, opener: HTMLElement) =>
-                    emit("manage", row, opener)
-                  }
+              identity change worth animating.
+              The whole exchange rides INSIDE this page's scroll-progress
+              dock (default on; `progressDock:false` demotes to a bare
+              passthrough): the dock must wrap the CROSSFADE, not sit in
+              a generation — a generation-scoped dock would unmount with
+              every swap and drop the registration. */}
+          <HkScrollProgressDock disabled={!props.progressDock}>
+            <HkCrossfade
+              swapKey={
+                props.error ? "error"
+                  : props.loading && !props.rows.length ? "placeholder"
+                    : !props.rows.length ? "placeholder"
+                      : "content"
+              }
+            >
+              {props.error ? (
+                <HAlert message={props.error} />
+              ) : props.loading && !props.rows.length ? (
+                <HSpinner center />
+              ) : !props.rows.length ? (
+                <HEmptyState
+                  boxed
+                  title={emptyTitle}
+                  description={props.emptyDescription}
                 >
-                  {slots}
-                </HTable>
-              </HCard>
-            )}
-          </HkCrossfade>
+                  {emptySlots}
+                </HEmptyState>
+              ) : slots.body ? (
+                <div class="hk-admin-table-page-body">{slots.body()}</div>
+              ) : (
+                <HCard padded={false}>
+                  <HTable
+                    columns={props.columns}
+                    rows={props.rows}
+                    rowKey={props.rowKey}
+                    total={props.total}
+                    draggable={props.draggable}
+                    manageable={props.manageable}
+                    onReorder={(from: number, to: number) => emit("reorder", from, to)}
+                    onManage={(row: Record<string, unknown>, opener: HTMLElement) =>
+                      emit("manage", row, opener)
+                    }
+                  >
+                    {slots}
+                  </HTable>
+                </HCard>
+              )}
+            </HkCrossfade>
+          </HkScrollProgressDock>
           {slots["create-modal"]?.()}
           {slots["edit-modal"]?.()}
         </div>

package/src/components/HkCardList.tsx

@@ -9,7 +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 { HK_SCROLL_PROGRESS_REGISTRAR, type HkScrollProgressHandle } from "./HkScrollProgressDock";
 import "./HkCardList.scss";
 
 /**
@@ -47,22 +47,22 @@ export const HkCardList = defineComponent({
   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). */
+     *  Forwarded to the nearest enclosing enabled HkScrollProgressDock,
+     *  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).
+    // enclosing ENABLED HkScrollProgressDock provides the registrar —
+    // provide/inject scoping resolves the shell viewport for console
+    // pages and keeps a list registered against an inner dock 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 = {

package/src/components/HkFaceShell.test.tsx

@@ -2,7 +2,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { createApp, h } from "vue";
+import { createApp, defineComponent, h, inject } from "vue";
 
 // HDrawer teleports and animates; replace it with an inline passthrough
 // (same stub shape as HkAdminShell.test.tsx) so the shell contract is
@@ -36,6 +36,7 @@ vi.mock("@celestia-island/hikari", async (importOriginal) => {
 
 import { HkFaceShell } from "./HkFaceShell";
 import { HkAdminShell } from "./HkAdminShell";
+import { HK_SCROLL_PROGRESS_ALLOWED } from "./HkScrollProgressDock";
 
 /**
  * HkFaceShell — the generalized face shell extracted from HkAdminShell
@@ -96,6 +97,11 @@ describe("HkFaceShell stage mode", () => {
     // The document host is GONE — that is the stage contract.
     expect(c.querySelector(".hk-scroll-container")).toBeNull();
     expect(c.querySelector(".hk-scroll-container-viewport")).toBeNull();
+    // …and so is the fallback scroll-progress dock (document-mode only —
+    // a stage face owns its own geometry, so the shell mounts no dock
+    // scope and provides no pill chrome at all).
+    expect(c.querySelector(".hk-scroll-progress-dock-scope")).toBeNull();
+    expect(c.querySelector(".hk-scroll-progress-dock")).toBeNull();
     // No padding wrapper anywhere: the content slot's first element IS
     // the main region's child (contentPadding is a document-mode prop).
     expect(main!.firstElementChild?.textContent).toBe("CONTENT");
@@ -158,12 +164,57 @@ describe("HkFaceShell document mode (the default)", () => {
     expect(c.querySelector(".hk-scroll-container")).toBeTruthy();
     const viewport = c.querySelector(".hk-scroll-container-viewport")
       ?? c.querySelector(".hk-scroll-container");
-    const inner = viewport!.firstElementChild as HTMLElement;
+    // The shell's fallback scroll-progress dock wraps the content
+    // (2026-11-09): its scope is display: contents, so the padding
+    // wrapper below it is STILL the viewport's only layout box.
+    const scope = viewport!.firstElementChild as HTMLElement;
+    expect(scope.classList.contains("hk-scroll-progress-dock-scope")).toBe(true);
+    const inner = scope.firstElementChild as HTMLElement;
     expect(inner.style.padding).toBe("2rem");
     expect(inner.textContent).toContain("CONTENT");
   });
 });
 
+describe("HkFaceShell scroll-progress dock master switch", () => {
+  const makeProbe = (box: { seen: unknown }) =>
+    defineComponent({
+      setup() {
+        box.seen = inject(HK_SCROLL_PROGRESS_ALLOWED, null);
+        return () => h("main", null, "CONTENT");
+      },
+    });
+
+  it("provides ALLOWED=true by default and mounts the fallback dock", () => {
+    const box: { seen: unknown } = { seen: "unset" };
+    const c = mount(h(HkFaceShell, {
+      navTitle: "Navigation",
+    }, {
+      header: () => null,
+      content: () => h(makeProbe(box)),
+    }));
+    // The `scrollProgress` prop (default true) is the face-level lever
+    // over every dock in the subtree.
+    expect(box.seen).toBe(true);
+    expect(c.querySelector(".hk-scroll-progress-dock-scope")).not.toBeNull();
+  });
+
+  it("scrollProgress:false closes the switch and stands the fallback dock down", () => {
+    const box: { seen: unknown } = { seen: "unset" };
+    const c = mount(h(HkFaceShell, {
+      navTitle: "Navigation",
+      scrollProgress: false,
+    }, {
+      header: () => null,
+      content: () => h(makeProbe(box)),
+    }));
+    expect(box.seen).toBe(false);
+    // Fully lazy: no scope, no pill anywhere in the shell.
+    expect(c.querySelector(".hk-scroll-progress-dock-scope")).toBeNull();
+    expect(c.querySelector(".hk-scroll-progress-dock")).toBeNull();
+    expect(c.querySelector(".hk-scroll-container-viewport")!.textContent).toContain("CONTENT");
+  });
+});
+
 describe("the extraction boundary: the action-bar channel", () => {
   it("HkFaceShell's header slot carries no actions param (no bar provided)", () => {
     const seen: Array<Record<string, unknown>> = [];

package/src/components/HkFaceShell.tsx

@@ -1,10 +1,11 @@
-import { computed, defineComponent, ref, watch, type PropType } from "vue";
+import { computed, defineComponent, provide, ref, watch, type PropType } from "vue";
 import { HkCrossfade, HDrawer, HScrollContainer, useBreakpoint } from "@celestia-island/hikari";
 import { useI18n } from "../i18n/context";
 import { useSidebarRail } from "../composables/useSidebarRail";
 import { provideMenuGroupState } from "../composables/useMenuGroupState";
 import HkSidebarRailSwap from "./HkSidebarRailSwap";
 import HkSidebarRailToggle, { isPointerOverRailToggle } from "./HkSidebarRailToggle";
+import HkScrollProgressDock, { HK_SCROLL_PROGRESS_ALLOWED } from "./HkScrollProgressDock";
 
 /** CSS-wide keywords. A shorthand rebuilt from one of them is NOT a
  * padding (`inherit 0 inherit` is rejected by every engine, measured in
@@ -236,13 +237,19 @@ export const HkFaceShell = defineComponent({
      *  `stage` renders the content bare — the face owns scrolling,
      *  canvases and floating layers. */
     contentMode: { type: String as PropType<"document" | "stage">, default: "document" },
-    /** Scroll-progress pill on the document viewport (2026-11): while a
-     *  registered list scrolls, the shell floats an "xx / xx" counter
-     *  near the viewport's bottom-center (HkScrollContainer
-     *  `scrollProgress`; lists register themselves — HkAdminTablePage
-     *  does it for every admin list — so hosts inherit the affordance
-     *  with zero per-page work). Default ON: the shell is the
-     *  system-wide default-on point. Pass `false` to run the face bare. */
+    /** Scroll-progress DOCK master switch (2026-11-09): the shell-level
+     *  on/off lever for every HkScrollProgressDock in the face —
+     *  provided to the subtree as `HK_SCROLL_PROGRESS_ALLOWED`, so a
+     *  `false` here turns a page's own dock lazy too (the shell >
+     *  page-level `progressDock` > the dock's own `disabled`). While on
+     *  (the default), the shell ALSO mounts its own fallback dock
+     *  around the document content: unmigrated pages and bare lists
+     *  still float the pill with zero per-page work; a standard page's
+     *  own dock nests INSIDE the fallback and is the side that stands
+     *  down (the nested-dock rule serves the outermost enabled dock —
+     *  one pill, never two). Lists register themselves (HkTable /
+     *  HkCardList / HkAdminTablePage do it built-in). Pass `false` to
+     *  run the face bare. */
     scrollProgress: { type: Boolean, default: true },
     /** Content-area padding (inside the scroll viewport). Document mode
      *  only — a stage face owns its own geometry. Padding is applied to
@@ -302,6 +309,12 @@ export const HkFaceShell = defineComponent({
     // same one as the desktop sidebar.
     provideMenuGroupState();
 
+    // ── scroll-progress dock master switch ───────────────────────────
+    // The `scrollProgress` prop is now the FACE-LEVEL lever over every
+    // dock in the subtree (see the prop doc): provided once, statically
+    // — hosts pass it statically, the HkScrollContainer prop precedent.
+    provide(HK_SCROLL_PROGRESS_ALLOWED, props.scrollProgress);
+
     // ── desktop icon rail + hover peek (sidebarCollapsible) ──────────
     // SEMI-CONTROLLED rail state: a local session-only ref is the live
     // state, so the toggle works with NO channel bound at all (the
@@ -545,11 +558,22 @@ export const HkFaceShell = defineComponent({
             {props.contentMode === "stage" ? (
               renderContentStage()
             ) : (
-              <HScrollContainer class="s-admin-shell-scroll" scrollProgress={props.scrollProgress}>
-                {/* Padding lives INSIDE the scroll viewport (an inner
-                    wrapper) so card box-shadows are not clipped at the
-                    viewport edges. */}
-                <div style={contentStyle.value}>{renderContentStage()}</div>
+              <HScrollContainer class="s-admin-shell-scroll">
+                {/* The shell's FALLBACK dock (2026-11-09): wraps the
+                    padded content so unmigrated pages and bare lists
+                    still float the pill. A page that mounts its own dock
+                    (HkAdminTablePage's, by default) nests INSIDE this
+                    one and is the side that stands down — the nested
+                    -dock rule serves the OUTERMOST enabled dock, so the
+                    fallback keeps sensing and one pill paints, never
+                    two. The scope is display: contents — the padding
+                    wrapper below stays the viewport's only layout box. */}
+                <HkScrollProgressDock>
+                  {/* Padding lives INSIDE the scroll viewport (an inner
+                      wrapper) so card box-shadows are not clipped at the
+                      viewport edges. */}
+                  <div style={contentStyle.value}>{renderContentStage()}</div>
+                </HkScrollProgressDock>
               </HScrollContainer>
             )}
           </main>

package/src/components/HkScrollContainer.test.ts

@@ -1,7 +1,8 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { createApp, defineComponent, h, nextTick, reactive, ref } from "vue";
+import { createApp, defineComponent, h, inject, nextTick, reactive, ref } from "vue";
 
 import HkScrollContainer from "./HkScrollContainer";
+import { HK_SCROLL_PROGRESS_HOST, HK_SCROLL_PROGRESS_REGISTRAR, HK_SCROLL_PROGRESS_VIEWPORT } from "./HkScrollProgressDock";
 import type { OverlayScrollbarMarker } from "../composables/useOverlayScrollbar";
 
 interface Mounted {
@@ -648,3 +649,47 @@ describe("HkScrollContainer change-mark rail", () => {
     expect(track?.querySelectorAll(".hk-scrollbar-marker").length ?? 0).toBe(0);
   });
 });
+
+describe("HkScrollContainer dock publication (2026-11-09)", () => {
+  it("publishes viewport + host refs and NO scroll-progress registrar", () => {
+    // The pill feature moved into the standalone HkScrollProgressDock:
+    // the container's only remaining role is publishing the two refs
+    // any dock in its slot injects (the one-way key dependency). Pin
+    // BOTH directions with probe injects: the dock keys resolve, the
+    // retired registrar key does not — a container that regrows the old
+    // provide (or drops the new ones) turns this red.
+    const seen = {
+      viewport: "unset" as unknown,
+      host: "unset" as unknown,
+      registrar: "unset" as unknown,
+    };
+    const Probe = defineComponent({
+      setup() {
+        seen.viewport = inject(HK_SCROLL_PROGRESS_VIEWPORT, null);
+        seen.host = inject(HK_SCROLL_PROGRESS_HOST, null);
+        seen.registrar = inject(HK_SCROLL_PROGRESS_REGISTRAR, null);
+        return () => h("div", "probe");
+      },
+    });
+    const host = document.createElement("div");
+    document.body.appendChild(host);
+    containers.push(host);
+    const app = createApp({ render: () => h(HkScrollContainer, {}, { default: () => h(Probe) }) });
+    mounts.push(app);
+    app.mount(host);
+    const root = host.querySelector<HTMLElement>(".hk-scroll-container");
+    const viewport = host.querySelector<HTMLElement>(".hk-scroll-container-viewport");
+    expect(root).not.toBeNull();
+    expect(viewport).not.toBeNull();
+    expect(seen.registrar).toBeNull();
+    // The refs are the shared `Ref<HTMLElement | null>` contract, and
+    // by probe time the template refs have landed: they point at THIS
+    // container's viewport / host elements.
+    const viewportRef = seen.viewport as { value: unknown } | null;
+    const hostRef = seen.host as { value: unknown } | null;
+    expect(viewportRef).not.toBeNull();
+    expect(hostRef).not.toBeNull();
+    expect(viewportRef!.value).toBe(viewport);
+    expect(hostRef!.value).toBe(root);
+  });
+});