@celestia-island/hikari 0.51.2 → 0.51.3

package/package.json

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

package/src/components/HkScrollContainer.dock.test.tsx

@@ -0,0 +1,92 @@
+// Dock-slot contract for HkScrollContainer.
+//
+// A dock (dockTop / dockBottom named slot) renders as a NON-scrolling
+// flex sibling of the viewport: pinned to its edge, occupying layout
+// space (the flex: 1 viewport shrinks by the dock's height — content
+// can never slide under it). The container measures each mounted dock
+// and publishes --hk-scroll-dock-top / --hk-scroll-dock-bottom on the
+// host so consumers size their content end-padding against the dock
+// without hand-rolled px. The dock-edge fade rides on data-dock-fade.
+//
+// House style: raw createApp mounts on shared containers (no
+// @vue/test-utils).
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h, defineComponent } from "vue";
+
+import HkScrollContainer from "./HkScrollContainer";
+
+const mounts: ReturnType<typeof createApp>[] = [];
+const containers: HTMLElement[] = [];
+
+function mountDock(slots: Record<string, () => any>, props: Record<string, unknown> = {}) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  containers.push(container);
+  const app = createApp(defineComponent({
+    setup() {
+      return () => h(HkScrollContainer, props, slots);
+    },
+  }));
+  mounts.push(app);
+  return app.mount(container);
+}
+
+afterEach(() => {
+  for (const app of mounts) app.unmount();
+  mounts.length = 0;
+  for (const el of containers) el.remove();
+  containers.length = 0;
+});
+
+describe("HkScrollContainer dock slots", () => {
+  it("renders a bottom dock as a non-scrolling sibling with the fade marker", () => {
+    const vm = mountDock({
+      default: () => h("div", { class: "content" }, "rows"),
+      dockBottom: () => h("div", { class: "the-dock" }, "dock"),
+    });
+    const host = vm.$el as HTMLElement;
+    const dock = host.querySelector(".hk-scroll-dock[data-side='bottom']");
+    expect(dock).toBeTruthy();
+    // Sibling of the viewport, not inside it — the dock never scrolls.
+    const viewport = host.querySelector(".hk-scroll-container-viewport")!;
+    expect(viewport.contains(dock as Node)).toBe(false);
+    // The dock-edge fade engages by default for a bottom dock.
+    expect(host.getAttribute("data-dock-fade")).toBe("bottom");
+    // The measured-height vars are published on the host (0px in
+    // happy-dom — no layout; the contract is the vars exist + RO wired).
+    expect(host.style.getPropertyValue("--hk-scroll-dock-bottom")).toBe("0px");
+    expect(host.style.getPropertyValue("--hk-scroll-dock-top")).toBe("0px");
+  });
+
+  it("renders a top dock and fades the top edge instead", () => {
+    const vm = mountDock({
+      default: () => h("div", { class: "content" }, "rows"),
+      dockTop: () => h("div", { class: "the-dock" }, "progress"),
+    });
+    const host = vm.$el as HTMLElement;
+    expect(host.querySelector(".hk-scroll-dock[data-side='top']")).toBeTruthy();
+    expect(host.getAttribute("data-dock-fade")).toBe("top");
+    expect(host.querySelector(".hk-scroll-dock[data-side='bottom']")).toBeNull();
+  });
+
+  it("omits the dock fade marker when dockFade is off", () => {
+    const vm = mountDock(
+      {
+        default: () => h("div", { class: "content" }, "rows"),
+        dockBottom: () => h("div", { class: "the-dock" }, "dock"),
+      },
+      { dockFade: false },
+    );
+    const host = vm.$el as HTMLElement;
+    expect(host.querySelector(".hk-scroll-dock[data-side='bottom']")).toBeTruthy();
+    expect(host.getAttribute("data-dock-fade")).toBeNull();
+  });
+
+  it("publishes no dock marker without dock slots", () => {
+    const vm = mountDock({ default: () => h("div", { class: "content" }, "rows") });
+    const host = vm.$el as HTMLElement;
+    expect(host.querySelector(".hk-scroll-dock")).toBeNull();
+    expect(host.getAttribute("data-dock-fade")).toBeNull();
+    expect(host.style.getPropertyValue("--hk-scroll-dock-bottom")).toBe("");
+  });
+});

package/src/components/HkScrollContainer.scss

@@ -53,6 +53,38 @@
   mask-image: linear-gradient(to left, transparent 0, #000 var(--hk-scroll-fade-size));
 }
 
+/* ── Anchored docks (dockTop / dockBottom slots) ─────────────────
+   A dock renders as a NON-scrolling flex sibling of the viewport: it
+   stays pinned to its edge, never scrolls, and occupies layout space —
+   the flex: 1 viewport shrinks by the dock's height, so the content's
+   scroll end lands exactly at the dock's edge and can never slide
+   under it. The container measures each mounted dock (ResizeObserver)
+   and publishes --hk-scroll-dock-top / --hk-scroll-dock-bottom on the
+   host, so a consumer's content end-padding clears the dock with
+   breathing room (padding-bottom: calc(var(--hk-scroll-dock-bottom)
+   + 2rem)) instead of hand-rolled px guesses that go stale when the
+   dock reflows. */
+.hk-scroll-dock {
+  flex: none;
+  min-height: 0;
+}
+
+/* Dock-edge fade: mid-scroll content dissolving at the dock's edge
+   (opacity 100 -> 0 across --hk-scroll-dock-fade) reads as intentional
+   instead of a hard clip against the dock's top edge. Content never
+   sits under the dock, so this fades the viewport's last few pixels,
+   not the dock itself. */
+.hk-scroll-container[data-dock-fade="bottom"] > .hk-scroll-container-viewport {
+  -webkit-mask-image: linear-gradient(to bottom, #000 calc(100% - var(--hk-scroll-dock-fade, 2rem)), transparent);
+  mask-image: linear-gradient(to bottom, #000 calc(100% - var(--hk-scroll-dock-fade, 2rem)), transparent);
+}
+
+.hk-scroll-container[data-dock-fade="top"] > .hk-scroll-container-viewport {
+  -webkit-mask-image: linear-gradient(to bottom, transparent, #000 var(--hk-scroll-dock-fade, 2rem));
+  mask-image: linear-gradient(to bottom, transparent, #000 var(--hk-scroll-dock-fade, 2rem));
+}
+
+
 .hk-scroll-container[data-fade="true"][data-h-overflow="start"] > .hk-scroll-container-viewport {
   -webkit-mask-image: linear-gradient(to right, transparent 0, #000 var(--hk-scroll-fade-size));
   mask-image: linear-gradient(to right, transparent 0, #000 var(--hk-scroll-fade-size));

package/src/components/HkScrollContainer.tsx

@@ -80,12 +80,21 @@ export default defineComponent({
      *  approaching (`approachEnd`). Read live, so runtime changes need
      *  no remount. */
     approachDistance: { type: Number, default: 160 },
+    /** Fade the viewport's bottom edge (CSS mask, --hk-scroll-dock-fade
+     *  tall, opacity 100 -> 0) while a dock slot is mounted, so mid-
+     *  scroll content dissolving at the dock's edge reads as
+     *  intentional instead of a hard clip. */
+    dockFade: { type: Boolean, default: true },
   },
   emits: { approachEnd: () => true },
   setup(props, { slots, expose, emit }) {
     const { t } = useI18n();
     const viewportRef = ref<HTMLElement>();
+    const hostRef = ref<HTMLElement>();
+    const dockTopRef = ref<HTMLElement>();
+    const dockBottomRef = ref<HTMLElement>();
     let ro: ResizeObserver | null = null;
+    let dockRO: ResizeObserver | null = null;
     let scheduled: AnimationHandle | null = null;
     // Overlay track/thumb machinery lives in the shared composable;
     // this component keeps overflow sensing, autoFollow, the aligner,
@@ -292,10 +301,40 @@ export default defineComponent({
       }
     }
 
+    /** Publish each mounted dock's measured height as a host-level custom
+     *  property (`--hk-scroll-dock-top` / `--hk-scroll-dock-bottom`). The
+     *  dock is a non-scrolling flex sibling, so the viewport already
+     *  shrinks by its height; the published var exists so a consumer's
+     *  content end-padding can clear the dock with breathing room
+     *  (padding-bottom: calc(var(--hk-scroll-dock-bottom, 0px) + 2rem))
+     *  instead of hand-rolled px guesses that go stale when the dock
+     *  reflows. ResizeObserver keeps it live across dock reflows. */
+    function publishDockSizes() {
+      const host = hostRef.value;
+      if (!host) return;
+      const top = dockTopRef.value;
+      const bottom = dockBottomRef.value;
+      host.style.setProperty(
+        "--hk-scroll-dock-top",
+        top ? `${Math.round(top.getBoundingClientRect().height)}px` : "0px",
+      );
+      host.style.setProperty(
+        "--hk-scroll-dock-bottom",
+        bottom ? `${Math.round(bottom.getBoundingClientRect().height)}px` : "0px",
+      );
+    }
+
     onMounted(() => {
       const vp = viewportRef.value;
       if (!vp) return;
 
+      if (dockTopRef.value || dockBottomRef.value) {
+        dockRO = new ResizeObserver(publishDockSizes);
+        if (dockTopRef.value) dockRO.observe(dockTopRef.value);
+        if (dockBottomRef.value) dockRO.observe(dockBottomRef.value);
+        publishDockSizes();
+      }
+
       if (props.scrollbar) {
         mountScrollbars();
       }
@@ -340,6 +379,8 @@ export default defineComponent({
       settleHandle = null;
       ro?.disconnect();
       ro = null;
+      dockRO?.disconnect();
+      dockRO = null;
       followRO?.disconnect();
       followRO = null;
       alignRO?.disconnect();
@@ -431,13 +472,34 @@ export default defineComponent({
       if (alignCenter()) {
         content = <div ref={setAligner} class="hk-scroll-container-aligner">{content}</div>;
       }
+      // Anchored dock slots: a dock renders as a NON-scrolling flex
+      // sibling of the viewport — it stays pinned to its edge, never
+      // scrolls, and occupies layout space (the flex: 1 viewport shrinks
+      // by the dock's height). The container measures each mounted dock
+      // and publishes --hk-scroll-dock-top/bottom so consumers can size
+      // their content end-padding against the dock without guessing px.
+      const dockTopSlot = slots.dockTop;
+      const dockBottomSlot = slots.dockBottom;
       return (
         <Tag
+          ref={hostRef}
           class="hk-scroll-container"
           data-axis={props.axis}
           data-align={alignCenter() ? "center" : undefined}
           data-fade={props.fade ? "true" : undefined}
+          data-dock-fade={
+            props.dockFade && dockBottomSlot
+              ? "bottom"
+              : props.dockFade && dockTopSlot
+                ? "top"
+                : undefined
+          }
         >
+          {dockTopSlot && (
+            <div ref={dockTopRef} class="hk-scroll-dock" data-side="top">
+              {dockTopSlot()}
+            </div>
+          )}
           {/* Scroll-pin host marker: the viewport participates in the pin
               contract with its live axis; generic containers declare no
               standard padding, so pins inside resolve their strategy from
@@ -449,6 +511,11 @@ export default defineComponent({
           >
             {content}
           </div>
+          {dockBottomSlot && (
+            <div ref={dockBottomRef} class="hk-scroll-dock" data-side="bottom">
+              {dockBottomSlot()}
+            </div>
+          )}
           {showAutoTag.value && (
             <span class="hk-scroll-container-autotag" aria-hidden="true">{t("hikari::scrollContainer.auto", "Auto")}</span>
           )}