mathjson-tree-builder 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mārtiņš Mednis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# mathjson-tree-builder
+
+**mathjson-tree-builder** is the front-end counterpart to
+[mathjson-solver](https://github.com/LongenesisLtd/mathjson-solver): build
+[MathJSON](https://mathlive.io/math-json/) formulas and data-processing
+expressions visually in the browser, evaluate them in your Python backend.
+
+Hand-writing MathJSON's array syntax isn't something you can ask a
+non-technical user to do — this framework-agnostic **Custom Element** gives
+them point-and-click building instead, with named external values (form
+fields, survey questions, ...) droppable into any slot.
+
+**[Live demo](https://mrtmednis.gitlab.io/mathjson-tree-builder/)**
+
+![Compound interest built as principal times (1 + rate over periods) to the power of periods times years — addition, a fraction, multiplication, and a parenthesized power base all in one formula](https://gitlab.com/mrtmednis/mathjson-tree-builder/-/raw/main/docs/screenshot-compound-interest.png)
+
+## Install & use
+
+```bash
+npm install mathjson-tree-builder
+```
+
+```html
+<script type="module">
+  import "mathjson-tree-builder";
+</script>
+
+<mathjson-tree-builder id="builder"></mathjson-tree-builder>
+
+<script type="module">
+  const el = document.getElementById("builder");
+
+  el.value = ["Divide", "weight", ["Power", "height", 2]]; // BMI
+
+  el.symbols = [
+    { id: "weight", label: "Weight (kg)", type: "number" },
+    { id: "height", label: "Height (m)", type: "number" },
+  ];
+
+  el.addEventListener("change", (e) => {
+    console.log(e.detail.value); // the current MathJSON expression,
+                                  // ready to hand to mathjson-solver
+  });
+</script>
+```
+
+Works identically in plain HTML, React, Vue, Angular, Svelte — it's a native
+Custom Element with no framework dependency baked into the published bundle
+(Lit is used to *build* it, not required to *use* it).
+
+## What it does
+
+- Every one of the ~338 constructs mathjson-solver implements is buildable,
+  via a generic `Name(arg1, arg2, ...)` fallback with add/remove-argument and
+  wrap-in-parent-construct affordances on every node.
+- The common ones get real notation instead of the generic form: arithmetic
+  and comparisons as infix (`a + b`, `age > 18`), `Power`/`Sqrt` as
+  superscript/radical, `Sum`/`Product` as Σ/Π, set/list membership as
+  `age in (1, 2, 3)`.
+- `Constants` bindings let a piece of a formula be named and collapsed, so a
+  large formula reads as a handful of names instead of one long expression.
+- `If` supports both of mathjson-solver's shapes — a single condition, or an
+  unlimited elseif chain — and any comparison/membership/boolean operator
+  can be swapped for another without rebuilding the condition from scratch.
+- A raw-JSON escape hatch for pasting in an expression built elsewhere, or
+  anything the tree view doesn't gracefully cover.
+
+See [`docs/API.md`](https://gitlab.com/mrtmednis/mathjson-tree-builder/-/blob/main/docs/API.md) for the full public API and a detailed
+rendering-model reference.
+
+## Known limitations
+
+Two things worth knowing before embedding it: the per-slot menu doesn't yet
+use the browser's Popover API, so a host container with
+`overflow: hidden`/`auto`/`scroll` will clip it; and moving focus away from
+an active node without a click can leave its menu visible slightly longer
+than ideal. See [`docs/API.md`](https://gitlab.com/mrtmednis/mathjson-tree-builder/-/blob/main/docs/API.md) for the full details.
+
+Not what you're after if you need a real math-notation input — CortexJS's
+[`mathfield`](https://cortexjs.io/mathfield/) is a mature LaTeX editor and
+solves a different problem than this does; see
+[`CONTRIBUTING.md`](https://gitlab.com/mrtmednis/mathjson-tree-builder/-/blob/main/CONTRIBUTING.md)
+for how the two compare.
+
+## Contributing
+
+See [`CONTRIBUTING.md`](https://gitlab.com/mrtmednis/mathjson-tree-builder/-/blob/main/CONTRIBUTING.md) for development setup and how the
+construct registry is generated, and
+[`CHANGELOG.md`](https://gitlab.com/mrtmednis/mathjson-tree-builder/-/blob/main/CHANGELOG.md)
+for what's shipped in each release.
+
+## License
+
+MIT

package/dist/data-model/classify.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Classify a node's current "kind" for rendering/editing purposes. This is
+ * the one place that decides literal-vs-symbol-vs-function for a value —
+ * see `resolveSymbol` for why a string is ambiguous on its own.
+ */
+import type { MathJsonExpression, SymbolReference } from "../types.js";
+export type NodeKind = "number" | "boolean" | "text" | "symbol" | "function";
+export declare function classifyValue(value: MathJsonExpression, symbols: readonly SymbolReference[]): NodeKind;

package/dist/data-model/path.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Generic, path-based tree mutation.
+ *
+ * This is the *only* place that knows how to read/write a node given its
+ * path from the root. Node rendering code calls these, and only these —
+ * there is deliberately no per-construct-name mutation logic anywhere else
+ * (contrast with prior art, which re-derived "where in
+ * the parent array does this go" via a giant if/else keyed on construct
+ * name).
+ */
+import { type MathJsonExpression, type Path } from "../types.js";
+/** Read the node at `path`, relative to `root`. `path: []` returns `root`. */
+export declare function getAtPath(root: MathJsonExpression, path: Path): MathJsonExpression;
+/**
+ * Return a new root with the node at `path` replaced by `value`. Does not
+ * mutate `root`. `path: []` replaces the whole root — wrapping the root in
+ * a new parent construct (the "add parent node" operation) is therefore
+ * the exact same call as wrapping any other node, just with an empty path;
+ * callers reassign `el.value` to the result either way.
+ *
+ * Uses shallow copy-on-the-path-only structural sharing: only the arrays
+ * along `path` are cloned, every sibling subtree is reused as-is.
+ */
+export declare function setAtPath(root: MathJsonExpression, path: Path, value: MathJsonExpression): MathJsonExpression;
+/**
+ * Append a new argument to the compound expression at `path`.
+ * `node` must be `[constructName, ...args]`; the new value is added last.
+ */
+export declare function withArgAdded(node: MathJsonExpression[], value: MathJsonExpression): MathJsonExpression[];
+/**
+ * Remove the argument at `argIndex` (an index into the compound array
+ * itself, so `1` is the first argument — index `0` is the construct name
+ * and is never a valid `argIndex`).
+ */
+export declare function withArgRemoved(node: MathJsonExpression[], argIndex: number): MathJsonExpression[];
+/**
+ * Wrap the node currently at `path` in a new parent construct `X`, so it
+ * becomes `X`'s first argument: `V` -> `[X, V, ...extraArgs]`. This is the
+ * one and only implementation of the "add parent node" operation — it
+ * works identically whether `path` addresses the root (`[]`) or any nested
+ * node, because it's built directly on `getAtPath`/`setAtPath`.
+ */
+export declare function wrapAtPath(root: MathJsonExpression, path: Path, constructName: string, extraArgs?: MathJsonExpression[]): MathJsonExpression;
+/**
+ * Swap the construct name of the compound node at `path`, keeping its
+ * arguments unchanged: `[Greater, a, b]` -> `[LessEqual, a, b]`. Meant for
+ * switching among arity-compatible siblings (the curated comparison/infix
+ * groups in `registry/notation.ts`'s `swapTargets`) — this doesn't check
+ * compatibility itself, it's a pure rename of index 0.
+ *
+ * `reverseFirstTwoArgs` additionally swaps the first two arguments —
+ * needed for the one pair in that group with a different calling
+ * convention (`Contains`'s collection-first order vs. everything else's
+ * value-first order; see `registry/notation.ts`'s `swapNeedsArgReversal`),
+ * where keeping the args as-is would silently reverse the meaning.
+ */
+export declare function swapOperator(root: MathJsonExpression, path: Path, newName: string, reverseFirstTwoArgs?: boolean): MathJsonExpression;

package/dist/data-model/symbols.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Symbol reference resolution.
+ *
+ * A MathJSON string leaf is ambiguous on its own — it's either a literal
+ * string *value* or a bare symbol reference. This editor doesn't decide
+ * that itself; it just checks the string against the host-supplied
+ * `symbols` list and renders accordingly (a matching id renders as a
+ * labeled chip, a non-matching string renders as a plain literal input).
+ */
+import type { SymbolReference } from "../types.js";
+export declare function resolveSymbol(symbols: readonly SymbolReference[], value: string): SymbolReference | undefined;
+/**
+ * Filter/sort `symbols` for a given search term and optional expected
+ * `type` hint (a soft hint, not a hard validation rule — matching
+ * entries sort first, non-matching entries are still included).
+ */
+export declare function searchSymbols(symbols: readonly SymbolReference[], query: string, expectedType?: string): SymbolReference[];

package/dist/element.d.ts

@@ -0,0 +1,65 @@
+/**
+ * `<mathjson-tree-builder>` — the custom element.
+ *
+ * Node rendering is implemented as a recursive private template method
+ * (`#renderSlot`) rather than as separate nested custom elements — one
+ * shadow root for the whole widget, one component recursively renders
+ * itself per node at the template level. This keeps the "every mutation
+ * goes through one path-based function" contract simple: every
+ * rendering call closes directly over its own `path` and calls `#commit`,
+ * with no event-bubbling-across-shadow-boundaries plumbing needed.
+ *
+ * Rendering is also click-to-edit: an unfocused node renders as plain
+ * content (no inputs, no "⋯" menu) — only the currently *active* node
+ * (the one that has focus, per `activePath`) shows its editable control
+ * and its menu. See the `activePath` state and `#onFocusIn` below.
+ */
+import { LitElement, type PropertyValues, type TemplateResult } from "lit";
+import { type Evaluator, type MathJsonExpression, type SymbolReference } from "./types.js";
+export declare class MathJsonTreeBuilderElement extends LitElement {
+    #private;
+    static styles: import("lit").CSSResult;
+    value: MathJsonExpression;
+    symbols: SymbolReference[];
+    blacklist: string[];
+    evaluate?: Evaluator;
+    /**
+     * Operand count above which `And`/`Or` switch from the compact inline
+     * `a ∧ b ∧ c` form to a vertical stacked list (one operand per line) —
+     * the inline form wraps mid-row once it runs out of width, which reads
+     * fine for a couple of conditions but ragged for a long chain. A real
+     * HTML attribute (not `attribute: false` like the object-typed
+     * properties above) since it's a plain number a host page can set
+     * declaratively: `<mathjson-tree-builder inline-to-stacked-threshold="5">`.
+     */
+    inlineToStackedThreshold: number;
+    /**
+     * The path (as a `pathKey` string) of the currently focused/active node,
+     * or `null` when nothing in this widget has focus. Drives both which
+     * node renders its editable control instead of plain text, and which
+     * node's "⋯" menu is shown — see the class doc comment.
+     */
+    private activePath;
+    /** Raw-JSON escape hatch: true while showing the textarea instead of the tree. */
+    private jsonMode;
+    /** The textarea's current (possibly invalid, uncommitted) content while in JSON mode. */
+    private jsonDraft;
+    /** Parse/shape error for `jsonDraft`, or `null` when it's valid and already committed. */
+    private jsonError;
+    /**
+     * Path keys of explicitly expanded `Constants` bindings — purely
+     * a view concern, never touches `value`. Absent = collapsed, so a big
+     * formula reads as just its constant names until you open one — the
+     * point of naming a piece of it in the first place.
+     */
+    private expandedConstants;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "mathjson-tree-builder": MathJsonTreeBuilderElement;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Public entry point. Importing this module registers
+ * `<mathjson-tree-builder>` via `customElements.define` (mirroring
+ * MathfieldElement's own integration pattern) as a side effect of
+ * importing `./element.js`.
+ */
+export { MathJsonTreeBuilderElement, } from "./element.js";
+export type { ArgSpec, ConstructDescriptor, EvalResult, Evaluator, MathJsonExpression, Path, SymbolReference, } from "./types.js";
+export { isCompound, isValidMathJson } from "./types.js";
+export { getAtPath, setAtPath, swapOperator, withArgAdded, withArgRemoved, wrapAtPath, } from "./data-model/path.js";
+export { resolveSymbol, searchSymbols } from "./data-model/symbols.js";
+export { allConstructs, argBounds, categoryLabel, defaultArgsFor, displayName, getConstruct, getNotation, isComparisonLike, operatorGlyph, searchConstructs, swapNeedsArgReversal, swapTargets, CATEGORY_LABELS, } from "./registry/registry.js";
+export type { NotationSpec } from "./registry/notation.js";