@celestia-island/hikari 0.55.151 → 0.55.152

package/package.json

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

package/src/components/HkBoard.fitCap.test.tsx

@@ -0,0 +1,59 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h, nextTick } from "vue";
+
+import HkBoard, { type BoardNodeInput } from "./HkBoard";
+
+/** A board whose content is far smaller than the viewport: the default fit
+ *  parks at the library cap; a fitCap lets the host fill the stage. */
+const nodes: BoardNodeInput[] = [
+  { id: "a", x: 0, y: 0, w: 120, h: 80, label: "A" },
+];
+const VIEW_W = 800;
+const VIEW_H = 600;
+
+function mountBoard(props: Record<string, unknown>): { world: () => string; app: ReturnType<typeof createApp> } {
+  // happy-dom lays nothing out: give the board a real viewport box so the
+  // fit maths are meaningful (the chest board tests use the same stub).
+  Object.defineProperty(HTMLElement.prototype, "clientWidth", { configurable: true, get: () => VIEW_W });
+  Object.defineProperty(HTMLElement.prototype, "clientHeight", { configurable: true, get: () => VIEW_H });
+  const host = document.createElement("div");
+  document.body.appendChild(host);
+  const app = createApp(defineComponent({
+    setup: () => () => h(HkBoard, { nodes, ...props }),
+  }));
+  app.mount(host);
+  return {
+    world: () => document.body.querySelector<HTMLElement>(".hk-board-world")!.style.transform,
+    app,
+  };
+}
+
+/** The world transform's scale factor, parsed out of `translate(..) scale(k)`. */
+function scaleOf(transform: string): number {
+  return Number(/scale\(([\d.]+)\)/.exec(transform)?.[1] ?? 0);
+}
+
+describe("HkBoard fitCap", () => {
+  afterEach(() => { document.body.innerHTML = ""; });
+
+  it("caps the default fit at the library ceiling when no fitCap is given", async () => {
+    const { world, app } = mountBoard({});
+    await nextTick();
+    await new Promise((r) => setTimeout(r, 30));
+    expect(scaleOf(world())).toBeLessThanOrEqual(1.25 + 1e-6);
+    app.unmount();
+  });
+
+  it("lets a host raise the fit ceiling to fill the stage", async () => {
+    const { world, app } = mountBoard({ fitCap: 3 });
+    await nextTick();
+    await new Promise((r) => setTimeout(r, 30));
+    const k = scaleOf(world());
+    // The fit honours the raised cap: with a 120px node in an 800px-ish
+    // stage the scale would be ~5 at fill; the cap is the ceiling, so the
+    // observed scale must exceed the library default and not exceed 3.
+    expect(k).toBeGreaterThan(1.25);
+    expect(k).toBeLessThanOrEqual(3 + 1e-6);
+    app.unmount();
+  });
+});

package/src/components/HkBoard.tsx

@@ -117,6 +117,11 @@ export default defineComponent({
     minimap: { type: Boolean, default: true },
     minK: { type: Number, default: 0.2 },
     maxK: { type: Number, default: 4 },
+    /** Ceiling for the fit zoom (reset button, fitOnMount). The library
+     *  default caps a fit at 1.25 so a small board never fills a huge
+     *  viewport; a host that wants fill-the-stage framing passes a higher
+     *  cap (the camera clamp still honours maxK). */
+    fitCap: { type: Number, default: undefined },
     animated: { type: Boolean, default: true },
     fitOnMount: { type: Boolean, default: true },
   },
@@ -141,6 +146,7 @@ export default defineComponent({
       minK: props.minK,
       maxK: props.maxK,
       animated: props.animated,
+      fitCap: props.fitCap,
     });
     const camera = cam.camera as Ref<BoardCamera>;
 

package/src/composables/useBoardCamera.ts

@@ -47,6 +47,11 @@ export interface UseBoardCameraOptions {
   maxK?: number;
   /** Master animation switch; reduced-motion forces snapping regardless. */
   animated?: boolean;
+  /** Optional ceiling for fit()'s scale: boards whose content is smaller
+   *  than the viewport may want to fill it instead of parking at the
+   *  library's default cap (BOARD_FIT_CAP). Unset keeps the default; the
+   *  camera clamp still honours maxK. */
+  fitCap?: number;
 }
 
 export interface UseBoardCameraReturn {
@@ -81,6 +86,10 @@ export function useBoardCamera(options: UseBoardCameraOptions): UseBoardCameraRe
     minK = BOARD_K_MIN,
     maxK = BOARD_K_MAX,
     animated = true,
+    /** Ceiling for fit()'s scale: boards whose content is smaller than the
+     *  viewport may want to fill it instead of parking at the library's
+     *  default cap (BOARD_FIT_CAP). Unset keeps the default. */
+    fitCap = undefined,
   } = options;
 
   const camera = ref<BoardCamera>({ x: 0, y: 0, k: 1 });
@@ -195,7 +204,7 @@ export function useBoardCamera(options: UseBoardCameraOptions): UseBoardCameraRe
   }
 
   function fit(): void {
-    const target = boardFit(contentRect(), viewport());
+    const target = boardFit(contentRect(), viewport(), fitCap !== undefined ? { cap: fitCap } : {});
     kFloor = Math.min(minK, target.k);
     animateTo(target);
   }