@drghaliasri/butex 4.4.0 → 5.0.0

package/README.md

@@ -253,6 +253,8 @@ const latex = document2Latex(documentNode);
 const preview = document2Preview(documentNode, 'svg');
 ```
 
+`document2Latex(doc)` emits a **complete Arabic XeLaTeX document** by default (preamble + `\begin{document}` + body + `\end{document}`). Pass `{ wrapDocument: false }` for body-only blocks. Optional `digitsMapping: 'arabicdigits' | 'digits'` controls eastern vs western digit font mapping in the preamble (default `'arabicdigits'`). See [`examples/example-latex-export.tex`](examples/example-latex-export.tex) for a full sample (regenerated by the wrap vitest). Hosts can also call `getArabicXeLatexPreamble()` alone.
+
 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`)
@@ -332,7 +334,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. 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"`.
+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 a root `references` catalog (`key`, `authors`, `title`, `year`, `url`, `venue`) and `\cite{key1,key2}` spans in text values; 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/document2.d.mts

@@ -46,6 +46,82 @@ declare class ChainNode {
     toArabicLatex(): string;
 }
 
+type EditorSide = 'english' | 'arabic';
+type EditorNodeKind = 'char' | 'number' | 'operator' | 'delimiter' | 'frac' | 'sqrt' | 'env' | 'atomicCommand' | 'atomicOperatorCommand';
+type MatrixEnvStyle = 'matrix' | 'pmatrix' | 'bmatrix' | 'Bmatrix' | 'vmatrix' | 'Vmatrix';
+type GridEnvName = MatrixEnvStyle | 'array' | 'aligned';
+type EnvColumnAlignment = 'l' | 'c' | 'r';
+type CharacterFontId = 'default' | 'takween' | 'diwani' | 'diwaniOutline';
+type DigitFormId = 'western' | 'arabicIndic' | 'persianIndic';
+type EditorSyncState = 'synced' | 'diverged';
+type EditorChain = {
+    id: string;
+    nodes: EditorNode[];
+};
+type EditorNode = {
+    id: string;
+    kind: EditorNodeKind;
+    expr: string;
+    characterFont?: CharacterFontId;
+    superscript: EditorChain | null;
+    subscript: EditorChain | null;
+    leftDelimExpr: string;
+    rightDelimExpr: string;
+    innerExpr: EditorChain | null;
+    numerator: EditorChain | null;
+    denominator: EditorChain | null;
+    radicand: EditorChain | null;
+    rootIndex: EditorChain | null;
+    envName: GridEnvName | null;
+    matrixStyle: MatrixEnvStyle | null;
+    matrixRows: EditorChain[][] | null;
+    columnAlignments: EnvColumnAlignment[] | null;
+};
+type EditorCaret = {
+    chainId: string;
+    index: number;
+};
+type EditorSelectionRange = {
+    chainId: string;
+    anchorIndex: number;
+    focusIndex: number;
+};
+type EditorSyncMap = Record<string, {
+    expr: EditorSyncState;
+}>;
+type EditorDebugEntry = {
+    timestamp: string;
+    command: string;
+    activeSide: EditorSide;
+    englishLatex: string;
+    arabicLatex: string;
+    renderOk: boolean;
+    renderError: string | null;
+    note: string;
+};
+type EditorSession = {
+    englishTree: EditorChain;
+    arabicTree: EditorChain;
+    activeSide: EditorSide;
+    /** When true, each typed letter/digit inserts a new char/number leaf; when false, merge into adjacent same-kind leaves. */
+    splitLeafTyping: boolean;
+    /** One-shot: when true, the next insertChar/insertNumber bypasses leaf-merge (used by Space in merge mode). */
+    forceSplitNextLeaf: boolean;
+    /** When true and active side is Arabic, merged number typing prepends digits (RTL-style); still mirrored on EN/AR. */
+    arabicReverseNumberTyping: boolean;
+    /** Font applied to newly typed char nodes. */
+    currentCharacterFont: CharacterFontId;
+    /** Digit glyph form used for editor display and LaTeX preview output. */
+    currentDigitForm: DigitFormId;
+    caret: EditorCaret;
+    /** Whole-node range selection inside a single chain (anchor==focus means no selection). */
+    selection: EditorSelectionRange | null;
+    selectedNodeId: string | null;
+    selectedStructureNodeId: string | null;
+    sync: EditorSyncMap;
+    debugLog: EditorDebugEntry[];
+};
+
 type MathNode = {
     nodeType: 'MathObject';
     mathMode: string;
@@ -55,19 +131,31 @@ type MathNode = {
 
 type Document2ParseMode = 'english' | 'arabic';
 type Document2MathOutput = 'svg' | 'chtml';
+type Document2Direction = 'rtl' | 'ltr';
 type MathObject2Json = {
     node_type: 'MathObject';
     math_mode: string;
     lines: ChainJson[];
     closing: string;
 };
+type Reference2Json = {
+    key: string;
+    authors?: string;
+    title?: string;
+    year?: string;
+    url?: string;
+    venue?: string;
+};
 type Document2Json = {
     node_type: 'DocumentObject';
+    references?: Reference2Json[];
     blocks: Document2BlockJson[];
 };
 type Document2BlockJson = {
     command: string;
     value?: string;
+    /** Stable host asset identity (e.g. S3 key / UUID); optional for \\includegraphics. */
+    asset_id?: string;
     math_objects?: MathObject2Json[];
     options?: Record<string, string>;
     closing?: string;
@@ -85,6 +173,15 @@ type Document2Diagnostic = {
     message: string;
     path: string;
 };
+type Reference2 = {
+    id: string;
+    key: string;
+    authors: string;
+    title: string;
+    year: string;
+    url: string;
+    venue: string;
+};
 type TextToken2 = {
     id: string;
     kind: 'text';
@@ -103,7 +200,12 @@ type MathToken2 = {
     reason?: string;
     sourceOwner: 'imported-structured' | 'raw' | 'editor';
 };
-type InlineToken2 = TextToken2 | MathToken2;
+type CiteToken2 = {
+    id: string;
+    kind: 'cite';
+    keys: string[];
+};
+type InlineToken2 = TextToken2 | MathToken2 | CiteToken2;
 type InlineField2 = {
     id: string;
     tokens: InlineToken2[];
@@ -139,17 +241,26 @@ type ImageBlock2 = {
     kind: 'image';
     command: '\\includegraphics';
     value: string;
+    /** Host asset identity from wire `asset_id`; preserved across value edits. */
+    assetId?: string;
     options: Record<string, string>;
 };
+type BibliographyBlock2 = {
+    id: string;
+    kind: 'bibliography';
+    command: '\\begin{thebibliography}';
+    closing: '\\end{thebibliography}';
+};
 type RawBlock2 = {
     id: string;
     kind: 'raw';
     command: '\\raw';
     value: string;
 };
-type Document2Block = TextBlock2 | ListBlock2 | TableBlock2 | ImageBlock2 | RawBlock2;
+type Document2Block = TextBlock2 | ListBlock2 | TableBlock2 | ImageBlock2 | BibliographyBlock2 | RawBlock2;
 type Document2Node = {
     nodeType: 'DocumentObject';
+    references: Reference2[];
     blocks: Document2Block[];
     diagnostics: Document2Diagnostic[];
 };
@@ -165,6 +276,16 @@ type DetectedMathSpan2 = {
     closing: string;
     display: boolean;
 };
+type DetectedCiteSpan2 = {
+    kind: 'cite';
+    start: number;
+    end: number;
+    source: string;
+    keys: string[];
+};
+type DetectedInlineSpan2 = ({
+    kind: 'math';
+} & DetectedMathSpan2) | DetectedCiteSpan2;
 type PreviewInline2 = {
     kind: 'text';
     text: string;
@@ -175,6 +296,11 @@ type PreviewInline2 = {
     display: boolean;
     output: Document2MathOutput;
     editable: boolean;
+} | {
+    kind: 'cite';
+    id: string;
+    keys: string[];
+    label: string;
 };
 type PreviewBlock2 = {
     kind: 'heading';
@@ -202,7 +328,21 @@ type PreviewBlock2 = {
     kind: 'image';
     id: string;
     src: string;
+    assetId?: string;
     options: Record<string, string>;
+} | {
+    kind: 'bibliography';
+    id: string;
+    items: Array<{
+        id: string;
+        numberLabel: string;
+        key: string;
+        authors: string;
+        title: string;
+        year: string;
+        url: string;
+        venue: string;
+    }>;
 }
 /** Preview-only: raw / unknown blocks are omitted from preview until we add proper rendering. */
  | {
@@ -220,81 +360,9 @@ type Document2Preview = {
     blocks: PreviewBlock2[];
     mathIslands: MathIsland2[];
 };
-
-type EditorSide = 'english' | 'arabic';
-type EditorNodeKind = 'char' | 'number' | 'operator' | 'delimiter' | 'frac' | 'sqrt' | 'env' | 'atomicCommand' | 'atomicOperatorCommand';
-type MatrixEnvStyle = 'matrix' | 'pmatrix' | 'bmatrix' | 'Bmatrix' | 'vmatrix' | 'Vmatrix';
-type GridEnvName = MatrixEnvStyle | 'array' | 'aligned';
-type EnvColumnAlignment = 'l' | 'c' | 'r';
-type CharacterFontId = 'default' | 'takween' | 'diwani' | 'diwaniOutline';
-type DigitFormId = 'western' | 'arabicIndic' | 'persianIndic';
-type EditorSyncState = 'synced' | 'diverged';
-type EditorChain = {
-    id: string;
-    nodes: EditorNode[];
-};
-type EditorNode = {
-    id: string;
-    kind: EditorNodeKind;
-    expr: string;
-    characterFont?: CharacterFontId;
-    superscript: EditorChain | null;
-    subscript: EditorChain | null;
-    leftDelimExpr: string;
-    rightDelimExpr: string;
-    innerExpr: EditorChain | null;
-    numerator: EditorChain | null;
-    denominator: EditorChain | null;
-    radicand: EditorChain | null;
-    rootIndex: EditorChain | null;
-    envName: GridEnvName | null;
-    matrixStyle: MatrixEnvStyle | null;
-    matrixRows: EditorChain[][] | null;
-    columnAlignments: EnvColumnAlignment[] | null;
-};
-type EditorCaret = {
-    chainId: string;
-    index: number;
-};
-type EditorSelectionRange = {
-    chainId: string;
-    anchorIndex: number;
-    focusIndex: number;
-};
-type EditorSyncMap = Record<string, {
-    expr: EditorSyncState;
-}>;
-type EditorDebugEntry = {
-    timestamp: string;
-    command: string;
-    activeSide: EditorSide;
-    englishLatex: string;
-    arabicLatex: string;
-    renderOk: boolean;
-    renderError: string | null;
-    note: string;
-};
-type EditorSession = {
-    englishTree: EditorChain;
-    arabicTree: EditorChain;
-    activeSide: EditorSide;
-    /** When true, each typed letter/digit inserts a new char/number leaf; when false, merge into adjacent same-kind leaves. */
-    splitLeafTyping: boolean;
-    /** One-shot: when true, the next insertChar/insertNumber bypasses leaf-merge (used by Space in merge mode). */
-    forceSplitNextLeaf: boolean;
-    /** When true and active side is Arabic, merged number typing prepends digits (RTL-style); still mirrored on EN/AR. */
-    arabicReverseNumberTyping: boolean;
-    /** Font applied to newly typed char nodes. */
-    currentCharacterFont: CharacterFontId;
-    /** Digit glyph form used for editor display and LaTeX preview output. */
-    currentDigitForm: DigitFormId;
-    caret: EditorCaret;
-    /** Whole-node range selection inside a single chain (anchor==focus means no selection). */
-    selection: EditorSelectionRange | null;
-    selectedNodeId: string | null;
-    selectedStructureNodeId: string | null;
-    sync: EditorSyncMap;
-    debugLog: EditorDebugEntry[];
+type FormatCiteLabelOptions = {
+    documentDirection?: Document2Direction;
+    digitForm?: DigitFormId;
 };
 
 declare function findFirstInlineField(document: Document2Node): InlineField2 | null;
@@ -314,9 +382,45 @@ declare function addDocument2ImageBlock(document: Document2Node, src?: string, a
 declare function updateDocument2ImageValue(document: Document2Node, blockId: string, value: string): Document2Node;
 declare function addDocument2ListItem(document: Document2Node, listBlockId: string): Document2Node;
 declare function removeDocument2ListItem(document: Document2Node, listBlockId: string, itemId: string): Document2Node;
+declare function insertCiteTokenAtCaret(document: Document2Node, fieldId: string, textTokenId: string | null, caretOffset: number, keys: string[]): Document2Node;
+declare function updateCiteTokenKeys(document: Document2Node, tokenId: string, keys: string[]): Document2Node;
+declare function removeCiteTokenById(document: Document2Node, tokenId: string): Document2Node;
+declare function ensureDocument2BibliographyBlock(document: Document2Node, afterBlockId?: string | null): Document2Node;
+declare function addDocument2Reference(document: Document2Node, partial?: Partial<Reference2Json>): Document2Node;
+declare function updateDocument2Reference(document: Document2Node, referenceId: string, patch: Partial<Reference2Json>): Document2Node;
+declare function removeDocument2Reference(document: Document2Node, referenceId: string): Document2Node;
+declare function moveDocument2Reference(document: Document2Node, referenceId: string, direction: -1 | 1): Document2Node;
+declare function setDocument2References(document: Document2Node, references: Reference2[]): Document2Node;
+
+declare function referenceNumberMap(references: Array<Pick<Reference2, 'key'>>): Map<string, number>;
+declare function resolveCiteNumbers(keys: string[], references: Array<Pick<Reference2, 'key'>>): Array<number | null>;
+declare function formatCiteLabel(keys: string[], references: Array<Pick<Reference2, 'key'>>, options?: FormatCiteLabelOptions): string;
+declare function formatBibliographyNumber(index: number, options?: FormatCiteLabelOptions): string;
+declare function parseCiteKeys(source: string): string[];
+declare function citeTokenLatex(keys: string[]): string;
+declare function referenceFromJson(json: Reference2Json): Reference2;
+declare function createEmptyReference2(partial?: Partial<Reference2Json>): Reference2;
+declare function bibliographyEntryLatex(reference: Reference2): string;
 
+/** Arabic XeLaTeX preamble fragments for full-document export. */
+type ArabicDigitsMapping = 'arabicdigits' | 'digits';
+declare function arabicXeLatexPreamblePkg(): string;
+declare function arabicXeLatexPreambleFont(digitsMapping?: ArabicDigitsMapping): string;
+declare function arabicXeLatexPreambleCmd(): string;
+declare function getArabicXeLatexPreamble(digitsMapping?: ArabicDigitsMapping): string;
+
+type Document2LatexOptions = {
+    /**
+     * When true (default), emit a complete Arabic XeLaTeX file:
+     * preamble + \\begin{document} + body + \\end{document}.
+     * Pass false for body-only blocks.
+     */
+    wrapDocument?: boolean;
+    /** Font digit Mapping when wrapping. Default 'arabicdigits'. */
+    digitsMapping?: ArabicDigitsMapping;
+};
 declare function inlineFieldLatex(field: InlineField2): string;
-declare function document2Latex(document: Document2Node): string;
+declare function document2Latex(document: Document2Node, options?: Document2LatexOptions): string;
 
 declare const DEFAULT_DOCUMENT2_HISTORY_MAX_DEPTH = 100;
 type Document2HistoryStacks = {
@@ -335,7 +439,10 @@ declare function createInlineField2(value?: string, mathObjects?: MathObject2Jso
 declare function fromDocumentJson2(json: unknown, options?: ImportDocument2Options): Document2Node;
 declare function createEmptyDocument2(): Document2Node;
 
+/** Math-only spans (used for math_objects alignment counts). */
 declare function detectMathSpans2(value: string): DetectedMathSpan2[];
+/** Left-to-right math + \\cite spans without overlap. */
+declare function detectInlineSpans2(value: string): DetectedInlineSpan2[];
 
 type Document2MathBridgeResult = {
     editable: true;
@@ -354,6 +461,10 @@ declare function mathNodeFromSession(session: EditorSession, opening?: string, c
 declare function mathNodeFromArabicSession(session: EditorSession, opening?: string, closing?: string): MathNode;
 declare function mathTokenSourceForSide(token: MathToken2, side: EditorSide): string;
 
-declare function document2Preview(document: Document2Node, output?: Document2MathOutput, equationSide?: EditorSide): Document2Preview;
+type Document2PreviewOptions = {
+    documentDirection?: Document2Direction;
+    digitForm?: DigitFormId;
+};
+declare function document2Preview(document: Document2Node, output?: Document2MathOutput, equationSide?: EditorSide, previewOptions?: Document2PreviewOptions): Document2Preview;
 
-export { DEFAULT_DOCUMENT2_HISTORY_MAX_DEPTH, type Document2Block, type Document2BlockJson, type Document2Diagnostic, type Document2HistoryStacks, type Document2Json, type Document2MathOutput, type Document2Node, type ImageBlock2, type ImportDocument2Options, type InlineField2, type InlineToken2, type ListBlock2, type MathIsland2, type MathObject2Json, type MathToken2, type PreviewBlock2, type PreviewInline2, type RawBlock2, type TableBlock2, type TextBlock2, type TextToken2, addDocument2ImageBlock, addDocument2ListBlock, addDocument2ListItem, addDocument2TableBlock, addDocument2TextBlock, cloneDocument2Node, createDocument2History, createEmptyArabicEquationSession, createEmptyDocument2, createEmptyEquationSession, createInlineField2, detectMathSpans2, document2HistoryCanRedo, document2HistoryCanUndo, document2Latex, document2Preview, findFirstInlineField, fromDocumentJson2, inlineFieldLatex, insertDocument2BlockAfter, insertMathToken, insertMathTokenAtCaret, mathNodeFromArabicSession, mathNodeFromSession, mathSourceFromArabicSession, mathSourceFromSession, mathTokenSourceForSide, mathTokenToArabicEditorSession, mathTokenToEditorSession, moveDocument2BlockById, pushDocument2Snapshot, removeDocument2BlockById, removeDocument2ListItem, removeMathTokenById, replaceMathTokenFromSession, restoreDocument2Redo, restoreDocument2Undo, updateDocument2ImageValue, updateTextToken };
+export { type ArabicDigitsMapping, type BibliographyBlock2, type CiteToken2, DEFAULT_DOCUMENT2_HISTORY_MAX_DEPTH, type Document2Block, type Document2BlockJson, type Document2Diagnostic, type Document2Direction, type Document2HistoryStacks, type Document2Json, type Document2LatexOptions, type Document2MathOutput, type Document2Node, type Document2PreviewOptions, type FormatCiteLabelOptions, type ImageBlock2, type ImportDocument2Options, type InlineField2, type InlineToken2, type ListBlock2, type MathIsland2, type MathObject2Json, type MathToken2, type PreviewBlock2, type PreviewInline2, type RawBlock2, type Reference2, type Reference2Json, type TableBlock2, type TextBlock2, type TextToken2, addDocument2ImageBlock, addDocument2ListBlock, addDocument2ListItem, addDocument2Reference, addDocument2TableBlock, addDocument2TextBlock, arabicXeLatexPreambleCmd, arabicXeLatexPreambleFont, arabicXeLatexPreamblePkg, bibliographyEntryLatex, citeTokenLatex, cloneDocument2Node, createDocument2History, createEmptyArabicEquationSession, createEmptyDocument2, createEmptyEquationSession, createEmptyReference2, createInlineField2, detectInlineSpans2, detectMathSpans2, document2HistoryCanRedo, document2HistoryCanUndo, document2Latex, document2Preview, ensureDocument2BibliographyBlock, findFirstInlineField, formatBibliographyNumber, formatCiteLabel, fromDocumentJson2, getArabicXeLatexPreamble, inlineFieldLatex, insertCiteTokenAtCaret, insertDocument2BlockAfter, insertMathToken, insertMathTokenAtCaret, mathNodeFromArabicSession, mathNodeFromSession, mathSourceFromArabicSession, mathSourceFromSession, mathTokenSourceForSide, mathTokenToArabicEditorSession, mathTokenToEditorSession, moveDocument2BlockById, moveDocument2Reference, parseCiteKeys, pushDocument2Snapshot, referenceFromJson, referenceNumberMap, removeCiteTokenById, removeDocument2BlockById, removeDocument2ListItem, removeDocument2Reference, removeMathTokenById, replaceMathTokenFromSession, resolveCiteNumbers, restoreDocument2Redo, restoreDocument2Undo, setDocument2References, updateCiteTokenKeys, updateDocument2ImageValue, updateDocument2Reference, updateTextToken };