@reekon-tools/boldr-utils 1.9.6 → 1.10.1

package/dist/calculator/schema.js

@@ -1,5 +1,6 @@
 import { ColumnType, Units, } from '../types/firestore.js';
-import { unitsForDimension } from './units.js';
+import { unitForBase, unitsForDimension } from './units.js';
+import { conversionColumnDimension, resolveConversionColumn, } from './conversionTable.js';
 // ---------------------------------------------------------------------------
 // The Construction Calculator definition — the shared artifact the web
 // authoring tool produces, the mobile runtime interprets, and sync ships.
@@ -59,6 +60,31 @@ export const fieldDimension = (field) => {
             return 'none';
     }
 };
+/** The binding for one variable letter, or null when the letter is unmapped. */
+export const equationBinding = (equation, variable) => {
+    const fieldId = equation.variableToFieldId[variable];
+    if (fieldId == null)
+        return null;
+    const columnId = equation.variableColumnIds?.[variable];
+    return columnId != null ? { fieldId, columnId } : { fieldId };
+};
+/** Every variable's binding, in the variable map's order. */
+export const equationBindings = (equation) => Object.keys(equation.variableToFieldId).map((variable) => ({
+    variable,
+    fieldId: equation.variableToFieldId[variable],
+    ...(equation.variableColumnIds?.[variable] != null
+        ? { columnId: equation.variableColumnIds[variable] }
+        : {}),
+}));
+/**
+ * The dimension a BOUND value carries. Same as `fieldDimension` for every kind
+ * but a conversion table, where a column may declare a unit and so give the
+ * binding a real dimension — the thing that lets `width · depth` off one table
+ * row infer as an area rather than a bare product.
+ */
+export const bindingDimension = (field, columnId) => field.kind === ColumnType.ConversionTable
+    ? conversionColumnDimension(resolveConversionColumn(field.columnData, columnId))
+    : fieldDimension(field);
 /**
  * The unit a field's value is entered and displayed in, or null for fields
  * that carry no unit. Also the unit an equation referencing the field starts
@@ -74,6 +100,40 @@ export const fieldDefaultUnit = (field) => {
             return null;
     }
 };
+/**
+ * The unit a BOUND value is DECLARED in — the conversion column's unit for a
+ * table binding (the unit the cell text was typed in), the field's display
+ * unit otherwise. This is what the value means at rest, not what it means
+ * inside an equation; `bindingUnitForBase` converts it to the latter.
+ */
+export const bindingDefaultUnit = (field, columnId) => field.kind === ColumnType.ConversionTable
+    ? (resolveConversionColumn(field.columnData, columnId).unit ?? null)
+    : fieldDefaultUnit(field);
+/**
+ * The unit a bound value enters a base-anchored equation's scope in — the
+ * base's member at the binding's own exponent, so a length arrives in `ft` and
+ * an area off the same equation in `ft²`.
+ *
+ * Never an author choice, and deliberately independent of how the value is
+ * declared or displayed: a column typed in ft² feeding an inch-based equation
+ * converts to in², which is a lossless re-expression of the same quantity, not
+ * a reinterpretation of the author's cell text. Returns null for dimensionless
+ * bindings, which enter the scope raw.
+ */
+export const bindingUnitForBase = (base, field, columnId) => {
+    const dimension = bindingDimension(field, columnId);
+    switch (dimension) {
+        case 'none':
+            return null;
+        // Trig in equations runs in DEGREES (see evaluate.ts), so angles enter the
+        // scope as degrees whatever the base — and degrees are already canonical,
+        // making this conversion a no-op that exists for uniformity.
+        case 'angle':
+            return 'deg';
+        default:
+            return unitForBase(base, dimension);
+    }
+};
 /** Fields whose value participates in equations as a number. */
 export const isNumericFieldKind = (kind) => kind === ColumnType.Number ||
     kind === ColumnType.Measurement ||

package/dist/calculator/units.d.ts

@@ -28,6 +28,33 @@ export declare const CALCULATOR_UNIT_INFO: Record<CalculatorUnit, CalculatorUnit
 /** The math.js token for a dimension's canonical unit. '' for dimensionless. */
 export declare const canonicalMathUnit: (dimension: FieldDimension) => string;
 export declare const unitDimension: (unit: CalculatorUnit) => FieldDimension;
+/** The math.js base token a unit reduces to: 'sq_ft' -> 'ft', 'in_frac' -> 'in'. */
+export declare const unitBase: (unit: CalculatorUnit) => string;
+/**
+ * Base + length exponent -> the unit that names it. Yards have no length entry
+ * (the `Units` enum has no yard) and liters/gallons no length base at all, so
+ * both simply fail to name a unit rather than guessing.
+ */
+export declare const UNIT_BY_BASE: Record<string, Partial<Record<number, CalculatorUnit>>>;
+/**
+ * A base an equation may evaluate in. Only bases that name a unit at EVERY
+ * length exponent qualify — an equation in yards could not express a plain
+ * yard length, and liters/gallons aren't a length family at all. Both remain
+ * perfectly usable as field/column units; they just get converted into the
+ * equation's base like anything else.
+ */
+export type EquationBase = 'mm' | 'cm' | 'm' | 'in' | 'ft';
+export declare const EQUATION_BASES: EquationBase[];
+export declare const isEquationBase: (value: unknown) => value is EquationBase;
+/** Length factors per dimension — an area is two lengths, a volume three. */
+export declare const LENGTH_EXPONENT: Record<MeasurementDimension, 1 | 2 | 3>;
+/** The unit naming `base` at a measurement dimension, e.g. ('ft','area') -> 'sq_ft'. */
+export declare const unitForBase: (base: EquationBase, dimension: MeasurementDimension) => CalculatorUnit | null;
+/**
+ * The equation base a unit belongs to, or null for units outside the five
+ * anchorable families (yd², liters, gallons, degrees, radians).
+ */
+export declare const equationBaseOfUnit: (unit: CalculatorUnit) => EquationBase | null;
 export declare const unitsForDimension: (dimension: FieldDimension) => CalculatorUnit[];
 /**
  * A unit's token and its disambiguating qualifier as separate pieces. The

package/dist/calculator/units.js

@@ -68,6 +68,53 @@ export const canonicalMathUnit = (dimension) => {
     }
 };
 export const unitDimension = (unit) => CALCULATOR_UNIT_INFO[unit]?.dimension ?? 'none';
+// ---------------------------------------------------------------------------
+// Equation bases
+//
+// An equation evaluates in ONE length base (see CalculatorEquation.base). The
+// base names a family — `ft` covers ft, ft², ft³ — and each variable's scope
+// unit is that family's member at the variable's own exponent. This is what
+// makes `(A * B) / C` meaningful: A and B arrive in ft, C in ft², and the
+// ratio is a true dimensionless count rather than a number that happens to
+// divide.
+//
+// Angles are a SEPARATE axis and never participate: the evaluator's trig runs
+// in degrees, so angle values always enter the scope as degrees regardless of
+// the base.
+// ---------------------------------------------------------------------------
+/** The math.js base token a unit reduces to: 'sq_ft' -> 'ft', 'in_frac' -> 'in'. */
+export const unitBase = (unit) => (CALCULATOR_UNIT_INFO[unit]?.mathUnit ?? '').split('^')[0];
+/**
+ * Base + length exponent -> the unit that names it. Yards have no length entry
+ * (the `Units` enum has no yard) and liters/gallons no length base at all, so
+ * both simply fail to name a unit rather than guessing.
+ */
+export const UNIT_BY_BASE = {
+    mm: { 1: Units.Millimeters, 2: 'sq_mm', 3: 'cu_mm' },
+    cm: { 1: Units.Centimeters, 2: 'sq_cm', 3: 'cu_cm' },
+    m: { 1: Units.Meters, 2: 'sq_m', 3: 'cu_m' },
+    in: { 1: Units.Inches, 2: 'sq_in', 3: 'cu_in' },
+    ft: { 1: Units.Feet, 2: 'sq_ft', 3: 'cu_ft' },
+    yd: { 2: 'sq_yd', 3: 'cu_yd' },
+};
+export const EQUATION_BASES = ['mm', 'cm', 'm', 'in', 'ft'];
+export const isEquationBase = (value) => typeof value === 'string' && EQUATION_BASES.includes(value);
+/** Length factors per dimension — an area is two lengths, a volume three. */
+export const LENGTH_EXPONENT = {
+    length: 1,
+    area: 2,
+    volume: 3,
+};
+/** The unit naming `base` at a measurement dimension, e.g. ('ft','area') -> 'sq_ft'. */
+export const unitForBase = (base, dimension) => UNIT_BY_BASE[base]?.[LENGTH_EXPONENT[dimension]] ?? null;
+/**
+ * The equation base a unit belongs to, or null for units outside the five
+ * anchorable families (yd², liters, gallons, degrees, radians).
+ */
+export const equationBaseOfUnit = (unit) => {
+    const base = unitBase(unit);
+    return isEquationBase(base) ? base : null;
+};
 export const unitsForDimension = (dimension) => Object.keys(CALCULATOR_UNIT_INFO).filter((u) => CALCULATOR_UNIT_INFO[u].dimension === dimension);
 /**
  * A unit's token and its disambiguating qualifier as separate pieces. The

package/dist/calculator/validate.d.ts

@@ -121,7 +121,13 @@ export declare const calculatorDefinitionSchema: z.ZodObject<{
             conversions: z.ZodArray<z.ZodObject<{
                 label: z.ZodString;
                 value: z.ZodString;
+                values: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             }, z.core.$strip>>;
+            columns: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                name: z.ZodString;
+                unit: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
         }, z.core.$strip>;
         defaultValue: z.ZodOptional<z.ZodString>;
         id: z.ZodString;
@@ -157,6 +163,14 @@ export declare const calculatorDefinitionSchema: z.ZodObject<{
         targetFieldId: z.ZodString;
         expression: z.ZodString;
         variableToFieldId: z.ZodRecord<z.ZodString, z.ZodString>;
+        variableColumnIds: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        base: z.ZodOptional<z.ZodEnum<{
+            in: "in";
+            ft: "ft";
+            m: "m";
+            mm: "mm";
+            cm: "cm";
+        }>>;
         variableUnits: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         resultUnit: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;

package/dist/calculator/validate.js

@@ -1,8 +1,9 @@
 import { z } from 'zod';
 import { ColumnType, DecimalTolerance, FractionalTolerance, } from '../types/firestore.js';
-import { CALCULATOR_SCHEMA_VERSION, equationForField, fieldDimension, isEquationTargetKind, isNumericFieldKind, } from './schema.js';
-import { CALCULATOR_UNIT_INFO, unitDimension, } from './units.js';
-import { MATHJS_CONSTANTS, inferExpressionUnit, isEquivalentUnit, parseExpression, producesCanonicalValue, unitScaleRatio, } from './expressionUnits.js';
+import { CALCULATOR_SCHEMA_VERSION, bindingDimension, equationForField, fieldDimension, isEquationTargetKind, isNumericFieldKind, } from './schema.js';
+import { conversionBindingLabel, conversionCellValue, conversionColumnLabel, conversionColumns, findConversionColumn, hasMultipleConversionColumns, } from './conversionTable.js';
+import { CALCULATOR_UNIT_INFO, EQUATION_BASES, isEquationBase, unitDimension, } from './units.js';
+import { MATHJS_CONSTANTS, deriveVariableUnits, inferExpressionUnit, isEquivalentUnit, parseExpression, producesCanonicalValue, unitScaleRatio, } from './expressionUnits.js';
 import { isCalculatorCategoryId } from './categories.js';
 // ---------------------------------------------------------------------------
 // Definition validation: zod for structure, plus the cross-field invariants
@@ -36,7 +37,18 @@ const fieldBase = {
 };
 const selectColumnDataSchema = z.object({ options: z.array(z.string()) });
 const conversionTableColumnDataSchema = z.object({
-    conversions: z.array(z.object({ label: z.string(), value: z.string() })),
+    conversions: z.array(z.object({
+        label: z.string(),
+        value: z.string(),
+        values: z.record(z.string(), z.string()).optional(),
+    })),
+    columns: z
+        .array(z.object({
+        id: z.string().min(1),
+        name: z.string(),
+        unit: calculatorUnitSchema.optional(),
+    }))
+        .optional(),
 });
 const instructionsColumnDataSchema = z.object({
     text: z.string(),
@@ -93,6 +105,8 @@ const calculatorEquationSchema = z.object({
     targetFieldId: z.string().min(1),
     expression: z.string().min(1),
     variableToFieldId: z.record(z.string(), z.string()),
+    variableColumnIds: z.record(z.string(), z.string()).optional(),
+    base: z.enum(EQUATION_BASES).optional(),
     variableUnits: z.record(z.string(), calculatorUnitSchema).optional(),
     resultUnit: calculatorUnitSchema.optional(),
 });
@@ -163,6 +177,12 @@ const DIMENSION_LABELS = {
     none: 'a plain number',
 };
 const describeDimension = (dimension) => DIMENSION_LABELS[dimension];
+// How a message names what a variable is bound to. A multi-column conversion
+// table needs the column too — "maps to Lumber" is useless when the author has
+// three columns and only one of them is wrong.
+const describeBinding = (field, columnId) => field.kind === ColumnType.ConversionTable
+    ? `"${conversionBindingLabel(field.name, field.columnData, columnId)}"`
+    : `"${field.name}"`;
 // 1728 stays 1728; 57.29577951308232 becomes 57.3.
 const trimRatio = (ratio) => Number.isInteger(ratio) ? String(ratio) : ratio.toFixed(1);
 // Does `equation` depend on `fieldId`, directly or through the equations of
@@ -259,9 +279,37 @@ export const validateCalculatorDefinition = (input) => {
             if (conversions.length === 0) {
                 push('empty-conversions', `${path}.columnData.conversions`, 'Conversion table is empty');
             }
+            // An explicit `columns` array is only ever written by the multi-column
+            // editor; a single-column table has none and normalizes to the implicit
+            // column, so these checks are no-ops for every table authored before now.
+            const columns = conversionColumns(field.columnData);
+            const columnIds = new Set();
+            columns.forEach((column, j) => {
+                if (columnIds.has(column.id)) {
+                    push('duplicate-conversion-column-id', `${path}.columnData.columns.${j}.id`, `Duplicate conversion column id "${column.id}"`);
+                }
+                columnIds.add(column.id);
+            });
+            const columnNames = columns
+                .map((c) => c.name.trim())
+                .filter((n) => n !== '');
+            const dupeNames = columnNames.filter((n, j) => columnNames.indexOf(n) !== j);
+            if (dupeNames.length > 0) {
+                push('duplicate-conversion-column-names', `${path}.columnData.columns`, `Two value columns are both called ${[...new Set(dupeNames)].map((n) => `"${n}"`).join(', ')} — formula chips for them will be indistinguishable`, 'warning');
+            }
             conversions.forEach((c, j) => {
-                if (!Number.isFinite(parseFloat(c.value))) {
-                    push('conversion-value-not-numeric', `${path}.columnData.conversions.${j}.value`, `Conversion "${c.label}" has non-numeric value "${c.value}"`);
+                for (const column of columns) {
+                    const cell = conversionCellValue(field.columnData, c, column.id);
+                    if (Number.isFinite(parseFloat(cell)))
+                        continue;
+                    // Path stays on `.value` for the implicit/first column so existing
+                    // consumers of this issue path keep resolving to the same input.
+                    const cellPath = column.id === columns[0].id
+                        ? `${path}.columnData.conversions.${j}.value`
+                        : `${path}.columnData.conversions.${j}.values.${column.id}`;
+                    push('conversion-value-not-numeric', cellPath, columns.length > 1
+                        ? `Conversion "${c.label}" has a non-numeric value "${cell}" in column "${conversionColumnLabel(field.columnData, column.id)}"`
+                        : `Conversion "${c.label}" has non-numeric value "${cell}"`);
                 }
             });
             const labels = conversions.map((c) => c.label);
@@ -298,10 +346,39 @@ export const validateCalculatorDefinition = (input) => {
             else if (!isNumericFieldKind(mapped.kind)) {
                 push('non-numeric-mapped-field', `${path}.variableToFieldId.${variable}`, `Variable ${variable} maps to "${mapped.name}", which has no numeric value`);
             }
+            else if (mapped.kind === ColumnType.ConversionTable &&
+                hasMultipleConversionColumns(mapped.columnData) &&
+                eq.variableColumnIds?.[variable] == null) {
+                // Not an error: the evaluator reads the first column, which is what
+                // this binding meant before the table grew a second one. But it is
+                // very likely not what the author now wants, so say so.
+                push('conversion-column-unspecified', `${path}.variableToFieldId.${variable}`, `Variable ${variable} maps to "${mapped.name}", which has ${conversionColumns(mapped.columnData).length} value columns, but names none — it reads "${conversionColumnLabel(mapped.columnData)}". Re-insert the chip for the column you want.`, 'warning');
+            }
             if (fieldId === eq.targetFieldId) {
                 push('self-referencing-equation', `${path}.variableToFieldId.${variable}`, `Equation for "${eq.targetFieldId}" references its own target`);
             }
         }
+        // --- Column bindings ---------------------------------------------------
+        for (const [variable, columnId] of Object.entries(eq.variableColumnIds ?? {})) {
+            const columnPath = `${path}.variableColumnIds.${variable}`;
+            const mappedId = eq.variableToFieldId[variable];
+            if (mappedId == null) {
+                push('column-for-unmapped-variable', columnPath, `Variable ${variable} names a conversion column but has no field mapping`, 'warning');
+                continue;
+            }
+            const mapped = fieldById.get(mappedId);
+            if (!mapped)
+                continue; // unknown-mapped-field already reported above
+            if (mapped.kind !== ColumnType.ConversionTable) {
+                push('column-on-non-conversion-field', columnPath, `Variable ${variable} names a conversion column but maps to "${mapped.name}", which is not a conversion table`, 'warning');
+                continue;
+            }
+            if (!findConversionColumn(mapped.columnData, columnId)) {
+                // The evaluator falls back to the first column, so the equation still
+                // computes — with a value the author never asked for. An error.
+                push('unknown-conversion-column', columnPath, `Variable ${variable} reads column "${columnId}" of "${mapped.name}", which no longer exists — it will fall back to "${conversionColumnLabel(mapped.columnData)}"`);
+            }
+        }
         // --- Unit annotations --------------------------------------------------
         for (const [variable, unit] of Object.entries(eq.variableUnits ?? {})) {
             const unitPath = `${path}.variableUnits.${variable}`;
@@ -313,18 +390,27 @@ export const validateCalculatorDefinition = (input) => {
             const mapped = fieldById.get(mappedId);
             if (!mapped)
                 continue; // unknown-mapped-field already reported above
-            const dim = fieldDimension(mapped);
+            const columnId = eq.variableColumnIds?.[variable];
+            const boundName = describeBinding(mapped, columnId);
+            const dim = bindingDimension(mapped, columnId);
             if (dim === 'none') {
-                push('variable-unit-on-dimensionless-field', unitPath, `Variable ${variable} maps to "${mapped.name}", which has no unit dimension`);
+                push('variable-unit-on-dimensionless-field', unitPath, `Variable ${variable} maps to ${boundName}, which has no unit dimension`);
             }
             else if (unitDimension(unit) !== dim) {
-                push('variable-unit-dimension-mismatch', unitPath, `Unit "${unit}" is not a ${dim} unit (variable ${variable} maps to "${mapped.name}")`);
+                push('variable-unit-dimension-mismatch', unitPath, `Unit "${unit}" is not a ${dim} unit (variable ${variable} maps to ${boundName})`);
             }
         }
         // The unit the EXPRESSION produces, which is what `resultUnit` claims to
         // be. Hoisted out of the `target` branch because the number-target check
         // further down needs it too.
-        const inferred = inferExpressionUnit(def.fields, eq);
+        //
+        // Inferred from what the equation will ACTUALLY evaluate with: for a
+        // base-anchored equation that is the derived units, not whatever the
+        // document stores. Otherwise a stale cache would make every check below
+        // reason about units the evaluator is going to ignore.
+        const inferred = inferExpressionUnit(def.fields, isEquationBase(eq.base)
+            ? { ...eq, variableUnits: deriveVariableUnits(eq.base, def.fields, eq) }
+            : eq);
         if (target) {
             const dim = fieldDimension(target);
             if (eq.resultUnit != null) {
@@ -349,6 +435,11 @@ export const validateCalculatorDefinition = (input) => {
                 if (inferred.dimension !== dim) {
                     push('expression-dimension-mismatch', `${path}.expression`, `Expression produces ${describeDimension(inferred.dimension)} but "${target.name}" is ${describeDimension(dim)} — check the variable units and the expression`);
                 }
+                else if (isEquationBase(eq.base)) {
+                    // Derived from the base at evaluation time, so it can be neither
+                    // missing nor mis-scaled — the two checks below exist only for the
+                    // pre-base form, where the result unit was an unverified assertion.
+                }
                 else if (eq.resultUnit == null) {
                     if (!producesCanonicalValue(inferred)) {
                         push('missing-result-unit', `${path}.resultUnit`, `Expression produces a value in ${inferred.unit ? `"${inferred.unit}"` : inferred.bases.join('/')} but no result unit is set, so it will be stored as a canonical value. Set the result unit${inferred.unit ? ` to "${inferred.unit}"` : ''}.`);
@@ -366,8 +457,24 @@ export const validateCalculatorDefinition = (input) => {
                     push('result-unit-scale-mismatch', `${path}.resultUnit`, `Expression produces "${inferred.unit}" but the result unit is "${eq.resultUnit}" — computed values will be ${off}. Use "${inferred.unit}", or change the variable units to match.`);
                 }
             }
-            if (inferred.ok && inferred.bases.length > 1) {
-                push('mixed-base-units', `${path}.variableUnits`, `Variables mix ${inferred.bases.join(' and ')} in one expression, so the result has no single unit. Put them all in the same unit.`, 'warning');
+            // Base-anchored equations cannot mix bases — every unit comes from the
+            // one base — so this only ever fires on the pre-base authored form.
+            //
+            // Checked PER AXIS. A length and an angle in one expression is ordinary
+            // (trig consumes the angle and hands back a ratio); two length bases
+            // never is. And read off `lengthBases`/`angleBases` rather than `bases`,
+            // because `bases` describes the result: `(A_in * B_in) / C_ft²` cancels
+            // to a dimensionless count, leaving `bases` empty and the 144× scale
+            // error it carries completely invisible here.
+            if (inferred.ok && !isEquationBase(eq.base)) {
+                for (const [axis, axisBases] of [
+                    ['length', inferred.lengthBases],
+                    ['angle', inferred.angleBases],
+                ]) {
+                    if (axisBases.length < 2)
+                        continue;
+                    push('mixed-base-units', `${path}.variableUnits`, `Variables mix ${axisBases.join(' and ')} in one expression, so ${axis === 'length' ? 'lengths' : 'angles'} of different scales are being combined as if they were the same — the result is silently off by a fixed factor. Put them all in one unit, or set the equation's base.`);
+                }
             }
             if (!inferred.ok && inferred.reason === 'inconsistent-terms') {
                 push('expression-mixed-dimensions', `${path}.expression`, 'Expression adds or compares terms of different dimensions (a length and an area, say) — one of them is probably the wrong field', 'warning');
@@ -390,14 +497,21 @@ export const validateCalculatorDefinition = (input) => {
         // authoring where a µm-scale value in a unitless field is intended, and
         // nothing gates on `ok`: mobile only console.warns in __DEV__, and the
         // web editor shows the banner without blocking save.
+        //
+        // Cannot happen once an equation has a base: every dimensioned binding
+        // gets a unit derived from it, so there is no way for a canonical value to
+        // reach the scope. Skipped rather than left to read the absent
+        // `variableUnits` and report every variable as unitless.
         if (target?.kind === ColumnType.Number &&
+            !isEquationBase(eq.base) &&
             (!inferred.ok || inferred.dimension !== 'none')) {
             for (const [variable, fieldId] of Object.entries(eq.variableToFieldId)) {
                 const mapped = fieldById.get(fieldId);
-                if (!mapped || fieldDimension(mapped) === 'none')
+                const columnId = eq.variableColumnIds?.[variable];
+                if (!mapped || bindingDimension(mapped, columnId) === 'none')
                     continue;
                 if (eq.variableUnits?.[variable] == null) {
-                    push('canonical-value-into-number-target', `${path}.variableToFieldId.${variable}`, `"${target.name}" is a number field, so it shows the raw result — but variable ${variable} ("${mapped.name}") has no display unit, so it arrives as a canonical µm-scale value and the result will be off by a large factor. Pick a unit for ${variable}.`);
+                    push('canonical-value-into-number-target', `${path}.variableToFieldId.${variable}`, `"${target.name}" is a number field, so it shows the raw result — but variable ${variable} (${describeBinding(mapped, columnId)}) has no display unit, so it arrives as a canonical µm-scale value and the result will be off by a large factor. Pick a unit for ${variable}.`);
                 }
             }
         }

package/dist/types/firestore.d.ts

@@ -1,4 +1,5 @@
 import type { AnnotationCanvasState } from './annotation.js';
+import type { CalculatorUnit } from '../calculator/units.js';
 interface FirestoreDoc {
     id: string;
 }
@@ -277,9 +278,40 @@ export interface Formula extends FirestoreDoc, Timestamps {
     variables: string[];
     variableToColumnMap: Record<string, any>;
 }
+/**
+ * One VALUE column of a conversion table. A table with more than one column
+ * lets a single row selection carry several numbers at once ("2x4" -> actual
+ * width 1.5 in AND actual depth 3.5 in), each addressable from an equation.
+ *
+ * `unit` is what the cell text is written in. Without it a cell is a plain
+ * scalar (the pre-multi-column meaning of `Conversion.value`); with it, the
+ * cell is converted to the canonical value for that unit's dimension before
+ * it reaches an equation, exactly like a measurement field — which is what
+ * lets `width * depth` on a conversion table produce a real area instead of a
+ * dimensionless product. See calculator/conversionTable.ts.
+ */
+export interface ConversionColumn {
+    /** Stable; referenced by CalculatorEquation.variableColumnIds. */
+    id: string;
+    /** Author-facing; may be blank, in which case UIs fall back to `[i]`. */
+    name: string;
+    unit?: CalculatorUnit;
+}
 export interface Conversion {
     label: string;
+    /**
+     * The FIRST column's value. Not merely a legacy alias: it is where column 0
+     * lives, full stop. Every reader that predates multi-column tables (job
+     * grids, label tiles, template formulas) reads this key, so column 0 stays
+     * here rather than moving into `values` and going dark for them.
+     */
     value: string;
+    /**
+     * Values for columns 1..n, keyed by `ConversionColumn.id`. Absent for a
+     * single-column table. Read through `conversionCellValue` rather than
+     * indexing this directly — it owns the column-0-lives-in-`value` rule.
+     */
+    values?: Record<string, string>;
 }
 export interface FormulaColumnData {
     formulaId: string;
@@ -290,6 +322,13 @@ export interface SelectColumnData {
 }
 export interface ConversionTableColumnData {
     conversions: Conversion[];
+    /**
+     * Value columns in display order. Absent means the single implicit column
+     * backed by `Conversion.value` — the shape every table written before
+     * multi-column support has, and still the shape of a one-column table
+     * authored today. `conversionColumns()` normalizes both.
+     */
+    columns?: ConversionColumn[];
 }
 export interface InstructionsColumnData {
     text: string;
@@ -445,8 +484,8 @@ export declare enum Units {
     FeetInchesDecimal = "ft_in_decimal",
     FeetInchesFractional = "ft_in_frac"
 }
-export declare const convertUnitsToReadable: (targetUnit: Units) => "cm" | "mm" | "m" | "in" | "ft" | "in (fractional)" | "ft-in (decimal)" | "ft-in (fractional)" | null;
-export declare const convertUnitsToReadableShort: (targetUnit: Units) => "cm" | "mm" | "m" | "in" | "ft" | "ft-in";
+export declare const convertUnitsToReadable: (targetUnit: Units) => "in" | "ft" | "m" | "mm" | "cm" | "in (fractional)" | "ft-in (decimal)" | "ft-in (fractional)" | null;
+export declare const convertUnitsToReadableShort: (targetUnit: Units) => "in" | "ft" | "m" | "mm" | "cm" | "ft-in";
 export declare enum FractionalTolerance {
     Fourth = "4",
     Eighth = "8",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reekon-tools/boldr-utils",
-  "version": "1.9.6",
+  "version": "1.10.1",
   "description": "Shared utilities for formulas and measurement conversion used in Reekon apps",
   "author": "REEKON Tools",
   "license": "MIT",