docx 9.9.0 → 9.11.0

package/dist/index.d.cts

@@ -1307,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;
 }
 
 /**
@@ -3465,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.
  */
@@ -3581,8 +3617,33 @@ export declare class EndnoteReference extends EmptyElement {
     constructor();
 }
 
+/**
+ * A run with an endnote's reference mark, its number, in the document's text.
+ *
+ * It refers to one of the document's `endnotes` by its id, or is given its endnote's content, for an endnote of its
+ * own, which is added to the document's endnotes when the run is written.
+ *
+ * @publicApi
+ *
+ * @example
+ * ```typescript
+ * new Paragraph({
+ *   children: [new TextRun("A claim"), new EndnoteReferenceRun({ children: [new Paragraph("Its source.")] })],
+ * });
+ * ```
+ */
 export declare class EndnoteReferenceRun extends Run {
-    constructor(id: number);
+    private readonly endnote?;
+    /**
+     * @param endnote - The id of one of the document's `endnotes`, or the endnote's content, for an endnote of the run's
+     * own. Word has endnotes only in a document's body, so a run with its endnote's content is left out of headers,
+     * footers, comments and notes
+     */
+    constructor(endnote: number | NoteContent);
+    /**
+     * Formats the run, with its own endnote added to the document's endnotes, and referred to by the id it has there.
+     */
+    prepForXml(context: IContext): IXmlableObject | undefined;
 }
 
 export declare class EndnoteReferenceRunAttributes extends XmlAttributeComponent<{
@@ -3594,8 +3655,22 @@ export declare class EndnoteReferenceRunAttributes extends XmlAttributeComponent
 }
 
 export declare class Endnotes extends XmlComponent {
+    private readonly ownNotes;
+    private highestId;
     constructor();
     createEndnote(id: number, paragraph: readonly Paragraph[]): void;
+    /**
+     * The id of the endnote that a reference run brings with it, which is added to the endnotes the first time the run
+     * is written, with an id no other endnote has. Word has endnotes only in a document's body, so a run written
+     * anywhere else, such as in a header, has none, and its endnote isn't added.
+     *
+     * @internal
+     * @param reference - The run, which has the same endnote each time it is written
+     * @param endnote - The endnote's content
+     * @param context - The context the run is written in
+     * @returns The endnote's id, or undefined outside the document's body
+     */
+    idOf(reference: object, endnote: NoteContent, context: IContext): number | undefined;
     /**
      * 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.
@@ -3657,6 +3732,11 @@ export declare type EstimatedPageNumbers = {
  * 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
  *
@@ -3670,6 +3750,7 @@ export declare type EstimatedPageNumbers = {
  *   <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>
  * ```
  *
@@ -3908,14 +3989,20 @@ export declare const fillSequenceNumbers: (body: IXmlableObject, context: IConte
 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;
@@ -3925,12 +4012,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 }
  * ]);
  * ```
  */
@@ -3938,7 +4026,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;
@@ -4110,6 +4201,10 @@ export declare class FootnoteReferenceElement extends EmptyElement {
  * (typically a superscript number) that appears in the main document text.
  * Clicking this marker navigates to the corresponding footnote content.
  *
+ * It refers to one of the document's `footnotes` by its id, or is given its footnote's content, for a footnote of its
+ * own, which is added to the document's footnotes when the run is written. Content made before the document it goes
+ * in, such as by a function that makes paragraphs, then brings its footnotes with it.
+ *
  * Reference: http://officeopenxml.com/WPfootnotes.php
  *
  * @publicApi
@@ -4123,15 +4218,30 @@ export declare class FootnoteReferenceElement extends EmptyElement {
  *     new FootnoteReferenceRun(1),
  *   ],
  * });
+ *
+ * // Or with the footnote's content
+ * new Paragraph({
+ *   children: [
+ *     new TextRun("This text has a footnote of its own"),
+ *     new FootnoteReferenceRun({ children: [new Paragraph("The footnote.")] }),
+ *   ],
+ * });
  * ```
  */
 export declare class FootnoteReferenceRun extends Run {
+    private readonly footnote?;
     /**
      * Creates a new footnote reference run.
      *
-     * @param id - Unique identifier linking to the footnote content
+     * @param footnote - The id of one of the document's `footnotes`, or the footnote's content, for a footnote of the
+     * run's own. Word has footnotes only in a document's body, so a run with its footnote's content is left out of
+     * headers, footers, comments and notes
      */
-    constructor(id: number);
+    constructor(footnote: number | NoteContent);
+    /**
+     * Formats the run, with its own footnote added to the document's footnotes, and referred to by the id it has there.
+     */
+    prepForXml(context: IContext): IXmlableObject | undefined;
 }
 
 /**
@@ -4191,6 +4301,8 @@ export declare class FootNoteReferenceRunAttributes extends XmlAttributeComponen
  * ```
  */
 export declare class FootNotes extends XmlComponent {
+    private readonly ownNotes;
+    private highestId;
     constructor();
     /**
      * Creates and adds a new footnote to the collection.
@@ -4199,6 +4311,18 @@ export declare class FootNotes extends XmlComponent {
      * @param paragraph - Array of paragraphs that make up the footnote content
      */
     createFootNote(id: number, paragraph: readonly Paragraph[]): void;
+    /**
+     * The id of the footnote that a reference run brings with it, which is added to the footnotes the first time the
+     * run is written, with an id no other footnote has. Word has footnotes only in a document's body, so a run written
+     * anywhere else, such as in a header, has none, and its footnote isn't added.
+     *
+     * @internal
+     * @param reference - The run, which has the same footnote each time it is written
+     * @param footnote - The footnote's content
+     * @param context - The context the run is written in
+     * @returns The footnote's id, or undefined outside the document's body
+     */
+    idOf(reference: object, footnote: NoteContent, context: IContext): number | undefined;
     /**
      * 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.
@@ -6493,12 +6617,7 @@ export declare type INumberedItemReferenceOptions = {
  */
 export declare type INumberingOptions = {
     /** Array of numbering configurations, each with levels and a reference name. */
-    readonly config: readonly {
-        /** Array of level definitions for this numbering configuration. */
-        readonly levels: readonly ILevelsOptions[];
-        /** Unique reference name for this numbering configuration. */
-        readonly reference: string;
-    }[];
+    readonly config: readonly NumberingDefinition[];
 };
 
 /**
@@ -6814,8 +6933,13 @@ export declare type IParagraphStylePropertiesOptions = {
     readonly shading?: IShadingAttributesProperties;
     /** Numbering configuration for lists, or false to remove numbering */
     readonly numbering?: {
-        /** Reference ID of the numbering definition to use */
-        readonly reference: string;
+        /**
+         * The list the paragraph is in: the reference of one of the document's `numbering` configs, or a list's
+         * definition, its reference and its levels, for a list the document's `numbering` option doesn't have.
+         * The definition is added to the document's numbering when the paragraph is written, unless it already has
+         * a list with that reference, which is kept
+         */
+        readonly reference: string | NumberingDefinition;
         /** Level in the numbering hierarchy (0-8) */
         readonly level: number;
         /** Instance number for multiple lists with same reference */
@@ -6993,7 +7117,13 @@ export declare type IRunStylePropertiesOptions = {
     readonly language?: ILanguageOptions;
     readonly border?: IBorderOptions;
     readonly snapToGrid?: boolean;
+    /** Hides the text. `false` shows text that the run's style hides. */
     readonly vanish?: boolean;
+    /**
+     * Keeps a hidden paragraph mark hidden even when hidden text is shown, so its paragraph always runs on into the next one,
+     * as Word's style separator does. It is meant for a paragraph's mark, with `vanish`:
+     * `new Paragraph({ run: { vanish: true, specVanish: true } })`. Without `vanish`, Word doesn't hide the mark.
+     */
     readonly specVanish?: boolean;
     readonly scale?: number;
     readonly math?: boolean;
@@ -7756,7 +7886,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?: {
@@ -8443,9 +8578,9 @@ export declare const LineNumberRestartFormat: {
 export declare const LineRuleType: {
     /** Line spacing is at least the specified value */
     readonly AT_LEAST: "atLeast";
-    /** Line spacing is exactly the specified value */
+    /** Writes `exactly`, which isn't a value the schema allows, so Word ignores it. Use {@link LineRuleType.EXACT} for an exact line height. */
     readonly EXACTLY: "exactly";
-    /** Line spacing is exactly the specified value (alias for EXACTLY) */
+    /** Line spacing is exactly the specified value */
     readonly EXACT: "exact";
     /** Line spacing is automatically determined based on content */
     readonly AUTO: "auto";
@@ -9446,6 +9581,18 @@ export declare type NonVisualDrawingPropertiesOptions = DrawingLinkOptions & {
     readonly title?: string;
 };
 
+/**
+ * A footnote's or endnote's content: its paragraphs.
+ *
+ * A {@link FootnoteReferenceRun} or {@link EndnoteReferenceRun} can be given its note's content, rather than the id of
+ * one of the document's `footnotes` or `endnotes`, for a note of its own. The note is added to the document's notes,
+ * with an id none of them has, when the run is written in the document's body.
+ */
+export declare type NoteContent = {
+    /** The note's paragraphs */
+    readonly children: readonly Paragraph[];
+};
+
 /**
  * When the footnote or endnote numbering restarts.
  *
@@ -9709,8 +9856,11 @@ export declare class Numbering extends XmlComponent {
      *
      * @param reference - The reference name of the abstract numbering definition
      * @param instance - The instance number for this concrete numbering
+     * @param definition - The list's definition, for a list a paragraph gives its own definition of. It is added with
+     * its reference, unless the numbering already has a list with that reference, such as one of the document's
+     * `numbering` option, which is kept
      */
-    createConcreteNumberingInstance(reference: string, instance: number): void;
+    createConcreteNumberingInstance(reference: string, instance: number, definition?: NumberingDefinition): void;
     /**
      * Gets all concrete numbering instances.
      *
@@ -9725,6 +9875,22 @@ export declare class Numbering extends XmlComponent {
     get ReferenceConfig(): readonly Record<string, any>[];
 }
 
+/**
+ * A list's definition: its reference and its levels.
+ *
+ * A document's `numbering` option has a definition for each of its lists. A paragraph can also be given a list's
+ * definition as its `numbering`'s `reference`, for a list the document's `numbering` option doesn't have, which is added
+ * to the document's numbering when the paragraph is written.
+ *
+ * @see {@link Numbering}
+ */
+export declare type NumberingDefinition = {
+    /** Array of level definitions for this numbering configuration. */
+    readonly levels: readonly ILevelsOptions[];
+    /** Unique reference name for this numbering configuration. */
+    readonly reference: string;
+};
+
 /**
  * Represents numbering properties for a paragraph.
  *
@@ -10858,7 +11024,7 @@ declare type PatchDetectorOptions = {
  *
  * @publicApi
  */
-export declare const patchDocument: <T extends PatchDocumentOutputType = PatchDocumentOutputType>({ outputType, data, patches, keepOriginalStyles, placeholderDelimiters, recursive, footnotes, endnotes, pageNumbers, }: PatchDocumentOptions<T>) => Promise<OutputByType[T]>;
+export declare const patchDocument: <T extends PatchDocumentOutputType = PatchDocumentOutputType>({ outputType, data, patches, keepOriginalStyles, placeholderDelimiters, recursive, footnotes, endnotes, numbering, pageNumbers, }: PatchDocumentOptions<T>) => Promise<OutputByType[T]>;
 
 /**
  * Options for patching a document.
@@ -10871,6 +11037,7 @@ export declare const patchDocument: <T extends PatchDocumentOutputType = PatchDo
  * @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 numbering - The lists that the paragraphs in patches use, by their references
  * @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> = {
@@ -10903,6 +11070,12 @@ export declare type PatchDocumentOptions<T extends PatchDocumentOutputType = Pat
     readonly endnotes?: Readonly<Record<string, {
         readonly children: readonly Paragraph[];
     }>>;
+    /**
+     * The lists that the paragraphs in patches use, as in a `Document`. A paragraph is put in one with
+     * `numbering: { reference, level }`. Each list that patches use is added to the document's numbering, with ids that
+     * none of the template's lists have, and so is the bullet list of `bullet` paragraphs
+     */
+    readonly numbering?: INumberingOptions;
     /**
      * 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