@docx4j/core-ts 0.4.0 → 0.6.0

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

@@ -1,8 +1,10 @@
 import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
 import { XmlMapping } from '../customxml/XmlMapping.mjs';
 import { CheckboxContentControl, DatePickerContentControl, ListContentControl, PictureContentControl, RepeatingSectionContentControl, GroupContentControl } from '../customxml/kinds.mjs';
+import { type LineBreaks } from './officeText.mjs';
+import { type DefaultEntry } from './placeholders.mjs';
 import { type SdtKind } from '@docx4j/generated-objects-ts/builders/wml';
-import { type Element } from './tree.mjs';
+import { type Element, type BranchMode } from './tree.mjs';
 import type { Body } from './Body.mjs';
 import type { Paragraph } from './Paragraph.mjs';
 import { Range } from './Range.mjs';
@@ -56,7 +58,11 @@ export declare class ContentControl {
     set title(value: string);
     /** w:id, the number Word gives a control; 0 when it has none. */
     get id(): number;
-    /** The control's text, a line per paragraph (docx4j TextUtils). */
+    /**
+     * The control's text as Office JS gives it (CR-012 phase 4): a run-level control's span of
+     * `Paragraph.text`; a block-level one's content as `Body.text` reads it, its paragraphs a mark `\r` apart
+     * (check 51); a row control's cells a `\t` apart and a cell control's paragraphs `\r` apart (check 53).
+     */
     get text(): string;
     /** Every paragraph in the control; for a run-level control, the paragraph it is in. */
     get paragraphs(): Paragraph[];
@@ -64,6 +70,12 @@ export declare class ContentControl {
     get tables(): Table[];
     /** The controls nested in this one, in document order. */
     get contentControls(): ContentControl[];
+    /**
+     * Office JS `getContentControls` (WordApi 1.5): the content controls `contentControls` lists, those of `options.types`
+     * where given. Word's `contentControls` lists rich-text controls only; this package's lists every kind, a recorded
+     * departure (CR-002 section 60 G1, check 55b), so this is how add-in code that asks for plain-text controls finds them.
+     */
+    getContentControls(options?: ContentControlOptions): ContentControl[];
     /**
      * Text at the start, the end, or replacing the control's text. On a **bound** control the value
      * is written through to the custom XML node as well when the mapping resolves (CR-002 phase E):
@@ -72,17 +84,112 @@ export declare class ContentControl {
      * write is left to `pkg.customXmlParts.updateFromContentControls()`.
      */
     insertText(text: string, location: 'Start' | 'End' | 'Replace'): Range;
+    /**
+     * The glossary entry the control's `w:placeholder` names, which makes it Word's form; undefined where it names none,
+     * the bare form, which has no entry to show once emptied, nor for `placeholderText` to read (CR-002 section 63; an
+     * extension). Writes are the same in both forms (check 63's run 2).
+     */
+    get placeholderEntry(): string | undefined;
+    /** @internal True for a block or run-level control showing its placeholder, which a text write replaces (section 63). */
+    get showsPlaceholderContent(): boolean;
+    /** The package's glossary entries, where the control is in a package. */
+    private get glossary();
+    /**
+     * @internal Text written into the content of this control while it shows its placeholder, by any route: its own
+     * `insertText`, its 'Content' range's, a block control's paragraph's (CR-002 section 63, D1, D2 (b), D5, D11). The
+     * placeholder is no content, in either form (checks 64 and 67, check 63's run 2): its runs go, untracked, the text takes
+     * their place in one paragraph, and the flag is cleared; under tracking only the insertion is recorded. The text takes
+     * the control's own run properties (`w:sdtPr/w:rPr`) and nothing of the placeholder's (check 68, cases 1 to 20).
+     */
+    writePlaceholder(text: string, options?: {
+        lineBreaks?: LineBreaks;
+    }): Range;
+    /** The control's first paragraph, made where its content has none. */
+    private firstParagraph;
+    /**
+     * Takes the placeholder's runs out of the content: a run-level control's, or a block control's paragraphs', the first
+     * paragraph kept, emptied, and any other going. What held them.
+     */
+    private takePlaceholderRuns;
+    /**
+     * Shows Word's filler for a control emptied in the bare form, where no glossary entry gives it a placeholder: the flag
+     * on over a run of five spaces, in the control's own run properties (CR-002 section 63, D10; check 63's run 2, cases 6,
+     * 17, 32 and 43, and check 52's case 13). Nothing is marked under tracking. The spaces read as no text while the flag is
+     * on (CR-012 section 18).
+     */
+    private showFiller;
+    /**
+     * @internal A write through the control's 'Content' or 'Whole' range that the control takes (D3, D4): text into a
+     * control showing its placeholder, or into an empty run-level control, goes inside it; a 'Whole' range's Replace over
+     * a run-level control showing its placeholder takes the control, the text in its place. Undefined where the range's
+     * own write applies.
+     */
+    writeThrough(part: 'Content' | 'Whole', text: string, location: string): Range | undefined;
+    /**
+     * @internal A delete through the control's 'Content' or 'Whole' range that the control takes; false where the range's
+     * own delete applies. A 'Content' delete of a control showing its placeholder keeps the control and the flag: in the
+     * bare form over Word's filler, five spaces (D10; check 63's run 2, cases 6, 17, 32 and 43, nothing marked under
+     * tracking); in Word's form nothing changes, the placeholder being no content. A 'Whole' delete takes a run-level
+     * control showing its placeholder (D3).
+     */
+    deleteThrough(part: 'Content' | 'Whole'): boolean;
+    /**
+     * @internal After a 'Content' delete, untracked, that left the control holding no text: in Word's form it shows its
+     * entry again (check 66 case 3); in the bare form Word's filler (D10; check 52's case 13), as for a control of a kind
+     * Word gives no default entry, naming an entry the glossary lacks.
+     */
+    showEmptied(): void;
+    /**
+     * @internal Word's default placeholder entry for this control's kind (CR-002 section 63.22; docx4j CR-063's D8): the
+     * text kinds', the date picker's, the lists', a building block gallery's, a repeating section item's. Undefined for a
+     * kind Word gives none.
+     */
+    get defaultPlaceholderEntry(): DefaultEntry | undefined;
+    /**
+     * @internal Whether an empty control shows a placeholder in Word's form (D8; docx4j CR-063's D3 and D8): a kind Word
+     * gives a default entry, or one naming an entry the glossary holds.
+     */
+    get showsWordsFormPlaceholder(): boolean;
+    /**
+     * @internal Takes the control whole (D3): a Replace or delete over a control showing its placeholder, as Word takes one
+     * (check 63 cases 12, 18 to 20, 26, 38, 44 to 46 and 52). Untracked it goes, a block control leaving its paragraph,
+     * emptied, in its place; tracked it is marked deleted in Word's form (`markHolderDeleted`: `w:customXmlDelRange`
+     * markers around it and inside its content), its placeholder gone unmarked and the flag cleared (check 63's run 2,
+     * cases 38, 44 to 46 and 52). `text` goes where a run-level control stood, before it under tracking, as Word puts a
+     * Replace's insertion first.
+     */
+    takeWhole(text?: string): Range;
+    /** The control marked deleted with Word's markers, its placeholder gone, unmarked, and the flag cleared (`takeWhole`). */
+    private markWholeDeleted;
+    /**
+     * Shows the control's placeholder (CR-002 section 63, D8; section 63.18): a copy of the content of the entry its
+     * `w:placeholder` names, as the glossary holds it, the control's own run properties not over it, as Word shows it
+     * (check 68, section 63.21), with `w:showingPlcHdr`. A control naming no entry, or one the glossary lacks, is made to
+     * name Word's default entry for its kind (section 63.22: a date picker's is "Click or tap to enter a date.", a list's
+     * "Choose an item."), which is written into the glossary on save where it lacks it (D9), as docx4j's CR-063 has it:
+     * Word's save drops a reference no entry holds (check 65). A kind Word gives no default entry (a picture, a check box)
+     * keeps the name it has, and naming none shows docx4j's run, with no reference; any control keeps its name until the
+     * glossary is read (`getBody`, `Word.run`), showing its kind's default text. An extension.
+     */
+    showPlaceholder(): void;
     private insertTextInto;
     /** A paragraph at the start or end of a block control; before or after the paragraph of a run control. */
     insertParagraph(text: string, location: 'Start' | 'End' | 'Before' | 'After'): Paragraph;
     /** Matches within the control. */
     search(text: string, options?: SearchOptions): Range[];
     /**
-     * The control's range. For a run-level control, exactly the text it holds; for the other forms,
-     * the first paragraph (departure: a Range here is within one paragraph, CR-002 section 7).
+     * The control's range. For a run-level control, exactly the text it holds; for the other forms, its
+     * paragraphs: one `Range` from the first one's start to the last one's end (CR-014 phase 1), its 'Whole'
+     * ending with the last one's mark, as Office JS's does (check 51: `CCP1\rCCP2\rCCP3\r`, its 'Content'
+     * without the last `\r`).
      */
     getRange(location?: 'Whole' | 'Start' | 'End' | 'Content'): Range;
-    /** Removes the control; `keepContent` puts what it held in its place, as Office JS. */
+    private rangeOf;
+    /**
+     * Removes the control; `keepContent` puts what it held in its place, as Office JS. Where the control held the
+     * paragraph a table cell ends with, that paragraph stays in its place, emptied, its properties kept, outside
+     * any control, as Word keeps a cell's last paragraph (check 52, case 95; CR-002 section 55.6).
+     */
     delete(keepContent?: boolean): void;
     /** The XML of the control (extension). */
     getXml(): Promise<string>;
@@ -103,14 +210,21 @@ export declare class ContentControl {
     /** The control's data binding (Office JS `xmlMapping`), backed by `w:dataBinding`. */
     get xmlMapping(): XmlMapping;
     /**
-     * The placeholder Word shows for an empty control: the control's own text while it is showing
-     * the placeholder (`w:showingPlcHdr`), else '' — Word keeps the text itself in a glossary
-     * document part, which this phase does not create (CR-002 section 12). Setting writes the text
-     * as the control's content and sets `w:showingPlcHdr`, which is refused when the control holds
-     * content of its own, so that a value is never lost.
+     * The placeholder Word shows for an empty control: the text of the glossary entry the control's `w:placeholder` names,
+     * as Office JS reads it (CR-002 section 63, D8; check 65), `null` where the control names none (the bare form) or the
+     * glossary lacks the entry. The glossary is read when the body is (`getBody`, `Word.run`). Setting it names Word's
+     * default entry for Word's default text, else a new entry holding the text, named as Word names one (32 hex digits),
+     * which is written into the glossary on save, the entry named before left there; a control showing its placeholder,
+     * or holding nothing, shows the new text. A control's content is left alone. Until section 63 the text was written as
+     * the control's content in the bare form, and a control holding content refused it.
      */
-    get placeholderText(): string;
+    get placeholderText(): string | null;
     set placeholderText(text: string);
+    /**
+     * Blocks taken out of the control's content: the relationships only they used (a picture's image) and the comments
+     * whose references they held go when the package is saved, as a deletion's do.
+     */
+    private removeBlocks;
     /** Office JS `appearance`: how Word draws the control (`w15:appearance`). */
     get appearance(): ContentControlAppearance;
     set appearance(value: ContentControlAppearance);
@@ -152,6 +266,8 @@ export declare class ContentControl {
     get runProperties(): wml.RPr | undefined;
     /** Whether a plain-text control accepts several lines (`w:text/@w:multiLine`). */
     get isMultiLine(): boolean;
+    /** Office JS's name for `isShowingPlaceholder` (`showingPlaceholderText`, WordApiDesktop 1.3, read-only there). */
+    get showingPlaceholderText(): boolean;
     /** Whether the control is showing its placeholder rather than a value (`w:showingPlcHdr`). */
     get isShowingPlaceholder(): boolean;
     set isShowingPlaceholder(value: boolean);
@@ -166,18 +282,81 @@ export declare class ContentControl {
     /** A copy of this control right after it, as Word's repeating-section + button does (extension). */
     insertCopyAfter(): ContentControl;
     /**
-     * Writes the control's text into the node it is bound to, when there is one and the XPath engine
-     * is warm. Silent when it is not: reading a custom XML part is `pkg.customXmlParts.load()`'s job,
+     * @internal Writes the control's text into the node it is bound to, when there is one and the XPath engine
+     * is warm (CR-002 section 63, D7: every text write into a bound control). Silent when it is not: reading a custom XML part is `pkg.customXmlParts.load()`'s job,
      * and `updateFromContentControls()` is the explicit form of this write.
      */
-    private syncBoundNode;
-    private firstRunOfContent;
+    syncBoundNode(): void;
     private lockValue;
     private setLock;
+    /**
+     * True for a control in the selected branch of a kept `mc:AlternateContent`, at any level, which the
+     * collectors list as Word reads it (CR-013 phase 2). Such a view is read-only (D4).
+     */
+    get inBranch(): boolean;
+    /** Refuses a write to a control in a branch (CR-013 D4). Internal: the control's mutators, and its kinds', call it first. */
+    assertWritable(): void;
     /** The table a row-level or cell-level control belongs to. */
     private ancestorTable;
 }
-/** Every content control under a list of block-level items, in document order, nested ones included. */
-export declare function collectControls(items: Element[], body: Body, out: ContentControl[]): void;
+/**
+ * Every content control under a list of block-level items, in document order, nested ones included. In a
+ * kept `mc:AlternateContent` a reader's (`'read'`, the default) takes the selected branch's controls (CR-013
+ * phase 2), the binding passes (`'every'`) every branch's, each other branch's where the element stands
+ * (phase 3).
+ */
+export declare function collectControls(items: Element[], body: Body, out: ContentControl[], mode?: BranchMode): void;
 /** The run-level controls in a paragraph (or any run holder), in order, nested ones included. */
-export declare function collectRunControls(holder: object, body: Body, out: ContentControl[]): void;
+export declare function collectRunControls(holder: object, body: Body, out: ContentControl[], mode?: BranchMode): void;
+/**
+ * A view of the content control whose `w:sdt` value this is, found in its owner's list (a paragraph's runs, a body's
+ * blocks, a holder's items).
+ */
+export declare function controlViewOf(sdt: object, body: Body): ContentControl;
+/**
+ * A block-level control bound by `w:dataBinding`, untyped, `w:text` or `w:richText`, whose node doesn't hold flat OPC
+ * (CR-002 section 61 H1): Word holds its content to one paragraph, and can't open a file where it holds more (check 56,
+ * docx4j-python's file 3). A node not resolved (the custom XML parts not loaded) counts as not flat OPC. `w15:dataBinding`
+ * is Word's rich-text binding, and isn't this.
+ */
+export declare function isBoundBlockControl(control: ContentControl): boolean;
+/**
+ * How a control holds lines, as Word reads it: `multi` or `single` for a plain-text control (`w:text` and its
+ * `w:multiLine`), `single` for a bound block control Word reads as plain text (section 61 H4); undefined for any other.
+ */
+export declare function plainTextLinesOf(control: ContentControl): 'multi' | 'single' | undefined;
+/**
+ * Text for a run-level control: a line feed or carriage return there is refused before anything changes (CR-002
+ * section 60 F4: Word, given one, moved a bound plain-text control to block level), and a plain-text control's breaks
+ * go as its kind takes them (F3: dropped in a single-line one).
+ */
+export declare function textForRunControl(control: ContentControl, text: string): string;
+/** Word's error for a block write into a bound block control, where measured (CR-002 section 61 H3; check 56). */
+export type BlockRefusal = 'InvalidArgument' | 'GeneralException';
+/**
+ * Refuses, before anything changes, putting blocks into a block-level control bound by `w:dataBinding` (untyped,
+ * `w:text` or `w:richText`, its node not flat OPC) that would leave it holding anything but one paragraph: Word can't
+ * open such a file, and its repair loses the extra blocks (CR-002 section 61, check 56). Word's own error where
+ * measured (`insertTable` `InvalidArgument`, `insertOoxml` `GeneralException`), else `NotSupportedError` (H3).
+ */
+export declare function assertControlHolds(body: Body, holder: object, container: Element[], elements: readonly Element[], refusal?: BlockRefusal, member?: [string, string]): void;
+/** Office JS `Word.ContentControlOptions`: the types `getContentControls` lists. */
+export interface ContentControlOptions {
+    /** `ContentControlType` values; Office JS takes the enum's strings. */
+    types?: readonly string[];
+}
+/** The controls of `options.types`, or all of them. */
+export declare function controlsOfTypes(controls: ContentControl[], options?: ContentControlOptions): ContentControl[];
+/**
+ * Whether a control of this kind made on an empty range shows its default placeholder, as Word's does (CR-002 section
+ * 63, D8; check 64; Jason's `placeholders.docx`, section 63.22): a text control, a date picker, a drop-down list or a
+ * combo box. The building block and repeating section kinds are made as before.
+ */
+export declare function showsPlaceholderWhenMade(kind: ContentControlType | undefined): boolean;
+/** A stand-in for a block-level control about to be made, for `assertControlHolds` before `sdtOf` takes its content. */
+export declare const BLOCK_CONTROL: Element;
+/**
+ * Whether a block-level control holds one paragraph and nothing else at block level, or nothing yet: what a bound
+ * block control may hold (CR-002 section 61).
+ */
+export declare function holdsOneParagraph(control: ContentControl): boolean;