@reekon-tools/boldr-utils 1.25.0 → 1.26.0

package/dist/data/hooks/useAnnotationCanvasDoc.js

@@ -0,0 +1,314 @@
+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, captureThumbnail, debugLogging = false, } = options;
+    const { data, loading, error } = useAnnotationDoc(scope, fileId);
+    const { create, update, uploadImage, deleteImage } = 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 captureThumbnailRef = useRef(captureThumbnail);
+    const uploadImageRef = useRef(uploadImage);
+    // Guards against overlapping thumbnail captures (each save fires one).
+    const thumbnailSavingRef = useRef(false);
+    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;
+    captureThumbnailRef.current = captureThumbnail;
+    uploadImageRef.current = uploadImage;
+    debugRef.current = debugLogging;
+    const setStatus = useCallback((next) => {
+        statusRef.current = next;
+        setSaveStatus(next);
+    }, []);
+    // Fire-and-forget thumbnail capture + upload, run after each successful save.
+    // Stable identity (reads refs) so it doesn't churn `flush`'s deps. Skips when
+    // no capturer is supplied or a capture is already in flight.
+    const saveThumbnail = useCallback(async (fileId) => {
+        const capture = captureThumbnailRef.current;
+        if (!capture || thumbnailSavingRef.current)
+            return;
+        thumbnailSavingRef.current = true;
+        try {
+            const blob = await capture();
+            if (blob)
+                await uploadImageRef.current(fileId, 'thumbnail', blob);
+        }
+        catch (e) {
+            console.warn('[useAnnotationCanvasDoc] thumbnail save failed', e);
+        }
+        finally {
+            thumbnailSavingRef.current = false;
+        }
+    }, []);
+    // 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;
+            // Refresh the file's thumbnail to match what was just saved (fire and
+            // forget — never blocks or fails the save).
+            const savedId = fileIdRef.current ?? createdIdRef.current;
+            if (savedId)
+                void saveThumbnail(savedId);
+            // 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, saveThumbnail]);
+    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]);
+    const ensureFileId = useCallback(async () => {
+        const existing = fileIdRef.current ?? createdIdRef.current;
+        if (existing)
+            return existing;
+        // No file yet — seed an empty canvas if nothing has hydrated, then flush
+        // so the existing create branch mints the doc.
+        if (!workingRef.current) {
+            const seeded = createEmptyCanvasState(fallbackViewport);
+            workingRef.current = seeded;
+            setWorking(seeded);
+        }
+        await flush();
+        const id = fileIdRef.current ?? createdIdRef.current;
+        if (!id) {
+            throw new Error('Unable to create annotation file before background upload');
+        }
+        return id;
+    }, [flush, fallbackViewport]);
+    const setBackgroundImage = useCallback(async (blob, dims, fit = 'contain') => {
+        const id = await ensureFileId();
+        const ref = await uploadImage(id, 'background', blob);
+        onCommit({
+            ops: [
+                {
+                    op: 'setViewport',
+                    patch: {
+                        backgroundImage: {
+                            storagePath: ref.storagePath,
+                            downloadUrl: ref.downloadUrl,
+                            widthPx: dims.width,
+                            heightPx: dims.height,
+                        },
+                        backgroundFit: fit,
+                    },
+                },
+            ],
+        });
+    }, [ensureFileId, uploadImage, onCommit]);
+    const clearBackgroundImage = useCallback(async () => {
+        const bg = workingRef.current?.viewport.backgroundImage;
+        const id = fileIdRef.current ?? createdIdRef.current;
+        if (bg && id) {
+            try {
+                await deleteImage(id, bg.storagePath);
+            }
+            catch (e) {
+                // Non-fatal: still clear the viewport reference even if the storage
+                // object is already gone.
+                console.warn('[useAnnotationCanvasDoc] failed to delete background image', e);
+            }
+        }
+        onCommit({
+            ops: [
+                {
+                    op: 'setViewport',
+                    patch: { backgroundImage: undefined, backgroundFit: undefined },
+                },
+            ],
+        });
+    }, [deleteImage, onCommit]);
+    // 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,
+        ensureFileId,
+        setBackgroundImage,
+        clearBackgroundImage,
+    };
+};

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

@@ -0,0 +1,7 @@
+import type { AnnotationFile, JobGroupScope } from '../AnnotationDataProvider.js';
+export interface UseAnnotationDocResult {
+    data: AnnotationFile | null;
+    loading: boolean;
+    error: Error | null;
+}
+export declare const useAnnotationDoc: (scope: JobGroupScope | null, fileId: string | null) => UseAnnotationDocResult;

package/dist/data/hooks/useAnnotationDoc.js

@@ -0,0 +1,33 @@
+import { useEffect, useState } from 'react';
+import { useAnnotationData } from '../AnnotationDataContext.js';
+export const useAnnotationDoc = (scope, fileId) => {
+    const provider = useAnnotationData();
+    const [data, setData] = useState(null);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        if (!scope || !fileId) {
+            setData(null);
+            setLoading(false);
+            return;
+        }
+        setLoading(true);
+        setError(null);
+        const unsubscribe = provider.subscribe(scope, fileId, (doc) => {
+            setData(doc);
+            setLoading(false);
+        }, (err) => {
+            setError(err);
+            setLoading(false);
+        });
+        return unsubscribe;
+    }, [
+        provider,
+        scope?.orgId,
+        scope?.projectId,
+        scope?.jobId,
+        scope?.groupId,
+        fileId,
+    ]);
+    return { data, loading, error };
+};

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

@@ -0,0 +1,7 @@
+import type { AnnotationFileSummary, JobGroupScope } from '../AnnotationDataProvider.js';
+export interface UseAnnotationListResult {
+    files: AnnotationFileSummary[];
+    loading: boolean;
+    error: Error | null;
+}
+export declare const useAnnotationList: (scope: JobGroupScope | null) => UseAnnotationListResult;

package/dist/data/hooks/useAnnotationList.js

@@ -0,0 +1,26 @@
+import { useEffect, useState } from 'react';
+import { useAnnotationData } from '../AnnotationDataContext.js';
+export const useAnnotationList = (scope) => {
+    const provider = useAnnotationData();
+    const [files, setFiles] = useState([]);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        if (!scope) {
+            setFiles([]);
+            setLoading(false);
+            return;
+        }
+        setLoading(true);
+        setError(null);
+        const unsubscribe = provider.list(scope, (next) => {
+            setFiles(next);
+            setLoading(false);
+        }, (err) => {
+            setError(err);
+            setLoading(false);
+        });
+        return unsubscribe;
+    }, [provider, scope?.orgId, scope?.projectId, scope?.jobId, scope?.groupId]);
+    return { files, loading, error };
+};

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

@@ -0,0 +1,9 @@
+import type { AnnotationFile, ImageBlob, JobGroupScope, Patch, UploadedImageRef } from '../AnnotationDataProvider.js';
+export interface AnnotationMutations {
+    create(seed: Partial<AnnotationFile>): Promise<string>;
+    update(fileId: string, patch: Patch<AnnotationFile>): Promise<void>;
+    remove(fileId: string): Promise<void>;
+    uploadImage(fileId: string, role: 'background' | 'thumbnail', blob: ImageBlob): Promise<UploadedImageRef>;
+    deleteImage(fileId: string, storagePath: string): Promise<void>;
+}
+export declare const useAnnotationMutations: (scope: JobGroupScope) => AnnotationMutations;

package/dist/data/hooks/useAnnotationMutations.js

@@ -0,0 +1,11 @@
+import { useCallback, useMemo } from 'react';
+import { useAnnotationData } from '../AnnotationDataContext.js';
+export const useAnnotationMutations = (scope) => {
+    const provider = useAnnotationData();
+    const create = useCallback((seed) => provider.create(scope, seed), [provider, scope.orgId, scope.projectId, scope.jobId, scope.groupId]);
+    const update = useCallback((fileId, patch) => provider.update(scope, fileId, patch), [provider, scope.orgId, scope.projectId, scope.jobId, scope.groupId]);
+    const remove = useCallback((fileId) => provider.delete(scope, fileId), [provider, scope.orgId, scope.projectId, scope.jobId, scope.groupId]);
+    const uploadImage = useCallback((fileId, role, blob) => provider.uploadImage(scope, fileId, role, blob), [provider, scope.orgId, scope.projectId, scope.jobId, scope.groupId]);
+    const deleteImage = useCallback((fileId, storagePath) => provider.deleteImage(scope, fileId, storagePath), [provider, scope.orgId, scope.projectId, scope.jobId, scope.groupId]);
+    return useMemo(() => ({ create, update, remove, uploadImage, deleteImage }), [create, update, remove, uploadImage, deleteImage]);
+};

package/dist/export/buildJobCsv.js

@@ -15,8 +15,7 @@ const objectCell = (obj) => obj.url ? hyperlinkCell(obj.url, obj.name) : escapeC
 const toExportDate = (value) => {
     if (value instanceof Date)
         return value;
-    if (value &&
-        typeof value.toDate === 'function') {
+    if (value && typeof value.toDate === 'function') {
         return value.toDate();
     }
     return null;
@@ -30,7 +29,7 @@ const dateCell = (value) => {
         ? `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())} ${pad2(d.getHours())}:${pad2(d.getMinutes())}`
         : '';
 };
-const userCell = (user) => (user ? [user.firstName, user.lastName].filter(Boolean).join(' ') : '');
+const userCell = (user) => user ? [user.firstName, user.lastName].filter(Boolean).join(' ') : '';
 // Pure CSV assembly for the job export, shared by rock-pro-app and
 // rock-desktop so the two platforms emit identical files. With no objects
 // selected and the legacy measurement/label/notes columns on, the

package/dist/exports.d.ts

@@ -1,4 +1,4 @@
-export { evaluateFormula, createFormulaScope, createEnhancedFormulaScope, clearFormulaCache, type EnhancedMapping, type FormulaDefinition, type FormulaEvaluationOptions, } from './formulas/evaluateFormula.js';
+export { evaluateFormula, createFormulaScope, createEnhancedFormulaScope, clearFormulaCache, micrometersToUnitNumber, type EnhancedMapping, type FormulaDefinition, type FormulaEvaluationOptions, } from './formulas/evaluateFormula.js';
 export { calculateFormula } from './formulas/calculateFormula.js';
 export { convertMicrometers } from './utils/micrometersToUnit.js';
 export { parseMeasurement } from './utils/parseMeasurement.js';

package/dist/exports.js

@@ -2,7 +2,7 @@
 // platform-specific `AnnotationCanvas` wrapper lives here. The two index
 // files (index.ts, index.native.ts) re-export from this and add their own
 // AnnotationCanvas import.
-export { evaluateFormula, createFormulaScope, createEnhancedFormulaScope, clearFormulaCache, } from './formulas/evaluateFormula.js';
+export { evaluateFormula, createFormulaScope, createEnhancedFormulaScope, clearFormulaCache, micrometersToUnitNumber, } from './formulas/evaluateFormula.js';
 export { calculateFormula } from './formulas/calculateFormula.js';
 export { convertMicrometers } from './utils/micrometersToUnit.js';
 export { parseMeasurement } from './utils/parseMeasurement.js';

package/dist/formulas/calculateFormula.d.ts

@@ -1,2 +1,2 @@
 import { ColumnConfig, DecimalTolerance, FractionalTolerance, Formula, Measurement, Units } from '../types/firestore.js';
-export declare const calculateFormula: (formula: Formula, formulas: Formula[], columns: Record<string, string>, tableConfig: ColumnConfig[], measurements: Measurement[], unit: Units, fractionalTolerance: FractionalTolerance, decimalTolerance: DecimalTolerance) => string | number | null;
+export declare const calculateFormula: (formula: Formula, formulas: Formula[], columns: Record<string, string>, tableConfig: ColumnConfig[], measurements: Measurement[], unit: Units, _fractionalTolerance?: FractionalTolerance, _decimalTolerance?: DecimalTolerance) => string | number | null;

package/dist/formulas/calculateFormula.js

@@ -1,25 +1,15 @@
-import { ColumnType, } from '../types/firestore.js';
-import { evaluateFormula } from './evaluateFormula.js';
-import { convertMicrometers } from '../utils/micrometersToUnit.js';
-function parseMixedNumber(str) {
-    const parts = str.trim().split(' ');
-    let whole = 0;
-    let fraction = 0;
-    if (parts.length === 2) {
-        whole = parseFloat(parts[0]);
-        const [num, den] = parts[1].split('/').map(Number);
-        fraction = num / den;
-    }
-    else if (parts[0].includes('/')) {
-        const [num, den] = parts[0].split('/').map(Number);
-        fraction = num / den;
-    }
-    else {
-        whole = parseFloat(parts[0]);
-    }
-    return whole + fraction;
-}
-export const calculateFormula = (formula, formulas, columns, tableConfig, measurements, unit, fractionalTolerance, decimalTolerance) => {
+import { ColumnType, Units, } from '../types/firestore.js';
+import { evaluateFormula, micrometersToUnitNumber } from './evaluateFormula.js';
+const VALID_UNITS = new Set(Object.values(Units));
+// A measurement operand resolves in ITS column's locked unit when one is set;
+// an unrecognized/legacy override falls back to the caller's unit — never to
+// normalizeUnitForMathJS's silent 'mm' default, which would be a wrong answer
+// rather than a visible error.
+const resolveColumnUnit = (override, fallback) => (override && VALID_UNITS.has(override) ? override : fallback);
+export const calculateFormula = (formula, formulas, columns, tableConfig, measurements, unit, 
+// Unused since measurement values stopped round-tripping through the display
+// string — kept so the 8-arg call sites in the apps don't break.
+_fractionalTolerance, _decimalTolerance) => {
     // Convert Firestore Map to plain object if necessary
     let variableToColumnMap = {};
     if (formula.variableToColumnMap) {
@@ -45,8 +35,16 @@ export const calculateFormula = (formula, formulas, columns, tableConfig, measur
             const measurement = measurements.find((m) => m.id === measurementId);
             if (!measurement)
                 continue;
-            const { value, unit: displayUnit } = convertMicrometers(measurement.value, unit, fractionalTolerance, decimalTolerance);
-            valueMap[columnId] = parseMixedNumber(value);
+            // Straight um -> display-unit number. The old path rendered the display
+            // STRING (convertMicrometers) and re-parsed it, which rounded the value
+            // to the display tolerance and returned NaN / dropped the inches for the
+            // composite feet-inches formats (`5' 3 1/2"`).
+            //
+            // Each operand resolves in its own column's unit (lock ?? user unit),
+            // so a locked column contributes the number its cell displays. With
+            // mixed locks the expression is numeric over display-space values by
+            // design; the RESULT (and typed constants) stay in the caller's unit.
+            valueMap[columnId] = micrometersToUnitNumber(measurement.value, resolveColumnUnit(column.unitOverride, unit));
         }
         else if (column.type === ColumnType.Angle) {
             const measurement = measurements.find((m) => m.id === measurementId);

package/dist/formulas/evaluateFormula.d.ts

@@ -17,6 +17,16 @@ export interface FormulaEvaluationOptions {
     formulas?: FormulaDefinition[];
     scope?: Record<string, number>;
 }
+export declare function normalizeUnitForMathJS(unit: Units | string): string;
+/**
+ * Convert a stored micrometer value to the number the formula scope expects
+ * for `unit` — the same conversion nested-formula results go through. This is
+ * the ONLY sanctioned way to put a measurement into a valueMap: converting via
+ * the display STRING (convertMicrometers + a string parser) both rounds the
+ * value to the display tolerance and falls apart on composite formats like
+ * `5' 3 1/2"`.
+ */
+export declare function micrometersToUnitNumber(micrometers: number, unit: Units): number;
 export declare function evaluateFormula({ expression, mappings, valueMap, unit, formulas, scope, }: FormulaEvaluationOptions): number | string | null;
 export declare function createFormulaScope({ mappings, valueMap, unit, }: {
     mappings: Record<string, string>;

package/dist/formulas/evaluateFormula.js

@@ -7,7 +7,7 @@ const compile = math.compile.bind(math);
 const mathUnit = math.unit.bind(math);
 // Cache for evaluated formulas to improve performance
 const formulaCache = new Map();
-function normalizeUnitForMathJS(unit) {
+export function normalizeUnitForMathJS(unit) {
     switch (unit) {
         case Units.Centimeters:
         case 'cm':
@@ -30,6 +30,17 @@ function normalizeUnitForMathJS(unit) {
             return 'mm'; // fallback
     }
 }
+/**
+ * Convert a stored micrometer value to the number the formula scope expects
+ * for `unit` — the same conversion nested-formula results go through. This is
+ * the ONLY sanctioned way to put a measurement into a valueMap: converting via
+ * the display STRING (convertMicrometers + a string parser) both rounds the
+ * value to the display tolerance and falls apart on composite formats like
+ * `5' 3 1/2"`.
+ */
+export function micrometersToUnitNumber(micrometers, unit) {
+    return mathUnit(micrometers, 'um').toNumber(normalizeUnitForMathJS(unit));
+}
 // Normalize mapping to EnhancedMapping format
 function normalizeMapping(mapping) {
     if (typeof mapping === 'string') {
@@ -112,7 +123,11 @@ export function evaluateFormula({ expression, mappings, valueMap, unit, formulas
         return 'Error: valueMap is required';
     }
     const evaluationStack = new Set(); // For circular dependency detection
-    const cache = new Map(); // Local cache for this evaluation session
+    // Local cache for this evaluation session. Deliberately per-invocation:
+    // valueMap is rebuilt (with any column unit locks applied) on every
+    // calculateFormula call, so the `${formulaId}_${unit}` key needs no lock
+    // signature — a stale entry cannot outlive the call that created it.
+    const cache = new Map();
     function evaluateNestedFormula(formulaId, currentExpression, currentMappings) {
         // Check for circular dependency
         if (evaluationStack.has(formulaId)) {

package/dist/hooks/useParseMeasurement.d.ts

@@ -0,0 +1,4 @@
+export declare const useParseMeasurement: () => {
+    parseMeasurementInput: (input: string, defaultUnit?: string) => number | null;
+    error: string | null;
+};

package/dist/hooks/useParseMeasurement.js

@@ -0,0 +1,14 @@
+import { useState } from 'react';
+import { parseMeasurement } from '../utils/parseMeasurement.js';
+export const useParseMeasurement = () => {
+    const [error, setError] = useState(null);
+    const parseMeasurementInput = (input, defaultUnit = 'mm') => {
+        setError(null);
+        const result = parseMeasurement(input, defaultUnit);
+        if (result === null) {
+            setError('Invalid measurement. Please provide a valid number and unit.');
+        }
+        return result;
+    };
+    return { parseMeasurementInput, error };
+};

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export * from './exports.js';
-export { evaluateFormula, createFormulaScope, createEnhancedFormulaScope, clearFormulaCache, type EnhancedMapping, type FormulaDefinition, type FormulaEvaluationOptions, } from './formulas/evaluateFormula.js';
+export { evaluateFormula, createFormulaScope, createEnhancedFormulaScope, clearFormulaCache, micrometersToUnitNumber, type EnhancedMapping, type FormulaDefinition, type FormulaEvaluationOptions, } from './formulas/evaluateFormula.js';
 export { calculateFormula } from './formulas/calculateFormula.js';
 export { convertMicrometers } from './utils/micrometersToUnit.js';
 export { parseMeasurement } from './utils/parseMeasurement.js';

package/dist/index.js

@@ -3,7 +3,7 @@
 // WithSkiaWeb. Metro/RN consumers resolve `index.native.ts` instead via
 // the `react-native` condition in package.json `exports`.
 export * from './exports.js';
-export { evaluateFormula, createFormulaScope, createEnhancedFormulaScope, clearFormulaCache, } from './formulas/evaluateFormula.js';
+export { evaluateFormula, createFormulaScope, createEnhancedFormulaScope, clearFormulaCache, micrometersToUnitNumber, } from './formulas/evaluateFormula.js';
 export { calculateFormula } from './formulas/calculateFormula.js';
 export { convertMicrometers } from './utils/micrometersToUnit.js';
 export { parseMeasurement } from './utils/parseMeasurement.js';

package/dist/server.d.ts

@@ -1,4 +1,4 @@
-export { evaluateFormula, createFormulaScope, createEnhancedFormulaScope, clearFormulaCache, type EnhancedMapping, type FormulaDefinition, type FormulaEvaluationOptions, } from './formulas/evaluateFormula.js';
+export { evaluateFormula, createFormulaScope, createEnhancedFormulaScope, clearFormulaCache, micrometersToUnitNumber, type EnhancedMapping, type FormulaDefinition, type FormulaEvaluationOptions, } from './formulas/evaluateFormula.js';
 export { calculateFormula } from './formulas/calculateFormula.js';
 export { convertMicrometers } from './utils/micrometersToUnit.js';
 export { parseMeasurement } from './utils/parseMeasurement.js';
@@ -18,5 +18,5 @@ export { numberToLetterIndex, formGroupInputLabel, listGroupMeasurementLabel, }
 export { toSelectedValues, formatSelectedValues, toStoredValue, } from './utils/selectValues.js';
 export * from './calculator/index.js';
 export * from './export/pdf/index.js';
-export { applyGroupFormulaUm, groupFormulaExpression, micrometersToUnitNumber, unitNumberToMicrometers, type GroupFormulaFrame, } from './formulas/groupFormula.js';
+export { applyGroupFormulaUm, groupFormulaExpression, unitNumberToMicrometers, type GroupFormulaFrame, } from './formulas/groupFormula.js';
 export { MEASUREMENT_LINE_COLOR, MEASUREMENT_LINE_WIDTH, MEASUREMENT_RECT_WIDTH, } from './annotation/canvas/measurementLineStyle.js';

package/dist/server.js

@@ -3,7 +3,7 @@
 // root barrel, whose module graph statically pulls in `react` and
 // `@shopify/react-native-skia`. Only modules with no React/Skia anywhere
 // in their import graph may be re-exported from this file.
-export { evaluateFormula, createFormulaScope, createEnhancedFormulaScope, clearFormulaCache, } from './formulas/evaluateFormula.js';
+export { evaluateFormula, createFormulaScope, createEnhancedFormulaScope, clearFormulaCache, micrometersToUnitNumber, } from './formulas/evaluateFormula.js';
 export { calculateFormula } from './formulas/calculateFormula.js';
 export { convertMicrometers } from './utils/micrometersToUnit.js';
 export { parseMeasurement } from './utils/parseMeasurement.js';
@@ -25,5 +25,9 @@ export * from './calculator/index.js';
 // Canvas → annotated PDF export (Cloud Function renderer). Pure pdf-lib; no
 // React or Skia anywhere in its import graph.
 export * from './export/pdf/index.js';
-export { applyGroupFormulaUm, groupFormulaExpression, micrometersToUnitNumber, unitNumberToMicrometers, } from './formulas/groupFormula.js';
+// groupFormula's own micrometersToUnitNumber (integer constants, NaN on
+// unknown units) stays module-local: the canonical export of that name is the
+// mathjs-exact one from evaluateFormula.js above, and no consumer imported
+// the groupFormula variant.
+export { applyGroupFormulaUm, groupFormulaExpression, unitNumberToMicrometers, } from './formulas/groupFormula.js';
 export { MEASUREMENT_LINE_COLOR, MEASUREMENT_LINE_WIDTH, MEASUREMENT_RECT_WIDTH, } from './annotation/canvas/measurementLineStyle.js';