@silurus/ooxml 0.64.2 → 0.65.0

package/dist/types/docx.d.ts

@@ -30,6 +30,27 @@ export declare type BodyElement = {
 } & DocTable | {
     type: 'pageBreak';
     parity?: 'odd' | 'even';
+}
+/** ECMA-376 §17.3.1.20 `<w:br w:type="column"/>` — force the following content
+*  into the next newspaper column (or the next page's first column when
+*  already in the last column). Hoisted to the body level by the parser. */
+| {
+    type: 'columnBreak';
+}
+/** ECMA-376 §17.6.x — a section boundary in the body. A `<w:sectPr>` carried in
+*  a paragraph's `pPr` (or a loose mid-body one) defines the section that ENDS
+*  here; the FINAL section's settings live on {@link DocxDocumentModel.section}.
+*  `columns` is the ENDING section's `<w:cols>` (§17.6.4; absent ⇒ single
+*  full-width column — the spec default for `@w:num` 1). `kind` is the
+*  ST_SectionMark (§17.18.79) controlling how the NEXT section starts:
+*  "continuous" (same page), "nextPage" (default; page break), "oddPage" /
+*  "evenPage" (page break + parity padding). The paginator switches its active
+*  newspaper-column geometry per section at each marker — fixing the regression
+*  where every section inherited the body-level section's columns. */
+| {
+    type: 'sectionBreak';
+    kind: 'continuous' | 'nextPage' | 'oddPage' | 'evenPage' | string;
+    columns?: ColumnsSpec | null;
 };
 
 export declare interface BorderSpec {
@@ -43,6 +64,14 @@ export declare interface CellBorders {
     bottom: BorderSpec | null;
     left: BorderSpec | null;
     right: BorderSpec | null;
+    /** ECMA-376 §17.4.34 (tcBorders w:insideH/w:insideV): the interior
+     *  horizontal/vertical border this cell contributes. Folded from the cell's
+     *  inline tcBorders OVER the resolved conditional table-style borders (§17.7.6)
+     *  at parse time. `null` = unset (the renderer falls back to the table-level
+     *  insideH/insideV); a spec with style "nil"/"none" = an explicit "no interior
+     *  border" (e.g. banded data rows in Medium List 2 / Medium Shading 2). */
+    insideH: BorderSpec | null;
+    insideV: BorderSpec | null;
 }
 
 /** ECMA-376 §17.4.7: a table cell may contain paragraphs AND nested tables. */
@@ -52,6 +81,29 @@ export declare type CellElement = {
     type: 'table';
 } & DocTable;
 
+/** ECMA-376 §17.6.3 `<w:col>` — one column's width and trailing space (pt). */
+export declare interface ColSpec {
+    widthPt: number;
+    spacePt: number;
+}
+
+/** ECMA-376 §17.6.4 `<w:cols>` — the section's multi-column configuration. */
+export declare interface ColumnsSpec {
+    /** `@w:num` — number of columns (>= 2 when emitted). */
+    count: number;
+    /** `@w:space` in pt — inter-column gap for equal-width columns (default 36pt
+     *  = 720 twips per the spec). */
+    spacePt: number;
+    /** `@w:equalWidth` (default true) — all columns share one width + `spacePt`.
+     *  When false, `cols` carries explicit per-column geometry. */
+    equalWidth: boolean;
+    /** `@w:sep` — draw vertical separator rules between columns. */
+    sep: boolean;
+    /** Per-column `<w:col>` entries (width + trailing space, pt). Empty when
+     *  `equalWidth` is true. */
+    cols: ColSpec[];
+}
+
 export declare interface DocComment {
     id: string;
     author?: string;
@@ -124,6 +176,13 @@ export declare interface DocParagraph {
      * Text" style, so footnote bodies use compact natural line height.
      */
     snapToGrid?: boolean;
+    /**
+     * ECMA-376 §17.3.1.11 `<w:framePr>` — text-frame / drop-cap properties.
+     * Present ⇒ this paragraph is part of a text frame; the renderer positions it
+     * as a frame (drop cap or generic frame) and registers a wrap exclusion so
+     * following body text flows around it. Absent ⇒ ordinary in-flow paragraph.
+     */
+    framePr?: FramePr;
 }
 
 export declare interface DocRevision {
@@ -182,9 +241,12 @@ export declare interface DocTable {
     /** table horizontal alignment on the page: 'left' | 'center' | 'right'. */
     jc: string;
     /** ECMA-376 §17.4.52 `<w:tblLayout w:type>` — 'fixed' | 'autofit'. Absent
-     *  (undefined) ⇒ spec default 'autofit': columns are sized by the per-column
-     *  max preferred width (cell `widthPt`), tblGrid only as fallback. 'fixed'
-     *  uses tblGrid widths verbatim (scaled to fit). */
+     *  (undefined) ⇒ spec default 'autofit'. Both paths size columns from the
+     *  tblGrid (§17.4.48) scaled to fit: 'fixed' uses the grid verbatim; 'autofit'
+     *  additionally lets content min-width grow a column. Per-cell `widthPt`/
+     *  `widthPct` (`<w:tcW>`) is NOT re-applied — Word bakes the resolved widths
+     *  into the saved grid (see resolveColumnWidths). Only a degenerate all-zero
+     *  grid falls back to tcW-preference sizing. */
     layout?: string;
     /** ECMA-376 §17.4.63 `<w:tblW>` preferred table width (type="dxa"), pt. */
     widthPt?: number;
@@ -197,6 +259,13 @@ export declare interface DocTable {
      * is placed rightmost, and flips per-cell left/right borders accordingly.
      */
     bidiVisual?: boolean;
+    /** ECMA-376 §17.4.57 `<w:tblpPr>` — when present the table is FLOATING
+     *  (absolutely positioned, out of the main text flow). Absent ⇒ block table. */
+    tblpPr?: TblpPr;
+    /** ECMA-376 §17.4.56 `<w:tblOverlap w:val>` — 'never' | 'overlap'. 'never' ⇒
+     *  the floating table must be repositioned to avoid overlapping other floats.
+     *  Default 'overlap' (omitted ⇒ overlap allowed). Ignored when not floating. */
+    overlap?: string;
 }
 
 export declare interface DocTableCell {
@@ -206,12 +275,15 @@ export declare interface DocTableCell {
     borders: CellBorders;
     background: string | null;
     vAlign: 'top' | 'center' | 'bottom';
-    /** ECMA-376 §17.4.71 `<w:tcW>` preferred cell width (type="dxa"), pt. Drives
-     *  autofit column sizing: each grid column's width is the max `widthPt` over
-     *  the cells anchored in it. */
+    /** ECMA-376 §17.4.71 `<w:tcW>` preferred cell width (type="dxa"), pt. A
+     *  PREFERRED width only: autofit column sizing is driven by the tblGrid
+     *  (§17.4.48), not by re-applying this (Word bakes the resolved widths into
+     *  the saved grid — see resolveColumnWidths). Consulted only for the
+     *  degenerate all-zero-grid fallback. */
     widthPt: number | null;
     /** `<w:tcW>` type="pct": 50ths of a percent of available content width.
-     *  Resolved against the available width at render time. */
+     *  Resolved against the available width at render time. Preferred width only
+     *  (see `widthPt`). */
     widthPct?: number;
     /** Per-cell margins (pt) from `<w:tcPr><w:tcMar>` (ECMA-376 §17.4.42). Each
      *  edge overrides the table-level `cellMargin*` default when set; null/absent
@@ -339,6 +411,19 @@ export declare interface DocxDocumentModel {
     settings?: DocSettings;
 }
 
+/** ECMA-376 §17.3.2.4 `<w:bdr>` — a run-level border drawn as a box around the
+ *  run's text. Parallel to {@link ParaBorderEdge} but applies per run. */
+export declare interface DocxRunBorder {
+    /** "single" | "double" | "dashed" | ... (w:bdr/@w:val) */
+    style: string;
+    /** hex 6-char, or null for automatic (renderer falls back to text color) */
+    color?: string | null;
+    /** pt (sz / 8) */
+    width: number;
+    /** pt spacing between the border and the run text (w:space) */
+    space: number;
+}
+
 export declare interface DocxTextRun {
     text: string;
     bold: boolean;
@@ -348,8 +433,26 @@ export declare interface DocxTextRun {
     fontSize: number;
     color: string | null;
     fontFamily: string | null;
+    /** ECMA-376 §17.3.2.26 eastAsia axis (`<w:rFonts w:eastAsia>`), resolved
+     *  through the style chain + docDefaults. CJK code points in this run render
+     *  with this family; {@link DocxTextRun.fontFamily} keeps the conflated single-
+     *  font fallback (ascii → eastAsia) for paths that do not split per character.
+     *  The renderer routes consecutive CJK code points to this axis (the same per-
+     *  script rule {@link ShapeTextRun.fontFamilyEastAsia} uses), so a Gothic
+     *  eastAsia title sits beside a serif ascii number with no name heuristics.
+     *  Absent ⇒ the renderer falls back to {@link DocxTextRun.fontFamily}. */
+    fontFamilyEastAsia?: string | null;
     isLink: boolean;
     background: string | null;
+    /** ECMA-376 §17.3.2.6 — `<w:color w:val="auto"/>` was set on this run. When
+     *  true and {@link DocxTextRun.color} is absent, the renderer resolves the
+     *  glyph color from the effective background (an implementation-defined
+     *  black/white contrast pick; ECMA-376 gives no normative algorithm) instead
+     *  of the default text color. */
+    colorAuto?: boolean | null;
+    /** ECMA-376 §17.3.2.4 `<w:bdr>` — a run-level border (box) drawn around the
+     *  run text. Absent when the run has no border. */
+    border?: DocxRunBorder | null;
     vertAlign: 'super' | 'sub' | null;
     /** Target URL for hyperlinks (resolved from relationships.xml) */
     hyperlink: string | null;
@@ -481,6 +584,45 @@ export declare interface FieldRun {
     highlight?: string | null;
 }
 
+/**
+ * ECMA-376 §17.3.1.11 `<w:framePr>` — text-frame / drop-cap properties.
+ *
+ * Lengths are pt (parser converts from twips). Per the spec, `x`/`y` are
+ * ignored when `xAlign`/`yAlign` are set, and for a drop cap `y`/`yAlign` are
+ * ignored entirely while `lines` drives the height. `w`/`h`/`x`/`y` are
+ * `undefined` when the attribute was absent (distinct from an explicit 0).
+ */
+export declare interface FramePr {
+    /** ST_DropCap (§17.18.20): 'none' | 'drop' | 'margin'. Default 'none'. */
+    dropCap: 'none' | 'drop' | 'margin' | string;
+    /** §17.3.1.11 `lines` — drop-cap vertical height in anchor lines. Default 1. */
+    lines: number;
+    /** ST_Wrap (§17.18.104): 'around'|'auto'|'none'|'notBeside'|'through'|'tight'. Default 'around'. */
+    wrap: 'around' | 'auto' | 'none' | 'notBeside' | 'through' | 'tight' | string;
+    /** ST_HAnchor (§17.18.35): 'text'(=column) | 'margin' | 'page'. Default 'page'. */
+    hAnchor: 'text' | 'margin' | 'page' | string;
+    /** ST_VAnchor (§17.18.100): 'text' | 'margin' | 'page'. Default 'page'. */
+    vAnchor: 'text' | 'margin' | 'page' | string;
+    /** ST_HeightRule (§17.18.37): 'auto' | 'atLeast' | 'exact'. Default 'auto'. */
+    hRule: 'auto' | 'atLeast' | 'exact' | string;
+    /** hSpace — min wrap padding L/R when wrap='around' (pt). Default 0. */
+    hSpace: number;
+    /** vSpace — min wrap padding top/bottom (pt). Default 0. */
+    vSpace: number;
+    /** w — exact frame width (pt). Absent ⇒ auto (max content line width). */
+    w?: number;
+    /** h — frame height (pt). Meaning gated by hRule. Absent ⇒ auto. */
+    h?: number;
+    /** x — absolute horizontal offset from hAnchor (pt). Ignored when xAlign set. */
+    x?: number;
+    /** y — absolute vertical offset from vAnchor (pt). Ignored when yAlign set / drop cap. */
+    y?: number;
+    /** ST_XAlign (§22.9.2.18): 'left'|'center'|'right'|'inside'|'outside'. Supersedes x. */
+    xAlign?: 'left' | 'center' | 'right' | 'inside' | 'outside' | string;
+    /** ST_YAlign (§22.9.2.20): 'inline'|'top'|'center'|'bottom'|'inside'|'outside'. Supersedes y. */
+    yAlign?: 'inline' | 'top' | 'center' | 'bottom' | 'inside' | 'outside' | string;
+}
+
 export declare interface GradientStop {
     /** 0.0–1.0 */
     position: number;
@@ -563,6 +705,29 @@ export declare interface ImageRun {
      * reposition the object to prevent any overlap.
      */
     allowOverlap?: boolean;
+    /** ECMA-376 §20.4.3.1 wp:align horizontal: "left" | "center" | "right" |
+     *  "inside" | "outside". When set the renderer aligns the image inside the
+     *  container indicated by `anchorXFromMargin` and ignores `anchorXPt`.
+     *  Mirrors {@link ShapeRun.anchorXAlign}. Absent for inline images and
+     *  offset-based anchors. */
+    anchorXAlign?: string | null;
+    /** Vertical equivalent of anchorXAlign: "top" | "center" | "bottom". */
+    anchorYAlign?: string | null;
+    /**
+     * ECMA-376 §20.4.3.2 `<wp:positionH/@relativeFrom>` / §20.4.3.5
+     * `<wp:positionV/@relativeFrom>` — names the container the offset / align /
+     * pctPos is measured against. Raw spec string: `"page"`, `"margin"`,
+     * `"paragraph"`, `"line"`, `"leftMargin"`, `"rightMargin"`, `"topMargin"`,
+     * `"bottomMargin"`, `"insideMargin"`, `"outsideMargin"`, `"column"`,
+     * `"character"`. Mirrors {@link ShapeRun.anchorXRelativeFrom} /
+     * {@link ShapeRun.anchorYRelativeFrom}. When present, supersedes the legacy
+     * coarse boolean hints (`anchorXFromMargin` / `anchorYFromPara`) for the
+     * align and pctPos paths so e.g. `relativeFrom="margin"` + `align="top"`
+     * pins the image to the top content margin rather than the page top. Absent
+     * for inline images and for anchors that omitted `<wp:positionH/V>`.
+     */
+    anchorXRelativeFrom?: string | null;
+    anchorYRelativeFrom?: string | null;
 }
 
 /** DrawingML line-end (arrow head). ECMA-376 §20.1.8.3 CT_LineEndProperties.
@@ -803,6 +968,33 @@ export declare interface NumberingInfo {
     /** ECMA-376 §17.9.28 `<w:suff>` — "tab" (default) | "space" | "nothing".
      *  Where body text starts after the marker on the first line. */
     suff: string;
+    /** ECMA-376 §17.9.8 `<w:lvlJc>` — marker justification: "left" (default) |
+     *  "right" (period-aligned numerals: marker RIGHT edge at the hanging-indent
+     *  position) | "center". The renderer offsets the marker draw accordingly.
+     *  Always emitted by the parser; optional here so hand-built fixtures may omit
+     *  it (the renderer treats absent as "left"). */
+    jc?: string;
+    /** ECMA-376 §17.3.2.26 ascii axis for the marker glyph, resolved through the
+     *  level's `rPr` (§17.9.6) merged over the paragraph's run formatting. The
+     *  renderer draws Latin marker chars (e.g. a decimal "1") with this family, so
+     *  a heading whose ascii=Times renders its auto-number in Times (serif) even
+     *  when eastAsia=Gothic. Absent ⇒ the renderer falls back to its default. */
+    fontFamily?: string | null;
+    /** ECMA-376 §17.3.2.26 eastAsia axis for the marker glyph (same resolution as
+     *  {@link NumberingInfo.fontFamily}). The renderer draws CJK marker chars with
+     *  this family. Absent ⇒ the renderer falls back to
+     *  {@link NumberingInfo.fontFamily}. */
+    fontFamilyEastAsia?: string | null;
+    /** ECMA-376 §17.9.9/§17.9.20 — when the level uses a `<w:lvlPicBulletId>`,
+     *  the marker is this image (zip path, e.g. `word/media/image1.gif`), drawn in
+     *  place of {@link NumberingInfo.text}. Absent ⇒ ordinary text/glyph marker. */
+    picBulletImagePath?: string;
+    /** MIME type of {@link NumberingInfo.picBulletImagePath} (e.g. `image/gif`). */
+    picBulletMimeType?: string;
+    /** Picture-bullet marker width in pt (from the `<v:shape style="width">`). */
+    picBulletWidthPt?: number;
+    /** Picture-bullet marker height in pt (from the `<v:shape style="height">`). */
+    picBulletHeightPt?: number;
 }
 
 export declare interface ParaBorderEdge {
@@ -901,6 +1093,18 @@ export declare interface SectionProps {
      *  "linesAndChars", auto line spacing multiplies against this pitch instead of
      *  the font's natural line height. */
     docGridLinePitch?: number | null;
+    /** ECMA-376 §17.6.5 w:docGrid/@w:charSpace (ST_DecimalNumber, signed). The
+     *  raw character-grid spacing in 1/4096ths of an em (NOT twips). When
+     *  docGridType is "linesAndChars" or "snapToChars", every full-width East-
+     *  Asian glyph occupies a fixed cell of width `fontSizePt + charSpace/4096` pt
+     *  (negative = tighter). Absent ⇒ East-Asian glyphs keep their natural em
+     *  advance. */
+    docGridCharSpace?: number | null;
+    /** ECMA-376 §17.6.4 `<w:cols>` — newspaper-style multi-column layout. `null`
+     *  (or absent) ⇒ single full-width column (unchanged behavior). When present,
+     *  body text flows top-to-bottom through `count` columns (newspaper fill);
+     *  see {@link computeColumns}. */
+    columns?: ColumnsSpec | null;
 }
 
 declare type ShapeFill = {
@@ -980,6 +1184,17 @@ export declare interface ShapeRun {
     /** `<a:xfrm flipV>` (§20.1.7.6) — mirror about the horizontal centre line. */
     flipV?: boolean;
     wrapMode?: string | null;
+    /** Padding top (pt). Anchor-only. Mirrors {@link ImageRun.distTop}; an anchored
+     *  wrap-shape uses these to size its float-exclusion band (ECMA-376 §20.4.2.x). */
+    distTop?: number;
+    /** Padding bottom (pt). Anchor-only. */
+    distBottom?: number;
+    /** Padding left (pt). Anchor-only. */
+    distLeft?: number;
+    /** Padding right (pt). Anchor-only. */
+    distRight?: number;
+    /** wrapText attribute: "bothSides" | "left" | "right" | "largest". */
+    wrapSide?: string | null;
     /** Text rendered INSIDE the shape's bounding box (`<wps:txbx><w:txbxContent>`). */
     textBlocks?: ShapeText[];
     /** "t" | "ctr" | "b" — vertical anchor for the shape's text body (`<wps:bodyPr @anchor>`). */
@@ -997,7 +1212,45 @@ export declare interface ShapeText {
     fontFamily?: string | null;
     bold?: boolean;
     italic?: boolean;
+    /** Per-run formatting for this paragraph (one entry per `<w:r>` with text).
+     *  When non-empty the renderer draws the block as rich text (each run's
+     *  font); otherwise it uses the single block-level format fields above
+     *  (image blocks / legacy single-format paragraphs). Absent for image-only
+     *  paragraphs. */
+    runs?: ShapeTextRun[];
     alignment: string;
+    /** Zip path of an inline image inside this text-box paragraph
+     *  (`<w:drawing><wp:inline><a:blip r:embed>`), e.g. `word/media/image1.emf`.
+     *  Absent for a text-only paragraph. */
+    imagePath?: string;
+    /** MIME type of the blip at {@link ShapeText.imagePath}. */
+    mimeType?: string;
+    /** Zip path of the vector original (`asvg:svgBlip` extension), preferred over
+     *  `imagePath` when present. */
+    svgImagePath?: string;
+    /** Inline image natural width in pt (from `<wp:extent cx>`). */
+    imageWidthPt?: number;
+    /** Inline image natural height in pt (from `<wp:extent cy>`). */
+    imageHeightPt?: number;
+}
+
+/** One formatting run (`<w:r>`) inside a shape-text paragraph. Mirrors the
+ *  character-formatting fields of {@link ShapeText}; the renderer lays a
+ *  paragraph's {@link ShapeText.runs} out as rich text so mixed bold/non-bold
+ *  runs each keep their own font. */
+export declare interface ShapeTextRun {
+    text: string;
+    fontSizePt: number;
+    color?: string | null;
+    /** ECMA-376 §17.3.2.26 ascii axis (`<w:rFonts w:ascii>`), resolved through
+     *  docDefaults. Latin letters/digits in this run render with this family. */
+    fontFamily?: string | null;
+    /** ECMA-376 §17.3.2.26 eastAsia axis (`<w:rFonts w:eastAsia>`), resolved
+     *  through docDefaults. CJK characters in this run render with this family;
+     *  the renderer falls back to {@link ShapeTextRun.fontFamily} when absent. */
+    fontFamilyEastAsia?: string | null;
+    bold?: boolean;
+    italic?: boolean;
 }
 
 export declare interface TableBorders {
@@ -1016,6 +1269,39 @@ export declare interface TabStop {
     leader: 'none' | 'dot' | 'hyphen' | 'underscore' | 'heavy' | 'middleDot';
 }
 
+/**
+ * ECMA-376 §17.4.57 `<w:tblpPr>` — floating-table positioning. Present in
+ * `<w:tblPr>` ⇒ the table FLOATS (out of the main text flow, absolutely
+ * positioned by its top-left corner). All fields are optional in the source.
+ */
+export declare interface TblpPr {
+    /** §17.4.57 minimum distance to wrapping text (dist padding), pt. Default 0. */
+    leftFromText: number;
+    rightFromText: number;
+    topFromText: number;
+    bottomFromText: number;
+    /** §17.4.57 ST_HAnchor {text,margin,page}. Default 'page'. */
+    horzAnchor: 'text' | 'margin' | 'page' | string;
+    /** True iff the source `<w:tblpPr>` carried ANY horizontal positioning hint
+     *  (horzAnchor, tblpX, or tblpXSpec). When false, no horizontal position was
+     *  given: ECMA-376's literal default is the page edge, but Word places such a
+     *  table at the anchor paragraph's text/column left. computeFloatTableBox uses
+     *  this flag to apply that Word-runtime placement. */
+    horzSpecified: boolean;
+    /** §17.4.57 ST_VAnchor {text,margin,page}. Default 'page'. */
+    vertAnchor: 'text' | 'margin' | 'page' | string;
+    /** §17.4.57 absolute signed offset from the horz/vert anchor edge, pt.
+     *  Default 0. Ignored when the matching `*Spec` is present. */
+    tblpX: number;
+    tblpY: number;
+    /** §17.4.57 ST_XAlign {left,center,right,inside,outside}. Supersedes tblpX. */
+    tblpXSpec?: 'left' | 'center' | 'right' | 'inside' | 'outside' | string;
+    /** §17.4.57 ST_YAlign {inline,top,center,bottom,inside,outside}. Supersedes
+     *  tblpY, UNLESS vertAnchor='text' (relative vertical positioning is not
+     *  allowed there ⇒ tblpYSpec is ignored, fall back to tblpY). */
+    tblpYSpec?: 'inline' | 'top' | 'center' | 'bottom' | 'inside' | 'outside' | string;
+}
+
 /** Serializable subset of RenderPageOptions (callbacks cannot cross the wire). */
 export declare type WireRenderPageOptions = Omit<RenderPageOptions, 'onTextRun'>;