@celestia-island/hikari 0.55.332 → 0.55.335

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.332",
+  "version": "0.55.335",
   "private": false,
   "type": "module",
   "description": "Hikari UI library, Vue 3 runtime — one design system for Vue 3 and Rust/WASM applications",

package/src/components/HkDockBar.tsx

@@ -42,11 +42,32 @@ export type HkDockBarSurface = "glass" | "solid";
  *
  * Relationship to HkScrollContainer: that component's dockTop /
  * dockBottom named slots are the contract for docks that live INSIDE a
- * scrolling region — pinned to the scroll viewport, excluded from the
- * scroll flow. HkDockBar is the carrier for docks that FLOAT over a
- * canvas or page instead. Pick by host: scrolling region →
- * HkScrollContainer dock slots; canvas/page overlay → HkDockBar. Do
- * not nest an HkDockBar inside a scroll viewport expecting pinning.
+ * scrolling region. Those slots place a dock two ways (2026-11-10
+ * addition — `dockMode`):
+ *   - `ride` (the pinned-to-the-visible-bottom-edge form): the dock
+ *     mounts inside the scroll viewport after the content, on a spacer
+ *     exactly one measured dock height tall, `position: sticky; bottom:
+ *     0`. The air between the content end and the dock is therefore
+ *     exactly one dock height; short content lets the dock follow the
+ *     content end (the leftover window height falls below it), long
+ *     content pins it to the visible bottom edge. Use it for a dock that
+ *     belongs to the CONTENT (a cruise canvas's bottom bar under its
+ *     last row). The container's ride wrapper is `pointer-events: none`
+ *     (it covers content while pinned), so this carrier's own box
+ *     contract is what keeps the dock interactive: the anchor box catches
+ *     nothing, the surface catches everything.
+ *   - `pin` (the default, older form): the dock is a non-scrolling flex
+ *     SIBLING of the viewport, so it sits on the container's edge and the
+ *     viewport shrinks by its height — correct for chrome that owns the
+ *     region's frame rather than trailing its content.
+ * HkDockBar is the carrier for docks that FLOAT over a canvas or page
+ * instead. Pick by host: scrolling region → HkScrollContainer dock slots
+ * (`ride` to follow the content, `pin` to own the edge); canvas/page
+ * overlay → HkDockBar. Do not nest an HkDockBar inside a scroll viewport
+ * expecting the container to place it — the container's slots do the
+ * placing, and a dock it mounted inside the viewport (ride) makes
+ * `closest(".hk-scroll-dock")` true, which is how a carrier knows to stop
+ * publishing shell-level clearance for it.
  *
  * Surfaces:
  *   - `glass` (default): translucent surface + backdrop blur.

package/src/components/HkKanban.scss

@@ -17,9 +17,32 @@
   display: flex;
   align-items: stretch;
   gap: var(--space-12);
+  /* A short board fills the strip: the lanes box is at least the viewport
+     height, so lane chrome reaches the strip's floor. */
   min-height: 100%;
 }
 
+/* ── Ride boards: the lanes box must follow its CONTENT ────────────────
+   2026-11-10 review S0, measured on a real board (chest cruise canvas):
+   in a column-flex strip viewport `min-height: 100%` makes the lanes BOX
+   exactly as tall as the viewport, so the ride spacer + sticky dock —
+   which are IN FLOW after that box — always sit below the fold. The dock
+   can then only hug the visible bottom edge, the spacer clears nothing,
+   and the air goes back to being the window's leftover (measured 275.8px
+   static / 563.8px at the scroll end against a 139px dock, i.e. no
+   improvement over the pin board and worse when scrolled). Releasing the
+   min-height lets the box end at the real content end, which is what the
+   ride placement needs: the spacer becomes the visible air and the dock
+   trails the content.
+
+   Ride only, by the root hook HkKanban emits for a ride host: a pin board
+   must keep the full-height lanes box it always had, so this rule never
+   reaches an existing board. Specificity (0,3,0) beats the base rule
+   above; a host that wants its own rule can override it the same way. */
+.hk-kanban[data-dock-mode="ride"] .hk-kanban-lanes {
+  min-height: 0;
+}
+
 .hk-kanban[data-axis="vertical"] .hk-kanban-lanes {
   flex-direction: column;
 }

package/src/components/HkKanban.tsx

@@ -105,6 +105,26 @@ export default defineComponent({
      *  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 },
+    /** Where a `dockBottom` dock lives, forwarded to the strip's
+     *  HkScrollContainer (see its `dockMode`): "pin" (default) keeps the
+     *  dock on the strip's bottom edge, "ride" moves it into the strip's
+     *  content flow so the air above it is the measured dock occupancy and
+     *  the dock follows the content. Only effective on axis="vertical"/
+     *  "both" boards — a horizontal strip carries its tail on the cross
+     *  axis, where the container's ride placement is gated off by design.
+     *
+     *  A ride board ALSO carries `data-dock-mode="ride"` on its root — only
+     *  while a `dockBottom` slot is actually mounted, since that hook
+     *  releases this component's full-height lanes box
+     *  (see HkKanban.scss): `.hk-kanban-lanes { min-height: 100% }` keeps
+     *  the lanes box as tall as the viewport, which would push the in-flow
+     *  spacer + dock below the fold and turn the air back into the
+     *  window's leftover (measured on a real board: 275.8px static vs the
+     *  139px dock, i.e. zero improvement over the pin board). The
+     *  attribute is emitted only while a ride dock is genuinely mounted (not
+     *  for pin, not for a horizontal board, not for an empty slot), so every
+     *  existing board is untouched. */
+    dockMode: { type: String as PropType<"pin" | "ride">, default: "pin" },
   },
   emits: ["move"],
   setup(props, { slots, emit, expose }) {
@@ -185,90 +205,117 @@ export default defineComponent({
 
     expose({ scrollHost, dragging });
 
-    return () => (
-      <div
-        class="hk-kanban"
-        data-axis={props.axis}
-        data-dragging={dragging.value ? "" : undefined}
-        aria-label={props.ariaLabel}
-      >
-        {props.lanes.length === 0
-          ? (slots.empty?.() ?? null)
-          : (
-            <HScrollContainer
-              ref={scrollHost}
-              class="hk-kanban-strip"
-              axis={stripAxis.value}
-              overscanScreens={1}
-              dockTailClearance={props.dockTailClearance}
-            >
-              <div
-                class="hk-kanban-lanes"
-                // One variable; the stylesheet decides whether it is the
-                // lane's width (horizontal boards) or its height (vertical).
-                style={
-                  props.laneSize ? { "--hk-kanban-lane-size": props.laneSize } : undefined
-                }
+    return () => {
+      // Docks attach to the strip's VERTICAL tail: `axis="horizontal"`
+      // boards keep the pre-2026-11-10 shape (no forwarded dock slot), the
+      // same gate the container itself applies to the ride placement —
+      // there the tail is the cross axis, where an in-flow block child
+      // leaks onto the hidden vertical axis.
+      const docksOnTail = stripAxis.value !== "horizontal";
+      // Styling hook AND behaviour switch for the CONTENT HEIGHT of the
+      // board (see the dockMode prop doc): a ride dock only follows the
+      // content when the lanes box is allowed to end above the viewport
+      // bottom. Ride only — a pin board keeps the full-height lanes box it
+      // always had, so no existing board changes. Gated on the dock actually
+      // being mounted too (S2-2): a requested-but-empty slot is legal, and
+      // releasing the lanes box for it would only shrink lane chrome on a
+      // short board while no dock is there to justify it.
+      const rideBoard = docksOnTail && props.dockMode === "ride" && !!slots.dockBottom;
+      return (
+        <div
+          class="hk-kanban"
+          data-axis={props.axis}
+          data-dock-mode={rideBoard ? "ride" : undefined}
+          data-dragging={dragging.value ? "" : undefined}
+          aria-label={props.ariaLabel}
+        >
+          {props.lanes.length === 0
+            ? (slots.empty?.() ?? null)
+            : (
+              <HScrollContainer
+                ref={scrollHost}
+                class="hk-kanban-strip"
+                axis={stripAxis.value}
+                overscanScreens={1}
+                dockTailClearance={props.dockTailClearance}
+                dockMode={props.dockMode}
               >
-                {props.lanes.map((lane, laneIndex) => {
-                  const laneKey = props.laneKeyOf(lane, laneIndex);
-                  const cards = cardsFor(lane, laneIndex);
-                  return (
-                    <section
-                      key={laneKey}
-                      class="hk-kanban-lane"
-                      data-lane={laneKey}
-                      data-drop-target={dropTarget.value === laneKey ? "" : undefined}
-                      onDragover={(event: DragEvent) => onDragOver(laneKey, event)}
-                      onDragleave={(event: DragEvent) => onDragLeave(laneKey, event)}
-                      onDrop={(event: DragEvent) => onDrop(laneKey, cards.length, event)}
+                {{
+                  default: () => (
+                    <div
+                      class="hk-kanban-lanes"
+                      // One variable; the stylesheet decides whether it is the
+                      // lane's width (horizontal boards) or its height (vertical).
+                      style={
+                        props.laneSize ? { "--hk-kanban-lane-size": props.laneSize } : undefined
+                      }
                     >
-                      <header class="hk-kanban-lane-header">
-                        {slots.laneHeader?.({
-                          lane,
-                          laneIndex,
-                          laneKey,
-                          cards,
-                        })}
-                      </header>
-                      <div class="hk-kanban-cards">
-                        {cards.map((card, cardIndex) => {
-                          const cardKey =
-                            props.cardKeyOf?.(card, cardIndex) ?? `${laneKey}#${cardIndex}`;
-                          return (
-                            <div
-                              key={cardKey}
-                              class="hk-kanban-card"
-                              data-card={cardKey}
-                              data-card-index={cardIndex}
-                              draggable={props.draggable || undefined}
-                              onDragstart={(event: DragEvent) =>
-                                onDragStart(card, laneKey, cardIndex, event)
-                              }
-                              onDragend={onDragEnd}
-                            >
-                              {slots.card?.({
-                                card,
-                                cardIndex,
+                      {props.lanes.map((lane, laneIndex) => {
+                        const laneKey = props.laneKeyOf(lane, laneIndex);
+                        const cards = cardsFor(lane, laneIndex);
+                        return (
+                          <section
+                            key={laneKey}
+                            class="hk-kanban-lane"
+                            data-lane={laneKey}
+                            data-drop-target={dropTarget.value === laneKey ? "" : undefined}
+                            onDragover={(event: DragEvent) => onDragOver(laneKey, event)}
+                            onDragleave={(event: DragEvent) => onDragLeave(laneKey, event)}
+                            onDrop={(event: DragEvent) => onDrop(laneKey, cards.length, event)}
+                          >
+                            <header class="hk-kanban-lane-header">
+                              {slots.laneHeader?.({
                                 lane,
                                 laneIndex,
                                 laneKey,
+                                cards,
                               })}
+                            </header>
+                            <div class="hk-kanban-cards">
+                              {cards.map((card, cardIndex) => {
+                                const cardKey =
+                                  props.cardKeyOf?.(card, cardIndex) ?? `${laneKey}#${cardIndex}`;
+                                return (
+                                  <div
+                                    key={cardKey}
+                                    class="hk-kanban-card"
+                                    data-card={cardKey}
+                                    data-card-index={cardIndex}
+                                    draggable={props.draggable || undefined}
+                                    onDragstart={(event: DragEvent) =>
+                                      onDragStart(card, laneKey, cardIndex, event)
+                                    }
+                                    onDragend={onDragEnd}
+                                  >
+                                    {slots.card?.({
+                                      card,
+                                      cardIndex,
+                                      lane,
+                                      laneIndex,
+                                      laneKey,
+                                    })}
+                                  </div>
+                                );
+                              })}
+                              {/* The tail keeps the lane's empty space hittable
+                                  (the lane itself owns the drop). */}
+                              <div class="hk-kanban-lane-tail" />
                             </div>
-                          );
-                        })}
-                        {/* The tail keeps the lane's empty space hittable
-                            (the lane itself owns the drop). */}
-                        <div class="hk-kanban-lane-tail" />
-                      </div>
-                      {slots.laneFooter?.({ lane, laneIndex, laneKey, cards })}
-                    </section>
-                  );
-                })}
-              </div>
-            </HScrollContainer>
-          )}
-      </div>
-    );
+                            {slots.laneFooter?.({ lane, laneIndex, laneKey, cards })}
+                          </section>
+                        );
+                      })}
+                    </div>
+                  ),
+                  // Forwarded so a board's own chrome (a cruise canvas's dock
+                  // under the lanes) keeps the container's dock contract —
+                  // including the --hk-scroll-dock-* heights it publishes.
+                  dockBottom: docksOnTail ? slots.dockBottom : undefined,
+                }}
+              </HScrollContainer>
+            )}
+        </div>
+      );
+    };
   },
 });

package/src/components/HkProgressBar.scss

@@ -111,6 +111,57 @@
   background: rgb(var(--color-primary));
 }
 
+// ── overspend (max + overValue) ─────────────────────────────────────
+// The track grows to `max + overValue`: the main fill keeps the quota's
+// share, the overspend stretch takes the rest to the inline end, and the
+// 1px divider is CARVED out of the stretch's inline-start edge — the track
+// background shows through the seam. A painted line would need a colour of
+// its own (and could not sit correctly over the translucent track); the
+// carved gap is one geometry that also mirrors correctly in RTL.
+.hk-progress-bar-overspend {
+  position: absolute;
+  top: 0;
+  height: 100%;
+  // Square on the seam side, rounded at the track's end: the 1px gap then
+  // reads as a divider over the whole track height instead of a lens
+  // between two round caps.
+  border-start-start-radius: 0;
+  border-end-start-radius: 0;
+  border-start-end-radius: var(--radius-full);
+  border-end-end-radius: var(--radius-full);
+  transition:
+    width var(--duration-normal) var(--ease-standard),
+    inset-inline-start var(--duration-normal) var(--ease-standard);
+
+  &-muted {
+    background: rgb(var(--color-muted));
+  }
+
+  &-danger {
+    background: rgb(var(--color-error));
+  }
+}
+
+// While an overspend stretch follows it, the main fill squares its
+// inline-end corners so the seam divider stays exactly 1px wide.
+.hk-progress-bar-track--overspend .hk-progress-bar-fill {
+  border-start-end-radius: 0;
+  border-end-end-radius: 0;
+}
+
+// Overspend caption ("超支 0.8 度"), riding the label row after the value.
+.hk-progress-bar-overspend-label {
+  margin-inline-start: var(--space-6);
+
+  &-muted {
+    color: rgb(var(--color-muted));
+  }
+
+  &-danger {
+    color: rgb(var(--color-error));
+  }
+}
+
 // Keyframes animate the logical inset so the sweep mirrors in RTL together
 // with the fill/secondary anchoring (LTR-identical).
 @keyframes hk-progress-indeterminate {
@@ -138,6 +189,7 @@
   // (house guard: the family bar-fill pattern).
   .hk-progress-bar-fill,
   .hk-progress-bar-secondary,
+  .hk-progress-bar-overspend,
   .hk-progress-bar-seg {
     transition: none;
   }

package/src/components/HkProgressBar.styles.test.ts

@@ -0,0 +1,79 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+/**
+ * Source contract for the overspend stretch's look. vitest cannot see
+ * stylesheets (happy-dom loads no SCSS), so a deleted rule would leave the
+ * DOM geometry guards green while the stretch painted as another primary
+ * fill — the whole point of the second segment is that it reads as PAST
+ * quota.
+ */
+const here = dirname(fileURLToPath(import.meta.url));
+const scss = readFileSync(join(here, "HkProgressBar.scss"), "utf8");
+
+/** The DECLARATIONS of a rule, comments stripped (a comment that names a
+ *  property must not satisfy a guard about it). */
+function ruleBlock(selector: string): string {
+  const escaped = selector.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const head = new RegExp(`${escaped}\\s*\\{`).exec(scss);
+  if (!head) throw new Error(`no rule for ${selector}`);
+  // Nested SCSS blocks: walk braces to the matching close.
+  const open = head.index + head[0].length - 1;
+  let depth = 0;
+  let end = open;
+  for (; end < scss.length; end++) {
+    if (scss[end] === "{") depth += 1;
+    else if (scss[end] === "}") {
+      depth -= 1;
+      if (depth === 0) break;
+    }
+  }
+  return scss.slice(open + 1, end)
+    .split("\n")
+    .filter((line) => {
+      const t = line.trim();
+      return !t.startsWith("*") && !t.startsWith("/*") && !t.startsWith("//");
+    })
+    .join("\n");
+}
+
+describe("HkProgressBar overspend sheet contract", () => {
+  it("positions the stretch as an inline-end block on the stretched track", () => {
+    const rule = ruleBlock(".hk-progress-bar-overspend");
+    expect(rule).toMatch(/position:\s*absolute/);
+    // Logical anchoring — the stretch sits at the inline end in RTL too.
+    expect(scss).not.toMatch(/\.hk-progress-bar-overspend[^{]*\{[^}]*\b(?:left|right):/);
+  });
+
+  it("tones the stretch muted by default and error-toned for danger", () => {
+    const block = ruleBlock(".hk-progress-bar-overspend");
+    expect(block).toMatch(/&-muted\s*\{[^}]*background:\s*rgb\(var\(--color-muted\)\)/);
+    expect(block).toMatch(/&-danger\s*\{[^}]*background:\s*rgb\(var\(--color-error\)\)/);
+  });
+
+  it("squares both sides of the 1px seam so it reads as a divider", () => {
+    const block = ruleBlock(".hk-progress-bar-overspend");
+    expect(block).toMatch(/border-start-start-radius:\s*0/);
+    expect(block).toMatch(/border-end-start-radius:\s*0/);
+    const fill = ruleBlock(".hk-progress-bar-track--overspend .hk-progress-bar-fill");
+    expect(fill).toMatch(/border-start-end-radius:\s*0/);
+    expect(fill).toMatch(/border-end-end-radius:\s*0/);
+  });
+
+  it("moves with the family cadence and stops under reduced motion", () => {
+    const block = ruleBlock(".hk-progress-bar-overspend");
+    expect(block).toMatch(/transition:[\s\S]*width var\(--duration-normal\)/);
+    const media = /@media \(prefers-reduced-motion: reduce\) \{([\s\S]*?)\n\}/.exec(scss);
+    expect(media, "reduced-motion guard").not.toBeNull();
+    expect(media![1]!).toMatch(/\.hk-progress-bar-overspend[\s\S]*transition:\s*none/);
+  });
+
+  it("co-locates the caption with the value label row", () => {
+    const rule = ruleBlock(".hk-progress-bar-overspend-label");
+    expect(rule).toMatch(/margin-inline-start:\s*var\(--space-6\)/);
+    expect(rule).toMatch(/&-danger\s*\{[^}]*color:\s*rgb\(var\(--color-error\)\)/);
+  });
+});