@reekon-tools/boldr-utils 1.15.0 → 1.15.2

package/dist/annotation/canvas/tools/planeTool.js

@@ -0,0 +1,357 @@
+import { DEFAULT_LAYER_ID } from '../../../types/annotation.js';
+import { isQuadConvexNonDegenerate, normalizeQuadOrder, planeEdgeLine, } from '../planeGeometry.js';
+import { linePosOf, recomputeAnchor, DEFAULT_LINE_POS, } from '../measurementGeometry.js';
+import { FormulaColors } from '../../../theme/colors.js';
+// Screen-px grab radius for an existing plane's corner/endpoint handles while
+// the tool is active (matches the drawn handle affordance scale).
+const HANDLE_GRAB_PX = 18;
+// Screen-px radius of the placed-corner dots drawn while marking a quad.
+const VERTEX_DOT_PX = 6;
+// Preview chrome color — matches PlaneElement's calibration purple.
+const PLANE_COLOR = FormulaColors.purple;
+let counter = 0;
+const makeId = (prefix) => `${prefix}-${Date.now().toString(36)}-${(counter++).toString(36)}`;
+const firstLayerId = (doc) => doc.layers[0]?.id ?? DEFAULT_LAYER_ID;
+const distSq = (a, b) => {
+    const dx = a.x - b.x;
+    const dy = a.y - b.y;
+    return dx * dx + dy * dy;
+};
+// The document's (single, v1) committed calibration this tool can edit.
+const committedPlane = (doc) => doc.planes?.[0] ?? null;
+// The grabbable points of a committed plane: quad corners, or the reference
+// line's endpoints.
+const planeHandles = (plane) => plane.mode === 'perspective'
+    ? plane.corners
+    : [plane.refLine.a, plane.refLine.b];
+// The committed plane with one handle moved to `p`.
+const withHandleMoved = (plane, index, p) => {
+    if (plane.mode === 'perspective') {
+        const corners = plane.corners.map((c, i) => (i === index ? p : c));
+        return { ...plane, corners };
+    }
+    return {
+        ...plane,
+        refLine: index === 0 ? { ...plane.refLine, a: p } : { ...plane.refLine, b: p },
+    };
+};
+// The dimension slots a mode carries a tile for.
+const edgesForMode = (mode) => mode === 'perspective' ? ['top', 'right', 'bottom', 'left'] : ['ref'];
+// A fresh dimension tile magnetized to one plane edge (see the planeEdge doc
+// on PlacedMeasurementRef).
+const buildDimensionTile = (doc, plane, edge) => {
+    const line = planeEdgeLine(plane, edge);
+    if (!line)
+        return null;
+    return {
+        id: makeId('plane-dim'),
+        layerId: firstLayerId(doc),
+        placement: 'line',
+        line,
+        linePos: DEFAULT_LINE_POS,
+        anchor: recomputeAnchor(line, 'line', DEFAULT_LINE_POS, line.a),
+        planeId: plane.id,
+        planeEdge: edge,
+        // The tile's line IS the plane edge PlaneElement already draws — style it
+        // as the same cyan stroke so it disappears into the outline instead of
+        // painting the default measurement blue on top of it.
+        lineColor: PLANE_COLOR,
+        lineWidth: 4,
+        showLabel: true,
+        showValue: true,
+        createdAt: Date.now(),
+    };
+};
+// Ops that pin every dimension tile of `plane` back onto its (just-moved)
+// edge, preserving each tile's slid position along it. Emitted alongside the
+// setPlane in the same patch, so a corner drag is one undo step.
+const syncDimensionTileOps = (doc, plane) => {
+    const ops = [];
+    for (const m of doc.placedMeasurements) {
+        if (m.planeId !== plane.id || !m.planeEdge)
+            continue;
+        const line = planeEdgeLine(plane, m.planeEdge);
+        if (!line)
+            continue;
+        ops.push({
+            op: 'updateMeasurement',
+            id: m.id,
+            patch: {
+                line,
+                anchor: recomputeAnchor(line, 'line', linePosOf(m), m.anchor),
+            },
+        });
+    }
+    return ops;
+};
+// Ops that remove a calibration AND its dimension tiles — the replace flow
+// when new geometry is marked while a plane exists (v1: one per canvas).
+const removePlaneOps = (doc, plane) => [
+    ...doc.placedMeasurements
+        .filter((m) => m.planeId === plane.id)
+        .map((m) => ({ op: 'removeMeasurement', id: m.id })),
+    { op: 'removePlane', id: plane.id },
+];
+// Plane-calibration tool. Two jobs, both Skia-free and JS-dispatched on native
+// (like polygonTool/measurementTool):
+//  - MARK new geometry: scale mode rubber-bands a reference line
+//    (measurementTool's drag pattern); perspective mode places 4 corners by
+//    tapping (polygonTool's pattern). Completion COMMITS the plane at once —
+//    geometry only, dimensions blank — together with a dimension tile per
+//    edge, replacing any existing plane (and its tiles) in the same undoable
+//    patch. The user then enters real-world sizes through the tiles.
+//  - EDIT the committed plane: while active, grabbing a corner/endpoint drags
+//    it with a live preview (the grid and dimension tiles follow through the
+//    preview patch) and commits one setPlane (+tile sync) per drag — a single
+//    undo step. A drag that would make the quad non-convex snaps back on
+//    release.
+// In-progress marks render through preview patches (line/polygon draft shapes
+// + vertex dots), so no platform-specific preview plumbing is needed.
+export const createPlaneTool = (options) => {
+    const mode = options.mode;
+    const minDragPx = options.minDragPx ?? 4;
+    // In-progress quad corners (span gestures — the canvas clears ToolState per
+    // pointer-up, so they live in the factory closure like polygonTool's).
+    let vertices = [];
+    let draftId = null;
+    // Preview of the in-progress mark: the polyline/line so far plus a dot per
+    // placed vertex. Preview-only shapes riding the preview patch — never
+    // committed.
+    const previewOps = (doc, zoom, rubber) => {
+        const pts = rubber ? [...vertices, rubber] : [...vertices];
+        const ops = [];
+        if (pts.length >= 2) {
+            ops.push({
+                op: 'addShape',
+                shape: {
+                    id: `${draftId}-draft`,
+                    layerId: firstLayerId(doc),
+                    kind: 'polygon',
+                    geometry: { points: pts, closed: pts.length >= 4 },
+                    style: { stroke: PLANE_COLOR, strokeWidth: 6 / zoom, dash: true },
+                    createdAt: 0,
+                },
+            });
+        }
+        pts.forEach((v, i) => {
+            const r = VERTEX_DOT_PX / zoom;
+            ops.push({
+                op: 'addShape',
+                shape: {
+                    id: `${draftId}-v${i}`,
+                    layerId: firstLayerId(doc),
+                    kind: 'ellipse',
+                    geometry: {
+                        points: [
+                            { x: v.x - r, y: v.y - r },
+                            { x: v.x + r, y: v.y + r },
+                        ],
+                    },
+                    style: { fill: PLANE_COLOR, stroke: '#FFFFFF', strokeWidth: r / 3 },
+                    createdAt: 0,
+                },
+            });
+        });
+        return ops;
+    };
+    const reset = () => {
+        vertices = [];
+        draftId = null;
+    };
+    // Commit freshly marked geometry: the plane (dimensions blank until the
+    // user enters them) plus its dimension tiles, replacing any existing plane
+    // — one undoable patch.
+    const commitPlane = (ctx, geometry) => {
+        const doc = ctx.document;
+        const plane = geometry.mode === 'scale'
+            ? {
+                id: makeId('plane'),
+                mode: 'scale',
+                refLine: geometry.refLine,
+                createdAt: Date.now(),
+            }
+            : {
+                id: makeId('plane'),
+                mode: 'perspective',
+                corners: geometry.corners,
+                createdAt: Date.now(),
+            };
+        const existing = committedPlane(doc);
+        const ops = [
+            ...(existing ? removePlaneOps(doc, existing) : []),
+            { op: 'setPlane', plane },
+            ...edgesForMode(plane.mode).flatMap((edge) => {
+                const tile = buildDimensionTile(doc, plane, edge);
+                return tile
+                    ? [{ op: 'addMeasurement', measurement: tile }]
+                    : [];
+            }),
+        ];
+        reset();
+        ctx.preview({ ops: [] });
+        ctx.commit({ ops });
+        options.onPlaced?.(plane);
+    };
+    // Which committed-plane handle a press landed on, if any.
+    const hitHandle = (ctx, world) => {
+        const plane = committedPlane(ctx.document);
+        if (!plane)
+            return null;
+        const tol = HANDLE_GRAB_PX / ctx.viewport.state.zoom;
+        const tolSq = tol * tol;
+        const handles = planeHandles(plane);
+        for (let i = 0; i < handles.length; i++) {
+            if (distSq(world, handles[i]) <= tolSq)
+                return i;
+        }
+        return null;
+    };
+    return {
+        id: options.id ?? `plane-${mode}`,
+        label: options.label ??
+            (mode === 'perspective' ? 'Perspective plane' : 'Scale reference'),
+        cursor: 'crosshair',
+        planeEditing: true,
+        onPointerDown(event, ctx) {
+            // Editing an existing plane wins over starting new geometry — but only
+            // when nothing is mid-mark (a quad in progress keeps collecting taps).
+            if (vertices.length === 0) {
+                const handleIndex = hitHandle(ctx, event.world);
+                if (handleIndex != null) {
+                    return { kind: 'plane-handle-drag', handleIndex, moved: false };
+                }
+            }
+            if (mode === 'scale') {
+                return {
+                    kind: 'plane-scale-drawing',
+                    startWorld: event.world,
+                    startScreen: event.screen,
+                    moved: false,
+                };
+            }
+            return { kind: 'plane-quad-pointing' };
+        },
+        onPointerMove(event, ctx, state) {
+            const s = state;
+            if (!s)
+                return s;
+            if (s.kind === 'plane-handle-drag') {
+                const plane = committedPlane(ctx.document);
+                if (!plane)
+                    return s;
+                const moved = withHandleMoved(plane, s.handleIndex, event.world);
+                // Dimension tiles ride along in the same preview so the whole
+                // calibration — outline, grid, tiles — tracks the finger.
+                ctx.preview({
+                    ops: [
+                        { op: 'setPlane', plane: moved },
+                        ...syncDimensionTileOps(ctx.document, moved),
+                    ],
+                });
+                return { ...s, moved: true };
+            }
+            // New geometry can't be marked while a calibration exists (delete it
+            // first) — suppress the rubber-band so nothing appears to happen and
+            // the pointer-up path explains why.
+            if (committedPlane(ctx.document))
+                return s;
+            if (s.kind === 'plane-scale-drawing') {
+                if (!draftId)
+                    draftId = makeId('plane-draft');
+                vertices = [s.startWorld];
+                ctx.preview({
+                    ops: previewOps(ctx.document, ctx.viewport.state.zoom, event.world),
+                });
+                vertices = [];
+                return { ...s, moved: true };
+            }
+            // Quad marking: rubber the next edge from the placed corners.
+            if (vertices.length > 0) {
+                ctx.preview({
+                    ops: previewOps(ctx.document, ctx.viewport.state.zoom, event.world),
+                });
+            }
+            return s;
+        },
+        onPointerUp(event, ctx, state) {
+            const s = state;
+            if (!s)
+                return;
+            if (s.kind === 'plane-handle-drag') {
+                ctx.preview({ ops: [] });
+                if (!s.moved)
+                    return;
+                const plane = committedPlane(ctx.document);
+                if (!plane)
+                    return;
+                const next = withHandleMoved(plane, s.handleIndex, event.world);
+                // A corner drag that breaks the quad snaps back instead of committing
+                // a plane the homography can't invert.
+                if (next.mode === 'perspective' &&
+                    !isQuadConvexNonDegenerate(next.corners)) {
+                    options.onInvalidQuad?.();
+                    return;
+                }
+                ctx.commit({
+                    ops: [
+                        { op: 'setPlane', plane: next },
+                        ...syncDimensionTileOps(ctx.document, next),
+                    ],
+                });
+                return;
+            }
+            // Creation is blocked while a calibration exists (only its handles are
+            // editable) — the user deletes it first to re-mark.
+            if (committedPlane(ctx.document)) {
+                options.onExistingPlane?.();
+                return;
+            }
+            if (s.kind === 'plane-scale-drawing') {
+                ctx.preview({ ops: [] });
+                const dx = event.screen.x - s.startScreen.x;
+                const dy = event.screen.y - s.startScreen.y;
+                if (!s.moved || dx * dx + dy * dy < minDragPx * minDragPx)
+                    return;
+                commitPlane(ctx, {
+                    mode: 'scale',
+                    refLine: { a: s.startWorld, b: event.world },
+                });
+                return;
+            }
+            // Quad marking: each tap places a corner; the 4th completes.
+            if (!draftId)
+                draftId = makeId('plane-draft');
+            vertices = [...vertices, { x: event.world.x, y: event.world.y }];
+            if (vertices.length < 4) {
+                ctx.preview({
+                    ops: previewOps(ctx.document, ctx.viewport.state.zoom),
+                });
+                return;
+            }
+            const corners = normalizeQuadOrder(vertices);
+            if (!corners) {
+                // Drop the offending 4th corner; the first three stay marked.
+                vertices = vertices.slice(0, 3);
+                ctx.preview({
+                    ops: previewOps(ctx.document, ctx.viewport.state.zoom),
+                });
+                options.onInvalidQuad?.();
+                return;
+            }
+            commitPlane(ctx, { mode: 'perspective', corners });
+        },
+        // Gesture interrupted (a second finger landed and the viewport pan took
+        // over): keep the placed corners and re-establish their preview — the
+        // canvas clears the preview patch before calling this.
+        onCancel(_state, ctx) {
+            if (vertices.length === 0)
+                return;
+            ctx.preview({ ops: previewOps(ctx.document, ctx.viewport.state.zoom) });
+        },
+        // Switching tools mid-mark discards the unfinished geometry — unlike a
+        // polygon, a partial calibration has no committable meaning.
+        onDeactivate() {
+            reset();
+        },
+    };
+};

package/dist/annotation/canvas/tools/selectTool.js

@@ -209,6 +209,11 @@ const classifyGrab = (doc, id, world, zoom, viewportTileScale = 1, tileScaleFact
     const halfH = (dims.height / 2 + HIT_PADDING) / zoom;
     const onTile = Math.abs(world.x - m.anchor.x) <= halfW &&
         Math.abs(world.y - m.anchor.y) <= halfH;
+    // A plane-dimension tile is locked to its calibration edge: EVERY grab
+    // slides it along the edge line — a group move would pull it off the plane
+    // geometry it annotates (the plane tool owns moving the geometry itself).
+    if (m.planeEdge && placementOf(m) === 'line' && m.line)
+        return 'slide';
     return onTile && placementOf(m) === 'line' && m.line ? 'slide' : 'move';
 };
 // Slide the tile along its line by a world-space drag delta (relative to
@@ -238,6 +243,10 @@ const findHandleHit = (doc, id, world, zoom) => {
     const m = doc.placedMeasurements.find((x) => x.id === id);
     if (!m || !m.line || placementOf(m) !== 'line')
         return null;
+    // A plane-dimension tile's line IS the calibration edge — no endpoint
+    // editing here; the plane tool drags the plane's corners instead.
+    if (m.planeEdge)
+        return null;
     const r2 = (HANDLE_GRAB_PX / zoom) ** 2;
     const da = (world.x - m.line.a.x) ** 2 + (world.y - m.line.a.y) ** 2;
     const db = (world.x - m.line.b.x) ** 2 + (world.y - m.line.b.y) ** 2;

package/dist/annotation/canvas/useAnnotationCanvasState.d.ts

@@ -1,5 +1,5 @@
 import type { Measurement } from '../../types/firestore.js';
-import { type AnnotationCanvasState, type AnnotationDocumentPatch, type AnnotationElementId, type AnnotationStroke, type MeasurementPlacement, type Selection, type TileScalePlatform, type Vec2 } from '../../types/annotation.js';
+import { type AnnotationCanvasState, type AnnotationDocumentPatch, type AnnotationElementId, type AnnotationStroke, type MeasurementPlacement, type PlaneCalibration, type Selection, type TileScalePlatform, type Vec2 } from '../../types/annotation.js';
 import type { FileRef, MeasurementRef } from './measurementPicker.js';
 import type { CanvasPointerEvent, RequestTextInput, Tool, ToolContext, ToolState } from './Tool.js';
 import { type ViewportState } from './viewport.js';
@@ -51,6 +51,8 @@ export interface AnnotationCanvasHandle {
     placeFileAtCenter(ref: FileRef): AnnotationElementId;
     setGroupHeaderCollapsed(id: AnnotationElementId, collapsed: boolean): void;
     deleteSelected(): void;
+    setPlane(plane: PlaneCalibration): void;
+    removePlane(id: string): void;
 }
 export interface UseAnnotationCanvasStateProps {
     canvas: AnnotationCanvasState;

package/dist/annotation/canvas/useAnnotationCanvasState.js

@@ -788,6 +788,23 @@ export const useAnnotationCanvasState = (props) => {
                 c.commit({ ops });
                 c.setSelection(null);
             },
+            setPlane(plane) {
+                ctxRef.current.commit({ ops: [{ op: 'setPlane', plane }] });
+            },
+            removePlane(id) {
+                // The calibration's dimension tiles (planeId) go with it — orphaned
+                // entry tiles would keep rendering with nothing to write to. One
+                // undoable patch.
+                const c = ctxRef.current;
+                c.commit({
+                    ops: [
+                        ...c.document.placedMeasurements
+                            .filter((m) => m.planeId === id)
+                            .map((m) => ({ op: 'removeMeasurement', id: m.id })),
+                        { op: 'removePlane', id },
+                    ],
+                });
+            },
         };
         return () => {
             if (imperativeRef)

package/dist/canvas/AnnotationCanvas.d.ts

@@ -0,0 +1,11 @@
+import { type ReactNode } from 'react';
+import type { AnnotationCanvasInnerProps } from './AnnotationCanvasInner.js';
+export type { AnnotationCanvasHandle, GestureConfig, PanTrigger, } from './AnnotationCanvasInner.js';
+export interface CanvasKitOpts {
+    locateFile?: (file: string) => string;
+}
+export type AnnotationCanvasProps = AnnotationCanvasInnerProps & {
+    fallback?: ReactNode;
+    canvasKitOpts?: CanvasKitOpts;
+};
+export declare const AnnotationCanvas: ({ fallback, canvasKitOpts, ...rest }: AnnotationCanvasProps) => import("react/jsx-runtime").JSX.Element;

package/dist/canvas/AnnotationCanvas.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { WithSkiaWeb } from '@shopify/react-native-skia/lib/module/web/index.js';
+// Web-only entry point: lazy-loads CanvasKit wasm via WithSkiaWeb. Imperative
+// API (undo/redo/zoom) is exposed through the `imperativeRef` prop rather
+// than React refs, since WithSkiaWeb can't forward refs through its lazy
+// component boundary. The native build sits in `AnnotationCanvas.native.tsx`
+// and skips WithSkiaWeb entirely (no wasm to load).
+export const AnnotationCanvas = ({ fallback, canvasKitOpts, ...rest }) => (_jsx(WithSkiaWeb, { getComponent: () => import('./AnnotationCanvasInner.js').then((m) => ({
+        default: m.AnnotationCanvasInner,
+    })), fallback: fallback ?? null, componentProps: rest, opts: canvasKitOpts }));

package/dist/canvas/AnnotationCanvas.native.d.ts

@@ -0,0 +1,8 @@
+import type { AnnotationCanvasInnerProps } from './AnnotationCanvasInner.native.js';
+export type { AnnotationCanvasHandle, } from './useAnnotationCanvasState.js';
+export type { GestureConfig, PanTrigger, } from './AnnotationCanvasInner.js';
+export type AnnotationCanvasProps = AnnotationCanvasInnerProps & {
+    fallback?: unknown;
+    canvasKitOpts?: unknown;
+};
+export declare const AnnotationCanvas: (props: AnnotationCanvasProps) => import("react/jsx-runtime").JSX.Element;

package/dist/canvas/AnnotationCanvas.native.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { AnnotationCanvasInner } from './AnnotationCanvasInner.native.js';
+export const AnnotationCanvas = (props) => {
+    const { fallback: _f, canvasKitOpts: _o, ...rest } = props;
+    return _jsx(AnnotationCanvasInner, { ...rest });
+};

package/dist/canvas/AnnotationCanvasInner.d.ts

@@ -0,0 +1,39 @@
+import { type CSSProperties, type MutableRefObject } from 'react';
+import type { DecimalTolerance, FractionalTolerance, Measurement, Units } from '../types/firestore.js';
+import type { AnnotationCanvasState, AnnotationDocumentPatch, Selection } from '../types/annotation.js';
+import type { MeasurementRef } from './measurementPicker.js';
+import type { Tool } from './Tool.js';
+import { type AnnotationCanvasHandle } from './useAnnotationCanvasState.js';
+import { type ViewportState } from './viewport.js';
+import type { RenderMeasurementStamp } from './measurementStampOverlay.js';
+export type { AnnotationCanvasHandle };
+export interface AnnotationCanvasInnerProps {
+    canvas: AnnotationCanvasState;
+    onCommit(patch: AnnotationDocumentPatch): void;
+    tools: Tool[];
+    activeToolId: string;
+    selection: Selection | null;
+    onSelectionChange(selection: Selection | null): void;
+    measurements?: Measurement[];
+    fallbackUnit?: Units;
+    fractionalTolerance?: FractionalTolerance;
+    decimalTolerance?: DecimalTolerance;
+    resolveImageUrl?: (storagePath: string) => Promise<string>;
+    pickMeasurement?: () => Promise<MeasurementRef | null>;
+    renderMeasurementStamp?: RenderMeasurementStamp;
+    stampFontSource?: unknown;
+    stampValueFontSize?: number;
+    stampLabelFontSize?: number;
+    gestures?: GestureConfig;
+    width: number;
+    height: number;
+    initialViewport?: ViewportState;
+    style?: CSSProperties;
+    imperativeRef?: MutableRefObject<AnnotationCanvasHandle | null>;
+}
+export type PanTrigger = 'middleMouse' | 'rightMouse' | 'space';
+export interface GestureConfig {
+    wheel?: 'zoom' | 'pan' | 'auto';
+    panTriggers?: PanTrigger[];
+}
+export declare const AnnotationCanvasInner: (props: AnnotationCanvasInnerProps) => import("react/jsx-runtime").JSX.Element;