@celestia-island/hikari 0.45.1 → 0.45.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.45.1",
+  "version": "0.45.3",
   "private": false,
   "type": "module",
   "description": "Hikari Vue 3 component library — production-grade UI components based on shittim-chest design system",

package/src/components/HkListTransition.scss

@@ -94,13 +94,18 @@
   opacity: 0;
 }
 
+/* The leave ghost keeps its in-flow geometry via the pinLeaveGeometry
+ * hook wired in HkListTransition.tsx (explicit width/top/left inline
+ * pins). Do NOT add `width: 100%` here — without a position:relative
+ * host it resolves against the nearest positioned ancestor's collapsed
+ * box and the row flashes full-width while fading (the toast #306
+ * defect class). */
 .hk-list-grow-leave-active {
   transition:
     transform var(--duration-fast, 0.15s) cubic-bezier(0.5, 0, 0.75, 0),
     opacity var(--duration-fast, 0.15s) ease-in;
   pointer-events: none;
   position: absolute;
-  width: 100%;
 }
 
 .hk-list-grow-leave-to {

package/src/components/HkListTransition.test.tsx

@@ -0,0 +1,105 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h, nextTick, ref } from "vue";
+
+import HkListTransition from "./HkListTransition";
+
+/**
+ * HkListTransition leave-geometry contract:
+ * - a leaving row in an absolute-leave variant (pop/slide/fade/grow) is
+ *   pinned to its measured in-flow box by the before-leave hook
+ *   (pinLeaveGeometry), so it cannot flash to `width: 100%` of a
+ *   collapsed containing block when the host is not position:relative
+ * - the `reveal` variant animates its own height and must NOT be pinned
+ *
+ * (Repo test convention: raw createApp + document queries, no
+ * @vue/test-utils dependency; happy-dom has no layout engine, so
+ * offset* metrics are stubbed.)
+ */
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+type Variant = "pop" | "slide" | "fade" | "grow" | "reveal";
+
+function mountRows(variant: Variant, keys: () => string[]) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({
+    render: () =>
+      h(
+        HkListTransition,
+        { tag: "ul", variant },
+        { default: () => keys().map((k) => h("li", { key: k }, k)) },
+      ),
+  });
+  mounts.push({ app, container });
+  app.mount(container);
+  return container;
+}
+
+function stubLayout(el: HTMLElement, over: Partial<{
+  offsetTop: number;
+  offsetLeft: number;
+  offsetWidth: number;
+  offsetHeight: number;
+}> = {}): void {
+  const wrapper = el.parentElement as HTMLElement;
+  Object.defineProperty(wrapper, "clientWidth", { value: 300, configurable: true });
+  Object.defineProperty(el, "offsetParent", { value: wrapper, configurable: true });
+  Object.defineProperty(el, "offsetTop", { value: over.offsetTop ?? 0, configurable: true });
+  Object.defineProperty(el, "offsetLeft", { value: over.offsetLeft ?? 0, configurable: true });
+  Object.defineProperty(el, "offsetWidth", { value: over.offsetWidth ?? 300, configurable: true });
+  Object.defineProperty(el, "offsetHeight", { value: over.offsetHeight ?? 40, configurable: true });
+}
+
+function rows(): HTMLElement[] {
+  return Array.from(document.querySelectorAll<HTMLElement>("ul > li"));
+}
+
+afterEach(() => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+});
+
+describe("HkListTransition leave geometry", () => {
+  it("pins the leaving grow row to its in-flow box instead of width:100%", async () => {
+    const keys = ref(["a", "b", "c"]);
+    mountRows("grow", () => keys.value);
+    await nextTick();
+
+    stubLayout(rows()[1]!, { offsetTop: 40, offsetLeft: 0, offsetWidth: 300, offsetHeight: 40 });
+
+    keys.value = ["a", "c"];
+    await nextTick();
+    await nextTick();
+
+    const leaving = document.querySelector<HTMLElement>(".hk-list-grow-leave-active");
+    expect(leaving).not.toBeNull();
+    // The pin mirrors the measured in-flow box exactly; a percentage
+    // width would resolve against a possibly-collapsed containing block.
+    expect(leaving!.style.left).toBe("0px");
+    expect(leaving!.style.top).toBe("40px");
+    expect(leaving!.style.width).toBe("300px");
+    expect(leaving!.style.height).toBe("40px");
+    expect(leaving!.style.boxSizing).toBe("border-box");
+    expect(leaving!.style.width).not.toBe("100%");
+  });
+
+  it("does not pin the reveal variant (its own height drives the squeeze)", async () => {
+    const keys = ref(["a", "b"]);
+    mountRows("reveal", () => keys.value);
+    await nextTick();
+
+    stubLayout(rows()[0]!);
+
+    keys.value = ["b"];
+    await nextTick();
+    await nextTick();
+
+    const leaving = document.querySelector<HTMLElement>(".hk-list-reveal-leave-active");
+    expect(leaving).not.toBeNull();
+    expect(leaving!.style.height).toBe("");
+    expect(leaving!.style.width).toBe("");
+  });
+});

package/src/components/HkListTransition.tsx

@@ -1,5 +1,6 @@
-import { defineComponent, TransitionGroup, type PropType } from "vue";
+import { defineComponent, onBeforeUpdate, ref, TransitionGroup, type PropType } from "vue";
 
+import { clearLeaveGeometry, pinLeaveGeometry, type LeaveBoxSnapshot } from "../utils/dom";
 import { useReportedTransition } from "../composables/useReportedTransition";
 
 import "./HkListTransition.scss";
@@ -63,10 +64,58 @@ export default defineComponent({
       if (pending === 0) report.cancel();
     };
 
+    // Variants whose leave-active rule lifts the row out of flow with
+    // `position: absolute` (see HkListTransition.scss). Only these need
+    // the geometry pin; `reveal` animates the row's own height in place
+    // and `none` never leaves the flow, so a pin would freeze the very
+    // property they animate.
+    const ABSOLUTE_VARIANTS: ReadonlySet<string> = new Set(["pop", "slide", "fade", "grow"]);
+
+    // Pre-patch geometry of every row, refreshed on each update (the DOM
+    // is still the pre-patch tree at onBeforeUpdate — same pattern as
+    // HkTabs). During a multi-row removal the first leaving sibling gets
+    // its leave-active class (position:absolute) synchronously inside the
+    // patch pass, so a live offset read in a later sibling's beforeLeave
+    // hook would freeze an already-reflowed position. The pin also
+    // replaces `grow`'s old `width: 100%`, which resolved against a
+    // possibly-collapsed containing block when the host is not
+    // position:relative (the full-width leave flash).
+    const hostRef = ref<{ $el?: Element } | null>(null);
+    const prePatchBoxes = new WeakMap<Element, LeaveBoxSnapshot>();
+    onBeforeUpdate(() => {
+      // Fragment hosts (tag="") have a comment anchor as $el — no
+      // element children to measure there.
+      const host = hostRef.value?.$el;
+      if (host == null || host.nodeType !== 1) return;
+      for (const child of Array.from(host.children)) {
+        const e = child as HTMLElement;
+        prePatchBoxes.set(e, {
+          top: e.offsetTop,
+          left: e.offsetLeft,
+          width: e.offsetWidth,
+          height: e.offsetHeight,
+        });
+      }
+    });
+
+    const usesAbsoluteLeave = () =>
+      !props.disabled && ABSOLUTE_VARIANTS.has(props.variant);
+
+    function pinLeaving(el: Element) {
+      if (!usesAbsoluteLeave()) return;
+      pinLeaveGeometry(el, { anchorX: "left", box: prePatchBoxes.get(el) });
+    }
+
+    function unpinLeaving(el: Element) {
+      if (!usesAbsoluteLeave()) return;
+      clearLeaveGeometry(el);
+    }
+
     return () => {
       const name = props.disabled ? "hk-list-none" : `hk-list-${props.variant}`;
       return (
         <TransitionGroup
+          ref={hostRef}
           tag={props.tag}
           name={name}
           appear={props.appear}
@@ -74,9 +123,15 @@ export default defineComponent({
           onBeforeEnter={arm}
           onAfterEnter={settle}
           onEnterCancelled={settle}
-          onBeforeLeave={arm}
+          onBeforeLeave={(el: Element) => {
+            arm();
+            pinLeaving(el);
+          }}
           onAfterLeave={settle}
-          onLeaveCancelled={settle}
+          onLeaveCancelled={(el: Element) => {
+            settle();
+            unpinLeaving(el);
+          }}
         >
           {slots.default?.()}
         </TransitionGroup>

package/src/components/HkModal.footerLead.test.tsx

@@ -0,0 +1,123 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import HkModal from "./HkModal";
+
+/**
+ * HkModal footerLead slot contract tests:
+ * - the named slot renders inside .hk-modal-footer BEFORE the action buttons,
+ *   wrapped in .hk-modal-footer-lead, with the band marked .hk-modal-footer--lead
+ * - the band still renders with ONLY a footerLead (no footerActions) — a lead
+ *   alone must not vanish with the actions
+ * - absent the slot, no new DOM appears (backward compat)
+ * - the explicit `footer` slot keeps precedence over footerLead + footerActions
+ *   (existing full-custom contract unchanged)
+ */
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+afterEach(() => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+});
+
+interface Harness {
+  container: HTMLElement;
+  footer: HTMLElement | null;
+}
+
+async function mountModal(
+  props: Record<string, unknown>,
+  slots: Record<string, unknown> = {},
+): Promise<Harness> {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const open = ref(true);
+  const Wrapper = defineComponent({
+    setup() {
+      // A FRESH slots object per Wrapper render: updateSlots mutates the
+      // slots object it is handed (deleting keys absent from a later
+      // sibling mount's shape), and a shared literal would lose footerLead
+      // on re-render.
+      return () =>
+        h(HkModal, {
+          ...props,
+          modelValue: open.value,
+          "onUpdate:modelValue": (v: boolean) => { open.value = v; },
+        }, { ...slots });
+    },
+  });
+  const app = createApp(Wrapper);
+  app.mount(container);
+  mounts.push({ app, container });
+  await nextTick();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  await nextTick();
+  // HkModal teleports to body and sibling test files in this worker can
+  // leave their own modals behind — scope to the NEWEST mounted footer
+  // instead of the document-first match.
+  const footers = document.querySelectorAll(".hk-modal-footer");
+  return {
+    container,
+    footer: footers.length ? (footers[footers.length - 1] as HTMLElement) : null,
+  };
+}
+
+describe("HkModal footerLead slot", () => {
+  it("renders the lead before the action buttons inside the band", async () => {
+    const { footer } = await mountModal(
+      {
+        title: "Config",
+        footerActions: [{ label: "Add", variant: "primary" }],
+      },
+      { footerLead: () => h("button", { class: "lead-jump", "data-test": "jump" }, "JUMP") },
+    );
+    expect(footer).not.toBeNull();
+    expect(footer?.classList.contains("hk-modal-footer--lead")).toBe(true);
+    const lead = footer?.querySelector(".hk-modal-footer-lead");
+    expect(lead).not.toBeNull();
+    expect(lead?.querySelector(".lead-jump")?.textContent).toBe("JUMP");
+
+    const children = footer ? Array.from(footer.children) : [];
+    expect(children[0]?.classList.contains("hk-modal-footer-lead")).toBe(true);
+    expect(children.length).toBe(2);
+    expect(children[1]?.textContent).toBe("Add");
+  });
+
+  it("keeps the band alive with ONLY a footerLead and no actions", async () => {
+    const { footer } = await mountModal(
+      { title: "Config" },
+      { footerLead: () => h("button", { class: "lead-jump" }, "JUMP") },
+    );
+    expect(footer).not.toBeNull();
+    expect(footer?.classList.contains("hk-modal-footer--lead")).toBe(true);
+    expect(footer?.querySelector(".hk-modal-footer-lead")).not.toBeNull();
+    // No action buttons — the only children are the lead wrapper.
+    const children = footer ? Array.from(footer.children) : [];
+    expect(children).toHaveLength(1);
+  });
+
+  it("adds no lead DOM and no band when both lead and actions are absent", async () => {
+    const { footer } = await mountModal({ title: "Config" });
+    expect(footer).toBeNull();
+  });
+
+  it("the explicit footer slot keeps precedence over footerLead and actions", async () => {
+    const { footer } = await mountModal(
+      {
+        title: "Config",
+        footerActions: [{ label: "Add" }],
+      },
+      {
+        footer: () => h("div", { class: "custom-footer" }, "CUSTOM"),
+        footerLead: () => h("button", { class: "lead-jump" }, "JUMP"),
+      },
+    );
+    expect(footer).not.toBeNull();
+    expect(footer?.classList.contains("hk-modal-footer--lead")).toBe(false);
+    expect(footer?.querySelector(".custom-footer")?.textContent).toBe("CUSTOM");
+    expect(footer?.querySelector(".hk-modal-footer-lead")).toBeNull();
+    expect(footer?.textContent).not.toContain("Add");
+  });
+});

package/src/components/HkModal.scss

@@ -298,6 +298,21 @@
   }
 }
 
+// Lead content (e.g. a ghost jump link into the admin console) rendered at
+// the footer's inline-start with the action buttons still pinned at
+// inline-end — the footer counterpart of .hk-modal-header-lead. The lead's
+// auto inline-end margin absorbs the slack (same distribution trick the
+// header uses), so the layout mirrors correctly in RTL without a
+// space-between override.
+.hk-modal-footer--lead {
+  .hk-modal-footer-lead {
+    display: flex;
+    align-items: center;
+    flex-shrink: 0;
+    margin-inline-end: auto;
+  }
+}
+
 // ------
 // Responsive — full-screen on narrow viewports
 // ------

package/src/components/HkModal.tsx

@@ -695,10 +695,13 @@ export default defineComponent({
       if (slots.footer) {
         return <div class="hk-modal-footer">{slots.footer()}</div>;
       }
-      if (props.footerActions && props.footerActions.length > 0) {
+      const hasLead = Boolean(slots.footerLead);
+      const hasActions = Boolean(props.footerActions && props.footerActions.length > 0);
+      if (hasLead || hasActions) {
         return (
-          <div class="hk-modal-footer">
-            {props.footerActions.map((action, i) => (
+          <div class={["hk-modal-footer", hasLead ? "hk-modal-footer--lead" : ""]}>
+            {hasLead && <div class="hk-modal-footer-lead">{slots.footerLead?.()}</div>}
+            {props.footerActions?.map((action, i) => (
               <HButton
                 key={i}
                 variant={action.variant ?? "secondary"}

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

@@ -7,12 +7,15 @@
  * assertion: the theme-row lead cell must carry an explicit size that
  * fits the widest host lead mark, not just the mixin's generic box.
  *
- * The widened cell must stay scoped to the lead slot (2026-09-12 field
- * report): shipped first as a bare `.s-theme-item-btn .hk-menu-item-icon`
- * rule, it also matched the 自定义 row and every host row reusing
- * s-theme-item-btn (chest's mode-extra DPI entry) — and mi.icon
- * normalizes those cells' svg to the cell, so their 14px glyphs rendered
- * 28px wide.
+ * The widened cell must stay scoped (2026-09-12 field report): shipped
+ * first as a bare `.s-theme-item-btn .hk-menu-item-icon` rule, it also
+ * matched the 自定义 row and every host row reusing s-theme-item-btn —
+ * and mi.icon normalizes those cells' svg to the cell, so their 14px
+ * glyphs rendered 28px wide. The widening therefore targets named scopes
+ * (lead slot, customize row) plus the toggle-owned mode-extra strip, the
+ * last one widening the CELL while pinning the glyph back to the
+ * standard box so host strip rows (chest's DPI entry) align their labels
+ * with the theme rows' names without rescaling their icons.
  */
 import { describe, expect, it } from "vitest";
 import { readFileSync } from "node:fs";
@@ -33,12 +36,12 @@ describe("HkThemeToggle row lead-cell contract", () => {
     expect(block![0]).toContain("height: 28px");
   });
 
-  it("does not widen icon cells outside the leading slot", () => {
+  it("does not widen icon cells with a bare unscoped theme-row rule", () => {
     const css = read("HkThemeToggle.scss");
     // A bare `.s-theme-item-btn .hk-menu-item-icon {` rule also hits the
     // customize row and host mode-extra rows; the widened cell may only
-    // target the lead slot class.
-    expect(css).not.toMatch(/\.s-theme-item-btn \.hk-menu-item-icon\s*\{/);
+    // target named scopes (lead slot, customize row, mode-extra strip).
+    expect(css).not.toMatch(/^\.s-theme-item-btn \.hk-menu-item-icon\s*\{/m);
   });
 
   it("aligns the customize row to the lead column without rescaling its glyph", () => {
@@ -60,4 +63,23 @@ describe("HkThemeToggle row lead-cell contract", () => {
     expect(svgBlock).not.toBeNull();
     expect(svgBlock![0]).toContain("var(--hk-menu-item-icon-box)");
   });
+
+  it("aligns mode-extra host rows to the lead column without rescaling their glyph", () => {
+    const css = read("HkThemeToggle.scss");
+    // Host strip rows (chest's DPI entry) join the 28px lead column so
+    // their label starts at the same x as the theme rows' names
+    // (2026-09-12 field report), but the glyph keeps the standard box.
+    const block = css.match(
+      /\.s-theme-mode-extra \.s-theme-item-btn \.hk-menu-item-icon\s*\{[^}]*\}/,
+    );
+    expect(block).not.toBeNull();
+    expect(block![0]).toContain("width: 28px");
+    expect(block![0]).toContain("height: 28px");
+
+    const svgBlock = css.match(
+      /\.s-theme-mode-extra \.s-theme-item-btn \.hk-menu-item-icon > svg\s*\{[^}]*\}/,
+    );
+    expect(svgBlock).not.toBeNull();
+    expect(svgBlock![0]).toContain("var(--hk-menu-item-icon-box)");
+  });
 });

package/src/components/HkThemeToggle.scss

@@ -243,6 +243,27 @@
   height: var(--hk-menu-item-icon-box);
 }
 
+/* Host rows in the mode-extra strip (chest's DPI entry row reuses
+ * s-theme-item-btn) join the same 28px lead column, so every row's name
+ * in the toggle starts at one x — desktop popover and mobile sheet both
+ * (2026-09-12 field report: with the strip row at the generic 16px cell
+ * its label sat a full cell-width left of the theme rows' names). The
+ * strip container is the toggle's own, so the scope needs no host
+ * class-name contract. As with the customize row, the cell widens but
+ * the GLYPH keeps the standard menu icon size — widening a cell must
+ * never re-scale its glyph (the 0.42.2 regression class). */
+.s-theme-mode-extra .s-theme-item-btn .hk-menu-item-icon {
+  @include mi.icon;
+
+  width: 28px;
+  height: 28px;
+}
+
+.s-theme-mode-extra .s-theme-item-btn .hk-menu-item-icon > svg {
+  width: var(--hk-menu-item-icon-box);
+  height: var(--hk-menu-item-icon-box);
+}
+
 /* Custom rows keep the name clear of the overlaid delete button. */
 .s-theme-item-row[data-custom] .s-theme-item-name {
   margin-inline-end: 2rem;