@drghaliasri/butex 4.2.0 → 4.4.0

package/README.md

@@ -118,6 +118,30 @@ Use this when you only need to render LaTeX strings:
 
 This mode does not require the GUI editor runtime.
 
+### Host CSS resets (Tailwind Preflight and similar)
+
+MathJax renders SVG equations as inline `<svg>` elements, and MathJax 4's inline
+line-breaking can emit one equation as **several sibling `<svg>` chunks**. Global
+CSS resets that declare `svg { display: block }` (e.g. **Tailwind Preflight**)
+stack those chunks vertically, so equations render one term per line.
+
+BuTeX's injected styles guard against this with:
+
+```css
+mjx-container svg {
+  display: inline;
+}
+```
+
+The guard ships in both `injectBuTeXStyles()` (`BUTEX_CHROME_CSS`) and
+`injectBuTeXDocument2Styles()` (`DOCUMENT2_WIDGET_CSS`), so make sure the host
+calls at least one of them (or embeds the CSS constants). If your app injects
+neither and you see stacked/wrapped equations under Tailwind, add the rule above
+to your global stylesheet after the reset.
+
+Also pin the MathJax version the host loads (e.g. `mathjax@4.1`) instead of a
+floating major tag, so CDN updates cannot change rendering behavior silently.
+
 ### 2) GUI editor contract (shippable editor UX)
 
 Use this when you want the same editor UX as the demo:
@@ -231,6 +255,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 +332,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/index.global.js

@@ -101,6 +101,14 @@ ${BUTEX_TAKWEEN_FONT_FACE_CSS}
   var BUTEX_CHROME_CSS = `
 ${BUTEX_FONT_FACE_CSS}
 
+/* Guard against host CSS resets (e.g. Tailwind Preflight's \`svg { display: block }\`).
+ * MathJax relies on the browser default \`display: inline\` for its SVG output; with
+ * MathJax v4 inline line-breaking an equation can be emitted as several sibling
+ * <svg> chunks, and a block-level reset stacks them vertically. */
+mjx-container svg {
+  display: inline;
+}
+
 /* BuTeX: Arabic sqrt \u2014 outer mirror entire radical, inner unmirror index & radicand */
 mjx-container[jax="CHTML"] .mjx-rtl-mirror {
   transform: scaleX(-1);