@silurus/ooxml 0.57.0 → 0.58.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 {
@@ -172,8 +188,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;
 }
@@ -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. */
@@ -648,6 +695,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;