@reekon-tools/boldr-utils 1.9.6 → 1.10.0

package/dist/calculator/conversionTable.d.ts

@@ -0,0 +1,81 @@
+import type { Conversion, ConversionColumn, ConversionTableColumnData } from '../types/firestore.js';
+import { type FieldDimension } from './units.js';
+/**
+ * Id of the implicit first column. Stable and reserved: a table that has never
+ * been given explicit columns is addressed by this id, so equations written
+ * against a single-column table keep resolving after columns are added (the
+ * editor preserves it as `columns[0].id`).
+ */
+export declare const DEFAULT_CONVERSION_COLUMN_ID = "value";
+/** Name shown for the implicit first column. */
+export declare const DEFAULT_CONVERSION_COLUMN_NAME = "Value";
+/**
+ * A table's value columns, always at least one. An absent or empty `columns`
+ * normalizes to the single implicit column, so callers never branch on shape.
+ */
+export declare const conversionColumns: (data: Pick<ConversionTableColumnData, "columns">) => ConversionColumn[];
+/** True when equations must name a column to be unambiguous. */
+export declare const hasMultipleConversionColumns: (data: Pick<ConversionTableColumnData, "columns">) => boolean;
+/**
+ * The column an equation variable binds to. An absent/unknown `columnId` is the
+ * first column: that is what a binding written before multi-column tables
+ * meant, and the only reading that keeps such equations computing.
+ */
+export declare const resolveConversionColumn: (data: Pick<ConversionTableColumnData, "columns">, columnId?: string) => ConversionColumn;
+export declare const findConversionColumn: (data: Pick<ConversionTableColumnData, "columns">, columnId: string) => ConversionColumn | undefined;
+/** Raw cell text for one row/column, or '' when the cell was never filled. */
+export declare const conversionCellValue: (data: Pick<ConversionTableColumnData, "columns">, conversion: Conversion, columnId: string) => string;
+/**
+ * `conversion` with one cell replaced, honouring the column-0-in-`value` rule.
+ * Returns a new object; `values` is omitted entirely when it would be empty so
+ * Firestore never receives a stray `{}`.
+ */
+export declare const writeConversionCell: (data: Pick<ConversionTableColumnData, "columns">, conversion: Conversion, columnId: string, cell: string) => Conversion;
+/** The dimension a column's values carry — 'none' for an unannotated column. */
+export declare const conversionColumnDimension: (column: ConversionColumn) => FieldDimension;
+/**
+ * The CANONICAL number a cell contributes to an equation, or null when the
+ * cell is blank or unparseable. Unit-less columns pass their value through
+ * unchanged (the historical meaning of a conversion factor); a column with a
+ * unit converts, so downstream code can treat it like any measurement value.
+ */
+export declare const conversionCellNumber: (data: Pick<ConversionTableColumnData, "columns">, conversion: Conversion, columnId?: string) => number | null;
+/** The row a selected label refers to. */
+export declare const findConversionRow: (data: Pick<ConversionTableColumnData, "conversions">, label: string) => Conversion | undefined;
+/**
+ * How a column is named in a chip, a picker or a validation message. Falls back
+ * to the positional `[i]` form the column is otherwise anonymous — an unnamed
+ * column still has to be tellable apart from its neighbours.
+ */
+export declare const conversionColumnLabel: (data: Pick<ConversionTableColumnData, "columns">, columnId?: string) => string;
+/**
+ * Qualified name for a binding — what the formula builder puts on a chip and
+ * what validation quotes back. Single-column tables read as the bare field
+ * name, so nothing changes for the tables that already exist.
+ */
+export declare const conversionBindingLabel: (fieldName: string, data: Pick<ConversionTableColumnData, "columns">, columnId?: string) => string;
+export interface ConversionRowDraft {
+    label: string;
+    /** Cell text per column id. Missing entries are treated as blank. */
+    cells: Record<string, string>;
+}
+/**
+ * Serialize an editor's (columns, rows) working state into storage shape.
+ * The single place the column-0 split is applied on write, and the reason the
+ * editor can add, rename, unit-annotate, reorder and delete columns without
+ * ever reasoning about which key a cell belongs in.
+ *
+ * A table whose only column is the plain implicit one is written WITHOUT a
+ * `columns` key, so it stays byte-identical to what the pre-multi-column editor
+ * produced — no schema churn on every table that doesn't use the feature. A
+ * single column that has been named or given a unit IS persisted: dropping it
+ * would silently discard the annotation.
+ */
+export declare const buildConversionTableColumnData: (columns: ConversionColumn[], rows: ConversionRowDraft[]) => ConversionTableColumnData;
+/** Storage shape back to editor working state. */
+export declare const toConversionRowDrafts: (data: ConversionTableColumnData) => ConversionRowDraft[];
+/** Convenience for pickers: every column's cell text for one row. */
+export declare const conversionRowCells: (data: ConversionTableColumnData, conversion: Conversion) => {
+    column: ConversionColumn;
+    value: string;
+}[];

package/dist/calculator/conversionTable.js

@@ -0,0 +1,170 @@
+import { toCanonical, unitDimension, } from './units.js';
+// ---------------------------------------------------------------------------
+// Multi-column conversion tables.
+//
+// A conversion table is a labelled lookup: the operator picks a ROW ("2x4",
+// "30-year architectural") and the calculator gets a number. With more than one
+// VALUE COLUMN, one selection carries several numbers — nominal vs. actual
+// dimensions, weight and price per unit, rise and run — and an equation binds
+// to a specific (field, column) pair rather than just the field.
+//
+// STORAGE (see types/firestore.ts): column 0's cell text lives in
+// `Conversion.value`, columns 1..n in `Conversion.values[columnId]`. That split
+// is not tidiness — `value` is the only key readers that predate this feature
+// know about (job grids, label tiles, template formulas), so keeping column 0
+// there means a table authored in a calculator still reads correctly
+// everywhere else. Nothing outside this module should apply the rule by hand:
+// go through `conversionCellValue` / `writeConversionCell`.
+//
+// UNITS: a column may declare the unit its cell text is written in. Cells then
+// convert to canonical (µm/µm²/µm³/deg) on the way into an equation, so a
+// column of inch values composes with measurement fields and with the unit
+// inference in expressionUnits.ts. A column with no unit stays a plain scalar,
+// which is exactly what a single-column table has always been.
+// ---------------------------------------------------------------------------
+/**
+ * Id of the implicit first column. Stable and reserved: a table that has never
+ * been given explicit columns is addressed by this id, so equations written
+ * against a single-column table keep resolving after columns are added (the
+ * editor preserves it as `columns[0].id`).
+ */
+export const DEFAULT_CONVERSION_COLUMN_ID = 'value';
+/** Name shown for the implicit first column. */
+export const DEFAULT_CONVERSION_COLUMN_NAME = 'Value';
+const IMPLICIT_COLUMN = {
+    id: DEFAULT_CONVERSION_COLUMN_ID,
+    name: DEFAULT_CONVERSION_COLUMN_NAME,
+};
+/**
+ * A table's value columns, always at least one. An absent or empty `columns`
+ * normalizes to the single implicit column, so callers never branch on shape.
+ */
+export const conversionColumns = (data) => data.columns && data.columns.length > 0 ? data.columns : [IMPLICIT_COLUMN];
+/** True when equations must name a column to be unambiguous. */
+export const hasMultipleConversionColumns = (data) => conversionColumns(data).length > 1;
+/**
+ * The column an equation variable binds to. An absent/unknown `columnId` is the
+ * first column: that is what a binding written before multi-column tables
+ * meant, and the only reading that keeps such equations computing.
+ */
+export const resolveConversionColumn = (data, columnId) => {
+    const columns = conversionColumns(data);
+    if (columnId == null)
+        return columns[0];
+    return columns.find((c) => c.id === columnId) ?? columns[0];
+};
+export const findConversionColumn = (data, columnId) => conversionColumns(data).find((c) => c.id === columnId);
+/** Raw cell text for one row/column, or '' when the cell was never filled. */
+export const conversionCellValue = (data, conversion, columnId) => {
+    const columns = conversionColumns(data);
+    return columnId === columns[0].id
+        ? conversion.value
+        : (conversion.values?.[columnId] ?? '');
+};
+/**
+ * `conversion` with one cell replaced, honouring the column-0-in-`value` rule.
+ * Returns a new object; `values` is omitted entirely when it would be empty so
+ * Firestore never receives a stray `{}`.
+ */
+export const writeConversionCell = (data, conversion, columnId, cell) => {
+    const columns = conversionColumns(data);
+    if (columnId === columns[0].id)
+        return { ...conversion, value: cell };
+    const values = { ...conversion.values, [columnId]: cell };
+    return { ...conversion, values };
+};
+/** The dimension a column's values carry — 'none' for an unannotated column. */
+export const conversionColumnDimension = (column) => column.unit != null ? unitDimension(column.unit) : 'none';
+/**
+ * The CANONICAL number a cell contributes to an equation, or null when the
+ * cell is blank or unparseable. Unit-less columns pass their value through
+ * unchanged (the historical meaning of a conversion factor); a column with a
+ * unit converts, so downstream code can treat it like any measurement value.
+ */
+export const conversionCellNumber = (data, conversion, columnId) => {
+    const column = resolveConversionColumn(data, columnId);
+    const parsed = parseFloat(conversionCellValue(data, conversion, column.id));
+    if (!Number.isFinite(parsed))
+        return null;
+    return column.unit != null ? toCanonical(parsed, column.unit) : parsed;
+};
+/** The row a selected label refers to. */
+export const findConversionRow = (data, label) => data.conversions.find((c) => c.label === label);
+/**
+ * How a column is named in a chip, a picker or a validation message. Falls back
+ * to the positional `[i]` form the column is otherwise anonymous — an unnamed
+ * column still has to be tellable apart from its neighbours.
+ */
+export const conversionColumnLabel = (data, columnId) => {
+    const columns = conversionColumns(data);
+    // An unknown id resolves to the first column, matching resolveConversionColumn
+    // — the label must name the column the equation will actually read.
+    const found = columnId == null ? -1 : columns.findIndex((c) => c.id === columnId);
+    const index = found < 0 ? 0 : found;
+    return columns[index].name.trim() !== '' ? columns[index].name : `[${index}]`;
+};
+/**
+ * Qualified name for a binding — what the formula builder puts on a chip and
+ * what validation quotes back. Single-column tables read as the bare field
+ * name, so nothing changes for the tables that already exist.
+ */
+export const conversionBindingLabel = (fieldName, data, columnId) => hasMultipleConversionColumns(data)
+    ? `${fieldName} · ${conversionColumnLabel(data, columnId)}`
+    : fieldName;
+/**
+ * True when a column carries nothing the implicit column doesn't already imply,
+ * so persisting it would only add a key. A named or unit-annotated column is
+ * NOT implicit even when it's the only one — that annotation is the difference
+ * between a table of inch values and a table of bare factors.
+ */
+const isImplicitColumn = (column) => column.id === DEFAULT_CONVERSION_COLUMN_ID &&
+    column.unit == null &&
+    (column.name.trim() === '' || column.name === DEFAULT_CONVERSION_COLUMN_NAME);
+/**
+ * Serialize an editor's (columns, rows) working state into storage shape.
+ * The single place the column-0 split is applied on write, and the reason the
+ * editor can add, rename, unit-annotate, reorder and delete columns without
+ * ever reasoning about which key a cell belongs in.
+ *
+ * A table whose only column is the plain implicit one is written WITHOUT a
+ * `columns` key, so it stays byte-identical to what the pre-multi-column editor
+ * produced — no schema churn on every table that doesn't use the feature. A
+ * single column that has been named or given a unit IS persisted: dropping it
+ * would silently discard the annotation.
+ */
+export const buildConversionTableColumnData = (columns, rows) => {
+    const effective = columns.length > 0 ? columns : [IMPLICIT_COLUMN];
+    const [first, ...rest] = effective;
+    const conversions = rows.map((row) => {
+        const values = {};
+        for (const column of rest) {
+            const cell = row.cells[column.id];
+            if (cell != null && cell !== '')
+                values[column.id] = cell;
+        }
+        return {
+            label: row.label,
+            value: row.cells[first.id] ?? '',
+            ...(Object.keys(values).length > 0 ? { values } : {}),
+        };
+    });
+    return effective.length === 1 && isImplicitColumn(effective[0])
+        ? { conversions }
+        : { conversions, columns: effective };
+};
+/** Storage shape back to editor working state. */
+export const toConversionRowDrafts = (data) => {
+    const columns = conversionColumns(data);
+    return data.conversions.map((conversion) => ({
+        label: conversion.label,
+        cells: Object.fromEntries(columns.map((column) => [
+            column.id,
+            conversionCellValue(data, conversion, column.id),
+        ])),
+    }));
+};
+/** Convenience for pickers: every column's cell text for one row. */
+export const conversionRowCells = (data, conversion) => conversionColumns(data).map((column) => ({
+    column,
+    value: conversionCellValue(data, conversion, column.id),
+}));

package/dist/calculator/evaluate.d.ts

@@ -16,8 +16,12 @@ export declare const evaluateExpression: (expression: string, scope: Record<stri
  * 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).
+ *
+ * `columnId` selects which value column a conversion-table field yields; it is
+ * ignored for every other kind. Omitted means the first column, so a caller
+ * that predates multi-column tables reads exactly what it used to.
  */
-export declare const numericFieldValue: (field: CalculatorField, value: CalculatorFieldValue | undefined) => number | null;
+export declare const numericFieldValue: (field: CalculatorField, value: CalculatorFieldValue | undefined, columnId?: string) => number | null;
 export type EquationResult = {
     ok: true;
     value: number;

package/dist/calculator/evaluate.js

@@ -1,6 +1,7 @@
 import { create, all } from 'mathjs';
 import { ColumnType } from '../types/firestore.js';
 import { equationForField, findField } from './schema.js';
+import { conversionCellNumber, findConversionRow } from './conversionTable.js';
 import { fromCanonical, toCanonical } from './units.js';
 // Trig in calculator equations works in DEGREES: angle fields are stored in
 // degrees canonically, and construction authors write `H = W * tan(A)`
@@ -77,8 +78,12 @@ export const evaluateExpression = (expression, scope) => {
  * 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).
+ *
+ * `columnId` selects which value column a conversion-table field yields; it is
+ * ignored for every other kind. Omitted means the first column, so a caller
+ * that predates multi-column tables reads exactly what it used to.
  */
-export const numericFieldValue = (field, value) => {
+export const numericFieldValue = (field, value, columnId) => {
     switch (field.kind) {
         case ColumnType.Number:
         case ColumnType.Measurement:
@@ -87,16 +92,16 @@ export const numericFieldValue = (field, value) => {
             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).
+            // The stored value is the selected ROW's label; the number comes from
+            // that row's cell in the requested column (cells are strings app-wide,
+            // and a unit-annotated column converts to canonical on the way out).
             const label = value ?? field.defaultValue;
             if (typeof label !== 'string')
                 return null;
-            const entry = field.columnData.conversions.find((c) => c.label === label);
-            if (!entry)
+            const row = findConversionRow(field.columnData, label);
+            if (!row)
                 return null;
-            const parsed = parseFloat(entry.value);
-            return Number.isFinite(parsed) ? parsed : null;
+            return conversionCellNumber(field.columnData, row, columnId);
         }
         default:
             return null;
@@ -118,7 +123,7 @@ const evaluateEquationInContext = (equation, ctx) => {
         const scope = {};
         const missing = [];
         for (const [variable, fieldId] of Object.entries(equation.variableToFieldId)) {
-            const resolved = resolveFieldNumeric(fieldId, ctx);
+            const resolved = resolveFieldNumeric(fieldId, ctx, equation.variableColumnIds?.[variable]);
             if (!resolved.ok) {
                 if (resolved.reason === 'missing-inputs') {
                     missing.push(...resolved.missingFieldIds);
@@ -185,7 +190,9 @@ const evaluateEquationInContext = (equation, ctx) => {
 // 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 resolveFieldNumeric = (fieldId, ctx, 
+/** Conversion-table column the referencing variable binds to. */
+columnId) => {
     const field = findField(ctx.definition, fieldId);
     if (!field) {
         return {
@@ -200,13 +207,13 @@ const resolveFieldNumeric = (fieldId, ctx) => {
         if (computed.ok)
             return computed;
         if (computed.reason === 'missing-inputs') {
-            const supplied = numericFieldValue(field, ctx.values[fieldId]);
+            const supplied = numericFieldValue(field, ctx.values[fieldId], columnId);
             if (supplied != null)
                 return { ok: true, value: supplied };
         }
         return computed;
     }
-    const value = numericFieldValue(field, ctx.values[fieldId]);
+    const value = numericFieldValue(field, ctx.values[fieldId], columnId);
     if (value == null) {
         return { ok: false, reason: 'missing-inputs', missingFieldIds: [fieldId] };
     }

package/dist/calculator/expressionUnits.d.ts

@@ -50,7 +50,7 @@ export type ExpressionUnitInference = ({
  * The dimension and unit of an equation's raw expression value — what the
  * number means BEFORE `resultUnit` is applied.
  */
-export declare const inferExpressionUnit: (fields: readonly CalculatorField[], equation: Pick<CalculatorEquation, "expression" | "variableToFieldId" | "variableUnits">) => ExpressionUnitInference;
+export declare const inferExpressionUnit: (fields: readonly CalculatorField[], equation: Pick<CalculatorEquation, "expression" | "variableToFieldId" | "variableColumnIds" | "variableUnits">) => ExpressionUnitInference;
 /**
  * True when an expression's raw value is already canonical, so omitting
  * `resultUnit` is correct rather than a 25400× mistake. Only the
@@ -70,13 +70,14 @@ export declare const unitScaleRatio: (declared: CalculatorUnit, actual: Calculat
  * (dimensionless or already-canonical result) or cannot be derived. An
  * existing equivalent unit is preserved so `in_frac` isn't churned to `in`.
  */
-export declare const deriveResultUnit: (fields: readonly CalculatorField[], equation: Pick<CalculatorEquation, "expression" | "variableToFieldId" | "variableUnits" | "resultUnit">) => CalculatorUnit | null;
+export declare const deriveResultUnit: (fields: readonly CalculatorField[], equation: Pick<CalculatorEquation, "expression" | "variableToFieldId" | "variableColumnIds" | "variableUnits" | "resultUnit">) => CalculatorUnit | null;
 /**
- * Bring an equation's unit annotations back in line with the fields it
- * references. Field edits (a dimension switch, a kind change, a deletion) are
- * written independently of equations, so a stale `variableUnits` entry or
- * `resultUnit` would otherwise keep converting against a unit the field no
- * longer uses — the failure mode this whole module exists to prevent.
+ * Bring an equation's field-derived annotations — variable column bindings,
+ * variable units, result unit — back in line with the fields it references.
+ * Field edits (a dimension switch, a kind change, a deleted conversion column,
+ * a deleted field) are written independently of equations, so a stale entry
+ * would otherwise keep converting against a unit or reading a column the field
+ * no longer has — the failure mode this whole module exists to prevent.
  */
 export declare const reconcileEquationUnits: (fields: readonly CalculatorField[], equations: readonly CalculatorEquation[]) => {
     equations: CalculatorEquation[];

package/dist/calculator/expressionUnits.js

@@ -1,6 +1,7 @@
 import { create, all } from 'mathjs';
-import { Units } from '../types/firestore.js';
-import { fieldDefaultUnit, fieldDimension } from './schema.js';
+import { ColumnType, Units } from '../types/firestore.js';
+import { bindingDefaultUnit, bindingDimension, fieldDimension, } from './schema.js';
+import { findConversionColumn } from './conversionTable.js';
 import { CALCULATOR_UNIT_INFO, toCanonical, unitDimension, } from './units.js';
 const math = create(all);
 // ---------------------------------------------------------------------------
@@ -143,7 +144,7 @@ export const inferExpressionUnit = (fields, equation) => {
         const field = fieldId != null ? fieldById.get(fieldId) : undefined;
         if (field) {
             // No variable unit: the value enters the scope canonically (units.ts).
-            const dimension = fieldDimension(field);
+            const dimension = bindingDimension(field, equation.variableColumnIds?.[name]);
             const exponents = EXPONENTS_BY_DIMENSION[dimension];
             noteBases(exponents, dimension === 'angle' ? CANONICAL_ANGLE_BASE : CANONICAL_LENGTH_BASE);
             return exponents;
@@ -369,33 +370,65 @@ const withoutResultUnit = (equation) => {
     const { resultUnit: _dropped, ...rest } = equation;
     return rest;
 };
+// Rebuild an equation without a key, since Firestore rejects `undefined`.
+const withoutVariableColumnIds = (equation) => {
+    const { variableColumnIds: _dropped, ...rest } = equation;
+    return rest;
+};
 /**
- * Bring an equation's unit annotations back in line with the fields it
- * references. Field edits (a dimension switch, a kind change, a deletion) are
- * written independently of equations, so a stale `variableUnits` entry or
- * `resultUnit` would otherwise keep converting against a unit the field no
- * longer uses — the failure mode this whole module exists to prevent.
+ * Bring an equation's field-derived annotations — variable column bindings,
+ * variable units, result unit — back in line with the fields it references.
+ * Field edits (a dimension switch, a kind change, a deleted conversion column,
+ * a deleted field) are written independently of equations, so a stale entry
+ * would otherwise keep converting against a unit or reading a column the field
+ * no longer has — the failure mode this whole module exists to prevent.
  */
 export const reconcileEquationUnits = (fields, equations) => {
     const fieldById = new Map(fields.map((f) => [f.id, f]));
     let changed = false;
     const next = equations.map((equation) => {
         let repaired = equation;
-        // 1. Variable units must match the dimension of the field they annotate.
-        if (equation.variableUnits) {
+        // 1. Column bindings must name a column the bound field still has. A
+        //    dropped entry falls back to the first column, which is the same
+        //    reading the evaluator gives it — so pruning here only removes a lie,
+        //    it never changes what the equation computes.
+        if (equation.variableColumnIds) {
+            const variableColumnIds = {};
+            let bindingsChanged = false;
+            for (const [variable, columnId] of Object.entries(equation.variableColumnIds)) {
+                const field = fieldById.get(equation.variableToFieldId[variable] ?? '');
+                if (field?.kind === ColumnType.ConversionTable &&
+                    findConversionColumn(field.columnData, columnId)) {
+                    variableColumnIds[variable] = columnId;
+                    continue;
+                }
+                bindingsChanged = true;
+            }
+            if (bindingsChanged) {
+                repaired =
+                    Object.keys(variableColumnIds).length > 0
+                        ? { ...repaired, variableColumnIds }
+                        : withoutVariableColumnIds(repaired);
+            }
+        }
+        // 2. Variable units must match the dimension of the binding they annotate.
+        //    Read against `repaired`, not `equation`: step 1 may have moved a
+        //    variable back to the first column, whose dimension is what matters now.
+        if (repaired.variableUnits) {
             const variableUnits = {};
             let unitsChanged = false;
-            for (const [variable, unit] of Object.entries(equation.variableUnits)) {
-                const field = fieldById.get(equation.variableToFieldId[variable] ?? '');
+            for (const [variable, unit] of Object.entries(repaired.variableUnits)) {
+                const field = fieldById.get(repaired.variableToFieldId[variable] ?? '');
                 if (!field) {
                     unitsChanged = true; // variable or field is gone
                     continue;
                 }
-                if (unitDimension(unit) === fieldDimension(field)) {
+                const columnId = repaired.variableColumnIds?.[variable];
+                if (unitDimension(unit) === bindingDimension(field, columnId)) {
                     variableUnits[variable] = unit;
                     continue;
                 }
-                const replacement = fieldDefaultUnit(field);
+                const replacement = bindingDefaultUnit(field, columnId);
                 unitsChanged = true;
                 if (replacement)
                     variableUnits[variable] = replacement;
@@ -410,7 +443,7 @@ export const reconcileEquationUnits = (fields, equations) => {
                         })();
             }
         }
-        // 2. The result unit follows from the repaired variable units.
+        // 3. The result unit follows from the repaired variable units.
         const target = fieldById.get(equation.targetFieldId);
         const targetDimension = target ? fieldDimension(target) : 'none';
         if (targetDimension === 'none') {

package/dist/calculator/index.d.ts

@@ -1,6 +1,7 @@
 export * from './schema.js';
 export * from './categories.js';
 export * from './units.js';
+export * from './conversionTable.js';
 export * from './expressionUnits.js';
 export * from './evaluate.js';
 export * from './solve.js';

package/dist/calculator/index.js

@@ -5,6 +5,7 @@
 export * from './schema.js';
 export * from './categories.js';
 export * from './units.js';
+export * from './conversionTable.js';
 export * from './expressionUnits.js';
 export * from './evaluate.js';
 export * from './solve.js';

package/dist/calculator/schema.d.ts

@@ -111,6 +111,16 @@ export interface CalculatorEquation {
     expression: string;
     /** Variable letter -> field id. */
     variableToFieldId: Record<string, string>;
+    /**
+     * Variable letter -> `ConversionColumn.id`, for variables bound to a
+     * conversion-table field. Absent (or absent for one letter) means that
+     * variable reads the table's FIRST column — the only reading under which
+     * equations written before multi-column tables keep computing.
+     *
+     * Two letters may map to the same field with different columns: that is the
+     * whole point, one row selection feeding several terms of an expression.
+     */
+    variableColumnIds?: Record<string, string>;
     /**
      * Variable letter -> display unit its value enters the scope in. A mapped
      * variable without an entry stays canonical (µm-scale) — the pre-1.9
@@ -171,12 +181,44 @@ export declare const findEquation: (definition: Pick<CalculatorDefinition, "equa
 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;
+/**
+ * What one equation VARIABLE binds to: a field, and for a conversion table
+ * which of its value columns. Everything downstream of the variable map — unit
+ * inference, validation, the scope build — needs the pair, because a
+ * conversion table's dimension is a property of the column, not the field.
+ */
+export interface VariableBinding {
+    fieldId: string;
+    /** Undefined for non-conversion fields and for first-column bindings. */
+    columnId?: string;
+}
+/** The binding for one variable letter, or null when the letter is unmapped. */
+export declare const equationBinding: (equation: Pick<CalculatorEquation, "variableToFieldId" | "variableColumnIds">, variable: string) => VariableBinding | null;
+/** Every variable's binding, in the variable map's order. */
+export declare const equationBindings: (equation: Pick<CalculatorEquation, "variableToFieldId" | "variableColumnIds">) => (VariableBinding & {
+    variable: string;
+})[];
+/**
+ * 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 declare const bindingDimension: (field: CalculatorField, columnId?: string) => FieldDimension;
 /**
  * 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
  * out annotated with.
  */
 export declare const fieldDefaultUnit: (field: CalculatorField) => CalculatorUnit | null;
+/**
+ * The unit a BOUND value is expressed in, or null when it carries none. For a
+ * conversion column this is the column's declared unit and is NOT a per-equation
+ * choice: the cell text was typed in that unit, so re-expressing the variable in
+ * another one would only invite the scale errors expressionUnits.ts exists to
+ * catch. The authoring UI shows it read-only for that reason.
+ */
+export declare const bindingDefaultUnit: (field: CalculatorField, columnId?: string) => CalculatorUnit | null;
 /** 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). */

package/dist/calculator/schema.js

@@ -1,5 +1,6 @@
 import { ColumnType, Units, } from '../types/firestore.js';
 import { 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,16 @@ export const fieldDefaultUnit = (field) => {
             return null;
     }
 };
+/**
+ * The unit a BOUND value is expressed in, or null when it carries none. For a
+ * conversion column this is the column's declared unit and is NOT a per-equation
+ * choice: the cell text was typed in that unit, so re-expressing the variable in
+ * another one would only invite the scale errors expressionUnits.ts exists to
+ * catch. The authoring UI shows it read-only for that reason.
+ */
+export const bindingDefaultUnit = (field, columnId) => field.kind === ColumnType.ConversionTable
+    ? (resolveConversionColumn(field.columnData, columnId).unit ?? null)
+    : fieldDefaultUnit(field);
 /** Fields whose value participates in equations as a number. */
 export const isNumericFieldKind = (kind) => kind === ColumnType.Number ||
     kind === ColumnType.Measurement ||

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,7 @@ 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>>;
         variableUnits: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         resultUnit: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;

package/dist/calculator/validate.js

@@ -1,6 +1,7 @@
 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_SCHEMA_VERSION, bindingDimension, equationForField, fieldDimension, isEquationTargetKind, isNumericFieldKind, } from './schema.js';
+import { conversionBindingLabel, conversionCellValue, conversionColumnLabel, conversionColumns, findConversionColumn, hasMultipleConversionColumns, } from './conversionTable.js';
 import { CALCULATOR_UNIT_INFO, unitDimension, } from './units.js';
 import { MATHJS_CONSTANTS, inferExpressionUnit, isEquivalentUnit, parseExpression, producesCanonicalValue, unitScaleRatio, } from './expressionUnits.js';
 import { isCalculatorCategoryId } from './categories.js';
@@ -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,7 @@ 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(),
     variableUnits: z.record(z.string(), calculatorUnitSchema).optional(),
     resultUnit: calculatorUnitSchema.optional(),
 });
@@ -163,6 +176,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 +278,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 +345,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,12 +389,14 @@ 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
@@ -394,10 +472,11 @@ export const validateCalculatorDefinition = (input) => {
             (!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.0",
   "description": "Shared utilities for formulas and measurement conversion used in Reekon apps",
   "author": "REEKON Tools",
   "license": "MIT",