@reekon-tools/boldr-utils 1.6.38 → 1.7.0

package/dist/annotation/canvas/tools/measurementLineTool.d.ts

@@ -0,0 +1,12 @@
+import type { PlacedMeasurementRef } from '../../../types/annotation.js';
+import type { Tool } from '../Tool.js';
+export interface MeasurementLineToolOptions {
+    id?: string;
+    label?: string;
+    minDragPx?: number;
+    autoSwitchToSelect?: boolean;
+    selectToolId?: string;
+    onAutoSwitch?: (toToolId: string) => void;
+    onPlaced?: (measurement: PlacedMeasurementRef) => void;
+}
+export declare const createMeasurementLineTool: (options?: MeasurementLineToolOptions) => Tool;

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

@@ -0,0 +1,95 @@
+import { DEFAULT_LAYER_ID } from '../../../types/annotation.js';
+import { DEFAULT_LINE_POS, recomputeAnchor } from '../measurementGeometry.js';
+let counter = 0;
+const makeId = () => `annotation-${Date.now().toString(36)}-${(counter++).toString(36)}`;
+const firstLayerId = (doc) => doc.layers[0]?.id ?? DEFAULT_LAYER_ID;
+// Build the blank line-measurement annotation for a drag from `a` to `b`: a
+// 2-point line with a value tile magnetized to its center (linePos 0.5). The
+// payload mirrors useAnnotationCanvasState's placeAnnotationAtCenter so a drawn
+// line and a (legacy) center-placed one are byte-identical once committed.
+const buildLineMeasurement = (opts) => {
+    const line = { a: opts.a, b: opts.b };
+    return {
+        id: opts.id,
+        layerId: opts.layerId,
+        placement: 'line',
+        line,
+        linePos: DEFAULT_LINE_POS,
+        // Center of the line; recomputeAnchor keeps this in sync on edits.
+        anchor: recomputeAnchor(line, 'line', DEFAULT_LINE_POS, {
+            x: (opts.a.x + opts.b.x) / 2,
+            y: (opts.a.y + opts.b.y) / 2,
+        }),
+        showLabel: true,
+        showValue: true,
+        createdAt: Date.now(),
+    };
+};
+// Drag-to-draw measurement-line tool. Press-drag rubber-bands a measurement
+// annotation (a line with a blank value tile at its center); release commits
+// it. Mirrors createShapeTool's interaction so "input lines" are placed the
+// same way as shapes — draw to add, not tap-the-icon-to-add — replacing the
+// old center-place affordance. The annotation stays blank (no measurement
+// associated) until the user fills it via the tile / picker. Skia-free, like
+// every tool factory; it renders its live preview through ctx.preview, so it
+// works on web and (via the generic tool-pan dispatch) on native.
+export const createMeasurementLineTool = (options = {}) => {
+    const minDragPx = options.minDragPx ?? 4;
+    const autoSwitchToSelect = options.autoSwitchToSelect ?? true;
+    const selectToolId = options.selectToolId ?? 'select';
+    return {
+        id: options.id ?? 'measure-line',
+        label: options.label ?? 'Measurement line',
+        cursor: 'crosshair',
+        onPointerDown(event) {
+            return {
+                kind: 'measurement-line-drawing',
+                id: makeId(),
+                startWorld: event.world,
+                startScreen: event.screen,
+                moved: false,
+            };
+        },
+        onPointerMove(event, ctx, state) {
+            const s = state;
+            if (s?.kind !== 'measurement-line-drawing')
+                return s;
+            const measurement = buildLineMeasurement({
+                id: s.id,
+                layerId: firstLayerId(ctx.document),
+                a: s.startWorld,
+                b: event.world,
+            });
+            ctx.preview({ ops: [{ op: 'addMeasurement', measurement }] });
+            return { ...s, moved: true };
+        },
+        onPointerUp(event, ctx, state) {
+            const s = state;
+            if (s?.kind !== 'measurement-line-drawing')
+                return;
+            const dx = event.screen.x - s.startScreen.x;
+            const dy = event.screen.y - s.startScreen.y;
+            if (!s.moved || dx * dx + dy * dy < minDragPx * minDragPx) {
+                // Accidental tap — discard the rubber-band, commit nothing.
+                ctx.preview({ ops: [] });
+                return;
+            }
+            const measurement = buildLineMeasurement({
+                id: s.id,
+                layerId: firstLayerId(ctx.document),
+                a: s.startWorld,
+                b: event.world,
+            });
+            ctx.commit({ ops: [{ op: 'addMeasurement', measurement }] });
+            // Leave it selected (and hand back to select) so the blank line can be
+            // filled / moved straight away — the same flow as the text tool.
+            ctx.setSelection({ ids: [measurement.id] });
+            options.onPlaced?.(measurement);
+            if (autoSwitchToSelect)
+                options.onAutoSwitch?.(selectToolId);
+        },
+        onCancel(_state, ctx) {
+            ctx.preview({ ops: [] });
+        },
+    };
+};

package/dist/annotation/canvas/useAnnotationCanvasState.js

@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { applyPatch, invertPatch, DEFAULT_LAYER_ID, } from '../../types/annotation.js';
-import { resolveTileScaleFactor, stampTileDims, tileDocSizeForFactor, tileScaleFromDocSize, } from './stampLayout.js';
+import { resolveTileScaleFactor, stampTileDims, STAMP_TILE_SIZE, tileDocSizeForFactor, tileScaleFromDocSize, } from './stampLayout.js';
 import { createViewportApi, fitRectToScreen, imageDocRect, panBy, zoomAt, DEFAULT_VIEWPORT, } from './viewport.js';
 import { buildRemoveMeasurementOps, recomputeAnchor, rectCenter, DEFAULT_LINE_POS, } from './measurementGeometry.js';
 // The viewport that frames the document's content on screen. When a background
@@ -265,6 +265,32 @@ export const useAnnotationCanvasState = (props) => {
                 ],
             });
         };
+        // Consecutive place-at-center drops would all land dead-center, stacking
+        // each new tile exactly on top of the previous one. Cascade instead: walk
+        // down-right in fixed screen-px steps from center until a slot with no
+        // existing anchor is found. Occupancy is derived from the live placed
+        // measurements (not a drop counter), so moving or deleting a tile frees
+        // its slot automatically. Screen space is the right frame — tiles are
+        // screen-constant boxes — and mirrors the Nutrient file-viewer's cascade.
+        const cascadeCenterWorld = () => {
+            const c = ctxRef.current;
+            const CASCADE_STEP = 30;
+            const anchorsScreen = c.document.placedMeasurements.map((m) => c.viewport.worldToScreen(m.anchor));
+            const slotTaken = (x, y) => anchorsScreen.some((p) => Math.abs(p.x - x) < CASCADE_STEP / 2 &&
+                Math.abs(p.y - y) < CASCADE_STEP / 2);
+            // Stop cascading before the tile's right/bottom edge would leave the
+            // screen (tiles are centered on their anchor).
+            const halfTile = (STAMP_TILE_SIZE / 2) * c.tileScaleFactor * c.tileViewportScale;
+            let cx = width / 2;
+            let cy = height / 2;
+            while (slotTaken(cx, cy) &&
+                cx + halfTile + CASCADE_STEP <= width &&
+                cy + halfTile + CASCADE_STEP <= height) {
+                cx += CASCADE_STEP;
+                cy += CASCADE_STEP;
+            }
+            return c.viewport.screenToWorld({ x: cx, y: cy });
+        };
         imperativeRef.current = {
             undo() {
                 const entry = undoStackRef.current.pop();
@@ -328,10 +354,7 @@ export const useAnnotationCanvasState = (props) => {
             },
             placeMeasurementAtCenter(ref) {
                 const c = ctxRef.current;
-                const anchor = c.viewport.screenToWorld({
-                    x: width / 2,
-                    y: height / 2,
-                });
+                const anchor = cascadeCenterWorld();
                 const placed = {
                     id: `measurement-${Date.now().toString(36)}-${Math.floor(Math.random() * 1e9).toString(36)}`,
                     layerId: c.document.layers[0]?.id ?? DEFAULT_LAYER_ID,
@@ -352,10 +375,7 @@ export const useAnnotationCanvasState = (props) => {
             },
             placeAnnotationAtCenter(opts) {
                 const c = ctxRef.current;
-                const center = c.viewport.screenToWorld({
-                    x: width / 2,
-                    y: height / 2,
-                });
+                const center = cascadeCenterWorld();
                 // Default line length: a generous fraction of the doc width, clamped,
                 // so the leader and its endcaps clear the fixed-size tile at full-fit.
                 const len = opts?.defaultLengthDoc ?? defaultLeaderLenDoc(canvas.viewport.width);
@@ -492,10 +512,7 @@ export const useAnnotationCanvasState = (props) => {
             },
             placeColumnTileAtCenter(binding) {
                 const c = ctxRef.current;
-                const anchor = c.viewport.screenToWorld({
-                    x: width / 2,
-                    y: height / 2,
-                });
+                const anchor = cascadeCenterWorld();
                 const placed = {
                     id: `measurement-${Date.now().toString(36)}-${Math.floor(Math.random() * 1e9).toString(36)}`,
                     layerId: c.document.layers[0]?.id ?? DEFAULT_LAYER_ID,
@@ -513,10 +530,7 @@ export const useAnnotationCanvasState = (props) => {
             },
             placeGroupHeaderAtCenter(ref) {
                 const c = ctxRef.current;
-                const anchor = c.viewport.screenToWorld({
-                    x: width / 2,
-                    y: height / 2,
-                });
+                const anchor = cascadeCenterWorld();
                 // No showLabel/showValue/placement — a header is not an input; it
                 // renders the group's name/index, resolved live by the consumer.
                 const placed = {

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

@@ -12,8 +12,13 @@ export interface TemplateScope {
     orgId?: string;
     templateId: string;
 }
-export type AnnotationScope = JobGroupScope | TemplateScope;
+export interface CalculatorScope {
+    kind: 'calculator';
+    calculatorId: string;
+}
+export type AnnotationScope = JobGroupScope | TemplateScope | CalculatorScope;
 export declare const isTemplateScope: (s: AnnotationScope) => s is TemplateScope;
+export declare const isCalculatorScope: (s: AnnotationScope) => s is CalculatorScope;
 export declare const annotationScopeKey: (s: AnnotationScope | null) => string;
 export type Unsubscribe = () => void;
 export type FieldOp = {

package/dist/annotation/data/AnnotationDataProvider.js

@@ -1,11 +1,14 @@
 export const isTemplateScope = (s) => 'kind' in s && s.kind === 'template';
+export const isCalculatorScope = (s) => 'kind' in s && s.kind === 'calculator';
 // Stable string identity for a scope, for React hook dep arrays — scope
 // objects are typically rebuilt every render.
 export const annotationScopeKey = (s) => s == null
     ? ''
     : isTemplateScope(s)
         ? `template/${s.orgId ?? ''}/${s.templateId}`
-        : `job/${s.orgId}/${s.projectId}/${s.jobId}/${s.groupId}`;
+        : isCalculatorScope(s)
+            ? `calculator/${s.calculatorId}`
+            : `job/${s.orgId}/${s.projectId}/${s.jobId}/${s.groupId}`;
 export const isFieldOp = (v) => !!v &&
     typeof v === 'object' &&
     'kind' in v &&

package/dist/calculator/evaluate.d.ts

@@ -0,0 +1,49 @@
+import type { CalculatorDefinition, CalculatorEquation, CalculatorField, CalculatorFieldValue, CalculatorValues } from './schema.js';
+export type ExpressionResult = {
+    ok: true;
+    value: number;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The unit-agnostic expression core: compile + evaluate + finiteness checks,
+ * no unit coercion. Scope values and the result share whatever unit system
+ * the caller established (canonical, for calculator equations).
+ */
+export declare const evaluateExpression: (expression: string, scope: Record<string, number>) => ExpressionResult;
+/**
+ * The canonical numeric value a field contributes to an equation scope, or
+ * null when the field has no usable value. Select and instructions fields are
+ * non-computational (validation rejects mapping them into equations).
+ */
+export declare const numericFieldValue: (field: CalculatorField, value: CalculatorFieldValue | undefined) => number | null;
+export type EquationResult = {
+    ok: true;
+    value: number;
+} | {
+    ok: false;
+    reason: 'missing-inputs';
+    missingFieldIds: string[];
+} | {
+    ok: false;
+    reason: 'error';
+    error: string;
+};
+/**
+ * Evaluate one equation against canonical field values. Variables referencing
+ * other output fields recurse into their equations (cycle-guarded).
+ */
+export declare const evaluateEquation: ({ definition, equation, values, }: {
+    definition: Pick<CalculatorDefinition, "fields" | "equations">;
+    equation: CalculatorEquation;
+    values: CalculatorValues;
+}) => EquationResult;
+/**
+ * Evaluate every equation in the definition. Returns a result per target
+ * field id — the live-preview / runtime "recompute all outputs" entry point.
+ */
+export declare const evaluateOutputs: ({ definition, values, }: {
+    definition: Pick<CalculatorDefinition, "fields" | "equations">;
+    values: CalculatorValues;
+}) => Record<string, EquationResult>;

package/dist/calculator/evaluate.js

@@ -0,0 +1,207 @@
+import { create, all } from 'mathjs';
+import { ColumnType } from '../types/firestore.js';
+import { equationForField, findField } from './schema.js';
+// Trig in calculator equations works in DEGREES: angle fields are stored in
+// degrees canonically, and construction authors write `H = W * tan(A)`
+// expecting A in degrees. mathjs has no `angle` config option (evaluateFormula
+// passes `{ angle: 'deg' }`, but mathjs ignores it and runs radians), so we
+// override the trig functions with degree-aware wrappers — the documented
+// mathjs recipe for degree mode.
+const math = create(all);
+const DEG = Math.PI / 180;
+math.import({
+    sin: (x) => Math.sin(x * DEG),
+    cos: (x) => Math.cos(x * DEG),
+    tan: (x) => Math.tan(x * DEG),
+    sec: (x) => 1 / Math.cos(x * DEG),
+    csc: (x) => 1 / Math.sin(x * DEG),
+    cot: (x) => 1 / Math.tan(x * DEG),
+    asin: (x) => Math.asin(x) / DEG,
+    acos: (x) => Math.acos(x) / DEG,
+    atan: (x) => Math.atan(x) / DEG,
+    atan2: (y, x) => Math.atan2(y, x) / DEG,
+}, { override: true });
+const compile = math.compile.bind(math);
+// Small compile cache — the editor preview re-evaluates on every keystroke.
+const compileCache = new Map();
+const COMPILE_CACHE_MAX = 200;
+const compiled = (expression) => {
+    const hit = compileCache.get(expression);
+    if (hit)
+        return hit;
+    const node = compile(expression);
+    if (compileCache.size >= COMPILE_CACHE_MAX)
+        compileCache.clear();
+    compileCache.set(expression, node);
+    return node;
+};
+/**
+ * The unit-agnostic expression core: compile + evaluate + finiteness checks,
+ * no unit coercion. Scope values and the result share whatever unit system
+ * the caller established (canonical, for calculator equations).
+ */
+export const evaluateExpression = (expression, scope) => {
+    let node;
+    try {
+        node = compiled(expression);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: `Invalid expression: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    let result;
+    try {
+        // Spread so mathjs can't mutate the caller's scope.
+        result = node.evaluate({ ...scope });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: `Evaluation failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    if (typeof result !== 'number') {
+        return { ok: false, error: 'Expression did not produce a number' };
+    }
+    if (Number.isNaN(result))
+        return { ok: false, error: 'Result is NaN' };
+    if (!Number.isFinite(result)) {
+        return { ok: false, error: 'Result is not finite (division by zero?)' };
+    }
+    return { ok: true, value: result };
+};
+/**
+ * The canonical numeric value a field contributes to an equation scope, or
+ * null when the field has no usable value. Select and instructions fields are
+ * non-computational (validation rejects mapping them into equations).
+ */
+export const numericFieldValue = (field, value) => {
+    switch (field.kind) {
+        case ColumnType.Number:
+        case ColumnType.Measurement:
+        case ColumnType.Angle: {
+            const v = value ?? field.defaultValue;
+            return typeof v === 'number' && Number.isFinite(v) ? v : null;
+        }
+        case ColumnType.ConversionTable: {
+            // Value is the selected conversion's label; the numeric factor comes
+            // from the matched entry (Conversion.value is a string app-wide).
+            const label = value ?? field.defaultValue;
+            if (typeof label !== 'string')
+                return null;
+            const entry = field.columnData.conversions.find((c) => c.label === label);
+            if (!entry)
+                return null;
+            const parsed = parseFloat(entry.value);
+            return Number.isFinite(parsed) ? parsed : null;
+        }
+        default:
+            return null;
+    }
+};
+const evaluateEquationInContext = (equation, ctx) => {
+    const cached = ctx.cache.get(equation.id);
+    if (cached)
+        return cached;
+    if (ctx.stack.has(equation.id)) {
+        return {
+            ok: false,
+            reason: 'error',
+            error: `Circular equation reference involving ${equation.id}`,
+        };
+    }
+    ctx.stack.add(equation.id);
+    try {
+        const scope = {};
+        const missing = [];
+        for (const [variable, fieldId] of Object.entries(equation.variableToFieldId)) {
+            const resolved = resolveFieldNumeric(fieldId, ctx);
+            if (!resolved.ok) {
+                if (resolved.reason === 'missing-inputs') {
+                    missing.push(...resolved.missingFieldIds);
+                    continue;
+                }
+                return resolved;
+            }
+            scope[variable] = resolved.value;
+        }
+        if (missing.length > 0) {
+            const result = {
+                ok: false,
+                reason: 'missing-inputs',
+                missingFieldIds: [...new Set(missing)],
+            };
+            ctx.cache.set(equation.id, result);
+            return result;
+        }
+        const evaluated = evaluateExpression(equation.expression, scope);
+        const result = evaluated.ok
+            ? { ok: true, value: evaluated.value }
+            : { ok: false, reason: 'error', error: evaluated.error };
+        ctx.cache.set(equation.id, result);
+        return result;
+    }
+    finally {
+        ctx.stack.delete(equation.id);
+    }
+};
+// An output field with an equation resolves to its COMPUTED value; if the
+// computation is blocked on missing inputs but the user supplied a value for
+// the output directly (the two-way-solving posture), the supplied value is
+// used instead. Everything else resolves from `values`/defaults.
+const resolveFieldNumeric = (fieldId, ctx) => {
+    const field = findField(ctx.definition, fieldId);
+    if (!field) {
+        return {
+            ok: false,
+            reason: 'error',
+            error: `Equation references unknown field ${fieldId}`,
+        };
+    }
+    const equation = equationForField(ctx.definition, fieldId);
+    if (equation) {
+        const computed = evaluateEquationInContext(equation, ctx);
+        if (computed.ok)
+            return computed;
+        if (computed.reason === 'missing-inputs') {
+            const supplied = numericFieldValue(field, ctx.values[fieldId]);
+            if (supplied != null)
+                return { ok: true, value: supplied };
+        }
+        return computed;
+    }
+    const value = numericFieldValue(field, ctx.values[fieldId]);
+    if (value == null) {
+        return { ok: false, reason: 'missing-inputs', missingFieldIds: [fieldId] };
+    }
+    return { ok: true, value };
+};
+/**
+ * Evaluate one equation against canonical field values. Variables referencing
+ * other output fields recurse into their equations (cycle-guarded).
+ */
+export const evaluateEquation = ({ definition, equation, values, }) => evaluateEquationInContext(equation, {
+    definition,
+    values,
+    stack: new Set(),
+    cache: new Map(),
+});
+/**
+ * Evaluate every equation in the definition. Returns a result per target
+ * field id — the live-preview / runtime "recompute all outputs" entry point.
+ */
+export const evaluateOutputs = ({ definition, values, }) => {
+    const ctx = {
+        definition,
+        values,
+        stack: new Set(),
+        cache: new Map(),
+    };
+    const results = {};
+    for (const equation of definition.equations) {
+        results[equation.targetFieldId] = evaluateEquationInContext(equation, ctx);
+    }
+    return results;
+};

package/dist/calculator/index.d.ts

@@ -0,0 +1,5 @@
+export * from './schema.js';
+export * from './units.js';
+export * from './evaluate.js';
+export * from './solve.js';
+export { calculatorDefinitionSchema, expressionSymbols, validateCalculatorDefinition, type IssueSeverity, type ValidationIssue, type ValidationResult, } from './validate.js';

package/dist/calculator/index.js

@@ -0,0 +1,9 @@
+// Construction Calculator shared module: the calculator-definition schema,
+// per-field unit system, forward evaluator, two-way numeric solver, and
+// definition validation. Pure logic (mathjs + zod only — no Skia/React), safe
+// on web, native, and Node.
+export * from './schema.js';
+export * from './units.js';
+export * from './evaluate.js';
+export * from './solve.js';
+export { calculatorDefinitionSchema, expressionSymbols, validateCalculatorDefinition, } from './validate.js';

package/dist/calculator/schema.d.ts

@@ -0,0 +1,163 @@
+import { ColumnType, type ColumnConfig, type ConversionTableColumnData, type InstructionsColumnData, type SelectColumnData, type DecimalTolerance, type FractionalTolerance } from '../types/firestore.js';
+import type { AngleUnit, CalculatorUnit, FieldDimension, MeasurementDimension } from './units.js';
+/**
+ * Version of the definition format itself. Bumped only on breaking schema
+ * changes; independent of the npm package version and of each calculator's
+ * own content `version`.
+ */
+export declare const CALCULATOR_SCHEMA_VERSION = 1;
+/**
+ * Which table a field appears in (the Figma mockup's Input Fields / Output
+ * Fields split). Mostly cosmetic: an input with solve hints can be computed
+ * from outputs at runtime, and outputs are just fields targeted by equations.
+ */
+export type FieldRole = 'input' | 'output';
+/** Field kinds reuse the app-wide ColumnType enum (calculator subset). */
+export type CalculatorFieldKind = ColumnType.Number | ColumnType.Measurement | ColumnType.Angle | ColumnType.SingleSelect | ColumnType.MultiSelect | ColumnType.ConversionTable | ColumnType.Instructions;
+export declare const CALCULATOR_FIELD_KINDS: CalculatorFieldKind[];
+/**
+ * Per-field unit configuration (templates have only a global user unit).
+ * `dimension` covers the volume-calculator case: inputs in inches, output in
+ * cubic feet — each field picks its own dimension and display units.
+ */
+export interface FieldUnitConfig {
+    dimension: MeasurementDimension;
+    /** Default display unit; must belong to `dimension`. */
+    defaultUnit: CalculatorUnit;
+    /** Units the runtime lets the user toggle between; must match `dimension`. */
+    allowedUnits: CalculatorUnit[];
+    fractionalTolerance?: FractionalTolerance;
+    decimalTolerance?: DecimalTolerance;
+}
+/**
+ * The schema half of two-way solving. A solvable field can be computed by
+ * numerically inverting its governing equation when the user supplies that
+ * equation's output value instead (see solve.ts). `min`/`max` bracket the
+ * root search in CANONICAL units; when absent the solver falls back to
+ * generous per-dimension defaults, so brackets are only needed to isolate a
+ * specific root (e.g. the positive branch of a quadratic) or to speed search.
+ */
+export interface SolveHints {
+    solvable: boolean;
+    /** The ONE equation numerically inverted for this field. */
+    governingEquationId?: string;
+    min?: number;
+    max?: number;
+    /** Optional Newton seed (canonical units). */
+    guess?: number;
+}
+/**
+ * Binds a field to a diagram hotspot. `hotspotId` is the id of the placed
+ * canvas tile — the tile itself carries the reverse link by storing the field
+ * id in `PlacedMeasurementRef.columnId` (the existing template-canvas
+ * column-anchor channel, reused with field-id semantics).
+ */
+export interface DiagramBinding {
+    hotspotId: string;
+}
+interface CalculatorFieldBase {
+    id: string;
+    name: string;
+    role: FieldRole;
+    description?: string;
+    binding?: DiagramBinding;
+}
+export type CalculatorField = CalculatorFieldBase & ({
+    kind: ColumnType.Number;
+    defaultValue?: number;
+    solve?: SolveHints;
+} | {
+    kind: ColumnType.Measurement;
+    unit: FieldUnitConfig;
+    /** Canonical (µm / µm² / µm³ per unit.dimension). */
+    defaultValue?: number;
+    solve?: SolveHints;
+} | {
+    kind: ColumnType.Angle;
+    /** Display unit; canonical storage is always degrees. */
+    angleUnit?: AngleUnit;
+    defaultValue?: number;
+    solve?: SolveHints;
+} | {
+    kind: ColumnType.SingleSelect;
+    columnData: SelectColumnData;
+    defaultValue?: string;
+} | {
+    kind: ColumnType.MultiSelect;
+    columnData: SelectColumnData;
+    defaultValue?: string[];
+} | {
+    kind: ColumnType.ConversionTable;
+    columnData: ConversionTableColumnData;
+    /** The selected conversion's label. */
+    defaultValue?: string;
+} | {
+    kind: ColumnType.Instructions;
+    columnData: InstructionsColumnData;
+});
+/**
+ * A forward equation computing one output field. Mirrors the existing
+ * `Formula` shape (`expression` + variable map), but variables bind to field
+ * ids and the equation lives inside the definition rather than in the org
+ * `formulas` collection. Variables may reference other OUTPUT fields — their
+ * equations are evaluated recursively (cycles are rejected by validation).
+ */
+export interface CalculatorEquation {
+    id: string;
+    /** The output field this equation computes. */
+    targetFieldId: string;
+    /** math.js forward expression, e.g. 'A * B * C'. */
+    expression: string;
+    /** Variable letter -> field id. */
+    variableToFieldId: Record<string, string>;
+}
+/** A runtime/preview value for one field, in canonical units. */
+export type CalculatorFieldValue = number | string | string[] | null;
+export type CalculatorValues = Record<string, CalculatorFieldValue>;
+export interface CalculatorDefinition {
+    id: string;
+    /** CALCULATOR_SCHEMA_VERSION captured at author time. */
+    schemaVersion: number;
+    /** Monotonic content revision; bumped on publish. Offline-cache key with updatedAt. */
+    version: number;
+    name: string;
+    description: string;
+    folderId: string | null;
+    /** Inputs + outputs in one list, discriminated by `role`. */
+    fields: CalculatorField[];
+    equations: CalculatorEquation[];
+    /** Diagram file (files subcollection doc carrying the Skia canvas). */
+    diagramFileId?: string | null;
+    /** Public calculators are readable by everyone; rules/query key. */
+    isPublic: boolean;
+    sharedUserIds?: string[];
+    sharedOrgIds?: string[];
+    createdBy?: {
+        userId: string;
+        firstName?: string;
+        lastName?: string;
+    };
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+export declare const fieldsByRole: (definition: Pick<CalculatorDefinition, "fields">, role: FieldRole) => CalculatorField[];
+export declare const findField: (definition: Pick<CalculatorDefinition, "fields">, fieldId: string) => CalculatorField | undefined;
+export declare const findEquation: (definition: Pick<CalculatorDefinition, "equations">, equationId: string) => CalculatorEquation | undefined;
+/** The equation targeting an output field, if any. */
+export declare const equationForField: (definition: Pick<CalculatorDefinition, "equations">, fieldId: string) => CalculatorEquation | undefined;
+/** The dimension a field's numeric value carries. */
+export declare const fieldDimension: (field: CalculatorField) => FieldDimension;
+/** Fields whose value participates in equations as a number. */
+export declare const isNumericFieldKind: (kind: CalculatorFieldKind) => kind is ColumnType.Number | ColumnType.Measurement | ColumnType.Angle | ColumnType.ConversionTable;
+/** Field kinds an equation may target (compute into). */
+export declare const isEquationTargetKind: (kind: CalculatorFieldKind) => kind is ColumnType.Number | ColumnType.Measurement | ColumnType.Angle;
+/**
+ * Synthesize a ColumnConfig for a field so the existing table/tile components
+ * (built around ColumnConfig) can render calculator fields unchanged.
+ */
+export declare const fieldToColumnConfig: (field: CalculatorField) => ColumnConfig;
+/** Default per-field unit config for a fresh measurement field. */
+export declare const defaultFieldUnitConfig: (dimension?: MeasurementDimension) => FieldUnitConfig;
+/** Seed for the create-new-calculator stub doc (mirrors the template flow). */
+export declare const createEmptyCalculatorDefinition: (id: string) => Omit<CalculatorDefinition, "createdAt" | "updatedAt" | "createdBy">;
+export {};