@silurus/ooxml 0.57.0 → 0.59.0

package/dist/types/docx.d.ts

@@ -62,7 +62,12 @@ export declare interface DocComment {
 
 export declare interface DocNote {
     id: string;
-    text: string;
+    /** ECMA-376 §17.11.2 / §17.11.10 — the note's block-level content
+     *  (paragraphs / nested tables), parsed with the document's styles +
+     *  numbering. The leading run is the `<w:footnoteRef/>` auto-number marker
+     *  (carries a {@link DocxTextRun.noteRef}). Use {@link noteText} to extract
+     *  the plain-text body without the marker. */
+    content: BodyElement[];
 }
 
 export declare interface DocParagraph {
@@ -104,10 +109,21 @@ export declare interface DocParagraph {
     defaultFontFamily?: string | null;
     /**
      * ECMA-376 §17.3.1.6 `<w:bidi>` — right-to-left paragraph. `true` = RTL,
-     * `false` = explicitly LTR, absent = unspecified (inherit). Phase 0 of RTL
-     * support: recorded only; alignment/column-order resolution is deferred.
+     * `false` = explicitly LTR, absent = unspecified (inherit). The renderer uses
+     * this as the paragraph base direction: it seeds the UAX#9 reordering pass
+     * (`computeLineVisualOrder`), swaps the left/right indents, resolves the
+     * `w:jc` start/end edges (`resolveAlignEdge`), and lays out lines from the
+     * right.
      */
     bidi?: boolean;
+    /**
+     * ECMA-376 §17.3.1.32 `<w:snapToGrid>` — when `false`, this paragraph opts out
+     * of the section's document grid (`w:docGrid`): its lines use natural font
+     * metrics / the line-spacing multiplier directly instead of snapping to the
+     * grid pitch. `undefined` = inherit (default on). Set on Word's "Footnote
+     * Text" style, so footnote bodies use compact natural line height.
+     */
+    snapToGrid?: boolean;
 }
 
 export declare interface DocRevision {
@@ -135,6 +151,7 @@ export declare type DocRun = {
     nodes: MathNode[];
     display: boolean;
     fontSize: number;
+    jc?: string;
 };
 
 export declare interface DocSettings {
@@ -148,6 +165,10 @@ export declare interface DocSettings {
     /** §17.15.1.59 `w:noLineBreaksAfter@w:val` — custom set of characters that
      *  cannot end a line (行末禁則). Replaces the default when present. */
     noLineBreaksAfter?: string;
+    /** §22.1.2.30 `m:mathPr/m:defJc@m:val` — document-wide default math
+     *  justification (ST_Jc math: left|right|center|centerGroup). `undefined`
+     *  ⇒ the renderer uses the spec default `centerGroup`. */
+    mathDefJc?: string;
 }
 
 export declare interface DocTable {
@@ -172,8 +193,8 @@ export declare interface DocTable {
     /**
      * ECMA-376 §17.4.1 `<w:bidiVisual>` — render columns in right-to-left
      * (visual) order. `true` = RTL columns, `false` = explicitly LTR, absent =
-     * unspecified. Phase 0 of RTL support: recorded only; column-order
-     * resolution is deferred.
+     * unspecified. When `true` the renderer mirrors the grid so logical column 0
+     * is placed rightmost, and flips per-cell left/right borders accordingly.
      */
     bidiVisual?: boolean;
 }
@@ -212,7 +233,9 @@ export declare interface DocTableRow {
 
 export declare class DocxDocument {
     private _document;
+    private _meta;
     private _pages;
+    private _mode;
     private _worker;
     private _bridge;
     private constructor();
@@ -220,9 +243,46 @@ export declare class DocxDocument {
     private _parse;
     destroy(): void;
     get pageCount(): number;
+    /**
+     * The raw parsed document model. Available only in `mode: 'main'`; in
+     * `mode: 'worker'` the model stays in the worker and this throws.
+     */
     get document(): DocxDocumentModel;
+    /**
+     * ECMA-376 §17.13.4 — the document's comments (`word/comments.xml`), each with
+     * id / author / initials / date / plain-text body. Comments are a data-only
+     * API: they are NOT drawn on the page (Word renders them in a margin pane /
+     * balloons, which this viewer does not reproduce). Use this to build a review
+     * panel, export an annotation list, etc. Returns `[]` when the document has no
+     * comments part. The same data is also reachable via `document.comments`.
+     */
+    get comments(): DocComment[];
+    /**
+     * ECMA-376 §17.11.10 — the document's footnotes (`word/footnotes.xml`),
+     * excluding the reserved separator entries. Each note carries its `id` and
+     * block-level `content`; use {@link noteText} for the plain-text body. These
+     * ARE drawn at the bottom of the page that holds their reference; this getter
+     * additionally exposes them as data. Returns `[]` when absent.
+     */
+    get footnotes(): DocNote[];
+    /**
+     * ECMA-376 §17.11.4 — the document's endnotes (`word/endnotes.xml`). Same
+     * shape as {@link footnotes}; rendered at the end of the document. Returns
+     * `[]` when absent.
+     */
+    get endnotes(): DocNote[];
     private _getPages;
     renderPage(target: HTMLCanvasElement | OffscreenCanvas, pageIndex: number, opts?: RenderPageOptions): Promise<void>;
+    /**
+     * Render a page and return it as an ImageBitmap. Works in both modes; in
+     * worker mode the render runs entirely off the main thread. Paint with:
+     * `canvas.getContext('bitmaprenderer').transferFromImageBitmap(bitmap)`.
+     *
+     * The returned ImageBitmap is owned by the caller: pass it to
+     * `transferFromImageBitmap` (which consumes it) or call `bitmap.close()`
+     * when done, or its backing memory is held until GC.
+     */
+    renderPageToBitmap(pageIndex: number, opts?: WireRenderPageOptions): Promise<ImageBitmap>;
 }
 
 export declare interface DocxDocumentModel {
@@ -291,8 +351,10 @@ export declare interface DocxTextRun {
      *  tracked changes appear inline. */
     revision?: RunRevision;
     /** ECMA-376 §17.3.2.30 `<w:rtl>` — complex-script / right-to-left run.
-     *  `true` = RTL, `false` = explicitly LTR, absent = unspecified.
-     *  Phase 0: recorded only; glyph-order resolution is deferred. */
+     *  `true` = RTL, `false` = explicitly LTR, absent = unspecified. The renderer
+     *  treats a `true` run as RTL for the UAX#9 pass (it forces complex-script
+     *  shaping and marks the segment so `computeLineVisualOrder` reorders it), and
+     *  draws the slice with `ctx.direction = 'rtl'` so Canvas mirrors the glyphs. */
     rtl?: boolean;
     /** ECMA-376 §17.3.2.7 `<w:cs/>` — complex-script run toggle: cs formatting
      *  applies to ALL characters of the run (§17.3.2.26). Distinct from
@@ -311,6 +373,12 @@ export declare interface DocxTextRun {
     /** ECMA-376 §17.3.2.20 `<w:lang w:bidi>` — complex-script (RTL) language tag,
      *  lower-cased (e.g. "ar-sa", "ae-ar"). Drives Word's AN digit ordering. */
     langBidi?: string;
+    /** ECMA-376 §17.11.6/.7/.16/.17 — set when this run is a footnote/endnote
+     *  reference marker (`<w:footnoteReference>` in the body, `<w:footnoteRef>` at
+     *  the start of the note's content, and the endnote equivalents). `text` holds
+     *  the raw `@w:id`; the renderer overrides the displayed glyph with the note's
+     *  sequential number. */
+    noteRef?: NoteRef;
 }
 
 /** Information about a rendered text segment for building a transparent selection overlay. */
@@ -337,6 +405,12 @@ export declare class DocxViewer {
     private _wrapper;
     private _textLayer;
     private _opts;
+    private readonly _mode;
+    /** The canvas's bitmaprenderer context, used only in worker mode (a canvas
+     *  holds one context type for its lifetime; the main-mode 2d render path is
+     *  never used on the same canvas). */
+    private _bitmapCtx;
+    private _warnedNoTextSelection;
     constructor(canvas: HTMLCanvasElement, opts?: DocxViewerOptions);
     /**
      * Load a DOCX from URL or ArrayBuffer and render the first page.
@@ -473,6 +547,14 @@ export declare interface LoadOptions extends LoadOptions_2 {
      * omitted, equations are skipped and the ~3 MB engine never enters the bundle.
      */
     math?: MathRenderer;
+    /**
+     * 'main' (default): parse in a worker, render on the main thread (current
+     * behaviour). 'worker': parse, paginate AND render inside the worker; use
+     * {@link DocxDocument.renderPageToBitmap} and paint the returned ImageBitmap
+     * via an `ImageBitmapRenderingContext`. Requires OffscreenCanvas. The math
+     * engine is unavailable in this mode (equations are skipped).
+     */
+    mode?: 'main' | 'worker';
 }
 
 /**
@@ -648,6 +730,20 @@ declare interface MathSvg {
     descentEm: number;
 }
 
+/** A footnote / endnote reference marker (ECMA-376 §17.11). */
+export declare interface NoteRef {
+    /** "footnote" | "endnote" */
+    kind: 'footnote' | 'endnote' | string;
+    /** `@w:id` linking the marker to its note. Empty for the in-note
+     *  `<w:footnoteRef/>` placeholder (the renderer uses the enclosing note). */
+    id: string;
+}
+
+/** Flatten a footnote/endnote's content to its plain-text body, excluding the
+ *  auto-number reference marker. Convenience for data-only consumers
+ *  (the renderer draws {@link DocNote.content} directly). */
+export declare function noteText(note: DocNote): string;
+
 export declare interface NumberingInfo {
     numId: number;
     level: number;
@@ -858,4 +954,7 @@ export declare interface TabStop {
     leader: 'none' | 'dot' | 'hyphen' | 'underscore' | 'heavy' | 'middleDot';
 }
 
+/** Serializable subset of RenderPageOptions (callbacks cannot cross the wire). */
+export declare type WireRenderPageOptions = Omit<RenderPageOptions, 'onTextRun'>;
+
 export { }