@silurus/ooxml 0.50.1 → 0.52.0

package/dist/types/xlsx.d.ts

@@ -476,6 +476,139 @@ declare interface ManualLayout {
     h?: number;
 }
 
+/** Accent (`m:acc`), e.g. hat, bar, vector arrow over the base. */
+declare interface MathAccent {
+    kind: 'accent';
+    char: string;
+    base: MathNode[];
+}
+
+/** Matrix (`m:m`) or aligned equation array (`m:eqArr`). rows → cells → nodes. */
+declare interface MathArray {
+    kind: 'array';
+    rows: MathNode[][][];
+    /** 'eq' = alternating right/left (eqArr); 'center' = matrix; 'left'. */
+    align: 'eq' | 'center' | 'left';
+}
+
+/** Over/under bar (`m:bar`). */
+declare interface MathBar {
+    kind: 'bar';
+    pos: 'top' | 'bot';
+    base: MathNode[];
+}
+
+declare interface MathDelimiter {
+    kind: 'delimiter';
+    /** opening char (default '('). */
+    begChar: string;
+    /** closing char (default ')'). */
+    endChar: string;
+    /** separated groups (e.g. for cases / multiple args). */
+    items: MathNode[][];
+}
+
+declare interface MathFraction {
+    kind: 'fraction';
+    num: MathNode[];
+    den: MathNode[];
+    /** false = no rule (e.g. binomial); defaults to true. */
+    bar?: boolean;
+}
+
+declare interface MathFunc {
+    kind: 'func';
+    name: MathNode[];
+    arg: MathNode[];
+}
+
+declare interface MathGroup {
+    kind: 'group';
+    items: MathNode[];
+}
+
+/** Group character (`m:groupChr`), e.g. under/over brace. */
+declare interface MathGroupChr {
+    kind: 'groupChr';
+    char: string;
+    pos: 'top' | 'bot';
+    base: MathNode[];
+}
+
+/** Lower/upper limit (`m:limLow` / `m:limUpp`), e.g. lim under n→∞. */
+declare interface MathLimit {
+    kind: 'limit';
+    base: MathNode[];
+    lower?: MathNode[];
+    upper?: MathNode[];
+}
+
+declare interface MathNary {
+    kind: 'nary';
+    /** operator char, e.g. '∑', '∫', '∏'. */
+    op: string;
+    /** limit location (`m:limLoc`): 'subSup' = beside the op, 'undOvr' = above/below.
+     *  Empty/omitted = default by operator class (integrals → subSup, others → undOvr). */
+    limLoc?: string;
+    sub?: MathNode[];
+    sup?: MathNode[];
+    body: MathNode[];
+}
+
+declare type MathNode = MathRun | MathFraction | MathScript | MathNary | MathDelimiter | MathRadical | MathLimit | MathArray | MathGroupChr | MathBar | MathAccent | MathFunc | MathGroup;
+
+declare interface MathRadical {
+    kind: 'radical';
+    /** optional index (e.g. cube root); empty/omitted = square root. */
+    index?: MathNode[];
+    radicand: MathNode[];
+}
+
+/**
+ * The math engine contract a viewer needs to render equations. Satisfied by the
+ * `math` named export of the separate `@silurus/ooxml/math` entry point, which
+ * the consumer opts into:
+ *
+ * ```ts
+ * import { DocxViewer } from '@silurus/ooxml/docx';
+ * import { math } from '@silurus/ooxml/math';
+ * new DocxViewer(canvas, { math });
+ * ```
+ *
+ * Omit it and the equation engine (MathJax + STIX Two Math, ~3 MB) is never
+ * imported, so a bundler drops it entirely.
+ */
+declare interface MathRenderer {
+    /** Preload the engine. Called once before converting equations. */
+    loadMathJax(): Promise<void>;
+    /** MathML string → standalone SVG + baseline-relative em extents. */
+    mathMLToSvg(mathml: string): Promise<MathSvg>;
+}
+
+declare interface MathRun {
+    kind: 'run';
+    text: string;
+    style: MathStyle;
+}
+
+declare interface MathScript {
+    kind: 'sup' | 'sub' | 'subSup';
+    base: MathNode[];
+    sup?: MathNode[];
+    sub?: MathNode[];
+}
+
+declare type MathStyle = 'roman' | 'italic' | 'bold' | 'boldItalic';
+
+declare interface MathSvg {
+    /** standalone `<svg>…</svg>` markup. */
+    svg: string;
+    /** extents in em (the SVG viewBox uses 1em = 1000 units). */
+    widthEm: number;
+    ascentEm: number;
+    descentEm: number;
+}
+
 export declare interface MergeCell {
     top: number;
     left: number;
@@ -549,6 +682,11 @@ export declare interface RenderViewportOptions {
     cellScale?: number;
     /** Pre-loaded Image elements keyed by their dataUrl (for ImageAnchor rendering). */
     loadedImages?: Map<string, HTMLImageElement>;
+    /** Opt-in OMML equation engine. Import it from the separate `@silurus/ooxml/math`
+     *  entry and pass it in (`import { math } from '@silurus/ooxml/math'`). When
+     *  omitted, equations in shapes are skipped and the ~3 MB engine never enters
+     *  the bundle. Same DI contract as docx/pptx. */
+    math?: MathRenderer;
     /** Called once per cell that contains text, with canvas-pixel position and cell address. */
     onTextRun?: (info: XlsxTextRunInfo) => void;
     /** Highlighted row range for selected row headers (1-indexed inclusive).
@@ -683,7 +821,12 @@ declare interface ShapeText {
     paragraphs: ShapeParagraph[];
 }
 
-declare interface ShapeTextRun {
+/** A run within a shape paragraph — tagged union mirroring the Rust enum
+ *  (matches the pptx `TextRun` shape): styled text, a soft line break, or an
+ *  OMML equation. Excel stores "Insert > Equation" as OMML inside the shared
+ *  DrawingML `<xdr:txBody>` grammar (ECMA-376 §22.1), like PowerPoint. */
+declare type ShapeTextRun = {
+    type: 'text';
     text: string;
     bold: boolean;
     italic: boolean;
@@ -692,7 +835,18 @@ declare interface ShapeTextRun {
     size: number;
     color?: string;
     fontFace?: string;
-}
+} | {
+    type: 'break';
+} | {
+    type: 'math';
+    /** OMML AST (shared `MathNode` model) for the equation. */
+    nodes: MathNode[];
+    /** true = block (`m:oMathPara`), false = inline (`m:oMath`). */
+    display: boolean;
+    /** Point size when the run carries an explicit `rPr@sz`; else inherit. */
+    fontSize?: number;
+    color?: string;
+};
 
 declare interface SharedString {
     text: string;
@@ -1076,6 +1230,14 @@ export declare interface XlsxViewerOptions {
      * values fall back to the default.
      */
     maxZipEntryBytes?: number;
+    /**
+     * Opt-in OMML equation engine for rendering math in shapes/text boxes.
+     * Import it from the separate `@silurus/ooxml/math` entry and pass it in
+     * (`import { math } from '@silurus/ooxml/math'`). When omitted, equations are
+     * skipped and the ~3 MB engine never enters the bundle (tree-shaken). Same
+     * dependency-injection contract as the docx/pptx viewers.
+     */
+    math?: MathRenderer;
 }
 
 export declare class XlsxWorkbook {