@mathzetta/inlinemath 0.1.0 → 0.2.0

package/README.md

@@ -29,11 +29,27 @@ toHTML('\\int_0^1 x^2\\,dx');              // HTML string; works in Node too
 const view = render(div, 'x^2 + 2x');       // a live view
 view.highlight('2x');                       // name a part by writing it
 view.color('x^2', 'crimson');
-view.on('click', ({ node, id, path }) => …);
-view.set('2x + x^2', { animate: true });    // the next step: matching parts glide over
+view.on('click', ({ node, id, path }) => …);   // also from the keyboard: Tab to it, arrows walk the parts, Enter picks one
+view.set('2x + x^2', { animate: true });    // the next step: matching parts glide over (instant under reduced motion; 'always' to insist)
+render(div, 'x^2', { announce: true });     // read each new step to a screen reader (a polite live region after the div)
+view.announce('Step 2: expand');            // your own words, through the same region
 view.segments();                            // [{ text: 'x', id: 3 }, { text: 'squared', id: 5 }, …]
+view.editable({ toText, onEdit: ({ text }) => … }); // double-click a part (or F2 on it) to edit it in place
 ```
 
+**Editing a part.** `view.editable({ toText })` (`import { toText } from 'mathzetta/text'`; in the
+`<script>` build it is `InlineMath.toText`) opens a text box over a part when it is double-clicked,
+or when F2 is pressed on the part the keyboard is on, holding that part as text. Enter puts what
+was typed in its place (the rest of the expression glides over), Escape leaves it as it was, and
+text that doesn't read keeps the box open, marked. `onEdit` gets the new expression as a tree and
+as text, the edited part's path and what was typed; `view.edit(target)` opens the box from code.
+
+**Keyboard and screen readers.** Every drawing has an accessible name (`role="math"`, its spoken form for a listener
+who can't see it). Once a view listens for `'click'`, the drawing is one tab stop: the arrow keys walk its parts (Down
+into a part, Up out, Left/Right between neighbours, Home or Escape back to the whole), each part is spoken through a
+polite live region and ringed, and Enter or Space calls the click listener for the current part (`event` is then the
+KeyboardEvent). `view.focusPart(node)` moves there from code.
+
 Inline Math needs its stylesheet on the page (the fonts are optional):
 
 ```js
@@ -43,8 +59,8 @@ import '@mathzetta/inlinemath/fonts/fonts.css';    // optional: Latin Modern, th
 
 ```html
 <!-- or from the CDN -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@mathzetta/inlinemath@0.1/inlinemath.css">
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@mathzetta/inlinemath@0.1/fonts/fonts.css">  <!-- optional -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@mathzetta/inlinemath@0.2/inlinemath.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@mathzetta/inlinemath@0.2/fonts/fonts.css">  <!-- optional -->
 ```
 
 ### Lite: drawing only
@@ -108,7 +124,8 @@ These go to `toHTML(input, options)` and `render(el, input, options)`.
 | `colors` | | `{ 'x^2': 'red', 5: 'blue' }` (number keys are ids) or `[[target, colour]]` |
 | `highlight` | | target(s) that get the `mv-hl` class |
 | `attributes`, `style` | | `(node) => ({…})` / `(node) => 'css'` for each node's element |
-| `label` | `true` | the accessible name of the expression (`role="math" aria-label`): `true` = its spoken form from MathZetta, or a string, `(tree) => string`, or `false` |
+| `mathml` | | MathZetta's `toMathML` (`import { toMathML } from 'mathzetta/mathml'`): also write the expression as visually hidden MathML (no ids), which screen readers can step through part by part and show in math braille; the drawing stays hidden from them and the label is dropped (MathML carries the meaning). A keyboard-enabled view keeps its label on the focusable element |
+| `label` | `true` | the accessible name of the expression (`role="math" aria-label`): `true` = its spoken form for a listener who can't see it (MathZetta's `toAudioSpeech`: "the square root of the quantity x plus 1, end root, plus 2"), or a string, `(tree) => string`, or `false` |
 | `prefix` | `'mv'` | class prefix |
 
 A *target* can be any of these:
@@ -150,21 +167,21 @@ Every npm release's `dist/` is on jsDelivr (and unpkg); the bundles carry MathZe
 page needs nothing else:
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@mathzetta/inlinemath@0.1/dist/fonts/fonts.css">
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@mathzetta/inlinemath@0.1/dist/inlinemath.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@mathzetta/inlinemath@0.2/dist/fonts/fonts.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@mathzetta/inlinemath@0.2/dist/inlinemath.css">
 
 <!-- a script tag: window.InlineMath -->
-<script src="https://cdn.jsdelivr.net/npm/@mathzetta/inlinemath@0.1/dist/inlinemath.global.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@mathzetta/inlinemath@0.2/dist/inlinemath.global.min.js"></script>
 <script>document.getElementById('out').innerHTML = InlineMath.toHTML('\\frac{d}{dx} x^2');</script>
 
 <!-- or modules: inlinemath.js, markdown.js, cas.js (the CAS one holds MathZetta CAS too) -->
 <script type="module">
-  import { toHTML } from 'https://cdn.jsdelivr.net/npm/@mathzetta/inlinemath@0.1/dist/inlinemath.js';
-  import { markdownToHTML } from 'https://cdn.jsdelivr.net/npm/@mathzetta/inlinemath@0.1/dist/markdown.js';
+  import { toHTML } from 'https://cdn.jsdelivr.net/npm/@mathzetta/inlinemath@0.2/dist/inlinemath.js';
+  import { markdownToHTML } from 'https://cdn.jsdelivr.net/npm/@mathzetta/inlinemath@0.2/dist/markdown.js';
 </script>
 ```
 
-`@0.1` follows the latest 0.1.x; `@0.1.0` pins a release.
+`@0.2` follows the latest 0.2.x; `@0.2.0` pins a release.
 
 **The stylesheet is required** — the drawing is HTML laid out by `inlinemath.css` (6.9 KB, 2.1 KB
 gzipped): without it fractions, radicals and brackets don't line up. The classic builds
@@ -200,7 +217,7 @@ map (every name can point at the one MathZetta bundle). The fonts are 94 KB more
                "mathzetta/calculate": "https://cdn.jsdelivr.net/npm/mathzetta@1/build/mathzetta.esm.min.js" } }
 </script>
 <script type="module">
-  import { toHTML } from 'https://cdn.jsdelivr.net/npm/@mathzetta/inlinemath@0.1/dist/inlinemath.external.js';
+  import { toHTML } from 'https://cdn.jsdelivr.net/npm/@mathzetta/inlinemath@0.2/dist/inlinemath.external.js';
 </script>
 ```
 
@@ -218,8 +235,37 @@ el.innerHTML = markdownToHTML(text, { blocks: casBlocks() }); // {{solve(…)}},
   `\(…\)` / `\[…\]`. MathZetta reads it, so LaTeX, plain text (`$sqrt(x)/2$`) and
   code all work.
 - **Working out:** `{{…}}` inside maths is worked out (the calculator, or the CAS with
-  `blocks`). A definition like `$r = 3$` or `$g := 9.81$` is remembered, exactly, for
-  the `{{…}}` after it (`define: false` turns that off; `scope: { r: 3 }` gives values).
+  `blocks`). A definition like `$r = 3$` is remembered, exactly, for the `{{…}}` after it
+  (`define: false` turns that off; `scope: { r: 3 }` gives values).
+- **Saved variables:** `$A := 2+2$` saves A (drawn A ≔ 2 + 2), and `$_A := 2+2$` saves it
+  without drawing anything. After that, A in any maths is drawn as its expression and `{{A}}`
+  is its value, so `$A = {{A}}$` draws 2 + 2 = 4 and `$3A$` draws 3(2 + 2). A name is a letter
+  (Greek too), optionally with a subscript (`A_1`); a variable may use the ones before it
+  (`$_B := 2A$`), and saving it again replaces it from there on. A plain `$r = 3$` still only
+  remembers the number: r keeps being drawn as r.
+- **Matrices:** `\begin{pmatrix}…`, `bmatrix`, `vmatrix` (and `[[1, 2], [3, 4]]`) are drawn as
+  a grid in brackets as tall as it, and worked out exactly: `{{A^2}}`, `{{A^{-1}}}`, `{{A^T}}`,
+  `{{det(A)}}`, `{{A [5, 6]}}`, `{{linsolve(A, b)}}`. A saved variable can hold one:
+  `$_M := [[2, 1], [1, 3]]$` then `$M^2 = {{M^2}}$`.
+- **With the CAS:** `{ blocks: casBlocks() }` works out `{{der(x^2, x)}}` (also `diff`,
+  `derivative`, `d/dx …`), `{{integral(x^2, x)}}`, `{{solve(…, x)}}`, `{{factor(…)}}` …, and a
+  saved variable stands for its expression there: after `$_f := x^3 + 2x$`, `{{der(f, x)}}` is
+  3x² + 2.
+- **Inputs:** `$A := [[2+2]]$` is a textbox that sets A, `$f := [[x^2 | sin(x) | 2x]]$` a
+  dropdown, `$n := [[1..10]]$` a slider (`[[0..1 step 0.05 = 0.5]]`: a step and a starting
+  value); with `$_…$` only the input is shown. `renderMarkdownInto(el, text)` makes them live:
+  every part of the page drawn with it shares the page's store (`variables`), so a variable
+  saved in one part is used in the others, and changing an input redraws everything that uses
+  it. `variables.set('A', 'x^2')` sets one from code, `variables.get('A')` reads it;
+  `{ variables: createVariables() }` gives a part a store of its own, `{ variables: false }` none.
+  `markdownToHTML` is static: inputs drawn at their starting values.
+- **Editing by double-click:** in `renderMarkdownInto`, a part drawn from a textbox variable is
+  edited where it is drawn with `{ editable: { toText } }` (the whole variable is written back
+  into its textbox, so everything using it redraws); without `toText` the textbox is focused.
+  Double-clicking any other part fires `inlinemath:select` on the element with where that maths
+  is in the Markdown (`detail.start`, `detail.end`, `detail.raw`; for a part drawn from a
+  variable saved in the same text, where it was saved), so an editor beside it can select it.
+  `extractMath` gives every piece's `start` and `end` too.
 - **Dollars:** a `$` is maths only when it looks like it (Pandoc's rule): "$5 and $10"
   stays text, and `\$` is a dollar sign. Code spans and fences are left alone.
 - **Bad maths:** maths that doesn't read is shown as written, marked, with the reason as
@@ -260,7 +306,6 @@ playground: any input, any operation, detail level, and a live rule editor).
 
 **Notation MathZetta doesn't read yet** (Inline Math can only draw what parses):
 - **Evaluation bars:** `[F(x)]_0^1` reads as a power of a subscript, and `\left. F \right|_0^1` is rejected.
-- **Matrices:** `\begin{pmatrix}` becomes nested lists.
 - **Partial derivatives:** `\partial f / \partial x` becomes products.
 - **Derivative orders:** `f^{(4)}` becomes a power.
 - **Lists of answers:** `x = 2, x = -3` is rejected.
@@ -270,11 +315,10 @@ playground: any input, any operation, detail level, and a live rule editor).
 1. **Exit animation.** Parts that disappear in a step should fade out where they were (ghost copies). Today they vanish, and new signs and bars just appear.
 2. **Step-diff helper.** Given `step.before`, `step.after` and `step.path`, return what changed, then highlight → animate → un-highlight in one call. That would be the video's main move.
 3. **Narration sync.** Something like `view.follow(segments, timings)`: drive highlights from a text-to-speech engine's word timings (`words: [{start, end, i, j}]`).
-4. **Click-to-edit.** Swap a clicked node for an input box showing its text (`toText` / LaTeX), re-parse, and splice it back in. This was a good inline-math idea.
-5. **Copy as LaTeX or text** from a selection.
-6. **Line breaking and alignment.** Multi-line derivations with the `=` signs lined up (an `align` helper), and breaking long sums.
-7. **A DOM refine pass, optional.** Measure once after fonts load, to nudge fraction bars and script heights where the em estimates are off with unusual fonts.
-8. **Spacing table.** Move the per-operator spacing (bin, rel, thin) into one table so a house style is one edit.
+4. **Copy as LaTeX or text** from a selection.
+5. **Line breaking and alignment.** Multi-line derivations with the `=` signs lined up (an `align` helper), and breaking long sums.
+6. **A DOM refine pass, optional.** Measure once after fonts load, to nudge fraction bars and script heights where the em estimates are off with unusual fonts.
+7. **Spacing table.** Move the per-operator spacing (bin, rel, thin) into one table so a house style is one edit.
 
 ## Known rough edges