@reekon-tools/boldr-utils 1.15.5 → 1.17.0

package/dist/annotation/canvas/AnnotationCanvasSkia.js

@@ -4,7 +4,7 @@ import { normalizeRect, placementOf } from './measurementGeometry.js';
 import { arrowheadTriangle, dashIntervals, toSkiaStrokeCap, } from './strokeGeometry.js';
 import { SELECTION_PAD, textResizeGeometry, textShapeBounds, } from './textGeometry.js';
 import { visualShapeBounds } from './shapeGeometry.js';
-import { backgroundLayerDocRect, backgroundLayersOf, } from './backgroundLayers.js';
+import { backgroundLayerDocRect, backgroundLayersOf, canEditBackgroundLayers, } from './backgroundLayers.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';
@@ -251,8 +251,13 @@ export const AnnotationCanvasSkia = ({ width, height, effectiveCanvas, worldTran
                 // bottom-right handle — backgrounds scale uniformly about their
                 // top-left corner (the transform origin), so a single opposite-corner
                 // grab is the whole gizmo. Chrome tracks the live drag/resize
-                // transform the same way the layer itself does above.
-                const layer = backgroundLayersOf(effectiveCanvas.viewport).find((l) => l.id === selectedId);
+                // transform the same way the layer itself does above. A lone
+                // background is never editable (canEditBackgroundLayers), so it gets
+                // no chrome even when a stale selection still names it — e.g. right
+                // after the other layer of a pair was removed.
+                const layer = canEditBackgroundLayers(effectiveCanvas.viewport)
+                    ? backgroundLayersOf(effectiveCanvas.viewport).find((l) => l.id === selectedId)
+                    : undefined;
                 if (layer) {
                     const r = backgroundLayerDocRect(layer);
                     const isResizing = layer.id === resizingId;

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

@@ -2,6 +2,7 @@ import type { AnnotationBackgroundLayer, AnnotationViewport, BackgroundLayerTran
 export declare const LEGACY_BACKGROUND_LAYER_ID = "background-legacy";
 export declare const BACKGROUND_PLACEMENT_GAP_RATIO = 0.02;
 export declare const backgroundLayersOf: (viewport: AnnotationViewport) => AnnotationBackgroundLayer[];
+export declare const canEditBackgroundLayers: (viewport: AnnotationViewport) => boolean;
 export declare const backgroundLayerDocRect: (layer: AnnotationBackgroundLayer) => {
     x: number;
     y: number;

package/dist/annotation/canvas/backgroundLayers.js

@@ -46,6 +46,14 @@ export const backgroundLayersOf = (viewport) => {
         },
     ];
 };
+// Whether the background stack is user-editable at all — selectable, draggable,
+// corner-scalable. A lone image IS the canvas: there is nothing to arrange it
+// against, so it exposes no selection chrome and never moves; taps and drags
+// on it fall through to the ordinary empty-canvas behavior (deselect / pan).
+// Only once a second image exists does arranging make sense, and then every
+// layer becomes editable. Shared by the select tool's hit-tests and the
+// selection chrome so both platforms agree on the rule.
+export const canEditBackgroundLayers = (viewport) => backgroundLayersOf(viewport).length > 1;
 // The doc-space rectangle a layer occupies: the intrinsic pixel grid under
 // the layer's translate+scale.
 export const backgroundLayerDocRect = (layer) => ({

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

@@ -1,4 +1,4 @@
-import { backgroundLayerDocRect, backgroundLayersOf, } from '../backgroundLayers.js';
+import { backgroundLayerDocRect, backgroundLayersOf, canEditBackgroundLayers, } from '../backgroundLayers.js';
 import { stampTileDims } from '../stampLayout.js';
 import { placementOf, linePosOf, snapLinePos, lerp, recomputeAnchor, rectCenter, rectCornerPoint, oppositeRectCorner, hitPlacedMeasurement, } from '../measurementGeometry.js';
 import { hitShapeOutline, visualShapeBounds } from '../shapeGeometry.js';
@@ -462,7 +462,10 @@ const shapeCornerPatch = (doc, id, corner, delta) => {
 // 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
 // layout tool's two-step model, which keeps a full-bleed background from
-// hijacking pan/marquee gestures. ---
+// hijacking pan/marquee gestures. And none of it applies to a LONE image: with
+// a single background there is nothing to arrange, so it is not selectable,
+// draggable, or scalable at all (canEditBackgroundLayers) — every hit-test
+// below misses, and the gesture falls through to deselect / pan. ---
 // Doc-space clamp on a resized background's larger doc dimension. The floor
 // keeps a corner drag from collapsing a layer below grabbable size; the
 // ceiling keeps the doc rect (which feeds fit math and the web SVG raster
@@ -478,6 +481,8 @@ const pointInBackgroundLayer = (layer, p) => {
 // layers draw on top). Point-in-doc-rect, no padding: a background is a big
 // target already.
 const findBackgroundHit = (doc, world) => {
+    if (!canEditBackgroundLayers(doc.viewport))
+        return null;
     const layers = backgroundLayersOf(doc.viewport);
     for (let i = layers.length - 1; i >= 0; i--) {
         if (pointInBackgroundLayer(layers[i], world)) {
@@ -490,6 +495,8 @@ const findBackgroundHit = (doc, world) => {
 // paths call this only after the general hit-test misses, so annotation
 // elements always win a grab over the background beneath them.
 const findSelectedBackgroundHit = (doc, world, selectedIds) => {
+    if (!canEditBackgroundLayers(doc.viewport))
+        return null;
     const layers = backgroundLayersOf(doc.viewport);
     for (let i = layers.length - 1; i >= 0; i--) {
         const layer = layers[i];
@@ -527,7 +534,11 @@ const backgroundResizeGeometry = (layer) => {
 // endpoint handles either way.
 const findResizeHandleHit = (doc, id, world, zoom) => {
     const s = doc.shapes.find((x) => x.id === id);
-    const layer = s ? null : backgroundLayerById(doc, id);
+    // A lone background is not editable at all (canEditBackgroundLayers), so
+    // its corner offers no handle — even to a stale selection naming it.
+    const layer = s || !canEditBackgroundLayers(doc.viewport)
+        ? null
+        : backgroundLayerById(doc, id);
     const geom = s
         ? textResizeGeometry(s)
         : layer

package/dist/calculator/index.d.ts

@@ -9,4 +9,5 @@ export * from './instance.js';
 export * from './runtime.js';
 export * from './display.js';
 export * from './chips.js';
+export * from './preview.js';
 export { calculatorDefinitionSchema, expressionSymbols, validateCalculatorDefinition, type IssueSeverity, type ValidationIssue, type ValidationResult, } from './validate.js';

package/dist/calculator/index.js

@@ -15,4 +15,5 @@ export * from './instance.js';
 export * from './runtime.js';
 export * from './display.js';
 export * from './chips.js';
+export * from './preview.js';
 export { calculatorDefinitionSchema, expressionSymbols, validateCalculatorDefinition, } from './validate.js';

package/dist/calculator/preview.d.ts

@@ -0,0 +1,22 @@
+import { type CalculatorDefinition, type CalculatorField } from './schema.js';
+import type { CalculatorInstanceFileData } from './instance.js';
+/**
+ * The field a thumbnail headlines, per CalculatorDefinition.previewFieldId's
+ * tri-state: an explicit id (when it names a numeric output), null for none,
+ * absent for auto — the sole numeric output, if there is exactly one.
+ */
+export declare const previewFieldFor: (definition: Pick<CalculatorDefinition, "fields" | "previewFieldId">) => CalculatorField | null;
+export interface PreviewValue {
+    field: CalculatorField;
+    /** Display string in `unit` — fractional inches etc., same as the runtime. */
+    value: string;
+    /** Unit label; empty for unit-less numbers. */
+    unit: string;
+}
+/**
+ * The headline value for an instance, or null when there is nothing to show:
+ * no preview field, the field is unresolved (inputs missing), or it is in
+ * conflict (the runtime withholds conflicted values behind a dash — a tile
+ * should show nothing rather than a dash).
+ */
+export declare const previewValueFor: (fileData: Pick<CalculatorInstanceFileData, "definition" | "entries" | "displayUnitOverrides">) => PreviewValue | null;

package/dist/calculator/preview.js

@@ -0,0 +1,43 @@
+// Thumbnail headline for a saved calculator instance (Asana
+// 1217881404454870): which output a tile shows, and its formatted value.
+// Shared by boldr-pro's FilePreview and rock-desktop so both platforms pick
+// the same field and print the same string. Pure — runs the same
+// deriveRuntime pass the runtime and the T1R drift check use, so it needs no
+// stored result (computed values are never persisted; see instance.ts).
+import { isEquationTargetKind, } from './schema.js';
+import { deriveRuntime } from './runtime.js';
+import { displayUnitFor, formatFieldValue } from './display.js';
+/** Outputs eligible to headline a thumbnail: numeric, equation-target kinds. */
+const numericOutputs = (definition) => definition.fields.filter((field) => field.role === 'output' && isEquationTargetKind(field.kind));
+/**
+ * The field a thumbnail headlines, per CalculatorDefinition.previewFieldId's
+ * tri-state: an explicit id (when it names a numeric output), null for none,
+ * absent for auto — the sole numeric output, if there is exactly one.
+ */
+export const previewFieldFor = (definition) => {
+    if (definition.previewFieldId === null)
+        return null;
+    const candidates = numericOutputs(definition);
+    if (typeof definition.previewFieldId === 'string') {
+        return (candidates.find((field) => field.id === definition.previewFieldId) ?? null);
+    }
+    return candidates.length === 1 ? candidates[0] : null;
+};
+/**
+ * The headline value for an instance, or null when there is nothing to show:
+ * no preview field, the field is unresolved (inputs missing), or it is in
+ * conflict (the runtime withholds conflicted values behind a dash — a tile
+ * should show nothing rather than a dash).
+ */
+export const previewValueFor = (fileData) => {
+    const field = previewFieldFor(fileData.definition);
+    if (!field)
+        return null;
+    const resolved = deriveRuntime(fileData.definition, fileData.entries ?? {})
+        .resolved[field.id];
+    if (!resolved || resolved.conflict || typeof resolved.value !== 'number') {
+        return null;
+    }
+    const unit = displayUnitFor(field, fileData.displayUnitOverrides ?? {});
+    return { field, ...formatFieldValue(field, unit, resolved.value) };
+};

package/dist/calculator/schema.d.ts

@@ -190,6 +190,20 @@ export interface CalculatorDefinition {
     /** Inputs + outputs in one list, discriminated by `role`. */
     fields: CalculatorField[];
     equations: CalculatorEquation[];
+    /**
+     * The output whose resolved value a saved instance's THUMBNAIL headlines
+     * (Asana 1217881404454870 — Area/Volume and every T1R function calculator
+     * are impractical to open one by one just to read the result). Tri-state:
+     *   - absent (undefined): AUTO — the sole numeric output when the
+     *     calculator has exactly one, nothing when it has several. This is also
+     *     what instances frozen before the field existed resolve to, so they
+     *     gain a headline without being re-saved.
+     *   - null: explicitly none — the author opted a single-output calc out.
+     *   - id: that output. Must be role 'output' and an equation-target kind;
+     *     anything else is validated as a warning and ignored at runtime.
+     * Always resolve through previewFieldFor() — never read this raw.
+     */
+    previewFieldId?: string | null;
     /** Diagram file (files subcollection doc carrying the Skia canvas). */
     diagramFileId?: string | null;
     /** Public calculators are readable by everyone; rules/query key. */

package/dist/calculator/schema.js

@@ -208,6 +208,8 @@ export const createEmptyCalculatorDefinition = (id) => ({
     category: null,
     fields: [],
     equations: [],
+    // previewFieldId is deliberately ABSENT, not null: absent means "auto"
+    // (headline the sole numeric output), null means the author opted out.
     diagramFileId: null,
     isPublic: false,
 });

package/dist/calculator/validate.d.ts

@@ -174,6 +174,7 @@ export declare const calculatorDefinitionSchema: z.ZodObject<{
         variableUnits: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         resultUnit: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    previewFieldId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     diagramFileId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     isPublic: z.ZodBoolean;
     sharedUserIds: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/calculator/validate.js

@@ -127,6 +127,9 @@ export const calculatorDefinitionSchema = z.object({
     category: z.string().nullish(),
     fields: z.array(calculatorFieldSchema),
     equations: z.array(calculatorEquationSchema),
+    // Listed so zod's unknown-key stripping doesn't silently drop it (see the
+    // `category` note above). Referential checks live in the invariant pass.
+    previewFieldId: z.string().nullish(),
     diagramFileId: z.string().nullable().optional(),
     isPublic: z.boolean(),
     sharedUserIds: z.array(z.string()).optional(),
@@ -229,6 +232,20 @@ export const validateCalculatorDefinition = (input) => {
         }
         fieldIds.add(field.id);
     });
+    // --- Thumbnail headline field -------------------------------------------
+    // Warnings, not errors: a dangling or mis-typed previewFieldId must not brick
+    // a published calculator (or every instance that froze it) — the runtime
+    // helper (previewFieldFor) simply shows no headline for it.
+    if (typeof def.previewFieldId === 'string') {
+        const previewField = def.fields.find((f) => f.id === def.previewFieldId);
+        if (!previewField) {
+            push('preview-field-missing', 'previewFieldId', `Thumbnail result field "${def.previewFieldId}" does not exist`, 'warning');
+        }
+        else if (previewField.role !== 'output' ||
+            !isEquationTargetKind(previewField.kind)) {
+            push('preview-field-not-numeric-output', 'previewFieldId', `Thumbnail result field "${previewField.name}" must be a numeric output`, 'warning');
+        }
+    }
     const equationIds = new Set();
     def.equations.forEach((eq, i) => {
         if (equationIds.has(eq.id)) {

package/dist/exports.d.ts

@@ -32,7 +32,7 @@ export type { MeasurementStampRenderArgs, RenderMeasurementStamp, } from './anno
 export { STAMP_TILE_SIZE, GROUP_HEADER_TILE_WIDTH, GROUP_HEADER_TILE_HEIGHT, GROUP_HEADER_COLLAPSED_WIDTH, GROUP_HEADER_COLLAPSED_HEIGHT, GROUP_HEADER_DESIGN, groupHeaderBaseDims, DEFAULT_TILE_SCALE, TILE_SCALE_MIN, TILE_SCALE_MAX, clampTileScale, resolveTileScaleFactor, resolveHeaderTileScaleFactor, resolveFileTileScaleFactor, tileDocSizeForFactor, tileScaleFromDocSize, stampTileSize, stampTileDims, isUnassociatedStamp, isFileStamp, type StampTileDims, } from './annotation/canvas/stampLayout.js';
 export { GROUP_HEADER_STYLE, describeGroupHeader, groupHeaderSignature, type GroupHeaderBadge, type GroupHeaderDescriptor, } from './annotation/canvas/groupHeaderLayout.js';
 export { createViewportApi, fitToScreen, fitRectToScreen, imageDocRect, panBy, zoomAt, DEFAULT_VIEWPORT, type ViewportApi, type ViewportState, } from './annotation/canvas/viewport.js';
-export { LEGACY_BACKGROUND_LAYER_ID, BACKGROUND_PLACEMENT_GAP_RATIO, backgroundLayersOf, backgroundLayerDocRect, backgroundLayersUnionRect, placeNewBackgroundLayer, } from './annotation/canvas/backgroundLayers.js';
+export { LEGACY_BACKGROUND_LAYER_ID, BACKGROUND_PLACEMENT_GAP_RATIO, backgroundLayersOf, canEditBackgroundLayers, backgroundLayerDocRect, backgroundLayersUnionRect, placeNewBackgroundLayer, } from './annotation/canvas/backgroundLayers.js';
 export { createPenTool, type PenToolOptions, } from './annotation/canvas/tools/penTool.js';
 export { createSelectTool, type SelectToolOptions, } from './annotation/canvas/tools/selectTool.js';
 export { createMeasurementStampTool, type MeasurementStampToolOptions, } from './annotation/canvas/tools/measurementStampTool.js';

package/dist/exports.js

@@ -37,7 +37,7 @@ export { InMemoryAnnotationProvider } from './annotation/data/InMemoryAnnotation
 export { STAMP_TILE_SIZE, GROUP_HEADER_TILE_WIDTH, GROUP_HEADER_TILE_HEIGHT, GROUP_HEADER_COLLAPSED_WIDTH, GROUP_HEADER_COLLAPSED_HEIGHT, GROUP_HEADER_DESIGN, groupHeaderBaseDims, DEFAULT_TILE_SCALE, TILE_SCALE_MIN, TILE_SCALE_MAX, clampTileScale, resolveTileScaleFactor, resolveHeaderTileScaleFactor, resolveFileTileScaleFactor, tileDocSizeForFactor, tileScaleFromDocSize, stampTileSize, stampTileDims, isUnassociatedStamp, isFileStamp, } from './annotation/canvas/stampLayout.js';
 export { GROUP_HEADER_STYLE, describeGroupHeader, groupHeaderSignature, } from './annotation/canvas/groupHeaderLayout.js';
 export { createViewportApi, fitToScreen, fitRectToScreen, imageDocRect, panBy, zoomAt, DEFAULT_VIEWPORT, } from './annotation/canvas/viewport.js';
-export { LEGACY_BACKGROUND_LAYER_ID, BACKGROUND_PLACEMENT_GAP_RATIO, backgroundLayersOf, backgroundLayerDocRect, backgroundLayersUnionRect, placeNewBackgroundLayer, } from './annotation/canvas/backgroundLayers.js';
+export { LEGACY_BACKGROUND_LAYER_ID, BACKGROUND_PLACEMENT_GAP_RATIO, backgroundLayersOf, canEditBackgroundLayers, backgroundLayerDocRect, backgroundLayersUnionRect, placeNewBackgroundLayer, } from './annotation/canvas/backgroundLayers.js';
 export { createPenTool, } from './annotation/canvas/tools/penTool.js';
 export { createSelectTool, } from './annotation/canvas/tools/selectTool.js';
 export { createMeasurementStampTool, } from './annotation/canvas/tools/measurementStampTool.js';

package/dist/server.d.ts

@@ -0,0 +1,16 @@
+export { evaluateFormula, createFormulaScope, createEnhancedFormulaScope, clearFormulaCache, 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';
+export * from './types/firestore.js';
+export * from './types/layout.js';
+export * from './types/annotation.js';
+export { getToleranceColor, getToleranceSecondaryColor, calculateDeviationPercentage, isWithinTolerance, generateToleranceGradient, createDefaultToleranceThresholds, DEFAULT_TOLERANCE_COLORS, DEFAULT_TOLERANCE_SECONDARY_COLORS, type ToleranceThreshold, type ToleranceConfig, } from './utils/tolerance.js';
+export { DEFAULT_GROUP_INDEX, isDefaultGroup, findDefaultGroup, isFormGroupCompleted, } from './utils/groups.js';
+export { ALL_EXPORT_CATEGORIES, ALL_EXPORT_MEASUREMENT_DATA_FIELDS, ALL_EXPORT_OBJECT_TYPES, DEFAULT_EXPORT_CONFIG, EXPORT_EVERYTHING_CONFIG, normalizeExportConfig, type ExportCategory, type ExportConfig, type ExportImageFormat, type ExportMeasurementDataField, type ExportMeasurementFilter, type ExportObjectType, } from './export/config.js';
+export { classifyFileForExport } from './export/objectKinds.js';
+export { buildJobCsv, escapeCSVField, hyperlinkCell, type BuildJobCsvInput, type ExportObjectRow, type ExportScope, } from './export/buildJobCsv.js';
+export { desktopBaseUrlForFirebaseProject, desktopFileEditorUrl, type DesktopLinkContext, } from './export/desktopLinks.js';
+export { numberToLetterIndex, formGroupInputLabel, listGroupMeasurementLabel, } from './utils/indexLabels.js';
+export { toSelectedValues, formatSelectedValues, toStoredValue, } from './utils/selectValues.js';
+export * from './calculator/index.js';

package/dist/server.js

@@ -0,0 +1,21 @@
+// Server-safe entry point (package export "./server"). Node consumers —
+// boldr-api, Cloud Functions, scripts — import from here instead of the
+// 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 { calculateFormula } from './formulas/calculateFormula.js';
+export { convertMicrometers } from './utils/micrometersToUnit.js';
+export { parseMeasurement } from './utils/parseMeasurement.js';
+export * from './types/firestore.js';
+export * from './types/layout.js';
+export * from './types/annotation.js';
+export { getToleranceColor, getToleranceSecondaryColor, calculateDeviationPercentage, isWithinTolerance, generateToleranceGradient, createDefaultToleranceThresholds, DEFAULT_TOLERANCE_COLORS, DEFAULT_TOLERANCE_SECONDARY_COLORS, } from './utils/tolerance.js';
+export { DEFAULT_GROUP_INDEX, isDefaultGroup, findDefaultGroup, isFormGroupCompleted, } from './utils/groups.js';
+export { ALL_EXPORT_CATEGORIES, ALL_EXPORT_MEASUREMENT_DATA_FIELDS, ALL_EXPORT_OBJECT_TYPES, DEFAULT_EXPORT_CONFIG, EXPORT_EVERYTHING_CONFIG, normalizeExportConfig, } from './export/config.js';
+export { classifyFileForExport } from './export/objectKinds.js';
+export { buildJobCsv, escapeCSVField, hyperlinkCell, } from './export/buildJobCsv.js';
+export { desktopBaseUrlForFirebaseProject, desktopFileEditorUrl, } from './export/desktopLinks.js';
+export { numberToLetterIndex, formGroupInputLabel, listGroupMeasurementLabel, } from './utils/indexLabels.js';
+export { toSelectedValues, formatSelectedValues, toStoredValue, } from './utils/selectValues.js';
+export * from './calculator/index.js';

package/dist/types/firestore.d.ts

@@ -67,6 +67,7 @@ export interface Project extends FirestoreDoc, Timestamps {
     state: string;
     collectionId: string | null;
     index: number | null;
+    bgImgUpdatedAt?: number;
 }
 export declare enum TemplateType {
     Layout = "layout",
@@ -228,6 +229,7 @@ export interface Job extends FirestoreDoc, Timestamps {
     description?: string;
     starred?: boolean;
     lastModified: Date;
+    bgImgUpdatedAt?: number;
 }
 export interface Section extends Timestamps {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reekon-tools/boldr-utils",
-  "version": "1.15.5",
+  "version": "1.17.0",
   "description": "Shared utilities for formulas and measurement conversion used in Reekon apps",
   "author": "REEKON Tools",
   "license": "MIT",
@@ -24,6 +24,11 @@
       "import": "./dist/theme/colors.js",
       "default": "./dist/theme/colors.js"
     },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {