@silurus/ooxml 0.56.0 → 0.58.0

package/dist/types/docx.d.ts

@@ -32,13 +32,13 @@ export declare type BodyElement = {
     parity?: 'odd' | 'even';
 };
 
-declare interface BorderSpec {
+export declare interface BorderSpec {
     width: number;
     color: string | null;
     style: string;
 }
 
-declare interface CellBorders {
+export declare interface CellBorders {
     top: BorderSpec | null;
     bottom: BorderSpec | null;
     left: BorderSpec | null;
@@ -46,7 +46,7 @@ declare interface CellBorders {
 }
 
 /** ECMA-376 §17.4.7: a table cell may contain paragraphs AND nested tables. */
-declare type CellElement = {
+export declare type CellElement = {
     type: 'paragraph';
 } & DocParagraph | {
     type: 'table';
@@ -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 {
@@ -137,7 +153,7 @@ export declare type DocRun = {
     fontSize: number;
 };
 
-declare interface DocSettings {
+export declare interface DocSettings {
     /** §17.15.1.58 `w:kinsoku` — East-Asian line-breaking toggle. `undefined`
      *  means the element is absent; the spec default is ON (treated as `true`). */
     kinsoku?: boolean;
@@ -150,7 +166,7 @@ declare interface DocSettings {
     noLineBreaksAfter?: string;
 }
 
-declare interface DocTable {
+export declare interface DocTable {
     colWidths: number[];
     rows: DocTableRow[];
     borders: TableBorders;
@@ -172,13 +188,13 @@ 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;
 }
 
-declare interface DocTableCell {
+export declare interface DocTableCell {
     content: CellElement[];
     colSpan: number;
     vMerge: boolean | null;
@@ -201,7 +217,7 @@ declare interface DocTableCell {
     marginRight?: number | null;
 }
 
-declare interface DocTableRow {
+export declare interface DocTableRow {
     cells: DocTableCell[];
     rowHeight: number | null;
     /** ECMA-376 §17.4.80 hRule. "auto" (default) = informational; "atLeast" =
@@ -221,6 +237,29 @@ export declare class DocxDocument {
     destroy(): void;
     get pageCount(): number;
     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>;
 }
@@ -291,8 +330,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 +352,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. */
@@ -372,7 +419,7 @@ export declare interface DocxViewerOptions extends RenderPageOptions, LoadOption
     onError?: (err: Error) => void;
 }
 
-declare interface FieldRun {
+export declare interface FieldRun {
     /** "page" | "numPages" | "other" */
     fieldType: string;
     instruction: string;
@@ -392,18 +439,18 @@ declare interface FieldRun {
     highlight?: string | null;
 }
 
-declare interface GradientStop {
+export declare interface GradientStop {
     /** 0.0–1.0 */
     position: number;
     /** hex 6-char */
     color: string;
 }
 
-declare interface HeaderFooter {
+export declare interface HeaderFooter {
     body: BodyElement[];
 }
 
-declare interface HeadersFooters {
+export declare interface HeadersFooters {
     default: HeaderFooter | null;
     first: HeaderFooter | null;
     even: HeaderFooter | null;
@@ -453,7 +500,7 @@ export declare interface ImageRun {
     wrapSide?: string;
 }
 
-declare interface LineSpacing {
+export declare interface LineSpacing {
     value: number;
     rule: 'auto' | 'exact' | 'atLeast';
     /** True when `w:spacing/@w:line` was set on the paragraph's own pPr or on a
@@ -648,7 +695,21 @@ declare interface MathSvg {
     descentEm: number;
 }
 
-declare interface NumberingInfo {
+/** 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;
     format: string;
@@ -657,7 +718,7 @@ declare interface NumberingInfo {
     tab: number;
 }
 
-declare interface ParaBorderEdge {
+export declare interface ParaBorderEdge {
     style: string;
     color: string | null;
     /** pt (sz / 8) */
@@ -666,7 +727,7 @@ declare interface ParaBorderEdge {
     space: number;
 }
 
-declare interface ParagraphBorders {
+export declare interface ParagraphBorders {
     top: ParaBorderEdge | null;
     bottom: ParaBorderEdge | null;
     left: ParaBorderEdge | null;
@@ -674,7 +735,7 @@ declare interface ParagraphBorders {
     between: ParaBorderEdge | null;
 }
 
-declare type PathCmd = {
+export declare type PathCmd = {
     cmd: 'moveTo';
     x: number;
     y: number;
@@ -721,7 +782,7 @@ export declare interface RenderPageOptions {
     showTrackChanges?: boolean;
 }
 
-declare interface RubyAnnotation {
+export declare interface RubyAnnotation {
     text: string;
     /** Annotation font size in pt. Word stores this as half-points in `<w:hps>`. */
     fontSizePt: number;
@@ -765,7 +826,7 @@ declare type ShapeFill = {
     gradType: string;
 };
 
-declare interface ShapeRun {
+export declare interface ShapeRun {
     widthPt: number;
     heightPt: number;
     /** X offset in pt */
@@ -832,7 +893,7 @@ declare interface ShapeRun {
     textInsetB?: number;
 }
 
-declare interface ShapeText {
+export declare interface ShapeText {
     text: string;
     fontSizePt: number;
     color?: string | null;
@@ -842,7 +903,7 @@ declare interface ShapeText {
     alignment: string;
 }
 
-declare interface TableBorders {
+export declare interface TableBorders {
     top: BorderSpec | null;
     bottom: BorderSpec | null;
     left: BorderSpec | null;
@@ -851,7 +912,7 @@ declare interface TableBorders {
     insideV: BorderSpec | null;
 }
 
-declare interface TabStop {
+export declare interface TabStop {
     /** tab stop position in pt (from the left of paragraph content area) */
     pos: number;
     alignment: 'left' | 'center' | 'right' | 'decimal' | 'bar' | 'clear';