@jarenjs/calc 0.34.0

package/dist/types/component/rules.d.ts

@@ -0,0 +1,180 @@
+/**
+ * @file The `calculator` JSLT view. Rules render the
+ * viewModel document produced by `contributeCalcViewModel`. Convention
+ * (mirrors the website views): `match` patterns are absolute from the
+ * document root; `$apply` paths and body `$` are relative to the matched
+ * node; list children wrap `[{ $apply: '…[*]' }]`; a ready-made vnode
+ * (the plot SVG, `$.plot.svg`) splices in verbatim as a query-string
+ * child.
+ *
+ * Mounted by the host with `{ $apply: ['$.ui.calculator', 'calculator'] }`.
+ */
+export declare const CALCULATOR_RULES: ({
+    match: string;
+    mode: string;
+    body: (string | (string | {
+        $apply: string;
+    }[] | {
+        class: string;
+    })[] | (string | (string | {
+        class: string;
+    })[] | {
+        class: string;
+        $if?: undefined;
+    } | {
+        class?: undefined;
+        $if: (string | (string | {
+            class: string;
+        })[])[];
+    })[] | {
+        class: string;
+        $if?: undefined;
+    } | {
+        class?: undefined;
+        $if: (string | (string | (string | {
+            $apply: string;
+        }[] | {
+            class: string;
+        })[] | (string | (string | {
+            class: string;
+        })[] | {
+            class: string;
+        })[] | {
+            class: string;
+        })[])[];
+    } | {
+        class?: undefined;
+        $if: (string | (string | (string | {
+            type: string;
+            class: string;
+            on: {
+                click: {
+                    action: string;
+                };
+            };
+        })[] | (string | {
+            class: string;
+        })[] | {
+            class: string;
+        })[])[];
+    } | {
+        class?: undefined;
+        $if: (string | (string | (string | {}[] | {
+            class: string;
+        })[] | (string | {
+            class: string;
+            $apply?: undefined;
+        } | {
+            class?: undefined;
+            $apply: string;
+        })[] | {
+            class: string;
+        })[])[];
+    } | {
+        class?: undefined;
+        $if: (string | (string | (string | {}[] | {
+            class: string;
+        })[] | (string | (string | {
+            type: string;
+            class: string;
+            value: string;
+            on: {
+                input: {
+                    action: string;
+                };
+            };
+        })[] | (string | {
+            type: string;
+            class: string;
+            on: {
+                click: {
+                    action: string;
+                };
+            };
+        })[] | (string | {
+            $apply: string;
+        }[] | {
+            class: string;
+            on: {
+                change: {
+                    action: string;
+                };
+            };
+        })[] | {
+            class: string;
+        })[] | {
+            $if?: undefined;
+            class: string;
+        } | {
+            class?: undefined;
+            $if: (string | (string | {}[] | (string | {
+                type: string;
+                class: string;
+                on: {
+                    click: {
+                        action: string;
+                    };
+                };
+            })[] | {
+                $if?: undefined;
+                class: string;
+            } | {
+                class?: undefined;
+                $if: (string | (string | {
+                    class: string;
+                })[])[];
+            })[])[];
+        })[])[];
+    } | {
+        class?: undefined;
+        $if: (string | (string | (string | {
+            type: string;
+            class: string;
+            value: string;
+            on: {
+                input: {
+                    action: string;
+                };
+            };
+        })[] | (string | {
+            $apply: string;
+        }[] | {
+            class: string;
+        })[] | {
+            class: string;
+        })[])[];
+    })[];
+} | {
+    match: string;
+    mode: string;
+    body: (string | {
+        type: string;
+        class: {
+            $if: string[];
+        };
+        on: string;
+    })[];
+} | {
+    match: string;
+    mode: string;
+    body: (string | {
+        $apply: string;
+    }[] | {
+        class: string;
+    })[];
+} | {
+    match: string;
+    mode: string;
+    body: (string | {
+        type: string;
+        class: string;
+        on: string;
+    })[];
+} | {
+    match: string;
+    mode: string;
+    body: (string | {
+        value: string;
+        selected: string;
+    })[];
+})[];

package/dist/types/component/schema.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @file The financial-inputs JSON Schema (draft-neutral). Rendered by
+ * `@jarenjs/forms` (`buildFormModel` → `buildFormViewModel`) in the
+ * viewModel, and available as `schemas/financial-inputs.schema.json` for
+ * `validateState`. The calculator holds no formulas — only these inputs.
+ */
+export declare const FINANCIAL_SCHEMA: {
+    type: string;
+    title: string;
+    properties: {
+        nper: {
+            type: string;
+            title: string;
+            minimum: number;
+        };
+        rate: {
+            type: string;
+            title: string;
+        };
+        pv: {
+            type: string;
+            title: string;
+        };
+        pmt: {
+            type: string;
+            title: string;
+        };
+        fv: {
+            type: string;
+            title: string;
+        };
+        solveFor: {
+            title: string;
+            enum: string[];
+        };
+    };
+    required: string[];
+};

package/dist/types/env.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @file Evaluation environments — the operator/function binding sets the
+ * compiler resolves against. The AST is neutral; an
+ * environment gives it meaning. `defaultEnv` covers standard/scientific
+ * (float, `^` = power, angle-aware trig); `programmerEnv` overrides the
+ * bitwise operators with `@jarenjs/core/math/word.js` word math and adds
+ * the programmer functions. Every binding closes over `scope` so angle
+ * mode and word size are read at evaluation time.
+ *
+ * Binding shapes (all monomorphic): `func(args[], scope)`,
+ * `binop(a, b, scope)`, `unop(a, scope)`, `postop(a, scope)`.
+ */
+/**
+ * The default (standard/scientific) environment.
+ * @returns {any}
+ */
+export declare function defaultEnv(): any;
+/**
+ * The programmer environment: word-masked bitwise operators plus the
+ * `and/or/xor/not/shl/shr/rol/ror/mod` functions, read against the
+ * scope's `wordBits`/`signed`.
+ * @returns {any}
+ */
+export declare function programmerEnv(): any;

package/dist/types/errors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @file The engine's parse error, carrying a 1-based `line`/`column`
+ * (the `fail(message, position)` idiom from `packages/json/src/path.js`,
+ * adapted to line/column like the mermaid parser). The evaluate/render
+ * path catches it and never rethrows into the app loop.
+ */
+export declare class CalcParseError extends Error {
+    line: number;
+    column: number;
+    position: number;
+    /**
+     * @param {string} message
+     * @param {number} [line] 1-based line
+     * @param {number} [column] 1-based column
+     * @param {number} [position] 0-based char offset
+     */
+    constructor(message: string, line?: number, column?: number, position?: number);
+}

package/dist/types/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @file `@jarenjs/calc` — the ENGINE (part one of the two-layer
+ * package). Pure functions over data — expression text ⇄ AST ⇄
+ * value, and AST/scene → pure-vnode SVG — that know only `@jarenjs/core`
+ * and `@jarenjs/view`. It imports nothing from the component,
+ * `@jarenjs/app`, `@jarenjs/forms` or the DOM. The boundary is one-way
+ * (the component imports the engine, never the reverse).
+ *
+ * The signature duality mirrors the rest of the suite:
+ * `parseExpression` ⇄ `toExpression` is a round-trip fixed point.
+ */
+export { parseExpression } from './parser/index.js';
+export { toExpression } from './to-expr.js';
+export { compileExpr, evaluate } from './compile.js';
+export { defaultEnv, programmerEnv } from './env.js';
+export { CalcParseError } from './errors.js';
+export { num, constant, variable, unary, postfix, binary, call, CONSTANTS, isConstant, astEqual, CALC_AST_VERSION, } from './ast.js';
+export { plot2d, buildScene2d, scene2dToVnode } from './plot/plot2d.js';
+export { plot3d, buildScene3d, scene3dToVnode } from './plot/plot3d.js';
+export { errorToVnode } from './render/error.js';
+export { createTheme, THEMES, HOST_VARS } from './theme.js';
+export { hashContent } from './utils.js';
+export { MODES, MODE_BY_ID, standardMode, scientificMode, programmerMode, financialMode, converterMode, wordViews, solveTvm, buildAmortization, npvOf, irrOf, convertValue, unitOptions, converterDimensions, CURRENCY, } from './modes/index.js';
+/**
+ * Render an expression to a plot vnode, choosing 2D or 3D by whether the
+ * expression's free variables include a second axis. Error-safe: a parse
+ * failure yields the error vnode, never a throw.
+ *
+ * @param {string} source
+ * @param {{ kind?: '2d'|'3d', [k: string]: any }} [options]
+ * @returns {any} an SVG vnode
+ */
+export declare function calcToVnode(source: string, options?: {
+    kind?: '2d' | '3d';
+    [k: string]: any;
+}): any;
+/**
+ * Render any calc SVG vnode to a standalone SVG string (SSR / headless).
+ * @param {any} vnode
+ * @returns {string}
+ */
+export declare function toSvgString(vnode: any): string;

package/dist/types/modes/converter.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @file The converter mode kernel. Contains
+ * **no factors** — static dimensions call `@jarenjs/core/convert`'s
+ * `convert(...)`, and the **currency** dimension calls the pure
+ * `convertCurrency(value, from, to, rateTable)` with the live table from
+ * `$.calc.rates`. The component's rates layer is the only place that
+ * fetches a rate; this module never does.
+ */
+/** Currency is a fifth, rate-table-backed dimension beside the static ones. */
+export declare const CURRENCY = "currency";
+/**
+ * All selectable dimensions (static core dimensions + currency).
+ * @returns {string[]}
+ */
+export declare function converterDimensions(): string[];
+/**
+ * The unit options for a dimension. Static dimensions come from core;
+ * the currency dimension enumerates the codes present in `rates`.
+ * @param {string} dimension
+ * @param {any} [rates] the rate table (currency only)
+ * @returns {Array<{ id: string, symbol: string }>}
+ */
+export declare function unitOptions(dimension: string, rates?: any): Array<{
+    id: string;
+    symbol: string;
+}>;
+/**
+ * Convert a value in a dimension. Delegates entirely to core: static
+ * dimensions to `convert`, currency to the pure `convertCurrency`.
+ * Returns `NaN` (never throws) so the display path stays total.
+ *
+ * @param {string} dimension @param {number} value @param {string} from @param {string} to
+ * @param {any} [rates] the rate table (currency only)
+ * @returns {number}
+ */
+export declare function convertValue(dimension: string, value: number, from: string, to: string, rates?: any): number;
+/** Format a converter result. @param {number} value */
+export declare function format(value: number): string;
+export declare const converterMode: {
+    id: string;
+    label: string;
+    dimensions: typeof converterDimensions;
+    unitOptions: typeof unitOptions;
+    convertValue: typeof convertValue;
+    format: typeof format;
+};

package/dist/types/modes/financial.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @file The financial mode kernel. Contains **no
+ * formulas** — every number comes from `@jarenjs/core/finance`. This is
+ * pure orchestration: the solve-for-unknown dispatcher (given any four of
+ * {N, I/Y, PV, PMT, FV}, pick the core function for the fifth) plus thin
+ * wrappers that turn a cash-flow / amortization request into core calls.
+ */
+/** The five TVM variables the panel exposes. */
+export declare const TVM_FIELDS: string[];
+/**
+ * Solve for the one unknown TVM variable. `rate` is a **percent** per
+ * period on the way in and out (e.g. 6 ⇒ 6%); the other four are plain
+ * numbers under the standard sign convention.
+ *
+ * @param {{ nper?: number, rate?: number, pv?: number, pmt?: number, fv?: number, type?: number, solveFor: string }} inputs
+ * @returns {number}
+ */
+export declare function solveTvm(inputs: {
+    nper?: number;
+    rate?: number;
+    pv?: number;
+    pmt?: number;
+    fv?: number;
+    type?: number;
+    solveFor: string;
+}): number;
+/**
+ * Amortization series (delegates to core), ready to become a table/plot.
+ * @param {{ principal: number, rate: number, nper: number, type?: number }} inputs
+ * @returns {import('@jarenjs/core/finance/amortization').AmortRow[]}
+ */
+export declare function buildAmortization(inputs: {
+    principal: number;
+    rate: number;
+    nper: number;
+    type?: number;
+}): import('@jarenjs/core/finance/amortization').AmortRow[];
+/**
+ * NPV of a discount rate (percent) and a comma/space-separated cash-flow
+ * string or array.
+ * @param {number} ratePct @param {number[]|string} cashflows
+ * @returns {number}
+ */
+export declare function npvOf(ratePct: number, cashflows: number[] | string): number;
+/**
+ * IRR (percent) of a cash-flow series.
+ * @param {number[]|string} cashflows
+ * @returns {number}
+ */
+export declare function irrOf(cashflows: number[] | string): number;
+/** Format a money-ish result. @param {number} value */
+export declare function format(value: number): string;
+export declare const financialMode: {
+    id: string;
+    label: string;
+    tvmFields: string[];
+    solveTvm: typeof solveTvm;
+    format: typeof format;
+};

package/dist/types/modes/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @file Mode-kernel barrel. Each mode is a data-driven descriptor
+ * (keypad/panel + function-binding env + formatter); switching mode is a
+ * patch of `$.calc.mode`.
+ */
+export { standardMode } from './standard.js';
+export { scientificMode } from './scientific.js';
+export { programmerMode, wordViews, BASES, WORD_SIZES } from './programmer.js';
+export { financialMode, solveTvm, buildAmortization, npvOf, irrOf } from './financial.js';
+export { converterMode, convertValue, unitOptions, converterDimensions, CURRENCY } from './converter.js';
+/** All modes, in selector order. */
+export declare const MODES: ({
+    id: string;
+    label: string;
+    env: any;
+    keypad: {
+        label: string;
+        k: string;
+        tone?: string;
+        span?: number;
+    }[][];
+    format: typeof import("./standard.js").format;
+} | {
+    id: string;
+    label: string;
+    tvmFields: string[];
+    solveTvm: typeof import("./financial.js").solveTvm;
+    format: typeof import("./financial.js").format;
+} | {
+    id: string;
+    label: string;
+    dimensions: typeof import("./converter.js").converterDimensions;
+    unitOptions: typeof import("./converter.js").unitOptions;
+    convertValue: typeof import("./converter.js").convertValue;
+    format: typeof import("./converter.js").format;
+})[];
+/** Mode descriptor by id. @type {Record<string, any>} */
+export declare const MODE_BY_ID: Record<string, any>;

package/dist/types/modes/programmer.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @file The programmer mode kernel. Binds the
+ * word-math environment (`@jarenjs/core/math/word.js`) so `& | << >> ~`
+ * and the `and/or/xor/not/shl/shr/rol/ror/mod` functions operate at the
+ * chosen word size (8/16/32/64) and signedness. Literals are written with
+ * `0x`/`0o`/`0b` prefixes; the display shows all four bases live.
+ *
+ * No formulas live here — the reusable word math is in core; this module
+ * is the keypad + the four-base view derivation.
+ */
+export declare const BASES: string[];
+export declare const WORD_SIZES: number[];
+/** @type {Array<Array<{label:string,k:string,tone?:string,span?:number}>>} */
+export declare const KEYPAD: Array<Array<{
+    label: string;
+    k: string;
+    tone?: string;
+    span?: number;
+}>>;
+/**
+ * The live four-base view of an integer value at the given word size.
+ * @param {number} value @param {number} [wordBits] @param {boolean} [signed]
+ * @returns {{ hex: string, dec: string, oct: string, bin: string }}
+ */
+export declare function wordViews(value: number, wordBits?: number, signed?: boolean): {
+    hex: string;
+    dec: string;
+    oct: string;
+    bin: string;
+};
+/**
+ * Format the primary display in the currently-selected base.
+ * @param {number} value @param {any} [state]
+ * @returns {string}
+ */
+export declare function format(value: number, state?: any): string;
+export declare const programmerMode: {
+    id: string;
+    label: string;
+    env: any;
+    keypad: {
+        label: string;
+        k: string;
+        tone?: string;
+        span?: number;
+    }[][];
+    format: typeof format;
+    bases: string[];
+    wordSizes: number[];
+};

package/dist/types/modes/scientific.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @file The scientific mode kernel: the standard keypad plus the
+ * A1 transcendentals as function-insert keys, constants, factorial and an
+ * angle-mode toggle. It binds the same float environment as standard —
+ * the transcendentals were already in it — so no formulas live here.
+ */
+import { format } from './standard.js';
+/** @type {Array<Array<{label:string,k:string,tone?:string,span?:number}>>} */
+export declare const KEYPAD: Array<Array<{
+    label: string;
+    k: string;
+    tone?: string;
+    span?: number;
+}>>;
+export declare const scientificMode: {
+    id: string;
+    label: string;
+    env: any;
+    keypad: {
+        label: string;
+        k: string;
+        tone?: string;
+        span?: number;
+    }[][];
+    format: typeof format;
+    /** angle modes offered by the toggle */
+    angleModes: string[];
+};

package/dist/types/modes/standard.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @file The standard mode kernel: a data-driven
+ * keypad descriptor, the function-binding environment the compiler uses,
+ * and a display formatter. A key is `{ label, k, tone?, span? }`; `k` is
+ * the token appended to the expression entry, or a command (`=`, `C`,
+ * `back`). Switching mode is just a patch of `$.calc.mode`.
+ */
+/** @type {Array<Array<{label:string,k:string,tone?:string,span?:number}>>} */
+export declare const KEYPAD: Array<Array<{
+    label: string;
+    k: string;
+    tone?: string;
+    span?: number;
+}>>;
+/**
+ * Format a numeric result for the display.
+ * @param {number} value @param {any} [state]
+ * @returns {string}
+ */
+export declare function format(value: number, state?: any): string;
+export declare const standardMode: {
+    id: string;
+    label: string;
+    env: any;
+    keypad: {
+        label: string;
+        k: string;
+        tone?: string;
+        span?: number;
+    }[][];
+    format: typeof format;
+};

package/dist/types/parser/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @file `parseExpression(text, opts) → ExprAST`. A char-offset
+ * recursive-descent, precedence-climbing parser in the repository idiom
+ * (module-const sticky regexes for the number/identifier leaves, a
+ * `fail(msg, pos)` that raises `CalcParseError` with 1-based line/column).
+ * No `eval`, no per-parse `RegExp` allocation.
+ *
+ * Grammar (low → high precedence), all left-associative except power
+ * (right) and the prefix unaries:
+ *
+ *   or      := and    ('|' and)*
+ *   and     := shift  ('&' shift)*
+ *   shift   := add    (('<<'|'>>') add)*
+ *   add     := mul    (('+'|'-') mul)*
+ *   mul     := unary  (('*'|'/') unary)*
+ *   unary   := ('-'|'+'|'~') unary | power
+ *   power   := postfix ('^' unary)?           // right-assoc via unary
+ *   postfix := primary ('!' | '%')*
+ *   primary := number | const | ident | ident '(' args ')' | '(' or ')'
+ *
+ * Number bases (`0x`/`0o`/`0b`) and scientific notation are recognized at
+ * the leaf; the AST keeps only the numeric value.
+ */
+/**
+ * Parse an expression string into an `ExprAST`.
+ * @param {string} text
+ * @param {{ [k: string]: any }} [opts]
+ * @returns {any}
+ */
+export declare function parseExpression(text: string, opts?: {
+    [k: string]: any;
+}): any;

package/dist/types/plot/plot2d.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @file The x·y plotter. `plot2d` compiles `f(x)`
+ * ONCE, samples the domain into `Float64Array` buffers, maps them to the
+ * viewport with a standard linear remap, and emits axes/grid/ticks plus one
+ * `<path>` polyline per series — breaking the path on NaN/±Inf and at
+ * asymptote jumps. The intermediate **scene** is geometry-as-plain-JSON
+ * (deterministic → golden-geometry tests); `scene2dToVnode` turns it into
+ * pure-vnode SVG.
+ */
+export type Plot2dConfig = {
+    /**
+     * one or more source expressions
+     */
+    expr?: string | string[];
+    domain?: [number, number];
+    /**
+     * omit for auto-range
+     */
+    range?: [number, number];
+    samples?: number;
+    width?: number;
+    height?: number;
+    /**
+     * independent variable name (default 'x')
+     */
+    variable?: string;
+    /**
+     * extra variables in scope
+     */
+    scope?: any;
+    /**
+     * evaluation environment (default float)
+     */
+    env?: any;
+    theme?: any;
+};
+/**
+ * @typedef {object} Plot2dConfig
+ * @property {string|string[]} [expr] one or more source expressions
+ * @property {[number,number]} [domain]
+ * @property {[number,number]} [range] omit for auto-range
+ * @property {number} [samples]
+ * @property {number} [width] @property {number} [height]
+ * @property {string} [variable] independent variable name (default 'x')
+ * @property {any} [scope] extra variables in scope
+ * @property {any} [env] evaluation environment (default float)
+ * @property {any} [theme]
+ */
+/**
+ * Build the geometry-as-JSON scene.
+ * @param {string|string[]|Plot2dConfig} exprOrConfig
+ * @param {Plot2dConfig} [options]
+ * @returns {any}
+ */
+export declare function buildScene2d(exprOrConfig: string | string[] | Plot2dConfig, options?: Plot2dConfig): any;
+/**
+ * Render a 2D scene into a pure-vnode SVG.
+ * @param {any} scene @param {{ theme?: any }} [options]
+ * @returns {any}
+ */
+export declare function scene2dToVnode(scene: any, options?: {
+    theme?: any;
+}): any;
+/**
+ * Compile → sample → SVG vnode in one call.
+ * @param {string|string[]|Plot2dConfig} exprOrConfig
+ * @param {Plot2dConfig} [options]
+ * @returns {any}
+ */
+export declare function plot2d(exprOrConfig: string | string[] | Plot2dConfig, options?: Plot2dConfig): any;