@drghaliasri/butex 5.5.5 → 5.6.1

package/README.md

@@ -64,7 +64,7 @@ Peer dependency: `mathjax` ^4.x (aligned with MathJax 4 components). If you use
 5. When using **SVG** (`tex-svg.js`), call `BuTeX.registerBuTeXSvgTextWrapper(MathJax)` **after** `defaultReady()` so Takween/Diwani/Maghribi text, `\ad`, and Arabic atomic commands (`\arsin`, etc.) render in the preview with the correct fonts. CommonHTML (`tex-chtml.js`) uses the injected CSS classes instead.
 6. Render math with `renderBuTeXMathIsland(tex, options?)` or mount into a host element via `mountBuTeXMathIsland(host, tex, options?)`. Pass `output: 'svg'` when the host loads `tex-svg.js`, or `output: 'chtml'` with `tex-chtml.js`. For raw Arabic TeX that did not come from the editor AST, pass `mirrorOperators: true` to wrap directional operators according to BuTeX's shared operator table. `ButexEditor` picks SVG vs CHTML automatically from the loaded MathJax bundle (`tex2svg` vs `tex2chtml`).
 
-Ensure TeX `packages` includes `butex-arabic-math` (use `BUTEX_TEX_PACKAGE` in config when using `{ '[+]': [...] }`).
+Ensure TeX `packages` includes `butex-arabic-math` (use `BUTEX_TEX_PACKAGE` in config when using `{ '[+]': [...] }`). BuTeX registers lightweight browser compatibility macros for toolbar symbols such as `\coloneqq` and `\eqqcolon`; XeLaTeX export still relies on the document preamble's `mathtools`.
 
 ## Usage (npm / bundler)
 
@@ -393,6 +393,44 @@ onDocumentChange={(node) => {
 
 Do not call `JSON.stringify(documentNode)` directly. JSON serialization removes `CharNode`, `CommandNode`, and other equation prototypes: the saved TeX source can still render in preview, but the structured equation cannot reopen in the editor. Also do not feed every change callback back into `initialDocument`; that prop is for initial or externally loaded data, and changing it resets the editor state and undo history. Keep the current save snapshot in a ref or separate state that is not passed back as `initialDocument`. Change callbacks run during editing, so debounce network autosaves or save explicitly.
 
+##### Host-driven figure insert
+
+After an external upload (for example S3), insert a figure on the **live** editor without remounting or rewriting `initialDocument`:
+
+```tsx
+'use client';
+
+import { useRef } from 'react';
+import {
+  ButexDocumentEditor2,
+  type ButexDocumentEditor2Ref,
+} from '@drghaliasri/butex/react-document2';
+
+export function ArticleEditorWithUpload() {
+  const editorRef = useRef<ButexDocumentEditor2Ref>(null);
+
+  async function onFileUploaded(uuid: string) {
+    // Sets \\includegraphics{assets/<uuid>.jpg} after the focused block.
+    // Do not call addDocument2ImageBlock outside the component or remount with key++.
+    editorRef.current?.insertImageBlock(`assets/${uuid}.jpg`);
+  }
+
+  return (
+    <ButexDocumentEditor2
+      ref={editorRef}
+      resolveImageUrl={({ assetId, value }) =>
+        assetId ? `https://cdn.example/${assetId}` : value
+      }
+      onDocumentJsonChange={(json) => {
+        /* persist json */
+      }}
+    />
+  );
+}
+```
+
+`insertImageBlock` matches the toolbar figure button (focus-aware insert + undo snapshot). Use `updateImageBlockValue(blockId, value)` to change a path on an existing image block, and `getDocumentJson()` to read the canonical wire JSON without host-side AST mutation.
+
 Host apps still register BuTeX with MathJax before preview rendering. `uiLocale` selects Arabic (`"ar"`, the default) or English (`"en"`) document-editor chrome and is passed to the embedded equation editor. `documentDirection` independently controls prose inputs and preview flow without creating a second document tree. `equationSide` independently controls whether structured equations open, render, and save from the `"english"` or `"arabic"` side. Set `editableEquations={false}` to show math islands without equation insertion, deletion, or editor access. Set `previewOnly={true}` to render only the read-only document preview with no toolbar, editor panel, or equation drawer. Optional `\includegraphics` `asset_id` is preserved on import; pass `resolveImageUrl={({ assetId, value }) => …})` so preview can load S3/CDN/local assets while plain `value` URLs keep working without a resolver. Document JSON may include root `meta` (`title`, `authors`, structured Hijri `date` `{ day, month, year }` with Arabic month names such as `"محرم"`, `abstract`) plus a `references` catalog (`key`, `authors`, `title`, `year`, `url`, `venue`) and `\cite{key1,key2}` spans in text values. Pass `documentMeta` to seed missing meta fields from the host; JSON keys win when present. The editor always centers a fixed basmala line before the title block and a closing ḥamdala after the body (preview + LaTeX). Hijri date uses day/month/year dropdowns (no calendar conversion; default year 1448). The editor shows numeric cite chips and a bibliography block. RTL preview/chips render reversed labels such as `[٣،٢،١]` (Arabic comma); LTR stays `[1, 2, 3]`. Pass `digitForm` (`western` / `arabicIndic` / `persianIndic`, defaulting from `documentDirection`) or use the toolbar digit control. LaTeX export keeps logical `\cite{…}` key order for XeLaTeX; digit shaping and bidi display in PDF belong in the host preamble (`bidi`/polyglossia + font `Mapping`, see `references/commands.py`). Range compression (`[3–7]`) is not implemented yet. Raw-only equations keep their original source because the browser does not parse raw LaTeX into equation ASTs. Document editor v2 defaults to **`tex-svg.js`**; use `tex-chtml.js` only if you pass `mathOutput="chtml"`.
 
 ### Styling/theming contract

package/dist/document.js

@@ -1379,6 +1379,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     category: "operators1",
     Tex: "\\neq",
     mirror: true,
+    compileMirror: true,
     Label: "\u2260",
     title: "\u0644\u0627 \u064A\u0633\u0627\u0648\u064A",
     svg_path: null
@@ -1418,6 +1419,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     Tex: "\\leq",
     mirror: true,
     displayMirror: false,
+    compileMirror: true,
     Label: "\u2264",
     title: "\u0623\u0635\u063A\u0631 \u0645\u0646 \u0623\u0648 \u064A\u0633\u0627\u0648\u064A",
     svg_path: null
@@ -1428,6 +1430,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     Tex: "\\geq",
     mirror: true,
     displayMirror: false,
+    compileMirror: true,
     Label: "\u2265",
     title: "\u0623\u0643\u0628\u0631 \u0645\u0646 \u0623\u0648 \u064A\u0633\u0627\u0648\u064A",
     svg_path: null
@@ -1438,6 +1441,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     Tex: "\\coloneqq",
     mirror: true,
     displayMirror: false,
+    compileMirror: true,
     Label: "\u2254",
     title: "\u064A\u0639\u0631\u0641 \u0628\u0623\u0646\u0647 \u064A\u0633\u0627\u0648\u064A",
     svg_path: null
@@ -1448,6 +1452,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     Tex: "\\eqqcolon",
     mirror: true,
     displayMirror: false,
+    compileMirror: true,
     Label: "\u2255",
     title: "\u064A\u0633\u0627\u0648\u064A \u0628\u0627\u0644\u062A\u0639\u0631\u064A\u0641",
     svg_path: null
@@ -1459,6 +1464,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     Tex: "\\propto",
     mirror: true,
     displayMirror: false,
+    compileMirror: true,
     Label: "\u221D",
     title: "\u064A\u062A\u0646\u0627\u0633\u0628 \u0645\u0639",
     svg_path: null
@@ -1469,6 +1475,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     Tex: "\\in",
     mirror: true,
     displayMirror: false,
+    compileMirror: true,
     Label: "\u2208",
     title: "\u064A\u0646\u062A\u0645\u064A \u0625\u0644\u0649",
     svg_path: null
@@ -1489,6 +1496,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     Tex: "\\subset",
     mirror: true,
     displayMirror: false,
+    compileMirror: true,
     Label: "\u2282",
     title: "\u0645\u062C\u0645\u0648\u0639\u0629 \u062C\u0632\u0626\u064A\u0629 \u0645\u0646",
     svg_path: null
@@ -1499,6 +1507,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     Tex: "\\supset",
     mirror: true,
     displayMirror: false,
+    compileMirror: true,
     Label: "\u2283",
     title: "\u0645\u062C\u0645\u0648\u0639\u0629 \u0634\u0627\u0645\u0644\u0629 \u0644\u0640",
     svg_path: null
@@ -1509,6 +1518,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     Tex: "\\subseteq",
     mirror: true,
     displayMirror: false,
+    compileMirror: true,
     Label: "\u2286",
     title: "\u0645\u062C\u0645\u0648\u0639\u0629 \u062C\u0632\u0626\u064A\u0629 \u0623\u0648 \u062A\u0633\u0627\u0648\u064A",
     svg_path: null
@@ -1519,6 +1529,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     Tex: "\\supseteq",
     mirror: true,
     displayMirror: false,
+    compileMirror: true,
     Label: "\u2287",
     title: "\u0645\u062C\u0645\u0648\u0639\u0629 \u0634\u0627\u0645\u0644\u0629 \u0623\u0648 \u062A\u0633\u0627\u0648\u064A",
     svg_path: null
@@ -1559,6 +1570,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     Tex: "\\nsubseteq",
     mirror: true,
     displayMirror: false,
+    compileMirror: true,
     Label: "\u2288",
     title: "\u0644\u064A\u0633\u062A \u0645\u062C\u0645\u0648\u0639\u0629 \u062C\u0632\u0626\u064A\u0629 \u0623\u0648 \u062A\u0633\u0627\u0648\u064A",
     svg_path: null
@@ -1569,6 +1581,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     Tex: "\\nsupseteq",
     mirror: true,
     displayMirror: false,
+    compileMirror: true,
     Label: "\u2289",
     title: "\u0644\u064A\u0633\u062A \u0645\u062C\u0645\u0648\u0639\u0629 \u0634\u0627\u0645\u0644\u0629 \u0623\u0648 \u062A\u0633\u0627\u0648\u064A",
     svg_path: null
@@ -1616,6 +1629,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     Tex: "\\ddots",
     mirror: true,
     displayMirror: false,
+    compileMirror: true,
     Label: "\u22F1",
     title: "\u0646\u0642\u0627\u0637 \u0642\u0637\u0631\u064A\u0629",
     svg_path: null
@@ -1635,6 +1649,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     category: "operators3",
     Tex: "\\implies",
     mirror: true,
+    compileMirror: true,
     Label: "\u21D2",
     title: "\u064A\u0633\u062A\u0644\u0632\u0645",
     svg_path: null
@@ -1644,6 +1659,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     category: "operators3",
     Tex: "\\impliedby",
     mirror: true,
+    compileMirror: true,
     Label: "\u21D0",
     title: "\u0645\u0633\u062A\u0644\u0632\u0645 \u0645\u0646",
     svg_path: null
@@ -1662,6 +1678,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     category: "operators3",
     Tex: "\\Longrightarrow",
     mirror: true,
+    compileMirror: true,
     Label: "\u27F9",
     title: "\u0633\u0647\u0645 \u0645\u0632\u062F\u0648\u062C \u0637\u0648\u064A\u0644 \u0625\u0644\u0649 \u0627\u0644\u064A\u0645\u064A\u0646",
     svg_path: null
@@ -1671,6 +1688,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     category: "operators3",
     Tex: "\\Longleftarrow",
     mirror: true,
+    compileMirror: true,
     Label: "\u27F8",
     title: "\u0633\u0647\u0645 \u0645\u0632\u062F\u0648\u062C \u0637\u0648\u064A\u0644 \u0625\u0644\u0649 \u0627\u0644\u064A\u0633\u0627\u0631",
     svg_path: null
@@ -1680,6 +1698,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     category: "operators3",
     Tex: "\\to",
     mirror: true,
+    compileMirror: true,
     Label: "\u2192",
     title: "\u064A\u0624\u0648\u0644 \u0625\u0644\u0649",
     svg_path: null
@@ -1689,6 +1708,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     category: "operators3",
     Tex: "\\rightleftharpoons",
     mirror: true,
+    compileMirror: true,
     Label: "\u21CC",
     title: "\u0627\u062A\u0632\u0627\u0646",
     svg_path: null
@@ -1698,6 +1718,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     category: "operators3",
     Tex: "\\leftarrow",
     mirror: true,
+    compileMirror: true,
     Label: "\u2190",
     title: "\u0633\u0647\u0645 \u0625\u0644\u0649 \u0627\u0644\u064A\u0633\u0627\u0631",
     svg_path: null
@@ -1707,6 +1728,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     category: "operators3",
     Tex: "\\rightarrow",
     mirror: true,
+    compileMirror: true,
     Label: "\u2192",
     title: "\u0633\u0647\u0645 \u0625\u0644\u0649 \u0627\u0644\u064A\u0645\u064A\u0646",
     svg_path: null
@@ -1716,6 +1738,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     category: "operators3",
     Tex: "\\Leftarrow",
     mirror: true,
+    compileMirror: true,
     Label: "\u21D0",
     title: "\u0633\u0647\u0645 \u0645\u0632\u062F\u0648\u062C \u0625\u0644\u0649 \u0627\u0644\u064A\u0633\u0627\u0631",
     svg_path: null
@@ -1725,6 +1748,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     category: "operators3",
     Tex: "\\Rightarrow",
     mirror: true,
+    compileMirror: true,
     Label: "\u21D2",
     title: "\u0633\u0647\u0645 \u0645\u0632\u062F\u0648\u062C \u0625\u0644\u0649 \u0627\u0644\u064A\u0645\u064A\u0646",
     svg_path: null
@@ -1734,6 +1758,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     category: "operators3",
     Tex: "\\leftharpoonup",
     mirror: true,
+    compileMirror: true,
     Label: "\u21BC",
     title: "\u0633\u0647\u0645 \u062E\u0637\u0627\u0641\u064A \u0639\u0644\u0648\u064A \u0625\u0644\u0649 \u0627\u0644\u064A\u0633\u0627\u0631",
     svg_path: null
@@ -1743,6 +1768,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     category: "operators3",
     Tex: "\\rightharpoonup",
     mirror: true,
+    compileMirror: true,
     Label: "\u21C0",
     title: "\u0633\u0647\u0645 \u062E\u0637\u0627\u0641\u064A \u0639\u0644\u0648\u064A \u0625\u0644\u0649 \u0627\u0644\u064A\u0645\u064A\u0646",
     svg_path: null
@@ -1752,6 +1778,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     category: "operators3",
     Tex: "\\leftharpoondown",
     mirror: true,
+    compileMirror: true,
     Label: "\u21BD",
     title: "\u0633\u0647\u0645 \u062E\u0637\u0627\u0641\u064A \u0633\u0641\u0644\u064A \u0625\u0644\u0649 \u0627\u0644\u064A\u0633\u0627\u0631",
     svg_path: null
@@ -1761,6 +1788,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     category: "operators3",
     Tex: "\\rightharpoondown",
     mirror: true,
+    compileMirror: true,
     Label: "\u21C1",
     title: "\u0633\u0647\u0645 \u062E\u0637\u0627\u0641\u064A \u0633\u0641\u0644\u064A \u0625\u0644\u0649 \u0627\u0644\u064A\u0645\u064A\u0646",
     svg_path: null
@@ -1771,6 +1799,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     category: "integrals",
     Tex: "\\int",
     mirror: true,
+    compileMirror: true,
     Label: "\u222B",
     title: "\u062A\u0643\u0627\u0645\u0644",
     svg_path: null
@@ -1781,6 +1810,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     Tex: "\\iint",
     mirror: true,
     displayMirror: false,
+    compileMirror: true,
     Label: "\u222C",
     title: "\u062A\u0643\u0627\u0645\u0644 \u0645\u0632\u062F\u0648\u062C",
     svg_path: null
@@ -1791,6 +1821,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     Tex: "\\iiint",
     mirror: true,
     displayMirror: false,
+    compileMirror: true,
     Label: "\u222D",
     title: "\u062A\u0643\u0627\u0645\u0644 \u062B\u0644\u0627\u062B\u064A",
     svg_path: null
@@ -1801,6 +1832,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     Tex: "\\iiiint",
     mirror: true,
     displayMirror: false,
+    compileMirror: true,
     Label: "\u2A0C",
     title: "\u062A\u0643\u0627\u0645\u0644 \u0631\u0628\u0627\u0639\u064A",
     svg_path: null
@@ -1811,6 +1843,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     Tex: "\\oint",
     mirror: true,
     displayMirror: false,
+    compileMirror: true,
     Label: "\u222E",
     title: "\u062A\u0643\u0627\u0645\u0644 \u0645\u063A\u0644\u0642",
     svg_path: null
@@ -1821,6 +1854,7 @@ var ATOMIC_OPERATOR_COMMANDS = {
     Tex: "\\oiint",
     mirror: true,
     displayMirror: false,
+    compileMirror: true,
     Label: "\u222F",
     title: "\u062A\u0643\u0627\u0645\u0644 \u0633\u0637\u062D\u064A \u0645\u063A\u0644\u0642",
     svg_path: null
@@ -1831,12 +1865,14 @@ var ATOMIC_OPERATOR_COMMANDS = {
     Tex: "\\oiiint",
     mirror: true,
     displayMirror: false,
+    compileMirror: true,
     Label: "\u2230",
     title: "\u062A\u0643\u0627\u0645\u0644 \u062D\u062C\u0645\u064A \u0645\u063A\u0644\u0642",
     svg_path: null
   }
 };
 var MIRRORED_OPERATOR_TEX = Object.values(ATOMIC_OPERATOR_COMMANDS).filter((command) => command.mirror).map((command) => command.Tex).sort((a, b) => b.length - a.length);
+var COMPILE_MIRRORED_OPERATOR_TEX = Object.values(ATOMIC_OPERATOR_COMMANDS).filter((command) => "compileMirror" in command && command.compileMirror).map((command) => command.Tex).sort((a, b) => b.length - a.length);
 function atomicOperatorCommandSpec(id) {
   return Object.prototype.hasOwnProperty.call(ATOMIC_OPERATOR_COMMANDS, id) ? ATOMIC_OPERATOR_COMMANDS[id] : null;
 }