@docx4j/core-ts 0.5.0 → 0.7.0

package/dist/model/text/TextContext.d.mts

@@ -0,0 +1,256 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import type * as w15 from '@docx4j/generated-objects-ts/modules/org_docx4j_w15';
+import type * as w16cid from '@docx4j/generated-objects-ts/modules/org_docx4j_w16cid';
+import type * as w16cex from '@docx4j/generated-objects-ts/modules/org_docx4j_w16cex';
+import type * as core from '@docx4j/generated-objects-ts/modules/org_docx4j_docProps_core';
+import type * as extended from '@docx4j/generated-objects-ts/modules/org_docx4j_docProps_extended';
+import type * as custom from '@docx4j/generated-objects-ts/modules/org_docx4j_docProps_custom';
+import type { Part } from '../../parts/Part.mjs';
+import type { XmlPart } from '../../parts/XmlPart.mjs';
+import { PropertyResolver } from '../properties/PropertyResolver.mjs';
+import { NumberingDefinitions } from '../listnumbering/definitions.mjs';
+import { Emulator, type NumberingPartLike } from '../listnumbering/Emulator.mjs';
+import { NumberingStates } from '../listnumbering/state.mjs';
+import { Body } from '../content/Body.mjs';
+import { ResolvedView } from '../content/ResolvedView.mjs';
+import type { XPathEngine } from '../customxml/xpath.mjs';
+import type { NoteType } from './TextResult.mjs';
+/** As much of a `WordprocessingMLPackage` as a reading uses, so that this module does not import the package. */
+export interface TextPackage {
+    getMainDocumentPart(): MainLike;
+    getPropertyResolver(): Promise<PropertyResolver>;
+    getNumberingEmulator(): Promise<unknown>;
+    readonly propertyResolverOrUndefined?: PropertyResolver;
+    readonly docPropsCorePart?: XmlPart<core.CoreProperties>;
+    readonly docPropsExtendedPart?: XmlPart<extended.Properties>;
+    readonly docPropsCustomPart?: XmlPart<custom.Properties>;
+    readonly customXmlDataStorageParts: ReadonlyMap<string, {
+        parseDocument(): Promise<Document>;
+        readonly partName: {
+            readonly name: string;
+        };
+    }>;
+    xpathEngine: XPathEngine;
+    /** The names the container held twice, read from the first under `repair: 'word'` (CR-024). */
+    readonly duplicateEntries?: readonly {
+        readonly entry: string;
+        readonly count: number;
+    }[];
+    /** More than one officeDocument relationship, the last's target read under `repair: 'word'` (CR-024 section 9). */
+    readonly multipleMainParts?: {
+        readonly partName: string;
+        readonly count: number;
+    } | undefined;
+    /** An `External` officeDocument relationship beside an internal one, dropped under `repair: 'all'` (CR-031). */
+    readonly externalMainPart?: {
+        readonly partName: string;
+        readonly urls: readonly string[];
+    } | undefined;
+    /** The relationships parts read by local name under `repair: 'word'` (CR-031 section 2.3). */
+    readonly relationshipsNamespaces?: readonly {
+        readonly partName: string;
+        readonly count: number;
+    }[];
+    /** What the load repaired (REQ-207's `repaired`, CR-031). */
+    readonly repaired?: 'none' | 'word' | 'own';
+}
+/** As much of a `MainDocumentPart` as a reading uses. */
+export interface MainLike extends XmlPart<wml.Document> {
+    readonly styleDefinitionsPart?: Part;
+    readonly numberingDefinitionsPart?: XmlPart<wml.Numbering> & NumberingPartLike & {
+        getDefinitions(): Promise<NumberingDefinitions>;
+    };
+    readonly documentSettingsPart?: XmlPart<wml.CTSettings>;
+    readonly footnotesPart?: XmlPart<wml.CTFootnotes>;
+    readonly endnotesPart?: XmlPart<wml.CTEndnotes>;
+    readonly commentsPart?: XmlPart<wml.Comments>;
+    readonly commentsExtendedPart?: XmlPart<w15.CTCommentsEx>;
+    readonly commentsIdsPart?: XmlPart<w16cid.CTCommentsIds>;
+    readonly commentsExtensiblePart?: XmlPart<w16cex.CTCommentsExtensible>;
+    readonly glossaryDocumentPart?: XmlPart<wml.GlossaryDocument>;
+    readonly headerParts: XmlPart<wml.Hdr>[];
+    readonly footerParts: XmlPart<wml.Ftr>[];
+}
+/**
+ * A part a reading may need that it could not read (CR-012 section 28, WD REQ-801): its role, by what it supplies. Each is
+ * raised as `part.not_read`, naming the part, where the reading needs it.
+ */
+export type UnreadPart = 'styles' | 'numbering' | 'settings' | 'core' | 'app' | 'custom';
+/**
+ * The trees one reading walks, each read **privately** where its part was not unmarshalled
+ * (`XmlPart.readContents`), so that reading a document costs no part its byte-for-byte round trip
+ * (REQ-204), and the live tree where it was. Every story is read, so that the views' plan covers them
+ * all ("the view is the package's"); the glossary only when it is included.
+ */
+export declare class PackageTrees {
+    readonly pkg: TextPackage | undefined;
+    main: {
+        part: MainLike;
+        document: wml.Document;
+    } | undefined;
+    footnotes: {
+        part: Part;
+        tree: wml.CTFootnotes;
+    } | undefined;
+    endnotes: {
+        part: Part;
+        tree: wml.CTEndnotes;
+    } | undefined;
+    comments: {
+        part: Part;
+        tree: wml.Comments;
+    } | undefined;
+    commentsExtended: w15.CTCommentsEx | undefined;
+    /**
+     * Each comment's `w16cex:dateUtc`, by its last paragraph's `w14:paraId` (upper case): the comments ids part gives the
+     * paragraph's durable id, the comments extensible part the durable id's date (REQ-702's offset; docx4j's `commentDatesUtc`).
+     */
+    readonly commentDatesUtc: Map<string, wml.XmlCalendar>;
+    /** Each header and footer part related from the main document part, with its content. */
+    readonly headersAndFooters: Map<Part, wml.Ftr | wml.Hdr>;
+    glossary: {
+        part: Part;
+        tree: wml.GlossaryDocument;
+    } | undefined;
+    /** Each story part that could not be read, with the reason: a reading taking it raises `content.not_read` (REQ-801). */
+    readonly unreadable: Map<Part, unknown>;
+    settings: wml.CTSettings | undefined;
+    /** The document properties under `core`, `app` and `custom` (REQ-515). */
+    properties: Record<string, unknown> | undefined;
+    /** The resolver, where the package has a styles part that can be read (docx4j makes none without one). */
+    resolver: PropertyResolver | undefined;
+    /**
+     * What the numbering resolves a style's `w:numPr` through: the package's resolver, else, where a styles or numbering part
+     * cannot be read, the reading's own without it (CR-012 section 28); undefined where the package has neither part.
+     */
+    private numberingResolver;
+    numbering: NumberingDefinitions | undefined;
+    /**
+     * The numbering this reading counts by: the numbering part's emulator, one of the reading's own where the styles cannot
+     * be read, or, where the numbering part is absent or cannot be read, one over Word's default definition, made at the
+     * first numbered paragraph (`numberingFor`).
+     */
+    emulator: Emulator | undefined;
+    /** Where the numbering part is absent or cannot be read: the warning the first numbered paragraph raises, and the part named. */
+    numberingMissing: {
+        kind: 'part.absent' | 'part.not_read';
+        partName: string;
+    } | undefined;
+    /** The parts this reading could not read that it may need, by role, each with its part's name (CR-012 section 28). */
+    readonly notRead: Map<UnreadPart, string>;
+    /** The custom XML stores and properties parts a binding could not be read against, by normalised store item id: their part names. */
+    private readonly unreadStores;
+    /** The core and application properties' DOMs, by their normalised store item ids. */
+    private readonly stores;
+    /** The custom XML parts' DOMs, in the package's order: what a binding resolves to (CR-020). */
+    private readonly customStores;
+    private readonly storeItems;
+    private xpath;
+    private anchored;
+    private constructor();
+    /** The trees of a package. */
+    static read(pkg: TextPackage): Promise<PackageTrees>;
+    /**
+     * The resolver and the numbering (CR-012 section 28, WD REQ-801). The package's own where they can be built; where a
+     * styles or numbering part cannot be read, a resolver of the reading's own without it, as for a package that lacks the
+     * part, the part kept in `notRead`. The package's resolver is never set from it, so the content API still refuses the
+     * part (CR-001 section 26), and a part put right is read again by the next reading. Where the styles cannot be read the
+     * numbering's definitions are read directly and counted by an emulator of the reading's own, so that nothing is kept on
+     * the numbering part. A numbering part absent or unread is Word's default definition (`numberingFor`, WD 0.76).
+     */
+    private readStylesAndNumbering;
+    /** `commentDatesUtc`, from the comments ids and extensible parts, read privately; neither read, as D3 (a) leaves them, nothing. */
+    private readCommentDates;
+    /** `readContents()`, undefined for a part that cannot be read, which is then kept in `notRead` under its role. */
+    private readOrNote;
+    /**
+     * The numbering a numbered paragraph is counted by. Where the numbering part is absent or cannot be read, Word's default
+     * definition (WD 0.76, REQ-510), made here once, at the first numbered paragraph, and never written to the package: one
+     * abstract definition of nine decimal levels, each `w:start` 1 and `w:lvlText` `%{level+1}.`, and one instance per
+     * `w:numId` other than 0 the document names, plain where a paragraph style's `w:numPr` names it, else with a
+     * `w:startOverride` of 1 at every level, so that the direct paragraphs restart at their first and then share the style's
+     * count.
+     */
+    numberingFor(): Emulator | undefined;
+    /** Trees with no package: content read as it stands (docx4j's planless `Texts.of(content)`). */
+    static none(): PackageTrees;
+    /** The glossary document, read when `include: glossary` first asks for it. */
+    readGlossary(): Promise<void>;
+    /** A story part's content; undefined where it has none, and where it could not be read, then kept in `unreadable`. */
+    private readStory;
+    private readStores;
+    /**
+     * A data binding's value, docx4j `BoundValues`: the binding's XPath, with its own prefix mappings,
+     * against the custom XML part its `w:storeItemID` names (or the core or application properties), or,
+     * where it names none, the part its XPath fits, as Word repairs it (CR-020; nothing is written back);
+     * the string value of the first node selected. Undefined where the binding does not resolve.
+     */
+    boundValue(binding: wml.CTDataBinding): string | undefined;
+    /**
+     * The name of the part a binding names that could not be read: a custom XML store, or the core or application
+     * properties (CR-012 section 28, D3); undefined where it names a part that was read, or none.
+     */
+    unreadStoreOf(binding: wml.CTDataBinding): string | undefined;
+    /** The nodes an XPath selects in a store, with a binding's prefix mappings (the default namespace's left out). */
+    private selectIn;
+    /**
+     * The ids of the comments anchored in the document: a `w:commentReference` or a `w:commentRangeStart`
+     * in the main document, a header or footer, or a note, in any branch.
+     */
+    anchoredComments(): Set<string>;
+    /** Every story's body, over these trees, for the views' plan: the main document, each note and comment, the headers and footers. */
+    stories(): Body[];
+    /** The part whose tree holds an object, by its `PARENT`s, or undefined. */
+    partOf(object: unknown): Part | undefined;
+}
+/**
+ * What a story needs from the rest of the document (CR-012 section 4.4): the note references' order, for
+ * `[n]`; the numbering states per story, for list labels and `value`; the bookmarks, for `fields: update`;
+ * and, made once, each view's plan of what Accept All or Reject All would leave. A call given a context
+ * uses it and adds to it, so that the editor's calls over one part at a time, in the order the
+ * specification reads the stories (REQ-501), number the notes and count the lists as one reading of the
+ * whole package does; `TextResult.concat` assembles their results.
+ *
+ * A context is a snapshot of the package as it was read (`Texts.contextOf`): after the package changes,
+ * make another. It is for one reading, in one view: the calls under it take the same options, as the parts
+ * of one `Texts.of(pkg)` would.
+ */
+export declare class TextContext {
+    readonly trees: PackageTrees;
+    /** Notes referenced, in reference order: id to number, 0 for a note with a custom mark. */
+    readonly footnotes: Map<string, number>;
+    readonly endnotes: Map<string, number>;
+    private footnoteCount;
+    private endnoteCount;
+    /** The numbering states, one per story (`Emulator`). */
+    readonly numberingStates: NumberingStates;
+    /** The `w:lastRenderedPageBreak`s of the main story so far (REQ-708). */
+    pageMarkers: number;
+    /** The bookmarks' text, by lower-cased name (REQ-506's REF, CR-012 phase 5a). */
+    readonly bookmarks: Map<string, string>;
+    /** Whether the main story has been read under this context, which numbers the notes. */
+    mainRead: boolean;
+    /**
+     * The view the context's first call read in: its note numbers and counts are that view's, so a call in
+     * another view is refused (`Texts.of`).
+     */
+    view: 'accepted' | 'original' | 'markup' | undefined;
+    private readonly plans;
+    /** Per container, then per options, what the blocks begin inside (`Extractor.fieldsAtBlocks`), made once; shared with siblings. */
+    private starts;
+    constructor(trees: PackageTrees);
+    /** What `make` gives for a container's blocks under options keyed `key`, made once in this context (CR-012 section 17.13). */
+    blockStarts<T>(container: object, key: string, make: () => T): T;
+    /** The package this context reads. */
+    get pkg(): TextPackage | undefined;
+    /** A note's number, given at its first reference: in reference order, footnotes and endnotes apart, 0 for a custom mark (REQ-503). */
+    noteNumber(type: NoteType, id: string, customMark: boolean): number;
+    /** The plan of Accept All (`accepted`) or Reject All, over every story, made once. */
+    plan(accepted: boolean): ResolvedView;
+    /** A context over the same trees and plans, its own notes and states: for a reading whose blocks are not the result's. */
+    sibling(): TextContext;
+    /** Adopts the note numbers another context gave (`sibling`'s, for a notes part read before its story). */
+    adoptNotes(other: TextContext): void;
+}
+/** An XML calendar as its lexical form. */
+export declare function calendarText(date: unknown): string | undefined;