@weasel-js/labkit 1.7.0 → 1.7.1

package/dist/job/index.d.ts

@@ -1,12 +1,20 @@
 import { a as JobCapability, J as JobHandle } from '../_dts/types-DJ79Tg5J.js';
 export { b as JobEvent, c as JobFailure, d as JobStatus } from '../_dts/types-DJ79Tg5J.js';
 
+/** Inputs to `useJob`. `setState` receives each item folded in by the
+ *  capability's `onItem`. */
 interface UseJobOptions<TS, TC, TItem> {
     capability: JobCapability<TS, TC, TItem>;
     config: TC;
     state: TS;
     setState: (next: TS | ((prev: TS) => TS)) => void;
 }
+/**
+ * Drive a `JobCapability` and report its progress. `start` cancels any run in
+ * flight and begins again; results from a superseded or canceled run are
+ * dropped. With `auto`, it starts on mount and again whenever `key` changes
+ * element-wise. Unmounting aborts the run.
+ */
 declare function useJob<TS, TC, TItem>({ capability, config, state, setState, }: UseJobOptions<TS, TC, TItem>): JobHandle;
 
 export { JobCapability, JobHandle, useJob };

package/dist/job/index.js

@@ -1,3 +1,3 @@
-export { useJob } from '../chunk-HXXTULDN.js';
+export { useJob } from '../chunk-EFXRM6XQ.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/layers/index.d.ts

@@ -1,8 +1,9 @@
-export { L as LayerList, a as LayerListItem, b as LayerListProps, c as LayerMove, m as moveLayers } from '../_dts/LayerList.d-DiuEArKq.js';
-export { L as LayerCapability, a as LayerDescriptor } from '../_dts/types-CSm9jgol.js';
+export { LayerList, LayerListItem, LayerListProps, LayerMove, moveLayers } from '@weasel-js/ui';
+export { ad as LayerCapability, ae as LayerDescriptor } from '../_dts/index-DCMA4Fy1.js';
+import '@weasel-js/core';
 import 'react';
-import '../_dts/PrefsRow.d-TOZ7BgD9.js';
 import '@weasel-js/theme';
-import '@weasel-js/core';
-import '../_dts/types-CRPSGFAp.js';
+import '../_dts/types-BUBSIZuV.js';
+import '@weasel-js/quantity';
+import '@weasel-js/geom';
 import '../_dts/types-DJ79Tg5J.js';

package/dist/layers/index.js

@@ -1,5 +1,6 @@
 import '../chunk-2RVCB2PT.js';
-export { E3 as LayerList, x3 as moveLayers } from '../chunk-MIM5R4ZT.js';
-import '../chunk-275JRRVD.js';
+export { D2 as LayerList, S2 as moveLayers } from '../chunk-4KSC7NXL.js';
+import '../chunk-E23Q6A3Y.js';
+import '../chunk-XVUKDSYV.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/loupe/index.d.ts

@@ -1,14 +1,16 @@
-import { ai as LoupePoint, ah as LoupeMode, aj as LoupeRenderArgs, am as ResolvedLoupe } from '../_dts/types-CSm9jgol.js';
-import { WorldFrame, WorldSpec, ViewportSize } from '../canvas/index.js';
-import { ViewTransform } from '../index.js';
-export { ae as LOUPE_DEFAULTS, af as LoupeCapability, ag as LoupeDeclaration, aK as resolveLoupe } from '../_dts/types-CSm9jgol.js';
+import { LoupePoint, LoupeMode } from '@weasel-js/loupe';
+export { LoupeMode, LoupePoint } from '@weasel-js/loupe';
 import * as react from 'react';
-import { RefObject, ReactNode } from 'react';
+import { ReactNode, RefObject } from 'react';
 import { CanvasStackSurface, CanvasLayerDescriptor } from '../canvas/index.js';
+import { WorldFrame, WorldSpec, ViewportSize } from '../canvas/index.js';
+import { ViewTransform } from '../index.js';
 import { Action } from '@weasel-js/core';
-import '../_dts/PrefsRow.d-TOZ7BgD9.js';
+import '@weasel-js/ui';
 import '@weasel-js/theme';
-import '../_dts/types-CRPSGFAp.js';
+import '../_dts/types-BUBSIZuV.js';
+import '@weasel-js/quantity';
+import '@weasel-js/geom';
 import '../_dts/types-DJ79Tg5J.js';
 
 /** Props for `<CanvasLoupe>`. */
@@ -77,6 +79,71 @@ declare function drawCanvasLens(ctx: CanvasRenderingContext2D, opts: {
     canvases: Map<string, HTMLCanvasElement>;
 }): void;
 
+/** What a DOM loupe's `render` is handed: the camera to draw the content
+ *  through again. */
+interface LoupeRenderArgs {
+    /** The trial's own camera composed with the magnification, about the aimed
+     *  point — so drawing the same content through it magnifies in place. */
+    view: ViewTransform;
+    /** The magnification on its own, for whatever must not scale with the
+     *  camera. */
+    factor: number;
+    mode: LoupeMode;
+    /** The size of the viewport `view` is written for: the trial's content well,
+     *  not the lens. The lens shows a circle cut out of it. */
+    size: ViewportSize;
+}
+/**
+ * How a lens magnifies.
+ *
+ * With no `render`, the lens re-draws the canvas stack's layers through a
+ * zoomed camera, so it stays sharp at any factor. Over DOM content, `render`
+ * draws it instead: given a camera, draw me again.
+ */
+interface LoupeOptions {
+    render?: (args: LoupeRenderArgs) => ReactNode;
+    /** Opening magnification, clamped to the bounds below. Default 6. */
+    factor?: number;
+    /** What the wheel clamps to. Defaults 2 and 32. */
+    minFactor?: number;
+    maxFactor?: number;
+    /** `'vector'` (default) re-renders the content magnified; `'pixel'` blows up
+     *  the pixels the instrument presented. A `render` loupe is always vector —
+     *  DOM has no framebuffer to enlarge. */
+    mode?: LoupeMode;
+    /** Lens diameter in CSS px. Default 200. */
+    diameter?: number;
+    /** Held for a momentary peek while the loupe is off. Default `'Alt'`; `null`
+     *  turns hold-to-peek off. Matched against `KeyboardEvent.key`. */
+    peekKey?: string | null;
+    /** Called with the color under the aim, wherever the surface can say. The
+     *  canvas painter reads it back; a DOM loupe has no pixels to sample. */
+    onColorChange?: (hex: string) => void;
+}
+/** {@link LoupeOptions} with every default filled in. */
+interface ResolvedLoupe {
+    render?: (args: LoupeRenderArgs) => ReactNode;
+    onColorChange?: (hex: string) => void;
+    factor: number;
+    minFactor: number;
+    maxFactor: number;
+    mode: LoupeMode;
+    diameter: number;
+    peekKey: string | null;
+}
+/** What `resolveLoupe` fills in for anything a declaration leaves unset. */
+declare const LOUPE_DEFAULTS: {
+    readonly factor: 6;
+    readonly minFactor: 2;
+    readonly maxFactor: 32;
+    readonly mode: "vector";
+    readonly diameter: 200;
+    readonly peekKey: "Alt";
+};
+/** `options` with every default filled in and `factor` clamped to
+ *  `[minFactor, maxFactor]`. A loupe with its own `render` is always `'vector'`. */
+declare function resolveLoupe(options?: LoupeOptions): ResolvedLoupe;
+
 /** Props for `<DomLoupe>`. */
 interface DomLoupeProps {
     aim: LoupePoint;
@@ -88,12 +155,10 @@ interface DomLoupeProps {
     /** The trial's own camera. */
     view: ViewTransform;
     frame?: WorldFrame;
-    state: unknown;
-    config: unknown;
     render: (args: LoupeRenderArgs) => React.ReactNode;
 }
 /**
- * Paints a lens over DOM content by asking the instrument to draw itself again
+ * Paints a lens over DOM content by asking its `render` to draw it again
  * at a magnified camera.
  *
  * The stage is a full copy of the host, so the instrument's own layout still
@@ -101,7 +166,7 @@ interface DomLoupeProps {
  * where it already was, and the stage is then slid by `diameter / 2 - aim` to
  * bring it to the middle of the lens.
  */
-declare function DomLoupe({ aim, factor, mode, diameter, size, view, frame, state, config, render, }: DomLoupeProps): react.JSX.Element;
+declare function DomLoupe({ aim, factor, mode, diameter, size, view, frame, render, }: DomLoupeProps): react.JSX.Element;
 
 /** Props for `<LoupeBubble>`. */
 interface LoupeBubbleProps {
@@ -170,29 +235,34 @@ interface LoupeGesturesProps {
 declare function LoupeGestures(props: LoupeGesturesProps): react.JSX.Element | null;
 
 /** Props for `<TrialLoupe>`. */
-interface TrialLoupeProps {
-    capability: ResolvedLoupe;
-    /** Whether the trial's loupe is turned on. Hold-to-peek shows it anyway. */
-    enabled: boolean;
-    state: unknown;
-    config: unknown;
-    /** The trial's own camera. */
-    view: ViewTransform;
-    worldSpec?: WorldSpec;
-    /** The element the lens tracks. A loupe mounted inside a `<CanvasStack>`
-     *  takes the stack's own element instead, and this goes unused. */
+interface TrialLoupeProps extends LoupeOptions {
+    /** Whether the lens is turned on. Omitted, it follows the trial's toolbar
+     *  toggle, which the trial offers while a lens like this is mounted — and is
+     *  off outside a trial. Hold-to-peek shows it either way. */
+    enabled?: boolean;
+    /** The camera a `render` lens composes its magnification onto. Defaults to
+     *  the camera around it, and to the identity outside one. */
+    view?: ViewTransform;
+    /** The element the lens tracks. Defaults to the canvas stack or stage around
+     *  it, and outside both to a box wrapped around `children`. */
     hostRef?: RefObject<HTMLElement | null>;
+    /** Content for the lens to sit over. Wrapped in a box of the lens's own only
+     *  when nothing around it gives the lens an element to track. */
+    children?: ReactNode;
 }
 /**
- * A trial's loupe, painted by whichever painter suits its content: the canvas
- * stack it is mounted inside, or the instrument's own `render` at a magnified
- * camera.
+ * A trial's magnifier, mounted by the instrument wherever its content is: in
+ * a canvas instrument's `render`, a stage's `overlay`, or around DOM content.
+ *
+ * With no `render` inside a `<CanvasStack>`, it re-draws the stack's own
+ * layers through a zoomed camera. With `render`, it asks for the content again
+ * at a magnified camera.
  */
-declare function TrialLoupe({ capability, enabled, state, config, view, worldSpec, hostRef, }: TrialLoupeProps): react.JSX.Element;
+declare function TrialLoupe({ enabled, view, hostRef, children, render, factor, minFactor, maxFactor, mode, diameter, peekKey, onColorChange, }: TrialLoupeProps): react.JSX.Element;
 
 /** Options for {@link useLoupe}. */
 interface UseLoupeOptions {
-    capability: ResolvedLoupe;
+    options: ResolvedLoupe;
     /** The element the lens tracks the pointer across. */
     hostRef: RefObject<HTMLElement | null>;
     /** Whether the loupe is turned on. Hold-to-peek shows it regardless. */
@@ -229,7 +299,7 @@ interface LoupeState {
  * has no continuous-motion entry, and inventing one to carry the lens' aim
  * would be an input taxonomy change, not a loupe change.
  */
-declare function useLoupe({ capability, hostRef, enabled, sample }: UseLoupeOptions): LoupeState;
+declare function useLoupe({ options, hostRef, enabled, sample }: UseLoupeOptions): LoupeState;
 
-export { CanvasLoupe, DomLoupe, LOUPE_MAGNIFY_ID, LOUPE_PEEK_ID, LoupeBubble, LoupeGestures, LoupeMode, LoupePoint, LoupeRenderArgs, ResolvedLoupe, TrialLoupe, createLoupeActions, drawCanvasLens, lensCamera, lensSourceRect, sampleStack, useLoupe };
-export type { CanvasLoupeProps, DomLoupeProps, LensCamera, LoupeBubbleProps, LoupeGesturesProps, LoupeInputApi, LoupeState, SourceRect, TrialLoupeProps, UseLoupeOptions };
+export { CanvasLoupe, DomLoupe, LOUPE_DEFAULTS, LOUPE_MAGNIFY_ID, LOUPE_PEEK_ID, LoupeBubble, LoupeGestures, TrialLoupe, createLoupeActions, drawCanvasLens, lensCamera, lensSourceRect, resolveLoupe, sampleStack, useLoupe };
+export type { CanvasLoupeProps, DomLoupeProps, LensCamera, LoupeBubbleProps, LoupeGesturesProps, LoupeInputApi, LoupeOptions, LoupeRenderArgs, LoupeState, ResolvedLoupe, SourceRect, TrialLoupeProps, UseLoupeOptions };