@docx4j/core-ts 0.5.0 → 0.6.0

package/dist/model/properties/catalogue.mjs

@@ -1,3 +1,4 @@
+import { WordColors } from '../color/WordColors.mjs';
 // ---------------------------------------------------------------- copying
 /**
  * A structural copy of a leaf value, without its `PARENT` link: what the merges store, so
@@ -36,6 +37,15 @@ function attr(source, destination) {
 function statesColour(val, theme) {
     return !emptyString(val) || !emptyThemeColor(theme);
 }
+/**
+ * docx4j `StyleUtil.statesWordColour` (its CR-060, 1d1b824a9): as {@link statesColour}, for a text or underline
+ * colour, whose value Word reads as absent where it rejects it ({@link WordColors.stated}: `F00`, `bogus`, `Auto`).
+ * A fill's or a border's colour keeps {@link statesColour}: Word reads any value there, one it rejects as automatic,
+ * which overrides a style's (CR-015 section 2, rule 5).
+ */
+function statesWordColour(val, theme) {
+    return WordColors.stated(val) || !emptyThemeColor(theme);
+}
 /** A merge with no per-attribute rule: a copy of the source where it has one, else the inherited. */
 export function mergeReplace(source, destination) {
     return source === undefined ? destination : copyLeaf(source);
@@ -76,21 +86,37 @@ export function isEmptyRFonts(value) {
 }
 /**
  * A `w:color` stating only a theme colour is not empty: it is inherited, where until docx4j CR-034
- * (2e381ef26) it was dropped.
+ * (2e381ef26) it was dropped. A value Word reads as absent (`F00`, `bogus`, `Auto`) is empty, so a style's
+ * colour beneath still shows, and only exactly `auto` overrides it (docx4j CR-060, {@link WordColors.stated};
+ * CR-015 section 2, rules 4 and 5).
  */
 export function isEmptyColor(value) {
     return value === undefined
-        || (emptyString(value.val) && value.themeColor === undefined
+        || (!WordColors.stated(value.val) && value.themeColor === undefined
             && emptyString(value.themeTint) && emptyString(value.themeShade));
 }
-/** The underline's colour attributes count, the theme ones too (docx4j CR-034, 2e381ef26). */
+/**
+ * The underline's colour attributes count, the theme ones too (docx4j CR-034, 2e381ef26); a colour Word reads as
+ * absent doesn't (docx4j CR-060, {@link WordColors.stated}).
+ */
 export function isEmptyU(value) {
     return value === undefined
-        || (value.val === undefined && emptyString(value.color) && value.themeColor === undefined
+        || (value.val === undefined && !WordColors.stated(value.color) && value.themeColor === undefined
             && emptyString(value.themeTint) && emptyString(value.themeShade));
 }
+/** `ST_HighlightColor`'s values, which Word compares case-exactly (docx4j `WordRepairs`). */
+const HIGHLIGHT_COLORS = new Set(['black', 'blue', 'cyan', 'green', 'magenta', 'red', 'yellow',
+    'white', 'darkBlue', 'darkCyan', 'darkGreen', 'darkMagenta', 'darkRed', 'darkYellow', 'darkGray', 'lightGray', 'none']);
+/** Whether a `w:highlight` value is one of `ST_HighlightColor`'s, compared case-exactly, as Word does (docx4j `WordRepairs.isHighlightColor`). */
+export function isHighlightColor(val) {
+    return val !== undefined && HIGHLIGHT_COLORS.has(val);
+}
+/**
+ * A value outside `ST_HighlightColor` (`YELLOW`, `bogus`), or none, is empty: Word's repair drops it, so a style's
+ * highlight beneath still shows (docx4j CR-060, its `StyleUtil.isEmpty(Highlight)`).
+ */
 export function isEmptyHighlight(value) {
-    return value === undefined || emptyString(value.val);
+    return value === undefined || !isHighlightColor(value.val);
 }
 /** @since CR-015 phase 1: a style stating only `w:lang` used to count as empty and was never applied. */
 export function isEmptyLang(value) {
@@ -151,16 +177,18 @@ export function isEmptyNumPr(value) {
         || ((value.numId === undefined || value.numId.val === undefined)
             && (value.ilvl === undefined || value.ilvl.val === undefined));
 }
-/** `w:anchorLock` defaults to true, so only an explicit `w:anchorLock="0"` makes a frame non-empty by itself. */
+/**
+ * Empty only with `w:anchorLock` absent too, as docx4j 82c64bf14 reads it (its CR-059: until then
+ * `isAnchorLock()`, which the schema's old `default="true"` made true for an absent attribute).
+ */
 export function isEmptyFramePr(value) {
-    var _a;
     return value === undefined
         || (value.dropCap === undefined && value.lines === undefined && value.w === undefined
             && value.h === undefined && value.vSpace === undefined && value.hSpace === undefined
             && value.wrap === undefined && value.hAnchor === undefined && value.vAnchor === undefined
             && value.x === undefined && value.xAlign === undefined
             && value.y === undefined && value.yAlign === undefined && value.hRule === undefined
-            && ((_a = value.anchorLock) !== null && _a !== void 0 ? _a : true));
+            && value.anchorLock === undefined);
 }
 function isEmptyTblWidth(value) {
     // @w:type is ignored, as docx4j does
@@ -317,7 +345,7 @@ export const mergeColor = (source, destination) => {
         return destination;
     const s = source;
     const out = (destination !== null && destination !== void 0 ? destination : {});
-    if (statesColour(s.val, s.themeColor)) {
+    if (statesWordColour(s.val, s.themeColor)) {
         out.val = s.val;
         out.themeColor = s.themeColor;
         out.themeTint = s.themeTint;
@@ -336,7 +364,7 @@ export const mergeU = (source, destination) => {
     const s = source;
     const out = destination !== null && destination !== void 0 ? destination : {};
     out.val = attr(s.val, out.val);
-    if (statesColour(s.color, s.themeColor)) {
+    if (statesWordColour(s.color, s.themeColor)) {
         out.color = s.color;
         out.themeColor = s.themeColor;
         out.themeTint = s.themeTint;
@@ -536,11 +564,10 @@ export const mergeTabs = (source, destination) => {
 };
 /**
  * `w:framePr`'s attributes each inherit on their own: a paragraph whose direct `w:framePr`
- * gives only `w:x`/`w:y` keeps the anchors its style states. `w:anchorLock` defaults to true,
- * and docx4j's merge writes that default out explicitly.
+ * gives only `w:x`/`w:y` keeps the anchors its style states, `w:anchorLock` among them (docx4j
+ * 82c64bf14 merges it as stated; until then its merge wrote `isAnchorLock()`'s default out).
  */
 export const mergeFramePr = (source, destination) => {
-    var _a;
     if (isEmptyFramePr(source))
         return destination;
     const s = source;
@@ -559,8 +586,7 @@ export const mergeFramePr = (source, destination) => {
     out.y = attr(s.y, out.y);
     out.yAlign = attr(s.yAlign, out.yAlign);
     out.hRule = attr(s.hRule, out.hRule);
-    // docx4j reads this through isAnchorLock(), which answers true when the attribute is absent
-    out.anchorLock = (_a = s.anchorLock) !== null && _a !== void 0 ? _a : true;
+    out.anchorLock = attr(s.anchorLock, out.anchorLock);
     return out;
 };
 const mergeTblWidth = (source, destination) => {

package/dist/model/properties/log.d.mts

@@ -1,7 +1,7 @@
 export interface Logger {
     warn(message: string): void;
 }
-/** The logger property resolution writes to. */
+/** The logger property resolution and the Markdown export write to. */
 export declare const log: Logger;
 /** Replaces the sink; pass nothing to go back to `console.warn`. */
 export declare function setLogger(logger?: Logger): void;

package/dist/model/properties/log.mjs

@@ -1,7 +1,7 @@
-// The one place property resolution writes a diagnostic. docx4j logs through SLF4J; this
-// package has no logging framework, so a missing style or a style cycle goes to `console.warn`
-// behind a settable sink (an add-in that must stay silent, or a test that wants to assert what
-// was logged, replaces it).
+// The one place property resolution writes a diagnostic, and the Markdown export a refused link
+// target (CR-012 section 21). docx4j logs through SLF4J; this package has no logging framework, so
+// a missing style, a style cycle or a refused link goes to `console.warn` behind a settable sink
+// (an add-in that must stay silent, or a test that wants to assert what was logged, replaces it).
 //
 // Resolution logs a missing style *once per id* (a `w:pStyle` naming a deleted style is common
 // in real documents, and docx4j used to log one ERROR per paragraph); the resolver keeps that
@@ -13,7 +13,7 @@ const consoleLogger = {
     },
 };
 let sink = consoleLogger;
-/** The logger property resolution writes to. */
+/** The logger property resolution and the Markdown export write to. */
 export const log = {
     warn(message) {
         sink.warn(message);

package/dist/model/properties/table.mjs

@@ -110,14 +110,16 @@ export class TableContext {
             this.look = DEFAULT_LOOK;
         this.rowBandSize = (tblPr === null || tblPr === void 0 ? void 0 : tblPr.tblStyleRowBandSize) !== undefined ? rowBandSize(tblPr) : rowBandSize(stylePr);
         this.colBandSize = (tblPr === null || tblPr === void 0 ? void 0 : tblPr.tblStyleColBandSize) !== undefined ? colBandSize(tblPr) : colBandSize(stylePr);
-        const rows = rowsOf(tbl);
+        // the rows and cells Word reads: a kept row- or cell-level mc:AlternateContent's selected branch (CR-013
+        // phase 2), so that its rows count for the first row, the last and the bands
+        const rows = rowsOf(tbl, 'read');
         let cols = 0;
         rows.forEach((located, r) => {
             var _a, _b;
             const tr = located.element.value;
             this.rowIndex.set(tr, r);
             let c = gridOf(tr, 'gridBefore');
-            for (const cell of cellsOf(tr)) {
+            for (const cell of cellsOf(tr, 'read')) {
                 const tc = cell.element.value;
                 const val = (_b = (_a = tc.tcPr) === null || _a === void 0 ? void 0 : _a.gridSpan) === null || _b === void 0 ? void 0 : _b.val;
                 const span = typeof val === 'number' ? Math.max(1, Math.trunc(val)) : 1;

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

@@ -0,0 +1,289 @@
+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;
+    /** 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;
+    /** 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` and the document properties (REQ-801, REQ-515). */
+    private metadata;
+    private fieldsUpdateOnOpen;
+    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. */
+    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;
+    private paragraph;
+    private endSection;
+    private flushIfOutsideTable;
+    /** An `altChunk`: not expanded until CR-012 phase 5e, which raises `altchunk.not_expanded` 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;
+    /** 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. */
+    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).
+     */
+    private compareBranches;
+    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. A run carrying only that.
+     */
+    private formatOf;
+    /** 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 {};