@celestia-island/hikari 0.55.241 → 0.55.243

package/package.json

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

package/src/components/HkCrossfade.test.tsx

@@ -139,6 +139,54 @@ describe("HkCrossfade — DOM contract", () => {
     expect(list[1]!.classList.contains("hk-crossfade-enter-from")).toBe(true);
   });
 
+  it("marks the leaving copy INERT for the dissolve (a11y: dead content)", async () => {
+    // pointer-events: none only stops the mouse — the frozen copy must
+    // also leave the tab order and the accessibility tree, or a screen
+    // reader walks a second, stale copy (duplicate landmarks/roles; in
+    // the rail swap it is a whole second sidebar). A cancelled leave has
+    // to restore the item (see the next case).
+    vi.useFakeTimers();
+    freezeRaf();
+    const { container, set } = mountCrossfade();
+    await set("b");
+    await vi.advanceTimersByTimeAsync(200);
+
+    const list = items(container);
+    expect(list[0]!.hasAttribute("inert"), "the leaving copy is inert").toBe(true);
+    expect(list[0]!.getAttribute("aria-hidden")).toBe("true");
+    expect(list[1]!.hasAttribute("inert"), "the live copy stays interactive").toBe(false);
+    expect(list[1]!.hasAttribute("aria-hidden")).toBe(false);
+  });
+
+  it("a flip-back never leaves a LIVE copy inert (Vue removes the leaving node)", async () => {
+    // Pins the behavior the inert contract relies on: on a keyed
+    // flip-back Vue cancels the in-flight leave of the old element
+    // through its internal callback (no element argument -> routed to
+    // afterLeave, which REMOVES it) and re-enters the key as a FRESH
+    // element. So no live copy can carry inert; if Vue ever changed that
+    // shape (a reused, re-entered element), this test is the tripwire.
+    vi.useFakeTimers();
+    freezeRaf();
+    const { container, set } = mountCrossfade();
+    await set("b");
+    await vi.advanceTimersByTimeAsync(100);
+    const oldA = items(container).find((el) => el.dataset.crossfadeKey === "a")!;
+    expect(oldA.hasAttribute("inert")).toBe(true);
+
+    await set("a");
+    await vi.advanceTimersByTimeAsync(100);
+
+    // The inert old node is gone (not left mounted), and every live node
+    // for the key renders un-inert.
+    expect(oldA.isConnected, "the inert leaving node is removed").toBe(false);
+    const live = items(container).filter((el) => el.dataset.crossfadeKey === "a");
+    expect(live.length).toBeGreaterThan(0);
+    for (const el of live) {
+      expect(el.hasAttribute("inert"), "a live copy must never be inert").toBe(false);
+      expect(el.getAttribute("aria-hidden")).toBeNull();
+    }
+  });
+
   it("watchdog completes a stalled swap: sweeps frozen classes, drops the stale item", async () => {
     vi.useFakeTimers();
     freezeRaf();

package/src/components/HkCrossfade.tsx

@@ -40,7 +40,16 @@ const REPORT_MS = CROSSFADE_WATCHDOG_MS;
  *   opacity ahead of the outgoing one's decay and stops the composite from
  *   dipping toward the background mid-swap.
  * - The leaving item drops pointer events: it is dead content and must not
- *   intercept clicks while it dissolves under the incoming one.
+ *   intercept clicks while it dissolves under the incoming one. It is also
+ *   marked `inert` + `aria-hidden` for the dissolve (2026-10-31): a frozen
+ *   copy must leave the TAB ORDER and the accessibility tree too, or a
+ *   screen reader walks a stale duplicate (in the rail swap it is a whole
+ *   second sidebar). TRADE-OFF: a control focused in the leaving item is
+ *   blurred by the browser the moment the attribute lands, `--duration`
+ *   earlier than the unmount would have; hosts that care move focus FIRST
+ *   (the rail kit's closePeek does exactly that). happy-dom applies no
+ *   inert focus fixup, so that browser behavior is intentionally not
+ *   covered by this suite.
  * - `appear` dissolves the initially rendered item in; off by default —
  *   first paint should never animate (view shells, restored state).
  * - `disabled` renders the active item bare (synchronous swap, no watchdog):
@@ -115,6 +124,25 @@ export default defineComponent({
       if (pending === 0) report.cancel();
     };
 
+    /** Mark a leaving item inert (out of the tab order and the a11y tree)
+     *  for the dissolve. Attribute-based (not the `inert` IDL property) so
+     *  the DOM contract is observable in tests and SSR-less hosts alike.
+     *  The restore is defence: on a keyed flip-back Vue removes the
+     *  leaving node and re-enters a FRESH element (its internal
+     *  cancel-callback runs with no argument and routes to afterLeave), so
+     *  nothing live is ever left inert by that route — but any shape that
+     *  DOES cancel a leave must not keep a live copy inert. */
+    function setLeavingInert(el: Element | null | undefined, on: boolean): void {
+      if (!el) return;
+      if (on) {
+        el.setAttribute("inert", "");
+        el.setAttribute("aria-hidden", "true");
+        return;
+      }
+      el.removeAttribute("inert");
+      el.removeAttribute("aria-hidden");
+    }
+
     // ── Swap-stall watchdog ──────────────────────────────────────────
     /** Budget for one arm: the base sweep window plus the choreographed
      *  enter hold — a delayed enter is mid-flight, not stalled, when the
@@ -211,9 +239,23 @@ export default defineComponent({
             onBeforeEnter={() => { armReport(); armWatchdog(); }}
             onAfterEnter={settleReport}
             onEnterCancelled={settleReport}
-            onBeforeLeave={() => { armReport(); armWatchdog(); }}
+            onBeforeLeave={(el: Element) => {
+              // DEAD CONTENT for the dissolve: drop it from the tab order
+              // AND the accessibility tree. pointer-events: none (the
+              // leave rule) only stops the mouse — a frozen copy otherwise
+              // stays reachable by Tab and by a screen reader's virtual
+              // cursor for the whole dissolve, and in the rail swap it is
+              // a second full sidebar (duplicate landmark/roles, stale
+              // controls) while the live one dissolves in.
+              setLeavingInert(el, true);
+              armReport();
+              armWatchdog();
+            }}
             onAfterLeave={settleReport}
-            onLeaveCancelled={settleReport}
+            onLeaveCancelled={(el: Element) => {
+              setLeavingInert(el, false);
+              settleReport();
+            }}
           >
             {item()}
           </Transition>

package/src/components/HkFaceShell.rail.test.tsx

@@ -475,9 +475,46 @@ describe("HkFaceShell rail chrome: toggle placement and the clip wrapper", () =>
     // marker reads rail while the DENSITY lives on the generation.
     expect(c.slotParams[c.slotParams.length - 1]!.collapsed).toBe(true);
     expect(c.aside().hasAttribute("data-rail"), "the root keeps the state marker").toBe(true);
+    // The leaving generation's ITEM is inert for the dissolve (dead
+    // content leaves the tab order and the a11y tree); the live one is
+    // not.
+    const leavingItem = mid[0]!.parentElement!;
+    const enteringItem = mid[1]!.parentElement!;
+    expect(leavingItem.hasAttribute("inert"), "the dying copy is inert").toBe(true);
+    expect(leavingItem.getAttribute("aria-hidden")).toBe("true");
+    expect(enteringItem.hasAttribute("inert"), "the live copy stays interactive").toBe(false);
     vi.unstubAllGlobals();
   });
 
+  it("hands focus to the toggle when a peek close unmounts the focused row", async () => {
+    // The rail/full swap mounts the entering generation fresh and marks
+    // the leaving one inert, so a focused row inside the clip dies with
+    // it. useSidebarRail's close paths hand focus to the toggle — this is
+    // the SHELL half of that contract (the HkSidebar suite pins the other
+    // host; different host ref, different toggle placement).
+    vi.useFakeTimers();
+    const c = mountShell({ sidebarCollapsible: true }, () =>
+      h("div", { class: "sidebar-mock" }, h("button", { class: "nav-btn" }, "NAV")),
+    );
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    c.aside().dispatchEvent(POINTER_ENTER());
+    await vi.advanceTimersByTimeAsync(400);
+    expect(c.aside().hasAttribute("data-peeking")).toBe(true);
+
+    // The ACTIVE (entering) generation's row: the leaving copy is inert
+    // and (correctly) refuses focus.
+    const gens = c.panel().querySelectorAll<HTMLElement>(".hk-sidebar-rail-generation");
+    const row = gens[gens.length - 1]!.querySelector<HTMLButtonElement>("button.nav-btn")!;
+    row.focus();
+    expect(document.activeElement).toBe(row);
+
+    c.aside().dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" }));
+    await vi.advanceTimersByTimeAsync(0);
+    expect(c.aside().hasAttribute("data-peeking")).toBe(false);
+    expect(document.activeElement, "focus moved to the toggle").toBe(c.toggle());
+  });
+
   it("does not touch the legacy sidebar path (no clip wrapper, no rail classes)", () => {
     const c = mountShell();
     expect(c.container.querySelector(".hk-sidebar-rail-clip")).toBeFalsy();

package/src/components/HkSidebar.rail.test.tsx

@@ -242,6 +242,11 @@ describe("HkSidebar rail chrome: toggle placement and the clip wrapper", () => {
     expect(entering!.style.width).toBe("64px");
     // The band content lives inside the entering generation.
     expect(entering!.querySelector(".hk-sidebar-body")).toBeTruthy();
+    // The leaving generation's ITEM is inert for the dissolve (dead
+    // content leaves the tab order and the a11y tree); the live one is not.
+    expect(leaving!.parentElement!.hasAttribute("inert"), "the dying copy is inert").toBe(true);
+    expect(leaving!.parentElement!.getAttribute("aria-hidden")).toBe("true");
+    expect(entering!.parentElement!.hasAttribute("inert")).toBe(false);
     vi.unstubAllGlobals();
   });
 
@@ -318,6 +323,37 @@ describe("HkSidebar pin window: expand must not replay the slide", () => {
   });
 });
 
+describe("HkSidebar peek close: focus is handed back to the toggle", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  it("Escape from a focused row inside the swapped clip lands focus on the toggle", async () => {
+    // The peek close flips the density, which MOUNTS the entering
+    // generation fresh — the focused row is unmounted a dissolve later.
+    // Without the handoff (useSidebarRail.closePeek) focus would fall to
+    // <body> and take the host's :focus-within reveal with it.
+    const c = mountSidebar({ collapsible: true });
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+
+    // The slot's faux nav row lives INSIDE the swapped clip.
+    const row = c.container.querySelector<HTMLButtonElement>("nav button")!;
+    row.focus();
+    expect(document.activeElement).toBe(row);
+
+    c.aside().dispatchEvent(new Event("pointerenter"));
+    await vi.advanceTimersByTimeAsync(400);
+    expect(c.aside().hasAttribute("data-peeking")).toBe(true);
+
+    c.aside().dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" }));
+    await vi.advanceTimersByTimeAsync(0);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(c.aside().hasAttribute("data-peeking")).toBe(false);
+    expect(document.activeElement, "focus moved to the toggle").toBe(c.toggle());
+  });
+});
+
 describe("HkSidebar hover suppression: a pointer on the toggle never peeks", () => {
   beforeEach(() => {
     vi.useFakeTimers();

package/src/components/HkSidebarRailSwap.tsx

@@ -65,11 +65,17 @@ import "./HkSidebarRail.scss";
  *   inside the slot. A peek OPEN also hands hover to the full row under
  *   the resting pointer without user intent — inherent to any dissolve.
  * - FOCUS: when the leaving generation unmounts at the end of the
- *   dissolve, focus inside it (a nav row focused in an open peek)
- *   drops to <body> — the sharpest edge is Escape-closing a peek from
- *   a focused row, which also drops the host's :focus-within (the
- *   toggle's keyboard reveal) until the next Tab. Hosts that need a
- *   softer landing can refocus the toggle from the peek-closer path.
+ *   dissolve (and the leaving item is marked inert, which blurs a
+ *   focused descendant), focus inside it would drop to <body> — taking
+ *   the host's :focus-within (the toggle's keyboard reveal) with it. The
+ *   KIT closes this for rail hosts: useSidebarRail.closePeek (and every
+ *   path that funnels through it, including the pointerleave grace close)
+ *   hands focus to the toggle when the focused node lived inside the
+ *   swapped window (2026-10-31). A bespoke host that drives its own
+ *   close paths still owns the handoff.
+ * - The leaving generation also carries `inert` + `aria-hidden` for the
+ *   dissolve (HkCrossfade), so the frozen copy is neither tabbable nor
+ *   announced while the live one fades in.
  *
  * Reduced motion: HkCrossfade keeps a short opacity exchange (a fade
  * carries no movement) while the kit's sheets kill the width slides —

package/src/components/HkSolarLocationSetting.scss

@@ -0,0 +1,91 @@
+/* HkSolarLocationSetting — the solar-clock location strategy row and
+ * its editor modal body (see the component docblock for the strategy
+ * ladder). AI-generated: developed with the ZCode agent (model
+ * GLM-5.3); human-directed. */
+
+/* ── The settings-page row: live summary + Edit button ────────────────── */
+.hk-solar-setting {
+  display: flex;
+  align-items: center;
+  gap: var(--space-8, 0.5rem);
+  min-width: 0;
+}
+
+.hk-solar-summary {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-6, 0.375rem);
+  min-width: 0;
+  flex: 1 1 auto;
+  color: rgb(var(--color-text-secondary, var(--color-muted)));
+  font-size: var(--text-sm);
+}
+
+.hk-solar-summary-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  color: rgb(var(--color-muted));
+}
+
+/* Zone ids ("America/Argentina/Buenos_Aires") can outrun narrow side
+ * columns — the summary clips at the ellipsis, never pushes the Edit
+ * button off the row. */
+.hk-solar-summary-text {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.hk-solar-edit {
+  flex-shrink: 0;
+}
+
+/* ── Editor body (inside the modal) ───────────────────────────────────── */
+.hk-solar-editor {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-12, 0.75rem);
+}
+
+/* Per-strategy explanation under the segmented strip — muted caption
+ * prose, same tier as the select's field label. */
+.hk-solar-hint {
+  margin: 0;
+  color: rgb(var(--color-muted));
+  font-size: var(--text-xs);
+  line-height: 1.5;
+}
+
+.hk-solar-manual {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-12, 0.75rem);
+}
+
+.hk-solar-hemisphere {
+  display: flex;
+  flex-direction: column;
+}
+
+/* Field label for the hemisphere group — the SAME metrics as
+ * .hk-select-label so the two manual fields read as one form. */
+.hk-solar-field-label {
+  display: block;
+  margin-bottom: var(--space-4, 0.25rem);
+  font-size: var(--text-xs);
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  color: rgb(var(--color-text) / var(--hk-field-label-alpha, 72%));
+}
+
+/* Resolved-coordinates readout (manual pane only) — a quiet trace of
+ * what the engine will actually feed the sun clock. */
+.hk-solar-resolved {
+  margin: 0;
+  color: rgb(var(--color-muted));
+  font-size: var(--text-xs);
+  font-variant-numeric: tabular-nums;
+}