@reekon-tools/boldr-utils 1.10.3 → 1.11.0

package/dist/calculator/runtime.js

@@ -0,0 +1,430 @@
+// The derive pass: everything the calculator UI shows that isn't a raw entry.
+// deriveRuntime(definition, entries) is a pure function — computed outputs,
+// solved fields, conflicts, equation badges all fall out of it, recomputed
+// after every mutation. Nothing here is stored, so it can never go stale.
+//
+// This is the ENGINE both runtimes share: mobile's editable run screen and the
+// web read-only viewer. A saved instance therefore re-derives identically on
+// either platform, which is the whole point — the numbers a crew reads on the
+// desktop preview are the numbers the phone showed when it saved.
+import { ColumnType } from '../types/firestore.js';
+import { equationForField, findField, } from './schema.js';
+import { evaluateOutputs } from './evaluate.js';
+import { solveForField } from './solve.js';
+import { valuesAgree } from './display.js';
+export const EMPTY_DERIVED = {
+    resolved: {},
+    equations: [],
+    equationsByField: {},
+};
+const EMPTY_RESOLVED = {
+    conflict: null,
+    error: null,
+    missingFieldIds: [],
+    viaEquationId: null,
+    locked: false,
+    populationBlocked: false,
+    attribution: null,
+};
+const solveHintsOf = (field) => field.kind === ColumnType.Number ||
+    field.kind === ColumnType.Measurement ||
+    field.kind === ColumnType.Angle
+    ? field.solve
+    : undefined;
+const entryOrigin = (entry) => entry.source === 'tool' ? 'tool' : 'user';
+const isNumericField = (field) => field?.kind === ColumnType.Number ||
+    field?.kind === ColumnType.Measurement ||
+    field?.kind === ColumnType.Angle;
+/** Variables ∪ target — the fields an equation ties together. */
+const participantsOf = (equation) => [
+    ...new Set([
+        ...Object.values(equation.variableToFieldId),
+        equation.targetFieldId,
+    ]),
+];
+/**
+ * The definition as the solver should see it while inverting `equation` for
+ * `fieldId` under the displacement rule below: whether this field may be
+ * calculated is a RUNTIME question there (the user left it unlocked), so the
+ * authored hints contribute their brackets but not their veto.
+ */
+const definitionForDisplacement = (definition, fieldId, equation) => ({
+    equations: definition.equations,
+    fields: definition.fields.map((field) => {
+        if (field.id !== fieldId)
+            return field;
+        if (field.kind !== ColumnType.Number &&
+            field.kind !== ColumnType.Measurement &&
+            field.kind !== ColumnType.Angle) {
+            return field;
+        }
+        return {
+            ...field,
+            solve: {
+                ...field.solve,
+                solvable: true,
+                governingEquationId: equation.id,
+            },
+        };
+    }),
+});
+export const deriveRuntime = (definition, entries, options) => {
+    const solveEnabled = options?.solveEnabled ?? true;
+    // 1. Project entries to canonical values. Defaults are NOT merged here —
+    //    numericFieldValue falls back to field.defaultValue during evaluation
+    //    and solving, so equations see them for free.
+    const values = {};
+    for (const [fieldId, entry] of Object.entries(entries)) {
+        values[fieldId] = entry.value;
+    }
+    const fieldOrder = new Map(definition.fields.map((f, index) => [f.id, index]));
+    /** fieldId -> equation ids it participates in. */
+    const equationsByField = {};
+    for (const equation of definition.equations) {
+        for (const fieldId of participantsOf(equation)) {
+            (equationsByField[fieldId] ?? (equationsByField[fieldId] = [])).push(equation.id);
+        }
+    }
+    const equationById = new Map(definition.equations.map((e) => [e.id, e]));
+    const equationTargeting = (fieldId) => definition.equations.find((e) => e.targetFieldId === fieldId);
+    /**
+     * Entries the displacement rule set aside. Shadowing is PRESENTATION: the
+     * entry stays in state untouched, so clearing whatever over-determined the
+     * equation brings the original number straight back, and a saved instance
+     * re-derives identically on reopen.
+     */
+    const shadowed = new Set();
+    /** A value the user is currently holding — an entry no shadow has set aside. */
+    const isPinned = (shadows, fieldId) => entries[fieldId] != null && !shadows.has(fieldId);
+    /** Entries (minus shadows) ∪ solved — what the runtime knows right now. */
+    const knownValues = (shadows, solved) => {
+        const known = {};
+        for (const [id, value] of Object.entries(values)) {
+            if (!shadows.has(id))
+                known[id] = value;
+        }
+        for (const [id, s] of Object.entries(solved))
+            known[id] = s.value;
+        return known;
+    };
+    // 2. Solve pass. Two halves: PROPAGATION works out everything derivable from
+    //    the values the user is holding, and DISPLACEMENT decides which held
+    //    values have to give way when they can't all hold at once.
+    /**
+     * Every value the runtime can pin down for a given shadow set, to a fixpoint
+     * so each filled-in value cascades into the next equation. Two rules:
+     *
+     *  - a SHADOWED field is taken over by the first equation that can invert for
+     *    it. The lock is the gate the user actually operates, so the authored
+     *    `solvable` hint gets no veto here — it only lends its brackets (see
+     *    definitionForDisplacement). Which equation ends up with the field is not
+     *    fixed: releasing another entry can hand it to a different one, which is
+     *    exactly how the newest entry takes the wheel below.
+     *  - an EMPTY field fills itself in only when its author marked it solvable.
+     *    solveForField enforces the exactly-one-missing rule (missing-target /
+     *    missing-inputs fail silently), so under-determined systems stay empty.
+     *
+     * Pure in `shadows`, so displacement can try a release and throw it away.
+     */
+    const propagate = (shadows) => {
+        const solved = {};
+        let progressed = true;
+        let sweeps = 0;
+        while (progressed && sweeps++ <= definition.fields.length) {
+            progressed = false;
+            for (const field of definition.fields) {
+                if (solved[field.id] || isPinned(shadows, field.id))
+                    continue;
+                if (!shadows.has(field.id)) {
+                    const hints = solveHintsOf(field);
+                    if (!hints?.solvable || !hints.governingEquationId)
+                        continue;
+                    const result = solveForField({
+                        definition,
+                        fieldId: field.id,
+                        values: knownValues(shadows, solved),
+                    });
+                    if (result.ok) {
+                        solved[field.id] = {
+                            value: result.value,
+                            viaEquationId: hints.governingEquationId,
+                        };
+                        progressed = true;
+                    }
+                    continue;
+                }
+                // A displaced equation TARGET needs no inversion — the forward pass
+                // (step 3) recomputes it from everything else.
+                if (equationTargeting(field.id) || !isNumericField(field))
+                    continue;
+                for (const equationId of equationsByField[field.id] ?? []) {
+                    const equation = equationById.get(equationId);
+                    if (!equation)
+                        continue;
+                    const result = solveForField({
+                        definition: definitionForDisplacement(definition, field.id, equation),
+                        fieldId: field.id,
+                        values: knownValues(shadows, solved),
+                    });
+                    if (!result.ok)
+                        continue;
+                    solved[field.id] = { value: result.value, viaEquationId: equationId };
+                    progressed = true;
+                    break;
+                }
+            }
+        }
+        return solved;
+    };
+    const evaluateAll = (shadows, solved) => evaluateOutputs({ definition, values: knownValues(shadows, solved) });
+    /**
+     * Can this equation still be satisfied as things stand? Two ways it can't,
+     * and both are asking the same question — is there anywhere left to put the
+     * answer:
+     *
+     *  (i)  every participant is pinned by an entry, so the equation has no free
+     *       field to calculate (Asana 1217042186684890 — filling in the last
+     *       field should show a result, not demand one be cleared by hand);
+     *  (ii) its target is pinned and disagrees with what the rest of the
+     *       calculator makes of it. That's the red conflict chip, caught one step
+     *       before step 4 draws it — and unlike (i) it fires even when the
+     *       disagreement arrives through a field ANOTHER equation solved.
+     */
+    const isOverConstrained = (equation, shadows, results) => {
+        if (participantsOf(equation).every((id) => isPinned(shadows, id)))
+            return true;
+        if (!isPinned(shadows, equation.targetFieldId))
+            return false;
+        const target = findField(definition, equation.targetFieldId);
+        const result = results[equation.targetFieldId];
+        const entered = entries[equation.targetFieldId].value;
+        return (target != null &&
+            result?.ok === true &&
+            typeof entered === 'number' &&
+            !valuesAgree(target, entered, result.value));
+    };
+    /**
+     * Every field whose entry decides this equation's value: its participants,
+     * plus — transitively — the participants of whatever equation supplied a
+     * participant the user isn't holding.
+     *
+     * The reach matters (Asana 1217332117501004). In the reported cuboid, the
+     * surface-area equation reads a length the VOLUME equation solved, so the
+     * stale volume entry is what has to give way — and it appears nowhere in the
+     * surface-area equation itself. Walking only the participants leaves the
+     * newest entry with nothing it may displace, and it lands as a red chip.
+     */
+    const determinants = (equation, shadows, solved) => {
+        const fields = new Set();
+        const visited = new Set();
+        const queue = [equation.id];
+        while (queue.length > 0) {
+            const equationId = queue.pop();
+            if (visited.has(equationId))
+                continue;
+            visited.add(equationId);
+            for (const fieldId of participantsOf(equationById.get(equationId) ?? equation)) {
+                fields.add(fieldId);
+                // A held value is decided by its own entry and nothing further back.
+                if (isPinned(shadows, fieldId))
+                    continue;
+                const via = solved[fieldId]?.viaEquationId ?? equationTargeting(fieldId)?.id;
+                if (via)
+                    queue.push(via);
+            }
+        }
+        return [...fields];
+    };
+    let solved = solveEnabled ? propagate(shadowed) : {};
+    let results = evaluateAll(shadowed, solved);
+    if (solveEnabled) {
+        // DISPLACEMENT. While some equation can't be satisfied, the OLDEST unlocked
+        // entry deciding it yields to the calculation.
+        //
+        // Every lock the user set is a value they asked to hold, so what's left
+        // unlocked is what the calculation may move; age breaks the tie, oldest
+        // first, because the newer number is the better statement of intent.
+        //
+        // The NEWEST entry is spared: it's what the user just typed, and
+        // calculating over it would swallow the keystroke. The one exception is
+        // when it is the ONLY thing left unlocked — sparing it there just paints
+        // the red chip and makes them clear it by hand. Locking that last free
+        // field is what pins the whole equation and brings the chip back.
+        //
+        // A release only sticks if it lands: the field has to end up calculated AND
+        // the equation actually satisfied. Otherwise it's rolled back and the next
+        // oldest tries, then the next — and when none of them work, the conflict
+        // chip stands, which is the honest answer.
+        for (let round = 0; round <= definition.fields.length; round++) {
+            let released = false;
+            for (const equation of definition.equations) {
+                if (!isOverConstrained(equation, shadowed, results))
+                    continue;
+                const byAge = determinants(equation, shadowed, solved)
+                    .filter((id) => isPinned(shadowed, id) && !entries[id].locked)
+                    .sort((a, b) => (entries[a].enteredAt ?? 0) - (entries[b].enteredAt ?? 0) ||
+                    (fieldOrder.get(a) ?? 0) - (fieldOrder.get(b) ?? 0));
+                const candidates = byAge.length === 1 ? byAge : byAge.slice(0, -1);
+                for (const candidate of candidates) {
+                    const trial = new Set(shadowed).add(candidate);
+                    const trialSolved = propagate(trial);
+                    const trialResults = evaluateAll(trial, trialSolved);
+                    const calculated = trialSolved[candidate] != null ||
+                        trialResults[candidate]?.ok === true;
+                    if (!calculated)
+                        continue;
+                    if (isOverConstrained(equation, trial, trialResults))
+                        continue;
+                    shadowed.add(candidate);
+                    solved = trialSolved;
+                    results = trialResults;
+                    released = true;
+                    break;
+                }
+                // One release re-decides which equation owns which field, so rescan
+                // from the top rather than carrying on with stale statuses.
+                if (released)
+                    break;
+            }
+            if (!released)
+                break;
+        }
+    }
+    // 3. The forward pass over entries ∪ solved (`results`, above) serves both
+    //    output display and conflict detection.
+    // 4. Resolve each field.
+    const resolved = {};
+    for (const field of definition.fields) {
+        // A shadowed entry resolves exactly as if the field were empty — computed
+        // if it's an equation target, solved otherwise — so the row shows the
+        // calculated value, not the number the displacement rule set aside.
+        const entry = shadowed.has(field.id) ? undefined : entries[field.id];
+        const equation = equationForField(definition, field.id);
+        const result = equation ? results[field.id] : undefined;
+        const base = {
+            ...EMPTY_RESOLVED,
+            value: null,
+            origin: 'empty',
+            locked: entry?.locked ?? false,
+            attribution: entry?.attribution ?? null,
+        };
+        if (field.kind === ColumnType.Instructions) {
+            resolved[field.id] = base;
+            continue;
+        }
+        if (equation && result) {
+            if (result.ok) {
+                if (entry && typeof entry.value === 'number') {
+                    resolved[field.id] = {
+                        ...base,
+                        value: entry.value,
+                        origin: entryOrigin(entry),
+                        viaEquationId: equation.id,
+                        conflict: valuesAgree(field, entry.value, result.value)
+                            ? null
+                            : { computedValue: result.value },
+                    };
+                }
+                else {
+                    resolved[field.id] = {
+                        ...base,
+                        value: result.value,
+                        origin: 'computed',
+                        viaEquationId: equation.id,
+                    };
+                }
+            }
+            else if (result.reason === 'missing-inputs') {
+                resolved[field.id] = entry
+                    ? { ...base, value: entry.value, origin: entryOrigin(entry) }
+                    : { ...base, missingFieldIds: result.missingFieldIds };
+            }
+            else {
+                resolved[field.id] = {
+                    ...base,
+                    value: entry?.value ?? null,
+                    origin: entry ? entryOrigin(entry) : 'empty',
+                    error: result.error,
+                };
+            }
+            continue;
+        }
+        if (entry) {
+            resolved[field.id] = {
+                ...base,
+                value: entry.value,
+                origin: entryOrigin(entry),
+            };
+            continue;
+        }
+        const solvedField = solved[field.id];
+        if (solvedField) {
+            resolved[field.id] = {
+                ...base,
+                value: solvedField.value,
+                origin: 'solved',
+                viaEquationId: solvedField.viaEquationId,
+            };
+            continue;
+        }
+        // Instructions were handled above, so every remaining kind may carry one.
+        if (field.defaultValue != null) {
+            resolved[field.id] = {
+                ...base,
+                value: field.defaultValue,
+                origin: 'default',
+            };
+            continue;
+        }
+        resolved[field.id] = base;
+    }
+    // 4b. Which calculated fields refuse entry (see ResolvedField.populationBlocked).
+    //     A separate pass because it reads the resolved origin: only a field the
+    //     runtime is CURRENTLY calculating can be blocked — an empty one is just
+    //     waiting for a value, and one showing its own entry can be retyped or
+    //     cleared.
+    for (const field of definition.fields) {
+        const current = resolved[field.id];
+        if (current.origin !== 'computed' && current.origin !== 'solved')
+            continue;
+        const equation = definition.equations.find((candidate) => candidate.id === current.viaEquationId);
+        if (!equation)
+            continue;
+        const others = participantsOf(equation).filter((id) => id !== field.id);
+        // `every` over the ENTERED test as well: a participant left to a default
+        // (no entry at all) can't be unlocked, so telling the user to unlock
+        // something wouldn't be true — that case keeps the conflict chip.
+        if (others.length > 0 &&
+            others.every((id) => entries[id]?.locked === true)) {
+            resolved[field.id] = { ...current, populationBlocked: true };
+        }
+    }
+    // 5. Equation statuses for the link/'=' badges.
+    const equations = definition.equations.map((equation) => {
+        const participantFieldIds = participantsOf(equation);
+        const solvedFieldId = Object.entries(solved).find(([, s]) => s.viaEquationId === equation.id)?.[0] ?? null;
+        const result = results[equation.targetFieldId];
+        const state = solvedFieldId
+            ? 'solved-a-field'
+            : result?.ok
+                ? 'computed'
+                : result && !result.ok && result.reason === 'missing-inputs'
+                    ? 'blocked'
+                    : 'error';
+        return {
+            equationId: equation.id,
+            targetFieldId: equation.targetFieldId,
+            participantFieldIds,
+            state,
+            solvedFieldId,
+        };
+    });
+    return { resolved, equations, equationsByField };
+};
+/**
+ * `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 const isPopulationBlocked = (definition, entries, fieldId) => deriveRuntime(definition, entries).resolved[fieldId]?.populationBlocked ===
+    true;

package/dist/theme/index.d.ts

@@ -0,0 +1,3 @@
+export * from './colors.js';
+export * from './semantic.js';
+export * from './preset.js';

package/dist/theme/index.js

@@ -0,0 +1,3 @@
+export * from './colors.js';
+export * from './semantic.js';
+export * from './preset.js';

package/dist/theme/preset.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Shared Tailwind preset. COLORS ONLY, by design.
+ *
+ * Must never define `content`, `plugins`, `presets`, or `darkMode`:
+ * NativeWind recurses `config.presets[].presets` hunting for its own marker
+ * preset, and a `content` key here would silently narrow the consuming app's
+ * globs.
+ *
+ * Consumed from CJS Tailwind configs, so this is a NAMED export with no
+ * default — that keeps ESM/CJS interop semantics irrelevant:
+ *
+ *   const { boldrPreset } = require('@reekon-tools/boldr-utils/theme/preset');
+ *   module.exports = { presets: [require('nativewind/preset'), boldrPreset] };
+ *
+ * Tailwind loads configs through jiti + sucrase, so requiring this ESM file
+ * from a CJS config works regardless of Node version.
+ *
+ * Note that Tailwind merges `theme.extend` per key with the *app* winning, and
+ * replaces a color key wholesale rather than deep-merging. An app that keeps
+ * its own `colors.background` will silently shadow this preset.
+ */
+export declare const boldrPreset: {
+    theme: {
+        extend: {
+            colors: {
+                background: "#1D1F21";
+                foreground: {
+                    DEFAULT: "#FFFFFF";
+                    disabled: "#626364";
+                };
+                card: {
+                    DEFAULT: "#2B2C2E";
+                    foreground: "#FFFFFF";
+                };
+                popover: {
+                    DEFAULT: "#2B2C2E";
+                    foreground: "#FFFFFF";
+                };
+                muted: {
+                    DEFAULT: "#424345";
+                    foreground: "#9FA0A2";
+                };
+                accent: {
+                    DEFAULT: "#424345";
+                    foreground: "#FFFFFF";
+                };
+                secondary: {
+                    DEFAULT: "#424345";
+                    foreground: "#FFFFFF";
+                };
+                border: {
+                    DEFAULT: "#424345";
+                    strong: "#626364";
+                };
+                input: "#424345";
+                ring: "#FFAD00";
+                primary: {
+                    DEFAULT: "#FFAD00";
+                    foreground: "#1D1F21";
+                };
+                destructive: {
+                    DEFAULT: "#DF6358";
+                    foreground: "#1D1F21";
+                };
+                elevated: {
+                    DEFAULT: "#424345";
+                    foreground: "#FFFFFF";
+                };
+                interactive: {
+                    DEFAULT: "#0066FF";
+                    foreground: "#FFFFFF";
+                };
+                nav: {
+                    DEFAULT: "#2D3843";
+                    foreground: "#FFFFFF";
+                };
+                paper: {
+                    DEFAULT: "#E8EAED";
+                    foreground: "#1D1F21";
+                    field: "#FFFFFF";
+                    line: "#BCBEC2";
+                    muted: "#626364";
+                };
+                tile: {
+                    foreground: "#FFFFFF";
+                    measurement: {
+                        DEFAULT: "#0066FF";
+                        badge: "#50A6FF";
+                    };
+                    formula: {
+                        DEFAULT: "#BD30A8";
+                        badge: "#6C155F";
+                    };
+                    count: {
+                        DEFAULT: "#02274B";
+                        foreground: "#FFFFFF";
+                    };
+                };
+                diagram: {
+                    1: "#2E4C6A";
+                    2: "#4B6074";
+                    3: "#67819A";
+                };
+                tolerance: {
+                    in: {
+                        DEFAULT: "#58A942";
+                        warning: "#00E920";
+                        muted: "#8BB380";
+                    };
+                    out: {
+                        DEFAULT: "#E83D2F";
+                        warning: "#DA1100";
+                        muted: "#DF6358";
+                    };
+                };
+            };
+        };
+    };
+};
+export type BoldrPreset = typeof boldrPreset;

package/dist/theme/preset.js

@@ -0,0 +1,25 @@
+import { boldrColors } from './semantic.js';
+/**
+ * Shared Tailwind preset. COLORS ONLY, by design.
+ *
+ * Must never define `content`, `plugins`, `presets`, or `darkMode`:
+ * NativeWind recurses `config.presets[].presets` hunting for its own marker
+ * preset, and a `content` key here would silently narrow the consuming app's
+ * globs.
+ *
+ * Consumed from CJS Tailwind configs, so this is a NAMED export with no
+ * default — that keeps ESM/CJS interop semantics irrelevant:
+ *
+ *   const { boldrPreset } = require('@reekon-tools/boldr-utils/theme/preset');
+ *   module.exports = { presets: [require('nativewind/preset'), boldrPreset] };
+ *
+ * Tailwind loads configs through jiti + sucrase, so requiring this ESM file
+ * from a CJS config works regardless of Node version.
+ *
+ * Note that Tailwind merges `theme.extend` per key with the *app* winning, and
+ * replaces a color key wholesale rather than deep-merging. An app that keeps
+ * its own `colors.background` will silently shadow this preset.
+ */
+export const boldrPreset = {
+    theme: { extend: { colors: boldrColors } },
+};