@drghaliasri/butex 5.5.2 → 5.5.3

package/dist/react-document2.d.mts

@@ -143,7 +143,20 @@ type MathObject2Json = {
     math_mode: string;
     lines: ChainJson[];
     closing: string;
+    /** Side used by the delimited source stored in the containing value/cell. */
+    source_side?: Document2ParseMode;
+    /** Preserve whether LaTeX export should prefer imported AST rendering or editor source. */
+    source_owner?: 'imported-structured' | 'editor';
+    label_enabled?: boolean;
+    label?: string;
+};
+/** Positional metadata for a raw-only span that has no structured equation AST. */
+type RawMathObject2Json = {
+    node_type: 'RawMathObject';
+    label_enabled?: boolean;
+    label?: string;
 };
+type Document2MathObjectJson = MathObject2Json | RawMathObject2Json;
 type ReferenceFieldSeparator = ',' | '،';
 type Reference2Json = {
     key: string;
@@ -179,7 +192,7 @@ type Document2BlockJson = {
     formats?: TextFormatSpan2Json[];
     /** Stable host asset identity (e.g. S3 key / UUID); optional for \\includegraphics. */
     asset_id?: string;
-    math_objects?: MathObject2Json[];
+    math_objects?: Array<Document2MathObjectJson | null>;
     options?: Record<string, string>;
     closing?: string;
     items?: Document2ListItemJson[];
@@ -195,7 +208,7 @@ type Document2BlockJson = {
 type Document2ListItemJson = {
     value: string;
     formats?: TextFormatSpan2Json[];
-    math_objects?: MathObject2Json[];
+    math_objects?: Array<Document2MathObjectJson | null>;
     blocks?: Document2BlockJson[];
 };
 type Document2Diagnostic = {
@@ -463,6 +476,8 @@ type ButexDocumentEditor2Props = {
         value: string;
     }) => string;
     onDocumentChange?: (document: Document2Node) => void;
+    /** Canonical JSON wire format for API/database persistence. */
+    onDocumentJsonChange?: (document: Document2Json) => void;
     onLatexChange?: (latex: string) => void;
 };
 type Document2InitialState = {
@@ -470,7 +485,7 @@ type Document2InitialState = {
     error: string | null;
 };
 declare function resolveInitialDocument2(initialDocument: Document2Json | Document2Node | undefined, uiLocale?: ButexUiLocale, documentMeta?: Document2MetaProp): Document2InitialState;
-declare function ButexDocumentEditor2({ initialDocument, documentMeta, className, debug, documentDirection, equationSide, editableEquations, previewOnly, uiLocale, mathOutput, digitForm: digitFormProp, onDigitFormChange, resolveImageUrl, onDocumentChange, onLatexChange, }: ButexDocumentEditor2Props): react_jsx_runtime.JSX.Element;
+declare function ButexDocumentEditor2({ initialDocument, documentMeta, className, debug, documentDirection, equationSide, editableEquations, previewOnly, uiLocale, mathOutput, digitForm: digitFormProp, onDigitFormChange, resolveImageUrl, onDocumentChange, onDocumentJsonChange, onLatexChange, }: ButexDocumentEditor2Props): react_jsx_runtime.JSX.Element;
 
 type DocumentInsertToolbarProps = {
     canUndo: boolean;

package/dist/react-document2.d.ts

@@ -143,7 +143,20 @@ type MathObject2Json = {
     math_mode: string;
     lines: ChainJson[];
     closing: string;
+    /** Side used by the delimited source stored in the containing value/cell. */
+    source_side?: Document2ParseMode;
+    /** Preserve whether LaTeX export should prefer imported AST rendering or editor source. */
+    source_owner?: 'imported-structured' | 'editor';
+    label_enabled?: boolean;
+    label?: string;
+};
+/** Positional metadata for a raw-only span that has no structured equation AST. */
+type RawMathObject2Json = {
+    node_type: 'RawMathObject';
+    label_enabled?: boolean;
+    label?: string;
 };
+type Document2MathObjectJson = MathObject2Json | RawMathObject2Json;
 type ReferenceFieldSeparator = ',' | '،';
 type Reference2Json = {
     key: string;
@@ -179,7 +192,7 @@ type Document2BlockJson = {
     formats?: TextFormatSpan2Json[];
     /** Stable host asset identity (e.g. S3 key / UUID); optional for \\includegraphics. */
     asset_id?: string;
-    math_objects?: MathObject2Json[];
+    math_objects?: Array<Document2MathObjectJson | null>;
     options?: Record<string, string>;
     closing?: string;
     items?: Document2ListItemJson[];
@@ -195,7 +208,7 @@ type Document2BlockJson = {
 type Document2ListItemJson = {
     value: string;
     formats?: TextFormatSpan2Json[];
-    math_objects?: MathObject2Json[];
+    math_objects?: Array<Document2MathObjectJson | null>;
     blocks?: Document2BlockJson[];
 };
 type Document2Diagnostic = {
@@ -463,6 +476,8 @@ type ButexDocumentEditor2Props = {
         value: string;
     }) => string;
     onDocumentChange?: (document: Document2Node) => void;
+    /** Canonical JSON wire format for API/database persistence. */
+    onDocumentJsonChange?: (document: Document2Json) => void;
     onLatexChange?: (latex: string) => void;
 };
 type Document2InitialState = {
@@ -470,7 +485,7 @@ type Document2InitialState = {
     error: string | null;
 };
 declare function resolveInitialDocument2(initialDocument: Document2Json | Document2Node | undefined, uiLocale?: ButexUiLocale, documentMeta?: Document2MetaProp): Document2InitialState;
-declare function ButexDocumentEditor2({ initialDocument, documentMeta, className, debug, documentDirection, equationSide, editableEquations, previewOnly, uiLocale, mathOutput, digitForm: digitFormProp, onDigitFormChange, resolveImageUrl, onDocumentChange, onLatexChange, }: ButexDocumentEditor2Props): react_jsx_runtime.JSX.Element;
+declare function ButexDocumentEditor2({ initialDocument, documentMeta, className, debug, documentDirection, equationSide, editableEquations, previewOnly, uiLocale, mathOutput, digitForm: digitFormProp, onDigitFormChange, resolveImageUrl, onDocumentChange, onDocumentJsonChange, onLatexChange, }: ButexDocumentEditor2Props): react_jsx_runtime.JSX.Element;
 
 type DocumentInsertToolbarProps = {
     canUndo: boolean;

package/dist/react-document2.js

@@ -739,6 +739,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 === "\\(") {
@@ -1203,10 +1263,11 @@ function createInlineField2(value = "", mathObjects = [], options = {}, path = "
     }
     const mathJson = mathObjects[mathObjectIndex];
     mathObjectIndex += 1;
-    if (mathJson && (mathJson.math_mode !== span.opening || mathJson.closing !== span.closing)) {
+    const structuredMathJson = mathJson?.node_type === "MathObject" ? mathJson : null;
+    if (structuredMathJson && (structuredMathJson.math_mode !== span.opening || structuredMathJson.closing !== span.closing)) {
       pushDiagnostic(diagnostics, options, path, "math_objects order mismatch");
     }
-    if (mathJson && mathJson.math_mode === span.opening && mathJson.closing === span.closing) {
+    if (structuredMathJson && structuredMathJson.math_mode === span.opening && structuredMathJson.closing === span.closing) {
       tokens.push({
         id: document2Id("math"),
         kind: "math",
@@ -1214,10 +1275,12 @@ function createInlineField2(value = "", mathObjects = [], options = {}, path = "
         opening: span.opening,
         closing: span.closing,
         source: span.source,
-        sourceSide: mode,
-        math: fromMathObjectJson(mathJson, mode),
+        sourceSide: structuredMathJson.source_side === "arabic" || structuredMathJson.source_side === "english" ? structuredMathJson.source_side : mode,
+        math: fromMathObjectJson(structuredMathJson, mode),
         editable: true,
-        sourceOwner: "imported-structured"
+        sourceOwner: structuredMathJson.source_owner === "editor" ? "editor" : "imported-structured",
+        ...typeof structuredMathJson.label_enabled === "boolean" ? { labelEnabled: structuredMathJson.label_enabled } : {},
+        ...typeof structuredMathJson.label === "string" ? { label: structuredMathJson.label } : {}
       });
     } else {
       tokens.push({
@@ -1230,7 +1293,9 @@ function createInlineField2(value = "", mathObjects = [], options = {}, path = "
         math: null,
         editable: false,
         reason: "\u0647\u0630\u0647 \u0627\u0644\u0645\u0639\u0627\u062F\u0644\u0629 \u0645\u062D\u0641\u0648\u0638\u0629 \u0643\u0646\u0635 \u062E\u0627\u0645 \u0641\u0642\u0637 \u062D\u0627\u0644\u064A\u0627",
-        sourceOwner: "raw"
+        sourceOwner: "raw",
+        ...mathJson?.node_type === "RawMathObject" && typeof mathJson.label_enabled === "boolean" ? { labelEnabled: mathJson.label_enabled } : {},
+        ...mathJson?.node_type === "RawMathObject" && typeof mathJson.label === "string" ? { label: mathJson.label } : {}
       });
     }
     index = span.end;
@@ -9288,6 +9353,155 @@ ${body}
 `;
 }
 
+// src/document2/exportJson.ts
+function serializeField(field) {
+  let value = "";
+  let hasPersistedMath = false;
+  const formats = [];
+  const mathObjects = [];
+  for (const token of field.tokens) {
+    if (token.kind === "text") {
+      const start = value.length;
+      value += token.text;
+      if (token.text.length > 0 && (token.style?.bold || token.style?.italic || token.style?.underline)) {
+        formats.push({
+          start,
+          end: value.length,
+          ...token.style.bold ? { bold: true } : {},
+          ...token.style.italic ? { italic: true } : {},
+          ...token.style.underline ? { underline: true } : {}
+        });
+      }
+      continue;
+    }
+    if (token.kind === "cite") {
+      value += citeTokenLatex(token.keys);
+      continue;
+    }
+    if (token.kind === "ref") {
+      value += refTokenLatex(token.keys, token.refCommand);
+      continue;
+    }
+    value += token.source;
+    if (!token.math || token.sourceOwner === "raw") {
+      if (token.labelEnabled !== void 0 || token.label !== void 0) {
+        hasPersistedMath = true;
+        mathObjects.push({
+          node_type: "RawMathObject",
+          ...token.labelEnabled !== void 0 ? { label_enabled: token.labelEnabled } : {},
+          ...token.label !== void 0 ? { label: token.label } : {}
+        });
+      } else {
+        mathObjects.push(null);
+      }
+      continue;
+    }
+    hasPersistedMath = true;
+    mathObjects.push({
+      ...toMathObjectJson(token.math),
+      ...token.sourceSide ? { source_side: token.sourceSide } : {},
+      source_owner: token.sourceOwner,
+      ...token.labelEnabled !== void 0 ? { label_enabled: token.labelEnabled } : {},
+      ...token.label !== void 0 ? { label: token.label } : {}
+    });
+  }
+  return { value, formats, mathObjects, hasPersistedMath };
+}
+function fieldJson(field) {
+  const serialized = serializeField(field);
+  return {
+    value: serialized.value,
+    ...serialized.formats.length > 0 ? { formats: serialized.formats } : {},
+    ...serialized.hasPersistedMath ? { math_objects: serialized.mathObjects } : {}
+  };
+}
+function listItemJson(item) {
+  const field = fieldJson(item.field);
+  return {
+    value: field.value ?? "",
+    ...field.formats ? { formats: field.formats } : {},
+    ...field.math_objects ? { math_objects: field.math_objects } : {},
+    ...item.blocks.length > 0 ? { blocks: item.blocks.map(blockJson) } : {}
+  };
+}
+function blockJson(block) {
+  if (block.kind === "textBlock") {
+    return {
+      command: block.command,
+      ...fieldJson(block.field),
+      ...block.command === "\\paragraph" ? { centered: block.centered === true } : {}
+    };
+  }
+  if (block.kind === "list") {
+    return {
+      command: block.command,
+      closing: block.closing,
+      items: block.items.map(listItemJson)
+    };
+  }
+  if (block.kind === "table") {
+    const fields = block.rows.map((row) => row.map(serializeField));
+    const hasPersistedMath = fields.some((row) => row.some((field) => field.hasPersistedMath));
+    return {
+      command: block.command,
+      closing: block.closing,
+      columns: block.columns,
+      rows: fields.map((row) => row.map((field) => field.value)),
+      ...fields.some((row) => row.some((field) => field.formats.length > 0)) ? { cell_formats: fields.map((row) => row.map((field) => field.formats)) } : {},
+      ...hasPersistedMath ? { math_objects: fields.flatMap((row) => row.flatMap((field) => field.mathObjects)) } : {},
+      centered: block.centered,
+      caption_enabled: block.captionEnabled,
+      caption: block.caption,
+      label_enabled: block.labelEnabled,
+      label: block.label
+    };
+  }
+  if (block.kind === "image") {
+    return {
+      command: block.command,
+      value: block.value,
+      ...block.assetId !== void 0 ? { asset_id: block.assetId } : {},
+      options: { ...block.options },
+      centered: block.centered,
+      caption_enabled: block.captionEnabled,
+      caption: block.caption,
+      label_enabled: block.labelEnabled,
+      label: block.label
+    };
+  }
+  if (block.kind === "bibliography") {
+    return { command: block.command, closing: block.closing };
+  }
+  return { command: block.command, value: block.value };
+}
+function referenceJson(reference) {
+  return {
+    key: reference.key,
+    authors: reference.authors,
+    title: reference.title,
+    year: reference.year,
+    url: reference.url,
+    venue: reference.venue,
+    field_separator: reference.fieldSeparator
+  };
+}
+function toDocumentJson2(document2) {
+  if (document2.nodeType !== "DocumentObject" || !Array.isArray(document2.blocks)) {
+    throw new Error("toDocumentJson2 requires a live Document2Node");
+  }
+  return {
+    node_type: "DocumentObject",
+    meta: {
+      title: document2.meta.title,
+      authors: document2.meta.authors,
+      date: { ...document2.meta.date },
+      abstract: document2.meta.abstract
+    },
+    references: document2.references.map(referenceJson),
+    blocks: document2.blocks.map(blockJson)
+  };
+}
+
 // src/document2/history.ts
 var DEFAULT_DOCUMENT2_HISTORY_MAX_DEPTH = 100;
 function createDocument2History(maxDepth = DEFAULT_DOCUMENT2_HISTORY_MAX_DEPTH) {
@@ -9631,6 +9845,7 @@ var DOCUMENT2_MESSAGES = {
     imagePath: "\u0645\u0633\u0627\u0631 \u0645\u0644\u0641 \u0627\u0644\u0635\u0648\u0631\u0629",
     imagePathLabel: "\u0645\u0633\u0627\u0631 \u0627\u0644\u0635\u0648\u0631\u0629",
     loadDocumentError: "\u062A\u0639\u0630\u0631 \u062A\u062D\u0645\u064A\u0644 \u0627\u0644\u0645\u0633\u062A\u0646\u062F",
+    runtimePersistenceError: "\u0644\u0627 \u064A\u0645\u0643\u0646 \u062A\u062D\u0645\u064A\u0644 Document2Node \u0628\u0639\u062F JSON.stringify. \u0627\u062D\u0641\u0638 Document2Json \u0628\u0627\u0633\u062A\u062E\u062F\u0627\u0645 toDocumentJson2.",
     emptyImagePath: "\u0644\u0627 \u064A\u0648\u062C\u062F \u0645\u0633\u0627\u0631 \u0635\u0648\u0631\u0629",
     blockSelection: "\u062A\u062D\u062F\u064A\u062F \u0627\u0644\u0643\u062A\u0644",
     selectBlock: "\u062A\u062D\u062F\u064A\u062F \u0627\u0644\u0643\u062A\u0644\u0629",
@@ -9774,6 +9989,7 @@ var DOCUMENT2_MESSAGES = {
     imagePath: "File path (\\includegraphics)",
     imagePathLabel: "Image path",
     loadDocumentError: "Could not load document",
+    runtimePersistenceError: "A Document2Node cannot be loaded after JSON.stringify. Persist Document2Json with toDocumentJson2 instead.",
     emptyImagePath: "Empty image path",
     blockSelection: "Block selection",
     selectBlock: "Select block",
@@ -17038,7 +17254,19 @@ function formatDocument2Diagnostic(d, messages) {
   return `${messages.importWarning}: ${d.message} \u2014 ${messages.path}: ${d.path}`;
 }
 function isDocument2Node(value) {
-  return typeof value === "object" && value !== null && value.nodeType === "DocumentObject" && Array.isArray(value.blocks) && Array.isArray(value.diagnostics);
+  const hasRuntimeShape = typeof value === "object" && value !== null && value.nodeType === "DocumentObject" && Array.isArray(value.blocks) && Array.isArray(value.diagnostics);
+  if (!hasRuntimeShape) {
+    return false;
+  }
+  try {
+    toDocumentJson2(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function hasDocument2RuntimeShape(value) {
+  return typeof value === "object" && value !== null && value.nodeType === "DocumentObject";
 }
 function applyDocumentMetaSeed(document2, documentMeta) {
   const current = document2.meta ?? emptyDocument2Meta();
@@ -17057,6 +17285,13 @@ function resolveInitialDocument2(initialDocument, uiLocale = "ar", documentMeta)
   if (isDocument2Node(initialDocument)) {
     return { document: applyDocumentMetaSeed(initialDocument, documentMeta), error: null };
   }
+  if (hasDocument2RuntimeShape(initialDocument)) {
+    const messages = document2Messages(uiLocale);
+    return {
+      document: applyDocumentMetaSeed(createEmptyDocument2(), documentMeta),
+      error: `${messages.loadDocumentError}: ${messages.runtimePersistenceError}`
+    };
+  }
   try {
     const imported = fromDocumentJson2(initialDocument);
     return {
@@ -17089,6 +17324,7 @@ function ButexDocumentEditor2({
   onDigitFormChange,
   resolveImageUrl,
   onDocumentChange,
+  onDocumentJsonChange,
   onLatexChange
 }) {
   const messages = document2Messages(uiLocale);
@@ -17120,6 +17356,7 @@ function ButexDocumentEditor2({
   const pendingFocusRef = (0, import_react13.useRef)(null);
   documentRef.current = documentNode;
   const latex = document2Latex(documentNode);
+  const documentJson = (0, import_react13.useMemo)(() => toDocumentJson2(documentNode), [documentNode]);
   const documentLabels = (0, import_react13.useMemo)(() => collectDocument2Labels(documentNode), [documentNode]);
   const preview = (0, import_react13.useMemo)(
     () => document2Preview(documentNode, mathOutput, equationSide, {
@@ -17204,6 +17441,9 @@ function ButexDocumentEditor2({
   (0, import_react13.useEffect)(() => {
     onDocumentChange?.(documentNode);
   }, [documentNode, onDocumentChange]);
+  (0, import_react13.useEffect)(() => {
+    onDocumentJsonChange?.(documentJson);
+  }, [documentJson, onDocumentJsonChange]);
   (0, import_react13.useEffect)(() => {
     onLatexChange?.(latex);
   }, [latex, onLatexChange]);