@reekon-tools/boldr-utils 1.27.0 → 1.28.0

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

@@ -15,6 +15,7 @@ export interface AnnotationCanvasInnerProps {
     activeToolId: string;
     selection: Selection | null;
     onSelectionChange(selection: Selection | null): void;
+    onViewportChange?(viewport: ViewportState): void;
     measurements?: Measurement[];
     fallbackUnit?: Units;
     fractionalTolerance?: FractionalTolerance;

package/dist/annotation/canvas/AnnotationCanvasSkia.js

@@ -5,7 +5,6 @@ import { arrowheadTriangle, dashIntervals, toSkiaStrokeCap, } from './strokeGeom
 import { SELECTION_PAD, textResizeGeometry, textShapeBounds, } from './textGeometry.js';
 import { visualShapeBounds } from './shapeGeometry.js';
 import { backgroundCropBars, backgroundLayerDocRect, backgroundLayersOf, isBackgroundLayerLocked, } from './backgroundLayers.js';
-import { YellowColors } from '../../theme/colors.js';
 import { BackgroundLayerElement } from './elements/BackgroundImageElement.js';
 import { PlaneElement, PLANE_CHROME_COLOR, PLANE_GRID_COLOR, PLANE_GRID_OPACITY, PLANE_GRID_WIDTH, PLANE_OUTLINE_WIDTH, } from './elements/PlaneElement.js';
 import { ShapeElement } from './elements/ShapeElement.js';
@@ -26,10 +25,6 @@ const SELECTION_STROKE = 1.5;
 // the target the dragged endpoint is currently locked onto. Orange so it reads
 // against both the blue selection chrome and the yellow lock accent.
 const SNAP_INDICATOR_COLOR = '#FF7A00';
-// Outline of a selected LOCKED background layer: the lock accent (the same
-// yellow the selected group-header border uses), distinct from the blue
-// manipulable-selection chrome — locked means "selected, but pinned".
-const BACKGROUND_LOCKED_COLOR = YellowColors.mainYellow;
 // Link badge on a LINKED background layer (layer.fileId — an expanded file
 // tile, see fileTileSwap.ts): a chain glyph in a white disc at the layer's
 // top-right, saying "this is a group file's image, not a plain background".
@@ -310,16 +305,24 @@ export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTran
                 // its opposite corner) plus four edge crop bars (raster layers only —
                 // dragging a bar windows the image non-destructively). Chrome tracks
                 // the live drag/resize transform the same way the layer itself does
-                // above. A LOCKED layer (backgroundLayerIsLocked) keeps the outline —
-                // it is selected, and the host's chrome offers the lock toggle — but
-                // recolored to the lock yellow and with no handles: it cannot scale
-                // or crop, so a grabbable gizmo would lie. During a native crop-bar
+                // above. A LOCKED layer (backgroundLayerIsLocked) keeps the same blue
+                // outline — it is selected, and the host's chrome offers the lock
+                // toggle — but no handles or bars: it cannot move, scale or crop, so
+                // a grabbable gizmo would lie. During a native crop-bar
                 // drag the chrome is just the LIVE outline — handles and bars would
                 // sit on stale committed edges.
                 const layer = backgroundLayersOf(effectiveCanvas.viewport).find((l) => l.id === selectedId);
                 if (layer) {
+                    // The outline is screen-constant (the handle ring width — 2px /
+                    // zoom, a number on web and a derived value on native), not the
+                    // doc-unit SELECTION_STROKE: a background is often huge in doc
+                    // space and viewed zoomed out, where a doc-unit stroke thins to
+                    // nothing — and for a LOCKED layer this border is the only
+                    // selected indicator. Doc units only when the host passes no
+                    // handle sizing (no drag-select tool).
+                    const outlineWidth = handleRingWidth ?? SELECTION_STROKE;
                     if (layer.id === bgCropId && liveBgCrop) {
-                        return (_jsx(Rect, { x: liveBgCrop.x, y: liveBgCrop.y, width: liveBgCrop.width, height: liveBgCrop.height, color: SELECTION_COLOR, style: "stroke", strokeWidth: SELECTION_STROKE }));
+                        return (_jsx(Rect, { x: liveBgCrop.x, y: liveBgCrop.y, width: liveBgCrop.width, height: liveBgCrop.height, color: SELECTION_COLOR, style: "stroke", strokeWidth: outlineWidth }));
                     }
                     const locked = isBackgroundLayerLocked(effectiveCanvas.viewport, layer.id);
                     const r = backgroundLayerDocRect(layer);
@@ -331,7 +334,7 @@ export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTran
                         { x: r.x, y: r.y + r.height },
                         { x: r.x + r.width, y: r.y + r.height },
                     ];
-                    return (_jsxs(DraggableElement, { isDragging: isDragging || isResizing, transform: liveTransform, children: [_jsx(Rect, { x: r.x, y: r.y, width: r.width, height: r.height, color: locked ? BACKGROUND_LOCKED_COLOR : SELECTION_COLOR, style: "stroke", strokeWidth: SELECTION_STROKE }), !locked &&
+                    return (_jsxs(DraggableElement, { isDragging: isDragging || isResizing, transform: liveTransform, children: [_jsx(Rect, { x: r.x, y: r.y, width: r.width, height: r.height, color: SELECTION_COLOR, style: "stroke", strokeWidth: outlineWidth }), !locked &&
                                 layer.format !== 'svg' &&
                                 backgroundCropBars(layer).map((bar) => {
                                     const inset = Math.min(bar.width, bar.height) * 0.18;

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

@@ -87,7 +87,7 @@ export interface DragSelectionConfig {
     } | null;
     buildShapeCornerPatch?(doc: AnnotationCanvasState, id: AnnotationElementId, corner: RectCorner, delta: Vec2): AnnotationDocumentPatch | null;
     isSelectedTileGrab?(doc: AnnotationCanvasState, id: AnnotationElementId, world: Vec2, zoom: number, viewportTileScale?: number, tileScaleFactor?: number, headerTileScaleFactor?: number, fileTileScaleFactor?: number): boolean;
-    hitTestBackground?(doc: AnnotationCanvasState, world: Vec2): {
+    hitTestBackground?(doc: AnnotationCanvasState, world: Vec2, zoom: number): {
         id: AnnotationElementId;
         locked: boolean;
     } | null;

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

@@ -488,7 +488,7 @@ const shapeCornerPatch = (doc, id, corner, delta) => {
 // DragSelectionConfig AND the web pointer handlers — one source of truth).
 // Backgrounds can cover the whole document, so they never join the general
 // hit-test: a tap selects one only when every stroke/shape/measurement
-// misses, and a drag translates one only when it is ALREADY selected — the
+// misses AND it lands on the layer's perimeter (findBackgroundHit), and a drag translates one only when it is ALREADY selected — the
 // layout tool's two-step model, which keeps a full-bleed background from
 // hijacking pan/marquee gestures. A LOCKED layer (backgroundLayerIsLocked —
 // by default the first image, which IS the canvas) is selectable like any
@@ -502,16 +502,38 @@ const pointInBackgroundLayer = (layer, p) => {
     const r = backgroundLayerDocRect(layer);
     return (p.x >= r.x && p.x <= r.x + r.width && p.y >= r.y && p.y <= r.y + r.height);
 };
-// Topmost background layer under a world point (reverse array order — later
-// layers draw on top). Point-in-doc-rect, no padding: a background is a big
-// target already.
-const findBackgroundHit = (doc, world) => {
+// Screen-px half-width of the edge band that selects an UNSELECTED background
+// (converted to doc space via zoom). A zoomed-in background often fills the
+// whole viewport, so a tap anywhere on it selecting the image made selection
+// accidental — and a selected background's chrome gets in the way of placing
+// more objects. Selecting now takes a deliberate tap on the image's perimeter:
+// within this distance of the visible (cropped) rect's outline, inside or out.
+// Once selected, the whole rect is live again (findSelectedBackgroundHit), so
+// body drags and the tap-toggle deselect are unchanged.
+const BACKGROUND_EDGE_GRAB_PX = 24;
+// Topmost background layer whose perimeter band contains a world point
+// (reverse array order — later layers draw on top). A point in a layer's
+// interior (past the band) is occluded by that layer: it never falls through
+// to the edge of a layer drawn beneath it, whose outline is hidden there. A
+// layer smaller than two band-widths on screen is all band, so it stays
+// selectable anywhere on it.
+const findBackgroundHit = (doc, world, zoom) => {
+    const band = BACKGROUND_EDGE_GRAB_PX / zoom;
     const layers = backgroundLayersOf(doc.viewport);
     for (let i = layers.length - 1; i >= 0; i--) {
         const layer = layers[i];
-        if (pointInBackgroundLayer(layer, world)) {
-            return { id: layer.id, locked: backgroundLayerIsLocked(layer, i) };
-        }
+        const r = backgroundLayerDocRect(layer);
+        const left = world.x - r.x;
+        const right = r.x + r.width - world.x;
+        const top = world.y - r.y;
+        const bottom = r.y + r.height - world.y;
+        // Outside the band-expanded rect: this layer is not under the point.
+        if (Math.min(left, right, top, bottom) < -band)
+            continue;
+        // Inside the band-inset rect: the layer's interior covers the point.
+        if (Math.min(left, right, top, bottom) > band)
+            return null;
+        return { id: layer.id, locked: backgroundLayerIsLocked(layer, i) };
     }
     return null;
 };
@@ -907,11 +929,14 @@ export const createSelectTool = (options = {}) => ({
                     delta: { x: 0, y: 0 },
                 };
             }
-            // An unselected background selects. A free one consumes the gesture
+            // An unselected background selects — but only from its perimeter
+            // band (findBackgroundHit); its interior behaves like empty canvas,
+            // so a full-bleed image never gets selected by accident. A free one
+            // consumes the gesture
             // (no pan, no drag): translating it takes a second gesture once
             // selected, the layout tool's two-step model. A locked one is the
             // canvas: it selects AND the drag pans, as on empty canvas.
-            const bg = findBackgroundHit(ctx.document, world);
+            const bg = findBackgroundHit(ctx.document, world, zoom);
             if (bg) {
                 ctx.setSelection({ ids: [bg.id] });
                 if (bg.locked && options.panOnEmptyDrag) {

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

@@ -14,6 +14,8 @@ export interface AnnotationCanvasHandle {
     redo(): void;
     canUndo(): boolean;
     canRedo(): boolean;
+    zoomBy(factor: number, focalScreen?: Vec2): void;
+    getZoom(): number;
     zoomToFit(opts?: {
         animated?: boolean;
         durationMs?: number;
@@ -72,6 +74,7 @@ export interface UseAnnotationCanvasStateProps {
     activeToolId: string;
     selection: Selection | null;
     onSelectionChange(selection: Selection | null): void;
+    onViewportChange?(viewport: ViewportState): void;
     measurements?: Measurement[];
     pickMeasurement?: () => Promise<MeasurementRef | null>;
     requestTextInput?: RequestTextInput;

package/dist/annotation/canvas/useAnnotationCanvasState.js

@@ -83,7 +83,7 @@ const defaultLeaderLenDoc = (docWidth) => Math.min(800, Math.max(240, docWidth *
 // inners share this hook; each wraps it with platform-specific event
 // capture and JSX (div + DOM events vs. GestureDetector + RN Views).
 export const useAnnotationCanvasState = (props) => {
-    const { canvas, onCommit, tools, activeToolId, selection, onSelectionChange, measurements, pickMeasurement, requestTextInput, snapToGeometry, width, height, initialViewport, tileScalePlatform, animateViewport, imperativeRef, } = props;
+    const { canvas, onCommit, tools, activeToolId, selection, onSelectionChange, onViewportChange, measurements, pickMeasurement, requestTextInput, snapToGeometry, width, height, initialViewport, tileScalePlatform, animateViewport, imperativeRef, } = props;
     const [viewport, setViewport] = useState(initialViewport ?? DEFAULT_VIEWPORT);
     const [toolState, setToolState] = useState(undefined);
     // Synchronous mirror for the DISPATCHERS. The native tap gesture
@@ -127,7 +127,17 @@ export const useAnnotationCanvasState = (props) => {
     // (Adding a background mid-session also fits it, so you see the whole image
     // you just dropped in.) Canvases that never gain a background keep the 1:1
     // default — for a screen-sized document that already frames it correctly.
-    const didInitialFitRef = useRef(false);
+    //
+    // Pre-latched in two cases, both "someone already framed the view":
+    // - The host passed `initialViewport` — it owns framing (the paged PDF
+    //   editor fits each page from the file record at mount, long before the
+    //   page's annotation doc hydrates).
+    // - The user (or the host, through the handle) has already moved the
+    //   viewport this mount. The doc can hydrate mid-gesture — a page turn's
+    //   snapshot lands while the user is already wheel-zooming — and a late fit
+    //   here would stomp that viewport, which reads as zoom pivoting around a
+    //   broken focal point. Every pan/zoom/fit path below latches the ref.
+    const didInitialFitRef = useRef(!!initialViewport);
     useEffect(() => {
         if (didInitialFitRef.current)
             return;
@@ -257,9 +267,11 @@ export const useAnnotationCanvasState = (props) => {
                 : Promise.resolve(null);
         },
         applyPan(deltaScreen) {
+            didInitialFitRef.current = true;
             setViewport((v) => panBy(v, deltaScreen));
         },
         applyZoom(focalScreen, nextZoom) {
+            didInitialFitRef.current = true;
             setViewport((v) => zoomAt(v, focalScreen, nextZoom, zoomLimitsRef.current));
         },
     }), [
@@ -369,18 +381,23 @@ export const useAnnotationCanvasState = (props) => {
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [activeTool, ctx]);
     const pan = useCallback((deltaScreen) => {
+        didInitialFitRef.current = true;
         setViewport((v) => panBy(v, deltaScreen));
     }, []);
     const zoom = useCallback((focalScreen, nextZoom) => {
+        didInitialFitRef.current = true;
         setViewport((v) => zoomAt(v, focalScreen, nextZoom, zoomLimitsRef.current));
     }, []);
     // `v.zoom * factor` inside the updater, so a burst of events that React
     // batches into one commit composes instead of each recomputing the same
-    // target from the same stale base. See `zoomBy` on the API type.
+    // target from the same stale base. See `zoomBy` on the API type. Clamped
+    // like the other zoom paths — an unclamped wheel burst could sail past the
+    // document floor/ceiling.
     const zoomBy = useCallback((focalScreen, factor) => {
         if (!Number.isFinite(factor) || factor <= 0)
             return;
-        setViewport((v) => zoomAt(v, focalScreen, v.zoom * factor));
+        didInitialFitRef.current = true;
+        setViewport((v) => zoomAt(v, focalScreen, v.zoom * factor, zoomLimitsRef.current));
     }, []);
     // Imperative API mirror — set via prop so it survives WithSkiaWeb's lazy
     // boundary on web.
@@ -445,6 +462,12 @@ export const useAnnotationCanvasState = (props) => {
             return c.viewport.screenToWorld({ x: cx, y: cy });
         };
         imperativeRef.current = {
+            zoomBy(factor, focalScreen) {
+                zoomBy(focalScreen ?? { x: width / 2, y: height / 2 }, factor);
+            },
+            getZoom() {
+                return ctxRef.current.viewport.state.zoom;
+            },
             undo() {
                 const entry = undoStackRef.current.pop();
                 if (!entry)
@@ -466,6 +489,7 @@ export const useAnnotationCanvasState = (props) => {
                 return redoStackRef.current.length > 0;
             },
             zoomToFit(opts) {
+                didInitialFitRef.current = true;
                 // The document is read through ctxRef, not the effect closure: this
                 // effect's deps deliberately exclude `canvas`, so the closed-over
                 // binding can predate tiles that landed or moved since — and the fit
@@ -479,6 +503,7 @@ export const useAnnotationCanvasState = (props) => {
                 }
             },
             resetView() {
+                didInitialFitRef.current = true;
                 // "Reset view" frames the whole document/image again — the same fit the
                 // canvas opens with — rather than snapping to a 1:1 top-left view, which
                 // for a high-res background is the very crop this is meant to escape.
@@ -487,6 +512,7 @@ export const useAnnotationCanvasState = (props) => {
             fitContentToRect(rect, opts) {
                 if (!(rect.width > 0) || !(rect.height > 0))
                     return;
+                didInitialFitRef.current = true;
                 const target = computeContentFitRect(ctxRef.current.document, rect);
                 if (opts?.animated && animateViewport) {
                     animateViewport(target, opts.durationMs ?? 450);
@@ -498,6 +524,7 @@ export const useAnnotationCanvasState = (props) => {
             fitDocRect(rect, opts) {
                 if (!(width > 0) || !(height > 0))
                     return;
+                didInitialFitRef.current = true;
                 const limits = zoomLimitsRef.current;
                 const target = fitDocRectViewport(rect, width, height, {
                     paddingPx: opts?.paddingPx,
@@ -844,7 +871,16 @@ export const useAnnotationCanvasState = (props) => {
         canvas.viewport.height,
         width,
         height,
+        zoomBy,
     ]);
+    // Viewport subscription for hosts (zoom readouts and the like). A ref keeps
+    // the effect off the callback identity — hosts often pass a fresh closure
+    // every render.
+    const onViewportChangeRef = useRef(onViewportChange);
+    onViewportChangeRef.current = onViewportChange;
+    useEffect(() => {
+        onViewportChangeRef.current?.(viewport);
+    }, [viewport]);
     const worldTransform = useMemo(() => [
         { scale: viewport.zoom },
         { translateX: -viewport.pan.x },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reekon-tools/boldr-utils",
-  "version": "1.27.0",
+  "version": "1.28.0",
   "description": "Shared utilities for formulas and measurement conversion used in Reekon apps",
   "author": "REEKON Tools",
   "license": "MIT",