@celestia-island/hikari 0.45.8 → 0.46.0

package/package.json

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

package/src/DemoApp.tsx

@@ -5,7 +5,7 @@ import { computed, defineComponent, ref } from "vue";
 import { ChevronDown, ChevronUp, PackageOpen } from "lucide-vue-next";
 import { HIKARI_FONT_MONO } from "./theme/fontContext";
 import {
-  HButton, HIconButton, HTooltip, HBadge, HTag, HIcon, HSpinner,
+  HButton, HIconButton, HIconButtonGroup, HTooltip, HBadge, HTag, HIcon, HSpinner,
   HProgressBar, HProgressRing, HGaugeRing,
   HInput, HSearchInput, HNumberInput, HPasswordInput, HTextarea,
   HFileField,
@@ -158,6 +158,8 @@ export default defineComponent({
         : panel.value.checked.filter((k) => k !== key);
     }
     const tabs = ref({ active: "tab1", items: [{ key: "tab1", label: "Overview" }, { key: "tab2", label: "Details" }, { key: "tab3", label: "Settings" }] });
+    const iconGroupPick = ref<string | null>("totp");
+    const iconGroupMulti = ref<string[]>(["flag"]);
     const mediaSliderRatio = ref(0.42);
     const demoAudioSrc = makeSilentWav();
     const demoImageSrc =
@@ -271,6 +273,40 @@ export default defineComponent({
           </div>
         </section>
 
+        <section>
+          <h2>HIconButtonGroup</h2>
+          <div class="row" style={{ flexDirection: "column", gap: "12px", alignItems: "flex-start" }}>
+            <HIconButtonGroup
+              mode="single"
+              modelValue={iconGroupPick.value}
+              onUpdate:modelValue={(v: string | string[]) => (iconGroupPick.value = v as string)}
+              options={[
+                { key: "totp", label: "验证器 App (TOTP)", icon: <HIcon name="settings" size={20} /> },
+                { key: "passkey", label: "Passkey", icon: <HIcon name="key" size={20} /> },
+                { key: "sms", label: "短信验证码", icon: <HIcon name="send" size={20} /> },
+              ]}
+            />
+            <HIconButtonGroup
+              mode="buttons"
+              size="sm"
+              options={[
+                { key: "github", label: "GitHub" },
+                { key: "linuxdo", label: "LinuxDo" },
+              ]}
+            />
+            <HIconButtonGroup
+              mode="multiple"
+              modelValue={iconGroupMulti.value}
+              onUpdate:modelValue={(v: string | string[]) => (iconGroupMulti.value = v as string[])}
+              options={[
+                { key: "alarm", label: "Alarm", icon: <HIcon name="bell" size={20} /> },
+                { key: "star", label: "Star", icon: <HIcon name="star" size={20} />, disabled: true },
+                { key: "flag", label: "Flag", icon: <HIcon name="flag" size={20} /> },
+              ]}
+            />
+          </div>
+        </section>
+
         <section>
           <h2>HTooltip</h2>
           <div class="row">

package/src/components/HkAuthMethodList.scss

@@ -1,7 +1,8 @@
-/* Full-width stacked alternative sign-in buttons (login card). The block
-   container `.s-auth-methods` and its spacing are owned by HkAuthCard's
-   slot styles (styles/admin-tokens.scss); this file only styles the
-   divider and the buttons the component renders into that slot. */
+/* Alternative sign-in methods as an icon button group (login card). The
+   block container `.s-auth-methods` and its spacing are owned by
+   HkAuthCard's slot styles (styles/admin-tokens.scss); this file only
+   styles the divider and the icon group row the component renders into
+   that slot. */
 
 /* "Other ways to sign in" divider row between rules. */
 .s-auth-methods-divider {
@@ -22,44 +23,17 @@
   background: var(--hi-color-border, #646464);
 }
 
-/* The component's own wrapper is `display: contents` (measurement anchor +
-   CSS-var inheritance) — layout-wise the buttons remain direct children of
-   HkAuthCard's `.s-auth-methods` slot container. */
+/* The component's own wrapper is `display: contents` — layout-wise the
+   divider and the group row remain direct children of HkAuthCard's
+   `.s-auth-methods` slot container. */
 .s-auth-methods-list {
   display: contents;
 }
 
-/* Fixed icon + label columns: the two spans keep the same width on every
-   row, so icons and labels align across buttons while each button stays a
-   centered hk-btn-block. The part classes sit on the default-slot spans
-   inside HkButton's single <button> root — scope everything off the
-   `.s-auth-methods` container (descendant match: the component wrapper
-   is display:contents).
-   The label column width is MEASURED by the component (widest label text
-   + 1px headroom, published as `--auth-methods-label-width` on its
-   wrapper, inherited into the rows); the `max-content` fallback only
-   covers the pre-measure / un-measurable frame, and apps may still
-   override the var explicitly. Labels are centered within the shared
-   column so every row's text sits on the same vertical center line. */
-.s-auth-methods .hk-btn .s-auth-methods-icon {
-  width: 20px;
-  flex: none;
-  display: inline-flex;
-  align-items: center;
+/* The icon button group row: fill the card column and center the
+   provider tiles inside it (descendant match off `.s-auth-methods` —
+   the wrapper generates no box of its own). */
+.s-auth-methods .hk-icon-group.s-auth-methods-group {
+  width: 100%;
   justify-content: center;
 }
-
-.s-auth-methods .hk-btn .s-auth-methods-label {
-  width: var(--auth-methods-label-width, max-content);
-  /* Hardened floor: even if the published column were ever stale or too
-     narrow (engine DPR / zoom mismatch), the label can never be clipped —
-     the row just widens to its own text. When the measurement is correct
-     the var already exceeds every label's natural width, so the floor is
-     inert and alignment is preserved. */
-  min-width: max-content;
-  flex: none;
-  text-align: center;
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
-}

package/src/components/HkAuthMethodList.test.tsx

@@ -19,6 +19,7 @@ afterEach(() => {
     app.unmount();
     container.remove();
   }
+  for (const popup of [...document.querySelectorAll(".hk-tooltip-popup")]) popup.remove();
 });
 
 const methods = [
@@ -27,102 +28,83 @@ const methods = [
 ];
 
 describe("HkAuthMethodList", () => {
-  it("renders one fixed-column button per method and an optional divider", () => {
+  it("renders the provider row as an icon button group with an optional divider", () => {
     // The card's `methods` slot owns the `.s-auth-methods` container —
-    // reproduce that context here (the buttons are layout children of it
-    // through the component's display:contents wrapper).
+    // reproduce that context here (the divider and the group row are layout
+    // children of it through the component's display:contents wrapper).
     const c = mount(
       h("div", { class: "s-auth-methods" }, h(HkAuthMethodList, { divider: "其他方式登录", methods })),
     );
     const divider = c.querySelector(".s-auth-methods-divider");
     expect(divider?.textContent).toContain("其他方式登录");
-    const buttons = c.querySelectorAll<HTMLButtonElement>(".s-auth-methods .hk-btn");
+    const group = c.querySelector<HTMLElement>(".s-auth-methods .hk-icon-group");
+    expect(group).toBeTruthy();
+    expect(group!.classList.contains("hk-icon-group-buttons")).toBe(true);
+    const buttons = c.querySelectorAll<HTMLButtonElement>(".s-auth-methods .hk-icon-group-item");
     expect(buttons.length).toBe(2);
-    const labels = [...buttons].map(
-      (b) => b.querySelector<HTMLElement>(".s-auth-methods-label")?.textContent,
+    // Icon-only: the label is the accessible name + tooltip, never visible text.
+    expect(buttons[0]!.getAttribute("aria-label")).toBe("GitHub");
+    expect(buttons[1]!.getAttribute("aria-label")).toBe("LinuxDo");
+    expect(buttons[0]!.textContent).not.toContain("GitHub");
+  });
+
+  it("wraps every item in a tooltip carrying the provider label", () => {
+    const c = mount(
+      h("div", { class: "s-auth-methods" }, h(HkAuthMethodList, { methods })),
     );
-    expect(labels).toEqual(["GitHub", "LinuxDo"]);
-    for (const b of buttons) {
-      expect(b.querySelector(".s-auth-methods-icon")).toBeTruthy();
-      expect(b.classList.contains("hk-btn-block")).toBe(true);
-    }
+    const wrappers = c.querySelectorAll(".hk-tooltip-wrapper");
+    expect(wrappers.length).toBe(2);
+    // The teleported popups exist with the label text (hidden until hover).
+    const popups = [...document.querySelectorAll(".hk-tooltip-popup .hk-tooltip-content")]
+      .map((el) => el.textContent);
+    expect(popups).toContain("GitHub");
+    expect(popups).toContain("LinuxDo");
   });
 
   it("emits select with the method key on click", async () => {
-    let picked = "";
+    const picked: string[] = [];
     const c = mount(
       h("div", { class: "s-auth-methods" }, h(HkAuthMethodList, {
         methods,
         onSelect: (key: string) => {
-          picked = key;
+          picked.push(key);
         },
       })),
     );
-    const buttons = c.querySelectorAll<HTMLButtonElement>(".s-auth-methods .hk-btn");
+    const buttons = c.querySelectorAll<HTMLButtonElement>(".s-auth-methods .hk-icon-group-item");
     buttons[1]!.click();
     await nextTick();
-    expect(picked).toBe("linuxdo");
-  });
-
-  it("publishes the widest label text plus a 1px headroom as the label-column custom property", async () => {
-    const c = mount(h("div", { class: "s-auth-methods" }, h(HkAuthMethodList, { methods })));
-    await nextTick();
-    const wrapper = c.querySelector<HTMLElement>(".s-auth-methods-list")!;
-    expect(wrapper).toBeTruthy();
-    // Layout engines in test DOM report zero text metrics; stub a fractional
-    // getBoundingClientRect width on the label spans so the widest-wins pair
-    // (LinuxDo wider) exercises the ceil+1 headroom instead of the integer
-    // scrollWidth that would previously round a fraction and clip the widest.
-    const spans = [...wrapper.querySelectorAll<HTMLElement>(".s-auth-methods-label")];
-    expect(spans.length).toBe(2);
-    // 61.4 ceil→62 (+1→63) and a shorter 58.0: the published column must
-    // exceed BOTH so the widest label can never sit on the clip boundary.
-    Object.defineProperty(spans[0]!, "getBoundingClientRect", { configurable: true, value: () => ({ width: 58 }) });
-    Object.defineProperty(spans[1]!, "getBoundingClientRect", { configurable: true, value: () => ({ width: 61.4 }) });
-    await nextTick();
-    // Re-run measurement via a re-mount-less route: the component exposes
-    // measure() — reach it through the rendered component instance.
-    const instance = (wrapper as unknown as { __vueParentComponent?: { exposed?: Record<string, unknown> } })
-      .__vueParentComponent?.exposed;
-    expect(typeof instance?.measure).toBe("function");
-    (instance!.measure as () => void)();
-    expect(wrapper.style.getPropertyValue("--auth-methods-label-width")).toBe("63px");
-  });
-
-  it("publishes a width in the column's own units inside a scaled root", async () => {
-    // The labels are measured where they are DRAWN while the custom property
-    // is a CSS length the column is laid out with: in a scaled or zoomed root
-    // the published column would come out that many times too wide.
-    const c = mount(h("div", { class: "s-auth-methods" }, h(HkAuthMethodList, { methods })));
+    // Both rows are asserted so a constant-literal emit cannot ride an
+    // accidental fixture coincidence.
+    buttons[0]!.click();
     await nextTick();
-    const wrapper = c.querySelector<HTMLElement>(".s-auth-methods-list")!;
-    const spans = [...wrapper.querySelectorAll<HTMLElement>(".s-auth-methods-label")];
-    // The scale has to come from a LABEL: the list is `display: contents` and
-    // generates no box at all (Blink reports offsetWidth 0 and a 0x0 rect), so
-    // stubbing a box on the list would only ever be green by accident.
-    for (const [i, drawn] of [58, 61.4].entries()) {
-      Object.defineProperty(spans[i]!, "getBoundingClientRect", {
-        configurable: true,
-        value: () => ({ left: 0, top: 0, right: drawn * 2, bottom: 40, width: drawn * 2, height: 40, x: 0, y: 0 }) as DOMRect,
-      });
-      // Laid out at half: the label is drawn twice the size it is laid out at.
-      Object.defineProperty(spans[i]!, "offsetWidth", { configurable: true, get: () => drawn });
-      Object.defineProperty(spans[i]!, "offsetHeight", { configurable: true, get: () => 20 });
-    }
-    const instance = (wrapper as unknown as { __vueParentComponent?: { exposed?: Record<string, unknown> } })
-      .__vueParentComponent?.exposed;
-    (instance!.measure as () => void)();
-    // 122.8 drawn are 61.4 of the column's own: ceil 62, plus the 1px headroom.
-    // Reading the scale off the LIST instead — the shape this shipped with —
-    // yields 1 for a `display: contents` element and publishes the drawn 124px.
-    expect(wrapper.style.getPropertyValue("--auth-methods-label-width")).toBe("63px");
+    expect(picked).toEqual(["linuxdo", "github"]);
   });
 
-  it("leaves the column fallback intact when no text metrics are available", async () => {
-    const c = mount(h("div", { class: "s-auth-methods" }, h(HkAuthMethodList, { methods })));
+  it("renders the icon vnode and honors disabled entries", async () => {
+    let picked = "";
+    const c = mount(
+      h("div", { class: "s-auth-methods" }, h(HkAuthMethodList, {
+        methods: [
+          { key: "gh", label: "GitHub", icon: h("span", { class: "brand-gh" }) },
+          { key: "ld", label: "LinuxDo", disabled: true },
+          { key: "fs", label: "Feishu" },
+        ],
+        onSelect: (key: string) => {
+          picked = key;
+        },
+      })),
+    );
+    const buttons = c.querySelectorAll<HTMLButtonElement>(".s-auth-methods .hk-icon-group-item");
+    expect(buttons.length).toBe(3);
+    // The prebuilt brand vnode renders inside the icon column.
+    expect(buttons[0]!.querySelector(".brand-gh")).toBeTruthy();
+    // A missing icon falls back to the label initial (never an empty box).
+    expect(buttons[2]!.querySelector<HTMLElement>(".hk-icon-group-item-initial")?.textContent).toBe("F");
+    // Disabled entries render dead and swallow clicks.
+    expect(buttons[1]!.disabled).toBe(true);
+    buttons[1]!.click();
     await nextTick();
-    const wrapper = c.querySelector<HTMLElement>(".s-auth-methods-list")!;
-    // Zero text metrics (no layout) must not publish a 0px or a 1px column.
-    expect(wrapper.style.getPropertyValue("--auth-methods-label-width")).toBe("");
+    expect(picked).toBe("");
   });
 });

package/src/components/HkAuthMethodList.tsx

@@ -1,37 +1,30 @@
-import { defineComponent, nextTick, onBeforeUnmount, onMounted, ref, watch } from "vue";
-import HkButton from "./HkButton";
-import { drawnScale } from "../composables/layoutGeometry";
+import { defineComponent } from "vue";
+import HkIconButtonGroup from "./HkIconButtonGroup";
 import "./HkAuthMethodList.scss";
 
 /**
- * HkAuthMethodList — full-width stacked third-party sign-in buttons for
- * auth cards (the ERP login's provider-button grammar, componentized).
+ * HkAuthMethodList — the auth card's third-party sign-in block (the
+ * "other ways to sign in" row under the credentials form).
  *
- * Every button renders [icon | label] with a FIXED icon column and a FIXED
- * label column, so the icons and the label text start at the same x on
- * every row regardless of label length; because every content block is
- * then the same width, the row can stay centered like any HkButton
- * without the columns drifting.
+ * Since 2026-09-13 (user direction) the block renders as the ICON
+ * BUTTON GROUP by default: one centered `HkIconButtonGroup` row of
+ * icon-only provider buttons (mode "buttons", size md) instead of the
+ * stacked full-width [icon | label] buttons. Provider identity is
+ * revealed on hover — every item wraps itself in an HkTooltip with the
+ * provider label — which matches the platform login-chooser pattern
+ * (Windows/macOS account tiles) and keeps the card compact when a
+ * deployment offers several providers. The `select` event carries the
+ * provider `key` exactly as before, so consumers swap rendering
+ * without touching their OAuth flow.
  *
- * The label column is auto-sized: after mount (and whenever the label set,
- * the document fonts, the browser zoom, or the container size change) the
- * component measures the widest label text and publishes it as
- * `--auth-methods-label-width` on its wrapper, so the aligned text region
- * hugs the longest label instead of a blind hardcoded width. The measured
- * fraction is rounded UP with a 1px margin — the column is always strictly
- * wider than the longest label, so the text can never overflow into an
- * ellipsis. Labels are centered within that shared column, keeping every
- * row's text on the same vertical center line. Consumers can still
- * override the var explicitly.
- *
- * The wrapper is `display: contents`: the component keeps a DOM node for
- * measurement and CSS-var inheritance while the buttons remain direct
- * layout children of HkAuthCard's `.s-auth-methods` slot container.
+ * The wrapper stays `display: contents`: the divider and the group row
+ * remain layout children of HkAuthCard's `.s-auth-methods` slot
+ * container (it owns the side padding and vertical rhythm).
  */
 export default defineComponent({
   name: "HkAuthMethodList",
   props: {
-    /** Optional divider text rendered above the buttons, e.g. "其他方式登录".
+    /** Optional divider text rendered above the row, e.g. "其他方式登录".
      *  Consumer-localized on purpose: hikari ships no dictionary dependency
      *  onto hosts here. */
     divider: { type: String, default: "" },
@@ -39,13 +32,14 @@ export default defineComponent({
     methods: {
       type: Array as unknown as () => Array<{
         key: string;
+        /** Accessible name + tooltip text (the hover reveal). */
         label: string;
-        /** Prebuilt icon vnode (brand SVG, <img>, …) — `null` renders an
-         *  empty fixed-width column so the labels still align. Typed loose
-         *  on purpose (same as HkAltSignIn entries): hosts materialize
-         *  hikari against their own vue store, and a hard VNode type
-         *  breaks typecheck whenever the host's vue minor differs. The
-         *  value renders as-is inside the fixed-size column. */
+        /** Prebuilt icon vnode (brand SVG, <img>, …) rendered inside the
+         *  icon-only button. Typed loose on purpose (same as
+         *  HkIconButtonGroup options): hosts materialize hikari against
+         *  their own vue store, and a hard VNode type breaks typecheck
+         *  whenever the host's vue minor differs. A missing icon falls
+         *  back to the label's initial. */
         icon?: unknown;
         disabled?: boolean;
       }>,
@@ -53,132 +47,29 @@ export default defineComponent({
     },
   },
   emits: {
-    /** A method button was clicked. */
+    /** A provider button was clicked. */
     select: (_key: string) => true,
   },
-  setup(props, { emit, expose }) {
-    const listRef = ref<HTMLDivElement | null>(null);
-
-    let resizeObserver: ResizeObserver | undefined;
-    const onResize = () => void nextTick(measure);
-    const onFontsReady = () => measure();
-
-    /** Measure the widest label text and publish it as the label-column
-     *  width custom property. Each span is momentarily set to
-     *  `max-content` while reading: a plain `scrollWidth` on the fixed
-     *  column would report `max(textWidth, columnWidth)` and the column
-     *  could never shrink below its fallback. All reads happen inside one
-     *  synchronous task, so no intermediate paint is observable.
-     *
-     *  Precision: the widest width is read as a fractional
-     *  `getBoundingClientRect()` (not the integer `scrollWidth`) and
-     *  rounded UP with a 1px margin before publishing. An integer read can
-     *  round the longest label DOWN (some engines floor it), pinning its
-     *  column exactly on the glyph boundary — then any sub-pixel
-     *  font-metric difference (zoom, DPR, engine) makes that one label
-     *  overflow and render an ellipsis while the shorter rows stay fine.
-     *  The headroom keeps the longest label strictly inside its column. */
-    function measure() {
-      const root = listRef.value;
-      if (!root) return;
-      let widest = 0;
-      // The labels are measured where they are DRAWN, and the width is
-      // published as a CSS length the column is laid out with: in a scaled or
-      // zoomed root the two differ by the scale of the space, so the column
-      // would come out that many times too wide (see `layoutGeometry`).
-      //
-      // The scale is read from the LABEL — the element the box was measured
-      // on. Reading it from the list itself cannot work: the list is
-      // `display: contents`, so it generates no box at all (measured in Blink:
-      // `offsetWidth` 0, a 0x0 rect, computed width `auto`), and every reader
-      // of a box reports nothing to divide by.
-      for (const label of root.querySelectorAll<HTMLElement>(".s-auth-methods-label")) {
-        const previous = label.style.width;
-        label.style.width = "max-content";
-        const drawn = label.getBoundingClientRect().width;
-        const scale = drawnScale(label);
-        const factor = Number.isFinite(scale.x) && scale.x > 0 ? scale.x : 1;
-        // `offsetWidth` is the laid-out fallback — already in the units the
-        // published length is used in, so it needs no division.
-        widest = Math.max(widest, factor > 0 ? drawn / factor : label.offsetWidth);
-        label.style.width = previous;
-      }
-      // Guard: only publish when real text metrics were observed, so a
-      // hidden / zero-size frame keeps the CSS `max-content` fallback
-      // instead of collapsing the column to a clipping 1px.
-      if (widest > 0) {
-        root.style.setProperty("--auth-methods-label-width", `${Math.ceil(widest) + 1}px`);
-      }
-      // Keep observing every rendered row so a layout change (the panel
-      // becoming visible, a container width change) re-measures. Rows are
-      // full-width `.hk-btn-block`, so publishing the column width never
-      // resizes them (no feedback loop into the observer).
-      if (resizeObserver) {
-        for (const button of root.querySelectorAll<HTMLElement>(".hk-btn")) {
-          resizeObserver.observe(button);
-        }
-      }
-    }
-
-    onMounted(() => {
-      void nextTick(measure);
-      // Webfonts change text metrics after first paint; re-measure when
-      // they finish loading (no-op in environments without document.fonts).
-      if (typeof document !== "undefined" && document.fonts) {
-        void document.fonts.ready.then(measure).catch(() => {});
-        document.fonts.addEventListener?.("loadingdone", onFontsReady);
-      }
-      // Browser zoom and container-width changes reflow the text; without a
-      // re-measure the published column goes stale and the longest label
-      // overflows into the ellipsis. `resize` covers page zoom; the
-      // ResizeObserver covers the panel appearing / the container resizing.
-      if (typeof window !== "undefined") {
-        window.addEventListener("resize", onResize);
-        if (!resizeObserver && typeof ResizeObserver !== "undefined") {
-          resizeObserver = new ResizeObserver(onResize);
-        }
-      }
-    });
-    onBeforeUnmount(() => {
-      listRef.value?.style.removeProperty("--auth-methods-label-width");
-      resizeObserver?.disconnect();
-      resizeObserver = undefined;
-      if (typeof window !== "undefined") {
-        window.removeEventListener("resize", onResize);
-      }
-      if (typeof document !== "undefined" && document.fonts) {
-        document.fonts.removeEventListener?.("loadingdone", onFontsReady);
-      }
-    });
-    watch(
-      () => props.methods.map((method) => method.label).join("\u0000"),
-      () => {
-        void nextTick(measure);
-      },
-    );
-
-    expose({ measure });
-
+  setup(props, { emit }) {
     return () => (
-      <div class="s-auth-methods-list" ref={listRef}>
+      <div class="s-auth-methods-list">
         {props.divider && (
           <div class="s-auth-methods-divider">
             <span>{props.divider}</span>
           </div>
         )}
-        {props.methods.map((method) => (
-          <HkButton
-            key={method.key}
-            variant="outline"
-            size="md"
-            block
-            disabled={method.disabled === true}
-            onClick={() => emit("select", method.key)}
-          >
-            <span class="s-auth-methods-icon">{method.icon}</span>
-            <span class="s-auth-methods-label">{method.label}</span>
-          </HkButton>
-        ))}
+        <HkIconButtonGroup
+          class="s-auth-methods-group"
+          mode="buttons"
+          size="md"
+          options={props.methods.map((method) => ({
+            key: method.key,
+            label: method.label,
+            icon: method.icon,
+            disabled: method.disabled === true,
+          }))}
+          onSelect={(key: string) => emit("select", key)}
+        />
       </div>
     );
   },

package/src/components/HkCrossfade.scss

@@ -0,0 +1,61 @@
+/* HkCrossfade — same-position simultaneous dissolve host.
+ *
+ * Geometry: the host is a one-cell grid and every item occupies THAT cell
+ * (grid-area: 1/1). During a swap the leaving item keeps the cell, so old
+ * and new stack in the SAME box: no exit blank phase, no side-by-side
+ * reflow, and the host stays as tall as the taller of the two items until
+ * the leave completes — variable-height content never collapses mid-
+ * dissolve. This is the height-safe generalization of HkPickerPane's fixed
+ * stage + absolute leave (no known stage size needed, so whole pages can
+ * swap through it).
+ *
+ * Consumers size the host from the outside (width/height/flex are theirs);
+ * the component only guarantees the stacking geometry and the dissolve.
+ */
+.hk-crossfade {
+  display: grid;
+
+  > .hk-crossfade-item {
+    grid-area: 1 / 1;
+    width: 100%;
+    min-width: 0;
+  }
+}
+
+/* Dissolve curves: BOTH sides run --duration-normal so the exchange is a
+ * true cross-fade (not a fade-out-then-in), and both ease OUT (fast
+ * start) — midway through the swap the incoming layer already carries most
+ * of the opacity while the outgoing one has already shed most of its, so
+ * the composite never dips toward the background (the classic
+ * double-exposure artifact of symmetric linear fades). The leaving item
+ * also drops pointer events: it is dead content and must not intercept
+ * clicks while it dissolves under the incoming one. */
+.hk-crossfade-enter-active {
+  transition:
+    opacity
+    var(--duration-normal, 0.3s)
+    var(--ease-out-expo, cubic-bezier(0.19, 1, 0.22, 1));
+}
+
+.hk-crossfade-leave-active {
+  transition: opacity var(--duration-normal, 0.3s) ease-out;
+  pointer-events: none;
+}
+
+.hk-crossfade-enter-from,
+.hk-crossfade-leave-to {
+  opacity: 0;
+}
+
+/* Reduced motion: keep the opacity exchange (a fade carries no movement —
+ * HkPhaseTransition precedent), just shorter. Hosts driving the global
+ * animation switch (`html[data-css-animations="0"]`) already pin every
+ * transition via theme.scss's global rule, so no extra variant is needed
+ * here (that variant exists for ANIMATIONS, which the global rule pauses
+ * per-play-state; transitions die through its transition-duration clamp). */
+@media (prefers-reduced-motion: reduce) {
+  .hk-crossfade-enter-active,
+  .hk-crossfade-leave-active {
+    transition: opacity var(--duration-fast, 0.15s) ease;
+  }
+}