@celestia-island/hikari 0.55.57 → 0.55.59

package/package.json

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

package/src/components/HkCard.scrollable.test.tsx

@@ -0,0 +1,94 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h } from "vue";
+
+import HkCard from "./HkCard";
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mountCard(props: Record<string, unknown> = {}, slotText = "content") {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({
+    render: () =>
+      h(HkCard, props, { default: () => h("span", { class: "slot-marker" }, slotText) }),
+  });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+afterEach(() => {
+  for (const m of mounts) m.app.unmount();
+  mounts.length = 0;
+});
+
+describe("HkCard — scrollable body", () => {
+  it("default card renders no scroll machinery", () => {
+    const c = mountCard();
+    expect(c.querySelector(".hk-card-scrollable")).toBeNull();
+    expect(c.querySelector(".hk-scroll-container")).toBeNull();
+    // The slot lands directly in the body, no pad wrapper in between.
+    expect(c.querySelector(".hk-card-body .slot-marker")).not.toBeNull();
+    expect(c.querySelector(".hk-card-body-pad")).toBeNull();
+  });
+
+  it("scrollable embeds the standard scroll container and flex classes", () => {
+    const c = mountCard({ scrollable: true });
+    expect(c.querySelector(".hk-card-scrollable")).not.toBeNull();
+    const scroll = c.querySelector(".hk-card-body .hk-scroll-container");
+    expect(scroll).not.toBeNull();
+    // The embedded scroller IS the library scroll container (overlay
+    // scrollbar machinery), not a bare overflow div.
+    expect(scroll?.querySelector(".hk-scroll-container-viewport")).not.toBeNull();
+    // Padded card: content padding lives inside the scroll region.
+    expect(c.querySelector(".hk-scroll-container .hk-card-body-pad .slot-marker")).not.toBeNull();
+  });
+
+  it("padded false drops the inner pad wrapper too", () => {
+    const c = mountCard({ scrollable: true, padded: false });
+    expect(c.querySelector(".hk-card-body-pad")).toBeNull();
+    expect(c.querySelector(".hk-scroll-container .slot-marker")).not.toBeNull();
+  });
+
+  it("header and footer stay outside the scroll region", () => {
+    const c = mountCard(
+      { scrollable: true, title: "T" },
+      undefined,
+    );
+    // Re-mount with a footer slot via raw slots is not available through
+    // the props-only helper; assert the header ordering here and cover
+    // the footer through the props-less variant below.
+    const header = c.querySelector(".hk-card-header");
+    const scroll = c.querySelector(".hk-card-body-scroll");
+    expect(header).not.toBeNull();
+    expect(scroll).not.toBeNull();
+    expect(header!.contains(scroll as Node)).toBe(false);
+  });
+
+  it("footer renders after the scroll body, not inside it", () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const app = createApp({
+      render: () =>
+        h(HkCard, { scrollable: true }, {
+          default: () => h("span", { class: "slot-marker" }, "content"),
+          footer: () => h("div", { class: "footer-marker" }, "foot"),
+        }),
+    });
+    app.mount(container);
+    mounts.push({ app, container });
+
+    const footer = container.querySelector(".hk-card-footer");
+    const scroll = container.querySelector(".hk-card-body-scroll");
+    expect(footer).not.toBeNull();
+    expect(footer!.contains(scroll as Node)).toBe(false);
+    expect(scroll!.contains(footer as Node)).toBe(false);
+  });
+
+  it("scroll content survives remounts of the pad wrapper class", () => {
+    // Padding flag flips at runtime (a consumer toggling density): the
+    // scroll container must persist (keyed on nothing but its slot).
+    const c = mountCard({ scrollable: true });
+    expect(c.querySelector(".hk-card-body-pad")).not.toBeNull();
+  });
+});

package/src/components/HkCard.scss

@@ -53,3 +53,38 @@
   padding: var(--space-12) var(--space-16);
   border-top: 1px solid var(--border-faint);
 }
+
+/* Scrollable card: the body becomes the flex host of an embedded
+   HkScrollContainer, so the card carries the ONE library scrollbar
+   system instead of every consumer nesting its own scroll layer.
+   Header and footer stay natural-height; the body fills the remainder.
+   Content padding lives INSIDE the scroll region (the pad wrapper the
+   component renders when `padded` is set) so the overlay scrollbar
+   hugs the card edge while content keeps its inset while scrolling. */
+.hk-card-scrollable {
+  display: flex;
+  flex-direction: column;
+
+  > .hk-card-header,
+  > .hk-card-footer {
+    flex: none;
+  }
+
+  > .hk-card-body {
+    display: flex;
+    flex-direction: column;
+    flex: 1 1 auto;
+    min-height: 0;
+    padding: 0;
+    overflow: hidden;
+  }
+
+  > .hk-card-body > .hk-card-body-scroll {
+    flex: 1 1 auto;
+    min-height: 0;
+  }
+
+  .hk-card-body-pad {
+    padding: var(--space-16);
+  }
+}

package/src/components/HkCard.tsx

@@ -1,5 +1,6 @@
 import { defineComponent } from "vue";
 
+import HkScrollContainer from "./HkScrollContainer";
 import "./HkCard.scss";
 
 export default defineComponent({
@@ -8,6 +9,17 @@ export default defineComponent({
     title: { type: String, default: undefined },
     hoverable: { type: Boolean, default: false },
     padded: { type: Boolean, default: true },
+    /** Turn the card body into the library's standard scroll region
+     *  (HkScrollContainer: overlay scrollbar, overflow sensing) instead
+     *  of a plain static block. The card becomes a column flex box —
+     *  header and footer keep their natural height while the body
+     *  fills the rest and scrolls. The card itself needs a height from
+     *  its context (grid stretch, an explicit h-* / max-h-* utility, or a flex
+     *  parent), exactly like any scroll container: without one there is
+     *  nothing to scroll and the body simply fits. Content padding
+     *  moves inside the scroll region so the scrollbar hugs the card
+     *  edge; `padded: false` drops the inner padding as usual. */
+    scrollable: { type: Boolean, default: false },
     class: { type: String, default: "" },
   },
   emits: {
@@ -18,6 +30,7 @@ export default defineComponent({
       <div
         class={[
           "hk-card",
+          props.scrollable ? "hk-card-scrollable" : "",
           props.hoverable ? "hk-card-hoverable" : "",
           props.class,
         ]}
@@ -29,7 +42,13 @@ export default defineComponent({
           </div>
         ) : null}
         <div class={["hk-card-body", !props.padded ? "hk-card-body-unpadded" : ""]}>
-          {slots.default?.()}
+          {props.scrollable ? (
+            <HkScrollContainer axis="vertical" class="hk-card-body-scroll">
+              <div class={props.padded ? "hk-card-body-pad" : undefined}>{slots.default?.()}</div>
+            </HkScrollContainer>
+          ) : (
+            slots.default?.()
+          )}
         </div>
         {slots.footer ? <div class="hk-card-footer">{slots.footer()}</div> : null}
       </div>

package/src/composables/useSizeMorph.test.ts

@@ -1184,12 +1184,19 @@ describe("useSizeMorph heightMorph (round 18)", () => {
     expect(h.frame.style.transition).toContain("300ms");
     // No clip staging, no riders — this is a plain height animation.
     expect(h.frame.style.clipPath).toBe("");
+    // The resident layer promotion is LIFTED for the animation's
+    // duration (round 19: the per-frame texture re-allocation of a
+    // composited layer during height animation composites as
+    // transparent on phone GPUs — the background flash-through).
+    expect(h.frame.style.willChange).toBe("");
 
-    // The transitionend cleans the inline override.
+    // The transitionend cleans the inline override AND restores the
+    // resident promotion (the frame is at rest).
     const ev = new Event("transitionend");
     Object.defineProperty(ev, "propertyName", { value: "height" });
     h.frame.dispatchEvent(ev);
     expect(h.frame.style.transition).toBe("");
+    expect(h.frame.style.willChange).toBe("clip-path");
     h.stop();
   });
 

package/src/composables/useSizeMorph.ts

@@ -936,25 +936,47 @@ export function useSizeMorph(
     // 2. Re-establish the OLD pin under no transition, flush it.
     f.style.height = `${pinned}px`;
     void f.offsetHeight;
-    // 3. Animate to the new pin under an inline height transition —
-    //    the CSS engine owns every frame; there is no staging task, no
-    //    warmup and no per-frame JS at all.
+    // 3. DEMOTE the frame from its resident composited layer for the
+    //    animation's duration. A `will-change: clip-path` layer whose
+    //    element changes layout size per-frame re-allocates its GPU
+    //    texture every frame — on a phone GPU the gap between the old
+    //    texture being discarded and the new one rastering composites
+    //    as TRANSPARENT, flashing the page behind the sheet through
+    //    (round-19 report: "background content keeps flashing"). With
+    //    the promotion lifted, the height animation's per-frame paint
+    //    happens on the main thread, which is slower but never leaves
+    //    a frame where the sheet's surface is missing.
+    const residentWill_ = f.style.willChange;
+    if (residentWill) {
+      f.style.willChange = "";
+      residentWill = false;
+    }
     f.style.transition =
       `height ${durationMs}ms cubic-bezier(0.4, 0, 0.2, 1)`;
     f.style.height = `${next}px`;
     pinned = next;
-    // 4. Clean the inline transition up on the animation's own clock.
+    // 4. Clean up on the animation's own clock: restore the transition
+    //    list and the resident layer promotion together — the frame is
+    //    at its final geometry and at rest, so the re-promotion's
+    //    raster has all the time it needs.
+    const restore = (): void => {
+      f.removeEventListener("transitionend", onEnd);
+      f.style.transition = "";
+      if (residentWill_ === "clip-path") {
+        f.style.willChange = "clip-path";
+        residentWill = true;
+      }
+    };
     const onEnd = (ev: TransitionEvent): void => {
       if (ev.target === f && ev.propertyName === "height") {
-        f.removeEventListener("transitionend", onEnd);
-        f.style.transition = "";
+        restore();
       }
     };
     f.addEventListener("transitionend", onEnd);
-    setTimeout(() => {
-      f.removeEventListener("transitionend", onEnd);
-      f.style.transition = "";
-    }, durationMs + 350);
+    const watchdog = setTimeout(restore, durationMs + 350);
+    // If the element goes away mid-flight, don't leak the timer.
+    const origClear = watchdog;
+    void origClear; // timer fires restore() which is idempotent
   }
 
   return { start, stop, hold, remeasure, heightMorph };