@celestia-island/hikari 0.35.1 → 0.36.0

package/package.json

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

package/src/components/HkAuthCard.test.tsx

@@ -0,0 +1,259 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createApp, h } from "vue";
+
+import { HkAuthCard } from "./HkAuthCard";
+
+/** Injectable ResizeObserver: captures the callback so tests can fire
+ *  content changes deterministically (happy-dom's own RO never fires —
+ *  there is no layout engine). Same harness as useSizeMorph.test.ts. */
+class FakeResizeObserver {
+  static instances: FakeResizeObserver[] = [];
+  callback: () => void;
+  observed: Element[] = [];
+  disconnected = false;
+
+  constructor(callback: () => void) {
+    this.callback = callback;
+    FakeResizeObserver.instances.push(this);
+  }
+  observe(el: Element): void {
+    this.observed.push(el);
+  }
+  disconnect(): void {
+    this.disconnected = true;
+  }
+}
+
+const originalRO = globalThis.ResizeObserver;
+
+/** The prototype that actually defines `offsetHeight` in this DOM
+ *  implementation, so the stub below is portable across environments. */
+function offsetHeightOwner(): object {
+  let proto = Object.getPrototypeOf(document.createElement("div")) as object | null;
+  while (proto) {
+    if (Object.getOwnPropertyDescriptor(proto, "offsetHeight")) return proto;
+    proto = Object.getPrototypeOf(proto);
+  }
+  return HTMLElement.prototype;
+}
+
+const originalOffsetHeight = Object.getOwnPropertyDescriptor(
+  offsetHeightOwner(),
+  "offsetHeight",
+);
+
+/** Natural height every element reports for `offsetHeight` in tests. */
+let naturalHeight = 0;
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mount(node: ReturnType<typeof h>) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render: () => node });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+function cardOf(c: HTMLElement) {
+  return c.querySelector<HTMLElement>(".s-auth-card")!;
+}
+
+function wrapperOf(c: HTMLElement) {
+  return c.querySelector<HTMLElement>(".s-auth-card-height")!;
+}
+
+function fireTransitionEnd(el: HTMLElement, propertyName: string) {
+  const event = new Event("transitionend", { bubbles: true });
+  Object.defineProperty(event, "propertyName", { value: propertyName });
+  el.dispatchEvent(event);
+}
+
+beforeEach(() => {
+  FakeResizeObserver.instances = [];
+  naturalHeight = 140;
+  globalThis.ResizeObserver = FakeResizeObserver as unknown as typeof ResizeObserver;
+  Object.defineProperty(offsetHeightOwner(), "offsetHeight", {
+    configurable: true,
+    get: () => naturalHeight,
+  });
+});
+
+afterEach(() => {
+  globalThis.ResizeObserver = originalRO;
+  if (originalOffsetHeight) {
+    Object.defineProperty(offsetHeightOwner(), "offsetHeight", originalOffsetHeight);
+  } else {
+    delete (offsetHeightOwner() as { offsetHeight?: number }).offsetHeight;
+  }
+  vi.restoreAllMocks();
+  vi.useRealTimers();
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+});
+
+describe("HkAuthCard", () => {
+  it("renders title, subtitle and every slot inside the unchanged card shell", () => {
+    const c = mount(
+      h(HkAuthCard, { title: "Sign in", subtitle: "Welcome back" }, {
+        default: () => h("input", { name: "probe-field" }),
+        methods: () => h("div", { class: "probe-methods" }, "methods"),
+        footer: () => h("div", { class: "probe-footer" }, "footer"),
+      }),
+    );
+    // The measuring wrapper is present and the card is still `.s-auth-card`.
+    const wrapper = wrapperOf(c);
+    const card = cardOf(c);
+    expect(wrapper).toBeTruthy();
+    expect(card).toBeTruthy();
+    expect(c.querySelector(".s-auth-title")?.textContent).toBe("Sign in");
+    expect(c.querySelector(".s-auth-subtitle")?.textContent).toBe("Welcome back");
+    expect(card.querySelector(".s-auth-form input[name='probe-field']")).toBeTruthy();
+    expect(card.querySelector(".s-auth-methods .probe-methods")).toBeTruthy();
+    expect(card.querySelector(".s-auth-footer .probe-footer")).toBeTruthy();
+    // The wrapper is transparent to descendant styling: the header, form,
+    // methods and footer blocks all remain children of `.s-auth-card`.
+    expect(wrapper.querySelector(".s-auth-card")).toBe(card);
+  });
+
+  it("seeds the wrapper height from the card on mount without animating", () => {
+    naturalHeight = 140;
+    const c = mount(h(HkAuthCard, { title: "T" }));
+    const wrapper = wrapperOf(c);
+    expect(wrapper.style.height).toBe("140px");
+    // Seeding must not animate: the measuring class is absent on first paint.
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(false);
+    // The observer watches the card element itself, not the wrapper.
+    expect(FakeResizeObserver.instances).toHaveLength(1);
+    expect(FakeResizeObserver.instances[0]!.observed).toEqual([cardOf(c)]);
+  });
+
+  it("animates growth through the measuring class and releases it on the backstop timer", () => {
+    vi.useFakeTimers();
+    naturalHeight = 140;
+    const c = mount(h(HkAuthCard, { title: "T" }));
+    const wrapper = wrapperOf(c);
+    expect(wrapper.style.height).toBe("140px");
+
+    naturalHeight = 240;
+    FakeResizeObserver.instances[0]!.callback();
+    expect(wrapper.style.height).toBe("240px");
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(true);
+
+    vi.advanceTimersByTime(449);
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(true);
+    vi.advanceTimersByTime(1);
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(false);
+  });
+
+  it("releases the measuring class when the height transition finishes", () => {
+    naturalHeight = 100;
+    const c = mount(h(HkAuthCard, { title: "T" }));
+    const wrapper = wrapperOf(c);
+
+    naturalHeight = 180;
+    FakeResizeObserver.instances[0]!.callback();
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(true);
+
+    // An unrelated property finishing its transition must not release.
+    fireTransitionEnd(wrapper, "color");
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(true);
+
+    fireTransitionEnd(wrapper, "height");
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(false);
+  });
+
+  it("ignores height transitionsend events bubbling up from descendant content", () => {
+    naturalHeight = 100;
+    const c = mount(
+      h(HkAuthCard, { title: "T" }, { default: () => h("div", { class: "probe-anim" }) }),
+    );
+    const wrapper = wrapperOf(c);
+    const child = c.querySelector<HTMLElement>(".probe-anim")!;
+
+    naturalHeight = 180;
+    FakeResizeObserver.instances[0]!.callback();
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(true);
+
+    // A descendant slot element's own height transition bubbling up must
+    // NOT release the clip — it did not open this measuring window.
+    fireTransitionEnd(child, "height");
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(true);
+
+    // Only the wrapper's own height transition may end it.
+    fireTransitionEnd(wrapper, "height");
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(false);
+  });
+
+  it("snaps unclipped under prefers-reduced-motion without arming the backstop", () => {
+    vi.useFakeTimers();
+    vi.spyOn(window, "matchMedia").mockReturnValue({ matches: true } as unknown as MediaQueryList);
+    naturalHeight = 140;
+    const c = mount(h(HkAuthCard, { title: "T" }));
+    const wrapper = wrapperOf(c);
+
+    naturalHeight = 240;
+    FakeResizeObserver.instances[0]!.callback();
+    // Height still tracks the content…
+    expect(wrapper.style.height).toBe("240px");
+    // …but with the transition disabled there is nothing to animate, so
+    // no measuring window opens: no clip, no pending backstop timer.
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(false);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("ignores observer firings that move the height by less than a pixel", () => {
+    naturalHeight = 140;
+    const c = mount(h(HkAuthCard, { title: "T" }));
+    const wrapper = wrapperOf(c);
+
+    naturalHeight = 140.6;
+    FakeResizeObserver.instances[0]!.callback();
+    expect(wrapper.style.height).toBe("140px");
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(false);
+  });
+
+  it("with smoothHeight=false renders the wrapper but installs no measuring", () => {
+    naturalHeight = 140;
+    const c = mount(h(HkAuthCard, { title: "T", smoothHeight: false }));
+    const wrapper = wrapperOf(c);
+    // The wrapper still exists (stable DOM shape for consumers) but is
+    // completely unmanaged: no explicit height and no observer.
+    expect(wrapper).toBeTruthy();
+    expect(wrapper.style.height).toBe("");
+    expect(FakeResizeObserver.instances).toHaveLength(0);
+  });
+
+  it("degrades to an unmanaged wrapper when ResizeObserver is unavailable", () => {
+    (globalThis as { ResizeObserver?: unknown }).ResizeObserver = undefined;
+    naturalHeight = 140;
+    const c = mount(h(HkAuthCard, { title: "T" }));
+    const wrapper = wrapperOf(c);
+    expect(wrapper).toBeTruthy();
+    expect(wrapper.style.height).toBe("");
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(false);
+  });
+
+  it("disconnects the observer and clears the backstop on unmount", () => {
+    vi.useFakeTimers();
+    naturalHeight = 140;
+    const c = mount(h(HkAuthCard, { title: "T" }));
+    const ro = FakeResizeObserver.instances[0]!;
+
+    naturalHeight = 200;
+    ro.callback();
+    expect(wrapperOf(c).classList.contains("s-auth-card--measuring")).toBe(true);
+
+    // Pop the entry so the shared afterEach does not unmount it twice.
+    const entry = mounts.pop()!;
+    entry.app.unmount();
+    expect(ro.disconnected).toBe(true);
+    // The pending backstop timer was cleared on unmount: nothing is left
+    // scheduled (a leaked timer here would also fire releaseClip on a
+    // dead element).
+    expect(vi.getTimerCount()).toBe(0);
+  });
+});

package/src/components/HkAuthCard.tsx

@@ -1,4 +1,10 @@
-import { defineComponent, type PropType } from "vue";
+import { defineComponent, onBeforeUnmount, onMounted, ref } from "vue";
+
+/** Grace window that force-releases the `--measuring` clip if the height
+ *  `transitionend` never arrives (interrupted transition, backgrounded
+ *  tab, reduced-motion). Slightly longer than the 0.3s CSS height
+ *  transition so a normal completion is always released by the event. */
+const MEASURE_BACKSTOP_MS = 450;
 
 /**
  * HkAuthCard — the shared shell of every Celestia auth screen (login,
@@ -19,42 +25,162 @@ import { defineComponent, type PropType } from "vue";
  *   per-row centering; content that must sit on one row belongs inside
  *   one child element.
  * - `logo` swaps the header's logo slot; `default` is the form body.
+ *
+ * Smooth height contract:
+ * The card's content is consumer-driven and changes at runtime — channel
+ * tabs swap the OAuth `methods` list (3 buttons ↔ 1), validation banners
+ * appear, locale switches reflow labels — and the card's height would
+ * otherwise snap between the two layouts. The root card is therefore
+ * wrapped in a `.s-auth-card-height` measuring wrapper that owns an
+ * explicit `height` and animates toward whatever natural height the card
+ * grows or shrinks to:
+ *
+ * - On mount the wrapper seeds its `height` from the card's current
+ *   `offsetHeight` while the animating state is impossible, so the first
+ *   paint never animates.
+ * - A `ResizeObserver` on the card element (not the wrapper) fires when
+ *   the content-driven natural height changes. Changes smaller than 1px
+ *   are ignored to keep rounding noise from starting a cycle. A real
+ *   change adds the `s-auth-card--measuring` class — the ONLY place
+ *   `overflow: hidden` is applied — then rewrites the height, and the CSS
+ *   `height` transition animates the wrapper between the two sizes.
+ * - The clipping class is released by the wrapper's `transitionend`
+ *   (propertyName === "height") and, if that event never fires, by a
+ *   450ms backstop timer. Between animations the card carries no clip,
+ *   so its shadow, focus rings and popovers are never cut off at rest.
+ * - `smoothHeight: false` opts out entirely: the wrapper still renders
+ *   (the DOM shape stays stable for consumers) but no height style, no
+ *   observer and no listeners are installed, and height changes snap as
+ *   before. The prop is read ONCE at mount time — runtime toggles are
+ *   ignored, making it a static opt-out rather than a reactive switch
+ *   (remount with a changed `:key` to apply a new value).
+ * - Environments without `ResizeObserver` degrade the same way: instant
+ *   snap, no measurement, no clipping.
+ * - `prefers-reduced-motion: reduce` disables the transition in CSS, so
+ *   the height still tracks the content, just without animation. While
+ *   it matches, the observer updates the height directly WITHOUT opening
+ *   a measuring window — no clip and no backstop timer — because a clip
+ *   held for the backstop would cut off the card's shadow with nothing
+ *   animating to mask it.
+ *
+ * The wrapper is transparent to descendant styling: nothing inside
+ * `.s-auth-card` changes, and no hikari stylesheet targets the card as a
+ * direct child. Only consumer styles that select `.s-auth-card` as a
+ * DIRECT child of a specific parent must account for the extra wrapper
+ * (e.g. `.us-main > .s-auth-card` becomes
+ * `.us-main > .s-auth-card-height > .s-auth-card`).
  */
 export const HkAuthCard = defineComponent({
   name: "HkAuthCard",
   props: {
     title: { type: String, required: true },
     subtitle: { type: String, default: "" },
+    smoothHeight: { type: Boolean, default: true },
   },
   setup(props, { slots }) {
+    const heightEl = ref<HTMLElement | null>(null);
+    const cardEl = ref<HTMLElement | null>(null);
+
+    let observer: ResizeObserver | null = null;
+    let backstopTimer: ReturnType<typeof setTimeout> | null = null;
+
+    /** End the current measuring window: drop the clip and the backstop. */
+    const releaseClip = () => {
+      if (backstopTimer !== null) {
+        clearTimeout(backstopTimer);
+        backstopTimer = null;
+      }
+      heightEl.value?.classList.remove("s-auth-card--measuring");
+    };
+
+    const onTransitionEnd = (event: TransitionEvent) => {
+      // Only the wrapper's OWN height transition may release the clip —
+      // a descendant slot element's height transition bubbling up must
+      // not end a measuring window it did not open.
+      if (event.target !== heightEl.value) return;
+      if (event.propertyName !== "height") return;
+      releaseClip();
+    };
+
+    onMounted(() => {
+      if (!props.smoothHeight) return;
+      const wrapper = heightEl.value;
+      const card = cardEl.value;
+      if (!wrapper || !card || typeof ResizeObserver === "undefined") return;
+
+      // Seed the explicit height BEFORE any animating class exists, so
+      // the first paint (wrapper already at the natural size) never
+      // animates.
+      wrapper.style.height = `${card.offsetHeight}px`;
+      wrapper.addEventListener("transitionend", onTransitionEnd);
+
+      observer = new ResizeObserver(() => {
+        const next = card.offsetHeight;
+        const current = parseFloat(wrapper.style.height) || 0;
+        // Ignore sub-pixel churn — rounding noise must not start a
+        // clip-and-animate cycle.
+        if (Math.abs(next - current) < 1) return;
+
+        // Reduced motion: the CSS transition is `none`, so transitionend
+        // will never fire and the clip would just sit there for the
+        // backstop window, cutting off the shadow with nothing to mask.
+        // Snap unclipped instead — no class, no timer.
+        if (window.matchMedia("(prefers-reduced-motion: reduce)").matches) {
+          wrapper.style.height = `${next}px`;
+          return;
+        }
+
+        // Clip ONLY while a height transition is actually running; the
+        // class is released by transitionend or the backstop timer.
+        wrapper.classList.add("s-auth-card--measuring");
+        wrapper.style.height = `${next}px`;
+
+        if (backstopTimer !== null) clearTimeout(backstopTimer);
+        backstopTimer = setTimeout(releaseClip, MEASURE_BACKSTOP_MS);
+      });
+      observer.observe(card);
+    });
+
+    onBeforeUnmount(() => {
+      observer?.disconnect();
+      observer = null;
+      heightEl.value?.removeEventListener("transitionend", onTransitionEnd);
+      if (backstopTimer !== null) {
+        clearTimeout(backstopTimer);
+        backstopTimer = null;
+      }
+    });
+
     return () => (
-      <div class="s-auth-card">
-        {slots.logo && (
-          <div class="s-auth-header">
-            {slots.logo()}
-            <h1 class="s-auth-title">{props.title}</h1>
-            {props.subtitle && <p class="s-auth-subtitle">{props.subtitle}</p>}
-          </div>
-        )}
-        {!slots.logo && (
-          <div class="s-auth-header">
-            <h1 class="s-auth-title">{props.title}</h1>
-            {props.subtitle && <p class="s-auth-subtitle">{props.subtitle}</p>}
+      <div class="s-auth-card-height" ref={heightEl}>
+        <div class="s-auth-card" ref={cardEl}>
+          {slots.logo && (
+            <div class="s-auth-header">
+              {slots.logo()}
+              <h1 class="s-auth-title">{props.title}</h1>
+              {props.subtitle && <p class="s-auth-subtitle">{props.subtitle}</p>}
+            </div>
+          )}
+          {!slots.logo && (
+            <div class="s-auth-header">
+              <h1 class="s-auth-title">{props.title}</h1>
+              {props.subtitle && <p class="s-auth-subtitle">{props.subtitle}</p>}
+            </div>
+          )}
+          <div class="s-auth-form">
+            {slots.default?.()}
           </div>
-        )}
-        <div class="s-auth-form">
-          {slots.default?.()}
+          {slots.methods && (
+            <div class="s-auth-methods">
+              {slots.methods()}
+            </div>
+          )}
+          {slots.footer && (
+            <div class="s-auth-footer">
+              {slots.footer()}
+            </div>
+          )}
         </div>
-        {slots.methods && (
-          <div class="s-auth-methods">
-            {slots.methods()}
-          </div>
-        )}
-        {slots.footer && (
-          <div class="s-auth-footer">
-            {slots.footer()}
-          </div>
-        )}
       </div>
     );
   },

package/src/styles/admin-tokens.scss

@@ -527,6 +527,30 @@
   to   { opacity: 1; transform: translateY(0) scale(1); }
 }
 
+/* Measuring wrapper (HkAuthCard): owns an explicit height so content-
+   driven height changes (channel tabs swapping the methods list, error
+   banners, …) animate instead of snapping. The transition lives here,
+   always on; the `--measuring` clip below is applied by HkAuthCard only
+   for the duration of a height transition, so an idle card never clips
+   its shadow, focus rings or popovers. */
+.s-auth-card-height {
+  /* The wrapper is sized from the card's offsetHeight (border-box); an
+     explicit box-sizing keeps that mapping honest on hosts without a
+     global border-box reset. */
+  box-sizing: border-box;
+  transition: height 0.3s var(--ease-out-expo, cubic-bezier(0.19, 1, 0.22, 1));
+
+  &.s-auth-card--measuring {
+    overflow: hidden;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .s-auth-card-height {
+    transition: none;
+  }
+}
+
 .s-auth-card input {
   transition: color calc(infinity * 1s) step-end, background-color calc(infinity * 1s) step-end;
   appearance: none;