@celestia-island/hikari 0.55.150 → 0.55.151

package/package.json

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

package/src/components/HkKanban.tsx

@@ -96,6 +96,15 @@ export default defineComponent({
     /** Whether cards can be dragged between lanes. */
     draggable: { type: Boolean, default: false },
     ariaLabel: { type: String, default: undefined },
+    /** Forwarded to the strip's HkScrollContainer: spend the shell-
+     *  published --hk-scroll-tail-bottom as an in-flow tail spacer so a
+     *  dock floating over the board never covers its last row at the
+     *  scroll end (see HkScrollContainer's dockTailClearance). Only
+     *  effective on axis="vertical"/"both" boards: the default
+     *  horizontal axis carries its tail on the cross axis, where the
+     *  contract generates no spacer and the shrink pin is inert in the
+     *  block viewport — a horizontal board gets a no-op by design. */
+    dockTailClearance: { type: Boolean, default: false },
   },
   emits: ["move"],
   setup(props, { slots, emit, expose }) {
@@ -191,6 +200,7 @@ export default defineComponent({
               class="hk-kanban-strip"
               axis={stripAxis.value}
               overscanScreens={1}
+              dockTailClearance={props.dockTailClearance}
             >
               <div
                 class="hk-kanban-lanes"

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

@@ -8,11 +8,20 @@
 // host so consumers size their content end-padding against the dock
 // without hand-rolled px. The dock-edge fade rides on data-dock-fade.
 //
+// The FLOATING-dock twin (dockTailClearance) is contract-tested below:
+// it spends the shell-published --hk-scroll-tail-bottom as an in-flow
+// tail spacer instead of reserving layout space.
+//
 // House style: raw createApp mounts on shared containers (no
 // @vue/test-utils).
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
 import { afterEach, describe, expect, it } from "vitest";
 import { createApp, h, defineComponent } from "vue";
 
+import HkKanban from "./HkKanban";
 import HkScrollContainer from "./HkScrollContainer";
 
 const mounts: ReturnType<typeof createApp>[] = [];
@@ -90,3 +99,83 @@ describe("HkScrollContainer dock slots", () => {
     expect(host.style.getPropertyValue("--hk-scroll-dock-bottom")).toBe("");
   });
 });
+
+describe("HkScrollContainer floating-dock tail clearance", () => {
+  function mountKanban(props: Record<string, unknown> = {}) {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const app = createApp(defineComponent({
+      setup() {
+        return () => h(HkKanban, {
+          lanes: [{ id: "a" }, { id: "b" }],
+          laneKeyOf: (lane: unknown) => (lane as { id: string }).id,
+          cardsOf: () => [{ id: "c" }],
+          axis: "vertical",
+          ...props,
+        }, { card: () => h("div", { class: "card" }, "card") });
+      },
+    }));
+    mounts.push(app);
+    return app.mount(container);
+  }
+
+  it("marks the host only while dockTailClearance is on", () => {
+    const on = mountDock({ default: () => h("div", "rows") }, { dockTailClearance: true });
+    expect((on.$el as HTMLElement).getAttribute("data-dock-tail")).toBe("true");
+    const off = mountDock({ default: () => h("div", "rows") });
+    expect((off.$el as HTMLElement).getAttribute("data-dock-tail")).toBeNull();
+  });
+
+  it("forwards through HkKanban onto the strip host", () => {
+    const vm = mountKanban({ dockTailClearance: true });
+    const strip = (vm.$el as HTMLElement).querySelector(".hk-kanban-strip")!;
+    expect(strip.getAttribute("data-dock-tail")).toBe("true");
+    const bare = mountKanban();
+    const bareStrip = (bare.$el as HTMLElement).querySelector(".hk-kanban-strip")!;
+    expect(bareStrip.getAttribute("data-dock-tail")).toBeNull();
+  });
+
+  it("spends the published var on a shrink-safe in-flow spacer (style contract)", () => {
+    // happy-dom has no layout, so the geometry half of the contract is
+    // pinned as a style contract: the spacer trails the viewport's own
+    // content as a `flex: none; display: block` ::after (a column-flex
+    // viewport cannot compress it; the explicit display is what makes
+    // its height apply in the DEFAULT block viewport, where a bare
+    // ::after is an inline box and `height` is inert on it — measured in
+    // a real engine: zero clearance without, content+spacer with), and
+    // EVERY direct child of the viewport is pinned against main-axis
+    // shrinking while the prop is on. The pin is the other load-bearing
+    // half: a child that behaves as a shrinkable flex item once the
+    // viewport is flex-ified (this library's own `.hk-kanban-lanes` ships
+    // only `min-height: 100%`, so the flex-item initial `0 1 auto`
+    // applies) collapses to the viewport height and overflows its rows
+    // visibly, painting them OVER a spacer that trails the box — zero
+    // reachable clearance on any content taller than the viewport while
+    // short content measures green (the defect that kept a consumer
+    // board's tail under its dock through three padding rounds,
+    // root-caused in a real layout engine 2026-10-12). The spacer is
+    // additionally gated OFF axis="horizontal" containers: the tail is
+    // the cross axis there, and an ungated block spacer leaks onto the
+    // hidden vertical axis (measured: scrollHeight +spacer, and a
+    // programmatic scrollTop shifts content up behind
+    // overflow-y:hidden with no wheel path back).
+    const scss = readFileSync(
+      join(dirname(fileURLToPath(import.meta.url)), "HkScrollContainer.scss"),
+      "utf8",
+    );
+    const spacer = scss.match(
+      /\.hk-scroll-container\[data-dock-tail="true"\]:not\(\[data-axis="horizontal"\]\) > \.hk-scroll-container-viewport::after\s*\{[^}]*\}/,
+    );
+    expect(spacer, "tail spacer rule must exist").not.toBeNull();
+    expect(spacer![0]).toMatch(/content:\s*""/);
+    expect(spacer![0]).toMatch(/display:\s*block/);
+    expect(spacer![0]).toMatch(/flex:\s*none/);
+    expect(spacer![0]).toMatch(/height:\s*var\(--hk-scroll-tail-bottom,\s*0px\)/);
+    const pin = scss.match(
+      /\.hk-scroll-container\[data-dock-tail="true"\] > \.hk-scroll-container-viewport > \*\s*\{[^}]*\}/,
+    );
+    expect(pin, "viewport-child shrink pin must exist").not.toBeNull();
+    expect(pin![0]).toMatch(/flex-shrink:\s*0/);
+  });
+});

package/src/components/HkScrollContainer.scss

@@ -84,6 +84,56 @@
   mask-image: linear-gradient(to bottom, transparent, #000 var(--hk-scroll-dock-fade, 2rem));
 }
 
+/* ── Floating-dock tail clearance (dockTailClearance opt-in) ──────
+   A dock that floats OVER the scroll area (shell-level fixed plane —
+   NOT a dockTop/dockBottom slot) covers the viewport's tail. The shell
+   publishes its live measured occupancy as --hk-scroll-tail-bottom;
+   this spends it as an IN-FLOW tail spacer on the viewport's own
+   content, so the room is reachable scroll range that only appears at
+   the scroll end (mid-scroll content keeps flowing under the dock).
+
+   Two halves, both load-bearing (root-caused 2026-10-12 in a real
+   layout engine after three consumer-side padding rounds "never
+   entered the flow"):
+   1. the spacer is a `flex: none` ::after WITH `display: block` — a
+      column-flex viewport cannot compress it (and blockifies it
+      anyway), while in the DEFAULT block viewport the explicit
+      display is what makes its height apply at all: a bare ::after
+      there is a non-replaced INLINE box and `height` is inert on it
+      (measured: block viewport, 300px child, 50px spacer ->
+      scrollHeight 300 without the display, 350 with);
+   2. every direct child of the viewport is pinned against main-axis
+      SHRINKING while the prop is on — a child that behaves as a
+      shrinkable flex item once the viewport is flex-ified
+      (`.hk-kanban-lanes` ships only `min-height: 100%`, so the
+      flex-item initial `0 1 auto` applies) collapses to the viewport
+      height and overflows its rows VISIBLY, painting them over a
+      spacer that trails the box: zero reachable clearance on any
+      content taller than the viewport, while short content (demo
+      boards, empty-ish pages) measures green and hides the defect.
+   The spacer is inert while the var is unset/0px; the shrink pin is
+   active whenever the prop is on (at S=0 it changes only box extent,
+   not scroll range). The spacer is NOT generated on axis="horizontal"
+   containers: there the tail is the cross axis, and an ungated block
+   spacer stacks below the full-height content on the HIDDEN vertical
+   axis (measured: scrollHeight +50, and a programmatic scrollTop
+   shifts the content up behind overflow-y:hidden with no wheel path
+   back). The pin stays ungated (flex-shrink is inert on block children
+   and a no-op on the align-center aligner, which is already
+   flex:none). Consumer note: a higher-specificity consumer ::after
+   recipe on the viewport overrides this spacer's height — adopting
+   the prop means deleting the hand-rolled recipe, not stacking it. */
+.hk-scroll-container[data-dock-tail="true"] > .hk-scroll-container-viewport > * {
+  flex-shrink: 0;
+}
+
+.hk-scroll-container[data-dock-tail="true"]:not([data-axis="horizontal"]) > .hk-scroll-container-viewport::after {
+  content: "";
+  display: block;
+  flex: none;
+  height: var(--hk-scroll-tail-bottom, 0px);
+}
+
 
 .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));

package/src/components/HkScrollContainer.tsx

@@ -85,6 +85,52 @@ export default defineComponent({
      *  scroll content dissolving at the dock's edge reads as
      *  intentional instead of a hard clip. */
     dockFade: { type: Boolean, default: true },
+    /** Opt-in tail clearance for FLOATING docks (2026-10-12): a dock that
+     *  lives OUTSIDE this container (a shell-level fixed plane — a page's
+     *  bottom-center dock bar, e.g. chest's DockBar) covers the bottom of
+     *  whatever scroll area it hovers over. The shell publishes the dock's
+     *  live measured occupancy as `--hk-scroll-tail-bottom` (on any
+     *  ancestor, typically :root); with this prop the container spends
+     *  that var as an IN-FLOW tail spacer on the viewport's own content,
+     *  so the room becomes reachable scroll range that only appears once
+     *  the scroll end is reached — mid-scroll content keeps flowing under
+     *  the dock across the full viewport. The published value is the
+     *  whole tail room the publisher wants spent (dock occupancy plus
+     *  whatever breathing room its design rules add).
+     *
+     *  The spacer is a `flex: none; display: block` ::after, and every
+     *  direct child of the viewport is pinned against main-axis SHRINKING
+     *  while the prop is on. Both halves are load-bearing: a child that
+     *  behaves as a shrinkable flex item once the viewport is flex-ified
+     *  (hikari's own `.hk-kanban-lanes` ships only `min-height: 100%`, so
+     *  the flex-item initial `0 1 auto` applies) overflows its own box
+     *  visibly and paints OVER a spacer that trails the box — the exact
+     *  defect that kept a consumer board's tail under its dock through
+     *  three rounds of padding adjustments that "never entered the flow"
+     *  (chest follow-up to #1538/#1542, root-caused and measured in a real
+     *  layout engine, 2026-10-12); and the explicit `display: block` is
+     *  what makes the spacer's height apply in the DEFAULT block viewport
+     *  at all (a bare ::after there is an inline box and `height` is inert
+     *  on it — measured: zero clearance without, content+spacer with).
+     *  The spacer is inert while the var is unset/0px, so dockless pages
+     *  keep their full centering box; the shrink pin is active whenever
+     *  the prop is on. Unlike the dockTop/dockBottom slots (layout-space
+     *  docks that shrink the viewport permanently), this contract is for
+     *  docks that float OVER the scroll area by design. Do not combine it
+     *  with a `--hk-scroll-dock-bottom` end-padding recipe for the SAME
+     *  dock (double clearance). The spacer is not generated on
+     *  axis="horizontal" containers — the tail is the cross axis there,
+     *  and an ungated block spacer leaks onto the hidden vertical axis
+     *  (measured: scrollHeight grows and a programmatic scrollTop shifts
+     *  content up behind overflow-y:hidden) — while the shrink pin still
+     *  applies. A higher-specificity consumer ::after recipe on the
+     *  viewport overrides this spacer's height: adopting the prop means
+     *  deleting the hand-rolled recipe, not stacking it. The shrink pin's
+     *  accepted cost: a child that legitimately needs main-axis shrink
+     *  inside an opted-in container (a nested pane meant to fit the
+     *  viewport and scroll internally) cannot shrink; consumers escape
+     *  with a >=(0,2,0) override loaded after the library CSS. */
+    dockTailClearance: { type: Boolean, default: false },
     /** Back-to-top signal (scroll parameter every scrollable template
      *  can hand to a floating quick-action pad): while set, the
      *  container derives a visibility signal from its own throttled
@@ -539,6 +585,7 @@ export default defineComponent({
           data-axis={props.axis}
           data-align={alignCenter() ? "center" : undefined}
           data-fade={props.fade ? "true" : undefined}
+          data-dock-tail={props.dockTailClearance ? "true" : undefined}
           data-dock-fade={
             props.dockFade && dockBottomSlot
               ? "bottom"