mathjson-tree-builder 0.1.0

package/dist/registry/registry.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The construct registry — the single source of
+ * truth for "how does construct X render and how many/which arguments
+ * does it take." Layers the generated construct list (kept in sync
+ * with mathjson-solver's own source, not hand-transcribed) with the small
+ * hand-authored `args` and `notation` overlays.
+ */
+import type { ConstructDescriptor, MathJsonExpression } from "../types.js";
+import { CATEGORY_LABELS } from "./constructs.generated.js";
+import { isComparisonLike, operatorGlyph, swapNeedsArgReversal, swapTargets, type NotationSpec } from "./notation.js";
+export { CATEGORY_LABELS, isComparisonLike, operatorGlyph, swapNeedsArgReversal, swapTargets };
+export type { NotationSpec };
+/** Every construct mathjson-solver implements, name + category only. */
+export declare function allConstructs(): readonly ConstructDescriptor[];
+/** Look up one construct's registry entry, if any. */
+export declare function getConstruct(name: string): ConstructDescriptor | undefined;
+/** The curated notation renderer for `name`, if it's in the small curated set. */
+export declare function getNotation(name: string): NotationSpec | undefined;
+export declare function categoryLabel(slug: string): string;
+/**
+ * A human-readable name for construct `name` — e.g. "Division" for
+ * `Divide`. Falls back to the raw construct name when no curated entry
+ * exists (see `display-names.ts`).
+ */
+export declare function displayName(name: string): string;
+/**
+ * The minimum and maximum number of arguments construct `name` accepts, if
+ * it has curated `args` metadata to derive that from — `undefined` when it
+ * doesn't (the vast majority of the registry), in which case the generic
+ * renderer stays fully permissive rather than guess at an unverified
+ * arity ("prefer erring toward permissive" over guessing wrong). A trailing
+ * `variadic` entry means unbounded (`max: Infinity`, `min` counting that
+ * slot as needing at least one instance); otherwise `max` is the curated
+ * entry count and `min` subtracts however many are marked `optional`
+ * (assumed trailing, e.g. `Round`'s `digits`).
+ */
+export declare function argBounds(name: string): {
+    min: number;
+    max: number;
+} | undefined;
+/**
+ * Search the palette by name/category, honoring the host's `blacklist` (mirrors
+ * mathjson-solver's own `create_solver(blacklist=...)`).
+ */
+export declare function searchConstructs(query: string, blacklist?: readonly string[]): ConstructDescriptor[];
+/**
+ * A reasonable, best-effort set of default arguments for freshly inserting
+ * construct `name` (via the function picker or the wrap-in-parent action).
+ * Notation shape takes priority where present, since those
+ * constructs have arity/shape requirements verified against
+ * mathjson-solver's own source (e.g. `Product` needs a single `Array` arg).
+ * Falls back to hand-authored `args` defaults, then to a single `0`.
+ */
+export declare function defaultArgsFor(name: string): MathJsonExpression[];

package/dist/styles.d.ts

@@ -0,0 +1 @@
+export declare const styles: import("lit").CSSResult;

package/dist/types.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Core types for mathjson-tree-builder.
+ */
+/**
+ * A MathJSON expression, restricted to the "array form" this editor
+ * operates on directly (no LaTeX, no boxed/canonical forms):
+ *
+ *   - a number literal
+ *   - a boolean literal
+ *   - a string — either a literal string *value*, or a bare symbol
+ *     reference (e.g. a named survey question). Disambiguating the two is
+ *     the host application's job via the symbol resolver, not this
+ *     editor's — see `resolveSymbol` in `data-model/symbols.ts`.
+ *   - a compound expression `[constructName, ...args]`
+ */
+export type MathJsonExpression = number | boolean | string | MathJsonExpression[];
+/** True for a compound expression `[constructName, ...args]`. */
+export declare function isCompound(expr: MathJsonExpression): expr is MathJsonExpression[];
+/**
+ * Type-guard for arbitrary parsed JSON (e.g. from the raw-JSON escape
+ * hatch): true for a number, boolean, string, or an array recursively made
+ * of the same — false for `null`, a plain object, or `undefined`. This is
+ * deliberately just a shape check, not semantic validation (a compound
+ * expression's first element isn't required to be a known construct name)
+ * — the raw-JSON view's job is catching malformed JSON, not building a
+ * MathJSON linter.
+ */
+export declare function isValidMathJson(value: unknown): value is MathJsonExpression;
+/**
+ * A path from the root to a node: an array of indices. `[]` addresses the
+ * root itself. `[i]` addresses element `i` of the root (index `0` is the
+ * construct name for a compound root). Nested paths descend the same way.
+ */
+export type Path = readonly number[];
+/** Metadata for one argument of a construct, for nicer generic-mode labels. */
+export interface ArgSpec {
+    label: string;
+    /** True on the last entry of a genuinely unbounded (variadic) construct. */
+    variadic?: boolean;
+    /**
+     * True for a trailing argument that may be omitted (e.g. `Round`'s
+     * `digits`) — only meaningful on the last entry/entries; arity bounds
+     * (`argBounds` in the registry) assume optional args are trailing.
+     */
+    optional?: boolean;
+    defaultValue?: MathJsonExpression;
+}
+/**
+ * Registry entry for one MathJSON construct. `args` and `notation` are
+ * optional, best-effort metadata — a construct with neither still renders
+ * correctly through the fully generic fallback.
+ */
+export interface ConstructDescriptor {
+    name: string;
+    category: string;
+    args?: ArgSpec[];
+}
+/**
+ * A host-supplied named reference the user can insert into an expression
+ * (e.g. a survey question, a spreadsheet cell, a form field) — see
+ * `resolveSymbol` in `data-model/symbols.ts`.
+ * Inserted verbatim as a bare MathJSON string (`id`).
+ */
+export interface SymbolReference {
+    id: string;
+    label: string;
+    type?: string;
+    group?: string;
+}
+/** Result of an optional host-wired evaluator. */
+export type EvalResult = {
+    result: MathJsonExpression;
+} | {
+    error: string;
+    path?: Path;
+};
+export type Evaluator = (expr: MathJsonExpression, parameters: Record<string, MathJsonExpression>) => Promise<EvalResult>;

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "mathjson-tree-builder",
+  "version": "0.1.0",
+  "description": "A framework-agnostic Custom Element for visually building MathJSON expressions, tuned for the constructs mathjson-solver implements.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Mārtiņš Mednis",
+  "homepage": "https://mrtmednis.gitlab.io/mathjson-tree-builder/",
+  "repository": {
+    "type": "git",
+    "url": "git@gitlab.com:mrtmednis/mathjson-tree-builder.git"
+  },
+  "bugs": "https://gitlab.com/mrtmednis/mathjson-tree-builder/-/issues",
+  "keywords": [
+    "mathjson",
+    "custom-element",
+    "web-component",
+    "formula-builder",
+    "mathjson-solver"
+  ],
+  "main": "./dist/mathjson-tree-builder.js",
+  "module": "./dist/mathjson-tree-builder.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/mathjson-tree-builder.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "registry:extract": "python3 scripts/extract-registry.py",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "devDependencies": {
+    "happy-dom": "^20.14.5",
+    "lit": "^3.2.1",
+    "typescript": "^5.6.3",
+    "vite": "^8.3.0",
+    "vitest": "^5.0.0"
+  }
+}