@celestia-island/hikari 0.55.202 → 0.55.203

package/package.json

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

package/src/animation/registerAnimations.ts

@@ -66,6 +66,9 @@ export function isCssAnimationsEnabled(): boolean {
 registerCssAnimation("s-nav-item-badge-pulse", { infinite: true });
 // styles/admin-tokens.scss — auth card entrance (plays once).
 registerCssAnimation("s-auth-card-in");
+// HkPaneHolder's reveal (opacity-only, one shot) — the keep-mounted pane
+// slot's entry, the dissolve-family language for persistent panes.
+registerCssAnimation("hk-pane-holder-in");
 // styles/admin-tokens.scss — status-bar recovery flash (plays once):
 // the traffic light's green background blink when a dropped connection
 // comes back.

package/src/components/HkAdminShell.tsx

@@ -1,5 +1,5 @@
-import { computed, defineComponent, ref } from "vue";
-import { HDrawer, HScrollContainer, useBreakpoint } from "@celestia-island/hikari";
+import { computed, defineComponent, ref, type PropType } from "vue";
+import { HkCrossfade, HDrawer, HScrollContainer, useBreakpoint } from "@celestia-island/hikari";
 import { provideActionBar } from "../composables/useActionBar";
 import { useI18n } from "../i18n/context";
 
@@ -162,6 +162,13 @@ export const HkAdminShell = defineComponent({
      *  verbatim at every width unless the page opts into
      *  `contentBleedOnMobile`. */
     contentPadding: { type: String, default: "1.5rem" },
+    /** Identity of the content page on stage (task-4, 2026-10-24):
+     *  pass the current view/route key and the content area swaps pages
+     *  through the family crossfade — the library owns the page-slot
+     *  mechanism instead of every host hand-wrapping it. Omitted (or
+     *  null) renders the slot bare: canvas-like hosts that mount one
+     *  persistent stage opt out. */
+    contentKey: { type: [String, Number] as PropType<string | number | null>, default: null },
     /** Whether the content on screen is a CANVAS — a 2D board or the 3D
      *  scene — that must span the full phone width. OPT-IN, declared by
      *  the page that renders the canvas (2026-10-04 user direction: the
@@ -257,7 +264,15 @@ export const HkAdminShell = defineComponent({
               {/* Padding lives INSIDE the scroll viewport (an inner
                   wrapper) so card box-shadows are not clipped at the
                   viewport edges. */}
-              <div style={contentStyle.value}>{slots.content?.()}</div>
+              <div style={contentStyle.value}>
+                {props.contentKey != null ? (
+                  <HkCrossfade swapKey={props.contentKey} class="s-admin-shell-swap">
+                    {slots.content?.()}
+                  </HkCrossfade>
+                ) : (
+                  slots.content?.()
+                )}
+              </div>
             </HScrollContainer>
           </main>
 

package/src/components/HkAdminTablePage.tsx

@@ -1,5 +1,6 @@
 import { defineComponent, type Component, type PropType } from "vue";
 import { HAlert, HCard, HEmptyState, HSpinner, HTable, useI18n } from "@celestia-island/hikari";
+import HkCrossfade from "./HkCrossfade";
 import { HkPageHeader } from "./HkPageHeader";
 import type { HkRowManageGate } from "./HkTable";
 
@@ -98,37 +99,53 @@ export const HkAdminTablePage = defineComponent({
            *  render alongside the error branch (its precondition — rows on
            *  screen — is exactly what the error branch removes). */}
           {props.staleError && !props.error ? <HAlert message={props.staleError} /> : null}
-          {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}
-                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)
-                }
+          {/* The body is a page slot with three generations — error,
+              loading/empty, content (task-4, 2026-10-24): the family
+              crossfade owns the exchange, so every admin table page in
+              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}
               >
-                {slots}
-              </HTable>
-            </HCard>
-          )}
+                {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}
+                  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>
           {slots["create-modal"]?.()}
           {slots["edit-modal"]?.()}
         </div>

package/src/components/HkPaneHolder.scss

@@ -0,0 +1,33 @@
+// HkPaneHolder — the keep-mounted pane slot (see the TSX doc for when to
+// choose it over the dissolve primitives).
+
+.hk-pane-holder {
+  display: none;
+
+  // Active: back in the layout with the family dissolve's own language —
+  // a one-shot opacity reveal. No transform: a pane sliding in would
+  // disagree with every crossfade around it.
+  &[data-active] {
+    display: block;
+    animation: hk-pane-holder-in var(--duration-normal, 0.3s) ease-out;
+  }
+}
+
+@keyframes hk-pane-holder-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+// Opt-outs: the global animation switch is the host's, reduced motion is
+// the OS's — the holder obeys both (an inline-less rule; the animation is
+// declared here in the sheet, so unlike HkTransitionContainer's inline
+// duration a media query CAN reach it).
+html[data-css-animations="0"] .hk-pane-holder[data-active] {
+  animation: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .hk-pane-holder[data-active] {
+    animation-duration: var(--duration-fast, 0.15s);
+  }
+}

package/src/components/HkPaneHolder.test.tsx

@@ -0,0 +1,99 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import sass from "sass";
+
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref, type App } from "vue";
+
+import HkPaneHolder from "./HkPaneHolder";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+const containers: HTMLElement[] = [];
+
+function mountHolder(active: boolean): {
+  app: App;
+  root: HTMLElement;
+  child: HTMLElement;
+  setActive: (v: boolean) => void;
+} {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  containers.push(container);
+  const isActive = ref(active);
+  const Child = defineComponent({
+    setup() {
+      // The point of the holder: the pane's instance state SURVIVES
+      // deactivation. A counter proves the component never unmounted.
+      const mounts = ref(0);
+      const tick = () => { mounts.value += 1; };
+      return () => h("button", { type: "button", onClick: tick, "data-mounts": String(mounts.value) }, "pane");
+    },
+  });
+  const Wrapper = defineComponent({
+    render: () =>
+      h(HkPaneHolder, { active: isActive.value }, { default: () => h(Child) }),
+  });
+  const app = createApp(Wrapper);
+  app.mount(container);
+  const root = container.firstElementChild as HTMLElement;
+  const child = root.firstElementChild as HTMLElement;
+  return { app, root, child, setActive: (v: boolean) => { isActive.value = v; } };
+}
+
+afterEach(() => {
+  for (const c of containers.splice(0)) c.remove();
+});
+
+describe("HkPaneHolder — DOM contract", () => {
+  it("renders the holder class and the data-active attribute only when active", async () => {
+    const t = mountHolder(false);
+    expect(t.root.classList.contains("hk-pane-holder")).toBe(true);
+    expect(t.root.hasAttribute("data-active")).toBe(false);
+    expect(t.child).toBeDefined(); // mounted, not unmounted
+    t.setActive(true);
+    await nextTick();
+    expect(t.root.hasAttribute("data-active")).toBe(true);
+    t.app.unmount();
+  });
+
+  it("keeps component state across deactivate/reactivate (the entire point)", async () => {
+    const t = mountHolder(true);
+    (t.child as HTMLButtonElement).click();
+    (t.child as HTMLButtonElement).click();
+    await new Promise((r) => setTimeout(r, 0));
+    expect(t.child.getAttribute("data-mounts")).toBe("2");
+    t.setActive(false);
+    await new Promise((r) => setTimeout(r, 0));
+    t.setActive(true);
+    await new Promise((r) => setTimeout(r, 0));
+    const childAfter = t.root.firstElementChild as HTMLElement;
+    // Same instance: the counter did not reset to 0.
+    expect(childAfter.getAttribute("data-mounts")).toBe("2");
+    t.app.unmount();
+  });
+});
+
+describe("HkPaneHolder — stylesheet contract", () => {
+  const css = sass.compile(join(here, "HkPaneHolder.scss")).css;
+  const scss = readFileSync(join(here, "HkPaneHolder.scss"), "utf-8");
+
+  it("hides the base holder and reveals on [data-active]", () => {
+    expect(css).toMatch(/\.hk-pane-holder\s*\{[^}]*display:\s*none/s);
+    expect(css).toMatch(/\.hk-pane-holder\[data-active\]\s*\{[^}]*display:\s*block/s);
+  });
+
+  it("reveals with opacity only — no transform, ever", () => {
+    const keyframe = /@keyframes\s+hk-pane-holder-in\s*\{([^}]*)\}/s.exec(css);
+    expect(keyframe).not.toBeNull();
+    expect(keyframe![1]).toContain("opacity");
+    expect(keyframe![1]).not.toContain("transform");
+    expect(keyframe![1]).not.toContain("translate");
+  });
+
+  it("obeys the global animation switch and reduced motion", () => {
+    expect(css).toMatch(/html\[data-css-animations="0"\][^{]*\{[^}]*animation:\s*none/s);
+    expect(css).toMatch(/prefers-reduced-motion[^{]*\{[^}]*animation-duration/s);
+  });
+});

package/src/components/HkPaneHolder.tsx

@@ -0,0 +1,57 @@
+import { defineComponent } from "vue";
+
+import "./HkPaneHolder.scss";
+
+/**
+ * HkPaneHolder — the keep-mounted pane slot.
+ *
+ * The third pane-swap surface, for the class of content the dissolve
+ * primitives cannot serve: PERSISTENT panes whose instance must survive
+ * while another pane is active — draft stores (an editor whose unsaved
+ * state lives in the component), canvases/WebGL stages that are too
+ * expensive to rebuild, or sockets that must not unplug.
+ *
+ * `HkCrossfade` / `HkTransitionContainer` swap by keying: the leaving
+ * generation UNMOUNTS when the dissolve completes — exactly wrong for a
+ * draft store. This holder instead keeps every pane in the tree and
+ * toggles reachability: `display: none` while inactive (out of layout,
+ * inert), `display: block` plus a one-shot opacity reveal when it
+ * becomes active. The reveal is opacity-ONLY at the family's
+ * `--duration-normal`, matching the dissolve language — no movement,
+ * ever.
+ *
+ * Contract:
+ * - `active` is a boolean, not a key: the holder IS one pane. A tab
+ *   surface renders one holder per persistent pane beside the ordinary
+ *   panel slots it already has.
+ * - The inactive pane is `display: none` (inert, out of the layout,
+ *   unreadable by assistive tech) but its component instances, state
+ *   and watchers all LIVE — that is the entire point.
+ * - The reveal animation is `hk-pane-holder-in` (opacity 0→1, one
+ *   shot, registered with the animation registry); reduced motion and
+ *   the global `data-css-animations="0"` switch clamp it to instant,
+ *   so the holder never animates for users who opted out.
+ * - No leave animation: the outgoing pane simply hides (it is usually
+ *   being covered by an incoming ordinary panel whose own dissolve is
+ *   the visible exchange).
+ */
+export const HkPaneHolder = defineComponent({
+  name: "HkPaneHolder",
+  props: {
+    /** Whether THIS pane is the active one. */
+    active: { type: Boolean, required: true },
+    tag: { type: String, default: "div" },
+  },
+  setup(props, { slots }) {
+    return () => {
+      const Tag = props.tag as "div" | "section";
+      return (
+        <Tag class="hk-pane-holder" data-active={props.active || undefined}>
+          {slots.default?.()}
+        </Tag>
+      );
+    };
+  },
+});
+
+export default HkPaneHolder;

package/src/components/paneSwap.contract.test.ts

@@ -51,6 +51,11 @@ const STANDARD_PANE_HOSTS: Array<{ file: string; marker: string; why: string }>
     marker: "<HkTransitionContainer",
     why: "settings sections are a page-scale pane slot (migrated 2026-10-23)",
   },
+  {
+    file: "HkAdminTablePage.tsx",
+    marker: "<HkCrossfade",
+    why: "the error/placeholder/content body is a page slot every admin table page inherits (2026-10-24)",
+  },
 ];
 
 /** Justified bespoke mechanisms: "<scss file>: <animation identifier>" → reason. */
@@ -66,6 +71,14 @@ const SANCTIONED_SWAP_KEYFRAMES: Record<string, string> = {
  *  animation must be argued, decorative pulses and spinners do not. */
 const SWAP_VOCABULARY = /(pane|swap|crossfade|morph|sheet)/;
 
+/** The primitives' own stylesheets ARE the sanctioned mechanism — their
+ *  keyframes are the family language itself, not bespoke swaps. */
+const PRIMITIVE_SHEETS = new Set([
+  "HkCrossfade.scss",
+  "HkTransitionContainer.scss",
+  "HkPaneHolder.scss",
+]);
+
 function readComponent(file: string): string {
   return readFileSync(join(componentsDir, file), "utf-8");
 }
@@ -124,6 +137,7 @@ describe("pane-swap contract", () => {
       for (const match of text.matchAll(/@keyframes\s+([\w-]+)/g)) {
         const name = match[1];
         if (!SWAP_VOCABULARY.test(name)) continue;
+        if (PRIMITIVE_SHEETS.has(file)) continue;
         const key = `${file}: ${name}`;
         if (!SANCTIONED_SWAP_KEYFRAMES[key]) offenders.push(`@keyframes ${key}`);
       }

package/src/index.ts

@@ -614,6 +614,7 @@ export { default as HkCopyBadge } from "./components/HkCopyBadge";
 export { default as HkConfirmDialog } from "./components/HkConfirmDialog";
 export { default as HkCrossfade } from "./components/HkCrossfade";
 export { default as HkTransitionContainer } from "./components/HkTransitionContainer";
+export { default as HkPaneHolder } from "./components/HkPaneHolder";
 export { default as HkWindowControls, isApplePlatform } from "./components/HkWindowControls";
 export { default as HkStatusRow } from "./components/HkStatusRow";
 export type { HkStatusRowTone } from "./components/HkStatusRow";