@reekon-tools/boldr-utils 1.23.0 → 1.25.0

package/dist/annotation/data/hooks/usePdfCanvasDoc.js

@@ -0,0 +1,353 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { applyPatch, createEmptyCanvasState, } from '../../../types/annotation.js';
+import { canvasStateToPageState, pageStateToCanvasState, pdfCanvasKnobsEqual, pdfCanvasKnobsOf, pdfPageDisplaySize, rotatePageState, rotatePdfCanvasPage, } from '../../canvas/pdfCanvasPages.js';
+import { useAnnotationData } from '../AnnotationDataContext.js';
+import { annotationScopeKey, } from '../AnnotationDataProvider.js';
+import { createCoalescedRunner } from '../coalescedRunner.js';
+import { useAnnotationDoc } from './useAnnotationDoc.js';
+const makeClientId = () => `${Date.now().toString(36)}-${Math.floor(Math.random() * 0x100000000).toString(36)}`;
+const hasContent = (canvas) => canvas.strokes.length > 0 ||
+    canvas.shapes.length > 0 ||
+    canvas.placedMeasurements.length > 0 ||
+    (canvas.planes?.length ?? 0) > 0;
+// Drop undefined keys (Firestore — RN in particular — rejects them) and detach
+// the persisted payload from the working state's object identities.
+const jsonClone = (value) => JSON.parse(JSON.stringify(value));
+// Load + explicit-save orchestration for ONE page of a PdfCanvas file. The
+// canvas engine is page-agnostic: this hook hands it the page's state as an
+// ordinary AnnotationCanvasState (pageStateToCanvasState) and persists it back
+// as a page doc. Mirrors useAnnotationCanvasDoc's echo suppression (a `rev`
+// stamped with this session's clientId) and single-flight flushing.
+export const usePdfCanvasDoc = (options) => {
+    const { scope, fileId, pageIndex, onSaveError, captureThumbnail, debugLogging = false, } = options;
+    const provider = useAnnotationData();
+    const { data: file, loading: fileLoading, error: fileError, } = useAnnotationDoc(scope, fileId);
+    const pdfCanvas = file?.fileData.pdfCanvas ?? null;
+    // The current page's doc, TAGGED with the page it answers for. On a page
+    // turn the previous page's doc is still in state until the new subscription
+    // reports, and hydrating the new page from it is exactly how annotations
+    // land on the wrong page. `state` null = the page has no doc yet.
+    const [pageSnapshot, setPageSnapshot] = useState(null);
+    const [pageLoading, setPageLoading] = useState(true);
+    const [pageError, setPageError] = useState(null);
+    const [working, setWorking] = useState(null);
+    const [saveStatus, setSaveStatus] = useState('idle');
+    const workingRef = useRef(null);
+    const pdfCanvasRef = useRef(null);
+    const statusRef = useRef('idle');
+    const pageIndexRef = useRef(pageIndex);
+    const scopeRef = useRef(scope);
+    const fileIdRef = useRef(fileId);
+    const onSaveErrorRef = useRef(onSaveError);
+    const captureThumbnailRef = useRef(captureThumbnail);
+    const debugRef = useRef(debugLogging);
+    const clientIdRef = useRef(null);
+    if (clientIdRef.current === null)
+        clientIdRef.current = makeClientId();
+    const writeSeqRef = useRef(0);
+    const editSeqRef = useRef(0);
+    const thumbnailSavingRef = useRef(false);
+    const thumbnailRequestedRef = useRef(false);
+    const thumbnailPromiseRef = useRef(undefined);
+    // A page whose edits must be persisted although it is no longer the current
+    // page (the user turned the page with unsaved edits).
+    const outgoingRef = useRef([]);
+    workingRef.current = working;
+    pdfCanvasRef.current = pdfCanvas;
+    statusRef.current = saveStatus;
+    scopeRef.current = scope;
+    fileIdRef.current = fileId;
+    onSaveErrorRef.current = onSaveError;
+    captureThumbnailRef.current = captureThumbnail;
+    debugRef.current = debugLogging;
+    const setStatus = useCallback((next) => {
+        statusRef.current = next;
+        setSaveStatus(next);
+    }, []);
+    // Subscribe to the current page's doc.
+    useEffect(() => {
+        if (!scope || !fileId) {
+            setPageSnapshot(null);
+            setPageLoading(false);
+            return;
+        }
+        // Drop the previous page's snapshot synchronously so nothing can read it
+        // as this page's while the subscription is still connecting.
+        setPageSnapshot(null);
+        setPageLoading(true);
+        setPageError(null);
+        const unsubscribe = provider.subscribePage(scope, fileId, pageIndex, (doc) => {
+            setPageSnapshot({ pageIndex, state: doc });
+            setPageLoading(false);
+        }, (err) => {
+            setPageError(err);
+            setPageLoading(false);
+        });
+        return unsubscribe;
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [provider, annotationScopeKey(scope), fileId, pageIndex]);
+    // Persist one page: the page doc, then whatever file-level fields it moved
+    // (first-annotation marker, tile knobs). Returns normally on failure after
+    // reporting it — callers read the status, not a rejection.
+    const persist = useCallback(async (target) => {
+        const currentScope = scopeRef.current;
+        const currentFileId = fileIdRef.current;
+        if (!currentScope || !currentFileId)
+            return false;
+        const rev = {
+            clientId: clientIdRef.current,
+            seq: ++writeSeqRef.current,
+        };
+        const state = jsonClone(canvasStateToPageState(target.canvas, target.pageIndex, {
+            updatedAt: Date.now(),
+            rev,
+        }));
+        if (debugRef.current) {
+            console.log('[usePdfCanvasDoc] save attempt', {
+                fileId: currentFileId,
+                pageIndex: target.pageIndex,
+                strokes: state.strokes.length,
+                shapes: state.shapes.length,
+                measurements: state.placedMeasurements.length,
+            });
+        }
+        try {
+            await provider.writePage(currentScope, currentFileId, target.pageIndex, state);
+            const patch = {};
+            if (!target.pdfCanvas.annotatedPages.includes(target.pageIndex)) {
+                patch['fileData.pdfCanvas.annotatedPages'] = {
+                    kind: 'arrayUnion',
+                    values: [target.pageIndex],
+                };
+            }
+            const knobs = pdfCanvasKnobsOf(target.canvas);
+            if (!pdfCanvasKnobsEqual(knobs, pdfCanvasKnobsOf(target.pdfCanvas))) {
+                for (const [key, value] of Object.entries(knobs)) {
+                    patch[`fileData.pdfCanvas.${key}`] = value;
+                }
+            }
+            if (Object.keys(patch).length > 0) {
+                await provider.update(currentScope, currentFileId, patch);
+            }
+            return true;
+        }
+        catch (e) {
+            console.error('[usePdfCanvasDoc] save failed', { fileId: currentFileId, pageIndex: target.pageIndex }, e);
+            onSaveErrorRef.current?.(e);
+            return false;
+        }
+    }, [provider]);
+    const saveThumbnail = useCallback(async (targetFileId) => {
+        const capture = captureThumbnailRef.current;
+        const currentScope = scopeRef.current;
+        if (!capture || !currentScope || thumbnailSavingRef.current)
+            return;
+        thumbnailSavingRef.current = true;
+        try {
+            const blob = await capture();
+            if (blob) {
+                await provider.uploadImage(currentScope, targetFileId, 'thumbnail', blob);
+            }
+        }
+        catch (e) {
+            console.warn('[usePdfCanvasDoc] thumbnail save failed', e);
+        }
+        finally {
+            thumbnailSavingRef.current = false;
+        }
+    }, [provider]);
+    // One flush pass: an outgoing page first (if a page turn left one behind),
+    // then the current page when it is dirty.
+    const runFlush = useCallback(async () => {
+        // Every page left behind with unsaved edits, in the order they were
+        // left: two quick turns must not lose the middle page.
+        while (outgoingRef.current.length > 0) {
+            await persist(outgoingRef.current.shift());
+        }
+        const canvas = workingRef.current;
+        const data = pdfCanvasRef.current;
+        if (!canvas ||
+            !data ||
+            (statusRef.current !== 'dirty' && statusRef.current !== 'error')) {
+            return;
+        }
+        const editSeqAtFlush = editSeqRef.current;
+        const wantThumbnail = thumbnailRequestedRef.current;
+        thumbnailRequestedRef.current = false;
+        const targetPage = pageIndexRef.current;
+        setStatus('saving');
+        const ok = await persist({
+            pageIndex: targetPage,
+            canvas,
+            pdfCanvas: data,
+        });
+        if (!ok) {
+            setStatus('error');
+            return;
+        }
+        const currentFileId = fileIdRef.current;
+        if (wantThumbnail && targetPage === 0 && currentFileId) {
+            thumbnailPromiseRef.current = saveThumbnail(currentFileId);
+        }
+        setStatus(editSeqRef.current !== editSeqAtFlush ? 'dirty' : 'saved');
+    }, [persist, saveThumbnail, setStatus]);
+    const runFlushRef = useRef(runFlush);
+    runFlushRef.current = runFlush;
+    const flushRunner = useMemo(() => createCoalescedRunner(() => runFlushRef.current()), []);
+    const flush = useCallback(() => flushRunner(), [flushRunner]);
+    // Page turn: hand the outgoing page to the flusher if it has unsaved edits,
+    // then drop the working state so the next snapshot hydrates the new page.
+    useEffect(() => {
+        if (pageIndexRef.current === pageIndex)
+            return;
+        const previous = workingRef.current;
+        const data = pdfCanvasRef.current;
+        if (previous &&
+            data &&
+            (statusRef.current === 'dirty' || statusRef.current === 'error')) {
+            outgoingRef.current.push({
+                pageIndex: pageIndexRef.current,
+                canvas: previous,
+                pdfCanvas: data,
+            });
+            void flush();
+        }
+        pageIndexRef.current = pageIndex;
+        workingRef.current = null;
+        setWorking(null);
+        setStatus('idle');
+    }, [pageIndex, flush, setStatus]);
+    // Reset on a different file.
+    useEffect(() => {
+        workingRef.current = null;
+        setWorking(null);
+        setStatus('idle');
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [annotationScopeKey(scope), fileId]);
+    // Hydrate / reconcile from the persisted docs.
+    useEffect(() => {
+        if (!pdfCanvas || pageLoading)
+            return;
+        if (pageIndex >= pdfCanvas.document.pages.length)
+            return;
+        // Only a snapshot for THIS page counts (see pageSnapshot).
+        if (!pageSnapshot || pageSnapshot.pageIndex !== pageIndex)
+            return;
+        const pageDoc = pageSnapshot.state;
+        if (workingRef.current === null) {
+            const next = pageStateToCanvasState(pdfCanvas, pageDoc, pageIndex);
+            workingRef.current = next;
+            setWorking(next);
+            return;
+        }
+        // Local edits pending or a write in flight: never clobber them.
+        if (statusRef.current === 'saving' || statusRef.current === 'dirty')
+            return;
+        // The echo of this session's own write carries our clientId.
+        if (pageDoc?.rev?.clientId === clientIdRef.current)
+            return;
+        const next = pageStateToCanvasState(pdfCanvas, pageDoc, pageIndex);
+        workingRef.current = next;
+        setWorking(next);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [pdfCanvas, pageSnapshot, pageLoading, pageIndex]);
+    const onCommit = useCallback((patch) => {
+        editSeqRef.current += 1;
+        setWorking((prev) => {
+            if (!prev)
+                return prev;
+            const next = applyPatch(prev, patch);
+            workingRef.current = next;
+            return next;
+        });
+        setStatus('dirty');
+    }, [setStatus]);
+    const save = useCallback(async () => {
+        thumbnailRequestedRef.current = true;
+        await flush();
+        await thumbnailPromiseRef.current;
+    }, [flush]);
+    const refreshThumbnail = useCallback(async () => {
+        const currentFileId = fileIdRef.current;
+        if (!currentFileId)
+            return;
+        await saveThumbnail(currentFileId);
+    }, [saveThumbnail]);
+    const rotatePage = useCallback(async (delta) => {
+        const currentScope = scopeRef.current;
+        const currentFileId = fileIdRef.current;
+        // Pending edits first, so the rewrite below starts from persisted truth.
+        await flush();
+        const data = pdfCanvasRef.current;
+        const canvas = workingRef.current;
+        const index = pageIndexRef.current;
+        if (!currentScope || !currentFileId || !data || !canvas)
+            return;
+        const page = data.document.pages[index];
+        if (!page)
+            return;
+        const size = pdfPageDisplaySize(page);
+        const turnedPage = rotatePdfCanvasPage(page, delta);
+        const pages = data.document.pages.map((p, i) => i === index ? turnedPage : p);
+        // Knobs the flush just wrote may not have echoed back yet; carry them.
+        const nextData = {
+            ...data,
+            ...pdfCanvasKnobsOf(canvas),
+            document: { ...data.document, pages },
+        };
+        setStatus('saving');
+        try {
+            const patch = {
+                'fileData.pdfCanvas.document.pages': pages,
+            };
+            let turnedState = null;
+            if (hasContent(canvas)) {
+                const rev = {
+                    clientId: clientIdRef.current,
+                    seq: ++writeSeqRef.current,
+                };
+                turnedState = jsonClone(rotatePageState(canvasStateToPageState(canvas, index, {
+                    updatedAt: Date.now(),
+                    rev,
+                }), size, delta));
+                await provider.writePage(currentScope, currentFileId, index, turnedState);
+                if (!data.annotatedPages.includes(index)) {
+                    patch['fileData.pdfCanvas.annotatedPages'] = {
+                        kind: 'arrayUnion',
+                        values: [index],
+                    };
+                }
+            }
+            await provider.update(currentScope, currentFileId, patch);
+            const next = pageStateToCanvasState(nextData, turnedState, index);
+            workingRef.current = next;
+            setWorking(next);
+            setStatus('saved');
+        }
+        catch (e) {
+            console.error('[usePdfCanvasDoc] rotate failed', { fileId: currentFileId, pageIndex: index, delta }, e);
+            onSaveErrorRef.current?.(e);
+            setStatus('error');
+        }
+    }, [flush, provider, setStatus]);
+    const page = pdfCanvas?.document.pages[pageIndex] ?? null;
+    const canvas = useMemo(() => working ??
+        (page
+            ? createEmptyCanvasState(pdfPageDisplaySize(page))
+            : createEmptyCanvasState()), [working, page]);
+    return {
+        file,
+        pdfCanvas,
+        pageCount: pdfCanvas?.document.pageCount ?? 0,
+        page,
+        canvas,
+        onCommit,
+        loading: fileLoading || pageLoading || working === null,
+        error: fileError ?? pageError,
+        saveStatus,
+        hasUnsavedChanges: saveStatus === 'dirty' || saveStatus === 'error',
+        save,
+        rotatePage,
+        refreshThumbnail,
+    };
+};

package/dist/export/pdf/index.d.ts

@@ -1,7 +1,7 @@
-export { renderCanvasToPdf } from './renderCanvasToPdf.js';
+export { renderCanvasToPdf, renderPdfCanvasToPdf, } from './renderCanvasToPdf.js';
 export { stripPdfEncryption, type StripPdfEncryptionOptions, type StripPdfEncryptionResult, } from './decrypt.js';
 export { docToPageMatrix, pageRectsOf, normalizeRotation, rotatedBoxSize, applyMatrix, type AffineMatrix, type PageRotation, type PdfBox, } from './pageMapping.js';
 export { resolveTileContent, measurementTileFillFor, FORMULA_COLUMN_TILE_FILL, PLANE_COMPUTED_TILE_FILL, type TileFileInfo, type TileResolutionContext, } from './tileContent.js';
 export { tileFootprint, type TileFootprint } from './tiles.js';
 export { annotationCount } from './annots.js';
-export { PdfExportError, type EmbeddedImage, type PdfExportCalibration, type RenderCanvasToPdfInput, type RenderCanvasToPdfResult, type ResolvedTileContent, type MeasurementTileContent, type LiteralTileContent, type EmptyTileContent, type HeaderTileContent, type ObjectTileContent, type PlaneDimensionTileContent, type InstructionsTileContent, type SkippedItem, } from './types.js';
+export { PdfExportError, type EmbeddedImage, type PdfExportCalibration, type RenderCanvasToPdfInput, type RenderPdfCanvasToPdfInput, type RenderCanvasToPdfResult, type ResolvedTileContent, type MeasurementTileContent, type LiteralTileContent, type EmptyTileContent, type HeaderTileContent, type ObjectTileContent, type PlaneDimensionTileContent, type InstructionsTileContent, type SkippedItem, } from './types.js';

package/dist/export/pdf/index.js

@@ -1,4 +1,4 @@
-export { renderCanvasToPdf } from './renderCanvasToPdf.js';
+export { renderCanvasToPdf, renderPdfCanvasToPdf, } from './renderCanvasToPdf.js';
 export { stripPdfEncryption, } from './decrypt.js';
 export { docToPageMatrix, pageRectsOf, normalizeRotation, rotatedBoxSize, applyMatrix, } from './pageMapping.js';
 export { resolveTileContent, measurementTileFillFor, FORMULA_COLUMN_TILE_FILL, PLANE_COMPUTED_TILE_FILL, } from './tileContent.js';

package/dist/export/pdf/renderCanvasToPdf.d.ts

@@ -1,2 +1,10 @@
-import { type RenderCanvasToPdfInput, type RenderCanvasToPdfResult } from './types.js';
+import { type RenderCanvasToPdfInput, type RenderCanvasToPdfResult, type RenderPdfCanvasToPdfInput } from './types.js';
 export declare const renderCanvasToPdf: (input: RenderCanvasToPdfInput) => Promise<RenderCanvasToPdfResult>;
+/**
+ * Export a PdfCanvas file. Each page's state is drawn in that page's own doc
+ * space (the DISPLAYED page: rotated extents, origin top-left). A user
+ * rotation is written into the page's /Rotate — so the recipient sees the
+ * page as the user did — and the page matrix undoes the combined rotation.
+ * Pages without a state are still rotated.
+ */
+export declare const renderPdfCanvasToPdf: (input: RenderPdfCanvasToPdfInput) => Promise<RenderCanvasToPdfResult>;