@reekon-tools/boldr-utils 1.10.3 → 1.11.0

package/dist/calculator/chips.d.ts

@@ -0,0 +1,32 @@
+import type { ResolvedField } from './runtime.js';
+export declare const CALC_COLORS: {
+    /** Ink on the white/light-grey chips. */
+    readonly text: "#181A1C";
+    readonly chipBg: "#E8EAED";
+    readonly chipBorder: "#BCBEC2";
+    readonly letterBg: "#E8EAED";
+    readonly focusRing: "#FFAD00";
+    readonly focusFill: "#FFF8DB";
+    /** A value the user (or a tool) typed. */
+    readonly entered: "#0066FF";
+    readonly enteredLetter: "#50A6FF";
+    /** A value the equation solved for. */
+    readonly computed: "#BD30A8";
+    readonly computedLetter: "#6C155F";
+    /**
+     * A value that disagrees with its equation. RED, not a fourth blue: blue
+     * means entered and purple means calculated, so a navy chip read as a third
+     * kind of VALUE rather than as a problem — and its number stayed legible
+     * enough to cut against. Red is the app's warning colour everywhere else.
+     */
+    readonly conflict: "#E83D2F";
+    readonly conflictLetter: "#DA1100";
+    readonly conflictClear: "#E83D2F";
+};
+export type ChipState = 'empty' | 'entered' | 'computed' | 'conflict' | 'default';
+export declare const chipStateOf: (resolved: ResolvedField) => ChipState;
+export declare const CHIP_STYLE: Record<ChipState, {
+    background: string;
+    letterBackground: string;
+    text: string;
+}>;

package/dist/calculator/chips.js

@@ -0,0 +1,79 @@
+// The value-state palette every calculator surface paints with: mobile's table
+// rows and diagram cards, and the web viewer's read-only cards. It lives here
+// (not in either app) because the COLOR IS THE MEANING — blue says a human
+// typed it, purple says the calculator worked it out, red says the two
+// disagree. A surface that re-derives that mapping locally is one refactor away
+// from telling a crew a computed number was measured.
+//
+// The runtime is a light paper island on both platforms — frame `5287:108428`
+// samples a `#2B2C2E` header over an `#E8EAED` canvas with `#FFFFFF` field
+// cards. That is the exact opposite of the BASIC calculator (`5365:17187`),
+// which is fully dark. Do not "fix" one to match the other.
+import { FormColors, FormulaColors, GeneralColors, RedColors, TileColors, YellowColors, } from '../theme/colors.js';
+export const CALC_COLORS = {
+    /** Ink on the white/light-grey chips. */
+    text: GeneralColors.darkGrey,
+    chipBg: FormColors.lightGrey2,
+    chipBorder: FormColors.lightGrey1,
+    letterBg: FormColors.lightGrey2,
+    focusRing: YellowColors.mainYellow,
+    // A pale cream wash for "focused and empty, waiting for the keypad". It only
+    // exists on the light canvas and has no palette equivalent — mainYellow at
+    // low alpha goes muddy over lightGrey2.
+    focusFill: '#FFF8DB',
+    /** A value the user (or a tool) typed. */
+    entered: TileColors.activeBlue,
+    enteredLetter: TileColors.lightBlue1,
+    /** A value the equation solved for. */
+    computed: FormulaColors.purple,
+    computedLetter: FormulaColors.darkPurple,
+    /**
+     * A value that disagrees with its equation. RED, not a fourth blue: blue
+     * means entered and purple means calculated, so a navy chip read as a third
+     * kind of VALUE rather than as a problem — and its number stayed legible
+     * enough to cut against. Red is the app's warning colour everywhere else.
+     */
+    conflict: RedColors.red,
+    conflictLetter: RedColors.warningRed,
+    conflictClear: RedColors.red,
+};
+export const chipStateOf = (resolved) => {
+    if (resolved.conflict)
+        return 'conflict';
+    if (resolved.origin === 'user' || resolved.origin === 'tool')
+        return 'entered';
+    if (resolved.origin === 'computed' || resolved.origin === 'solved')
+        return 'computed';
+    if (resolved.origin === 'default')
+        return 'default';
+    return 'empty';
+};
+export const CHIP_STYLE = {
+    empty: {
+        background: GeneralColors.white,
+        letterBackground: CALC_COLORS.letterBg,
+        text: CALC_COLORS.text,
+    },
+    default: {
+        background: GeneralColors.white,
+        letterBackground: CALC_COLORS.letterBg,
+        text: CALC_COLORS.text,
+    },
+    entered: {
+        background: CALC_COLORS.entered,
+        letterBackground: CALC_COLORS.enteredLetter,
+        text: GeneralColors.white,
+    },
+    computed: {
+        background: CALC_COLORS.computed,
+        letterBackground: CALC_COLORS.computedLetter,
+        text: GeneralColors.white,
+    },
+    conflict: {
+        background: CALC_COLORS.conflict,
+        letterBackground: CALC_COLORS.conflictLetter,
+        // Full white: the chip shows a dash, and a dash has to be legible. The old
+        // 55% wash existed to de-emphasise a number that is no longer drawn.
+        text: GeneralColors.white,
+    },
+};

package/dist/calculator/display.d.ts

@@ -0,0 +1,78 @@
+import { type CalculatorUnit } from './units.js';
+import type { CalculatorDefinition, CalculatorField } from './schema.js';
+import type { ResolvedField } from './runtime.js';
+export type UnitSystem = 'imperial' | 'metric';
+export type DisplayUnitOverrides = Readonly<Record<string, CalculatorUnit>>;
+/** The unit a field currently displays in (session override > field default). */
+export declare const displayUnitFor: (field: CalculatorField, overrides?: DisplayUnitOverrides) => CalculatorUnit | null;
+/** Units the picker offers for a field; empty for unit-less kinds. */
+export declare const allowedDisplayUnits: (field: CalculatorField) => CalculatorUnit[];
+/**
+ * Parse raw keypad text (in the given display unit) into a canonical value.
+ * Fractions and mixed numbers are accepted for measurements and angles
+ * (mirrors the web editor's EditEquation semantics). Returns null when the
+ * draft isn't parseable yet — callers keep the last good value.
+ */
+export declare const parseFieldInput: (field: CalculatorField, unit: CalculatorUnit | null, raw: string) => number | null;
+/** Format a canonical value for display in the given unit. */
+export declare const formatFieldValue: (field: CalculatorField, unit: CalculatorUnit | null, canonical: number) => {
+    value: string;
+    unit: string;
+};
+/**
+ * What a conflicting field shows INSTEAD of its number. A value the runtime
+ * knows disagrees with its equation must not be readable as a measurement —
+ * someone cuts to what's on the screen — so the number is withheld rather than
+ * dimmed, and the detail sheet is where the entered value is recoverable.
+ * Same em dash the empty-output placeholder uses.
+ */
+export declare const CONFLICT_DASH = "\u2014";
+/**
+ * The text every value surface shows for a resolved field — table row, diagram
+ * stamp, and the detail sheet's card all route through here so the conflict
+ * dash can't ship in one of them and not the others. Null means "nothing to
+ * show": the caller draws its own empty placeholder.
+ */
+export declare const resolvedValueText: (field: CalculatorField, unit: CalculatorUnit | null, resolved: ResolvedField) => string | null;
+/**
+ * The letter chip a field wears in both the diagram badges and the table
+ * rows: sequential A, B, C… over the definition's fields (Instructions
+ * excluded — they carry no value).
+ */
+export declare const letterLabelFor: (definition: Pick<CalculatorDefinition, "fields">, fieldId: string) => string;
+/**
+ * Whether a user-entered value and a freshly computed one count as the same
+ * number: they format identically in the field's DEFAULT unit at its
+ * configured tolerance (i.e. the user couldn't tell them apart), with a tiny
+ * absolute/relative epsilon as a float-noise backstop. Deliberately ignores
+ * session unit overrides so conflict-ness doesn't change with the unit
+ * toggle.
+ */
+export declare const valuesAgree: (field: CalculatorField, entered: number, computed: number) => boolean;
+/** The structured draft the fraction keypad edits. All parts are digit text. */
+export interface KeypadParts {
+    negative: boolean;
+    /** Feet, in feet-inches mode only. */
+    feet: string;
+    /** Whole number (or decimal text in decimal mode). */
+    whole: string;
+    numerator: string;
+    denominator: string;
+}
+export declare const emptyKeypadParts: () => KeypadParts;
+export type KeypadMode = 'decimal' | 'fractional' | 'feetFractional';
+/** Which keypad layout a display unit gets. */
+export declare const keypadModeForUnit: (unit: CalculatorUnit | null) => KeypadMode;
+/**
+ * Convert a keypad draft into a canonical value for the field. Returns null
+ * when the draft is empty/incomplete (callers keep the previous value).
+ * Feet-inches composes feet + fractional inches directly, since a single
+ * "F W N/D" string has no parseable representation in a feet unit.
+ */
+export declare const keypadPartsToCanonical: (field: CalculatorField, unit: CalculatorUnit | null, parts: KeypadParts) => number | null;
+/**
+ * Overrides implementing the English/Metric toggle: every measurement field
+ * flips to its dimension's preferred unit (constrained to allowedUnits).
+ * Fields whose pick equals their default get no override. Angles stay put.
+ */
+export declare const mapUnitSystem: (definition: Pick<CalculatorDefinition, "fields">, system: UnitSystem) => Record<string, CalculatorUnit>;

package/dist/calculator/display.js

@@ -0,0 +1,223 @@
+// Display-unit edge of the calculator runtime: parsing keypad input into
+// canonical values, formatting canonical values back out, per-field unit
+// choices, and the letter labels shared by diagram badges and table rows.
+// Pure functions only, shared by every consuming runtime (mobile's run screen,
+// the web read-only viewer) so a value can't render two ways.
+import { ColumnType, Units } from '../types/firestore.js';
+import { formatCanonical, parseToCanonical, unitsForDimension, } from './units.js';
+/** The unit a field currently displays in (session override > field default). */
+export const displayUnitFor = (field, overrides = {}) => {
+    switch (field.kind) {
+        case ColumnType.Measurement:
+            return overrides[field.id] ?? field.unit.defaultUnit;
+        case ColumnType.Angle:
+            return overrides[field.id] ?? field.angleUnit ?? 'deg';
+        default:
+            return null;
+    }
+};
+/** Units the picker offers for a field; empty for unit-less kinds. */
+export const allowedDisplayUnits = (field) => {
+    switch (field.kind) {
+        case ColumnType.Measurement: {
+            const allowed = field.unit.allowedUnits?.length
+                ? field.unit.allowedUnits
+                : unitsForDimension(field.unit.dimension);
+            return allowed.includes(field.unit.defaultUnit)
+                ? allowed
+                : [field.unit.defaultUnit, ...allowed];
+        }
+        case ColumnType.Angle:
+            return ['deg', 'rad'];
+        default:
+            return [];
+    }
+};
+/**
+ * Parse raw keypad text (in the given display unit) into a canonical value.
+ * Fractions and mixed numbers are accepted for measurements and angles
+ * (mirrors the web editor's EditEquation semantics). Returns null when the
+ * draft isn't parseable yet — callers keep the last good value.
+ */
+export const parseFieldInput = (field, unit, raw) => {
+    switch (field.kind) {
+        case ColumnType.Measurement:
+        case ColumnType.Angle:
+            return unit ? parseToCanonical(raw, unit) : null;
+        case ColumnType.Number: {
+            const trimmed = raw.trim();
+            if (trimmed === '')
+                return null;
+            const parsed = Number(trimmed);
+            return Number.isFinite(parsed) ? parsed : null;
+        }
+        default:
+            return null;
+    }
+};
+// Matches the web editor's unit-less number formatting (6 significant
+// figures, no trailing zeros).
+const trimNumber = (value) => Number.isFinite(value) ? Number(value.toPrecision(6)).toString() : 'NaN';
+/** Format a canonical value for display in the given unit. */
+export const formatFieldValue = (field, unit, canonical) => {
+    if (!unit)
+        return { value: trimNumber(canonical), unit: '' };
+    return formatCanonical(canonical, unit, field.kind === ColumnType.Measurement
+        ? {
+            fractionalTolerance: field.unit.fractionalTolerance,
+            decimalTolerance: field.unit.decimalTolerance,
+        }
+        : undefined);
+};
+/**
+ * What a conflicting field shows INSTEAD of its number. A value the runtime
+ * knows disagrees with its equation must not be readable as a measurement —
+ * someone cuts to what's on the screen — so the number is withheld rather than
+ * dimmed, and the detail sheet is where the entered value is recoverable.
+ * Same em dash the empty-output placeholder uses.
+ */
+export const CONFLICT_DASH = '—';
+/**
+ * The text every value surface shows for a resolved field — table row, diagram
+ * stamp, and the detail sheet's card all route through here so the conflict
+ * dash can't ship in one of them and not the others. Null means "nothing to
+ * show": the caller draws its own empty placeholder.
+ */
+export const resolvedValueText = (field, unit, resolved) => {
+    if (resolved.conflict)
+        return CONFLICT_DASH;
+    if (resolved.value == null)
+        return null;
+    if (typeof resolved.value === 'number') {
+        return formatFieldValue(field, unit, resolved.value).value;
+    }
+    return Array.isArray(resolved.value)
+        ? resolved.value.join(', ')
+        : String(resolved.value);
+};
+// 0 -> A, 25 -> Z, 26 -> AA ...
+const indexToLetters = (index) => {
+    let label = '';
+    let i = index;
+    do {
+        label = String.fromCharCode(65 + (i % 26)) + label;
+        i = Math.floor(i / 26) - 1;
+    } while (i >= 0);
+    return label;
+};
+/**
+ * The letter chip a field wears in both the diagram badges and the table
+ * rows: sequential A, B, C… over the definition's fields (Instructions
+ * excluded — they carry no value).
+ */
+export const letterLabelFor = (definition, fieldId) => {
+    let index = 0;
+    for (const field of definition.fields) {
+        if (field.kind === ColumnType.Instructions)
+            continue;
+        if (field.id === fieldId)
+            return indexToLetters(index);
+        index++;
+    }
+    return '';
+};
+/**
+ * Whether a user-entered value and a freshly computed one count as the same
+ * number: they format identically in the field's DEFAULT unit at its
+ * configured tolerance (i.e. the user couldn't tell them apart), with a tiny
+ * absolute/relative epsilon as a float-noise backstop. Deliberately ignores
+ * session unit overrides so conflict-ness doesn't change with the unit
+ * toggle.
+ */
+export const valuesAgree = (field, entered, computed) => {
+    const unit = displayUnitFor(field, {});
+    const enteredText = formatFieldValue(field, unit, entered).value;
+    const computedText = formatFieldValue(field, unit, computed).value;
+    if (enteredText === computedText)
+        return true;
+    const epsilon = Math.max(1e-6, 1e-9 * Math.abs(computed));
+    return Math.abs(entered - computed) <= epsilon;
+};
+// Preferred display units per dimension for the header's unit-system toggle,
+// best-first. The pick is constrained to each field's allowedUnits.
+const SYSTEM_PREFERENCES = {
+    imperial: {
+        length: [
+            Units.FractionalInches,
+            Units.FeetInchesFractional,
+            Units.Inches,
+            Units.Feet,
+            Units.FeetInchesDecimal,
+        ],
+        area: ['sq_ft', 'sq_in', 'sq_yd'],
+        volume: ['cu_ft', 'cu_in', 'cu_yd', 'gallon'],
+    },
+    metric: {
+        length: [Units.Millimeters, Units.Centimeters, Units.Meters],
+        area: ['sq_m', 'sq_cm', 'sq_mm'],
+        volume: ['cu_m', 'liter', 'cu_cm', 'cu_mm'],
+    },
+};
+export const emptyKeypadParts = () => ({
+    negative: false,
+    feet: '',
+    whole: '',
+    numerator: '',
+    denominator: '',
+});
+/** Which keypad layout a display unit gets. */
+export const keypadModeForUnit = (unit) => {
+    if (unit === Units.FractionalInches)
+        return 'fractional';
+    if (unit === Units.FeetInchesFractional)
+        return 'feetFractional';
+    return 'decimal';
+};
+const fractionText = (parts) => {
+    const { whole, numerator, denominator } = parts;
+    const hasFraction = numerator !== '' && denominator !== '' && denominator !== '0';
+    const body = hasFraction
+        ? `${whole || '0'} ${numerator}/${denominator}`
+        : whole;
+    return body;
+};
+/**
+ * Convert a keypad draft into a canonical value for the field. Returns null
+ * when the draft is empty/incomplete (callers keep the previous value).
+ * Feet-inches composes feet + fractional inches directly, since a single
+ * "F W N/D" string has no parseable representation in a feet unit.
+ */
+export const keypadPartsToCanonical = (field, unit, parts) => {
+    const sign = parts.negative ? -1 : 1;
+    if (keypadModeForUnit(unit) === 'feetFractional') {
+        if (parts.feet === '' && fractionText(parts) === '')
+            return null;
+        const feetUm = parseToCanonical(parts.feet || '0', Units.Feet);
+        const inchesUm = parseToCanonical(fractionText(parts) || '0', Units.Inches);
+        if (feetUm == null || inchesUm == null)
+            return null;
+        return sign * (feetUm + inchesUm);
+    }
+    const text = fractionText(parts);
+    if (text === '')
+        return null;
+    const parsed = parseFieldInput(field, unit, text);
+    return parsed == null ? null : sign * parsed;
+};
+/**
+ * Overrides implementing the English/Metric toggle: every measurement field
+ * flips to its dimension's preferred unit (constrained to allowedUnits).
+ * Fields whose pick equals their default get no override. Angles stay put.
+ */
+export const mapUnitSystem = (definition, system) => {
+    const overrides = {};
+    for (const field of definition.fields) {
+        if (field.kind !== ColumnType.Measurement)
+            continue;
+        const allowed = allowedDisplayUnits(field);
+        const pick = SYSTEM_PREFERENCES[system][field.unit.dimension].find((unit) => allowed.includes(unit));
+        if (pick && pick !== field.unit.defaultUnit)
+            overrides[field.id] = pick;
+    }
+    return overrides;
+};

package/dist/calculator/index.d.ts

@@ -6,4 +6,7 @@ export * from './expressionUnits.js';
 export * from './evaluate.js';
 export * from './solve.js';
 export * from './instance.js';
+export * from './runtime.js';
+export * from './display.js';
+export * from './chips.js';
 export { calculatorDefinitionSchema, expressionSymbols, validateCalculatorDefinition, type IssueSeverity, type ValidationIssue, type ValidationResult, } from './validate.js';

package/dist/calculator/index.js

@@ -1,7 +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.
+// per-field unit system, forward evaluator, two-way numeric solver, definition
+// validation, and the consumption-time runtime (derive pass + display
+// formatting + value-state palette) that turns a saved instance into what a
+// screen shows. Pure logic (mathjs + zod only — no Skia/React), safe on web,
+// native, and Node.
 export * from './schema.js';
 export * from './categories.js';
 export * from './units.js';
@@ -10,4 +12,7 @@ export * from './expressionUnits.js';
 export * from './evaluate.js';
 export * from './solve.js';
 export * from './instance.js';
+export * from './runtime.js';
+export * from './display.js';
+export * from './chips.js';
 export { calculatorDefinitionSchema, expressionSymbols, validateCalculatorDefinition, } from './validate.js';

package/dist/calculator/runtime.d.ts

@@ -0,0 +1,61 @@
+import { type CalculatorDefinition, type CalculatorFieldValue } from './schema.js';
+import type { CalculatorEntryAttribution, CalculatorFieldEntry } from './instance.js';
+export type ResolvedOrigin = 'user' | 'tool' | 'computed' | 'solved' | 'default' | 'empty';
+export interface ResolvedField {
+    /** Canonical value to display; null when empty/blocked. */
+    value: CalculatorFieldValue | null;
+    origin: ResolvedOrigin;
+    /**
+     * Over-constrained: this entry sits on an equation target whose freshly
+     * computed value disagrees beyond the field's display tolerance. Reachable
+     * only when the displacement pass below can't move anything — EVERY entry
+     * deciding it is locked, or nothing left is invertible. UI: RED chip
+     * with the value withheld behind a dash — clearing the entry, or unlocking a
+     * participant, resolves it.
+     */
+    conflict: {
+        computedValue: number;
+    } | null;
+    /** Eval/solve error attributable to this field's equation. */
+    error: string | null;
+    /** When its equation is blocked: the field ids still needed. */
+    missingFieldIds: string[];
+    /** Which equation computed/solved this value. */
+    viaEquationId: string | null;
+    locked: boolean;
+    /**
+     * Populating this field can only end in a conflict, so entry is refused
+     * outright (Asana 1217172568173859). True when the row is showing a
+     * CALCULATED value and every other field on its governing equation is
+     * entered AND locked: the displacement pass then has nothing left to
+     * yield, so a typed value would land as the red conflict chip instead of
+     * steering the calculation. Unlocking any one of them clears it.
+     */
+    populationBlocked: boolean;
+    attribution: CalculatorEntryAttribution | null;
+}
+export interface EquationStatus {
+    equationId: string;
+    targetFieldId: string;
+    /** Variables ∪ target — drives the link badges on participating rows. */
+    participantFieldIds: string[];
+    state: 'computed' | 'solved-a-field' | 'blocked' | 'error';
+    /** The field this equation was inverted for (wears the '=' badge). */
+    solvedFieldId: string | null;
+}
+export interface DerivedRuntime {
+    resolved: Record<string, ResolvedField>;
+    equations: EquationStatus[];
+    /** fieldId -> equation ids it participates in (focus highlighting). */
+    equationsByField: Record<string, string[]>;
+}
+export declare const EMPTY_DERIVED: DerivedRuntime;
+export declare const deriveRuntime: (definition: Pick<CalculatorDefinition, "fields" | "equations">, entries: Readonly<Record<string, CalculatorFieldEntry>>, options?: {
+    solveEnabled?: boolean;
+}) => DerivedRuntime;
+/**
+ * `populationBlocked` for a single field — the one rule the reducer's guards
+ * and the UI's entry affordances share, so a refused "+" and a refused tape
+ * reading can never disagree about which fields are enterable.
+ */
+export declare const isPopulationBlocked: (definition: Pick<CalculatorDefinition, "fields" | "equations">, entries: Readonly<Record<string, CalculatorFieldEntry>>, fieldId: string) => boolean;