@weasel-js/labkit 1.3.0 → 1.4.0-pre.1

package/dist/canvas/index.d.ts

@@ -1,50 +1,134 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import * as react from 'react';
-import { ReactNode } from 'react';
-import { V as ViewTransform, a as Point } from '../_dts/types-BttTIent.js';
-import '../_dts/types-DCGEcMO_.js';
-import '../_dts/PrefsForm-BYa6cWnO.js';
-import '../_dts/types-1Sdxy_Pv.js';
+import { ReactNode, WheelEvent, PointerEvent } from 'react';
+import { V as ViewTransform, c as WorldSpec, a2 as ViewportSize, a as Point, W as WorldFrame } from '../_dts/frac-C-2c72Ij.js';
+export { x as DEFAULT_FRAME, a4 as applyCamera, aa as resolveFrame } from '../_dts/frac-C-2c72Ij.js';
+import { C as CanvasLayerDescriptor } from '../_dts/CanvasStackContext-LnCfqNBA.js';
+export { a as CanvasStackContext, b as CanvasStackContextValue, c as CanvasStackSurface } from '../_dts/CanvasStackContext-LnCfqNBA.js';
+import '../_dts/types-D6s4b7if.js';
+import '../_dts/PrefsForm-BkUJZx0A.js';
+import '../_dts/types-DYMaEvM5.js';
 import '../_dts/types-DJ79Tg5J.js';
-
-/** One layer of a canvas stack: its id, whether it is currently shown, and how
- *  it paints itself. */
-interface CanvasLayerDescriptor {
-    id: string;
-    visible: boolean;
-    render: (ctx: CanvasRenderingContext2D, view: ViewTransform) => void;
-}
+import '../_dts/types-C-gh9Ap-.js';
 
 /** Props for `<CanvasStack>`. */
 interface CanvasStackProps {
     layers: CanvasLayerDescriptor[];
     view: ViewTransform;
     onViewChange: (v: ViewTransform) => void;
+    /** The instrument's coordinate system. Omitted, world (0,0) sits at the
+     *  element's top-left with y running down. */
+    worldSpec?: WorldSpec;
     minZoom?: number;
     maxZoom?: number;
     width?: number | string;
     height?: number | string;
     className?: string;
+    /** Fired whenever the stack is measured, so a consumer can place a view that
+     *  only makes sense in terms of the viewport. */
+    onResize?: (size: ViewportSize) => void;
     onHitTest?: (worldPos: Point) => void;
     children?: ReactNode;
 }
 /** Stacks one `<canvas>` per layer and drives them from a shared view, so a
  *  layer that changes rarely is not redrawn with one that changes every frame.
  *  Handles sizing, device pixel ratio, and pan/zoom. */
-declare function CanvasStack({ layers, view, onViewChange, minZoom, maxZoom, width, height, className, onHitTest, children, }: CanvasStackProps): react_jsx_runtime.JSX.Element;
+declare function CanvasStack({ layers, view, onViewChange, worldSpec, minZoom, maxZoom, width, height, className, onResize, onHitTest, children, }: CanvasStackProps): react_jsx_runtime.JSX.Element;
 
-/** What a canvas stack publishes to its children — currently the view, so
- *  DOM overlays can position themselves in the same coordinates. */
-interface CanvasStackContextValue {
-    view: ViewTransform;
+/** Bounds and coordinate system a {@link zoomAt} works in. */
+interface ZoomAtOptions {
+    /** The instrument's coordinate system, resolved against the viewport.
+     *  Omitted, `at` is measured from the element's top-left. */
+    frame?: WorldFrame;
+    min?: number;
+    max?: number;
 }
-/** Context carrying the surrounding canvas stack's view. */
-declare const CanvasStackContext: react.Context<CanvasStackContextValue | null>;
+/**
+ * Zoom a view by `factor` about a fixed point, so whatever world coordinate
+ * `at` was over stays under it.
+ *
+ * `at` is in the element's own pixels — a cursor position, or the centre of a
+ * lens. The clamp is applied before the pan is solved, so a zoom that hits a
+ * bound still anchors on the zoom it actually reached.
+ */
+declare function zoomAt(view: ViewTransform, factor: number, at: Point, { frame, min, max }?: ZoomAtOptions): ViewTransform;
+/** The view that puts a world point at the centre of a `size` viewport, at
+ *  `zoom`. What a lens showing a region around one point renders through. */
+declare function centerOn(world: Point, zoom: number, size: ViewportSize, frame?: WorldFrame): ViewTransform;
 
-/** Project a world point into screen coordinates under a view. */
-declare function worldToScreen(world: Point, view: ViewTransform): Point;
+/** Project a world point into screen coordinates under a view.
+ *
+ *  `frame` is the instrument's declared coordinate system, resolved against the
+ *  viewport; omitting it gives labkit's original one — origin at the top-left,
+ *  y downward. */
+declare function worldToScreen(world: Point, view: ViewTransform, frame?: WorldFrame): Point;
 /** Unproject a screen point back to world coordinates under a view. */
-declare function screenToWorld(screen: Point, view: ViewTransform): Point;
+declare function screenToWorld(screen: Point, view: ViewTransform, frame?: WorldFrame): Point;
+
+/** A point in the space the instrument works in. */
+interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+/** An orbit camera as a trial view: where it looks from, and what it looks at.
+ *  labkit does not turn this into a matrix — the host's renderer does. */
+interface OrbitView {
+    yaw: number;
+    pitch: number;
+    distance: number;
+    target: Vec3;
+}
+/** Just short of the pole. At exactly ±PI/2 the azimuth is undefined and the
+ *  camera rolls, which reads as the model jumping rather than as a limit. */
+declare const PITCH_LIMIT: number;
+declare function clampPitch(pitch: number): number;
+declare function wrapYaw(yaw: number): number;
+/** The view a drag of (dx, dy) from `start` produces. Absolute against the drag
+ *  start, so it can be re-applied any number of times without compounding. */
+declare function orbitAfterDrag(start: OrbitView, dx: number, dy: number): OrbitView;
+/** Multiplicative, so one notch covers the same proportion of the distance
+ *  whether the camera is near or far. */
+declare function orbitAfterWheel(view: OrbitView, deltaY: number, minDistance: number, maxDistance: number): OrbitView;
+interface UseOrbitOptions {
+    view: OrbitView;
+    onViewChange: (v: OrbitView) => void;
+    /** Restored on double-click. Defaults to the view the hook first saw. */
+    home?: OrbitView;
+    minDistance?: number;
+    maxDistance?: number;
+}
+interface OrbitHandlers {
+    onWheel: (e: WheelEvent<HTMLElement>) => void;
+    onPointerDown: (e: PointerEvent<HTMLElement>) => void;
+    onPointerMove: (e: PointerEvent<HTMLElement>) => void;
+    onPointerUp: (e: PointerEvent<HTMLElement>) => void;
+    onDoubleClick: () => void;
+    isDragging: () => boolean;
+}
+/** Pointer gestures over an orbit view: drag to turn, wheel or pinch to dolly,
+ *  double-click to go home. The 3D peer of `usePanZoom`. */
+declare function useOrbit({ view, onViewChange, home, minDistance, maxDistance, }: UseOrbitOptions): OrbitHandlers;
+
+interface UsePanZoomOptions {
+    view: ViewTransform;
+    onViewChange: (v: ViewTransform) => void;
+    /** The opening `view.zoom` always stays reachable, widening these past
+     *  whatever is passed here if it would otherwise exclude it. */
+    minZoom?: number;
+    maxZoom?: number;
+    /** The instrument's coordinate system, resolved against the viewport. The
+     *  wheel anchors in this frame; omitting it anchors at the element's
+     *  top-left, which is what labkit did before a frame could be declared. */
+    frame?: WorldFrame;
+}
+interface PanZoomHandlers {
+    onWheel: (e: WheelEvent<HTMLElement>) => void;
+    onPointerDown: (e: PointerEvent<HTMLElement>) => void;
+    onPointerMove: (e: PointerEvent<HTMLElement>) => void;
+    onPointerUp: (e: PointerEvent<HTMLElement>) => void;
+    isDragging: () => boolean;
+}
+declare function usePanZoom({ view, onViewChange, minZoom, maxZoom, frame, }: UsePanZoomOptions): PanZoomHandlers;
 
-export { CanvasStack, CanvasStackContext, screenToWorld, worldToScreen };
-export type { CanvasLayerDescriptor, CanvasStackContextValue, CanvasStackProps };
+export { CanvasLayerDescriptor, CanvasStack, PITCH_LIMIT, ViewportSize, WorldFrame, WorldSpec, centerOn, clampPitch, orbitAfterDrag, orbitAfterWheel, screenToWorld, useOrbit, usePanZoom, worldToScreen, wrapYaw, zoomAt };
+export type { CanvasStackProps, OrbitHandlers, OrbitView, PanZoomHandlers, UseOrbitOptions, UsePanZoomOptions, Vec3, ZoomAtOptions };

package/dist/canvas/index.js

@@ -1,6 +1,7 @@
-export { CanvasStack } from '../chunk-BDJXIBRZ.js';
-export { screenToWorld, worldToScreen } from '../chunk-T66HU3HX.js';
-export { CanvasStackContext } from '../chunk-CPUJ3QXL.js';
-import '../chunk-QCICIHEO.js';
+export { CanvasStack, PITCH_LIMIT, clampPitch, orbitAfterDrag, orbitAfterWheel, useOrbit, usePanZoom, wrapYaw } from '../chunk-HMFODCOX.js';
+export { centerOn, zoomAt } from '../chunk-CTRKTLYZ.js';
+export { DEFAULT_FRAME, applyCamera, resolveFrame, screenToWorld, worldToScreen } from '../chunk-2AYGEN57.js';
+export { CanvasStackContext } from '../chunk-CQLQPQ4P.js';
+import '../chunk-L5QJOOLV.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/chrome/index.d.ts

@@ -1,11 +1,12 @@
-import { c as ControlRenderer } from '../_dts/types-DCGEcMO_.js';
-import { I as Instrument, m as TrialChromeContext, T as TrialContribution } from '../_dts/types-BttTIent.js';
-export { f as IconComponent, S as SidebarSection, h as StatusReadout, k as ToolItem, l as ToolbarItem, n as TrialRegion, o as ViewportControl } from '../_dts/types-BttTIent.js';
+import { c as ControlRenderer } from '../_dts/types-D6s4b7if.js';
+import { I as Instrument, _ as TrialChromeContext, m as TrialContribution } from '../_dts/frac-C-2c72Ij.js';
+export { z as IconComponent, O as SidebarSection, Q as StatusReadout, Y as ToolItem, Z as ToolbarItem, $ as TrialRegion, a1 as ViewportControl } from '../_dts/frac-C-2c72Ij.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import '../_dts/PrefsForm-BYa6cWnO.js';
+import '../_dts/PrefsForm-BkUJZx0A.js';
 import 'react';
-import '../_dts/types-1Sdxy_Pv.js';
+import '../_dts/types-DYMaEvM5.js';
 import '../_dts/types-DJ79Tg5J.js';
+import '../_dts/types-C-gh9Ap-.js';
 
 /**
  * The contributions a trial gets from what its instrument declared. This is
@@ -44,7 +45,9 @@ interface SidebarRegionProps {
     contributions: readonly TrialContribution[];
     ctx: TrialChromeContext;
 }
-/** Lays a trial's `sidebar` contributions out as titled, collapsible sections. */
+/** Lays a trial's `sidebar` contributions out as titled, collapsible sections.
+ *  A section the trial has torn out is not rendered here — `Trial` portals its
+ *  body into the workspace instead. */
 declare function SidebarRegion({ contributions, ctx }: SidebarRegionProps): react_jsx_runtime.JSX.Element | null;
 
 /** Props for `<StatusRegion>`. */

package/dist/chrome/index.js

@@ -1,9 +1,9 @@
-export { PaletteRegion, SidebarRegion, StatusRegion, TitleBarRegion, ToolbarRegion, ViewportRegion, builtinContributions, mergeContributions, suppressContributions } from '../chunk-6X5RBC6G.js';
-import '../chunk-JDROYQM3.js';
-import '../chunk-WTI26YTM.js';
-import '../chunk-CPUJ3QXL.js';
+export { PaletteRegion, SidebarRegion, StatusRegion, TitleBarRegion, ToolbarRegion, ViewportRegion, builtinContributions, mergeContributions, suppressContributions } from '../chunk-6OEYTYML.js';
+import '../chunk-HHGVISVZ.js';
+import '../chunk-TO2FUOKF.js';
 import '../chunk-SBXNQW4G.js';
-import '../chunk-RGT4EJIB.js';
-import '../chunk-QCICIHEO.js';
+import '../chunk-RBGKL7NF.js';
+import '../chunk-CQLQPQ4P.js';
+import '../chunk-L5QJOOLV.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/chunk-2AYGEN57.js

@@ -0,0 +1,32 @@
+// src/canvas/worldSpec.ts
+var DEFAULT_FRAME = { originPx: { x: 0, y: 0 }, yDir: 1 };
+function resolveFrame(spec, size) {
+  if (!spec) return DEFAULT_FRAME;
+  const origin = spec.origin ?? { x: 0, y: 0 };
+  return {
+    originPx: { x: origin.x * size.width, y: origin.y * size.height },
+    yDir: spec.yAxis === "up" ? -1 : 1
+  };
+}
+function applyCamera(ctx, view, frame = DEFAULT_FRAME) {
+  ctx.translate(frame.originPx.x + view.pan.x, frame.originPx.y + view.pan.y);
+  ctx.scale(view.zoom, view.zoom * frame.yDir);
+}
+
+// src/canvas/canvasCoords.ts
+function worldToScreen(world, view, frame = DEFAULT_FRAME) {
+  return {
+    x: frame.originPx.x + view.pan.x + world.x * view.zoom,
+    y: frame.originPx.y + view.pan.y + world.y * view.zoom * frame.yDir
+  };
+}
+function screenToWorld(screen, view, frame = DEFAULT_FRAME) {
+  return {
+    x: (screen.x - frame.originPx.x - view.pan.x) / view.zoom,
+    y: (screen.y - frame.originPx.y - view.pan.y) / (view.zoom * frame.yDir)
+  };
+}
+
+export { DEFAULT_FRAME, applyCamera, resolveFrame, screenToWorld, worldToScreen };
+//# sourceMappingURL=chunk-2AYGEN57.js.map
+//# sourceMappingURL=chunk-2AYGEN57.js.map

package/dist/chunk-2AYGEN57.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/canvas/worldSpec.ts","../src/canvas/canvasCoords.ts"],"names":[],"mappings":";AA2BO,IAAM,aAAA,GAA4B,EAAE,QAAA,EAAU,EAAE,CAAA,EAAG,GAAG,CAAA,EAAG,CAAA,EAAE,EAAG,IAAA,EAAM,CAAA;AAEpE,SAAS,YAAA,CAAa,MAA6B,IAAA,EAAgC;AACxF,EAAA,IAAI,CAAC,MAAM,OAAO,aAAA;AAClB,EAAA,MAAM,SAAS,IAAA,CAAK,MAAA,IAAU,EAAE,CAAA,EAAG,CAAA,EAAG,GAAG,CAAA,EAAE;AAC3C,EAAA,OAAO;AAAA,IACL,QAAA,EAAU,EAAE,CAAA,EAAG,MAAA,CAAO,CAAA,GAAI,IAAA,CAAK,KAAA,EAAO,CAAA,EAAG,MAAA,CAAO,CAAA,GAAI,IAAA,CAAK,MAAA,EAAO;AAAA,IAChE,IAAA,EAAM,IAAA,CAAK,KAAA,KAAU,IAAA,GAAO,EAAA,GAAK;AAAA,GACnC;AACF;AAIO,SAAS,WAAA,CACd,GAAA,EACA,IAAA,EACA,KAAA,GAAoB,aAAA,EACd;AACN,EAAA,GAAA,CAAI,SAAA,CAAU,KAAA,CAAM,QAAA,CAAS,CAAA,GAAI,IAAA,CAAK,GAAA,CAAI,CAAA,EAAG,KAAA,CAAM,QAAA,CAAS,CAAA,GAAI,IAAA,CAAK,GAAA,CAAI,CAAC,CAAA;AAC1E,EAAA,GAAA,CAAI,MAAM,IAAA,CAAK,IAAA,EAAM,IAAA,CAAK,IAAA,GAAO,MAAM,IAAI,CAAA;AAC7C;;;ACvCO,SAAS,aAAA,CACd,KAAA,EACA,IAAA,EACA,KAAA,GAAoB,aAAA,EACb;AACP,EAAA,OAAO;AAAA,IACL,CAAA,EAAG,MAAM,QAAA,CAAS,CAAA,GAAI,KAAK,GAAA,CAAI,CAAA,GAAI,KAAA,CAAM,CAAA,GAAI,IAAA,CAAK,IAAA;AAAA,IAClD,CAAA,EAAG,KAAA,CAAM,QAAA,CAAS,CAAA,GAAI,IAAA,CAAK,GAAA,CAAI,CAAA,GAAI,KAAA,CAAM,CAAA,GAAI,IAAA,CAAK,IAAA,GAAO,KAAA,CAAM;AAAA,GACjE;AACF;AAGO,SAAS,aAAA,CACd,MAAA,EACA,IAAA,EACA,KAAA,GAAoB,aAAA,EACb;AACP,EAAA,OAAO;AAAA,IACL,CAAA,EAAA,CAAI,OAAO,CAAA,GAAI,KAAA,CAAM,SAAS,CAAA,GAAI,IAAA,CAAK,GAAA,CAAI,CAAA,IAAK,IAAA,CAAK,IAAA;AAAA,IACrD,CAAA,EAAA,CAAI,MAAA,CAAO,CAAA,GAAI,KAAA,CAAM,QAAA,CAAS,CAAA,GAAI,IAAA,CAAK,GAAA,CAAI,CAAA,KAAM,IAAA,CAAK,IAAA,GAAO,KAAA,CAAM,IAAA;AAAA,GACrE;AACF","file":"chunk-2AYGEN57.js","sourcesContent":["import type { Point, ViewTransform } from '../instrument/types';\n\n/** How an instrument's world sits on the canvas, independent of the camera.\n *  The defaults reproduce the convention labkit shipped before this existed:\n *  world (0,0) at the element's top-left, y growing downward. */\nexport interface WorldSpec {\n  /** Where world (0,0) sits at `pan` zero, as a fraction of the viewport.\n   *  `{x:0,y:0}` top-left (default); `{x:0.5,y:0.5}` centre. */\n  origin?: Point;\n  /** Which way the world y axis runs on screen. Default `'down'`. */\n  yAxis?: 'down' | 'up';\n}\n\n/** A viewport's CSS-pixel size. */\nexport interface ViewportSize {\n  width: number;\n  height: number;\n}\n\n/** A `WorldSpec` resolved against a viewport: what the coordinate helpers,\n *  the camera and the wheel all read. */\nexport interface WorldFrame {\n  /** Screen position of world (0,0) at `pan` zero. */\n  originPx: Point;\n  yDir: 1 | -1;\n}\n\nexport const DEFAULT_FRAME: WorldFrame = { originPx: { x: 0, y: 0 }, yDir: 1 };\n\nexport function resolveFrame(spec: WorldSpec | undefined, size: ViewportSize): WorldFrame {\n  if (!spec) return DEFAULT_FRAME;\n  const origin = spec.origin ?? { x: 0, y: 0 };\n  return {\n    originPx: { x: origin.x * size.width, y: origin.y * size.height },\n    yDir: spec.yAxis === 'up' ? -1 : 1,\n  };\n}\n\n/** Put a 2D context into the instrument's world coordinates, so a layer's\n *  `draw` works in them. Must stay the exact inverse of `screenToWorld`. */\nexport function applyCamera(\n  ctx: CanvasRenderingContext2D,\n  view: ViewTransform,\n  frame: WorldFrame = DEFAULT_FRAME,\n): void {\n  ctx.translate(frame.originPx.x + view.pan.x, frame.originPx.y + view.pan.y);\n  ctx.scale(view.zoom, view.zoom * frame.yDir);\n}\n","import type { Point, ViewTransform } from '../instrument/types';\nimport { DEFAULT_FRAME, type WorldFrame } from './worldSpec';\n\n/** Project a world point into screen coordinates under a view.\n *\n *  `frame` is the instrument's declared coordinate system, resolved against the\n *  viewport; omitting it gives labkit's original one — origin at the top-left,\n *  y downward. */\nexport function worldToScreen(\n  world: Point,\n  view: ViewTransform,\n  frame: WorldFrame = DEFAULT_FRAME,\n): Point {\n  return {\n    x: frame.originPx.x + view.pan.x + world.x * view.zoom,\n    y: frame.originPx.y + view.pan.y + world.y * view.zoom * frame.yDir,\n  };\n}\n\n/** Unproject a screen point back to world coordinates under a view. */\nexport function screenToWorld(\n  screen: Point,\n  view: ViewTransform,\n  frame: WorldFrame = DEFAULT_FRAME,\n): Point {\n  return {\n    x: (screen.x - frame.originPx.x - view.pan.x) / view.zoom,\n    y: (screen.y - frame.originPx.y - view.pan.y) / (view.zoom * frame.yDir),\n  };\n}\n"]}