@celestia-island/hikari 0.55.93 → 0.55.94

package/package.json

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

package/src/components/HkNodeCanvas.test.tsx

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { createApp, defineComponent, h, isRef, nextTick, onUpdated, ref, type App } from "vue";
 
 import HkNodeCanvas, { NODE_CANVAS_DEFAULTS } from "./HkNodeCanvas";
+import { CANVAS_BOUNDS_MARGIN, clampCameraToBounds } from "./nodeCanvasTypes";
 
 /**
  * HkNodeCanvas tests — the camera protocol the three node surfaces share:
@@ -1050,4 +1051,142 @@ describe("HkNodeCanvas", () => {
     // Controlled: the internal camera did not move on its own.
     expect(instance.value!.camera).toEqual({ k: 1, x: 0, y: 0 });
   });
+
+  // ── Bounds clamp ─────────────────────────────────────────────────
+  // The camera may never push the content hull farther than half a
+  // viewport past the visible edge, per axis: at the limit the hull sits
+  // exactly CANVAS_BOUNDS_MARGIN of a viewport outside, and past it the
+  // outward drag is refused. Every camera write funnels through
+  // `setCamera`, so a drag, a wheel/pinch zoom, a tween and an imperative
+  // call all stop at the same edge.
+
+  describe("bounds clamp", () => {
+    // BOUNDS = 400×200 at (0,0), viewport 800×600, k = 1 ⇒
+    // x ∈ [-k·(x+w) - f·W, W - k·x + f·W] = [-800, 1200],
+    // y ∈ [-200 - 300, 600 + 300] = [-500, 900].
+    const X_LIMIT_LOW = -800;
+    const Y_LIMIT_LOW = -500;
+
+    it("clamps the pure camera to the expanded hull", () => {
+      const bounds = { x: 0, y: 0, width: 400, height: 200 };
+      const viewport = { width: 800, height: 600 };
+      // A camera already framing the content passes through untouched.
+      const inside = { k: 1, x: 100, y: 100 };
+      expect(clampCameraToBounds(inside, bounds, viewport)).toEqual(inside);
+      // Dragged far off-screen: stopped at the derived limit.
+      expect(clampCameraToBounds({ k: 1, x: -5000, y: -9000 }, bounds, viewport)).toEqual({
+        k: 1,
+        x: X_LIMIT_LOW,
+        y: Y_LIMIT_LOW,
+      });
+      // …and symmetrically for the far corners.
+      expect(clampCameraToBounds({ k: 1, x: 5000, y: 9000 }, bounds, viewport)).toEqual({
+        k: 1,
+        x: 1200,
+        y: 900,
+      });
+    });
+
+    it("holds the margin as a SCREEN distance at any zoom", () => {
+      // At k = 2 the world window halves, so the world-space margin halves
+      // with it — but the on-screen slack stays half a viewport.
+      const bounds = { x: 0, y: 0, width: 400, height: 200 };
+      const viewport = { width: 800, height: 600 };
+      const clamped = clampCameraToBounds({ k: 2, x: -99999, y: 0 }, bounds, viewport);
+      // xLow = -2·400 - 0.5·800 = -1200.
+      expect(clamped.x).toBe(-1200);
+      // At the limit the hull's right edge sits exactly half a viewport
+      // left of the screen's left edge.
+      const hullRightOnScreen = (bounds.width) * clamped.k + clamped.x;
+      expect(hullRightOnScreen).toBe(-viewport.width / 2);
+    });
+
+    it("passes degenerate inputs through unchanged", () => {
+      const cam = { k: 1, x: 123, y: 456 };
+      expect(clampCameraToBounds(cam, null, { width: 800, height: 600 })).toBe(cam);
+      expect(clampCameraToBounds(cam, { x: 0, y: 0, width: 0, height: 100 }, { width: 800, height: 600 })).toBe(cam);
+      expect(clampCameraToBounds(cam, { x: 0, y: 0, width: 100, height: 0 }, { width: 800, height: 600 })).toBe(cam);
+      expect(clampCameraToBounds(cam, { x: 0, y: 0, width: 100, height: 100 }, { width: 0, height: 0 })).toBe(cam);
+      expect(clampCameraToBounds({ k: 0, x: 1, y: 1 }, { x: 0, y: 0, width: 100, height: 100 }, { width: 800, height: 600 })).toEqual({ k: 0, x: 1, y: 1 });
+      // An astronomically placed hull overflows the clamp range (k·coord
+      // passes the double ceiling): refuse to clamp rather than write a
+      // non-finite translation (the browser would drop the transform).
+      const far = { x: 1e308, y: 1e308, width: 100, height: 100 };
+      expect(clampCameraToBounds({ k: 2, x: 123, y: 456 }, far, { width: 800, height: 600 })).toEqual({ k: 2, x: 123, y: 456 });
+      expect(clampCameraToBounds({ k: 1, x: NaN, y: 0 }, { x: 0, y: 0, width: 100, height: 100 }, { width: 800, height: 600 })).toEqual({ k: 1, x: NaN, y: 0 });
+    });
+
+    it("stops a pan that would drag the hull off-screen", async () => {
+      const { instance } = mount({ contentBounds: BOUNDS, fitOnLoad: false });
+      await nextTick();
+      instance.value?.panBy(-5000, -5000);
+      expect(instance.value!.camera).toEqual({ k: 1, x: X_LIMIT_LOW, y: Y_LIMIT_LOW });
+      // The far direction clamps at its own wall.
+      instance.value?.panBy(99999, 99999);
+      expect(instance.value!.camera).toEqual({ k: 1, x: 1200, y: 900 });
+      // Small moves apply on the free axis; the wall axis stays pinned.
+      instance.value?.panBy(-10, 5);
+      expect(instance.value!.camera).toEqual({ k: 1, x: 1190, y: 900 });
+    });
+
+    it("stops a pointer drag at the same edge", async () => {
+      const { instance, root } = mount({ contentBounds: BOUNDS, fitOnLoad: false });
+      await nextTick();
+      root.setPointerCapture = () => {};
+      root.dispatchEvent(pointerEvent("pointerdown", { pointerId: 21, clientX: 400, clientY: 300 }));
+      // 400 px of drag left/up, in two moves, is nowhere near the limit —
+      // then one enormous move rides into the wall.
+      root.dispatchEvent(pointerEvent("pointermove", { pointerId: 21, clientX: 300, clientY: 250 }));
+      root.dispatchEvent(pointerEvent("pointermove", { pointerId: 21, clientX: 200, clientY: 200 }));
+      root.dispatchEvent(pointerEvent("pointermove", { pointerId: 21, clientX: -100000, clientY: -100000 }));
+      document.body.dispatchEvent(pointerEvent("pointerup", { pointerId: 21, clientX: -100000, clientY: -100000, buttons: 0 }));
+      expect(instance.value!.camera).toEqual({ k: 1, x: X_LIMIT_LOW, y: Y_LIMIT_LOW });
+    });
+
+    it("keeps a wheel zoom anchored without escaping the walls", async () => {
+      const { instance } = mount({ contentBounds: BOUNDS, fitOnLoad: false });
+      await nextTick();
+      // Ride to the low-x wall first, then zoom out hard: the anchor keeps
+      // the world point under the cursor, but the translation must stay
+      // inside the clamp interval for the new k.
+      instance.value?.panBy(-5000, 0);
+      for (let step = 0; step < 12; step++) instance.value?.zoomBy(-1);
+      const cam = instance.value!.camera;
+      const xLow = -cam.k * (BOUNDS.x + BOUNDS.width) - CANVAS_BOUNDS_MARGIN * VIEWPORT.width;
+      const xHigh = VIEWPORT.width - cam.k * BOUNDS.x + CANVAS_BOUNDS_MARGIN * VIEWPORT.width;
+      expect(cam.x).toBeGreaterThanOrEqual(xLow - 1e-6);
+      expect(cam.x).toBeLessThanOrEqual(xHigh + 1e-6);
+    });
+
+    it("lets a controlled host's gestures clamp before the emit", async () => {
+      const onUpdate = vi.fn();
+      const { instance } = mount({
+        contentBounds: BOUNDS,
+        camera: { k: 1, x: 0, y: 0 },
+        "onUpdate:camera": onUpdate,
+        fitOnLoad: false,
+      });
+      await nextTick();
+      instance.value?.panBy(-5000, -5000);
+      const last = onUpdate.mock.calls.at(-1)?.[0] as { k: number; x: number; y: number };
+      expect(last).toEqual({ k: 1, x: X_LIMIT_LOW, y: Y_LIMIT_LOW });
+    });
+
+    it("does nothing the host did not ask for when the clamp is off", async () => {
+      const { instance } = mount({ contentBounds: BOUNDS, fitOnLoad: false, clampToBounds: false });
+      await nextTick();
+      instance.value?.panBy(-5000, -5000);
+      expect(instance.value!.camera).toEqual({ k: 1, x: -5000, y: -5000 });
+    });
+
+    it("never fights a fit: framing still centres the hull", async () => {
+      const { instance } = mount({ contentBounds: BOUNDS, fitOnLoad: false });
+      await nextTick();
+      instance.value?.panBy(-5000, -5000);
+      expect(instance.value!.fit()).toBe(true);
+      // 400×200 in 800×600 with 40 px padding → k = min(1.8, 2.6) capped at
+      // fitCap 1.25, centred: x = (800-500)/2, y = (600-250)/2.
+      expect(instance.value!.camera).toEqual({ k: 1.25, x: 150, y: 175 });
+    });
+  });
 });

package/src/components/HkNodeCanvas.tsx

@@ -13,6 +13,7 @@ import "./HkNodeCanvas.scss";
 
 import {
   computeLod,
+  clampCameraToBounds,
   edgeHitWidth,
   edgeMidpoint,
   edgePath,
@@ -39,7 +40,7 @@ export type {
   NodeCanvasPainter,
   PrintPaper,
 } from "./nodeCanvasTypes";
-export { computeLod, edgePath, edgeMidpoint, edgeHitWidth, sideOffset, oppositeSide, LOD_DEFAULTS, PAPER_SIZES } from "./nodeCanvasTypes";
+export { computeLod, edgePath, edgeMidpoint, edgeHitWidth, sideOffset, oppositeSide, LOD_DEFAULTS, PAPER_SIZES, clampCameraToBounds, CANVAS_BOUNDS_MARGIN } from "./nodeCanvasTypes";
 
 /** The pointer payload the edge events carry: a real MouseEvent for
  * hover/click/contextmenu, or a synthesized stand-in when a touch
@@ -143,6 +144,13 @@ interface PendingRequest {
  *     read to simplify their nodes at low zoom.
  *   - a **print mode**: disables gestures, fixes the camera, and exposes
  *     `exportSVG()` for vector output.
+ *   - a **bounds clamp** (default on): every camera write stops where the
+ *     content hull would leave half a viewport of itself past the visible
+ *     edge — a drag, a wheel or pinch zoom, a tween, an imperative call.
+ *     A graph can still be stranded only through the host's own channels:
+ *     opting out (`clampToBounds: false`), never supplying
+ *     `contentBounds`, or a controlled `camera` prop the host writes
+ *     verbatim (emitted gesture results are always pre-clamped).
  *
  * What it still does NOT own: what nodes look like, what data drives
  * them, or how they are laid out. The host draws node content through
@@ -165,7 +173,10 @@ export default defineComponent({
     /** Controlled camera (`v-model:camera`). Without it the component keeps
      *  its own, seeded by `fitOnLoad`. */
     camera: { type: Object as PropType<NodeCanvasCamera | undefined>, default: undefined },
-    /** Content rectangle, in world units, used for fit and clamping. */
+    /** Content rectangle, in world units — the hull every node on the
+     *  canvas forms. `fit` frames it, and the bounds clamp (`clampToBounds`,
+     *  on by default) refuses camera moves that would push it out of
+     *  reach. */
     contentBounds: { type: Object as PropType<NodeCanvasBounds | null>, default: null },
     /** Smallest zoom the camera will settle on. */
     minZoom: { type: Number, default: NODE_CANVAS_DEFAULTS.minZoom },
@@ -197,6 +208,15 @@ export default defineComponent({
     pannable: { type: Boolean, default: true },
     /** Whether the wheel zooms. */
     zoomable: { type: Boolean, default: true },
+    /** Keep the content within reach: the camera may never push the
+     *  content hull (the `contentBounds` envelope every node on the canvas
+     *  forms) farther than half a viewport past the visible edge, per
+     *  axis — the outward drag stops there instead of stranding the graph
+     *  off-screen. On by default; a canvas with a genuinely unbounded
+     *  surface (or one whose content the host moves independently) opts
+     *  out with `false`. Needs `contentBounds` to know the hull — without
+     *  it there is nothing to clamp against and this is a no-op. */
+    clampToBounds: { type: Boolean, default: true },
     /** Mount the minimap in the corner. */
     minimap: { type: Boolean, default: true },
     /** Which corner the minimap takes. */
@@ -558,12 +578,21 @@ export default defineComponent({
       // the surface freezes with no way back. Refuse to propagate it.
       if (!Number.isFinite(k) || k <= 0) return;
       if (!Number.isFinite(next.x) || !Number.isFinite(next.y)) return;
+      // Bounds clamp (default on): every write funnels through here, so a
+      // drag, a wheel/pinch zoom, a tween and an imperative `setCamera` all
+      // stop at the same edge — the content hull never leaves half a
+      // viewport of reach. `fit()` frames the hull inside the viewport and
+      // therefore always satisfies the clamp; it writes through
+      // `writeCamera` directly, so a host framing is never fought.
+      const bounded = props.clampToBounds
+        ? clampCameraToBounds({ k, x: next.x, y: next.y }, props.contentBounds, viewport.value)
+        : { k, x: next.x, y: next.y };
       // Any non-automatic camera move is the user's: a late `contentBounds`
       // must not throw that work away. It also means the host is somewhere
       // else, so a later `fit()` may ask for the same camera again.
       movedByHand = true;
       lastRequested = null;
-      writeCamera({ k, x: next.x, y: next.y });
+      writeCamera(bounded);
     }
 
     /** The camera that frames `contentBounds` inside the viewport. */

package/src/components/nodeCanvasTypes.ts

@@ -278,6 +278,74 @@ export function edgeMidpoint(
   return { x: (from.x + to.x) / 2, y: (from.y + to.y) / 2 };
 }
 
+// ── Camera bounds clamp ──────────────────────────────────────────────────
+
+/** How far past the content hull the camera may push it, as a fraction of
+ *  the viewport size per axis (0.5 = the hull may leave at most half a
+ *  viewport of itself past the visible edge — no farther). */
+export const CANVAS_BOUNDS_MARGIN = 0.5;
+
+/** Clamp a camera so the content cannot be dragged out of reach.
+ *
+ *  The binding geometry is the content hull — the axis-aligned envelope of
+ *  every component on the canvas (the hull's x/y extremes are exactly what
+ *  a pure translation can bind against). The camera is clamped so the
+ *  viewport's world window keeps intersecting that hull expanded by
+ *  `marginFactor` viewport sizes per axis: at the limit the hull itself
+ *  sits exactly `marginFactor` of a viewport outside the visible edge, and
+ *  past that the outward drag is refused.
+ *
+ *  Degenerate inputs pass the camera through unchanged: no bounds (the
+ *  host gave none), a non-finite or empty hull, an unmeasured viewport, a
+ *  non-finite zoom, or a coordinate combination whose clamp range is not
+ *  finite (an astronomically placed hull) — a clamped camera is only ever
+ *  returned finite, because the browser drops the whole transform
+ *  otherwise. */
+export function clampCameraToBounds(
+  camera: NodeCanvasCamera,
+  bounds: NodeCanvasBounds | null,
+  viewport: { width: number; height: number },
+  marginFactor: number = CANVAS_BOUNDS_MARGIN,
+): NodeCanvasCamera {
+  if (
+    !bounds ||
+    !(bounds.width > 0) ||
+    !(bounds.height > 0) ||
+    !Number.isFinite(bounds.x) ||
+    !Number.isFinite(bounds.y) ||
+    !(viewport.width > 0) ||
+    !(viewport.height > 0)
+  ) {
+    return camera;
+  }
+  const { k } = camera;
+  if (!Number.isFinite(k) || k <= 0) return camera;
+  if (!Number.isFinite(camera.x) || !Number.isFinite(camera.y)) return camera;
+  // The viewport's world window is [-x/k, (W-x)/k]; "keep intersecting the
+  // hull expanded by (f·W/k, f·H/k) world units" solves to these
+  // translation ranges. The viewport fraction cancels the zoom — the
+  // margin is a SCREEN distance (half a viewport) at any k.
+  const xLow = -k * (bounds.x + bounds.width) - marginFactor * viewport.width;
+  const xHigh = viewport.width - k * bounds.x + marginFactor * viewport.width;
+  const yLow = -k * (bounds.y + bounds.height) - marginFactor * viewport.height;
+  const yHigh = viewport.height - k * bounds.y + marginFactor * viewport.height;
+  // bounds.width/height > 0 keeps both intervals non-empty (dust aside);
+  // the finiteness guard refuses a hull so far out the range overflows —
+  // a non-finite translation would drop the whole transform.
+  if (!(xLow <= xHigh) || !(yLow <= yHigh)) return camera;
+  if (
+    !Number.isFinite(xLow) || !Number.isFinite(xHigh)
+    || !Number.isFinite(yLow) || !Number.isFinite(yHigh)
+  ) {
+    return camera;
+  }
+  return {
+    k,
+    x: Math.min(xHigh, Math.max(xLow, camera.x)),
+    y: Math.min(yHigh, Math.max(yLow, camera.y)),
+  };
+}
+
 // ── Print ────────────────────────────────────────────────────────────────
 
 export type PrintPaper = "a4-landscape" | "a3-landscape" | "auto";