@drghaliasri/butex 4.2.0 → 4.3.0

package/README.md

@@ -231,6 +231,60 @@ const preview = document2Preview(documentNode, 'svg');
 
 V2 exports Arabic TeX by default for equations saved from the embedded editor. Imported raw-only math is preserved as raw source and marked non-editable until a structured equation object is attached.
 
+### Document JSON contract (`value` + `math_objects`)
+
+Both document layers import the same shape. A text field holds `value` (the full string, **with math delimiters kept in place**) and an optional parallel `math_objects` array that supplies the structured equation AST for each math span found in that string.
+
+Rules:
+
+- **Detect, then align.** The importer scans `value` for delimiters (`$…$`, `\(…\)`, `\[…\]`, `$$…$$`, and math environments) and binds each detected span to `math_objects` **in reading order (left-to-right)**.
+- **Count and order must match.** Extra or missing entries produce a diagnostic; the browser never silently remaps. `math_mode`/`closing` on each `MathObject` must match the delimiter in `value`.
+- **Per field, not per document.** Each paragraph, heading, and list `item` carries its own `math_objects`.
+- **Tables are the exception:** one flat `math_objects` array lives on the `\begin{tabular}` block and is consumed **row-major** across all cells (each cell takes as many entries as it has spans).
+- **Missing `math_objects`** → the span renders as a non-editable raw math chip from its delimited source.
+- The browser **does not** parse equation LaTeX bodies into `ChainClass`; structured chains come from `math_objects` (import) or the equation editor (GUI).
+
+Paragraph with one inline span:
+
+```json
+{
+  "command": "\\paragraph",
+  "value": "لدينا $x^2$ ثابت.",
+  "math_objects": [
+    { "node_type": "MathObject", "math_mode": "$",
+      "lines": [{ "node_type": "ChainClass", "chain": [] }], "closing": "$" }
+  ]
+}
+```
+
+List item with a display span (`math_mode`/`closing` match the delimiter in `value`):
+
+```json
+{
+  "value": "الحل \\[a+b\\]",
+  "math_objects": [
+    { "node_type": "MathObject", "math_mode": "\\[",
+      "lines": [{ "node_type": "ChainClass", "chain": [] }], "closing": "\\]" }
+  ]
+}
+```
+
+Table: one flat array, consumed row-major (here `$x$`, then `$y$`):
+
+```json
+{
+  "command": "\\begin{tabular}",
+  "columns": "cc",
+  "rows": [["الرمز $x$", "القيمة"], ["الرمز $y$", "القيمة"]],
+  "math_objects": [
+    { "node_type": "MathObject", "math_mode": "$",
+      "lines": [{ "node_type": "ChainClass", "chain": [] }], "closing": "$" },
+    { "node_type": "MathObject", "math_mode": "$",
+      "lines": [{ "node_type": "ChainClass", "chain": [] }], "closing": "$" }
+  ]
+}
+```
+
 ### Document React widget v2 (`butex/react-document2`)
 
 Use this entry for the new document editor integration. It opens embedded `<ButexEditor />` sessions in Arabic/RTL mode by default and renders document preview math islands with MathJax **SVG** by default (`mathOutput` defaults to `'svg'`; pass `mathOutput="chtml"` only if the host loads `tex-chtml.js`).
@@ -254,7 +308,7 @@ export default function Page() {
 }
 ```
 
-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. 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"`.
+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. 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/react-document2.d.mts

@@ -285,6 +285,8 @@ type ButexDocumentEditor2Props = {
     documentDirection?: 'rtl' | 'ltr';
     equationSide?: EditorSide;
     editableEquations?: boolean;
+    /** When true, render only the read-only document preview (no toolbar, editor panel, or equation drawer). */
+    previewOnly?: boolean;
     uiLocale?: ButexUiLocale;
     mathOutput?: Document2MathOutput;
     onDocumentChange?: (document: Document2Node) => void;
@@ -295,7 +297,7 @@ type Document2InitialState = {
     error: string | null;
 };
 declare function resolveInitialDocument2(initialDocument: Document2Json | Document2Node | undefined, uiLocale?: ButexUiLocale): Document2InitialState;
-declare function ButexDocumentEditor2({ initialDocument, className, debug, documentDirection, equationSide, editableEquations, uiLocale, mathOutput, onDocumentChange, onLatexChange, }: ButexDocumentEditor2Props): react_jsx_runtime.JSX.Element;
+declare function ButexDocumentEditor2({ initialDocument, className, debug, documentDirection, equationSide, editableEquations, previewOnly, uiLocale, mathOutput, onDocumentChange, onLatexChange, }: ButexDocumentEditor2Props): react_jsx_runtime.JSX.Element;
 
 type DocumentInsertToolbarProps = {
     canUndo: boolean;

package/dist/react-document2.d.ts

@@ -285,6 +285,8 @@ type ButexDocumentEditor2Props = {
     documentDirection?: 'rtl' | 'ltr';
     equationSide?: EditorSide;
     editableEquations?: boolean;
+    /** When true, render only the read-only document preview (no toolbar, editor panel, or equation drawer). */
+    previewOnly?: boolean;
     uiLocale?: ButexUiLocale;
     mathOutput?: Document2MathOutput;
     onDocumentChange?: (document: Document2Node) => void;
@@ -295,7 +297,7 @@ type Document2InitialState = {
     error: string | null;
 };
 declare function resolveInitialDocument2(initialDocument: Document2Json | Document2Node | undefined, uiLocale?: ButexUiLocale): Document2InitialState;
-declare function ButexDocumentEditor2({ initialDocument, className, debug, documentDirection, equationSide, editableEquations, uiLocale, mathOutput, onDocumentChange, onLatexChange, }: ButexDocumentEditor2Props): react_jsx_runtime.JSX.Element;
+declare function ButexDocumentEditor2({ initialDocument, className, debug, documentDirection, equationSide, editableEquations, previewOnly, uiLocale, mathOutput, onDocumentChange, onLatexChange, }: ButexDocumentEditor2Props): react_jsx_runtime.JSX.Element;
 
 type DocumentInsertToolbarProps = {
     canUndo: boolean;

package/dist/react-document2.js

@@ -11556,6 +11556,7 @@ function ButexDocumentEditor2({
   documentDirection = "rtl",
   equationSide = "arabic",
   editableEquations = true,
+  previewOnly = false,
   uiLocale = "ar",
   mathOutput = "svg",
   onDocumentChange,
@@ -11598,10 +11599,10 @@ function ButexDocumentEditor2({
     injectBuTeXDocument2Styles();
   }, []);
   (0, import_react6.useEffect)(() => {
-    if (!editableEquations) {
+    if (!editableEquations || previewOnly) {
       setSelectedMath(null);
     }
-  }, [editableEquations]);
+  }, [editableEquations, previewOnly]);
   (0, import_react6.useEffect)(() => {
     const next = resolveInitialDocument2(initialDocument, uiLocale);
     setDocumentNode(next.document);
@@ -11890,6 +11891,8 @@ function ButexDocumentEditor2({
     pendingFocusRef.current = focusAfterDeletedMath(current, next, tokenId);
     applyDocument(next, "immediate");
   }
+  const showEditorPanel = !previewOnly && editorOpen;
+  const showPreviewPanel = previewOnly || previewOpen;
   return /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
     "div",
     {
@@ -11898,7 +11901,7 @@ function ButexDocumentEditor2({
       dir: uiLocaleDirection(uiLocale),
       lang: uiLocale,
       children: /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("div", { className: "butex-document2-widget__shell", children: [
-        /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("div", { className: "butex-document2-widget__toolbar", children: [
+        !previewOnly ? /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("div", { className: "butex-document2-widget__toolbar", children: [
           /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
             DocumentInsertToolbar,
             {
@@ -11928,19 +11931,19 @@ function ButexDocumentEditor2({
             /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("button", { type: "button", onClick: collapseAllBlocks, children: messages.collapseAll }),
             /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("button", { type: "button", onClick: openAllBlocks, children: messages.openAll })
           ] })
-        ] }),
+        ] }) : null,
         error ? /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("p", { className: "butex-document2-widget__error", children: error }) : null,
         /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(
           "div",
           {
-            className: `butex-document2-widget__layout butex-document2-widget__layout--editor-${editorOpen ? "open" : "closed"} butex-document2-widget__layout--preview-${previewOpen ? "open" : "closed"}`,
+            className: `butex-document2-widget__layout butex-document2-widget__layout--editor-${showEditorPanel ? "open" : "closed"} butex-document2-widget__layout--preview-${showPreviewPanel ? "open" : "closed"}`,
             children: [
-              /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
+              !previewOnly ? /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
                 "section",
                 {
                   className: "butex-document2-widget__panel butex-document2-widget__editor-panel",
                   "aria-label": messages.documentEditor,
-                  "aria-hidden": !editorOpen,
+                  "aria-hidden": !showEditorPanel,
                   children: /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("div", { className: "butex-document2-widget__blocks", children: documentNode.blocks.map((block, blockIndex) => /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
                     BlockEditor,
                     {
@@ -11970,13 +11973,13 @@ function ButexDocumentEditor2({
                     block.id
                   )) })
                 }
-              ),
+              ) : null,
               /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
                 "section",
                 {
                   className: "butex-document2-widget__panel butex-document2-widget__preview-panel",
                   "aria-label": messages.documentPreview,
-                  "aria-hidden": !previewOpen,
+                  "aria-hidden": !showPreviewPanel,
                   children: /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(DocumentPreview, { blocks: preview.blocks, output: mathOutput, documentDirection, uiLocale })
                 }
               )
@@ -11993,7 +11996,7 @@ function ButexDocumentEditor2({
           /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("strong", { children: "AST" }),
           /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("pre", { children: JSON.stringify(documentNode, null, 2) })
         ] }) : null,
-        selectedMath ? /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
+        !previewOnly && selectedMath ? /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
           EquationDrawer,
           {
             session: selectedMath.session,