docx 9.8.1 → 9.10.0

package/dist/index.d.ts

@@ -103,11 +103,11 @@ export declare const abstractNumUniqueNumericIdGen: () => UniqueNumericIdCreator
  * @publicApi
  */
 export declare const AlignmentType: {
-    /** Align Start */
+    /** Align Start: the left in a left-to-right paragraph, and the right in a `bidirectional` (right-to-left) paragraph */
     readonly START: "start";
     /** Align Center */
     readonly CENTER: "center";
-    /** End */
+    /** Align End: the right in a left-to-right paragraph, and the left in a `bidirectional` (right-to-left) paragraph */
     readonly END: "end";
     /** Justified */
     readonly BOTH: "both";
@@ -123,9 +123,9 @@ export declare const AlignmentType: {
     readonly LOW_KASHIDA: "lowKashida";
     /** Thai Language Justification */
     readonly THAI_DISTRIBUTE: "thaiDistribute";
-    /** Align Left */
+    /** Align Left: a paragraph stays on the left of the page even when it is `bidirectional` (right-to-left) */
     readonly LEFT: "left";
-    /** Align Right */
+    /** Align Right: a paragraph stays on the right of the page even when it is `bidirectional` (right-to-left) */
     readonly RIGHT: "right";
     /** Justified */
     readonly JUSTIFIED: "both";
@@ -383,10 +383,13 @@ declare class Body_2 extends XmlComponent {
     /**
      * Section properties that were moved into a paragraph at the end of their section
      * by {@link addSection}, keyed by that paragraph. Used to find the section that
-     * governs a given child of the body.
+     * governs a given child of the body, and to write each section's properties into
+     * its paragraph while the body is written.
      */
     private readonly sectionParagraphs;
-    constructor();
+    private readonly headingBookmarkIds;
+    private readonly pageNumbers?;
+    constructor({ pageNumbers }?: IBodyOptions);
     /**
      * Finds the section properties that govern a top-level child of the body.
      *
@@ -403,8 +406,10 @@ declare class Body_2 extends XmlComponent {
     /**
      * Adds new section properties to the document body.
      *
-     * Creates a new section by moving the previous section's properties into a paragraph
-     * at the end of that section, and then adding the new section as the current section.
+     * Creates a new section by moving the previous section's properties into the last
+     * paragraph of that section, and then adding the new section as the current section.
+     * When that section doesn't end with a paragraph of its own (it ends with a table, or
+     * it is empty), an empty paragraph is added to hold its properties.
      *
      * According to the OOXML specification:
      * - Section properties for all sections except the last must be stored in a paragraph's
@@ -418,7 +423,11 @@ declare class Body_2 extends XmlComponent {
      * Prepares the body element for XML serialization.
      *
      * Ensures that the last section's properties are placed as a direct child of the body
-     * element, as required by the OOXML specification.
+     * element, as required by the OOXML specification. Once the body is written, its tables
+     * of contents are filled in from its headings, and, when the body has a page number
+     * estimator, its page references are given their page numbers. Its SEQ fields are given
+     * their numbers after the tables of contents are filled in, as Word leaves a heading's SEQ
+     * number out of its entry.
      *
      * @param context - The XML serialization context
      * @returns The prepared XML object or undefined
@@ -433,6 +442,18 @@ declare class Body_2 extends XmlComponent {
      * @param component - The XML component to add (paragraph, table, etc.)
      */
     push(component: XmlComponent): void;
+    /**
+     * The paragraph the current section ends with, which can hold its properties.
+     *
+     * There is none when the section ends with something other than a paragraph, or is empty:
+     * its last child is then the placeholder at the start of the body (removed when the body is
+     * written) or the paragraph that ends the section before, which has properties of its own.
+     */
+    private lastParagraphOfSection;
+    /**
+     * An empty paragraph to end a section that has no paragraph of its own to end it. The section's
+     * properties are written into it with the others, when the body is written.
+     */
     private createSectionParagraph;
 }
 export { Body_2 as Body }
@@ -482,13 +503,21 @@ export declare class Bookmark {
     readonly children: readonly ParagraphChild[];
     readonly end: BookmarkEnd;
     constructor(options: IBookmarkOptions);
+    /**
+     * The components written in this bookmark's place: its start, its children and its end. A bookmark in its
+     * children is written the same way, so one bookmark can hold another.
+     *
+     * @internal
+     */
+    get writtenAs(): readonly (ParagraphChild | BookmarkStart | BookmarkEnd)[];
 }
 
 /**
  * Represents the end marker of a bookmark range.
  *
  * This element marks the end of a bookmarked region in the document.
- * It must be paired with a corresponding BookmarkStart element with the same id.
+ * It must be paired with a corresponding BookmarkStart element with the same id,
+ * taken from `bookmarkUniqueNumericId` (see `BookmarkStart`).
  *
  * Reference: http://officeopenxml.com/WPbookmark.php
  *
@@ -507,7 +536,9 @@ export declare class Bookmark {
  *
  * @example
  * ```typescript
- * new BookmarkEnd(1);
+ * const id = bookmarkUniqueNumericId();
+ * new BookmarkStart("myBookmark", id);
+ * new BookmarkEnd(id);
  * ```
  */
 export declare class BookmarkEnd extends XmlComponent {
@@ -520,6 +551,10 @@ export declare class BookmarkEnd extends XmlComponent {
  * This element marks the beginning of a bookmarked region in the document.
  * It must be paired with a corresponding BookmarkEnd element with the same id.
  *
+ * The id must be unique in the document. `Bookmark` takes its ids from
+ * `bookmarkUniqueNumericId`, so take this one from it too, or it can be the
+ * same as a `Bookmark`'s.
+ *
  * Reference: http://officeopenxml.com/WPbookmark.php
  *
  * ## XSD Schema
@@ -537,7 +572,10 @@ export declare class BookmarkEnd extends XmlComponent {
  *
  * @example
  * ```typescript
- * new BookmarkStart("myBookmark", 1);
+ * // A bookmark across two paragraphs
+ * const id = bookmarkUniqueNumericId();
+ * new Paragraph({ children: [new BookmarkStart("myBookmark", id), new TextRun("First")] });
+ * new Paragraph({ children: [new TextRun("Last"), new BookmarkEnd(id)] });
  * ```
  */
 export declare class BookmarkStart extends XmlComponent {
@@ -1181,6 +1219,11 @@ export declare class Comments extends XmlComponent {
     get CommentIdsData(): readonly ICommentIdData[] | undefined;
     /** Whether there are no comments, in which case the document has no comments.xml part. */
     get IsEmpty(): boolean;
+    /**
+     * Formats the comments, with the page numbers worked out for their document written into their fields, when the
+     * document's body is written with an estimate of its pages.
+     */
+    prepForXml(context: IContext): IXmlableObject | undefined;
 }
 
 /**
@@ -1264,7 +1307,26 @@ declare const CompoundLine: {
  */
 export declare class ConcreteHyperlink extends XmlComponent {
     readonly linkId: string;
-    constructor(children: readonly ParagraphChild[], relationshipId: string, anchor?: string);
+    private readonly drawingLink?;
+    /**
+     * @param children - Inline content of the hyperlink
+     * @param relationshipId - Id of the external relationship, without the rId prefix
+     * @param anchor - Bookmark name or external URL fragment
+     * @param externalLink - The full address of an external hyperlink, so the relationship id is kept alongside its anchor
+     */
+    constructor(children: readonly ParagraphChild[], relationshipId: string, anchor?: string, externalLink?: string);
+    /**
+     * Creates the `a:hlinkClick` of a picture in the hyperlink, which links to the same address.
+     *
+     * The hyperlink decides which relationship its pictures use, rather than the pictures reading `linkId`, because only it
+     * knows whether that relationship has lost the fragment to `w:anchor`. The picture's relationship is added as the
+     * picture is written, through the context's relationships, so it lands in the part the picture is in, both when
+     * packing and when patching.
+     *
+     * @param context - The context the picture is written in, whose relationships get the picture's link if it has its own
+     * @param declareNamespace - Declares the DrawingML namespace, for elements outside `a:graphic` such as `wp:docPr`
+     */
+    createDrawingClick(context: IContext, declareNamespace: boolean): XmlComponent;
 }
 
 /**
@@ -1462,7 +1524,7 @@ declare type CoreGroupOptions = {
  * it: use it instead of alternative text for images that carry no information, such as borders and flourishes.
  */
 declare type CoreImageOptions = DrawingLinkOptions & {
-    /** Size, position, rotation, and flip settings for the image. Width and height are specified in pixels. */
+    /** Size, position, rotation, and flip settings for the image. Width and height are in pixels, at 96 to the inch, not EMUs. */
     readonly transformation: IMediaTransformation;
     /** Floating layout options. When set, the image is positioned freely on the page rather than inline with text. Controls text wrapping, overlap, anchoring, and z-order. */
     readonly floating?: IFloating;
@@ -1691,6 +1753,57 @@ export declare const createDotEmphasisMark: () => XmlComponent;
  */
 export declare const createEmphasisMark: (emphasisMarkType?: (typeof EmphasisMarkType)[keyof typeof EmphasisMarkType]) => XmlComponent;
 
+/**
+ * Creates the endnote properties (endnotePr) of a section.
+ *
+ * ## XSD Schema
+ * ```xml
+ * <xsd:complexType name="CT_EdnProps">
+ *   <xsd:sequence>
+ *     <xsd:element name="pos" type="CT_EdnPos" minOccurs="0"/>
+ *     <xsd:element name="numFmt" type="CT_NumFmt" minOccurs="0"/>
+ *     <xsd:group ref="EG_FtnEdnNumProps" minOccurs="0"/>
+ *   </xsd:sequence>
+ * </xsd:complexType>
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Endnotes at the end of the document, numbered 001, 002, 003
+ * createEndnoteProperties({
+ *   position: EndnotePosition.DOCUMENT_END,
+ *   numberFormat: { type: NumberFormat.CUSTOM, format: "001" },
+ * });
+ * ```
+ */
+export declare const createEndnoteProperties: (options: IEndnotePropertiesOptions) => XmlComponent;
+
+/**
+ * Creates the footnote properties (footnotePr) of a section.
+ *
+ * ## XSD Schema
+ * ```xml
+ * <xsd:complexType name="CT_FtnProps">
+ *   <xsd:sequence>
+ *     <xsd:element name="pos" type="CT_FtnPos" minOccurs="0"/>
+ *     <xsd:element name="numFmt" type="CT_NumFmt" minOccurs="0"/>
+ *     <xsd:group ref="EG_FtnEdnNumProps" minOccurs="0"/>
+ *   </xsd:sequence>
+ * </xsd:complexType>
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Footnotes at the end of the section, numbered a, b, c and restarting in each section
+ * createFootnoteProperties({
+ *   position: FootnotePosition.SECTION_END,
+ *   numberFormat: { type: NumberFormat.LOWER_LETTER },
+ *   restart: NoteNumberRestart.EACH_SECTION,
+ * });
+ * ```
+ */
+export declare const createFootnoteProperties: (options: IFootnotePropertiesOptions) => XmlComponent;
+
 /**
  * Creates a frame properties XML component for paragraph text frames.
  *
@@ -2123,7 +2236,7 @@ export declare const createPageMargin: (top: number | UniversalMeasure, right: n
  * });
  * ```
  */
-export declare const createPageNumberType: ({ start, formatType, separator }: IPageNumberTypeAttributes) => XmlComponent;
+export declare const createPageNumberType: ({ start, formatType, separator, chapterHeadingLevel }: IPageNumberTypeAttributes) => XmlComponent;
 
 /**
  * This element specifies the properties (size and orientation) for all pages in the current section.
@@ -3371,6 +3484,23 @@ export declare type EffectExtentAttributes = {
  */
 export declare const eighthPointMeasureValue: (val: number) => number;
 
+/**
+ * A font file the document embeds: one face of one of its fonts, with the unique key it is obfuscated with.
+ *
+ * @property name - Font family name
+ * @property data - Font file data of the face
+ * @property bold - Whether the face is bold
+ * @property italic - Whether the face is italic
+ * @property fontKey - Unique key (GUID) the file is obfuscated with
+ */
+declare type EmbeddedFontFile = {
+    readonly name: string;
+    readonly data: Buffer;
+    readonly bold: boolean;
+    readonly italic: boolean;
+    readonly fontKey: string;
+};
+
 /**
  * A file of a package that is embedded in the document, such as a sheet of an embedded workbook.
  */
@@ -3456,6 +3586,28 @@ export declare class EndnoteIdReference extends XmlComponent {
     constructor(id: number);
 }
 
+/**
+ * Where the endnotes of a section are placed.
+ *
+ * ## XSD Schema
+ * ```xml
+ * <xsd:simpleType name="ST_EdnPos">
+ *   <xsd:restriction base="xsd:string">
+ *     <xsd:enumeration value="sectEnd"/>
+ *     <xsd:enumeration value="docEnd"/>
+ *   </xsd:restriction>
+ * </xsd:simpleType>
+ * ```
+ *
+ * @publicApi
+ */
+export declare const EndnotePosition: {
+    /** At the end of the section */
+    readonly SECTION_END: "sectEnd";
+    /** At the end of the document */
+    readonly DOCUMENT_END: "docEnd";
+};
+
 /**
  * Represents a reference to an endnote.
  *
@@ -3480,6 +3632,11 @@ export declare class EndnoteReferenceRunAttributes extends XmlAttributeComponent
 export declare class Endnotes extends XmlComponent {
     constructor();
     createEndnote(id: number, paragraph: readonly Paragraph[]): void;
+    /**
+     * Formats the endnotes, with the page numbers worked out for their document written into their fields, when the
+     * document's body is written with an estimate of its pages.
+     */
+    prepForXml(context: IContext): IXmlableObject | undefined;
 }
 
 declare class EndnotesWrapper implements IViewWrapper {
@@ -3490,12 +3647,57 @@ declare class EndnotesWrapper implements IViewWrapper {
     get Relationships(): Relationships;
 }
 
+/**
+ * The page each bookmark of a document starts on, and the number of pages of the document and of each of its sections,
+ * as a {@link PageNumberEstimator} works them out.
+ *
+ * @publicApi
+ */
+export declare type EstimatedPageNumbers = {
+    /**
+     * The number of the page each bookmark starts on, as the page shows it, such as `"3"` or `"iv"`, by the bookmark's
+     * name. The page references to a bookmark that isn't in it are left blank.
+     */
+    readonly bookmarks: ReadonlyMap<string, string>;
+    /** The number of pages of the document, which its NUMPAGES fields show. They are left blank without it */
+    readonly pageCount?: number;
+    /**
+     * The number of pages of each of the document's sections, in order, which the SECTIONPAGES fields in the section, and
+     * in headers and footers only on its pages, show. Those of a section whose number is undefined are left blank.
+     */
+    readonly sectionPageCounts?: readonly (number | undefined)[];
+    /**
+     * The number of the page each bookmark starts on, as a number, such as 4, by the bookmark's name, which the page
+     * references to it with a number format of their own write in that format: `PAGEREF Results \* roman` writes "iv".
+     * Those to a bookmark that isn't in it are left blank.
+     */
+    readonly bookmarkPageNumbers?: ReadonlyMap<string, number>;
+    /**
+     * What each page reference with `\p` (`useRelativePosition`) in the body writes, by the name of the bookmark it
+     * refers to, in the order they are in the body: "above" or "below" when it is on the same page as the bookmark, and
+     * "on page" and the bookmark's page otherwise, such as "on page 4". Those it has nothing for are left blank, as are
+     * those in headers, footers and notes.
+     */
+    readonly relativePositions?: ReadonlyMap<string, readonly (string | undefined)[]>;
+    /**
+     * Where the estimator guessed, when it was asked to lay out past what it can't lay out as Word does, as
+     * `estimatePageNumbersWith({ guess: true })` from `docx/layout` is, in the order of the pages. The page numbers from
+     * the first of them on may not be Word's. Nothing of them is written into the document.
+     */
+    readonly guesses?: readonly PageNumberGuess[];
+};
+
 /**
  * Represents an external hyperlink to a URL outside the document.
  *
  * External hyperlinks create a relationship to an external resource (URL).
  * The relationship is created during document preparation and the hyperlink
  * is converted to a ConcreteHyperlink with the relationship ID.
+ * URL fragments of at most 255 UTF-16 units are written as anchors, preserving any additional # characters.
+ * Longer fragments stay in the original relationship URI to avoid exceeding Word's anchor limit;
+ * those links retain the existing limitations for fragments with multiple # characters.
+ * Word appends the anchor to the relationship target as described in MS-OI29500 §17.16.22:
+ * https://learn.microsoft.com/en-us/openspecs/office_standards/ms-oi29500/df06e423-11a6-4a36-bfb3-82139e531781
  *
  * Reference: http://officeopenxml.com/WPhyperlink.php
  *
@@ -3509,6 +3711,7 @@ declare class EndnotesWrapper implements IViewWrapper {
  *   <xsd:group ref="EG_PContent" minOccurs="0" maxOccurs="unbounded"/>
  *   <xsd:attribute ref="r:id"/>
  *   <xsd:attribute name="history" type="s:ST_OnOff" use="optional"/>
+ *   <xsd:attribute name="anchor" type="s:ST_String" use="optional"/>
  * </xsd:complexType>
  * ```
  *
@@ -3713,20 +3916,54 @@ declare type FilePatch = {
     readonly children: readonly FileChild[];
 };
 
+/**
+ * Writes the page numbers the estimator works out into the fields of a formatted body that show them: the PAGEREF fields
+ * in its tables of contents and elsewhere, those with `\p` and in number formats of their own, and its NUMPAGES and
+ * SECTIONPAGES fields. A field whose number the estimator didn't work out is left as it is. Page references and tables
+ * of contents are written clean, whether or not their numbers were worked out. The estimate is kept for the document's
+ * headers and footers.
+ */
+export declare const fillPageNumbers: (body: IXmlableObject, context: IContext, estimator: PageNumberEstimator) => void;
+
+/**
+ * Writes the page numbers worked out for the document a header, footer, footnote, endnote or comment is in into the
+ * fields of the formatted part that show them, once the document's body is written. Its page references and SEQ fields
+ * are written clean, and its SEQ fields are left blank: Word writes them as an error, "Error! Main Document Only.".
+ *
+ * @param part - The formatted part, if it has anything to write
+ * @param context - The context it was formatted in, with the document it is in
+ * @param referenceId - The number of the relationship to a header or footer. The SECTIONPAGES fields of the other parts
+ * are left as they are
+ */
+export declare const fillPartPageNumbers: (part: IXmlableObject | undefined, context: IContext, referenceId?: number) => void;
+
+/**
+ * Writes the numbers of the SEQ fields of a formatted body into them, counted as Word counts them (see
+ * {@link sequenceNumbering}), and writes them clean, whether or not their numbers were worked out. It is done after its
+ * tables of contents are filled in from its headings, as Word leaves a heading's SEQ number out of its entry.
+ */
+export declare const fillSequenceNumbers: (body: IXmlableObject, context: IContext) => void;
+
 /**
  * Options for embedding a font in the document.
  */
 declare type FontOptions = {
     /** Font family name */
     readonly name: string;
-    /** Font file data (TTF, OTF, etc.) */
+    /** Font file data (TTF, OTF, etc.) of the regular face */
     readonly data: Buffer;
+    /** Font file data of the bold face, embedded as `w:embedBold` */
+    readonly bold?: Buffer;
+    /** Font file data of the italic face, embedded as `w:embedItalic` */
+    readonly italic?: Buffer;
+    /** Font file data of the bold italic face, embedded as `w:embedBoldItalic` */
+    readonly boldItalic?: Buffer;
     /** Character set/encoding for the font */
     readonly characterSet?: (typeof CharacterSet)[keyof typeof CharacterSet];
 };
 
 /**
- * Font options extended with a unique font key.
+ * Font options extended with the unique key of the regular face's file.
  */
 declare type FontOptionsWithKey = FontOptions & {
     readonly fontKey: string;
@@ -3736,12 +3973,13 @@ declare type FontOptionsWithKey = FontOptions & {
  * Wrapper class for managing the font table and its relationships.
  *
  * Creates a font table with embedded font files and manages the relationships
- * required for font embedding. Each font is assigned a unique key for obfuscation.
+ * required for font embedding. Each face of a font is embedded as a file of its own,
+ * with a unique key for obfuscation.
  *
  * @example
  * ```typescript
  * const fontWrapper = new FontWrapper([
- *   { name: "CustomFont", data: fontBuffer }
+ *   { name: "CustomFont", data: fontBuffer, bold: boldFontBuffer }
  * ]);
  * ```
  */
@@ -3749,7 +3987,10 @@ declare class FontWrapper implements IViewWrapper {
     readonly options: readonly FontOptions[];
     private readonly fontTable;
     private readonly relationships;
+    /** @deprecated Use `files`, which has the file and key of each face a font embeds, not only the regular face's key */
     readonly fontOptionsWithKey: readonly FontOptionsWithKey[];
+    /** The files of the faces the fonts embed, in order: the Nth is `fonts/font<N>.odttf`, with the relationship `rId<N>` */
+    readonly files: readonly EmbeddedFontFile[];
     constructor(options: readonly FontOptions[]);
     get View(): XmlComponent;
     get Relationships(): Relationships;
@@ -3820,6 +4061,11 @@ declare class Footer_2 extends InitializableXmlComponent {
     constructor(referenceNumber: number, initContent?: XmlComponent);
     get ReferenceId(): number;
     add(item: Paragraph | Table): void;
+    /**
+     * Formats the footer, with the page numbers worked out for its document written into its fields, when the document's
+     * body is written with an estimate of its pages.
+     */
+    prepForXml(context: IContext): IXmlableObject | undefined;
 }
 
 /**
@@ -3852,6 +4098,34 @@ export declare class FooterWrapper implements IViewWrapper {
     get Media(): Media;
 }
 
+/**
+ * Where the footnotes of a section are placed.
+ *
+ * ## XSD Schema
+ * ```xml
+ * <xsd:simpleType name="ST_FtnPos">
+ *   <xsd:restriction base="xsd:string">
+ *     <xsd:enumeration value="pageBottom"/>
+ *     <xsd:enumeration value="beneathText"/>
+ *     <xsd:enumeration value="sectEnd"/>
+ *     <xsd:enumeration value="docEnd"/>
+ *   </xsd:restriction>
+ * </xsd:simpleType>
+ * ```
+ *
+ * @publicApi
+ */
+export declare const FootnotePosition: {
+    /** At the bottom of each page */
+    readonly PAGE_BOTTOM: "pageBottom";
+    /** Directly below the text on each page */
+    readonly BENEATH_TEXT: "beneathText";
+    /** At the end of the section */
+    readonly SECTION_END: "sectEnd";
+    /** At the end of the document */
+    readonly DOCUMENT_END: "docEnd";
+};
+
 /**
  * Represents a footnote reference element in WordprocessingML.
  *
@@ -3977,6 +4251,11 @@ export declare class FootNotes extends XmlComponent {
      * @param paragraph - Array of paragraphs that make up the footnote content
      */
     createFootNote(id: number, paragraph: readonly Paragraph[]): void;
+    /**
+     * Formats the footnotes, with the page numbers worked out for their document written into their fields, when the
+     * document's body is written with an estimate of its pages.
+     */
+    prepForXml(context: IContext): IXmlableObject | undefined;
 }
 
 /**
@@ -4168,6 +4447,11 @@ declare class Header_2 extends InitializableXmlComponent {
     constructor(referenceNumber: number, initContent?: XmlComponent);
     get ReferenceId(): number;
     add(item: Paragraph | Table): void;
+    /**
+     * Formats the header, with the page numbers worked out for its document written into its fields, when the document's
+     * body is written with an estimate of its pages.
+     */
+    prepForXml(context: IContext): IXmlableObject | undefined;
 }
 
 /**
@@ -4596,10 +4880,10 @@ declare type IBaseFrameOptions = {
     readonly anchorLock?: boolean;
     /** Drop cap effect type */
     readonly dropCap?: (typeof DropCapType)[keyof typeof DropCapType];
-    /** Frame width in twips */
-    readonly width: number;
-    /** Frame height in twips */
-    readonly height: number;
+    /** Frame width in twips. When omitted, the frame is as wide as its content. */
+    readonly width?: number;
+    /** Frame height in twips. When omitted, the frame is as tall as its content. */
+    readonly height?: number;
     /** Text wrapping behavior around the frame */
     readonly wrap?: (typeof FrameWrap)[keyof typeof FrameWrap];
     /** Number of lines for drop cap effect */
@@ -4635,6 +4919,14 @@ export declare type IBaseParagraphStyleOptions = {
     readonly run?: IRunStylePropertiesOptions;
 } & IStyleOptions;
 
+/**
+ * Options for the body of a document.
+ */
+export declare type IBodyOptions = {
+    /** Works out the page each bookmark is on, to write the page numbers of page references. See {@link PageNumberEstimator} */
+    readonly pageNumbers?: PageNumberEstimator;
+};
+
 export declare type IBodyPropertiesOptions = {
     readonly wrap?: (typeof TextWrappingType)[keyof typeof TextWrappingType];
     readonly verticalAnchor?: VerticalAnchor;
@@ -5280,12 +5572,15 @@ export declare type IDocumentHeader = {
  * Options for creating a Document element.
  *
  * @property background - Optional background settings for the document
+ * @property pageNumbers - Works out the page each bookmark is on, to write the page numbers of page references
  *
  * @see {@link Document}
  */
 export declare type IDocumentOptions = {
     /** Optional background settings for the document */
     readonly background?: IDocumentBackgroundOptions;
+    /** Works out the page each bookmark is on, to write the page numbers of page references. See {@link PageNumberEstimator} */
+    readonly pageNumbers?: PageNumberEstimator;
 };
 
 /**
@@ -5303,6 +5598,19 @@ export declare type IDrawingOptions = DrawingLinkOptions & {
     readonly effectExtent?: EffectExtentAttributes;
 };
 
+/**
+ * Endnote settings of a section.
+ *
+ * @property position - Where the endnotes are placed
+ * @property numberFormat - Number format of the endnotes
+ * @property start - Number of the first endnote
+ * @property restart - When the numbering restarts
+ */
+export declare type IEndnotePropertiesOptions = INotePropertiesBaseOptions & {
+    /** Where the endnotes are placed */
+    readonly position?: (typeof EndnotePosition)[keyof typeof EndnotePosition];
+};
+
 export declare type IExtendedMediaData = IMediaData | WpsMediaData | WpgMediaData | GraphicMediaData;
 
 /**
@@ -5362,6 +5670,19 @@ declare type IFontOptions = {
     readonly hint?: string;
 };
 
+/**
+ * Footnote settings of a section.
+ *
+ * @property position - Where the footnotes are placed
+ * @property numberFormat - Number format of the footnotes
+ * @property start - Number of the first footnote
+ * @property restart - When the numbering restarts
+ */
+export declare type IFootnotePropertiesOptions = INotePropertiesBaseOptions & {
+    /** Where the footnotes are placed */
+    readonly position?: (typeof FootnotePosition)[keyof typeof FootnotePosition];
+};
+
 /**
  * Union type for all frame positioning options.
  *
@@ -5945,8 +6266,9 @@ export declare type IMediaTransformation = {
         readonly top?: number;
         readonly left?: number;
     };
+    /** Display width in pixels, at 96 to the inch, not EMUs. Word won't open a drawing more than 225457 pixels wide */
     readonly width: number;
-    /** Display height in pixels */
+    /** Display height in pixels, at 96 to the inch, not EMUs. Word won't open a drawing more than 225457 pixels tall */
     readonly height: number;
     /** Optional flip transformations */
     readonly flip?: {
@@ -6080,6 +6402,28 @@ declare type INonVisualShapePropertiesOptions = {
     readonly txBox: string;
 };
 
+/**
+ * Number format of the footnotes or endnotes of a section.
+ *
+ * @property type - Number format (decimal, roman, letter, etc.)
+ * @property format - Pattern used with `NumberFormat.CUSTOM`, such as "001"
+ */
+export declare type INoteNumberFormatOptions = {
+    /** Number format (decimal, roman, letter, etc.) */
+    readonly type: (typeof NumberFormat)[keyof typeof NumberFormat];
+    /** Pattern used with `NumberFormat.CUSTOM`, such as "001" */
+    readonly format?: string;
+};
+
+declare type INotePropertiesBaseOptions = {
+    /** Number format of the notes */
+    readonly numberFormat?: INoteNumberFormatOptions;
+    /** Number of the first note */
+    readonly start?: number;
+    /** When the numbering restarts */
+    readonly restart?: (typeof NoteNumberRestart)[keyof typeof NoteNumberRestart];
+};
+
 /**
  * Supported input data types for document patching.
  *
@@ -6296,6 +6640,7 @@ export declare type IPageMarginAttributes = {
  * @property start - Starting page number for the section
  * @property formatType - Number format (decimal, roman, letter, etc.)
  * @property separator - Separator between chapter and page number
+ * @property chapterHeadingLevel - The level of the headings whose numbers are the chapter numbers
  */
 export declare type IPageNumberTypeAttributes = {
     /** Starting page number for the section */
@@ -6304,6 +6649,12 @@ export declare type IPageNumberTypeAttributes = {
     readonly formatType?: (typeof NumberFormat)[keyof typeof NumberFormat];
     /** Separator between chapter and page number (default: hyphen) */
     readonly separator?: (typeof PageNumberSeparator)[keyof typeof PageNumberSeparator];
+    /**
+     * Puts the chapter number before each page number, such as "2-5" for page 5 of chapter 2. The chapter number is the
+     * number of the last heading of this level (1 to 9, for `HeadingLevel.HEADING_1` to `HEADING_9`), so those headings
+     * must be numbered through their style (`w:chapStyle`)
+     */
+    readonly chapterHeadingLevel?: number;
 };
 
 /**
@@ -6444,7 +6795,11 @@ export declare type IParagraphPropertiesOptions = {
 export declare type IParagraphPropertiesOptionsBase = {
     /** Heading level (Heading1, Heading2, etc.) - applies predefined heading style */
     readonly heading?: (typeof HeadingLevel)[keyof typeof HeadingLevel];
-    /** Whether to render text right-to-left for bidirectional languages */
+    /**
+     * Whether to lay the paragraph out right-to-left, for languages such as Arabic and Hebrew.
+     * A right-to-left paragraph starts on the right of the page, so it is right-aligned unless `alignment` says otherwise.
+     * `alignment` `LEFT` and `RIGHT` still mean those sides of the page, while `START` and `END` follow the paragraph's direction.
+     */
     readonly bidirectional?: boolean;
     /** Whether to insert a page break before this paragraph */
     readonly pageBreakBefore?: boolean;
@@ -6557,6 +6912,7 @@ export declare type IPatch = ParagraphPatch | FilePatch;
  * @property fonts - Font configurations
  * @property hyphenation - Hyphenation settings
  * @property theme - The document's theme: its colors, and its fonts for headings and body text
+ * @property pageNumbers - Works out the page each bookmark is on, so the page numbers of tables of contents and page references are written with the document
  */
 export declare type IPropertiesOptions = {
     readonly sections: readonly ISectionOptions[];
@@ -6594,6 +6950,12 @@ export declare type IPropertiesOptions = {
      * from Office 2016 to 2021 unless the options change it
      */
     readonly theme?: IThemeOptions;
+    /**
+     * Works out the page each bookmark is on, so the page numbers of the document's tables of contents and page
+     * references are written with it, rather than left blank until Word updates them. Give it `estimatePageNumbers`
+     * from `docx/layout`, which lays out the document's pages as Word would
+     */
+    readonly pageNumbers?: PageNumberEstimator;
 };
 
 /**
@@ -6747,6 +7109,8 @@ export declare type ISectionPropertiesChangeOptions = IChangedAttributesProperti
  * @property verticalAlign - Vertical alignment of text on page
  * @property column - Column layout settings
  * @property type - Section break type (next page, continuous, etc.)
+ * @property footnoteProperties - Footnote placement and numbering
+ * @property endnoteProperties - Endnote placement and numbering
  *
  * @see {@link SectionProperties}
  */
@@ -6784,6 +7148,10 @@ export declare type ISectionPropertiesOptionsBase = {
     readonly column?: IColumnsAttributes;
     /** Section break type (next page, continuous, even page, odd page) */
     readonly type?: (typeof SectionType)[keyof typeof SectionType];
+    /** Where the footnotes of the section are placed and how they are numbered */
+    readonly footnoteProperties?: IFootnotePropertiesOptions;
+    /** Where the endnotes of the section are placed and how they are numbered */
+    readonly endnoteProperties?: IEndnotePropertiesOptions;
 };
 
 /**
@@ -6800,6 +7168,8 @@ declare type ISettingsOptions = {
     readonly trackRevisions?: boolean;
     /** Update fields when document is opened */
     readonly updateFields?: boolean;
+    /** Keep the document's embedded fonts when it is saved again, as Word's "Embed fonts in the file" option does */
+    readonly embedFonts?: boolean;
     /** Compatibility settings for older Word versions */
     readonly compatibility?: ICompatibilityOptions;
     /** Default distance between tab stops in twips */
@@ -6821,6 +7191,14 @@ export declare type IShadingAttributesProperties = {
     readonly type?: (typeof ShadingType)[keyof typeof ShadingType];
 };
 
+/**
+ * Options for a simple field.
+ */
+export declare type ISimpleFieldOptions = {
+    /** Locks the field so Word keeps the cached value when fields are updated. Not locked by default. */
+    readonly locked?: boolean;
+};
+
 /**
  * Properties for configuring paragraph spacing.
  *
@@ -6923,9 +7301,9 @@ export declare type IStylesOptions = {
     readonly default?: IDefaultStylesOptions;
     /** Initial base XML component for styles root element */
     readonly initialStyles?: BaseXmlComponent;
-    /** Array of custom paragraph style definitions */
+    /** Array of custom paragraph style definitions. Each takes the place of a default or external style with its id */
     readonly paragraphStyles?: readonly IParagraphStyleOptions[];
-    /** Array of custom character style definitions */
+    /** Array of custom character style definitions. Each takes the place of a default or external style with its id */
     readonly characterStyles?: readonly ICharacterStyleOptions[];
     /** Array of styles imported from external sources */
     readonly importedStyles?: readonly (XmlComponent | StyleForParagraph | StyleForCharacter | ImportedXmlComponent)[];
@@ -7353,8 +7731,10 @@ export declare type ITableOptions = {
      * Widths of the grid columns (`w:tblGrid`) in twips (twentieths of a point).
      *
      * Word treats the grid as a hint and lays the table out from `width` and the cells'
-     * widths, but Google Docs, Apple Pages and QuickLook lay the table out from the grid
-     * alone and ignore percentage widths. When omitted, the grid is derived from `width`
+     * widths, sizing columns whose cells have no width to their content, so each cell
+     * without a `width` of its own is given the width of the columns it spans, scaled up
+     * to the table's `width` when that is wider. Google Docs, Apple Pages and QuickLook
+     * lay the table out from the grid alone and ignore percentage widths. When omitted, the grid is derived from `width`
      * and the cells' widths, resolved against the page (or, for nested tables, the
      * parent cell) when the document is packed, so the table renders the same in every
      * consumer. Supply explicit values to take full control of the grid.
@@ -7428,7 +7808,12 @@ export declare type ITableRowPropertiesOptions = ITableRowPropertiesOptionsBase
 export declare type ITableRowPropertiesOptionsBase = {
     /** Whether the row can be split across pages (cantSplit) */
     readonly cantSplit?: boolean;
-    /** Whether the row should be repeated as a header row on each page (tblHeader) */
+    /**
+     * Whether the row should be repeated as a header row on each page (tblHeader).
+     *
+     * Only the table's first row and the rows straight after it that also set this repeat. Word ignores it on
+     * any row further down, so to repeat a different header for each part of a table, make each part a table of its own.
+     */
     readonly tableHeader?: boolean;
     /** Row height configuration (trHeight) */
     readonly height?: {
@@ -9118,6 +9503,31 @@ export declare type NonVisualDrawingPropertiesOptions = DrawingLinkOptions & {
     readonly title?: string;
 };
 
+/**
+ * When the footnote or endnote numbering restarts.
+ *
+ * ## XSD Schema
+ * ```xml
+ * <xsd:simpleType name="ST_RestartNumber">
+ *   <xsd:restriction base="xsd:string">
+ *     <xsd:enumeration value="continuous"/>
+ *     <xsd:enumeration value="eachSect"/>
+ *     <xsd:enumeration value="eachPage"/>
+ *   </xsd:restriction>
+ * </xsd:simpleType>
+ * ```
+ *
+ * @publicApi
+ */
+export declare const NoteNumberRestart: {
+    /** Numbering never restarts */
+    readonly CONTINUOUS: "continuous";
+    /** Numbering restarts in each section */
+    readonly EACH_SECTION: "eachSect";
+    /** Numbering restarts on each page */
+    readonly EACH_PAGE: "eachPage";
+};
+
 /**
  * Creates a field/cross reference to a numbered item in the document.
  *
@@ -9259,6 +9669,7 @@ export declare const NumberFormat: {
     readonly THAI_COUNTING: "thaiCounting";
     readonly BAHT_TEXT: "bahtText";
     readonly DOLLAR_TEXT: "dollarText";
+    readonly CUSTOM: "custom";
 };
 
 /**
@@ -9652,6 +10063,7 @@ export declare class PackagePart {
     private readonly addedTo;
     /**
      * @throws If the folder isn't a single folder name, or is one of the folders docx writes parts of its own in
+     * @throws If the name or the extension isn't a single part of a file name, which could lead out of the folder
      */
     constructor(options: PackagePartOptions);
     /**
@@ -9696,7 +10108,7 @@ declare class PackageParts {
     /**
      * @param contentTypes - Where each part's content type is added
      * @param existingPaths - The paths under word/ of the parts the package already has, such as a template's charts,
-     * which new parts are numbered after
+     * which new parts don't take
      */
     constructor(contentTypes: Pick<ContentTypes, "addOverride">, existingPaths?: ReadonlySet<string>);
     /**
@@ -10010,6 +10422,32 @@ export declare class PageNumberElement extends EmptyElement {
     constructor();
 }
 
+/**
+ * Works out which page each bookmark of a document starts on, and how many pages the document and its sections have,
+ * from the body of the document as it is written, so the page numbers of its tables of contents, page references and
+ * page counts can be written with it.
+ *
+ * `estimatePageNumbers`, from `docx/layout`, is one. Give it to a document as its `pageNumbers`.
+ *
+ * @param body - The document's body, formatted to be written as XML
+ * @param context - The context the body was formatted in, with the document it is in
+ *
+ * @publicApi
+ */
+export declare type PageNumberEstimator = (body: IXmlableObject, context: IContext) => EstimatedPageNumbers;
+
+/**
+ * Where a {@link PageNumberEstimator} guessed at something it can't lay out as Word does.
+ *
+ * @publicApi
+ */
+export declare type PageNumberGuess = {
+    /** What it guessed at, as why it would have stopped there, such as `"a font not in the width tables"` */
+    readonly reason: string;
+    /** The page it guessed on, counted from 1 for the first page of the document, whatever number the page shows */
+    readonly page: number;
+};
+
 /**
  * Specifies the separator character between chapter number and page number.
  *
@@ -10037,7 +10475,7 @@ export declare const PageNumberSeparator: {
     readonly COLON: "colon";
     /** Em dash separator (—) */
     readonly EM_DASH: "emDash";
-    /** En dash separator (–) */
+    /** En dash separator (–), written as `enDash` */
     readonly EN_DASH: "endash";
 };
 
@@ -10080,6 +10518,10 @@ export declare const PageOrientation: {
  * The PAGEREF field displays the page number of the page containing
  * the specified bookmark, useful for cross-references like "see page 5".
  *
+ * It is written dirty, so Word fills in the page number when it opens the document, after asking to. When the
+ * document is given `pageNumbers`, it is written clean, with the number they work out, or blank when they couldn't,
+ * and Word doesn't ask.
+ *
  * @publicApi
  *
  * @example
@@ -10176,6 +10618,24 @@ export declare class Paragraph extends FileChild {
     private readonly properties;
     constructor(options: string | IParagraphOptions);
     prepForXml(context: IContext): IXmlableObject | undefined;
+    /**
+     * Ends a section at this paragraph by adding the section's properties to the paragraph's properties,
+     * as Word does with the last paragraph of each section but the last.
+     *
+     * The body adds them only while it is written and removes them afterwards with
+     * {@link removeSectionProperties}, so the same paragraph can be used in other documents.
+     *
+     * @internal
+     * @param sectionProperties - The properties of the section the paragraph ends
+     */
+    addSectionProperties(sectionProperties: SectionProperties): void;
+    /**
+     * Removes the section properties added with {@link addSectionProperties}.
+     *
+     * @internal
+     * @param sectionProperties - The properties of the section to remove
+     */
+    removeSectionProperties(sectionProperties: SectionProperties): void;
     addRunToFront(run: Run): Paragraph;
 }
 
@@ -10318,6 +10778,21 @@ export declare class ParagraphProperties extends IgnoreIfEmptyXmlComponent {
      * @param item - The XML component to add to the paragraph properties
      */
     push(item: XmlComponent): void;
+    /**
+     * Adds the section properties (`w:sectPr`) of the section this paragraph ends.
+     *
+     * They go after the paragraph's run properties and before its revision (`w:pPrChange`),
+     * the order CT_PPr gives them.
+     *
+     * @param sectionProperties - The properties of the section the paragraph ends
+     */
+    addSectionProperties(sectionProperties: SectionProperties): void;
+    /**
+     * Removes the section properties added with {@link addSectionProperties}.
+     *
+     * @param sectionProperties - The properties of the section to remove
+     */
+    removeSectionProperties(sectionProperties: SectionProperties): void;
     /**
      * Prepares the paragraph properties for XML serialization.
      *
@@ -10440,7 +10915,7 @@ declare type PatchDetectorOptions = {
  *
  * @publicApi
  */
-export declare const patchDocument: <T extends PatchDocumentOutputType = PatchDocumentOutputType>({ outputType, data, patches, keepOriginalStyles, placeholderDelimiters, recursive, }: PatchDocumentOptions<T>) => Promise<OutputByType[T]>;
+export declare const patchDocument: <T extends PatchDocumentOutputType = PatchDocumentOutputType>({ outputType, data, patches, keepOriginalStyles, placeholderDelimiters, recursive, footnotes, endnotes, pageNumbers, }: PatchDocumentOptions<T>) => Promise<OutputByType[T]>;
 
 /**
  * Options for patching a document.
@@ -10451,6 +10926,9 @@ export declare const patchDocument: <T extends PatchDocumentOutputType = PatchDo
  * @property keepOriginalStyles - Whether to preserve original text formatting
  * @property placeholderDelimiters - Custom delimiter characters for placeholders
  * @property recursive - Whether to replace every occurrence of a placeholder in a paragraph, rather than only the first
+ * @property footnotes - The footnotes that patches refer to with a `FootnoteReferenceRun`
+ * @property endnotes - The endnotes that patches refer to with an `EndnoteReferenceRun`
+ * @property pageNumbers - Works out the page each bookmark is on, to write the page numbers of page references
  */
 export declare type PatchDocumentOptions<T extends PatchDocumentOutputType = PatchDocumentOutputType> = {
     /** Output format type */
@@ -10458,10 +10936,10 @@ export declare type PatchDocumentOptions<T extends PatchDocumentOutputType = Pat
     /** Input document data */
     readonly data: InputDataType;
     /**
-     * Mapping of placeholder keys to patch content, or to a {@link DrawingPatch}, such as `docx/charts`' `ChartDataPatch`,
-     * for a drawing whose alt text holds the placeholder
+     * Mapping of placeholder keys to patch content, to a {@link TableRowsPatch} that repeats the rows of a table, or to a
+     * {@link DrawingPatch}, such as `docx/charts`' `ChartDataPatch`, for a drawing whose alt text holds the placeholder
      */
-    readonly patches: Readonly<Record<string, IPatch | DrawingPatch>>;
+    readonly patches: Readonly<Record<string, IPatch | TableRowsPatch | DrawingPatch>>;
     /** Preserve original formatting of replaced text (default: true) */
     readonly keepOriginalStyles?: boolean;
     /** Custom placeholder delimiters (default: {{ and }}) */
@@ -10471,6 +10949,23 @@ export declare type PatchDocumentOptions<T extends PatchDocumentOutputType = Pat
     }>;
     /** Replace every occurrence of a placeholder in a paragraph, rather than only the first (default: true) */
     readonly recursive?: boolean;
+    /**
+     * The footnotes that patches refer to, by the id given to their `FootnoteReferenceRun`s, as in a `Document`. Each
+     * reference a patch inserts gets a footnote of its own, with an id that none of the document's footnotes have
+     */
+    readonly footnotes?: Readonly<Record<string, {
+        readonly children: readonly Paragraph[];
+    }>>;
+    /** The endnotes that patches refer to, by the id given to their `EndnoteReferenceRun`s, as with footnotes */
+    readonly endnotes?: Readonly<Record<string, {
+        readonly children: readonly Paragraph[];
+    }>>;
+    /**
+     * Works out the page each bookmark of the patched document is on, and how many pages it has, so the page numbers of
+     * its tables of contents and page references, and its numbers of pages, are written with it, rather than left as they
+     * were in the template. Give it `estimatePageNumbers` from `docx/layout`. See {@link TemplatePageNumberEstimator}
+     */
+    readonly pageNumbers?: TemplatePageNumberEstimator;
 };
 
 /**
@@ -10478,6 +10973,27 @@ export declare type PatchDocumentOptions<T extends PatchDocumentOutputType = Pat
  */
 export declare type PatchDocumentOutputType = OutputType;
 
+/**
+ * A template once `patchDocument` has patched it, as a {@link TemplatePageNumberEstimator} reads it.
+ *
+ * @publicApi
+ */
+export declare type PatchedTemplate = {
+    /**
+     * Each XML part of the template's package, by its path in the package, such as "word/document.xml". Each is parsed as
+     * `patchDocument` parses it, with xml-js's `xml2js`, not compact, and keeping the spaces between elements
+     * (`captureSpacesBetweenElements`), as the spaces in a text element are its text
+     */
+    readonly parts: ReadonlyMap<string, Element_2>;
+    /** Each of its other parts, such as its pictures and the fonts it embeds, by its path in the package, as bytes */
+    readonly binaryParts?: ReadonlyMap<string, Uint8Array>;
+    /**
+     * Each .docx the template imports (`w:altChunk`), which Word turns into paragraphs and tables of the template's own
+     * when it opens it, unzipped and read as the template is, by its path in the template's package
+     */
+    readonly importedDocuments?: ReadonlyMap<string, PatchedTemplate>;
+};
+
 /**
  * Patch type enumeration.
  *
@@ -10490,6 +11006,11 @@ export declare const PatchType: {
     readonly DOCUMENT: "file";
     /** Replace content within paragraphs (inline replacement) */
     readonly PARAGRAPH: "paragraph";
+    /**
+     * Repeat the rows of a table that hold the placeholder's fields, such as `{{items.name}}`, once for each row of
+     * data. See {@link TableRowsPatch}
+     */
+    readonly TABLE_ROWS: "tableRows";
     /**
      * Change a drawing whose alt text holds the placeholder, and the parts it refers to, such as the data of a chart made
      * in Word. See {@link DrawingPatch}
@@ -10796,6 +11317,16 @@ declare class Relationships extends XmlComponent {
      * @param targetMode - Optional mode indicating if target is external
      */
     addRelationship(id: number | string, type: RelationshipType, target: string, targetMode?: (typeof TargetModeType)[keyof typeof TargetModeType]): void;
+    /**
+     * Creates a copy of the relationships given. Relationships added to the copy aren't added to them, so the compiler
+     * adds the ones it writes for a part, such as to its images, to a copy, and packing a document again doesn't add
+     * them a second time.
+     *
+     * Static, as `IContext` is public and has `Relationships`, so a new instance member would change the public API.
+     *
+     * @param relationships - The relationships to copy
+     */
+    static copy(relationships: Relationships): Relationships;
     /**
      * Gets the count of relationships in this collection.
      * Excludes the attributes element from the count.
@@ -11123,7 +11654,7 @@ export declare class SectionProperties extends XmlComponent {
      * the width of a single column. Percentage table widths are resolved against it.
      */
     private readonly availableTextWidth;
-    constructor({ page: { size: { width, height, orientation, code, }, margin: { top, right, bottom, left, header, footer, gutter, }, pageNumbers, borders, textDirection, }, grid: { linePitch, charSpace, type: gridType }, headerWrapperGroup, footerWrapperGroup, lineNumbers, titlePage, verticalAlign, column, type, revision, }?: ISectionPropertiesOptions);
+    constructor({ page: { size: { width, height, orientation, code, }, margin: { top, right, bottom, left, header, footer, gutter, }, pageNumbers, borders, textDirection, }, grid: { linePitch, charSpace, type: gridType }, headerWrapperGroup, footerWrapperGroup, lineNumbers, titlePage, verticalAlign, column, type, footnoteProperties, endnoteProperties, revision, }?: ISectionPropertiesOptions);
     /**
      * Width, in twips, available to block-level content (paragraphs and tables) in this section.
      *
@@ -11198,6 +11729,10 @@ export declare class Separator extends EmptyElement {
  * Each identifier maintains its own sequence, allowing you to have separate numbering
  * for figures, tables, equations, etc.
  *
+ * It is written dirty, so Word numbers it when it opens the document, after asking to update the fields. When the
+ * document is given `pageNumbers`, it is written clean, with its number counted as Word counts it, or blank where
+ * Word's count isn't known, and Word doesn't ask.
+ *
  * Reference: http://officeopenxml.com/WPrun.php
  *
  * @publicApi
@@ -11239,6 +11774,7 @@ export declare class SequentialIdentifier extends Run {
  * ```xml
  * <xsd:complexType name="CT_Settings">
  *   <xsd:sequence>
+ *     <xsd:element name="embedTrueTypeFonts" type="CT_OnOff" minOccurs="0"/>
  *     <xsd:element name="trackRevisions" type="CT_OnOff" minOccurs="0"/>
  *     <xsd:element name="defaultTabStop" type="CT_TwipsMeasure" minOccurs="0"/>
  *     <xsd:element name="autoHyphenation" type="CT_OnOff" minOccurs="0"/>
@@ -11426,10 +11962,13 @@ export declare const signedTwipsMeasureValue: (val: UniversalMeasure | number) =
  *
  * // Simple field with cached value
  * new SimpleField("DATE", "2024-01-01");
+ *
+ * // Locked field, Word keeps the cached value when fields are updated
+ * new SimpleField("DATE", "2024-01-01", { locked: true });
  * ```
  */
 export declare class SimpleField extends XmlComponent {
-    constructor(instruction: string, cachedValue?: string);
+    constructor(instruction: string, cachedValue?: string, options?: ISimpleFieldOptions);
 }
 
 /**
@@ -11902,6 +12441,13 @@ export declare class Table extends FileChild {
      * serializing.
      */
     prepForXml(context: IContext): IXmlableObject | undefined;
+    /**
+     * Gives each cell without a width of its own the width of the `columnWidths` it spans, as Word sizes the columns of
+     * cells without a width to their content, whatever the grid says. When the table's width is wider than the columns
+     * add up to, they are scaled up to fill it, as Word and LibreOffice lay them out, so columns given as proportions
+     * keep them.
+     */
+    private setCellWidths;
     /**
      * Finds the width in twips available to this table from the serialization context:
      * the parent cell for a nested table, otherwise the text width of the section the
@@ -11993,7 +12539,14 @@ export declare class TableCell extends XmlComponent {
     readonly options: WithHexColors<Omit<ITableCellOptions, "revision">> & {
         readonly revision?: WithHexColors<NonNullable<ITableCellOptions["revision"]>>;
     };
+    private readonly properties;
     constructor(options: ITableCellOptions);
+    /**
+     * Gives the cell, unless it has a width of its own, the width of the table's columns it spans, in twips.
+     *
+     * @internal
+     */
+    setColumnWidth(twips: number): void;
     prepForXml(context: IContext): IXmlableObject | undefined;
 }
 
@@ -12065,6 +12618,12 @@ export declare const TableLayoutType: {
  * TableOfContents creates an auto-generated list of document headings
  * with page numbers. It uses a TOC field code to generate entries.
  *
+ * Unless it is given `cachedEntries` or `contentChildren`, it is written with an
+ * entry for each heading its options include, linked to a bookmark on the heading,
+ * so it isn't empty before Word updates it or in applications that don't update it.
+ * The page numbers are left for Word to fill in when it updates the field, unless the document's `pageNumbers`
+ * writes them.
+ *
  * Reference: http://officeopenxml.com/WPtableOfContents.php
  *
  * @publicApi
@@ -12089,6 +12648,8 @@ export declare const TableLayoutType: {
  * ```
  */
 export declare class TableOfContents extends FileChild {
+    /** What it is filled in with from the headings, when it isn't given its content */
+    private readonly fromHeadings?;
     constructor(alias?: string, { contentChildren, cachedEntries, beginDirty, ...properties }?: ITableOfContentsOptions & {
         readonly contentChildren?: readonly (XmlComponent | string)[];
         /**
@@ -12097,8 +12658,20 @@ export declare class TableOfContents extends FileChild {
          * Note that indentation should come from the paragraph styles defined on the document. By default the styles are TOC1, TOC2, etc. These can be overridden with stylesWithLevels (\t)
          */
         readonly cachedEntries?: readonly ToCEntry[];
+        /**
+         * Whether the field is written dirty, so Word updates the table when it opens the document, after asking to.
+         * Default is dirty, unless the document is given `pageNumbers`: then it is written clean, so Word shows it as
+         * it is written, and doesn't ask.
+         */
         readonly beginDirty?: boolean;
     });
+    /**
+     * Written empty, and filled in from the headings once the body it is in is written, unless it was given its content.
+     * The page numbers are aligned to the right of the text in its section.
+     */
+    prepForXml(context: IContext): IXmlableObject | undefined;
+    /** The width of the text in the section it is in */
+    private textWidthIn;
     private getTabStopsForLevel;
     private buildCachedContentRun;
     private buildCachedContentParagraphChild;
@@ -12190,6 +12763,52 @@ export declare class TableRowPropertiesChange extends XmlComponent {
     constructor(options: ITableRowPropertiesChangeOptions);
 }
 
+/**
+ * Patch definition that repeats the rows of a table in the template, once for each row of data, so a table can be
+ * designed in Word and filled in with any number of rows.
+ *
+ * The rows it repeats are those that hold its fields: placeholders made of the patch's key, a dot and the field's name,
+ * such as `{{items.name}}` and `{{items.price}}` for the patch `items`. Each copy's fields are patched with a row's
+ * patches, by their field's name, and the other rows of the table, such as its header, are kept as they are. Rows next
+ * to each other are repeated together, such as a row for an item and a row for its notes.
+ *
+ * A field that a row has no patch for is left empty. With no rows, the rows are removed, and so is a table left with
+ * none. The other patches are applied after the rows are repeated, so a placeholder of theirs in a repeated row, such as
+ * `{{currency}}`, is patched in every copy.
+ *
+ * @example
+ * ```typescript
+ * const text = (value: string): IPatch => ({ type: PatchType.PARAGRAPH, children: [new TextRun(value)] });
+ *
+ * await patchDocument({
+ *   outputType: "nodebuffer",
+ *   data: template,
+ *   patches: {
+ *     items: {
+ *       type: PatchType.TABLE_ROWS,
+ *       rows: [
+ *         { name: text("Apples"), price: text("1.20") },
+ *         { name: text("Pears"), price: text("0.90") },
+ *       ],
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @publicApi
+ */
+export declare type TableRowsPatch = {
+    /** Indicates this patch repeats the rows of a table */
+    readonly type: typeof PatchType.TABLE_ROWS;
+    /**
+     * The patches for each copy of the rows, by the name of the field they patch, such as `name` for `{{items.name}}`.
+     * A field's patch can repeat rows of a table in the copy in turn, whose fields are then such as
+     * `{{items.parts.name}}`. When those fields are in the copy's own row, rather than in a table in it, the row is
+     * repeated for each part, with its item's fields, and an item without parts has no row
+     */
+    readonly rows: readonly Readonly<Record<string, IPatch | TableRowsPatch | undefined>>[];
+};
+
 export declare type TableVerticalAlign = (typeof VerticalAlignTable)[keyof typeof VerticalAlignTable];
 
 /**
@@ -12328,6 +12947,17 @@ export declare type TemplatePackage = {
     readonly format: (content: XmlComponent) => Element_2;
 };
 
+/**
+ * Works out which page each bookmark of a template starts on, and how many pages it and each of its sections have, once
+ * `patchDocument` has patched it, so the page numbers of its tables of contents and page references, and its numbers of
+ * pages, are written with it.
+ *
+ * `estimatePageNumbers`, from `docx/layout`, is one. Give it to `patchDocument` as its `pageNumbers`.
+ *
+ * @publicApi
+ */
+export declare type TemplatePageNumberEstimator = (template: PatchedTemplate) => EstimatedPageNumbers;
+
 /**
  * A part of a template's package, as a {@link DrawingPatch} sees it.
  *