@drghaliasri/butex 5.5.2 → 5.5.3

package/README.md

@@ -271,6 +271,7 @@ Rules:
 - **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.
+- **Mixed raw and structured math** uses `null` placeholders so every detected span still has one positional entry, for example `math_objects: [null, structuredMathObject]`. A labeled raw display span uses a `RawMathObject` positional metadata entry so its label survives without pretending the equation has an editable AST.
 - 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:
@@ -337,6 +338,57 @@ export default function Page() {
 }
 ```
 
+#### Persisting Document Editor v2 state
+
+`Document2Node` is the live editor AST. It contains class-backed equation nodes and must not cross an API, database, local-storage, worker, or `JSON.stringify` boundary. Persist the canonical `Document2Json` wire format instead. The backend may store and return that JSON unchanged.
+
+Use `onDocumentJsonChange` for a persistence-ready snapshot:
+
+```tsx
+'use client';
+
+import { useRef } from 'react';
+import { ButexDocumentEditor2 } from '@drghaliasri/butex/react-document2';
+import type { Document2Json } from '@drghaliasri/butex/document2';
+
+export function ArticleEditor({ loadedDocument }: { loadedDocument: Document2Json }) {
+  const latestDocument = useRef<Document2Json>(loadedDocument);
+
+  async function saveArticle() {
+    await fetch('/api/article', {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ document: latestDocument.current }),
+    });
+  }
+
+  return (
+    <>
+      <ButexDocumentEditor2
+        initialDocument={loadedDocument}
+        editableEquations
+        onDocumentJsonChange={(json) => {
+          latestDocument.current = json;
+        }}
+      />
+      <button type="button" onClick={saveArticle}>Save</button>
+    </>
+  );
+}
+```
+
+`onDocumentChange` remains available for hosts that need the live AST. Convert it before persistence with `toDocumentJson2`:
+
+```ts
+import { toDocumentJson2 } from '@drghaliasri/butex/document2';
+
+onDocumentChange={(node) => {
+  latestDocument.current = toDocumentJson2(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 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
@@ -346,6 +398,20 @@ Host apps still register BuTeX with MathJax before preview rendering. `uiLocale`
 - Document editor theming is scoped under `.butex-document-widget`. Override `--butex-document-*` variables on that root or an ancestor, especially `--butex-document-bg`, `--butex-document-fg`, `--butex-document-panel`, `--butex-document-border`, `--butex-document-accent`, `--butex-document-preview-bg`, `--butex-document-drawer-bg`, `--butex-document-input-bg`, `--butex-document-table-border`, `--butex-document-math-bg`, and `--butex-document-dev-bg`.
 - Document editor v2 theming is scoped under `.butex-document2-widget`. Override `--butex-document2-*` variables on that root or an ancestor; defaults inherit from the existing `--butex-*` variables where practical, including accent, panel, border, preview, focus, danger/error, and debug colors. The embedded equation editor opens as a centered modal (backdrop + panel); its BuTeX chrome reads the same `--butex-document2-*` tokens via a scoped bridge, so hosts normally theme once on `.butex-document2-widget` without a second equation theme. The built-in editor uses a **sticky compact icon toolbar** (Arabic `نص` formatting icons, heading glyphs, inline `$…$` vs display `\[…\]` math buttons with tooltips, a labeled references menu, and a table size popover), **focus-aware block insertion** after the active block, **↑/↓ block reorder**, **math delete** (chip × and drawer button), **document undo/redo** (toolbar + Ctrl/⌘Z, Ctrl/⌘Shift+Z, Ctrl+Y) via AST snapshots, and theme-tinted block cards. Preview tables use fixed black cell borders; raw `\raw` blocks stay out of preview until dedicated rendering exists.
 
+#### Keeping the Document Editor v2 toolbar sticky
+
+`<ButexDocumentEditor2 />` injects `style#butex-document2-widget-styles`; its main toolbar ships with `position: sticky`, `top: 0`, and a stacking layer. If a strict CSP blocks injected inline styles, embed `DOCUMENT2_WIDGET_CSS` through the host's approved global stylesheet or nonced style path, after Tailwind Preflight or other resets.
+
+Do not override `.butex-document2-widget__toolbar` with `position: static`, `position: fixed`, a lower stacking layer, or an unrelated `top`. Avoid `overflow: auto`, `scroll`, or `hidden` on editor ancestors unless that ancestor is intentionally the constrained vertical scrolling container; sticky positioning follows the nearest such ancestor. `overflow-x: clip` by itself does not require an override. For a fixed application header, keep the toolbar sticky and apply only a scoped offset:
+
+```css
+.article-editor .butex-document2-widget__toolbar {
+  top: var(--app-header-height, 0px);
+}
+```
+
+When diagnosing host CSS, verify that `#butex-document2-widget-styles` exists and that `getComputedStyle(toolbar).position` is `sticky` before adding overrides.
+
 ## Demo
 
 From repo root (after `npm run build`):

package/dist/document.d.mts

@@ -60,7 +60,7 @@ type DocumentJson = {
 type DocumentBlockJson = {
     command: string;
     value?: string;
-    math_objects?: MathObjectJson[];
+    math_objects?: Array<MathObjectJson | null>;
     options?: Record<string, string>;
     closing?: string;
     items?: DocumentListItemJson[];
@@ -69,7 +69,7 @@ type DocumentBlockJson = {
 };
 type DocumentListItemJson = {
     value: string;
-    math_objects?: MathObjectJson[];
+    math_objects?: Array<MathObjectJson | null>;
     blocks?: DocumentBlockJson[];
 };
 type DocumentCommand = '\\section' | '\\subsection' | '\\subsubsection' | '\\paragraph' | '\\begin{itemize}' | '\\begin{enumerate}' | '\\begin{tabular}' | '\\includegraphics' | '\\raw';
@@ -156,6 +156,7 @@ declare function createImageBlock(value?: string, options?: Record<string, strin
 declare function isSupportedDocumentCommand(command: string): command is DocumentCommand;
 
 declare function fromMathObjectJson(json: unknown, mode?: DocumentParseMode): MathNode;
+declare function toMathObjectJson(math: MathNode): MathObjectJson;
 declare function renderMathNodeLatex(math: MathNode): string;
 declare function isDisplayMathNode(math: MathNode): boolean;
 
@@ -250,7 +251,7 @@ declare function mathNodeFromEditorSession(session: EditorSession, mathMode?: st
 declare function mathSourceFromEditorSession(session: EditorSession, mathMode?: string, closing?: string): string;
 
 declare function detectMathSpans(value: string): DetectedMathSpan[];
-declare function buildInlines(value: string, mathObjects?: MathObjectJson[], mode?: DocumentParseMode): DocumentInline[];
+declare function buildInlines(value: string, mathObjects?: Array<MathObjectJson | null>, mode?: DocumentParseMode): DocumentInline[];
 
 declare function renderDocumentLatex(document: DocumentNode): string;
 declare function buildDocumentPreview(document: DocumentNode): DocumentPreview;
@@ -307,4 +308,4 @@ declare function replaceMathSpanFromEditor(document: DocumentNode, target: Docum
 declare function insertMathSpanFromEditor(document: DocumentNode, target: DocumentInlineTarget, insertAt: number, math: MathNode, source?: string): DocumentNode;
 declare function documentInlineText(inlines: DocumentInline[]): string;
 
-export { type DetectedMathSpan, type DocumentBlockJson, type DocumentBlockNode, type DocumentCommand, type DocumentInline, type DocumentInlineTarget, type DocumentJson, type DocumentListItemJson, type DocumentMathTarget, type DocumentNode, type DocumentParseMode, type DocumentPreview, type DocumentPreviewMathIsland, type ImageBlockNode, type ListBlockNode, type ListItemNode, type MathInline, type MathNode, type MathObjectJson, type NewDocumentBlockKind, type RawBlockNode, type TableBlockNode, type TextBlockNode, type TextInline, addDocumentBlock, addListItem, addNestedListBlock, addTableColumn, addTableRow, buildDocumentPreview, buildInlines, createDocumentBlock, createEmptyDocument, createImageBlock, createListBlock, createRawBlock, createTableBlock, createTextBlock, detectMathSpans, documentInlineText, fromDocumentJson, fromMathObjectJson, insertMathSpanFromEditor, isDisplayMathNode, isSupportedDocumentCommand, mathNodeFromEditorSession, mathSourceFromEditorSession, moveDocumentBlock, removeDocumentBlock, removeListItem, removeTableColumn, removeTableRow, renderDocumentLatex, renderMathNodeLatex, replaceMathSpanFromEditor, replaceMathSpanSource, updateImageBlock, updateListItemValue, updateRawBlockValue, updateTableCell, updateTableColumns, updateTextBlockValue };
+export { type DetectedMathSpan, type DocumentBlockJson, type DocumentBlockNode, type DocumentCommand, type DocumentInline, type DocumentInlineTarget, type DocumentJson, type DocumentListItemJson, type DocumentMathTarget, type DocumentNode, type DocumentParseMode, type DocumentPreview, type DocumentPreviewMathIsland, type ImageBlockNode, type ListBlockNode, type ListItemNode, type MathInline, type MathNode, type MathObjectJson, type NewDocumentBlockKind, type RawBlockNode, type TableBlockNode, type TextBlockNode, type TextInline, addDocumentBlock, addListItem, addNestedListBlock, addTableColumn, addTableRow, buildDocumentPreview, buildInlines, createDocumentBlock, createEmptyDocument, createImageBlock, createListBlock, createRawBlock, createTableBlock, createTextBlock, detectMathSpans, documentInlineText, fromDocumentJson, fromMathObjectJson, insertMathSpanFromEditor, isDisplayMathNode, isSupportedDocumentCommand, mathNodeFromEditorSession, mathSourceFromEditorSession, moveDocumentBlock, removeDocumentBlock, removeListItem, removeTableColumn, removeTableRow, renderDocumentLatex, renderMathNodeLatex, replaceMathSpanFromEditor, replaceMathSpanSource, toMathObjectJson, updateImageBlock, updateListItemValue, updateRawBlockValue, updateTableCell, updateTableColumns, updateTextBlockValue };

package/dist/document.d.ts

@@ -60,7 +60,7 @@ type DocumentJson = {
 type DocumentBlockJson = {
     command: string;
     value?: string;
-    math_objects?: MathObjectJson[];
+    math_objects?: Array<MathObjectJson | null>;
     options?: Record<string, string>;
     closing?: string;
     items?: DocumentListItemJson[];
@@ -69,7 +69,7 @@ type DocumentBlockJson = {
 };
 type DocumentListItemJson = {
     value: string;
-    math_objects?: MathObjectJson[];
+    math_objects?: Array<MathObjectJson | null>;
     blocks?: DocumentBlockJson[];
 };
 type DocumentCommand = '\\section' | '\\subsection' | '\\subsubsection' | '\\paragraph' | '\\begin{itemize}' | '\\begin{enumerate}' | '\\begin{tabular}' | '\\includegraphics' | '\\raw';
@@ -156,6 +156,7 @@ declare function createImageBlock(value?: string, options?: Record<string, strin
 declare function isSupportedDocumentCommand(command: string): command is DocumentCommand;
 
 declare function fromMathObjectJson(json: unknown, mode?: DocumentParseMode): MathNode;
+declare function toMathObjectJson(math: MathNode): MathObjectJson;
 declare function renderMathNodeLatex(math: MathNode): string;
 declare function isDisplayMathNode(math: MathNode): boolean;
 
@@ -250,7 +251,7 @@ declare function mathNodeFromEditorSession(session: EditorSession, mathMode?: st
 declare function mathSourceFromEditorSession(session: EditorSession, mathMode?: string, closing?: string): string;
 
 declare function detectMathSpans(value: string): DetectedMathSpan[];
-declare function buildInlines(value: string, mathObjects?: MathObjectJson[], mode?: DocumentParseMode): DocumentInline[];
+declare function buildInlines(value: string, mathObjects?: Array<MathObjectJson | null>, mode?: DocumentParseMode): DocumentInline[];
 
 declare function renderDocumentLatex(document: DocumentNode): string;
 declare function buildDocumentPreview(document: DocumentNode): DocumentPreview;
@@ -307,4 +308,4 @@ declare function replaceMathSpanFromEditor(document: DocumentNode, target: Docum
 declare function insertMathSpanFromEditor(document: DocumentNode, target: DocumentInlineTarget, insertAt: number, math: MathNode, source?: string): DocumentNode;
 declare function documentInlineText(inlines: DocumentInline[]): string;
 
-export { type DetectedMathSpan, type DocumentBlockJson, type DocumentBlockNode, type DocumentCommand, type DocumentInline, type DocumentInlineTarget, type DocumentJson, type DocumentListItemJson, type DocumentMathTarget, type DocumentNode, type DocumentParseMode, type DocumentPreview, type DocumentPreviewMathIsland, type ImageBlockNode, type ListBlockNode, type ListItemNode, type MathInline, type MathNode, type MathObjectJson, type NewDocumentBlockKind, type RawBlockNode, type TableBlockNode, type TextBlockNode, type TextInline, addDocumentBlock, addListItem, addNestedListBlock, addTableColumn, addTableRow, buildDocumentPreview, buildInlines, createDocumentBlock, createEmptyDocument, createImageBlock, createListBlock, createRawBlock, createTableBlock, createTextBlock, detectMathSpans, documentInlineText, fromDocumentJson, fromMathObjectJson, insertMathSpanFromEditor, isDisplayMathNode, isSupportedDocumentCommand, mathNodeFromEditorSession, mathSourceFromEditorSession, moveDocumentBlock, removeDocumentBlock, removeListItem, removeTableColumn, removeTableRow, renderDocumentLatex, renderMathNodeLatex, replaceMathSpanFromEditor, replaceMathSpanSource, updateImageBlock, updateListItemValue, updateRawBlockValue, updateTableCell, updateTableColumns, updateTextBlockValue };
+export { type DetectedMathSpan, type DocumentBlockJson, type DocumentBlockNode, type DocumentCommand, type DocumentInline, type DocumentInlineTarget, type DocumentJson, type DocumentListItemJson, type DocumentMathTarget, type DocumentNode, type DocumentParseMode, type DocumentPreview, type DocumentPreviewMathIsland, type ImageBlockNode, type ListBlockNode, type ListItemNode, type MathInline, type MathNode, type MathObjectJson, type NewDocumentBlockKind, type RawBlockNode, type TableBlockNode, type TextBlockNode, type TextInline, addDocumentBlock, addListItem, addNestedListBlock, addTableColumn, addTableRow, buildDocumentPreview, buildInlines, createDocumentBlock, createEmptyDocument, createImageBlock, createListBlock, createRawBlock, createTableBlock, createTextBlock, detectMathSpans, documentInlineText, fromDocumentJson, fromMathObjectJson, insertMathSpanFromEditor, isDisplayMathNode, isSupportedDocumentCommand, mathNodeFromEditorSession, mathSourceFromEditorSession, moveDocumentBlock, removeDocumentBlock, removeListItem, removeTableColumn, removeTableRow, renderDocumentLatex, renderMathNodeLatex, replaceMathSpanFromEditor, replaceMathSpanSource, toMathObjectJson, updateImageBlock, updateListItemValue, updateRawBlockValue, updateTableCell, updateTableColumns, updateTextBlockValue };

package/dist/document.js

@@ -52,6 +52,7 @@ __export(document_exports, {
   renderMathNodeLatex: () => renderMathNodeLatex,
   replaceMathSpanFromEditor: () => replaceMathSpanFromEditor,
   replaceMathSpanSource: () => replaceMathSpanSource,
+  toMathObjectJson: () => toMathObjectJson,
   updateImageBlock: () => updateImageBlock,
   updateListItemValue: () => updateListItemValue,
   updateRawBlockValue: () => updateRawBlockValue,
@@ -409,6 +410,66 @@ function fromMathObjectJson(json, mode = "english") {
     closing: json.closing
   };
 }
+function scriptsToJson(node, path) {
+  return {
+    ...node.superscript ? { superscript: chainToJson(node.superscript, `${path}.superscript`) } : {},
+    ...node.subscript ? { subscript: chainToJson(node.subscript, `${path}.subscript`) } : {}
+  };
+}
+function nodeToJson(node, path) {
+  const scripts = scriptsToJson(node, path);
+  if (node instanceof CharNode || node instanceof NumberNode || node instanceof OperatorNode) {
+    return { node_type: node.nodeType, expr: node.expr, ...scripts };
+  }
+  if (node instanceof DelimiterNode) {
+    return {
+      node_type: "DelimiterObject",
+      left_delim_expr: node.leftDelimExpr,
+      inner_expr: chainToJson(node.innerExpr, `${path}.inner_expr`),
+      right_delim_expr: node.rightDelimExpr,
+      ...scripts
+    };
+  }
+  if (node instanceof CommandNode) {
+    return {
+      node_type: "CommandObject",
+      name: node.name,
+      optional_args: node.optionalArgs.map((arg, index) => chainToJson(arg, `${path}.optional_args[${String(index)}]`)),
+      mandatory_args: node.mandatoryArgs.map((arg, index) => chainToJson(arg, `${path}.mandatory_args[${String(index)}]`)),
+      ...scripts
+    };
+  }
+  if (node instanceof EnvNode) {
+    return {
+      node_type: "EnvObject",
+      opening: node.opening,
+      lines: node.lines.map((line, index) => chainToJson(line, `${path}.lines[${String(index)}]`)),
+      closing: node.closing,
+      ...scripts
+    };
+  }
+  throw new Error(`Unsupported runtime math node at ${path}: ${node.nodeType}`);
+}
+function chainToJson(chain, path) {
+  if (!(chain instanceof ChainNode)) {
+    throw new Error(`Expected live ChainNode at ${path}`);
+  }
+  return {
+    node_type: "ChainClass",
+    chain: chain.chain.map((node, index) => nodeToJson(node, `${path}.chain[${String(index)}]`))
+  };
+}
+function toMathObjectJson(math) {
+  if (math.nodeType !== "MathObject" || !Array.isArray(math.lines) || math.lines.length === 0) {
+    throw new Error("Cannot serialize invalid runtime MathObject");
+  }
+  return {
+    node_type: "MathObject",
+    math_mode: math.mathMode,
+    lines: math.lines.map((line, index) => chainToJson(line, `$.lines[${String(index)}]`)),
+    closing: math.closing
+  };
+}
 function renderMathNodeLatex(math) {
   const lines = math.lines.map((line) => line.arabicLatex());
   if (math.mathMode === "$" || math.mathMode === "\\(") {
@@ -3319,6 +3380,7 @@ function documentInlineText(inlines) {
   renderMathNodeLatex,
   replaceMathSpanFromEditor,
   replaceMathSpanSource,
+  toMathObjectJson,
   updateImageBlock,
   updateListItemValue,
   updateRawBlockValue,