@docx4j/core-ts 0.5.0 → 0.7.0

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

@@ -0,0 +1,349 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import type { Part } from '../../parts/Part.mjs';
+import type { PropertyResolver } from '../properties/PropertyResolver.mjs';
+import type { NumberingState } from '../listnumbering/state.mjs';
+import { type Element } from '../content/tree.mjs';
+import type { ResolvedView } from '../content/ResolvedView.mjs';
+import type { TextOptions, TextModelView } from './TextOptions.mjs';
+import { TextBlock, TextRun, TextRevision, TextWarning, TextResult, type TextStory, type NoteType } from './TextResult.mjs';
+import { type TextContext, type PackageTrees } from './TextContext.mjs';
+/** How the view is read (docx4j `Extractor.Mode`). */
+export type ExtractorMode = 
+/** The view's rules: a plan for accepted and original, revisions marked for markup. */
+'view'
+/** A package already resolved by Accept All or Reject All (the copy route, REQ-406): no view logic. */
+ | 'resolved'
+/** Content with no package to plan over: run-level revisions only, no joins or moves. */
+ | 'planless';
+interface OfficeSpan {
+    offset: number;
+    length: number;
+}
+/** An open complex field. */
+declare class FieldState {
+    instr: string;
+    result: string;
+    separated: boolean;
+    /** `w:fldLock` on its beginning: never recomputed (REQ-506). */
+    locked: boolean;
+    /** Its result computed under `fields: update` (REQ-506): the cached result's text is not read. */
+    computed: string | undefined;
+    /** A HYPERLINK field's target, once its code is read (REQ-703). */
+    link: string | undefined;
+    /** A table of contents under `toc: false` (D12): nothing of it is read. */
+    toc: boolean;
+    /** A SET field: its stored result is never shown (Word hides it; REQ-505, CR-012 section 26). */
+    hiddenResult: boolean;
+    /** Where its code's runs begin, for a table of contents' to be taken out again. */
+    codeBlock: TextBlock | undefined;
+    codeStart: number;
+    /** The paragraph whose merge floor its code raised, and the floor before. */
+    floorParagraph: ParagraphState | undefined;
+    previousFloor: number;
+    /** The field as a block after the one it began in starts inside it: its code's block and paragraph left behind. */
+    copy(): FieldState;
+}
+/** The complex fields open where a container's blocks begin, by the block's index (`Extractor.fieldsAtBlocks`). */
+export type BlockStarts = ReadonlyMap<number, readonly FieldState[]>;
+/** The state of a run-level walk: the revision and the control the runs are in. */
+declare class RunState {
+    /** markup: the innermost revision; else undefined. */
+    readonly revision: TextRevision | undefined;
+    /** accepted, original: inside a revision holder the view keeps (its runs are text whatever their elements). */
+    readonly kept: boolean;
+    readonly placeholder: boolean;
+    constructor(
+    /** markup: the innermost revision; else undefined. */
+    revision: TextRevision | undefined, 
+    /** accepted, original: inside a revision holder the view keeps (its runs are text whatever their elements). */
+    kept: boolean, placeholder: boolean);
+    withRevision(r: TextRevision | undefined, kept: boolean): RunState;
+    withPlaceholder(): RunState;
+}
+/** What follows its anchoring paragraph, or the table its anchor is in (REQ-511, REQ-518): a text box, legacy WordArt. */
+interface Anchored {
+    prefix: string;
+    emit(x: Extractor, anchoring: Story, sink: TextBlock[]): void;
+}
+/** The walk of one story. */
+declare class Story {
+    private readonly x;
+    readonly kind: TextStory;
+    readonly prefix: string;
+    readonly part: Part | undefined;
+    /** Open complex fields; [0] is the innermost (docx4j's deque head). */
+    readonly fields: FieldState[];
+    /** What was anchored since the last flush, to follow its anchor (or its table). */
+    readonly pending: Anchored[];
+    tableDepth: number;
+    /** The sections ended so far (the main story only). */
+    sections: (wml.SectPr | undefined)[] | undefined;
+    noteType: NoteType | undefined;
+    noteNumber: number;
+    noteId: string | undefined;
+    private numberingState;
+    constructor(x: Extractor, kind: TextStory, prefix: string, part: Part | undefined);
+    /** The resolver the walk reads styles with, for `officeSpans`' hidden rule. */
+    get resolver(): PropertyResolver | undefined;
+    numbering(): NumberingState;
+}
+/** A paragraph being read: the block its runs go to, its address, what it anchored so far. */
+declare class ParagraphState {
+    readonly block: TextBlock;
+    readonly p: wml.P;
+    readonly address: string;
+    readonly story: Story;
+    boxes: number;
+    charts: number;
+    smartArts: number;
+    objects: number;
+    /** Whether every run with text so far is in a monospaced font; undefined before the first. */
+    monospace: boolean | undefined;
+    /** The formatting of the run being read (a run carrying only it), or undefined outside a run. */
+    format: TextRun | undefined;
+    /** The target of the `w:hyperlink` being read. */
+    link: string | undefined;
+    /** An equation being written, and whether it is a display one. */
+    math: boolean;
+    displayMath: boolean;
+    /** Whether a table of contents left out (D12) is in the paragraph. */
+    toc: boolean;
+    /** The first of the block's runs a run may be merged into: a field's code starts a run of its own where it may be taken out. */
+    mergeFloor: number;
+    private office;
+    constructor(block: TextBlock, p: wml.P, address: string, story: Story);
+    /** Where an item's text is in this paragraph's `Paragraph.text`. */
+    officeSpan(item: Element): OfficeSpan | undefined;
+}
+/**
+ * The text model's walk (CR-046 section 2.3): `scope(view(resolve(package)))` in one pass over the
+ * unresolved tree, producing the block model. docx4j `Extractor`, over trees read before it starts.
+ */
+export declare class Extractor {
+    readonly trees: PackageTrees;
+    readonly options: TextOptions;
+    readonly context: TextContext;
+    readonly view: TextModelView;
+    readonly mode: ExtractorMode;
+    /** What a view removes and joins; undefined in markup, and in the resolved and planless modes. */
+    readonly plan: ResolvedView | undefined;
+    readonly resolver: PropertyResolver | undefined;
+    readonly warnings: TextWarning[];
+    private readonly warned;
+    /** The parts this reading took a story from, for what the walk can't meet (`partWarningsUnmet`). */
+    readonly storyParts: Set<Part>;
+    /** What every address this extraction makes starts with. */
+    root: string;
+    /** The run properties a paragraph style and character style give, by their ids. */
+    private readonly styleRPrCache;
+    /** Bookmarks open in the walk, by id (REQ-506's REF, phase 5a). */
+    private readonly openBookmarks;
+    /** `fieldsAtBlocks`' walk: paragraphs read for their field characters and instructions alone, nothing emitted. */
+    private fieldsOnly;
+    constructor(trees: PackageTrees, options: TextOptions, mode: ExtractorMode, context: TextContext);
+    extract(): TextResult;
+    /** The result's metadata: `fields_update_on_open`, `repaired` and the document properties (REQ-801, REQ-207, REQ-515). */
+    private metadata;
+    /** `w:updateFields`, which every result's metadata carries: so a settings part that cannot be read is needed by every reading. */
+    private fieldsUpdateOnOpen;
+    /** A part the reading needs here: `part.not_read`, once, where it could not be read (REQ-801; CR-012 section 28). */
+    private consult;
+    commentsIncluded(): boolean;
+    /** A part's or object's content as one story (`Texts.of(part)`, `Texts.of(pkg, content)`). */
+    extractContent(content: unknown, kind: TextStory, prefix: string, part: Part | undefined): TextResult;
+    /** The notes of one kind, in the context's reference order (`Texts.of(notesPart)`). */
+    extractNotes(type: NoteType): TextResult;
+    /** The comments (`Texts.of(commentsPart)`): what the view includes, in the comments part's order. */
+    extractComments(): TextResult;
+    private glossary;
+    /** Block-level content into `sink`: paragraphs (joined in a view), tables, and what is transparent. */
+    blocks(items: Element[] | undefined, prefix: string, story: Story, sink: TextBlock[], state?: RunState): void;
+    /** A paragraph chain whose deleted mark has a table next: it joins the table's first cell's first paragraph (docx4j CR-043 section 17). */
+    private pendingTableJoin;
+    /**
+     * The block at `items[i]` into `sink`, with the paragraphs a view joins to it; the index of the last item it took.
+     * `dropCap` is a drop cap's frame paragraph just read in the same container, for the paragraph next to take (REQ-521).
+     */
+    private block;
+    /**
+     * Some of a container's blocks, by their indices, each as `extractContent` reads it in the whole: a
+     * paragraph the view joins to one before it gives nothing (its text is in that one's block), and each
+     * block starts inside the complex fields open where it begins (`starts`, from `fieldsAtBlocks`), so that
+     * a table of contents left out (D12) is left out here too. Each block is read as a story of its own.
+     */
+    extractBlocks(content: unknown, kind: TextStory, prefix: string, part: Part | undefined, indices: readonly number[], starts: BlockStarts): TextResult;
+    /**
+     * The complex fields open where each of a container's blocks begins, for `extractBlocks`: a walk of the
+     * blocks reading field characters and instructions alone (`fieldsOnly`), as the whole walk reads them.
+     * Blocks with none open are not in the map. Its own context and warnings, so the reading leaves no trace.
+     */
+    static fieldsAtBlocks(trees: PackageTrees, options: TextOptions, mode: ExtractorMode, context: TextContext, content: unknown, kind: TextStory, prefix: string, part: Part | undefined): BlockStarts;
+    /** Whether the view joins the paragraph at `items[i]` to one before it: the item before it, past markers and what the view removes, is a paragraph whose mark goes. */
+    private joinedFromBefore;
+    /** The index of the paragraph a paragraph joins: the next in the list past markers and what the view removes, or -1. */
+    private nextParagraph;
+    /**
+     * A paragraph chain's block into the sink, returned; undefined where it makes none. A drop cap's frame paragraph read
+     * just before (`dropCap`; REQ-521) is taken in at its start.
+     */
+    private paragraph;
+    /**
+     * Whether a paragraph just read is a drop cap's frame, for the paragraph next to take (REQ-521; CR-012 section 24.3):
+     * under `drop_caps: join`, one `w:p` whose `w:framePr/@w:dropCap` (its own, or its style's) is `drop` or `margin`, whose
+     * text is at most one word (no white space and no space character, U+00A0 included), and which ends no section.
+     */
+    private dropCapFrame;
+    /**
+     * A drop cap's frame paragraph joined to the block after it (REQ-521): its runs and fields put at the block's start with
+     * no separator, the block (its address, its properties) in the frame's place in the sink, so that what the frame
+     * anchored still follows it; the warning `paragraph.drop_cap_joined` at the frame's address. The letter's run merges
+     * into the word's first run on docx4j's rule (the same kind, hidden and placeholder flags, revision and formatting; D6,
+     * Jason 2026-11-02), which replaces section 4.4's `officeOffset` contiguity rule at this one join, the two runs' text
+     * coming from two paragraphs' `Paragraph.text`: the merged run keeps the letter's source, and its `officeOffset` is
+     * undefined. False, and nothing done, where the frame is not in the sink.
+     */
+    private joinDropCap;
+    private endSection;
+    private flushIfOutsideTable;
+    /**
+     * An `altChunk`: not expanded until CR-012 phase 5e, which raises `altchunk.not_expanded` naming the chunk's part, its
+     * selector (WD 0.47, CR-012 section 22.2 (a)), with its content type.
+     */
+    private altChunk;
+    /**
+     * A plain-text control's bound value where its binding resolves and is what Word shows: not where the
+     * value is empty and the control shows its placeholder, nor under `bindings: surface`. Undefined to read
+     * the surface. Raises `sdt.binding_differs` where the two differ.
+     */
+    private bound;
+    /**
+     * A control's surface in the view: its `w:t`, tabs and breaks, what the view removes left out, and of an
+     * mc:AlternateContent the selected branch only, as the reading takes it (CR-013: every branch's text
+     * made a surface no binding could match, and a false `sdt.binding_differs`).
+     */
+    private surfaceText;
+    private bookmark;
+    private properties;
+    /**
+     * A paragraph's numbering from its effective `w:numPr` and the numbering definitions; undefined for none,
+     * for `w:numId` 0, and where Word gives the paragraph no number: a `w:numId` its style brought, whose
+     * level belongs to another paragraph style (`Emulator.levelStyleId`, REQ-510).
+     */
+    private numbering;
+    /**
+     * The numbering a numbered paragraph is counted by (`PackageTrees.numberingFor`): where the numbering part is absent or
+     * cannot be read, Word's default definition, and `part.absent` or `part.not_read` naming the part, once (WD 0.76).
+     */
+    private numberingEmulator;
+    /** Whether the level belongs to a paragraph style that is neither the paragraph's nor one its style is based on. */
+    private linkedElsewhere;
+    /** The paragraph counted in its story's numbering state; undefined where it is not numbered. */
+    private count;
+    private table;
+    private rows;
+    private cells;
+    private runs;
+    private holderState;
+    private run;
+    private runItem;
+    /** Document text: a field's code where a field is in its code (shown only under `field_codes`), else text. */
+    private text;
+    private addText;
+    private endField;
+    private simpleField;
+    /** The runs of a simple field's result, added to the paragraph; their text. `hidden`: a result never shown (a SET's). */
+    private resultOf;
+    /**
+     * An equation, `$...$` (`$$...$$` for an `m:oMathPara`). Until CR-012 phase 5b ports a LaTeX converter
+     * it is its `m:t` text in document order inside the delimiters, REQ-604's form for an equation that
+     * can't be converted. In markup, an equation with tracked changes is its Reject All form deleted and
+     * its Accept All form inserted, each as the plan for that view leaves it.
+     */
+    private math;
+    private mathText;
+    /** The view's rule for an equation's list members: what the plan removes goes; without a plan, a revision by its type. */
+    private keepMathInView;
+    /**
+     * What a run's drawing, picture or object holds, in document order, branches selected: text boxes and
+     * WordArt to follow the paragraph; pictures and objects as runs where they are. A chart or SmartArt
+     * contributes nothing until CR-012 phase 5c.
+     */
+    private anchored;
+    /** A `wp:inline` or `wp:anchor`: a chart, SmartArt, a picture, or a shape to walk into. */
+    private graphic;
+    /** A VML shape: legacy WordArt, a picture, or a shape to walk into for its text box. */
+    private vmlShape;
+    /** A `w:object`: an object run with its ProgID (REQ-512); its package is read under `embedded: true`, phase 5d. */
+    private object;
+    /**
+     * A DrawingML picture: its `wp:docPr` (or a nested picture's `pic:cNvPr`). `descr` and `title` are the
+     * schema's default, `''`, where the element doesn't give them, as docx4j's JAXB getters read them (CR-012
+     * section 20).
+     */
+    private image;
+    private imageOf;
+    /**
+     * `mce.branches_differ` (REQ-307): where the selected branch and another both hold text, and the texts
+     * differ after REQ-1201's normalisation. A branch's text is every `w:t`, `m:t` and `a:t` in it, whatever
+     * the view and hidden or not, as docx4j reads it: a comparison made at load knows no view, and a branch
+     * that differs only in hidden or deleted text is one an agent should hear of (Jason, 2026-10-21, for WD
+     * 0.29; CR-012 section 15.6). `mce.nothing_selected` (REQ-305): where the element has Choices and nothing is selected.
+     */
+    private compareBranches;
+    /** `mce.nothing_selected`, its selector the part and its `detail` the namespaces (REQ-801). */
+    private nothingSelected;
+    /**
+     * What the walk can't meet, from the warnings the load's passes recorded on each part this reading took, none with an address:
+     * `mce.nothing_selected` for an element a resolving load took out or one at a part's root (CR-029 section 3.5);
+     * `mce.undeclared_prefix` (REQ-323, CR-030), on a story part or the styles, numbering or settings part the reading consults;
+     * and `part.unexpected_root` (REQ-320, CR-028 D11).
+     */
+    private partWarningsUnmet;
+    /**
+     * A story part the reading takes that could not be read: none of its text, and `content.not_read` naming it (REQ-801),
+     * at the story's address prefix for a header or footer; docx4j's `storyContent` (`4fdd80063`).
+     */
+    private storyRead;
+    warn(w: TextWarning): void;
+    private sectionsWithHeaders;
+    private headerOrFooter;
+    /** A header or footer part's content as its own story (`Texts.of(headerPart)`). */
+    headerOrFooterPart(part: Part, kind: 'HEADER' | 'FOOTER', rId: string): TextResult;
+    private notes;
+    private comments;
+    /** Whether the view removes a list member (always false in markup and on a resolved copy). */
+    removes(item: unknown): boolean;
+    /** Whether the view takes a content control away and leaves its content (an inserted one, rejected). */
+    private unwraps;
+    private joinsNext;
+    /** The paragraph's properties in the view: its own, or what the plan gives a paragraph whose mark is gone with no paragraph next. */
+    private viewPPr;
+    private isHiddenRun;
+    /**
+     * A run's formatting beyond its paragraph style's (CR-046 phase 3): bold, italic, struck through,
+     * monospaced, each as the run's own property gives it, else its styles', where the paragraph style
+     * alone doesn't give it. And, whatever the paragraph style says, what the text shows (docx4j CR-069;
+     * CR-012 section 24): its case, folded the same way, a run under both caps and small caps being caps
+     * (WD REQ-607); its vertical alignment (REQ-710); and a cased run's language. A run carrying only that.
+     */
+    private formatOf;
+    /**
+     * The language a cased run's capitals are mapped by (WD REQ-607): its own `w:lang/@w:val`, else its styles' (with the
+     * document defaults'), else the `default_language` option. `w:themeFontLang` is no link (WD 0.80, CR-012 section 24.8):
+     * it chooses among the theme's fonts, and Word cases such a run by its editing language, which the option stands in for.
+     */
+    private language;
+    /** The run's font for `monospace`: its own `w:rFonts/@w:ascii`, else its styles'. */
+    private runFont;
+    /** The effective run properties of the paragraph's style and a character style, cached by their ids; undefined without styles. */
+    private styleRPr;
+    private isHiddenMark;
+}
+/** A TOC field's instruction: a table of contents, of figures (`\c`), of anything it collects. */
+export declare function isTocField(instr: string): boolean;
+/**
+ * A HYPERLINK field's target from its instruction (WD REQ-703): its address, and `#` and the bookmark its
+ * `\l` names; undefined for any other field, or one with neither.
+ */
+export declare function fieldHyperlinkTarget(instr: string): string | undefined;
+export {};