@reekon-tools/boldr-utils 1.23.0 → 1.24.0

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

@@ -0,0 +1,25 @@
+import { type AnnotationCanvasState, type AnnotationPdfDocument, type Vec2 } from '../../types/annotation.js';
+import type { PdfCanvasData, PdfCanvasPage, PdfCanvasPageState, PdfCanvasRev, PdfPageRotation } from '../../types/pdfCanvas.js';
+export interface PdfPageDisplaySize {
+    width: number;
+    height: number;
+}
+export declare const normalizePdfRotation: (deg: number) => PdfPageRotation;
+export declare const effectivePageRotation: (intrinsicDeg: number, user: PdfPageRotation) => PdfPageRotation;
+export declare const pdfPageDisplaySize: (page: Pick<PdfCanvasPage, "width" | "height" | "rotation">) => PdfPageDisplaySize;
+export declare const pdfCanvasPageDocId: (pageIndex: number) => string;
+export declare const emptyPdfCanvasPageState: (pageIndex: number) => PdfCanvasPageState;
+export declare const pdfCanvasPageDocument: (data: PdfCanvasData, pageIndex: number) => AnnotationPdfDocument;
+type PdfCanvasKnobs = Pick<PdfCanvasData, 'tileScaleFactor' | 'tileScaleFactorMobile' | 'headerTileScaleFactor' | 'headerTileScaleFactorMobile' | 'tileDocSize'>;
+export declare const pdfCanvasKnobsOf: (source: Partial<PdfCanvasKnobs>) => PdfCanvasKnobs;
+export declare const pdfCanvasKnobsEqual: (a: Partial<PdfCanvasKnobs>, b: Partial<PdfCanvasKnobs>) => boolean;
+export declare const pageStateToCanvasState: (data: PdfCanvasData, pageState: PdfCanvasPageState | null, pageIndex: number) => AnnotationCanvasState;
+export declare const canvasStateToPageState: (canvas: AnnotationCanvasState, pageIndex: number, stamp: {
+    updatedAt: number;
+    rev?: PdfCanvasRev;
+}) => PdfCanvasPageState;
+export type PdfRotationDelta = 90 | -90 | 180;
+export declare const rotatePointInPage: (p: Vec2, size: PdfPageDisplaySize, delta: PdfRotationDelta) => Vec2;
+export declare const rotatePageState: <T extends Pick<PdfCanvasPageState, "strokes" | "shapes" | "placedMeasurements" | "planes">>(state: T, currentSize: PdfPageDisplaySize, delta: PdfRotationDelta) => T;
+export declare const rotatePdfCanvasPage: (page: PdfCanvasPage, delta: PdfRotationDelta) => PdfCanvasPage;
+export {};

package/dist/annotation/canvas/pdfCanvasPages.js

@@ -0,0 +1,255 @@
+// Pure helpers for PDF canvas files (see types/pdfCanvas.ts): page geometry
+// under user rotation, the mapping between a persisted page doc and the
+// AnnotationCanvasState the engine mounts, and the coordinate transform that
+// turns a page's annotations with it when the page is rotated.
+import { createDefaultLayer, createEmptyCanvasState, } from '../../types/annotation.js';
+import { textShapeBounds } from './textGeometry.js';
+// Snap any degree value onto the four legal rotations, modulo 360.
+export const normalizePdfRotation = (deg) => {
+    const snapped = (((Math.round(deg / 90) * 90) % 360) + 360) % 360;
+    return snapped;
+};
+// The rotation a viewer must apply to the ORIGINAL page (its own /Rotate plus
+// the user's) — what the export writes into /Rotate.
+export const effectivePageRotation = (intrinsicDeg, user) => normalizePdfRotation(intrinsicDeg + user);
+// A page's displayed extents: its stored size with width/height swapped at
+// 90/270. This IS the page's canvas doc space.
+export const pdfPageDisplaySize = (page) => page.rotation === 90 || page.rotation === 270
+    ? { width: page.height, height: page.width }
+    : { width: page.width, height: page.height };
+// Firestore doc id of a page under `files/{fileId}/pages`. Plain index: the
+// set of existing pages comes from `annotatedPages`, never from listing.
+export const pdfCanvasPageDocId = (pageIndex) => String(pageIndex);
+export const emptyPdfCanvasPageState = (pageIndex) => ({
+    schemaVersion: 1,
+    pageIndex,
+    layers: [createDefaultLayer()],
+    strokes: [],
+    shapes: [],
+    placedMeasurements: [],
+    updatedAt: 0,
+});
+const requirePage = (data, pageIndex) => {
+    const page = data.document.pages[pageIndex];
+    if (!page) {
+        throw new RangeError(`PDF canvas has ${data.document.pages.length} pages; asked for ${pageIndex}`);
+    }
+    return page;
+};
+// The one-page substrate descriptor a page canvas carries. pdfPageDocRects of
+// it is exactly {0, 0, w, h}, so every consumer of `viewport.pdfDocument` (fit,
+// zoom floor, tile-scale reference, export matrix) sees the displayed page.
+export const pdfCanvasPageDocument = (data, pageIndex) => {
+    const size = pdfPageDisplaySize(requirePage(data, pageIndex));
+    return {
+        id: `pdf-page-${pageIndex}`,
+        storagePath: data.document.storagePath,
+        ...(data.document.fileName ? { fileName: data.document.fileName } : {}),
+        pageCount: 1,
+        pages: [size],
+        layout: 'continuousVertical',
+        gap: 0,
+    };
+};
+const KNOB_KEYS = [
+    'tileScaleFactor',
+    'tileScaleFactorMobile',
+    'headerTileScaleFactor',
+    'headerTileScaleFactorMobile',
+    'tileDocSize',
+];
+// The file-level tile-scale knobs present on a canvas (undefined keys omitted).
+export const pdfCanvasKnobsOf = (source) => {
+    const out = {};
+    for (const key of KNOB_KEYS) {
+        const value = source[key];
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+};
+export const pdfCanvasKnobsEqual = (a, b) => KNOB_KEYS.every((key) => a[key] === b[key]);
+// The AnnotationCanvasState the editor mounts for one page. A null page state
+// (never annotated) yields an empty canvas over the page.
+export const pageStateToCanvasState = (data, pageState, pageIndex) => {
+    const doc = pdfCanvasPageDocument(data, pageIndex);
+    const size = doc.pages[0];
+    const base = createEmptyCanvasState({
+        width: size.width,
+        height: size.height,
+        pdfDocument: doc,
+    });
+    return {
+        ...base,
+        ...pdfCanvasKnobsOf(data),
+        layers: pageState && pageState.layers.length > 0 ? pageState.layers : base.layers,
+        strokes: pageState?.strokes ?? [],
+        shapes: pageState?.shapes ?? [],
+        placedMeasurements: pageState?.placedMeasurements ?? [],
+        ...(pageState?.planes !== undefined ? { planes: pageState.planes } : {}),
+    };
+};
+// Inverse of pageStateToCanvasState: the elements to persist for one page.
+// Viewport and pdfDocument are derived and never stored on the page doc.
+export const canvasStateToPageState = (canvas, pageIndex, stamp) => ({
+    schemaVersion: 1,
+    pageIndex,
+    layers: canvas.layers,
+    strokes: canvas.strokes,
+    shapes: canvas.shapes,
+    placedMeasurements: canvas.placedMeasurements,
+    ...(canvas.planes !== undefined ? { planes: canvas.planes } : {}),
+    updatedAt: stamp.updatedAt,
+    ...(stamp.rev ? { rev: stamp.rev } : {}),
+});
+export const rotatePointInPage = (p, size, delta) => {
+    switch (normalizePdfRotation(delta)) {
+        case 90:
+            return { x: size.height - p.y, y: p.x };
+        case 270:
+            return { x: p.y, y: size.width - p.x };
+        case 180:
+            return { x: size.width - p.x, y: size.height - p.y };
+        default:
+            return p;
+    }
+};
+const rotateFlatPoints = (points, size, delta) => {
+    const out = new Array(points.length);
+    for (let i = 0; i + 1 < points.length; i += 2) {
+        const p = rotatePointInPage({ x: points[i], y: points[i + 1] }, size, delta);
+        out[i] = p.x;
+        out[i + 1] = p.y;
+    }
+    return out;
+};
+const rotateStroke = (stroke, size, delta) => ({
+    ...stroke,
+    points: rotateFlatPoints(stroke.points, size, delta),
+});
+const rotateShape = (shape, size, delta) => {
+    if (shape.kind === 'text') {
+        const bounds = textShapeBounds(shape);
+        const origin = shape.geometry.points[0];
+        if (bounds && origin) {
+            const width = bounds.maxX - bounds.minX;
+            const height = bounds.maxY - bounds.minY;
+            const centre = rotatePointInPage({ x: bounds.minX + width / 2, y: bounds.minY + height / 2 }, size, delta);
+            return {
+                ...shape,
+                geometry: {
+                    ...shape.geometry,
+                    points: [
+                        { x: centre.x - width / 2, y: centre.y - height / 2 },
+                        ...shape.geometry.points.slice(1),
+                    ],
+                },
+            };
+        }
+    }
+    return {
+        ...shape,
+        geometry: {
+            ...shape.geometry,
+            points: shape.geometry.points.map((p) => rotatePointInPage(p, size, delta)),
+        },
+    };
+};
+// Where each rectangle edge lands after the turn — used for the perspective
+// plane's dimensioned-edge provenance and for the dimension tiles' slots.
+const rotateEdge = (edge, delta) => {
+    if (edge === 'ref')
+        return edge;
+    const order = ['top', 'right', 'bottom', 'left'];
+    const steps = normalizePdfRotation(delta) / 90;
+    return order[(order.indexOf(edge) + steps) % 4];
+};
+const rotatePlaced = (placed, size, delta) => {
+    const r = (p) => rotatePointInPage(p, size, delta);
+    return {
+        ...placed,
+        anchor: r(placed.anchor),
+        ...(placed.line
+            ? { line: { a: r(placed.line.a), b: r(placed.line.b) } }
+            : {}),
+        ...(placed.rect
+            ? { rect: { a: r(placed.rect.a), b: r(placed.rect.b) } }
+            : {}),
+        ...(placed.leader
+            ? { leader: { from: r(placed.leader.from), to: r(placed.leader.to) } }
+            : {}),
+        ...(placed.planeEdge
+            ? { planeEdge: rotateEdge(placed.planeEdge, delta) }
+            : {}),
+    };
+};
+const rotatePlane = (plane, size, delta) => {
+    const r = (p) => rotatePointInPage(p, size, delta);
+    if (plane.mode === 'scale') {
+        return {
+            ...plane,
+            refLine: { a: r(plane.refLine.a), b: r(plane.refLine.b) },
+        };
+    }
+    // Corners stay in TL, TR, BR, BL order: after a clockwise quarter turn the
+    // old bottom-left corner is the new top-left, so the array rotates by one
+    // slot per quarter turn.
+    const steps = normalizePdfRotation(delta) / 90;
+    const turned = plane.corners.map(r);
+    const corners = [0, 1, 2, 3].map((i) => turned[(i - steps + 4) % 4]);
+    const quarter = steps % 2 === 1;
+    const widthEdge = plane.heightEdge
+        ? rotateEdge(plane.heightEdge, delta)
+        : undefined;
+    const heightEdge = plane.widthEdge
+        ? rotateEdge(plane.widthEdge, delta)
+        : undefined;
+    return {
+        ...plane,
+        corners,
+        // A quarter turn makes the horizontal dimension vertical and vice versa.
+        ...(quarter
+            ? {
+                ...(plane.heightUm !== undefined
+                    ? { widthUm: plane.heightUm }
+                    : { widthUm: undefined }),
+                ...(plane.widthUm !== undefined
+                    ? { heightUm: plane.widthUm }
+                    : { heightUm: undefined }),
+                ...(widthEdge === 'top' || widthEdge === 'bottom'
+                    ? { widthEdge }
+                    : { widthEdge: undefined }),
+                ...(heightEdge === 'left' || heightEdge === 'right'
+                    ? { heightEdge }
+                    : { heightEdge: undefined }),
+            }
+            : {
+                ...(plane.widthEdge
+                    ? {
+                        widthEdge: rotateEdge(plane.widthEdge, delta),
+                    }
+                    : {}),
+                ...(plane.heightEdge
+                    ? {
+                        heightEdge: rotateEdge(plane.heightEdge, delta),
+                    }
+                    : {}),
+            }),
+    };
+};
+// Rewrite every coordinate of a page's state from its current displayed size
+// into the size it will have after turning by `delta`.
+export const rotatePageState = (state, currentSize, delta) => ({
+    ...state,
+    strokes: state.strokes.map((s) => rotateStroke(s, currentSize, delta)),
+    shapes: state.shapes.map((s) => rotateShape(s, currentSize, delta)),
+    placedMeasurements: state.placedMeasurements.map((p) => rotatePlaced(p, currentSize, delta)),
+    ...(state.planes !== undefined
+        ? { planes: state.planes.map((p) => rotatePlane(p, currentSize, delta)) }
+        : {}),
+});
+// The page record after turning by `delta`.
+export const rotatePdfCanvasPage = (page, delta) => ({
+    ...page,
+    rotation: normalizePdfRotation(page.rotation + delta),
+});

package/dist/annotation/data/AnnotationDataProvider.d.ts

@@ -1,4 +1,5 @@
 import type { FileUpload, FileUploadType, Measurement } from '../../types/firestore.js';
+import type { PdfCanvasPageState } from '../../types/pdfCanvas.js';
 export interface JobScope {
     orgId: string;
     projectId: string;
@@ -56,6 +57,8 @@ export interface UploadedImageRef {
 }
 export type AnnotationFile = Extract<FileUpload, {
     type: FileUploadType.Canvas;
+} | {
+    type: FileUploadType.PdfCanvas;
 }>;
 export interface AnnotationFileSummary {
     id: string;
@@ -78,4 +81,7 @@ export interface AnnotationDataProvider {
     uploadImage(scope: AnnotationScope, fileId: string, role: string, blob: ImageBlob): Promise<UploadedImageRef>;
     getImageUrl(scope: AnnotationScope, fileId: string, storagePath: string): Promise<string>;
     deleteImage(scope: AnnotationScope, fileId: string, storagePath: string): Promise<void>;
+    getPage(scope: AnnotationScope, fileId: string, pageIndex: number): Promise<PdfCanvasPageState | null>;
+    subscribePage(scope: AnnotationScope, fileId: string, pageIndex: number, onNext: (page: PdfCanvasPageState | null) => void, onError?: (err: Error) => void): Unsubscribe;
+    writePage(scope: AnnotationScope, fileId: string, pageIndex: number, state: PdfCanvasPageState): Promise<void>;
 }

package/dist/annotation/data/InMemoryAnnotationProvider.d.ts

@@ -1,4 +1,5 @@
 import { type Measurement } from '../../types/firestore.js';
+import type { PdfCanvasPageState } from '../../types/pdfCanvas.js';
 import { type AnnotationDataProvider, type AnnotationFile, type AnnotationFilePatch, type AnnotationFileSummary, type AnnotationScope, type ImageBlob, type JobGroupScope, type JobScope, type Unsubscribe, type UploadedImageRef } from './AnnotationDataProvider.js';
 export declare class InMemoryAnnotationProvider implements AnnotationDataProvider {
     private docs;
@@ -8,6 +9,8 @@ export declare class InMemoryAnnotationProvider implements AnnotationDataProvide
     private listListeners;
     private groupMeasurementListeners;
     private jobMeasurementListeners;
+    private pages;
+    private pageListeners;
     private nextId;
     setMeasurements(scope: JobGroupScope, measurements: Measurement[]): void;
     create(scope: AnnotationScope, seed: Partial<AnnotationFile>): Promise<string>;
@@ -21,6 +24,9 @@ export declare class InMemoryAnnotationProvider implements AnnotationDataProvide
     uploadImage(scope: AnnotationScope, fileId: string, role: string, blob: ImageBlob): Promise<UploadedImageRef>;
     getImageUrl(_scope: AnnotationScope, fileId: string, storagePath: string): Promise<string>;
     deleteImage(_scope: AnnotationScope, fileId: string, storagePath: string): Promise<void>;
+    getPage(scope: AnnotationScope, fileId: string, pageIndex: number): Promise<PdfCanvasPageState | null>;
+    subscribePage(scope: AnnotationScope, fileId: string, pageIndex: number, onNext: (page: PdfCanvasPageState | null) => void): Unsubscribe;
+    writePage(scope: AnnotationScope, fileId: string, pageIndex: number, state: PdfCanvasPageState): Promise<void>;
     private getBucket;
     private notifyDoc;
     private notifyList;

package/dist/annotation/data/InMemoryAnnotationProvider.js

@@ -1,9 +1,11 @@
 import { FileUploadType } from '../../types/firestore.js';
+import { pdfCanvasPageDocId } from '../canvas/pdfCanvasPages.js';
 import { annotationScopeKey, isFieldOp, } from './AnnotationDataProvider.js';
 const scopeKey = annotationScopeKey;
 // Prefix of annotationScopeKey for job scopes, so collectJobMeasurements can
 // match group keys by startsWith.
 const jobKey = (s) => `job/${s.orgId}/${s.projectId}/${s.jobId}`;
+const pageKey = (s, fileId, pageIndex) => `${scopeKey(s)}/${fileId}/pages/${pdfCanvasPageDocId(pageIndex)}`;
 const summarize = (file) => ({
     id: file.id,
     name: file.name,
@@ -75,6 +77,8 @@ export class InMemoryAnnotationProvider {
         this.listListeners = new Map();
         this.groupMeasurementListeners = new Map();
         this.jobMeasurementListeners = new Map();
+        this.pages = new Map();
+        this.pageListeners = new Map();
         this.nextId = 1;
     }
     // Seed helpers for tests
@@ -182,6 +186,27 @@ export class InMemoryAnnotationProvider {
     async deleteImage(_scope, fileId, storagePath) {
         this.images.get(fileId)?.delete(storagePath);
     }
+    async getPage(scope, fileId, pageIndex) {
+        return this.pages.get(pageKey(scope, fileId, pageIndex)) ?? null;
+    }
+    subscribePage(scope, fileId, pageIndex, onNext) {
+        const key = pageKey(scope, fileId, pageIndex);
+        const set = this.pageListeners.get(key) ?? new Set();
+        set.add(onNext);
+        this.pageListeners.set(key, set);
+        queueMicrotask(() => onNext(this.pages.get(key) ?? null));
+        return () => {
+            set.delete(onNext);
+        };
+    }
+    async writePage(scope, fileId, pageIndex, state) {
+        const key = pageKey(scope, fileId, pageIndex);
+        // Same JSON round-trip as the real SDKs' effective behaviour: undefined
+        // keys vanish, object identity is not preserved across the write.
+        const stored = JSON.parse(JSON.stringify(state));
+        this.pages.set(key, stored);
+        this.pageListeners.get(key)?.forEach((cb) => cb(stored));
+    }
     getBucket(scope) {
         const key = scopeKey(scope);
         let bucket = this.docs.get(key);

package/dist/annotation/data/hooks/usePdfCanvasDoc.d.ts

@@ -0,0 +1,29 @@
+import { type AnnotationCanvasState, type AnnotationDocumentPatch } from '../../../types/annotation.js';
+import type { PdfCanvasData, PdfCanvasPage } from '../../../types/pdfCanvas.js';
+import { type PdfRotationDelta } from '../../canvas/pdfCanvasPages.js';
+import { type AnnotationFile, type AnnotationScope, type ImageBlob } from '../AnnotationDataProvider.js';
+import type { SaveStatus } from './useAnnotationCanvasDoc.js';
+export interface UsePdfCanvasDocOptions {
+    scope: AnnotationScope | null;
+    fileId: string | null;
+    pageIndex: number;
+    onSaveError?: (error: unknown) => void;
+    captureThumbnail?: () => Promise<ImageBlob | null>;
+    debugLogging?: boolean;
+}
+export interface UsePdfCanvasDocResult {
+    file: AnnotationFile | null;
+    pdfCanvas: PdfCanvasData | null;
+    pageCount: number;
+    page: PdfCanvasPage | null;
+    canvas: AnnotationCanvasState;
+    onCommit: (patch: AnnotationDocumentPatch) => void;
+    loading: boolean;
+    error: Error | null;
+    saveStatus: SaveStatus;
+    hasUnsavedChanges: boolean;
+    save: () => Promise<void>;
+    rotatePage: (delta: PdfRotationDelta) => Promise<void>;
+    refreshThumbnail: () => Promise<void>;
+}
+export declare const usePdfCanvasDoc: (options: UsePdfCanvasDocOptions) => UsePdfCanvasDocResult;