@celestia-island/hikari 0.55.219 → 0.55.221

package/package.json

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

package/src/components/HkSettingsDialog.scss

@@ -122,6 +122,39 @@
     flex-direction: column;
     gap: var(--space-16);
   }
+
+  /* ── phone: the rail becomes a top tab strip ────────────────────────
+     Under the family's mobile breakpoint the left rail moves to the
+     window's top edge as the shared pill strip (HTabs), horizontally
+     scrollable with edge fades — every section fits, the window never
+     grows a second nav column. The DOM branch and this layout share ONE
+     breakpoint through the data-phone attribute (useBreakpoint), so
+     neither half can drift. Desktop never sees these rules. */
+  &[data-phone] {
+    flex-direction: column;
+    /* A small breath between the strip and the pane (2026-10-28 user
+       direction) — tighter than the desktop rail gutter. */
+    gap: var(--space-12);
+
+    > .hk-settings__topnav {
+      flex: none;
+      /* Center the strip while it fits (the pill-strip family look);
+         once it overflows the scroller caps at 100% and the fades take
+         over, so centering never clips the overflowing start. */
+      display: flex;
+      justify-content: center;
+
+      /* One notch UP from the regular strips (text-sm, 4/12 padding,
+         16px icons): the phone nav is the window's primary switcher
+         (2026-10-28 user direction). Icons scale through the strip's
+         own trigger icon cell (the shell renders them at 18). */
+      .hk-tabs-trigger {
+        gap: var(--space-8);
+        padding: var(--space-6) var(--space-14);
+        font-size: var(--text-base);
+      }
+    }
+  }
 }
 
 /* ── Dialog host: stable frame + flush scrollbar edge ────────────────── */

package/src/components/HkSettingsDialog.test.tsx

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, afterEach } from "vitest";
 import { readFileSync } from "node:fs";
 import { createApp, defineComponent, h, nextTick, ref } from "vue";
 import { Languages, Globe } from "lucide-vue-next";
@@ -322,3 +322,196 @@ describe("settings dialog SCSS host contract (source-level)", () => {
     unmount();
   });
 });
+
+describe("phone shell (rail → top tab strip, 2026-10-28 user direction)", () => {
+  const originalWidth = window.innerWidth;
+
+  const setWidth = (w: number) => {
+    Object.defineProperty(window, "innerWidth", {
+      configurable: true,
+      writable: true,
+      value: w,
+    });
+    window.dispatchEvent(new Event("resize"));
+  };
+
+  afterEach(() => setWidth(originalWidth));
+
+  it("renders the top strip instead of the rail under the mobile breakpoint", () => {
+    setWidth(390);
+    const { container, unmount } = mount(Host);
+    // The rail is gone; the strip carries every section as a trigger and
+    // the shell marks the column layout for the SCSS.
+    expect(container.querySelector(".hk-settings__rail")).toBeNull();
+    expect(container.querySelector(".hk-settings")!.hasAttribute("data-phone")).toBe(true);
+    const triggers = container.querySelectorAll<HTMLButtonElement>(
+      ".hk-settings__topnav .hk-tabs-trigger",
+    );
+    expect(triggers).toHaveLength(3);
+    expect(triggers[0].textContent).toContain("Language");
+    // Icons ride one notch up with the strip (18 vs the rail's 16).
+    expect(triggers[0].querySelector(".hk-tabs-trigger-icon svg")).toBeTruthy();
+    expect(container.querySelector('[data-test="pane-language"]')).toBeTruthy();
+    unmount();
+  });
+
+  it("switches sections from the strip and reports selection", async () => {
+    setWidth(390);
+    const { container, unmount } = mount(Host);
+    const triggers = container.querySelectorAll<HTMLButtonElement>(
+      ".hk-settings__topnav .hk-tabs-trigger",
+    );
+    triggers[1].click();
+    await nextTick();
+    expect(container.querySelector('[data-test="pane-network"]')).toBeTruthy();
+    expect(triggers[1].getAttribute("aria-selected")).toBe("true");
+    // The strip's pill semantics: inactive triggers carry "false", not
+    // the attribute's absence.
+    expect(triggers[0].getAttribute("aria-selected")).toBe("false");
+    unmount();
+  });
+
+  it("never activates a disabled section from the strip", async () => {
+    setWidth(390);
+    const { container, unmount } = mount(Host);
+    const triggers = container.querySelectorAll<HTMLButtonElement>(
+      ".hk-settings__topnav .hk-tabs-trigger",
+    );
+    expect(triggers[2].disabled).toBe(true);
+    triggers[2].click();
+    await nextTick();
+    expect(container.querySelector('[data-test="pane-language"]')).toBeTruthy();
+    expect(triggers[2].getAttribute("aria-selected")).toBe("false");
+    unmount();
+  });
+
+  it("flips live when the viewport crosses the breakpoint", async () => {
+    // Start desktop: the rail is the nav.
+    const { container, unmount } = mount(Host);
+    expect(container.querySelector(".hk-settings__rail")).toBeTruthy();
+    expect(container.querySelector(".hk-settings__topnav")).toBeNull();
+    setWidth(390);
+    await nextTick();
+    expect(container.querySelector(".hk-settings__topnav")).toBeTruthy();
+    expect(container.querySelector(".hk-settings__rail")).toBeNull();
+    // …and back.
+    setWidth(1024);
+    await nextTick();
+    expect(container.querySelector(".hk-settings__rail")).toBeTruthy();
+    expect(container.querySelector(".hk-settings__topnav")).toBeNull();
+    unmount();
+  });
+
+  it("lands navLabel on the strip's tablist", () => {
+    setWidth(390);
+    const Named = defineComponent({
+      setup() {
+        return () => (
+          <HSettingsBody sections={SECTIONS.slice(0, 2)} navLabel="Settings sections">
+            {{
+              language: () => <div data-test="pane-language" />,
+              network: () => <div data-test="pane-network" />,
+            }}
+          </HSettingsBody>
+        );
+      },
+    });
+    const { container, unmount } = mount(Named);
+    const list = container.querySelector(".hk-settings__topnav .hk-tabs-list");
+    expect(list).toBeTruthy();
+    expect(list!.getAttribute("role")).toBe("tablist");
+    expect(list!.getAttribute("aria-label")).toBe("Settings sections");
+    unmount();
+  });
+
+  it("never shows a disabled-first section as selected (either nav)", async () => {
+    // R2 2026-10-28: the landing default is the first USABLE key — a
+    // disabled-first host must not open on the dead entry, and the phone
+    // strip must not frame it aria-selected while the desktop rail
+    // highlights nothing.
+    const LockedFirst = defineComponent({
+      setup() {
+        return () => (
+          <HSettingsBody
+            sections={[
+              { key: "locked", label: "Locked", disabled: true },
+              { key: "network", label: "Network", icon: Globe },
+            ]}
+          >
+            {{
+              locked: () => <div data-test="pane-locked" />,
+              network: () => <div data-test="pane-network" />,
+            }}
+          </HSettingsBody>
+        );
+      },
+    });
+    // Desktop: the rail never marks the dead entry active.
+    const desktop = mount(LockedFirst);
+    const railItems = desktop.container.querySelectorAll<HTMLButtonElement>(".hk-settings__rail-item");
+    expect(railItems[0].classList.contains("is-active")).toBe(false);
+    expect(railItems[1].classList.contains("is-active")).toBe(true);
+    desktop.unmount();
+    // Phone: the strip's dead trigger stays unselected; the usable one
+    // carries the selection and its pane renders.
+    setWidth(390);
+    const phone = mount(LockedFirst);
+    const triggers = phone.container.querySelectorAll<HTMLButtonElement>(
+      ".hk-settings__topnav .hk-tabs-trigger",
+    );
+    expect(triggers[0].getAttribute("aria-selected")).toBe("false");
+    expect(triggers[1].getAttribute("aria-selected")).toBe("true");
+    expect(phone.container.querySelector('[data-test="pane-network"]')).toBeTruthy();
+    phone.unmount();
+  });
+
+  it("round-trips strip picks to a bound section prop (controlled contract)", async () => {
+    // The pane follows internal state, so a deleted update:section emit
+    // would be invisible to an unbound host — pin the controlled half.
+    setWidth(390);
+    const section = ref("language");
+    const Controlled = defineComponent({
+      setup() {
+        return () => (
+          <HSettingsBody
+            sections={SECTIONS.slice(0, 2)}
+            section={section.value}
+            onUpdate:section={(v: string) => (section.value = v)}
+          >
+            {{
+              language: () => <div data-test="pane-language" />,
+              network: () => <div data-test="pane-network" />,
+            }}
+          </HSettingsBody>
+        );
+      },
+    });
+    const { container, unmount } = mount(Controlled);
+    const triggers = container.querySelectorAll<HTMLButtonElement>(
+      ".hk-settings__topnav .hk-tabs-trigger",
+    );
+    triggers[1].click();
+    await nextTick();
+    expect(section.value).toBe("network");
+    unmount();
+  });
+
+  it("pins the phone layout contract in the SCSS source", () => {
+    // happy-dom cannot exercise the cascade: pin the column flip, the
+    // gap, the centering and the one-notch-up sizing at the source. The
+    // assertions read INSIDE the &[data-phone] block — several of these
+    // declarations also exist elsewhere in the sheet, and a bare
+    // toContain would keep passing after the phone rule dies (R2).
+    const scss = readFileSync("src/components/HkSettingsDialog.scss", "utf8");
+    const phoneBlock = scss.slice(
+      scss.indexOf("&[data-phone] {"),
+      scss.indexOf("Dialog host"),
+    );
+    expect(phoneBlock).toContain("flex-direction: column;");
+    expect(phoneBlock).toContain("gap: var(--space-12);");
+    expect(phoneBlock).toContain("> .hk-settings__topnav {");
+    expect(phoneBlock).toContain("justify-content: center;");
+    expect(phoneBlock).toContain("padding: var(--space-6) var(--space-14);");
+    expect(phoneBlock).toContain("font-size: var(--text-base);");
+  });
+});

package/src/components/HkSettingsDialog.tsx

@@ -10,6 +10,8 @@ import {
 
 import HkTransitionContainer from "./HkTransitionContainer";
 import HkScrollContainer from "./HkScrollContainer";
+import HTabs from "./HkTabs";
+import { useBreakpoint } from "../runtime/useBreakpoint";
 import HModal from "./HkModal";
 import "./HkSettingsDialog.scss";
 
@@ -48,6 +50,15 @@ export interface HkSettingsSection {
  * SettingsShell.scss). Inside the dialog the modal body's own scroller is
  * made mathematically idle by the host height rule (see the SCSS); on a
  * page the host manages its own layout.
+ *
+ * Phone anatomy (2026-10-28 user direction): under the family's mobile
+ * breakpoint the left rail moves to the TOP of the window as the shared
+ * pill strip (HTabs) — horizontally scrollable with edge fades, so every
+ * section fits no matter how many entries a host offers — one notch
+ * larger than the regular strips, with a small gap before the pane.
+ * Desktop keeps the rail exactly as it was; the flip is live on resize
+ * and shared by every consumer of this shell (page-embedded bodies
+ * included).
  */
 export const HkSettingsBody = defineComponent({
   name: "HkSettingsBody",
@@ -63,7 +74,14 @@ export const HkSettingsBody = defineComponent({
     "update:section": (key: string) => typeof key === "string",
   },
   setup(props, { emit, slots }) {
-    const internal = ref(props.sections[0]?.key ?? "");
+    // The landing default is the FIRST USABLE section, never a disabled
+    // one: a disabled entry "renders but cannot be activated", so it must
+    // not win the default (R2 2026-10-28 — the old first-entry fallback
+    // let a disabled-first host open on a dead section, and the phone
+    // strip went further and FRAMED it as selected).
+    const firstUsable = () =>
+      props.sections.find((s) => !s.disabled)?.key ?? "";
+    const internal = ref(firstUsable());
     // Controlled while a section prop is bound: external changes flow in,
     // clicks flow out. Unbound: the internal ref alone decides. Immediate
     // so an opener that mounts ALREADY on a deep-linked section
@@ -86,7 +104,7 @@ export const HkSettingsBody = defineComponent({
     const active = () =>
       props.sections.some((s) => s.key === internal.value)
         ? internal.value
-        : (props.sections[0]?.key ?? "");
+        : firstUsable();
 
     // The pane is an HkScrollContainer; only its consumed ref slice is
     // typed here — the scroll reset needs the live viewport element and
@@ -103,42 +121,83 @@ export const HkSettingsBody = defineComponent({
     });
 
     function pick(key: string) {
+      // Belt-and-braces: every caller already refuses disabled entries
+      // upstream (rail: natively disabled buttons; strip: HTabs' disabled
+      // triggers + its keyboard guard; deep links: the section watch), so
+      // deleting this guard is provably behavior-neutral today (R3
+      // mutation M6, 2026-10-28). It stays so a future caller cannot
+      // bypass the contract by accident.
       const entry = props.sections.find((s) => s.key === key);
       if (!entry || entry.disabled) return;
       internal.value = key;
       emit("update:section", key);
     }
 
+    // Phone flips the nav to the top strip; desktop keeps the rail. One
+    // breakpoint source (useBreakpoint) drives BOTH the DOM branch and
+    // the data-phone attribute the SCSS keys the column layout on, so
+    // the two halves cannot drift (see the SCSS block for the layout).
+    const { isMobile } = useBreakpoint();
+
     return () => (
-      <div class="hk-settings">
+      <div class="hk-settings" data-phone={isMobile.value || undefined}>
         {/* Scroll ownership (see the docblock): both scrollers are
             HkScrollContainers — the overlay chrome replaces the native
             bars, and the paired-class rules in the SCSS carry each
             region's padding/gap vocabulary into its viewport. */}
-        <HkScrollContainer as="nav" class="hk-settings__rail" aria-label={props.navLabel}>
-          {props.sections.map((s) => {
-            const Icon = s.icon;
-            const on = active() === s.key && !s.disabled;
-            return (
-              <button
-                key={s.key}
-                type="button"
-                class={["hk-settings__rail-item", on ? "is-active" : ""]}
-                aria-current={on ? "true" : undefined}
-                aria-disabled={s.disabled || undefined}
-                disabled={s.disabled}
-                onClick={() => pick(s.key)}
-              >
-                {typeof Icon === "function" ? (
-                  <span class="hk-settings__rail-icon" aria-hidden="true">
-                    <Icon size={16} />
-                  </span>
-                ) : null}
-                <span class="hk-settings__rail-label">{s.label}</span>
-              </button>
-            );
-          })}
-        </HkScrollContainer>
+        {isMobile.value ? (
+          <div class="hk-settings__topnav">
+            {/* The shared pill strip IS the button-group primitive: it
+                scrolls horizontally with edge fades, keeps the active
+                tab scrolled into view, and carries the tablist
+                semantics the rail had as a nav landmark. Panels stay
+                with the shell's own pane (renderPanels off). Icons ride
+                one notch up with the strip (18px vs the rail's 16). */}
+            <HTabs
+              modelValue={active()}
+              tabs={props.sections.map((s) => {
+                const Icon = s.icon;
+                return {
+                  key: s.key,
+                  label: s.label,
+                  // Same functional-component guard the rail applies —
+                  // Component covers object-form components too, which
+                  // JSX cannot invoke directly.
+                  icon: typeof Icon === "function" ? <Icon size={18} /> : undefined,
+                  disabled: s.disabled,
+                };
+              })}
+              renderPanels={false}
+              ariaLabel={props.navLabel}
+              onUpdate:modelValue={(key: string) => pick(key)}
+            />
+          </div>
+        ) : (
+          <HkScrollContainer as="nav" class="hk-settings__rail" aria-label={props.navLabel}>
+            {props.sections.map((s) => {
+              const Icon = s.icon;
+              const on = active() === s.key && !s.disabled;
+              return (
+                <button
+                  key={s.key}
+                  type="button"
+                  class={["hk-settings__rail-item", on ? "is-active" : ""]}
+                  aria-current={on ? "true" : undefined}
+                  aria-disabled={s.disabled || undefined}
+                  disabled={s.disabled}
+                  onClick={() => pick(s.key)}
+                >
+                  {typeof Icon === "function" ? (
+                    <span class="hk-settings__rail-icon" aria-hidden="true">
+                      <Icon size={16} />
+                    </span>
+                  ) : null}
+                  <span class="hk-settings__rail-label">{s.label}</span>
+                </button>
+              );
+            })}
+          </HkScrollContainer>
+        )}
         <HkScrollContainer class="hk-settings__pane" ref={paneRef}>
           {/* The section swap runs through the family's standard morph
               container (audit 2026-10-23): the pane's frame follows the

package/src/components/HkTreemap.test.tsx

@@ -229,18 +229,13 @@ describe("HkTreemap pure layout input", () => {
     ).toEqual({ nodes: [], total: 0 });
   });
 
-  it("chooses readable label colours across pale, mid-tone and dark backgrounds", () => {
-    expect(contrastTextColor("#edc948")).toBe("#0b1220");
-    expect(contrastTextColor("#4e79a7")).toBe("#fff");
-    expect(contrastTextColor("#76b7b2")).toBe("#0b1220");
-    expect(contrastTextColor("rgb(242, 142, 43)")).toBe("#0b1220");
-    expect(contrastTextColor("#abc")).toBe("#0b1220");
-    expect(contrastTextColor("hsl(0, 0%, 100%)")).toBe("#0b1220");
-    expect(contrastTextColor("not-a-color")).toBe("#fff");
-    // Every default palette member must clear WCAG AA with its chosen text.
-    for (const color of HK_TREEMAP_DEFAULT_COLORS) {
-      expect(["#fff", "#0b1220"]).toContain(contrastTextColor(color));
-    }
+  it("cell labels follow the theme icon/text token, not a per-block flip", () => {
+    // User direction 2026-10-28: cells read like icon glyphs — white on the
+    // dark theme via rgb(var(--color-text)), the same vocabulary as
+    // HkIconButton; the token flips the ink in the light theme.
+    expect(contrastTextColor("#edc948")).toBe("rgb(var(--color-text, 30 30 30))");
+    expect(contrastTextColor("#4e79a7")).toBe("rgb(var(--color-text, 30 30 30))");
+    expect(contrastTextColor("not-a-color")).toBe("rgb(var(--color-text, 30 30 30))");
   });
 
   it("builds an accessible leaf-path summary from the same layout", () => {

package/src/components/HkTreemap.tsx

@@ -144,21 +144,18 @@ function resolveOpaqueColor(raw: string, fallback: string): string {
   return `rgb(${Math.round(channels[0])} ${Math.round(channels[1])} ${Math.round(channels[2])})`;
 }
 
-/** Pick the higher-contrast label colour for an opaque CSS background. */
-export function contrastTextColor(background: string): string {
-  const channels = parseCssColor(background);
-  if (!channels || channels[3] < 0.999) return "#fff";
-  // sRGB relative luminance, with the standard gamma expansion. The two
-  // candidate text colours (#fff / #0b1220) cross at luminance ~= 0.193.
-  const linear = (channel: number) => {
-    const value = channel / 255;
-    return value <= 0.03928 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
-  };
-  const luminance =
-    0.2126 * linear(channels[0]) +
-    0.7152 * linear(channels[1]) +
-    0.0722 * linear(channels[2]);
-  return luminance > 0.193 ? "#0b1220" : "#fff";
+/**
+ * Cell label colour — user direction 2026-10-28: the text inside the colour
+ * blocks should read like the family's icon glyphs (WHITE on the dark
+ * theme), not a per-block black/white flip that made mid-tone cells carry
+ * dark text. So the foreground simply follows the theme's icon/text token
+ * (`--hi-icon-color` resolves to `rgb(var(--color-text))`), the same
+ * vocabulary HkIconButton uses; the light theme keeps dark ink via the same
+ * token. The background argument is kept for signature compatibility and
+ * intentionally unused.
+ */
+export function contrastTextColor(_background: string): string {
+  return "rgb(var(--color-text, 30 30 30))";
 }
 
 export const HK_TREEMAP_DEFAULT_COLORS = [