@docx4j/core-ts 0.3.1 → 0.4.0

package/dist/model/content/Range.mjs

@@ -6,7 +6,7 @@ import { ContentControl } from './ContentControl.mjs';
 import { sdt as sdtOf, nextSdtId, applyRunOptions, t as textElement } from '@docx4j/generated-objects-ts/builders/wml';
 import { hyperlink as hyperlinkOf } from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
 import { Namespaces } from '../../parts/Namespaces.mjs';
-import { controlIdScope, sdtKindFor } from '../customxml/insert.mjs';
+import { controlIdScope, sdtKindFor, declareSdtExtensions } from '../customxml/insert.mjs';
 import { contentOf } from './ooxml.mjs';
 import { markHolderInserted } from './tracking.mjs';
 import { searchPattern, findAll, matchesOf, expandReplacement } from './search.mjs';
@@ -74,7 +74,7 @@ export class Range {
         };
         if ((options === null || options === void 0 ? void 0 : options.direct) === true)
             return new Font(holders, () => this.paragraph.fontTracking());
-        return new Font(holders, () => this.paragraph.fontTracking(), (rPr) => this.paragraph.parentBody.propertyResolver.getEffectiveRPr(rPr, this.paragraph.p.pPr), (rPr) => { var _a; return (_a = runFontSelectorOf(this.paragraph.parentBody.package_)) === null || _a === void 0 ? void 0 : _a.asciiFontName(rPr); });
+        return new Font(holders, () => this.paragraph.fontTracking(), (rPr) => this.paragraph.parentBody.propertyResolver.getEffectiveRPr(rPr, this.paragraph.p.pPr, this.paragraph.cellContext), (rPr) => { var _a; return (_a = runFontSelectorOf(this.paragraph.parentBody.package_)) === null || _a === void 0 ? void 0 : _a.asciiFontName(rPr); });
     }
     /** The runs the span covers (a run partly inside counts). */
     get runs() {
@@ -215,6 +215,7 @@ export class Range {
         // The control is built empty first: `sdt` refuses a kind that cannot be run-level (a repeating
         // section), and that refusal must come before any run is split.
         const sdt = sdtOf([], { kind: sdtKindFor(kind), id: nextSdtId(controlIdScope(body)), form: 'run' });
+        declareSdtExtensions(body, sdt);
         if (this.start === this.end) {
             paragraph.insertItemsAt(this.start, [sdt]);
             return new ContentControl(sdt, containerOf(sdt, paragraph), body);

package/dist/model/content/Table.d.mts

@@ -4,6 +4,7 @@ import type { Body } from './Body.mjs';
 import type { Paragraph } from './Paragraph.mjs';
 import type { Range } from './Range.mjs';
 import { type ChangeTracker } from './tracking.mjs';
+import { type TableLayoutMode } from './tableColumns.mjs';
 /**
  * A subset of Office JS `Word.Table` over a `w:tbl`. Rows are read through row-level content
  * controls (an OpenDoPE repeat wraps its `w:tr` in a `w:sdt`), so `rows` is what Word shows.
@@ -51,6 +52,30 @@ export declare class Table {
      * tracks changes the rows stay and take a `w:trPr/w:del` instead (CR-002 phase F).
      */
     deleteRows(rowIndex: number, rowCount?: number): void;
+    /**
+     * Adds columns at the start or the end (Office JS `Table.addColumns`), the new cells taking the
+     * properties and width of the column beside them - the one to the right of the boundary when
+     * there is one, else the left - in the table's layout mode as Word 365 writes it (CR-002 section
+     * 42, checks 39 and 40): fixed copies the width and grows the table past the margin, AutoFit to
+     * window rescales the grid and writes the cells' percentages again, AutoFit to contents stays
+     * automatic. `values` is by row, then by new column. Returns the new cells per row, an extension
+     * (Office JS returns nothing); a row whose skipped columns grew instead has none. Tracked, the
+     * table change is recorded as Office JS records one and the new cells' text is an insertion.
+     */
+    addColumns(location: 'Start' | 'End', columnCount: number, values?: string[][]): TableCell[][];
+    /**
+     * Removes `columnCount` grid columns from `columnIndex` (one by default; Office JS
+     * `Table.deleteColumns`): a cell covering only those columns goes, one spanning further shrinks.
+     * Tracked, the cells still go and the table change is recorded, as Office JS's deletion leaves
+     * it (section 42.3; check 40c; Word's own is not tracked at all, known issues entry 2).
+     */
+    deleteColumns(columnIndex: number, columnCount?: number): void;
+    /** Which of Word's three layout modes the table is in: fixed, AutoFit to window, or AutoFit to contents (extension). */
+    get layoutMode(): TableLayoutMode;
+    /** The section's text width in twips, for the window mode and a percentage width. */
+    textWidth(): number;
+    /** Views of new cells, row by row. */
+    cellViewsOf(cells: Element<wml.Tc>[][]): TableCell[][];
     /** Removes the table from its container; tracked, every row is marked deleted instead. */
     delete(): void;
     /** The package's change tracker while `changeTrackingMode` is on (CR-002 phase F). */
@@ -118,7 +143,20 @@ export declare class TableCell {
     insertText(text: string, location: 'Start' | 'End' | 'Replace'): Range;
     /** The cell width in points (w:tcW in twips), as Office JS reports it; 0 when it is not a fixed width. */
     get width(): number;
+    /**
+     * Written in the form the cell states, else its table, else twips (CR-002 section 42.2 item 4): a
+     * cell in percent takes the points as a share of the section's text width; `auto` becomes twips,
+     * a stated width being what was asked for.
+     */
     set width(points: number);
+    /**
+     * New columns before or after this cell (Office JS `TableCell.insertColumns`), the new cells
+     * taking this cell's properties and width, as `Table.addColumns` does. Returns the new cells per
+     * row (extension).
+     */
+    insertColumns(location: 'Before' | 'After', columnCount: number, values?: string[][]): TableCell[][];
+    /** Removes the grid columns this cell covers (Office JS `TableCell.deleteColumn`); tracked as `Table.deleteColumns` is. */
+    deleteColumn(): void;
     /** Office JS TableCell.columnWidth, the same value. */
     get columnWidth(): number;
     set columnWidth(points: number);

package/dist/model/content/Table.mjs

@@ -4,6 +4,7 @@ import { Docx4JException } from '../../opc/exceptions.mjs';
 import { typeNameOf, childrenOf, linkParents, textOf, rowsOf, cellsOf } from './tree.mjs';
 import { builtInOf, idOfBuiltIn, styleNameOf, styleIdOf } from './styles.mjs';
 import { trackInsertedBlocks } from './tracking.mjs';
+import { insertGridColumns, deleteGridColumns, gridRangeOf, textWidthTwips, widthTypeOf, layoutModeOf } from './tableColumns.mjs';
 /** The default table width in twips (A4 with 2.54 cm margins), as the objects package's `tbl` builder uses. */
 const DEFAULT_WIDTH = 9026;
 const TWIPS_PER_POINT = 20;
@@ -128,6 +129,51 @@ export class Table {
                 row.container.splice(i, 1);
         }
     }
+    /**
+     * Adds columns at the start or the end (Office JS `Table.addColumns`), the new cells taking the
+     * properties and width of the column beside them - the one to the right of the boundary when
+     * there is one, else the left - in the table's layout mode as Word 365 writes it (CR-002 section
+     * 42, checks 39 and 40): fixed copies the width and grows the table past the margin, AutoFit to
+     * window rescales the grid and writes the cells' percentages again, AutoFit to contents stays
+     * automatic. `values` is by row, then by new column. Returns the new cells per row, an extension
+     * (Office JS returns nothing); a row whose skipped columns grew instead has none. Tracked, the
+     * table change is recorded as Office JS records one and the new cells' text is an insertion.
+     */
+    addColumns(location, columnCount, values) {
+        const at = location === 'Start' ? 0 : this.columnWidths().length;
+        const inserted = insertGridColumns(this.tbl, this.textWidth(), at, columnCount, values, this.changeTracker);
+        return this.cellViewsOf(inserted.cells);
+    }
+    /**
+     * Removes `columnCount` grid columns from `columnIndex` (one by default; Office JS
+     * `Table.deleteColumns`): a cell covering only those columns goes, one spanning further shrinks.
+     * Tracked, the cells still go and the table change is recorded, as Office JS's deletion leaves
+     * it (section 42.3; check 40c; Word's own is not tracked at all, known issues entry 2).
+     */
+    deleteColumns(columnIndex, columnCount = 1) {
+        var _a, _b, _c;
+        deleteGridColumns(this.tbl, this.textWidth(), columnIndex, columnCount, this.changeTracker);
+        if (((_c = (_b = (_a = this.tbl.tblGrid) === null || _a === void 0 ? void 0 : _a.gridCol) === null || _b === void 0 ? void 0 : _b.length) !== null && _c !== void 0 ? _c : 0) === 0 || rowsOf(this.tbl).every((row) => cellsOf(row.element.value).length === 0))
+            this.delete();
+    }
+    /** Which of Word's three layout modes the table is in: fixed, AutoFit to window, or AutoFit to contents (extension). */
+    get layoutMode() {
+        return layoutModeOf(this.tbl);
+    }
+    /** The section's text width in twips, for the window mode and a percentage width. */
+    textWidth() {
+        return textWidthTwips(this.parentBody.container);
+    }
+    /** Views of new cells, row by row. */
+    cellViewsOf(cells) {
+        const rows = this.rows;
+        return cells.map((rowCells, i) => {
+            const row = rows[i];
+            if (!row || rowCells.length === 0)
+                return [];
+            return row.cells.filter((cell) => rowCells.includes(cell.element));
+        });
+    }
     /** Removes the table from its container; tracked, every row is marked deleted instead. */
     delete() {
         const tracker = this.changeTracker;
@@ -311,12 +357,44 @@ export class TableCell {
         const w = (_a = this.tc.tcPr) === null || _a === void 0 ? void 0 : _a.tcW;
         return (w === null || w === void 0 ? void 0 : w.type) === 'dxa' ? ((_b = w.w) !== null && _b !== void 0 ? _b : 0) / TWIPS_PER_POINT : 0;
     }
+    /**
+     * Written in the form the cell states, else its table, else twips (CR-002 section 42.2 item 4): a
+     * cell in percent takes the points as a share of the section's text width; `auto` becomes twips,
+     * a stated width being what was asked for.
+     */
     set width(points) {
         var _a, _b;
         var _c, _d;
+        const twips = Math.round(points * TWIPS_PER_POINT);
         const tcW = ((_b = (_d = ((_a = (_c = this.tc).tcPr) !== null && _a !== void 0 ? _a : (_c.tcPr = {}))).tcW) !== null && _b !== void 0 ? _b : (_d.tcW = {}));
-        tcW.w = Math.round(points * TWIPS_PER_POINT);
-        tcW.type = 'dxa';
+        if (widthTypeOf(this.tc, this.parentTable.tbl) === 'pct') {
+            tcW.w = Math.round((twips * 5000) / this.parentTable.textWidth());
+            tcW.type = 'pct';
+        }
+        else {
+            tcW.w = twips;
+            tcW.type = 'dxa';
+        }
+    }
+    /**
+     * New columns before or after this cell (Office JS `TableCell.insertColumns`), the new cells
+     * taking this cell's properties and width, as `Table.addColumns` does. Returns the new cells per
+     * row (extension).
+     */
+    insertColumns(location, columnCount, values) {
+        const range = gridRangeOf(this.parentRow.tr, this.tc);
+        if (!range)
+            throw new Docx4JException('This cell is not in its row');
+        const table = this.parentTable;
+        const inserted = insertGridColumns(table.tbl, table.textWidth(), location === 'Before' ? range.start : range.end, columnCount, values, table.changeTracker);
+        return table.cellViewsOf(inserted.cells);
+    }
+    /** Removes the grid columns this cell covers (Office JS `TableCell.deleteColumn`); tracked as `Table.deleteColumns` is. */
+    deleteColumn() {
+        const range = gridRangeOf(this.parentRow.tr, this.tc);
+        if (!range)
+            throw new Docx4JException('This cell is not in its row');
+        this.parentTable.deleteColumns(range.start, range.end - range.start);
     }
     /** Office JS TableCell.columnWidth, the same value. */
     get columnWidth() {

package/dist/model/content/index.d.mts

@@ -7,7 +7,8 @@ export { List, ListItem, ListItemNotFoundError, NumberingFacade, listsOf, listLa
 export { type Author, type CommentContent, type CommentOptions, type CommentEntry, type CommentParts, type CommentPartsAccess, type CommentsExtensible, type CommentMarker, COMMENT_TEXT_STYLE, COMMENT_REFERENCE_STYLE, markersOf, markersOfParagraph, commentIdsOf } from './comments.mjs';
 export { Font, type UnderlineType, type RPrHolder, type FontTracking } from './Font.mjs';
 export { Table, TableRow, TableCell, cellOf } from './Table.mjs';
-export { InlinePicture, imageInfoOf, naturalSizeEmu, addImage, writableWidthEmu, type ImageFormat, type ImageInfo, type InlinePictureOptions, type NewPicture } from './InlinePicture.mjs';
+export { layoutModeOf, textWidthTwips, gridWidthsOf, widthTypeOf, insertGridColumns, deleteGridColumns, gridRangeOf, type TableLayoutMode, type ColumnInsertion } from './tableColumns.mjs';
+export { InlinePicture, imageInfoOf, naturalSizeEmu, addImage, addImagePart, writableWidthEmu, type ImageFormat, type ImageInfo, type InlinePictureOptions, type NewPicture, type NewImagePart } from './InlinePicture.mjs';
 export { ContentControl, collectControls, collectRunControls, W14_NS, W15_NS, type ContentControlType, type ContentControlForm, type ContentControlAppearance } from './ContentControl.mjs';
 export { contentOf, isFlatOpc, rewriteRelationshipIds, type OoxmlOptions } from './ooxml.mjs';
 export { type SearchOptions, searchPattern, findAll, matchesOf, expandReplacement } from './search.mjs';

package/dist/model/content/index.mjs

@@ -9,7 +9,8 @@ export { List, ListItem, ListItemNotFoundError, NumberingFacade, listsOf, listLa
 export { COMMENT_TEXT_STYLE, COMMENT_REFERENCE_STYLE, markersOf, markersOfParagraph, commentIdsOf } from './comments.mjs';
 export { Font } from './Font.mjs';
 export { Table, TableRow, TableCell, cellOf } from './Table.mjs';
-export { InlinePicture, imageInfoOf, naturalSizeEmu, addImage, writableWidthEmu } from './InlinePicture.mjs';
+export { layoutModeOf, textWidthTwips, gridWidthsOf, widthTypeOf, insertGridColumns, deleteGridColumns, gridRangeOf } from './tableColumns.mjs';
+export { InlinePicture, imageInfoOf, naturalSizeEmu, addImage, addImagePart, writableWidthEmu } from './InlinePicture.mjs';
 export { ContentControl, collectControls, collectRunControls, W14_NS, W15_NS } from './ContentControl.mjs';
 export { contentOf, isFlatOpc, rewriteRelationshipIds } from './ooxml.mjs';
 export { searchPattern, findAll, matchesOf, expandReplacement } from './search.mjs';

package/dist/model/content/stylesFacade.d.mts

@@ -23,8 +23,10 @@ export declare class StylesFacade {
      *
      * A style already in the document is left exactly as it is - the document's own definition wins
      * over the default, always, since a consumer must not silently restyle a document it was asked to
-     * add a footnote to. An id the defaults do not carry throws a `Docx4JException` naming it: the
-     * caller asked for a definition nothing here has, and inventing one would be worse than saying so.
+     * add a footnote to. An id none of the sources carry - the defaults, the nine spliceable styles,
+     * the comment and placeholder styles, and Word's built-ins from docx4j's `KnownStyles.xml`
+     * (section 41) - throws a `Docx4JException` naming it: the caller asked for a definition nothing
+     * here has, and inventing one would be worse than saying so.
      * The whole closure is worked out before anything is written, so a call that throws has changed
      * nothing (CR-002 section 31).
      *

package/dist/model/content/stylesFacade.mjs

@@ -4,12 +4,17 @@ import { parseXml } from '../../xml/dom.mjs';
 import { DEFAULT_STYLES_XML } from '../../parts/wml/defaultStyles.mjs';
 import { SPLICEABLE_STYLES_XML } from '../../parts/wml/spliceableStyles.mjs';
 import { commentStyles } from '../../parts/wml/commentStyles.mjs';
+import { placeholderStyle } from '../../parts/wml/placeholderStyle.mjs';
+import { KNOWN_STYLES_XML } from '../../parts/wml/knownStyles.mjs';
 import { Docx4JException } from '../../opc/exceptions.mjs';
 /**
  * Where a definition is looked up, unmarshalled once and never handed out (a copy is spliced in):
  * the defaults `createPackage()` writes, and then the nine styles docx4j's own `styles.xml` carries
  * **commented out** - which is why a created document has no `FootnoteText` although the file
- * appears to contain one, and why this facade exists (CR-002 section 22.2).
+ * appears to contain one, and why this facade exists (CR-002 section 22.2) - with Word's two comment
+ * styles and its `PlaceholderText` after them, and last Word's 164 built-ins as docx4j's
+ * `KnownStyles.xml` carries them (CR-002 section 41: `Heading5`, `Quote`, `HTMLCode`, ...), the
+ * list numbering some of them name dropped, since no numbering definition comes with them.
  */
 let sources;
 function styleSources() {
@@ -17,8 +22,18 @@ function styleSources() {
         const read = async (xml) => { var _a; return (_a = (await unmarshalNode(parseXml(xml))).value.style) !== null && _a !== void 0 ? _a : []; };
         const defaults = await read(DEFAULT_STYLES_XML);
         // and Word's two comment styles, which the comment parts add when they are made, for a caller
-        // that makes the comment itself (CR-002 section 37)
-        return { defaults, all: [...defaults, ...(await read(SPLICEABLE_STYLES_XML)), ...commentStyles()] };
+        // that makes the comment itself (CR-002 section 37), and Word's PlaceholderText, which a
+        // placeholder run names (CR-002 section 40); then the known styles (section 41), each without
+        // the w:numPr the file left on the headings and list styles: it names a w:numId of the document
+        // the file was taken from, which the document being spliced into need not have, and a heading
+        // spliced with it would join a list that is not there (the editor's copy drops it the same way)
+        const known = (await read(KNOWN_STYLES_XML)).map((style) => {
+            var _a;
+            if ((_a = style.pPr) === null || _a === void 0 ? void 0 : _a.numPr)
+                delete style.pPr.numPr;
+            return style;
+        });
+        return { defaults, all: [...defaults, ...(await read(SPLICEABLE_STYLES_XML)), ...commentStyles(), placeholderStyle(), ...known] };
     })()));
 }
 /**
@@ -39,8 +54,10 @@ export class StylesFacade {
      *
      * A style already in the document is left exactly as it is - the document's own definition wins
      * over the default, always, since a consumer must not silently restyle a document it was asked to
-     * add a footnote to. An id the defaults do not carry throws a `Docx4JException` naming it: the
-     * caller asked for a definition nothing here has, and inventing one would be worse than saying so.
+     * add a footnote to. An id none of the sources carry - the defaults, the nine spliceable styles,
+     * the comment and placeholder styles, and Word's built-ins from docx4j's `KnownStyles.xml`
+     * (section 41) - throws a `Docx4JException` naming it: the caller asked for a definition nothing
+     * here has, and inventing one would be worse than saying so.
      * The whole closure is worked out before anything is written, so a call that throws has changed
      * nothing (CR-002 section 31).
      *
@@ -102,7 +119,7 @@ function closureOf(wanted, present, source) {
         seen.add(id);
         const template = source.find((s) => s.styleId === id);
         if (template === undefined) {
-            throw new Docx4JException(`No definition to splice for the style ${id}: neither docx4j's default styles, the nine it comments out nor the two comment styles carry one. Define it yourself on the styles part.`);
+            throw new Docx4JException(`No definition to splice for the style ${id}: neither docx4j's default styles, the nine it comments out, the two comment styles, PlaceholderText nor Word's built-ins in docx4j's KnownStyles.xml carry one. Define it yourself on the styles part.`);
         }
         // what it is based on and linked to must be there too, and before it reads better in the part
         for (const dependency of [(_a = template.basedOn) === null || _a === void 0 ? void 0 : _a.val, (_b = template.link) === null || _b === void 0 ? void 0 : _b.val]) {

package/dist/model/content/tableColumns.d.mts

@@ -0,0 +1,48 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import { type Element } from './tree.mjs';
+import { type ChangeTracker } from './tracking.mjs';
+/** The default text width in twips (A4 with 2.54 cm margins), as the objects package's `tbl` builder uses. */
+export declare const DEFAULT_TEXT_WIDTH = 9026;
+export type TableLayoutMode = 'fixed' | 'window' | 'contents';
+/** Which of Word's three layout modes a table is in, read as Word's Table Properties reads the file. */
+export declare function layoutModeOf(tbl: wml.Tbl): TableLayoutMode;
+/** The section's text width in twips: the page less its margins and gutter, else the default. */
+export declare function textWidthTwips(container: {
+    sectPr?: wml.SectPr;
+} | undefined): number;
+/** The grid's column widths in twips; a table without a `w:tblGrid` gets one from its first row (equal columns over the text width when the cells state none). */
+export declare function gridWidthsOf(tbl: wml.Tbl, textWidth: number): number[];
+/** The form a cell's width takes: its own `w:tcW` type, else the table's `w:tblW` type, else twips (section 42.2 item 4). */
+export declare function widthTypeOf(tc: wml.Tc | undefined, tbl: wml.Tbl): string;
+export interface ColumnInsertion {
+    /** The new cells per row, in row order; a row whose spanning cell was widened, or whose skipped columns grew, has none. */
+    cells: Element<wml.Tc>[][];
+}
+/**
+ * Inserts `count` grid columns at `gridIndex` (0 to the column count). The new column copies the
+ * width of the column to the right of the boundary when there is one, else the left (check 40:
+ * Insert Right in a narrow cell beside a wide one took the wide width; Insert Right in a spanning
+ * cell took the column after it), and each row's new cell takes the properties of the cell on the
+ * same side, less its span and merges. A cell spanning the boundary keeps its span and the new
+ * cell goes before it (check 40b1); a row's `w:gridBefore` or `w:gridAfter` covering the boundary
+ * grows instead. `values` is by row, then by new column. While changes are tracked the table
+ * change is recorded as Word's Office JS records one (check 40c): the old properties, every
+ * cell's properties - the new cells' as made - the grid as it is after, and the new cells' text in
+ * a `w:ins`, with no mark insertion.
+ */
+export declare function insertGridColumns(tbl: wml.Tbl, textWidth: number, gridIndex: number, count: number, values: string[][] | undefined, tracker: ChangeTracker | undefined): ColumnInsertion;
+/**
+ * Removes `count` grid columns from `columnIndex`: a cell covering only removed columns goes, one
+ * spanning further shrinks, a row's skipped columns shrink; the grid loses the columns, a `w:tblW`
+ * in twips loses their width, and in window mode the grid is rescaled to the width it had and the
+ * cells' percentages written again. While changes are tracked the cells still go, untracked, as
+ * Word's own Delete Columns and Office JS's `deleteColumns` leave them (known issues, entry 2;
+ * check 40c), and the table change is recorded as Office JS records it: the old properties, the
+ * remaining cells' properties, the grid as it is after.
+ */
+export declare function deleteGridColumns(tbl: wml.Tbl, textWidth: number, columnIndex: number, count: number, tracker: ChangeTracker | undefined): void;
+/** The grid columns a cell covers: its start and the one past its end. */
+export declare function gridRangeOf(tr: wml.Tr, tc: wml.Tc): {
+    start: number;
+    end: number;
+} | undefined;