@jarenjs/calc 0.34.0

package/src/component/rules.js

@@ -0,0 +1,118 @@
+//@ts-check
+/**
+ * @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 const CALCULATOR_RULES = [
+  {
+    match: '$.ui.calculator', mode: 'calculator',
+    body: ['div', { class: 'calc' },
+      ['div', { class: 'calc-modes' }, [{ $apply: '$.modes[*]' }]],
+
+      ['div', { class: 'calc-display' },
+        ['div', { class: 'calc-entry' }, '$.display.entry'],
+        ['div', { class: 'calc-result' }, '$.display.result'],
+        { $if: ['$.display.error', ['div', { class: 'calc-err' }, '$.display.error']] },
+      ],
+
+      // programmer four-base view + word size toggles
+      { $if: ['$.isProgrammer', ['div', { class: 'calc-bases' },
+        ['div', { class: 'calc-baserow' }, ['span', { class: 'calc-baselabel' }, 'HEX'], ['span', { class: 'calc-baseval' }, '$.bases.views.hex']],
+        ['div', { class: 'calc-baserow' }, ['span', { class: 'calc-baselabel' }, 'DEC'], ['span', { class: 'calc-baseval' }, '$.bases.views.dec']],
+        ['div', { class: 'calc-baserow' }, ['span', { class: 'calc-baselabel' }, 'OCT'], ['span', { class: 'calc-baseval' }, '$.bases.views.oct']],
+        ['div', { class: 'calc-baserow' }, ['span', { class: 'calc-baselabel' }, 'BIN'], ['span', { class: 'calc-baseval' }, '$.bases.views.bin']],
+        ['div', { class: 'calc-wordopts' }, [{ $apply: '$.bases.wordOptions[*]' }]],
+      ]] },
+
+      // scientific angle mode toggle
+      { $if: ['$.isScientific', ['div', { class: 'calc-angle' }, [{ $apply: '$.angle.options[*]' }]]] },
+
+      // keypad (standard / scientific / programmer)
+      { $if: ['$.keypad', ['div', { class: 'calc-keypad' }, [{ $apply: '$.keypad[*]' }]]] },
+
+      // memory row (present for calculator-style modes)
+      { $if: ['$.keypad', ['div', { class: 'calc-mem' },
+        ['button', { type: 'button', class: 'calc-key calc-key-mem', on: { click: { action: 'calc/mem-add' } } }, 'M+'],
+        ['button', { type: 'button', class: 'calc-key calc-key-mem', on: { click: { action: 'calc/mem-clear' } } }, 'MC'],
+        ['span', { class: 'calc-memval' }, 'M = ', '$.memory'],
+      ]] },
+
+      // financial panel — the form comes from @jarenjs/forms
+      { $if: ['$.financial', ['div', { class: 'calc-financial' },
+        ['div', { class: 'calc-fin-form' }, { $apply: '$.financial.form' }],
+        ['div', { class: 'calc-fin-result' }, ['span', {}, 'Result ('], ['span', {}, '$.financial.solveFor'], ['span', {}, '): '], ['strong', {}, '$.financial.result']],
+      ]] },
+
+      // converter panel — every conversion via @jarenjs/core/convert
+      { $if: ['$.converter', ['div', { class: 'calc-converter' },
+        ['label', { class: 'calc-conv-dimlabel' }, 'Dimension ',
+          ['select', { class: 'calc-dim', on: { change: { action: 'calc/conv-dim' } } }, [{ $apply: '$.converter.dimensions[*]' }]],
+        ],
+        ['div', { class: 'calc-conv-row' },
+          ['input', { type: 'text', class: 'calc-conv-input', value: '$.converter.value', on: { input: { action: 'calc/conv-value' } } }],
+          ['select', { class: 'calc-conv-from', on: { change: { action: 'calc/conv-from' } } }, [{ $apply: '$.converter.unitsFrom[*]' }]],
+          ['button', { type: 'button', class: 'calc-swap', on: { click: { action: 'calc/conv-swap' } } }, '⇄'],
+          ['select', { class: 'calc-conv-to', on: { change: { action: 'calc/conv-to' } } }, [{ $apply: '$.converter.unitsTo[*]' }]],
+        ],
+        ['div', { class: 'calc-conv-result' }, ['strong', {}, '$.converter.result']],
+        { $if: ['$.converter.isCurrency', ['div', { class: 'calc-rates' },
+          ['span', {}, 'rates: '], ['span', {}, '$.converter.rates.status'],
+          { $if: ['$.converter.rates.stale', ['span', { class: 'calc-rates-stale' }, ' · static fallback']] },
+          ['button', { type: 'button', class: 'calc-rates-refresh', on: { click: { action: 'calc/rates-refresh' } } }, '↻'],
+        ]] },
+      ]] },
+
+      // plot panel (standard / scientific)
+      { $if: ['$.plot', ['div', { class: 'calc-plot-panel' },
+        ['div', { class: 'calc-plot-kinds' }, [{ $apply: '$.plot.kinds[*]' }]],
+        ['input', { type: 'text', class: 'calc-plot-expr', value: '$.plot.expr', on: { input: { action: 'calc/plot-expr' } } }],
+        ['div', { class: 'calc-plot-svg' }, '$.plot.svg'],
+      ]] },
+
+      // history tape
+      { $if: ['$.tape', ['div', { class: 'calc-tape' }, [{ $apply: '$.tape[*]' }]]] },
+    ],
+  },
+
+  { match: '$.ui.calculator.modes[*]', mode: 'calculator',
+    body: ['button', { type: 'button', class: { $if: ['$.active', 'calc-mode calc-mode-active', 'calc-mode'] }, on: '$.on' }, '$.label'] },
+
+  { match: '$.ui.calculator.keypad[*]', mode: 'calculator',
+    body: ['div', { class: 'calc-row' }, [{ $apply: '$.keys[*]' }]] },
+
+  { match: '$.ui.calculator.keypad[*].keys[*]', mode: 'calculator',
+    body: ['button', { type: 'button', class: '$.cls', on: '$.on' }, '$.label'] },
+
+  { match: '$.ui.calculator.angle.options[*]', mode: 'calculator',
+    body: ['button', { type: 'button', class: { $if: ['$.active', 'calc-angle-btn active', 'calc-angle-btn'] }, on: '$.on' }, '$.label'] },
+
+  { match: '$.ui.calculator.bases.wordOptions[*]', mode: 'calculator',
+    body: ['button', { type: 'button', class: { $if: ['$.active', 'calc-word active', 'calc-word'] }, on: '$.on' }, '$.label'] },
+
+  { match: '$.ui.calculator.plot.kinds[*]', mode: 'calculator',
+    body: ['button', { type: 'button', class: { $if: ['$.active', 'calc-plotkind active', 'calc-plotkind'] }, on: '$.on' }, '$.label'] },
+
+  { match: '$.ui.calculator.converter.dimensions[*]', mode: 'calculator',
+    body: ['option', { value: '$.id', selected: '$.selected' }, '$.label'] },
+
+  { match: '$.ui.calculator.converter.unitsFrom[*]', mode: 'calculator',
+    body: ['option', { value: '$.id', selected: '$.selected' }, '$.symbol'] },
+
+  { match: '$.ui.calculator.converter.unitsTo[*]', mode: 'calculator',
+    body: ['option', { value: '$.id', selected: '$.selected' }, '$.symbol'] },
+
+  { match: '$.ui.calculator.tape[*]', mode: 'calculator',
+    body: ['div', { class: 'calc-tape-row' },
+      ['span', { class: 'calc-tape-expr' }, '$.expr'],
+      ['span', { class: 'calc-tape-eq' }, ' = '],
+      ['span', { class: 'calc-tape-res' }, '$.result'],
+    ] },
+];

package/src/component/schema.js

@@ -0,0 +1,24 @@
+//@ts-check
+/**
+ * @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 const FINANCIAL_SCHEMA = {
+  type: 'object',
+  title: 'Time Value of Money',
+  properties: {
+    nper: { type: 'number', title: 'N — number of periods', minimum: 0 },
+    rate: { type: 'number', title: 'I/Y — interest % per period' },
+    pv: { type: 'number', title: 'PV — present value' },
+    pmt: { type: 'number', title: 'PMT — payment' },
+    fv: { type: 'number', title: 'FV — future value' },
+    solveFor: {
+      title: 'Solve for',
+      enum: ['pmt', 'pv', 'fv', 'nper', 'rate'],
+    },
+  },
+  required: ['solveFor'],
+};

package/src/env.js

@@ -0,0 +1,163 @@
+//@ts-check
+/**
+ * @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)`.
+ */
+
+import {
+  Float64,
+  mathf64_sin, mathf64_cos, mathf64_tan, mathf64_asin, mathf64_acos, mathf64_atan,
+  mathf64_sinh, mathf64_cosh, mathf64_tanh, mathf64_atan2,
+  mathf64_log, mathf64_log2, mathf64_log10, mathf64_exp, mathf64_expm1,
+  mathf64_sqrt, mathf64_cbrt, mathf64_abs, mathf64_floor, mathf64_ceil,
+  mathf64_round, mathf64_min, mathf64_max, mathf64_pow,
+  toWord, wAnd, wOr, wXor, wNot, wShl, wShr, wRol, wRor, wMod,
+} from '@jarenjs/core/math';
+import { CONSTANTS } from './ast.js';
+
+/** Convert a user angle to radians per the scope's angle mode. */
+function toRad(x, scope) {
+  const m = scope && scope.angleMode;
+  if (m === 'deg') return (x * Math.PI) / 180;
+  if (m === 'grad') return (x * Math.PI) / 200;
+  return x;
+}
+/** Convert a radian result back to the scope's angle mode. */
+function fromRad(x, scope) {
+  const m = scope && scope.angleMode;
+  if (m === 'deg') return (x * 180) / Math.PI;
+  if (m === 'grad') return (x * 200) / Math.PI;
+  return x;
+}
+
+/** Coerce to a BigInt word using the scope's word size/sign. */
+function big(v, scope) {
+  return toWord(BigInt(Math.trunc(+v)), scope?.wordBits ?? 32, scope?.signed ?? false);
+}
+
+/** @type {Record<string, (args: number[], scope: any) => number>} */
+const FLOAT_FUNCS = {
+  sin: (a, s) => mathf64_sin(toRad(a[0], s)),
+  cos: (a, s) => mathf64_cos(toRad(a[0], s)),
+  tan: (a, s) => mathf64_tan(toRad(a[0], s)),
+  asin: (a, s) => fromRad(mathf64_asin(a[0]), s),
+  acos: (a, s) => fromRad(mathf64_acos(a[0]), s),
+  atan: (a, s) => fromRad(mathf64_atan(a[0]), s),
+  atan2: (a, s) => fromRad(mathf64_atan2(a[0], a[1]), s),
+  sinh: (a) => mathf64_sinh(a[0]),
+  cosh: (a) => mathf64_cosh(a[0]),
+  tanh: (a) => mathf64_tanh(a[0]),
+  ln: (a) => mathf64_log(a[0]),
+  log: (a) => (a.length > 1 ? Float64.logBase(a[0], a[1]) : mathf64_log10(a[0])),
+  log2: (a) => mathf64_log2(a[0]),
+  log10: (a) => mathf64_log10(a[0]),
+  exp: (a) => mathf64_exp(a[0]),
+  expm1: (a) => mathf64_expm1(a[0]),
+  sqrt: (a) => mathf64_sqrt(a[0]),
+  cbrt: (a) => mathf64_cbrt(a[0]),
+  root: (a) => Float64.nthroot(a[0], a[1]),
+  abs: (a) => mathf64_abs(a[0]),
+  sign: (a) => Float64.sign(a[0]),
+  floor: (a) => mathf64_floor(a[0]),
+  ceil: (a) => mathf64_ceil(a[0]),
+  round: (a) => (a.length > 1 ? Float64.roundTo(a[0], a[1]) : mathf64_round(a[0])),
+  trunc: (a) => Math.trunc(a[0]),
+  min: (a) => mathf64_min(...a),
+  max: (a) => mathf64_max(...a),
+  hypot: (a) => Float64.hypot(...a),
+  fact: (a) => Float64.factorial(a[0]),
+  gamma: (a) => Float64.gamma(a[0]),
+  pow: (a) => mathf64_pow(a[0], a[1]),
+  mod: (a) => a[0] % a[1],
+};
+
+/** @type {Record<string, (a: number, b: number, scope: any) => number>} */
+const FLOAT_BINOPS = {
+  '+': (a, b) => a + b,
+  '-': (a, b) => a - b,
+  '*': (a, b) => a * b,
+  '/': (a, b) => a / b,
+  '^': (a, b) => mathf64_pow(a, b),
+  '&': (a, b) => (a | 0) & (b | 0),
+  '|': (a, b) => (a | 0) | (b | 0),
+  '<<': (a, b) => (a | 0) << (b | 0),
+  '>>': (a, b) => (a | 0) >> (b | 0),
+};
+
+/** @type {Record<string, (a: number, scope: any) => number>} */
+const FLOAT_UNOPS = {
+  '-': (a) => -a,
+  '+': (a) => a,
+  '~': (a) => ~(a | 0),
+};
+
+/** @type {Record<string, (a: number, scope: any) => number>} */
+const FLOAT_POSTOPS = {
+  '!': (a) => Float64.factorial(a),
+  '%': (a) => a / 100,
+};
+
+/**
+ * The default (standard/scientific) environment.
+ * @returns {any}
+ */
+export function defaultEnv() {
+  return {
+    constants: { ...CONSTANTS },
+    funcs: FLOAT_FUNCS,
+    binops: FLOAT_BINOPS,
+    unops: FLOAT_UNOPS,
+    postops: FLOAT_POSTOPS,
+  };
+}
+
+/** Word-aware programmer functions (return `Number`; see the >2^53 caveat in docs). */
+const WORD_FUNCS = {
+  ...FLOAT_FUNCS,
+  and: (a, s) => Number(wAnd(big(a[0], s), big(a[1], s), s?.wordBits ?? 32, s?.signed ?? false)),
+  or: (a, s) => Number(wOr(big(a[0], s), big(a[1], s), s?.wordBits ?? 32, s?.signed ?? false)),
+  xor: (a, s) => Number(wXor(big(a[0], s), big(a[1], s), s?.wordBits ?? 32, s?.signed ?? false)),
+  not: (a, s) => Number(wNot(big(a[0], s), s?.wordBits ?? 32, s?.signed ?? false)),
+  shl: (a, s) => Number(wShl(big(a[0], s), BigInt(Math.trunc(a[1])), s?.wordBits ?? 32, s?.signed ?? false)),
+  shr: (a, s) => Number(wShr(big(a[0], s), BigInt(Math.trunc(a[1])), s?.wordBits ?? 32, s?.signed ?? false)),
+  rol: (a, s) => Number(wRol(big(a[0], s), BigInt(Math.trunc(a[1])), s?.wordBits ?? 32, s?.signed ?? false)),
+  ror: (a, s) => Number(wRor(big(a[0], s), BigInt(Math.trunc(a[1])), s?.wordBits ?? 32, s?.signed ?? false)),
+  mod: (a, s) => Number(wMod(big(a[0], s), big(a[1], s), s?.wordBits ?? 32, s?.signed ?? false)),
+};
+
+const WORD_BINOPS = {
+  ...FLOAT_BINOPS,
+  '&': (a, b, s) => Number(wAnd(big(a, s), big(b, s), s?.wordBits ?? 32, s?.signed ?? false)),
+  '|': (a, b, s) => Number(wOr(big(a, s), big(b, s), s?.wordBits ?? 32, s?.signed ?? false)),
+  '<<': (a, b, s) => Number(wShl(big(a, s), BigInt(Math.trunc(b)), s?.wordBits ?? 32, s?.signed ?? false)),
+  '>>': (a, b, s) => Number(wShr(big(a, s), BigInt(Math.trunc(b)), s?.wordBits ?? 32, s?.signed ?? false)),
+};
+
+const WORD_UNOPS = {
+  ...FLOAT_UNOPS,
+  '~': (a, s) => Number(wNot(big(a, s), s?.wordBits ?? 32, s?.signed ?? false)),
+};
+
+/**
+ * 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 function programmerEnv() {
+  return {
+    constants: { ...CONSTANTS },
+    funcs: WORD_FUNCS,
+    binops: WORD_BINOPS,
+    unops: WORD_UNOPS,
+    postops: FLOAT_POSTOPS,
+  };
+}

package/src/errors.js

@@ -0,0 +1,23 @@
+//@ts-check
+/**
+ * @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 class CalcParseError extends Error {
+  /**
+   * @param {string} message
+   * @param {number} [line] 1-based line
+   * @param {number} [column] 1-based column
+   * @param {number} [position] 0-based char offset
+   */
+  constructor(message, line = 1, column = 1, position = 0) {
+    super(message);
+    this.name = 'CalcParseError';
+    this.line = line;
+    this.column = column;
+    this.position = position;
+  }
+}

package/src/index.js

@@ -0,0 +1,85 @@
+//@ts-check
+/**
+ * @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.
+ */
+
+import { renderToString } from '@jarenjs/view';
+import { evaluate } from './compile.js';
+import { plot2d } from './plot/plot2d.js';
+import { plot3d } from './plot/plot3d.js';
+import { errorToVnode } from './render/error.js';
+
+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 function calcToVnode(source, options = {}) {
+  const ev = evaluate(source, {}, { env: options.env });
+  if (!ev.ok && ev.error && ev.error.line !== undefined) {
+    // a genuine parse error (not just an unbound variable like x/y)
+    if (/unexpected|expected|invalid|empty/.test(ev.error.message)) {
+      return errorToVnode(ev.error, options);
+    }
+  }
+  const kind = options.kind ?? (usesVar(source, 'y') ? '3d' : '2d');
+  try {
+    return kind === '3d' ? plot3d(source, options) : plot2d(source, options);
+  }
+  catch (err) {
+    return errorToVnode({ message: String(/** @type {any} */ (err)?.message ?? err) }, options);
+  }
+}
+
+/** Cheap check for whether a source references a bare identifier `name`. */
+function usesVar(source, name) {
+  try {
+    const re = new RegExp(`(^|[^A-Za-z0-9_])${name}([^A-Za-z0-9_(]|$)`);
+    return re.test(source);
+  }
+  catch {
+    return false;
+  }
+}
+
+/**
+ * Render any calc SVG vnode to a standalone SVG string (SSR / headless).
+ * @param {any} vnode
+ * @returns {string}
+ */
+export function toSvgString(vnode) {
+  return renderToString(vnode);
+}

package/src/modes/converter.js

@@ -0,0 +1,73 @@
+//@ts-check
+/**
+ * @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.
+ */
+
+import {
+  convert, unitsOf, dimensions, convertCurrency, currenciesOf,
+} from '@jarenjs/core/convert';
+import { formatNumber } from '@jarenjs/core/math';
+
+/** Currency is a fifth, rate-table-backed dimension beside the static ones. */
+export const CURRENCY = 'currency';
+
+/**
+ * All selectable dimensions (static core dimensions + currency).
+ * @returns {string[]}
+ */
+export function converterDimensions() {
+  return [...dimensions(), CURRENCY];
+}
+
+/**
+ * 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 function unitOptions(dimension, rates) {
+  if (dimension === CURRENCY) {
+    return currenciesOf(rates ?? {}).map((code) => ({ id: code, symbol: code }));
+  }
+  return unitsOf(dimension).map((u) => ({ id: u.id, symbol: u.symbol }));
+}
+
+/**
+ * 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 function convertValue(dimension, value, from, to, rates) {
+  try {
+    if (dimension === CURRENCY) return convertCurrency(value, from, to, rates ?? {});
+    return convert(value, from, to);
+  }
+  catch {
+    return NaN;
+  }
+}
+
+/** Format a converter result. @param {number} value */
+export function format(value) {
+  if (!Number.isFinite(value)) return '—';
+  return formatNumber(value, { notation: 'auto', precision: 8, group: true });
+}
+
+export const converterMode = {
+  id: 'converter',
+  label: 'Converter',
+  dimensions: converterDimensions,
+  unitOptions,
+  convertValue,
+  format,
+};

package/src/modes/financial.js

@@ -0,0 +1,89 @@
+//@ts-check
+/**
+ * @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.
+ */
+
+import {
+  pmt, pv, fv, nper, rate,
+  npv, irr, amortizationSchedule,
+} from '@jarenjs/core/finance';
+import { formatNumber } from '@jarenjs/core/math';
+
+/** The five TVM variables the panel exposes. */
+export const TVM_FIELDS = ['nper', 'rate', 'pv', 'pmt', 'fv'];
+
+/**
+ * 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 function solveTvm(inputs) {
+  const N = +inputs.nper;
+  const i = +inputs.rate / 100;
+  const PV = +inputs.pv;
+  const PMT = +inputs.pmt;
+  const FV = +inputs.fv;
+  const type = inputs.type ?? 0;
+  switch (inputs.solveFor) {
+    case 'pmt': return pmt(i, N, PV, FV, type);
+    case 'pv': return pv(i, N, PMT, FV, type);
+    case 'fv': return fv(i, N, PMT, PV, type);
+    case 'nper': return nper(i, PMT, PV, FV, type);
+    case 'rate': return rate(N, PMT, PV, FV, type) * 100;
+    default: return NaN;
+  }
+}
+
+/**
+ * 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 function buildAmortization(inputs) {
+  return amortizationSchedule(+inputs.principal, +inputs.rate / 100, +inputs.nper, { type: inputs.type ?? 0 });
+}
+
+/**
+ * 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 function npvOf(ratePct, cashflows) {
+  return npv(ratePct / 100, parseFlows(cashflows));
+}
+
+/**
+ * IRR (percent) of a cash-flow series.
+ * @param {number[]|string} cashflows
+ * @returns {number}
+ */
+export function irrOf(cashflows) {
+  return irr(parseFlows(cashflows)) * 100;
+}
+
+/** @param {number[]|string} flows */
+function parseFlows(flows) {
+  if (Array.isArray(flows)) return flows.map(Number);
+  return String(flows).split(/[\s,]+/).filter((s) => s !== '').map(Number);
+}
+
+/** Format a money-ish result. @param {number} value */
+export function format(value) {
+  return formatNumber(value, { notation: 'fixed', precision: 2, group: true });
+}
+
+export const financialMode = {
+  id: 'financial',
+  label: 'Financial',
+  tvmFields: TVM_FIELDS,
+  solveTvm,
+  format,
+};

package/src/modes/index.js

@@ -0,0 +1,24 @@
+//@ts-check
+/**
+ * @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';
+
+import { standardMode } from './standard.js';
+import { scientificMode } from './scientific.js';
+import { programmerMode } from './programmer.js';
+import { financialMode } from './financial.js';
+import { converterMode } from './converter.js';
+
+/** All modes, in selector order. */
+export const MODES = [standardMode, scientificMode, programmerMode, financialMode, converterMode];
+
+/** Mode descriptor by id. @type {Record<string, any>} */
+export const MODE_BY_ID = Object.fromEntries(MODES.map((m) => [m.id, m]));

package/src/modes/programmer.js

@@ -0,0 +1,69 @@
+//@ts-check
+/**
+ * @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.
+ */
+
+import { toWord, toBase } from '@jarenjs/core/math';
+import { programmerEnv } from '../env.js';
+
+export const BASES = ['HEX', 'DEC', 'OCT', 'BIN'];
+export const WORD_SIZES = [8, 16, 32, 64];
+
+/** @type {Array<Array<{label:string,k:string,tone?:string,span?:number}>>} */
+export const KEYPAD = [
+  [{ label: 'C', k: 'clear', tone: 'clear' }, { label: '⌫', k: 'back', tone: 'clear' }, { label: '(', k: '(' }, { label: ')', k: ')' }, { label: '~', k: '~', tone: 'op' }],
+  [{ label: 'A', k: 'A' }, { label: 'B', k: 'B' }, { label: '&', k: '&', tone: 'op' }, { label: '|', k: '|', tone: 'op' }, { label: 'xor', k: 'xor(', tone: 'fn' }],
+  [{ label: 'C', k: 'C' }, { label: 'D', k: 'D' }, { label: '«', k: '<<', tone: 'op' }, { label: '»', k: '>>', tone: 'op' }, { label: 'mod', k: 'mod(', tone: 'fn' }],
+  [{ label: 'E', k: 'E' }, { label: 'F', k: 'F' }, { label: '0x', k: '0x' }, { label: '0b', k: '0b' }, { label: '0o', k: '0o' }],
+  [{ label: '7', k: '7' }, { label: '8', k: '8' }, { label: '9', k: '9' }, { label: '×', k: '*', tone: 'op' }, { label: '÷', k: '/', tone: 'op' }],
+  [{ label: '4', k: '4' }, { label: '5', k: '5' }, { label: '6', k: '6' }, { label: '+', k: '+', tone: 'op' }, { label: '−', k: '-', tone: 'op' }],
+  [{ label: '1', k: '1' }, { label: '2', k: '2' }, { label: '3', k: '3' }, { label: '0', k: '0' }, { label: '=', k: 'equals', tone: 'equals' }],
+];
+
+/**
+ * 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 function wordViews(value, wordBits = 32, signed = false) {
+  if (!Number.isFinite(value)) return { hex: '—', dec: '—', oct: '—', bin: '—' };
+  const w = toWord(BigInt(Math.trunc(value)), wordBits, signed);
+  // unsigned view for hex/oct/bin so the two's-complement bit pattern shows
+  const u = toWord(w, wordBits, false);
+  return {
+    hex: toBase(u, 16, { upper: true, group: 4 }),
+    dec: toBase(w, 10),
+    oct: toBase(u, 8, { group: 3 }),
+    bin: toBase(u, 2, { group: 4, pad: wordBits }),
+  };
+}
+
+/**
+ * Format the primary display in the currently-selected base.
+ * @param {number} value @param {any} [state]
+ * @returns {string}
+ */
+export function format(value, state) {
+  const bits = state?.wordBits ?? 32;
+  const signed = state?.signed ?? false;
+  const base = state?.base ?? 'DEC';
+  const v = wordViews(value, bits, signed);
+  return base === 'HEX' ? '0x' + v.hex : base === 'OCT' ? '0o' + v.oct : base === 'BIN' ? '0b' + v.bin : v.dec;
+}
+
+export const programmerMode = {
+  id: 'programmer',
+  label: 'Programmer',
+  env: programmerEnv(),
+  keypad: KEYPAD,
+  format,
+  bases: BASES,
+  wordSizes: WORD_SIZES,
+};