@mathzetta/inlinemath 0.0.0-stage → 0.2.0

package/src/mathzetta.js

@@ -0,0 +1,18 @@
+/**
+ * Where Inline Math reaches into MathZetta: this file (the core and speech) and calculator.js (the
+ * calculator, for `{{…}}` blocks). Everything else imports from these two, so a change in
+ * MathZetta's API is a small change — and the lite build, which leaves the calculator out, is
+ * everything that doesn't import calculator.js.
+ *
+ * MathZetta is a peer dependency; a page without a bundler maps the names with an import map (as
+ * the README shows).
+ */
+
+export {
+    parse, parseTree, fromPostfix, toPostfix, asTree, walk, firstVariable,
+    operator, precedenceOf, isCustomFunction, VARIADIC,
+    GREEK, needsBrackets, unaryNeedsBrackets, isMinusOneTimes, isImplicitProduct, isVariable,
+    firstLeaf, customName, derivativeOrder, bracketedSides, bracketOp,
+    MATRICES, matrixRows,
+} from 'mathzetta';
+export { toSpeech, toSpeechSegments, toAudioSpeech } from 'mathzetta/speech';

package/src/select.js

@@ -0,0 +1,108 @@
+/**
+ * Picking out parts of an expression.
+ *
+ * A target can be written several ways; select() turns any of them into
+ * the matching tree nodes:
+ *
+ *   4                 the node with id 4 (MathZetta's postfix index)
+ *   'x^2'             every part that is x² — written like any other input
+ *   { path: [0, 1] }  child 1 of child 0 of the root — the same paths @mathzetta/cas reports
+ *   (node) => bool    any test
+ *   [ …targets ]      all of them
+ *
+ * Matching by expression compares postfix, so 'x^2 + 1' finds x² + 1 only
+ * where it is a part of the tree on its own: in 3 + x² + 1, which reads
+ * (3 + x²) + 1, it is not.
+ */
+
+import { parseTree, toPostfix, walk, operator, VARIADIC } from './mathzetta.js';
+
+/** A subtree's postfix as one string: two parts look the same exactly when these match. */
+export const signature = (node) => toPostfix(node).join(' ');
+
+/**
+ * @param {object} tree
+ * @param {*} target see above
+ * @returns {object[]} nodes, in tree order, without repeats
+ */
+export function select(tree, target) {
+    const found = new Set();
+    collect(tree, target, found);
+    const out = [];
+    walk(tree, (n) => { if (found.has(n)) out.push(n); });
+    return out;
+}
+
+function collect(tree, target, found) {
+    if (target === null || target === undefined) return;
+    if (Array.isArray(target)) {
+        target.forEach((t) => collect(tree, t, found));
+        return;
+    }
+    if (typeof target === 'number') {
+        walk(tree, (n) => { if (n.id === target) found.add(n); });
+        return;
+    }
+    if (typeof target === 'function') {
+        walk(tree, (n, parent) => { if (target(n, parent)) found.add(n); });
+        return;
+    }
+    if (typeof target === 'string') {
+        const sig = signature(parseTree(target));
+        walk(tree, (n) => { if (signature(n) === sig) found.add(n); });
+        return;
+    }
+    if (target.path) {
+        const n = nodeAt(tree, target.path);
+        if (n) found.add(n);
+        return;
+    }
+    if (target.type) {
+        const sig = signature(target);
+        walk(tree, (n) => { if (n === target || signature(n) === sig) found.add(n); });
+    }
+}
+
+/** The node at a path of child indices, or null. */
+export function nodeAt(tree, path) {
+    let n = tree;
+    for (const i of path) {
+        if (n.type !== 'op' || !n.args[i]) return null;
+        n = n.args[i];
+    }
+    return n;
+}
+
+/** The path of child indices to the node with this id, or null. */
+export function pathOf(tree, id) {
+    const path = [];
+    const visit = (n) => {
+        if (n.id === id) return true;
+        if (n.type !== 'op') return false;
+        for (let i = 0; i < n.args.length; i++) {
+            path.push(i);
+            if (visit(n.args[i])) return true;
+            path.pop();
+        }
+        return false;
+    };
+    return visit(tree) ? path : null;
+}
+
+/**
+ * Give every node of a hand-built tree the id MathZetta would: its index
+ * in the postfix (variadic operators count their argument-count token).
+ * Changes the tree in place and returns it.
+ */
+export function numberTree(tree) {
+    let i = 0;
+    const visit = (n) => {
+        if (n.type === 'op') {
+            n.args.forEach(visit);
+            if (operator(n.op)?.arity === VARIADIC) i++;
+        }
+        n.id = i++;
+    };
+    visit(tree);
+    return tree;
+}

package/src/types.d.ts

@@ -0,0 +1,204 @@
+// Inline Math's declarations. Each entry's .d.ts (index, lite, lite-calc, markdown, cas) picks from here.
+import type { Input, Node, BlockHandler } from 'mathzetta';
+import type { SpeechOptions } from 'mathzetta/speech';
+
+export type { Input, Node, BlockHandler };
+
+/**
+ * A part of an expression: a node id (MathZetta's postfix index), an expression written like any
+ * input ('x^2': every part that is x²), a path ({ path: [0, 1] }, as @mathzetta/cas reports it), a test,
+ * or a list of any of these.
+ */
+export type Target = number | string | { path: number[] } | ((node: Node) => boolean) | Target[];
+
+export interface LayoutOptions {
+    /** CSS class prefix (default 'mv'). */
+    prefix?: string;
+    /** Big operators with limits above and below, full-size fractions (default true). */
+    display?: boolean;
+    /** 'auto': sin x, ln|x|, sin(x + 1); 'always': sin(x). */
+    fnParens?: 'auto' | 'always';
+    /** sin(x)^2 written sin²x (default true). */
+    trigPowers?: boolean;
+    /** 'arc': arcsin x; 'power': sin⁻¹x. */
+    inverseTrig?: 'arc' | 'power';
+    /** d/dx [x² + 1] ('[') or d/dx (x² + 1) ('('). */
+    derivativeBrackets?: '[' | '(';
+    /** x^{1/2} with a slash ('slash') or stacked ('stack'). */
+    scriptFractions?: 'slash' | 'stack';
+    /** c ? a : b drawn as a piecewise brace (default true). */
+    cases?: boolean;
+    /** The accessible name: true = the spoken form, a string, a function of the tree, or false for none. */
+    label?: boolean | string | ((tree: Node) => string);
+    /** MathZetta's toMathML (from 'mathzetta/mathml'): also write the expression as visually hidden MathML, which
+     *  screen readers can step through and show in math braille; it takes the place of the label. Off by default. */
+    mathml?: ((input: Node) => string) | null;
+    /** Extra attributes for a node's element. */
+    attributes?: ((node: Node) => Record<string, string>) | null;
+    /** Inline style for a node's element. */
+    style?: ((node: Node) => string) | null;
+}
+
+export interface DrawOptions extends LayoutOptions {
+    /** Colours by target: { 'x^2': 'red', 3: '#06c' } or [[target, colour], …]. */
+    colors?: Record<string | number, string> | Array<[Target, string]>;
+    /** Parts to mark with the `<prefix>-hl` class. */
+    highlight?: Target;
+    /** Variable values for `{{…}}` blocks. */
+    scope?: Record<string, unknown>;
+    /** Another `{{…}}` handler (casBlocks() from '@mathzetta/inlinemath/cas'). */
+    blocks?: BlockHandler;
+}
+
+/** Options for a live view: everything toHTML takes, plus how steps reach a screen reader. */
+export interface ViewOptions extends DrawOptions {
+    /** Read each new step (every set() after the first) to a screen reader: true places a polite live
+     *  region after the element; or pass your own live-region element. Off by default. */
+    announce?: boolean | Element;
+}
+
+export const DEFAULTS: Required<LayoutOptions>;
+
+/** Anything MathZetta reads, as HTML (a string; works in Node). Needs inlinemath.css on the page. */
+export function toHTML(input: Input, options?: DrawOptions): string;
+/** Anything MathZetta reads → a tree with node ids (`{{…}}` filled as toHTML would). */
+export function treeOf(input: Input, options?: DrawOptions): Node;
+/** A tree → HTML, with its height and depth in em. */
+export function layout(tree: Node, options?: LayoutOptions): { html: string; h: number; d: number };
+
+/** The nodes a target picks out, in tree order. */
+export function select(tree: Node, target: Target): Node[];
+/** A subtree's postfix as one string: two parts look the same exactly when these match. */
+export function signature(node: Node): string;
+export function nodeAt(tree: Node, path: number[]): Node | null;
+export function pathOf(tree: Node, id: number): number[] | null;
+/** Gives a tree built by hand the ids MathZetta would. */
+export function numberTree<T extends Node>(tree: T): T;
+/** SVG paths of the glyphs Inline Math draws, ( ) { } √ ∫ ∑ ∏: each filled or stroked, in a unit box. */
+export const PATHS: Record<string, { fill?: string; stroke?: string }>;
+
+export interface ClickInfo { node: Node; id: number; path: number[] | null; element: Element; event: Event }
+
+/** A live drawing: highlight, colour, listen, step with animation. */
+export class View {
+    constructor(element: Element, input: Input, options?: ViewOptions);
+    readonly element: Element;
+    readonly tree: Node;
+    /** Show a new expression; with animate, matching parts glide over and new ones fade in. `true` is instant
+     *  when the reader's system asks for reduced motion; `'always'` animates regardless. */
+    set(input: Input, options?: { animate?: boolean | 'always'; duration?: number; easing?: string }): this;
+    /** The expression as a listener hears it (its accessible name, else MathZetta's audio speech). */
+    spoken(): string;
+    /** Say something through the live region ({ announce } must be set); steps are announced this way. */
+    announce(text: string): this;
+    nodes(target: Target): Node[];
+    elements(target: Target): Element[];
+    elementOf(node: Node): Element | null;
+    highlight(target: Target, className?: string): this;
+    unhighlight(target?: Target | null, className?: string): this;
+    color(target: Target, colour: string): this;
+    /** Listen for an event on a part; returns a function that stops listening. */
+    /** Listen for an event on the parts. A 'click' listener also makes the drawing work from the keyboard:
+     *  one tab stop, arrow keys walk the parts (each spoken), Enter or Space calls the listener for the
+     *  current part — `event` is then the KeyboardEvent. */
+    on(type: string, fn: (info: ClickInfo) => void): () => void;
+    /**
+     * Let the reader edit a part at a time: double-click it (or F2 on the keyboard's part) and a
+     * text box opens over it; Enter puts the new text in its place, Escape leaves it.
+     * toText is MathZetta's (import { toText } from 'mathzetta/text'; InlineMath.toText in the <script> build).
+     */
+    editable(how: { toText: (input: Input) => string; onEdit?: (change: { tree: Node; text: string; path: number[]; part: string }) => void }): this;
+    /** Open the editing box over a part (editable() first). */
+    edit(target?: unknown, options?: { returnFocus?: boolean }): HTMLInputElement | null;
+    /** The part the arrow keys are on (null: the whole expression). */
+    readonly active: Node | null;
+    /** Put the keyboard on a part (null: the whole expression) and say it. */
+    focusPart(node: Node | null): this;
+    /** The expression read aloud in pieces, each tagged with the node it describes. */
+    segments(options?: SpeechOptions): { text: string; id?: number }[];
+    showSegment(segment: { id?: number } | null, className?: string): this;
+}
+/** Draw into an element and return the live view. */
+export function render(element: Element, input: Input, options?: ViewOptions): View;
+/** Should a step animate: true honours prefers-reduced-motion, 'always' does not, false never. */
+export function shouldAnimate(animate?: boolean | 'always'): boolean;
+
+// ---- inlinemath/markdown --------------------------------------------------------------------
+
+export interface MarkdownOptions {
+    /** Options for each drawing (toHTML's). */
+    math?: DrawOptions;
+    /** The `{{…}}` handler (default the calculator; casBlocks() for the CAS). */
+    blocks?: BlockHandler;
+    /** Values for `{{…}}`. */
+    scope?: Record<string, unknown>;
+    /** Remember $r = 3$ for later `{{…}}` (default true). */
+    define?: boolean;
+    /** Let raw HTML through (default false: it is shown as text). */
+    html?: boolean;
+    /** Another Markdown renderer; the maths is taken out first and put back into its output. */
+    render?: (markdown: string) => string;
+    /** Which of '$$', '$', '\\[', '\\(' mark maths (default all). */
+    delimiters?: string[];
+    /**
+     * The saved variables ($A := 2+2$) the maths may use. markdownToHTML: none by default;
+     * renderMarkdownInto: the page's `variables` by default, false for none.
+     */
+    variables?: Variables | false | null;
+    /**
+     * renderMarkdownInto: double-clicking a part drawn from a textbox variable edits it in place
+     * (toText from 'mathzetta/text'); without it the textbox is focused. Any other part fires
+     * 'inlinemath:select' (detail { index, start, end, raw, source, id, path }) on the element.
+     */
+    editable?: { toText: (input: Input) => string };
+}
+/** What a saved variable is: its expression, or the input that sets it. */
+export interface VariableDefinition {
+    name: string;
+    text: string;
+    input: null | { kind: 'textbox'; default: string } | { kind: 'dropdown'; options: string[]; default: string } | { kind: 'slider'; min: number; max: number; step: number; default: string };
+    key: string;
+}
+/** A page's saved variables: every part drawn with renderMarkdownInto sees the others'. */
+export class Variables {
+    /** A variable's expression now (what its input holds, for an input), or undefined. */
+    get(name: string): string | undefined;
+    /** Set a variable: what its input holds, or (with no input) a definition for the whole page. */
+    set(name: string, text: string | number): this;
+    /** Forget a variable set with set(), or everything. */
+    clear(name?: string): this;
+    /** The saved names. */
+    names(): string[];
+    /** Called whenever a variable changes; returns a function that stops it. */
+    subscribe(fn: (owner: unknown, name?: string) => void): () => void;
+    definitions(except?: unknown): Map<string, VariableDefinition>;
+    textOf(def: VariableDefinition): string;
+    own(owner: unknown, defs: Map<string, VariableDefinition> | null): void;
+}
+/** A store of its own, for parts of a page that shouldn't share variables. */
+export function createVariables(): Variables;
+/** The page's store, renderMarkdownInto's default. */
+export const variables: Variables;
+export function markdownToHTML(markdown: string, options?: MarkdownOptions): string;
+export function renderMarkdownInto<E extends Element>(element: E, markdown: string, options?: MarkdownOptions): E;
+export function extractMath(markdown: string, options?: { delimiters?: string[] }): { text: string; math: Array<{ source: string; display: boolean; raw: string; start: number; end: number }> };
+export function renderMarkdown(markdown: string, options?: MarkdownOptions): string;
+
+// ---- inlinemath/cas (needs @mathzetta/cas) --------------------------------------------------------
+
+/** A step from the CAS (@mathzetta/cas's CASStep fits): path null for a step standing for hidden ones. */
+export interface CASStep { id: string; name: string; from: string; to: string; path?: number[] | null; explanation?: string }
+/** @mathzetta/cas reading and writing MathZetta text (its full API: @mathzetta/cas/docs/cas.md). */
+export type CAS = Record<string, any>;
+export function mathCAS(options?: { rules?: unknown[]; names?: string[]; complex?: boolean; [option: string]: unknown }): CAS;
+/** A `{{…}}` handler: toHTML(input, { blocks: casBlocks() }). `last` holds the latest CAS result. */
+/** steps: how much working each call keeps (true: every step, 'brief': the ones that carry the idea, false: none). */
+export function casBlocks(options?: { cas?: CAS; steps?: boolean | 'brief' | Record<string, unknown> }): BlockHandler & { last?: { steps?: CASStep[]; text?: string; [k: string]: unknown } };
+/** Steps as an ordered list, each rewrite highlighted, with its explanation. */
+export function stepsHTML(steps: CASStep[], options?: DrawOptions): string;
+/** A CAS node → MathZetta postfix tokens. */
+export function tokensOf(node: unknown): string[];
+
+// ---- the calculator (inlinemath/lite-calc re-exports it) -------------------------------------
+
+export { calculateBlock, calculate } from 'mathzetta/calculate';

package/src/variables.js

@@ -0,0 +1,228 @@
+/**
+ * Saved variables for '@mathzetta/inlinemath/markdown': `$A := 2+2$` saves A, and A in any maths
+ * after it is drawn as 2 + 2 (and `{{A}}` is 4). A store holds them for a whole page, so every
+ * part drawn with renderMarkdownInto sees the others' variables, and an input bound to a variable
+ * (`$A := [[2+2]]$`, a textbox) redraws everything that uses it.
+ *
+ *   import { createVariables, variables } from '@mathzetta/inlinemath/markdown';
+ *   variables.set('A', 'x^2');   // the page's store: A is x² everywhere
+ *   variables.get('A');          // 'x^2'
+ */
+
+/**
+ * Where a scope carries the saved variables' expressions, for {{…}} handlers that work with
+ * expressions rather than values (casBlocks: {{diff(f, x)}} with f saved): name → MathZetta
+ * postfix, every saved name inside already put in. A symbol, so the calculator never sees it.
+ */
+export const EXPRESSIONS = Symbol.for('inlinemath.expressions');
+
+// ---- names ----------------------------------------------------------------------------------
+
+const LEAF = new Set(['symbol', 'number']);
+
+/** The variable a node names: A, α, A_1 (a symbol with a plain subscript) — else null. */
+export function nameOf(node) {
+    if (!node) return null;
+    if (node.type === 'symbol') return node.value;
+    if (node.type === 'op' && node.op === '_' && node.args.length === 2 && node.args[0].type === 'symbol' && LEAF.has(node.args[1].type)) {
+        return `${node.args[0].value}_${node.args[1].value}`;
+    }
+    return null;
+}
+
+/** A tree with its ids (and where-it-came-from marks) dropped, so it can be numbered again inside another. */
+export function bare(node) {
+    const { id, from, ...rest } = node;
+    if (rest.args) rest.args = rest.args.map(bare);
+    return rest;
+}
+
+/** Ids dropped (to be numbered again), `from` marks kept. */
+function renumber(node) {
+    const { id, ...rest } = node;
+    if (rest.args) rest.args = rest.args.map(renumber);
+    return rest;
+}
+
+/**
+ * The part of a substituted tree a variable stands for, written back in its own terms: the
+ * variables inside it put back as their names. `named(name)` gives a name's own tree.
+ */
+export function unexpand(node, named) {
+    const visit = (n, top) => {
+        if (!top && n.from !== undefined) return named(n.from);
+        const { id, from, ...rest } = n;
+        if (rest.args) rest.args = rest.args.map((a) => visit(a, false));
+        return rest;
+    };
+    return visit(node, true);
+}
+
+/**
+ * Every saved name in a tree replaced by its own tree (which may use other saved names).
+ * `lookup(name)` gives a saved name's tree, or null. A name inside its own definition is left as it is.
+ * @returns {{ tree: object, changed: boolean }}
+ */
+export function substitute(tree, lookup) {
+    let changed = false;
+    const seen = new Set();
+    const visit = (node) => {
+        const name = nameOf(node);
+        if (name !== null) {
+            if (!seen.has(name)) {
+                const value = lookup(name);
+                if (value) {
+                    changed = true;
+                    seen.add(name);
+                    const out = { ...visit(bare(value)), from: name };   // where it came from, for editing
+                    seen.delete(name);
+                    return out;
+                }
+            }
+            return node;   // A_1 is one name: its A is not substituted
+        }
+        if (node.args) return { ...node, args: node.args.map(visit) };
+        return node;
+    };
+    const out = visit(tree);
+    return { tree: changed ? renumber(out) : tree, changed };
+}
+
+// ---- inputs ---------------------------------------------------------------------------------
+
+const NUMBER = '[-+]?(?:\\d+\\.?\\d*|\\.\\d+)';
+const SLIDER = new RegExp(`^(${NUMBER})\\s*\\.\\.\\s*(${NUMBER})(?:\\s+step\\s+(${NUMBER}))?(?:\\s*=\\s*(${NUMBER}))?$`);
+
+/**
+ * What `[[…]]` asks for: `[[2+2]]` a textbox, `[[2+2 | x^2]]` a dropdown,
+ * `[[1..10]]` a slider (`[[0..1 step 0.1 = 0.5]]` with a step and a starting value). Else null.
+ */
+export function inputOf(text) {
+    const m = /^\s*\[\[([\s\S]*)\]\]\s*$/.exec(text);
+    // [[2, 1], [1, 3]] is a matrix (rows of a list), not an input
+    if (!m || /\]\s*,\s*\[/.test(m[1])) return null;
+    const inner = m[1].trim();
+    const range = SLIDER.exec(inner);
+    if (range) {
+        const min = Number(range[1]);
+        const max = Number(range[2]);
+        if (!(max > min)) return null;
+        const step = range[3] !== undefined ? Number(range[3]) : Number.isInteger(min) && Number.isInteger(max) ? 1 : (max - min) / 100;
+        if (!(step > 0)) return null;
+        const start = range[4] !== undefined ? Math.min(max, Math.max(min, Number(range[4]))) : min;
+        return { kind: 'slider', min, max, step, default: String(start) };
+    }
+    if (inner.includes('|')) {
+        const options = inner.split('|').map((o) => o.trim()).filter(Boolean);
+        if (options.length) return { kind: 'dropdown', options, default: options[0] };
+    }
+    return { kind: 'textbox', default: inner };
+}
+
+// ---- the store ------------------------------------------------------------------------------
+
+const PAGE = Symbol('set on the page');
+
+/**
+ * Where a page's variables live. A part of the page owns the definitions it makes (drawing it
+ * again replaces them); `set` is how an input — or the page's own code — changes one.
+ */
+export class Variables {
+    constructor() {
+        this.owners = new Map();     // owner → Map(name → definition)
+        this.chosen = new Map();     // name → { key, text }: what an input was set to
+        this.listeners = new Set();
+    }
+
+    /** Every definition, in the order the parts were drawn; `except` leaves one part out. */
+    definitions(except) {
+        const all = new Map();
+        for (const [owner, defs] of this.owners) {
+            if (owner === except) continue;
+            for (const [name, def] of defs) {
+                all.delete(name);   // a later definition goes after the earlier ones
+                all.set(name, def);
+            }
+        }
+        return all;
+    }
+
+    /** The text a definition stands for now: its expression, or what its input is set to. */
+    textOf(def) {
+        const chosen = this.chosen.get(def.name);
+        return chosen && chosen.key === def.key ? chosen.text : def.text;
+    }
+
+    /** A variable's expression now, or undefined. */
+    get(name) {
+        const def = this.definitions().get(name);
+        return def ? this.textOf(def) : undefined;
+    }
+
+    /** The saved names. */
+    names() {
+        return [...this.definitions().keys()];
+    }
+
+    /** Set a variable: what its input holds, or (with no input) a definition for the whole page. */
+    set(name, text) {
+        text = String(text);
+        const def = this.definitions().get(name);
+        if (def && def.input) {
+            const chosen = this.chosen.get(name);
+            if (chosen && chosen.key === def.key && chosen.text === text) return this;
+            this.chosen.set(name, { key: def.key, text });
+        } else {
+            const defs = new Map(this.owners.get(PAGE));
+            defs.set(name, { name, text, key: `page:${text}`, input: null });
+            this.owners.delete(PAGE);
+            this.owners.set(PAGE, defs);
+        }
+        this.notify(null, name);
+        return this;
+    }
+
+    /** Forget a variable set with `set`, or everything (no name). */
+    clear(name) {
+        if (name === undefined) {
+            this.owners.clear();
+            this.chosen.clear();
+        } else {
+            this.owners.get(PAGE)?.delete(name);
+            this.chosen.delete(name);
+        }
+        this.notify(null, name);
+        return this;
+    }
+
+    /** Called with (owner, name) when something changes; returns a function that stops it. */
+    subscribe(fn) {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    }
+
+    /** A part's definitions (null: it has none any more). Tells the others only when they change. */
+    own(owner, defs) {
+        const before = this.owners.get(owner);
+        const same = (a, b) => (a?.size ?? 0) === (b?.size ?? 0) && [...(a ?? [])].every(([k, d]) => b?.get(k)?.key === d.key);
+        if (same(before, defs)) {
+            if (defs) this.owners.set(owner, defs);
+            return;
+        }
+        if (defs && defs.size) this.owners.set(owner, defs);
+        else this.owners.delete(owner);
+        this.notify(owner);
+    }
+
+    notify(owner, name) {
+        for (const fn of [...this.listeners]) fn(owner, name);
+    }
+}
+
+/** A store of its own, for parts of a page that shouldn't share variables. */
+export function createVariables() {
+    return new Variables();
+}
+
+/** The page's store: renderMarkdownInto uses it unless told otherwise. */
+export const variables = createVariables();