@reekon-tools/boldr-utils 1.6.8 → 1.6.9

package/dist/data/AnnotationDataProvider.d.ts

@@ -39,7 +39,7 @@ export interface UploadedImageRef {
     bytes?: number;
 }
 export type AnnotationFile = Extract<FileUpload, {
-    type: FileUploadType.Annotation;
+    type: FileUploadType.Canvas;
 }>;
 export interface AnnotationFileSummary {
     id: string;

package/dist/data/InMemoryAnnotationProvider.js

@@ -1,4 +1,4 @@
-import { FileUploadType, } from '../types/firestore.js';
+import { FileUploadType } from '../types/firestore.js';
 import { isFieldOp, } from './AnnotationDataProvider.js';
 const scopeKey = (s) => `${s.orgId}/${s.projectId}/${s.jobId}/${s.groupId}`;
 const jobKey = (s) => `${s.orgId}/${s.projectId}/${s.jobId}`;
@@ -69,7 +69,7 @@ export class InMemoryAnnotationProvider {
             thumbnailUrl: seed.thumbnailUrl ?? null,
             createdAt: seed.createdAt ?? new Date(),
             createdBy: seed.createdBy,
-            type: FileUploadType.Annotation,
+            type: FileUploadType.Canvas,
             fileData: seed.fileData ?? { fileType: 'sketch' },
         };
         this.getBucket(scope).set(id, file);

package/dist/data/canvasPersistence.d.ts

@@ -0,0 +1,3 @@
+import { type AnnotationCanvasState, type AnnotationViewport } from '../types/annotation.js';
+import type { AnnotationFile } from './AnnotationDataProvider.js';
+export declare const hydrateCanvasState: (file: AnnotationFile | null, fallbackViewport?: Partial<AnnotationViewport>) => AnnotationCanvasState;

package/dist/data/canvasPersistence.js

@@ -0,0 +1,26 @@
+import { createEmptyCanvasState, } from '../types/annotation.js';
+// Bring a persisted canvas forward to the current schema. Keyed on
+// `schemaVersion` so each client migrates identically and the provider can
+// stay a dumb transport. Identity for v1 today; add a `case 1: return
+// upgradeV1toV2(raw)` arm when the schema bumps.
+const migrateCanvasState = (raw) => {
+    switch (raw.schemaVersion) {
+        case 1:
+            return raw;
+        default:
+            // Forward-compat: a doc written by a newer client. Trust it as-is
+            // rather than risk a lossy downgrade-write.
+            return raw;
+    }
+};
+// Turn a loaded annotation file into a working canvas state ready to feed the
+// canvas. Missing/legacy docs (no `fileData.canvas`) start from an empty
+// canvas sized by `fallbackViewport`. This is the single entry point for going
+// from `useAnnotationDoc` data to an `AnnotationCanvasState` — consumers should
+// not call `createEmptyCanvasState` directly.
+export const hydrateCanvasState = (file, fallbackViewport) => {
+    const persisted = file?.fileData.canvas;
+    if (!persisted)
+        return createEmptyCanvasState(fallbackViewport);
+    return migrateCanvasState(persisted);
+};

package/dist/data/hooks/useAnnotationCanvasDoc.d.ts

@@ -0,0 +1,26 @@
+import { type AnnotationCanvasState, type AnnotationDocumentPatch, type AnnotationViewport } from '../../types/annotation.js';
+import type { JobGroupScope } from '../AnnotationDataProvider.js';
+export type SaveStatus = 'idle' | 'dirty' | 'saving' | 'saved' | 'error';
+export interface UseAnnotationCanvasDocOptions {
+    scope: JobGroupScope | null;
+    fileId: string | null;
+    fallbackViewport?: Partial<AnnotationViewport>;
+    debounceMs?: number;
+    createSeed?: {
+        name?: string;
+        fileType?: 'sketch' | 'document';
+        isLabel?: boolean;
+    };
+    onFileCreated?: (fileId: string) => void;
+    onSaveError?: (error: unknown) => void;
+    debugLogging?: boolean;
+}
+export interface UseAnnotationCanvasDocResult {
+    canvas: AnnotationCanvasState;
+    onCommit: (patch: AnnotationDocumentPatch) => void;
+    loading: boolean;
+    error: Error | null;
+    saveStatus: SaveStatus;
+    save: () => Promise<void>;
+}
+export declare const useAnnotationCanvasDoc: (options: UseAnnotationCanvasDocOptions) => UseAnnotationCanvasDocResult;

package/dist/data/hooks/useAnnotationCanvasDoc.js

@@ -0,0 +1,220 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { applyPatch, createEmptyCanvasState, } from '../../types/annotation.js';
+import { FileUploadType } from '../../types/firestore.js';
+import { useAnnotationDoc } from './useAnnotationDoc.js';
+import { useAnnotationMutations } from './useAnnotationMutations.js';
+import { hydrateCanvasState } from '../canvasPersistence.js';
+// Stable placeholder so useAnnotationMutations (which requires a non-null
+// scope) can be called unconditionally. Never used to write — flushes are
+// guarded on a real scope.
+const EMPTY_SCOPE = {
+    orgId: '',
+    projectId: '',
+    jobId: '',
+    groupId: '',
+};
+// Build the persisted fileData, omitting `isLabel` when undefined so the write
+// contains no undefined values (Firestore rejects them on RN).
+const buildFileData = (fileType, isLabel, canvas) => ({
+    fileType,
+    ...(isLabel !== undefined ? { isLabel } : {}),
+    canvas,
+});
+// Orchestrates load + auto-save for the annotation canvas. Hydrates the working
+// state from the persisted doc, applies commits optimistically, and persists
+// (debounced) through the data provider — creating the file on first save when
+// no `fileId` was supplied. Composes the existing low-level hooks so it stays
+// decoupled from any specific Firebase SDK.
+export const useAnnotationCanvasDoc = (options) => {
+    const { scope, fileId, fallbackViewport, debounceMs = 800, createSeed, onFileCreated, onSaveError, debugLogging = false, } = options;
+    const { data, loading, error } = useAnnotationDoc(scope, fileId);
+    const { create, update } = useAnnotationMutations(scope ?? EMPTY_SCOPE);
+    const [working, setWorking] = useState(null);
+    const [saveStatus, setSaveStatus] = useState('idle');
+    // Refs let the debounced/unmount flush read the latest values without
+    // re-creating timers on every keystroke.
+    const workingRef = useRef(null);
+    const dataRef = useRef(data);
+    const statusRef = useRef('idle');
+    const timerRef = useRef(null);
+    const createRef = useRef(create);
+    const updateRef = useRef(update);
+    const fileIdRef = useRef(fileId);
+    // Id of a file this hook created on first save (when opened with no fileId).
+    // Used for subsequent updates and to recognize the caller echoing it back
+    // into `fileId`.
+    const createdIdRef = useRef(null);
+    const createSeedRef = useRef(createSeed);
+    const onFileCreatedRef = useRef(onFileCreated);
+    const onSaveErrorRef = useRef(onSaveError);
+    const debugRef = useRef(debugLogging);
+    // JSON of the canvas we last wrote, to recognize (and ignore) the snapshot
+    // echo of our own write when reconciling incoming remote changes.
+    const lastSavedJsonRef = useRef(null);
+    // Guards against two creates racing if flushes overlap.
+    const creatingRef = useRef(false);
+    workingRef.current = working;
+    dataRef.current = data;
+    statusRef.current = saveStatus;
+    createRef.current = create;
+    updateRef.current = update;
+    createSeedRef.current = createSeed;
+    onFileCreatedRef.current = onFileCreated;
+    onSaveErrorRef.current = onSaveError;
+    debugRef.current = debugLogging;
+    const setStatus = useCallback((next) => {
+        statusRef.current = next;
+        setSaveStatus(next);
+    }, []);
+    // Reset working state when the target document changes so the next snapshot
+    // hydrates the new file rather than leaking the previous one. Skip the reset
+    // when the new fileId is one we just created (the caller echoing it back) —
+    // our working state is already correct and must not be wiped.
+    useEffect(() => {
+        if (fileIdRef.current === fileId)
+            return;
+        fileIdRef.current = fileId;
+        if (fileId !== null && fileId === createdIdRef.current)
+            return;
+        if (timerRef.current) {
+            clearTimeout(timerRef.current);
+            timerRef.current = null;
+        }
+        createdIdRef.current = null;
+        lastSavedJsonRef.current = null;
+        setWorking(null);
+        setStatus('idle');
+    }, [fileId, setStatus]);
+    // Hydrate / reconcile from the persisted doc.
+    useEffect(() => {
+        // First load — always hydrate.
+        if (workingRef.current === null) {
+            setWorking(hydrateCanvasState(data, fallbackViewport));
+            lastSavedJsonRef.current = data?.fileData.canvas
+                ? JSON.stringify(data.fileData.canvas)
+                : null;
+            return;
+        }
+        // A write of ours is queued or in flight — ignore the snapshot; it is
+        // either the echo of our write or about to be superseded by it.
+        if (statusRef.current === 'saving' || timerRef.current !== null)
+            return;
+        // Clean locally: accept a genuine remote change, but ignore the echo of
+        // our own last write (same content).
+        const incoming = data?.fileData.canvas;
+        if (!incoming)
+            return;
+        const incomingJson = JSON.stringify(incoming);
+        if (incomingJson === lastSavedJsonRef.current)
+            return;
+        lastSavedJsonRef.current = incomingJson;
+        setWorking(hydrateCanvasState(data, fallbackViewport));
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [data]);
+    const flush = useCallback(async () => {
+        if (timerRef.current) {
+            clearTimeout(timerRef.current);
+            timerRef.current = null;
+        }
+        const canvas = workingRef.current;
+        // Nothing to persist, or no real target scope yet.
+        if (!canvas || !scope)
+            return;
+        if (creatingRef.current)
+            return;
+        const json = JSON.stringify(canvas);
+        const id = fileIdRef.current ?? createdIdRef.current;
+        const mode = id ? 'update' : 'create';
+        const debug = debugRef.current;
+        if (debug) {
+            console.log('[useAnnotationCanvasDoc] save attempt', {
+                mode,
+                fileId: id,
+                scope,
+                bytes: json.length,
+                strokes: canvas.strokes.length,
+                shapes: canvas.shapes.length,
+                measurements: canvas.placedMeasurements.length,
+            });
+        }
+        // Round-trip through JSON to drop `undefined` keys (e.g. an empty canvas's
+        // viewport.backgroundImage/backgroundFit). Firestore — RN in particular —
+        // rejects undefined field values unless ignoreUndefinedProperties is set.
+        const canvasPayload = JSON.parse(json);
+        setStatus('saving');
+        try {
+            if (!id) {
+                // First save with no file — create the doc seeded with the canvas.
+                creatingRef.current = true;
+                const seed = createSeedRef.current;
+                const newId = await createRef.current({
+                    type: FileUploadType.Canvas,
+                    ...(seed?.name !== undefined ? { name: seed.name } : {}),
+                    fileData: buildFileData(seed?.fileType ?? 'sketch', seed?.isLabel, canvasPayload),
+                });
+                creatingRef.current = false;
+                createdIdRef.current = newId;
+                if (debug) {
+                    console.log('[useAnnotationCanvasDoc] created file', newId);
+                }
+                onFileCreatedRef.current?.(newId);
+            }
+            else {
+                const doc = dataRef.current;
+                await updateRef.current(id, {
+                    fileData: buildFileData(doc?.fileData.fileType ??
+                        createSeedRef.current?.fileType ??
+                        'sketch', doc?.fileData.isLabel ?? createSeedRef.current?.isLabel, canvasPayload),
+                });
+                if (debug) {
+                    console.log('[useAnnotationCanvasDoc] updated file', id);
+                }
+            }
+            lastSavedJsonRef.current = json;
+            // If new edits landed mid-flight, stay dirty and let the next debounce
+            // (or unmount) flush them.
+            const latest = workingRef.current;
+            if (latest && JSON.stringify(latest) !== json) {
+                setStatus('dirty');
+            }
+            else {
+                setStatus('saved');
+            }
+        }
+        catch (e) {
+            creatingRef.current = false;
+            // Always log save failures with context — these are otherwise invisible
+            // (the canvas keeps working from local state).
+            console.error(`[useAnnotationCanvasDoc] ${mode} failed`, { fileId: id, scope, bytes: json.length }, e);
+            onSaveErrorRef.current?.(e);
+            setStatus('error');
+        }
+    }, [scope, setStatus]);
+    const onCommit = useCallback((patch) => {
+        setWorking((prev) => (prev ? applyPatch(prev, patch) : prev));
+        setStatus('dirty');
+        if (timerRef.current)
+            clearTimeout(timerRef.current);
+        timerRef.current = setTimeout(() => {
+            timerRef.current = null;
+            void flush();
+        }, debounceMs);
+    }, [debounceMs, flush, setStatus]);
+    // Flush any pending edits on unmount.
+    useEffect(() => () => {
+        if (timerRef.current) {
+            clearTimeout(timerRef.current);
+            timerRef.current = null;
+            void flush();
+        }
+    }, [flush]);
+    const canvas = useMemo(() => working ?? createEmptyCanvasState(fallbackViewport), [working, fallbackViewport]);
+    return {
+        canvas,
+        onCommit,
+        loading,
+        error,
+        saveStatus,
+        save: flush,
+    };
+};

package/dist/exports.d.ts

@@ -13,13 +13,15 @@ export { AnnotationDataProviderContext, useAnnotationData, type AnnotationDataPr
 export { useAnnotationDoc, type UseAnnotationDocResult, } from './data/hooks/useAnnotationDoc.js';
 export { useAnnotationList, type UseAnnotationListResult, } from './data/hooks/useAnnotationList.js';
 export { useAnnotationMutations, type AnnotationMutations, } from './data/hooks/useAnnotationMutations.js';
+export { useAnnotationCanvasDoc, type SaveStatus, type UseAnnotationCanvasDocOptions, type UseAnnotationCanvasDocResult, } from './data/hooks/useAnnotationCanvasDoc.js';
+export { hydrateCanvasState } from './data/canvasPersistence.js';
 export { InMemoryAnnotationProvider } from './data/InMemoryAnnotationProvider.js';
-export type { AnnotationCanvasHandle, } from './canvas/useAnnotationCanvasState.js';
+export type { AnnotationCanvasHandle } from './canvas/useAnnotationCanvasState.js';
 export type { GestureConfig, PanTrigger, AnnotationCanvasInnerProps, } from './canvas/AnnotationCanvasInner.js';
 export type { CanvasPointerEvent, Tool, ToolContext, ToolState, } from './canvas/Tool.js';
 export type { MeasurementRef, PickMeasurement, } from './canvas/measurementPicker.js';
 export { createViewportApi, fitToScreen, panBy, zoomAt, DEFAULT_VIEWPORT, type ViewportApi, type ViewportState, } from './canvas/viewport.js';
-export { createPenTool, type PenToolOptions, } from './canvas/tools/penTool.js';
+export { createPenTool, type PenToolOptions } from './canvas/tools/penTool.js';
 export { createSelectTool } from './canvas/tools/selectTool.js';
 export { createMeasurementStampTool, type MeasurementStampToolOptions, } from './canvas/tools/measurementStampTool.js';
-export { createPanTool, type PanToolOptions, } from './canvas/tools/panTool.js';
+export { createPanTool, type PanToolOptions } from './canvas/tools/panTool.js';

package/dist/exports.js

@@ -18,9 +18,11 @@ export { AnnotationDataProviderContext, useAnnotationData, } from './data/Annota
 export { useAnnotationDoc, } from './data/hooks/useAnnotationDoc.js';
 export { useAnnotationList, } from './data/hooks/useAnnotationList.js';
 export { useAnnotationMutations, } from './data/hooks/useAnnotationMutations.js';
+export { useAnnotationCanvasDoc, } from './data/hooks/useAnnotationCanvasDoc.js';
+export { hydrateCanvasState } from './data/canvasPersistence.js';
 export { InMemoryAnnotationProvider } from './data/InMemoryAnnotationProvider.js';
 export { createViewportApi, fitToScreen, panBy, zoomAt, DEFAULT_VIEWPORT, } from './canvas/viewport.js';
-export { createPenTool, } from './canvas/tools/penTool.js';
+export { createPenTool } from './canvas/tools/penTool.js';
 export { createSelectTool } from './canvas/tools/selectTool.js';
 export { createMeasurementStampTool, } from './canvas/tools/measurementStampTool.js';
-export { createPanTool, } from './canvas/tools/panTool.js';
+export { createPanTool } from './canvas/tools/panTool.js';

package/dist/types/firestore.d.ts

@@ -100,6 +100,7 @@ export interface SelectedTemplate extends FirestoreDoc {
 }
 export declare enum FileUploadType {
     Annotation = "annotation",
+    Canvas = "canvas",
     Template = "template",
     Background = "background",
     LayoutGroup = "layoutGroup",
@@ -148,6 +149,7 @@ interface FileUploadBase {
     id: string;
     name: string;
     thumbnailUrl: string | null;
+    folderPath?: string;
     createdBy?: {
         userId: string;
         firstName?: string;
@@ -158,6 +160,9 @@ interface FileUploadBase {
 export type FileUpload = FileUploadBase & ({
     type: FileUploadType.Annotation;
     fileData: AnnotationFileData;
+} | {
+    type: FileUploadType.Canvas;
+    fileData: AnnotationFileData;
 } | {
     type: FileUploadType.Calculator;
     fileData: CalculatorFileData;

package/dist/types/firestore.js

@@ -18,6 +18,9 @@ export var TemplateType;
 export var FileUploadType;
 (function (FileUploadType) {
     FileUploadType["Annotation"] = "annotation";
+    // v2 Skia photo-annotation canvas. Distinct from the legacy PSPDFKit
+    // `Annotation` docs so file-open routing sends it to the canvas editor.
+    FileUploadType["Canvas"] = "canvas";
     FileUploadType["Template"] = "template";
     FileUploadType["Background"] = "background";
     FileUploadType["LayoutGroup"] = "layoutGroup";

package/package.json

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