@docx4j/core-ts 0.4.0 → 0.6.0

package/dist/model/text/TextResult.mjs

@@ -0,0 +1,526 @@
+// The tree objects a block or run was read from: kept out of the block model's JSON (REQ-706 holds no
+// tree objects; CR-012 section 4.4), so held here rather than as properties.
+const blockSources = new WeakMap();
+const blockJoins = new WeakMap();
+const runSources = new WeakMap();
+/**
+ * A run's revision in the `markup` view (WD REQ-706): `w:ins` and `w:moveTo` are insertions, `w:del`
+ * and `w:moveFrom` deletions, with their author and date as written. docx4j `TextRevision`.
+ */
+export class TextRevision {
+    constructor(type, author, 
+    /** The date as the package wrote it (`w:date`), or undefined. */
+    date) {
+        this.type = type;
+        this.author = author;
+        this.date = date;
+    }
+    equals(o) {
+        return o !== undefined && this.type === o.type && this.author === o.author && this.date === o.date;
+    }
+    toString() {
+        return this.type + (this.author === undefined ? '' : ` by ${this.author}`) + (this.date === undefined ? '' : ` ${this.date}`);
+    }
+}
+/**
+ * An image's description (WD REQ-514) and where it came from: the document's author, or a describer
+ * that generated it. Plain text writes it `[image: ...]` or `[image, generated: ...]` under
+ * `alt_text: true` (REQ-707). docx4j `ImageDescription`.
+ */
+export class ImageDescription {
+    constructor(text, provenance) {
+        this.text = text;
+        this.provenance = provenance;
+    }
+    /** An author's description. */
+    static author(text) {
+        return new ImageDescription(text, 'AUTHOR');
+    }
+    /** A generated description. */
+    static generated(text) {
+        return new ImageDescription(text, 'GENERATED');
+    }
+    toString() {
+        return this.provenance === 'GENERATED' ? `generated: ${this.text}` : this.text;
+    }
+}
+/**
+ * A picture as the document gives it, for an `ImageDescriber` (WD REQ-514): its alt text
+ * (`wp:docPr/@descr`, or VML's `v:shape/@alt`), its name and title, whether it is marked decorative
+ * (`adec:decorative`), and its image part where the package holds one. The title is never read as text.
+ * docx4j `TextImage`.
+ */
+export class TextImage {
+    constructor(
+    /**
+     * The alt text: `wp:docPr/@descr` (or a nested picture's `pic:cNvPr/@descr`), `''` where a DrawingML picture has
+     * none (the schema's default); VML `v:shape/@alt`.
+     */
+    descr, 
+    /** `wp:docPr/@name` (`pic:cNvPr/@name`); undefined for a VML picture. */
+    name, 
+    /** `wp:docPr/@title`, `''` where it has none (the schema's default); undefined for a VML picture. */
+    title, 
+    /** True for a picture marked decorative (`adec:decorative val="1"` in `wp:docPr`'s extensions). */
+    decorative, 
+    /** True for a VML picture (`v:shape` with `v:imagedata`). */
+    vml, 
+    /**
+     * The image part (`a:blip/@r:embed`, else its `asvg:svgBlip`'s; `v:imagedata/@r:id`), or undefined
+     * for a linked or missing one.
+     */
+    part, 
+    /** The tree object the picture is read from: a `wp:inline`, `wp:anchor`, `pic:pic` or `v:shape`. */
+    source) {
+        this.descr = descr;
+        this.name = name;
+        this.title = title;
+        this.decorative = decorative;
+        this.vml = vml;
+        this.part = part;
+        this.source = source;
+    }
+    toJSON() {
+        var _a;
+        return { descr: this.descr, name: this.name, title: this.title, decorative: this.decorative, vml: this.vml, part: (_a = this.part) === null || _a === void 0 ? void 0 : _a.partName.name };
+    }
+}
+/**
+ * The default `ImageDescriber` (WD REQ-514): the author's alt text, `wp:docPr/@descr`, else the
+ * picture's `@name`; for VML, `v:shape/@alt`; nothing for a picture marked decorative.
+ * docx4j `AltTextDescriber`.
+ */
+export const AltTextDescriber = {
+    INSTANCE: ((image) => {
+        if (!image || image.decorative)
+            return undefined;
+        if (image.descr)
+            return ImageDescription.author(image.descr);
+        if (image.name)
+            return ImageDescription.author(image.name);
+        return undefined;
+    }),
+};
+/**
+ * A piece of a block's content (WD REQ-706): document text, or a typed item whose text, if any, the
+ * serialiser adds (a note reference is written `[n]` in plain text, REQ-707; it is a field of the run
+ * here, never text). docx4j `TextRun`.
+ *
+ * `source` and `officeOffset` are this package's (CR-012 section 4.4; WD REQ-202's emulated-API
+ * exemption): where the run's text was read from, and where it lies in its paragraph's `Paragraph.text`.
+ */
+export class TextRun {
+    constructor(kind, 
+    /** The text: the document's for `TEXT`, `FIELD_CODE` and `LIST_LABEL`; empty for the others. */
+    text, 
+    /** The run's revision in the `markup` view; undefined in the other views and for an unrevised run. */
+    revision) {
+        this.kind = kind;
+        this.text = text;
+        this.revision = revision;
+        /** True for hidden text included under `hidden: true` (REQ-507). */
+        this.hidden = false;
+        /** True for a content control's placeholder text (REQ-508). */
+        this.placeholder = false;
+        /** For a note reference or mark: its number in reference order, from 1; 0 for a custom mark. */
+        this.noteNumber = 0;
+        /** For a page marker: the number of the page that begins there, from 2. */
+        this.pageNumber = 0;
+        /** Bold where its paragraph's style is not: the run's `w:b`, else its styles' (CR-046 phase 3). */
+        this.bold = false;
+        /** Italic where its paragraph's style is not. */
+        this.italic = false;
+        /** Struck through where its paragraph's style is not. */
+        this.strike = false;
+        /** In a monospaced font where its paragraph's style is not in one. */
+        this.monospace = false;
+        /** True for an equation (REQ-604). */
+        this.math = false;
+        /** True for a display equation (`m:oMathPara`). */
+        this.displayMath = false;
+    }
+    /** Where the run's text was read from (not in the JSON). */
+    get source() {
+        return runSources.get(this);
+    }
+    set source(value) {
+        if (value)
+            runSources.set(this, value);
+        else
+            runSources.delete(this);
+    }
+    /** Whether two runs' text can be one run: the same formatting, link and equation. */
+    sameFormat(o) {
+        return this.bold === o.bold && this.italic === o.italic && this.strike === o.strike && this.monospace === o.monospace
+            && this.link === o.link && this.math === o.math && this.displayMath === o.displayMath;
+    }
+    copyFormat(from) {
+        this.bold = from.bold;
+        this.italic = from.italic;
+        this.strike = from.strike;
+        this.monospace = from.monospace;
+        this.link = from.link;
+        this.math = from.math;
+        this.displayMath = from.displayMath;
+    }
+    toString() {
+        return this.kind + (this.text === '' ? '' : ` '${this.text}'`) + (this.revision ? ` [${this.revision.toString()}]` : '');
+    }
+}
+/**
+ * A field in a block (WD REQ-505): its instruction, and its cached result, undefined where it has none.
+ * docx4j `TextField`.
+ */
+export class TextField {
+    constructor(
+    /** The instruction (`w:instrText`, `w:fldSimple/@instr`), as written. */
+    instr, 
+    /** The cached result's text in the view; undefined for a field with none. */
+    result, 
+    /** True when the result was computed under `fields: update` (REQ-506), rather than cached. */
+    updated = false) {
+        this.instr = instr;
+        this.result = result;
+        this.updated = updated;
+    }
+    toString() {
+        return `field{${this.instr}${this.updated ? ' => ' : ' -> '}${String(this.result)}}`;
+    }
+}
+/**
+ * A paragraph's numbering, as its effective `w:numPr` and the numbering definitions give it: what
+ * Markdown's list markers are made from (WD REQ-510, REQ-703). The label itself is the block's
+ * `listLabel`, under `list_labels: true`. docx4j `TextNumbering`.
+ */
+export class TextNumbering {
+    constructor(
+    /** The `w:numId`. */
+    numId, 
+    /** The level, `w:ilvl`: 0 to 8. */
+    level, 
+    /** The level's `w:numFmt` value, or undefined where the definitions don't give one. */
+    format, 
+    /** The level's `w:lvlText` value, or undefined. */
+    levelText, 
+    /** The level's `w:start`: 1 where it has none. */
+    start) {
+        this.numId = numId;
+        this.level = level;
+        this.format = format;
+        this.levelText = levelText;
+        this.start = start;
+    }
+    /** True for a bullet level. */
+    get bullet() {
+        return this.format === 'bullet';
+    }
+    /** True for a level that is a label rather than a number: not a bullet, and its format `none` or its text with no `%n`. */
+    get label() {
+        if (this.bullet || (this.format === undefined && this.levelText === undefined))
+            return false;
+        return this.format === 'none' || this.levelText === undefined || !this.levelText.includes('%');
+    }
+    toString() {
+        return `${this.numId}/${this.level} ${String(this.format)} '${String(this.levelText)}' from ${this.start}${this.value === undefined ? '' : ` = ${this.value}`}`;
+    }
+}
+/**
+ * A table row of the block model: its cells, and whether it is a header row (`w:tblHeader`).
+ * docx4j `TextRow`.
+ */
+export class TextRow {
+    constructor(address) {
+        this.address = address;
+        this.cells = [];
+        /** True for a row marked `w:tblHeader`. */
+        this.header = false;
+    }
+}
+/**
+ * A table cell of the block model: its blocks (paragraphs, and nested tables), how many grid columns it
+ * spans, and whether it is in a vertical merge. docx4j `TextCell`.
+ */
+export class TextCell {
+    constructor(address) {
+        this.address = address;
+        this.blocks = [];
+        /** `w:gridSpan`, 1 by default. */
+        this.gridSpan = 1;
+        /** True for a cell continuing a vertical merge (`w:vMerge` without `restart`). */
+        this.mergeContinue = false;
+        /** True for a cell starting a vertical merge (`w:vMerge w:val="restart"`). */
+        this.mergeRestart = false;
+    }
+}
+/**
+ * A block of the block model (WD REQ-706): a paragraph, a table whose cells hold blocks, or a chart. A
+ * paragraph's text is its runs' in the view; what an extractor adds in plain text (note numbers, a
+ * table-format note, an image's bracket) is not in it, but carried as fields (REQ-707). docx4j `TextBlock`.
+ *
+ * Addresses are CR-002 section 3.3's ordinal form, on the unresolved document (REQ-405, REQ-518):
+ * `body/3`, `body/4/1/0/2` (a table's row 1, cell 0, block 2), `header:rId3/0`, `footnote:2/0`,
+ * `comment:5/0`, and what follows an anchoring paragraph is addressed from it, each kind counted apart
+ * (REQ-519): `body/3/textbox:0/1` (legacy WordArt too), `body/3/chart:0`, `body/3/smartart:0/1`,
+ * `body/3/object:0/...`, `body/7/altchunk:0/...`; the glossary's `glossary:0/1`. A paragraph joined to
+ * the next in the `accepted` view (a deleted mark) takes the first paragraph's address and `w14:paraId`.
+ */
+export class TextBlock {
+    constructor(kind, 
+    /** The story; not readonly, since an embedded package's or a chunk's content takes the story it is read into. */
+    story, address) {
+        this.kind = kind;
+        this.story = story;
+        this.address = address;
+        this.runs = [];
+        /** The fields whose result or instruction is in the block (REQ-505). */
+        this.fields = [];
+        /** A table's rows; empty for a paragraph. */
+        this.rows = [];
+        /** True for a hidden paragraph included under `hidden: true`: its runs and mark are hidden (REQ-507). */
+        this.hidden = false;
+        /** How many revisions (run-level revisions and paragraph marks) the block's paragraphs hold, in any view. */
+        this.revisions = 0;
+        /** True when every text run is in a monospaced font, and at least one is. */
+        this.monospace = false;
+        /** True when the paragraph has a bottom border of its own (`w:pBdr/w:bottom` in its `w:pPr`). */
+        this.bottomBorder = false;
+        /** For a note's block: the note's number in reference order; else 0. */
+        this.noteNumber = 0;
+        /** The section the block ends or is in (main story only). */
+        this.section = 0;
+        /** For a table: always written in REQ-605's simple form (an embedded workbook's sheet). */
+        this.simpleForm = false;
+        /** For a chart: its table's column headings. */
+        this.chartHeader = [];
+        /** For a chart: its table's rows. */
+        this.chartRows = [];
+    }
+    /**
+     * What the block was read from (CR-012 section 4.4; not in the JSON): a paragraph's `w:p` (a joined
+     * block's first, as its paraId is, REQ-405), a table's `w:tbl`, a bound control's `w:sdt`; undefined
+     * for a block the model makes (a chart, a WordArt line).
+     */
+    get source() {
+        return blockSources.get(this);
+    }
+    set source(value) {
+        if (value)
+            blockSources.set(this, value);
+        else
+            blockSources.delete(this);
+    }
+    /**
+     * For a paragraph the view joins to the paragraphs after it (a deleted mark in `accepted`, an inserted one
+     * in `original`), their addresses, in order; empty for any other block (CR-012 section 17.13; not in the JSON).
+     */
+    get joined() {
+        var _a;
+        return (_a = blockJoins.get(this)) !== null && _a !== void 0 ? _a : [];
+    }
+    set joined(value) {
+        if (value.length > 0)
+            blockJoins.set(this, value);
+        else
+            blockJoins.delete(this);
+    }
+    /** True when the block holds placeholder text (REQ-508). */
+    get placeholder() {
+        return this.runs.some((r) => r.placeholder);
+    }
+    /** True for a block in a text box (REQ-518). */
+    get textbox() {
+        return this.story === 'TEXT_BOX';
+    }
+    /** True for a paragraph whose only content is one or more pictures marked decorative (REQ-514). */
+    get decorative() {
+        let decorative = false;
+        for (const r of this.runs) {
+            if (r.kind === 'IMAGE') {
+                if (!r.image || !r.image.decorative)
+                    return false;
+                decorative = true;
+            }
+            else if (r.kind === 'TEXT' && r.text !== '') {
+                return false;
+            }
+        }
+        return decorative;
+    }
+    /**
+     * The block's text in the view: its text runs (and field codes, where included); for a table, its
+     * rows a line apart, their cells a tab apart. No list label, note number or comment.
+     */
+    get text() {
+        var _a;
+        if (this.kind === 'CHART') {
+            let out = (_a = this.chartTitle) !== null && _a !== void 0 ? _a : '';
+            if (this.chartHeader.length > 0)
+                out += (out === '' ? '' : '\n') + this.chartHeader.join('\t');
+            for (const row of this.chartRows)
+                out += `\n${row.join('\t')}`;
+            return out;
+        }
+        if (this.kind === 'TABLE') {
+            return this.rows.map((row) => row.cells.map((cell) => cell.blocks.map((b) => b.text).join(' ')).join('\t')).join('\n');
+        }
+        let out = '';
+        for (const r of this.runs)
+            if (r.kind === 'TEXT' || r.kind === 'FIELD_CODE')
+                out += r.text;
+        return out;
+    }
+    /** The block model's JSON (REQ-706): the fields, the text and the flags; never a tree object. */
+    toJSON() {
+        const out = { ...this, text: this.text, placeholder: this.placeholder, textbox: this.textbox, decorative: this.decorative };
+        if (this.kind !== 'CHART') {
+            delete out.chartTitle;
+            delete out.chart;
+            delete out.chartHeader;
+            delete out.chartRows;
+        }
+        return out;
+    }
+    toString() {
+        return `${this.address} ${this.story} '${this.text}'`;
+    }
+}
+/**
+ * A comment (WD REQ-504): its author, date and blocks, the comment it replies to, and whether it is
+ * resolved (`w15:done`). Plain text renders a comment at its reference, replies after it. docx4j `TextComment`.
+ */
+export class TextComment {
+    constructor(/** The comment's `w:id`. */ id) {
+        this.id = id;
+        /** True when the comment is resolved (`w15:done`). */
+        this.resolved = false;
+        this.blocks = [];
+        /** The replies, in the comments part's order. */
+        this.replies = [];
+    }
+    /** The comment's text: its blocks a line apart. */
+    get text() {
+        return this.blocks.map((b) => b.text).join('\n');
+    }
+    toJSON() {
+        return { id: this.id, author: this.author, initials: this.initials, date: this.date, parentId: this.parentId, resolved: this.resolved, blocks: this.blocks, replies: this.replies.map((r) => r.id) };
+    }
+}
+/**
+ * Where a result is not the whole document (WD section 8, REQ-801): a kind, the address it is at where
+ * there is one, and its selector: for `mce.branches_differ` the name of the branch selected, for
+ * `altchunk.not_expanded` the chunk's content type, for `content.not_read` and `image.not_described` the
+ * part's name. Never the document's text (REQ-802). docx4j `TextWarning`.
+ */
+export class TextWarning {
+    constructor(kind, 
+    /** The address of the block it is in (REQ-518's grammar), or undefined. */
+    address, 
+    /** For `mce.branches_differ`, the selected branch (`mc:Choice Requires="wps"`, `mc:Fallback`). */
+    branch, 
+    /** For `altchunk.not_expanded`, the chunk's content type as the package declares it. */
+    contentType, 
+    /** For `content.not_read` and `image.not_described`, the part's name. */
+    partName) {
+        this.kind = kind;
+        this.address = address;
+        this.branch = branch;
+        this.contentType = contentType;
+        this.partName = partName;
+    }
+    /** The selector of REQ-801: the branch, the content type or the part's name, whichever the kind has. */
+    get selector() {
+        var _a, _b;
+        return (_b = (_a = this.branch) !== null && _a !== void 0 ? _a : this.contentType) !== null && _b !== void 0 ? _b : this.partName;
+    }
+    /** The identity a result keeps each warning once by. */
+    get key() {
+        return [this.kind, this.address, this.branch, this.contentType, this.partName].map((v) => v !== null && v !== void 0 ? v : '\u0000').join('\u0001');
+    }
+    toJSON() {
+        return { kind: this.kind, address: this.address, selector: this.selector };
+    }
+    toString() {
+        return this.kind + (this.address === undefined ? '' : ` at ${this.address}`) + (this.branch === undefined ? '' : ` (${this.branch})`)
+            + (this.contentType === undefined ? '' : ` (${this.contentType})`) + (this.partName === undefined ? '' : ` (${this.partName})`);
+    }
+}
+/** Both branches of an `mc:AlternateContent` hold text, and the texts differ (REQ-307). */
+TextWarning.MCE_BRANCHES_DIFFER = 'mce.branches_differ';
+/** A field with no cached result (REQ-505). */
+TextWarning.FIELD_NO_RESULT = 'field.no_result';
+/** A data-bound control whose surface differs from its bound value (REQ-509). */
+TextWarning.SDT_BINDING_DIFFERS = 'sdt.binding_differs';
+/** An `altChunk` not expanded (REQ-513). */
+TextWarning.ALTCHUNK_NOT_EXPANDED = 'altchunk.not_expanded';
+/** A chart, a SmartArt data part, or an embedded package or a part inside it, that can't be read. */
+TextWarning.CONTENT_NOT_READ = 'content.not_read';
+/** An image the `ImageDescriber` failed to describe (REQ-514). */
+TextWarning.IMAGE_NOT_DESCRIBED = 'image.not_described';
+/**
+ * A text in the block model (WD sections 7.4 and 8): the blocks in reading order, the comments, the
+ * warnings and the metadata. Plain text (`PlainText`) and the other serialisations are written from it
+ * (REQ-202). docx4j `TextResult`.
+ */
+export class TextResult {
+    constructor(
+    /** The blocks in reading order (REQ-501, REQ-502, REQ-518, REQ-606). Comments are not among them. */
+    blocks, 
+    /** The comments the view includes, by `w:id`, in the comments part's order (REQ-504). */
+    comments, 
+    /** The warnings raised (REQ-801), never with the document's text (REQ-802). */
+    warnings, 
+    /**
+     * The result's metadata (REQ-801, REQ-515), whatever the options: `fields_update_on_open`, and the
+     * document properties under `core`, `app` and `custom`, each a record, present when the package has
+     * that part. Property values are document text, in the text stream only under `metadata: true`.
+     */
+    metadata, 
+    /** The options the result was made with. */
+    options) {
+        this.blocks = blocks;
+        this.comments = comments;
+        this.warnings = warnings;
+        this.metadata = metadata;
+        this.options = options;
+    }
+    /**
+     * Several results as one, in the order given (CR-012 section 4.4): the blocks one after another, the
+     * comments together, each warning once, the metadata and options the first's. What the editor
+     * assembles from its per-part calls under one `TextContext`.
+     */
+    static concat(...results) {
+        if (results.length === 0)
+            throw new RangeError('TextResult.concat needs a result');
+        const blocks = [];
+        const comments = new Map();
+        const warnings = [];
+        const seen = new Set();
+        const metadata = {};
+        for (const r of results) {
+            blocks.push(...r.blocks);
+            for (const [id, c] of r.comments)
+                if (!comments.has(id))
+                    comments.set(id, c);
+            for (const w of r.warnings)
+                if (!seen.has(w.key)) {
+                    seen.add(w.key);
+                    warnings.push(w);
+                }
+            for (const [k, v] of Object.entries(r.metadata))
+                if (!(k in metadata))
+                    metadata[k] = v;
+        }
+        return new TextResult(blocks, comments, warnings, metadata, results[0].options);
+    }
+    toJSON() {
+        return { blocks: this.blocks, comments: Object.fromEntries(this.comments), warnings: this.warnings, metadata: this.metadata, options: this.options };
+    }
+}
+/** The metadata's key for the settings' `w:updateFields` (REQ-506, REQ-801): a boolean. */
+TextResult.FIELDS_UPDATE_ON_OPEN = 'fields_update_on_open';
+/** The metadata's key for the core properties (REQ-515): each property's element name to its value. */
+TextResult.CORE = 'core';
+/** The metadata's key for the application properties (REQ-515), the statistics left out. */
+TextResult.APP = 'app';
+/** The metadata's key for the custom properties (REQ-515): each property's name to its typed value. */
+TextResult.CUSTOM = 'custom';

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

@@ -0,0 +1,99 @@
+import { Part } from '../../parts/Part.mjs';
+import { TextOptions, type TextOptionsInit } from './TextOptions.mjs';
+import { TextResult } from './TextResult.mjs';
+import { TextContext, type TextPackage } from './TextContext.mjs';
+type Options = TextOptionsInit | TextOptions | undefined;
+declare function optionsOf(options: Options): TextOptions;
+declare function isPackage(value: unknown): value is TextPackage;
+/**
+ * docx4j's text model (its CR-046; the portfolio's *WordprocessingML Text Extraction*, WD): a text is
+ * `serialize(scope(view(resolve(package))))` (WD REQ-201). `Texts.of` makes the block model
+ * (`TextResult`); `PlainText.of` writes plain text from it.
+ *
+ * ```ts
+ * const result = await Texts.of(pkg, { view: 'markup', include: ['headers', 'footers'], hidden: true });
+ * PlainText.of(result);
+ * result.warnings;
+ * ```
+ *
+ * - **resolve**: each `mc:AlternateContent` is read from the branch the content API reads
+ *   (`selectedBranchOf`, CR-010), so that the text model and `Paragraph.text` take the same branch.
+ * - **view**: `accepted` (the default), `original` or `markup`; the first two are the text of the document
+ *   `acceptAllRevisions` or `rejectAllRevisions` leaves, worked out without resolving anything
+ *   (`ResolvedView`), held equal to that copy route by the agreement test (REQ-406).
+ * - **scope**: the main story, each text box once after its anchoring paragraph (after the table for one in
+ *   a cell), then the footnotes and endnotes in reference order; headers, footers and comments where
+ *   included, and the glossary, last, under `include: glossary`; hidden text excluded; placeholders
+ *   included; a bound control's value from its custom XML part; images' descriptions by an
+ *   `ImageDescriber`; the document properties in the metadata.
+ *
+ * **Not yet** (CR-012 section 5): `fields: update` and `embedded: true` are refused (REQ-1001); an equation
+ * is its text inside `$...$`, not LaTeX (phase 5b); a chart or SmartArt contributes nothing (5c); an
+ * `altChunk` is not expanded and raises `altchunk.not_expanded` (5e).
+ *
+ * **The package is never changed** (REQ-204): every part is read with `readContents()`, the live tree where
+ * the part is unmarshalled and a private one where it is not, so a save afterwards is byte for byte where it
+ * was before.
+ *
+ * **Cost.** Each call reads every story and, in the `accepted` and `original` views, their tracked changes
+ * once, whether it reads the whole package or one paragraph of it. A `TextContext` (`contextOf`) holds what
+ * was read, so calls under one context read it once.
+ *
+ * **Not Office JS's text.** `Paragraph.text` and the other Office JS readers keep Office JS's text (CR-012
+ * D2, REQ-202's emulated-API exemption); each `TextRun` records where its text lies in its paragraph's
+ * `Paragraph.text` (`officeOffset`), so that the two map onto each other.
+ */
+export declare class Texts {
+    private constructor();
+    /** The text of a package (REQ-501's scope), or of one story part, or of content in a package. */
+    static of(pkg: TextPackage, options?: Options, context?: TextContext): Promise<TextResult>;
+    /**
+     * The text of one story part, as its own story: the main document part (its story and text boxes; the
+     * notes it references numbered in the context, not read), a header or a footer (addressed
+     * `header:rId3/...`), the footnotes or endnotes part (the notes the context's stories referenced, in
+     * reference order; under a context that has not read the main story, the main story is read first, for
+     * the order alone), or the comments part (the comments the view includes, in `TextResult.comments`).
+     * The part must belong to a package. Read them in REQ-501's order under one context and
+     * `TextResult.concat` the results to have the package's text.
+     */
+    static of(part: Part, options?: Options, context?: TextContext): Promise<TextResult>;
+    /**
+     * The text of content in a package (a paragraph, a table, a body, a header's content), as the main story:
+     * the view is the package's, so a join or a move is resolved as in the whole document. Its addresses
+     * start `content`. The content is the package's own tree, its part unmarshalled (`getContents()`): a part
+     * that is not is read privately, afresh for each context, and the views' plan is made over that reading.
+     */
+    static of(pkg: TextPackage, content: object, options?: Options, context?: TextContext): Promise<TextResult>;
+    /**
+     * The text of content with no package: in the `accepted` and `original` views only run-level revisions
+     * are resolved (no paragraph is joined, a move is its two halves), and hidden text is only what the runs
+     * themselves hide, since there are no styles.
+     */
+    static of(content: object, options?: Options): Promise<TextResult>;
+    private static ofContent;
+    private static ofPart;
+    /**
+     * The text of a package that `acceptAllRevisions` or `rejectAllRevisions` has already resolved, read with
+     * no view logic: the copy route of WD REQ-406, which the views of `Texts.of` are held equal to. The
+     * options' view says which resolution it was (`accepted` or `original`).
+     */
+    static ofResolved(resolved: TextPackage, options?: Options): Promise<TextResult>;
+    /** Plain text of a package (WD section 7.1): `PlainText.of(await Texts.of(pkg, options))`. */
+    static plainText(pkg: TextPackage, options?: Options): Promise<string>;
+    /**
+     * A context for calls over one package (CR-012 section 4.4): it reads the package's stories once, makes
+     * each view's plan once, and carries the note numbers, numbering states and bookmarks from one call to the
+     * next. A snapshot: after the package changes, make another.
+     */
+    static contextOf(pkg: TextPackage): Promise<TextContext>;
+    /** WD REQ-1201's normalisation, under which texts are compared. */
+    static normalize(value: string | undefined | null): string;
+    private static context;
+}
+/**
+ * The context a call reads under: the one given, checked against the package and the view, or a new one
+ * (internal: `Texts` and the outline reader share it).
+ */
+export declare function contextFor(pkg: TextPackage, given: TextContext | undefined, o: TextOptions): Promise<TextContext>;
+/** Options checked as `Texts.of` checks them (internal). */
+export { optionsOf, isPackage };