@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

package/src/features/fields/index.d.ts

@@ -0,0 +1,428 @@
+import { WordDocument } from '../document/document';
+import { FeatureInline } from '../document/feature-inline';
+import { FeatureRunLeaf } from '../document/feature-run-leaf';
+import { Paragraph } from '../document/paragraph';
+import { ParagraphItem, TextRange } from '../document/text-range';
+import { OpenXmlElement } from '../../core/xml/index';
+import { Field } from './paragraph-field';
+export { Field, IfField, MergeField, FieldMark, FieldMarkType } from './paragraph-field';
+import { Picture } from '../images/index';
+/**
+ * Customer-facing Word field types (ECMA-376-1 §17.16 instruction keywords).
+ *
+ * Only PAGE, NUMPAGES, IF, MERGEFIELD, and HYPERLINK are public in this phase.
+ * Other instructions load as opaque content and are excluded from {@link fieldsInParagraph}.
+ *
+ * @public
+ */
+export declare const FieldType: {
+    /** `PAGE` — current page number. */
+    Page: "PAGE";
+    /** `NUMPAGES` — total number of pages. */
+    NumPages: "NUMPAGES";
+    /** `IF` — conditional field. */
+    If: "IF";
+    /** `MERGEFIELD` — mail-merge field. */
+    MergeField: "MERGEFIELD";
+    /** `HYPERLINK` — hyperlink field. */
+    Hyperlink: "HYPERLINK";
+};
+/**
+ * One of the {@link FieldType} tokens.
+ *
+ * @public
+ */
+export declare type FieldType = (typeof FieldType)[keyof typeof FieldType];
+/**
+ * Hyperlink classification for field-based ({@link Hyperlink}) authoring.
+ *
+ * @public
+ */
+export declare const HyperlinkType: {
+    WebLink: "WebLink";
+    EmailLink: "EmailLink";
+    FileLink: "FileLink";
+    Bookmark: "Bookmark";
+};
+/**
+ * One of the {@link HyperlinkType} tokens.
+ *
+ * @public
+ */
+export declare type HyperlinkType = (typeof HyperlinkType)[keyof typeof HyperlinkType];
+/**
+ * Field mark types on `w:fldChar/@w:fldCharType` (`ST_FldCharType`).
+ *
+ * @private
+ */
+declare type FieldMarkType = 'begin' | 'separate' | 'end';
+declare class SimpleFieldRunOwner {
+    private runs;
+    assertAttachedItem(target: ParagraphItem): void;
+    appendRun(): TextRange;
+    listRuns(): ReadonlyArray<TextRange>;
+    detachRuns(): void;
+    hydrateRuns(runs: TextRange[]): void;
+}
+declare type SimpleFieldInlineItem = {
+    readonly type: 'textRange';
+    readonly run: TextRange;
+} | {
+    readonly type: 'opaque';
+    readonly xml: OpenXmlElement;
+};
+/**
+ * Simple field storage (`w:fldSimple`).
+ *
+ * @private
+ */
+declare class SimpleField implements FeatureInline {
+    private readonly runOwner;
+    private readonly extras;
+    private readonly items;
+    private instructionValue;
+    readonly fldLock: boolean | undefined;
+    readonly dirty: boolean | undefined;
+    /**
+     * @private
+     */
+    constructor(runOwner: SimpleFieldRunOwner, extras: OpenXmlElement[], items: SimpleFieldInlineItem[], instruction: string, fldLock: boolean | undefined, dirty: boolean | undefined);
+    /**
+     * Field instruction (`w:fldSimple/@w:instr`).
+     * @private
+     */
+    readonly instruction: string;
+    /**
+     * @private
+     */
+    setInstruction(value: string): void;
+    /**
+     * Result text ranges inside the simple field.
+     * @private
+     */
+    readonly runs: ReadonlyArray<TextRange>;
+    /**
+     * @private
+     */
+    releaseContent(): void;
+    toOpenXml(): OpenXmlElement;
+}
+/**
+ * Complex field character marker (`w:fldChar`).
+ *
+ * Children such as `w:ffData` and `w:fldData` are retained and re-emitted
+ * unchanged. Typed form-field access is via {@link FormField}.
+ *
+ * @private
+ */
+declare class FieldMark implements FeatureRunLeaf {
+    readonly fldCharType: FieldMarkType;
+    readonly fldLock: boolean | undefined;
+    readonly dirty: boolean | undefined;
+    private readonly extras;
+    /**
+     * @private
+     */
+    constructor(fldCharType: FieldMarkType, fldLock: boolean | undefined, dirty: boolean | undefined, extras: OpenXmlElement[]);
+    /**
+     * Unmodeled / pass-through children of `w:fldChar` (includes `w:ffData`).
+     *
+     * @private
+     */
+    childElements(): ReadonlyArray<OpenXmlElement>;
+    toOpenXml(): OpenXmlElement;
+}
+/**
+ * Field instruction text (`w:instrText`).
+ *
+ * @private
+ */
+declare class InstrText implements FeatureRunLeaf {
+    private textValue;
+    readonly xmlSpacePreserve: boolean;
+    /**
+     * @private
+     */
+    constructor(text: string, xmlSpacePreserve: boolean);
+    /**
+     * Instruction text content.
+     * @private
+     */
+    readonly text: string;
+    /**
+     * @private
+     */
+    setText(value: string): void;
+    toOpenXml(): OpenXmlElement;
+}
+/**
+ * A complex field span within one paragraph (begin → instr → separate → result → end).
+ *
+ * Markers and instruction text are elevated {@link FeatureRunParagraphItem} values on the
+ * paragraph; result content is plain {@link TextRange} siblings between separate and end.
+ *
+ * @private
+ */
+declare class ComplexField {
+    private instructionValue;
+    readonly resultRuns: ReadonlyArray<TextRange>;
+    private readonly markerValues;
+    private readonly instructionTexts;
+    /**
+     * @private
+     */
+    constructor(instruction: string, resultRuns: ReadonlyArray<TextRange>, markerValues: ReadonlyArray<FeatureRunLeaf>, instructionTexts?: ReadonlyArray<InstrText>);
+    /**
+     * Instruction snapshot / live value.
+     * @private
+     */
+    readonly instruction: string;
+    /**
+     * @private
+     */
+    setInstruction(value: string): void;
+    /**
+     * All feature-run marker/instr values plus result text ranges, used for removal.
+     * @private
+     */
+    allFeatureValues(): ReadonlyArray<FeatureRunLeaf>;
+}
+/**
+ * Kind of legacy form field hosted under begin `w:fldChar`/`w:ffData`.
+ *
+ * Values match the OOXML child local names for text and checkbox controls.
+ * Drop-down uses product name `'dropDown'` (XML child is `w:ddList` /
+ * Transitional `CT_FFDDList`).
+ *
+ * @public
+ */
+export declare type FormFieldType = 'textInput' | 'checkBox' | 'dropDown';
+/**
+ * Read-only view of a legacy Word form field (`w:ffData` on begin `w:fldChar`).
+ *
+ * Form fields are complex-field spans whose begin marker carries form-field
+ * data (ECMA-376-1 §17.16.17 `ffData`; Transitional `wml.xsd` `CT_FFData`).
+ * This helper does **not** implement `FeatureInline` / `FeatureRunLeaf` and is
+ * never serialized on its own — the begin `w:fldChar` re-emits the stored
+ * `w:ffData` element (no double-emit). Internal field markers and complex-field
+ * spans are not part of the public surface.
+ *
+ * Kind-specific members apply only when {@link type} matches; otherwise they
+ * are `undefined` / empty. Mutation of `ffData` is out of scope for this MVP.
+ *
+ * @public
+ */
+export declare class FormField {
+    private readonly data;
+    private readonly kindValue;
+    /**
+     * @private
+     */
+    constructor(_beginMark: FieldMark, data: OpenXmlElement, kind: FormFieldType, _complex: ComplexField | undefined);
+    /**
+     * Control kind derived from the exclusive `w:textInput` / `w:checkBox` /
+     * `w:ddList` child under `w:ffData`.
+     */
+    readonly type: FormFieldType;
+    /** `w:ffData/w:name/@w:val` (`ST_FFName`). */
+    readonly name: string | undefined;
+    /**
+     * `w:ffData/w:enabled` (`CT_OnOff`). Absent means enabled in Word UI; this
+     * surface returns `undefined` when the element is missing, `true`/`false`
+     * when present (including empty `w:enabled` = true).
+     */
+    readonly enabled: boolean | undefined;
+    /** `w:ffData/w:tabIndex/@w:val` (`CT_UnsignedDecimalNumber`). */
+    readonly tabIndex: number | undefined;
+    /** `w:ffData/w:helpText/@w:val` (type attribute is preserved on the element). */
+    readonly helpText: string | undefined;
+    /** `w:ffData/w:statusText/@w:val`. */
+    readonly statusText: string | undefined;
+    /** `w:textInput/w:maxLength/@w:val` (`CT_DecimalNumber`; 0 = unlimited). */
+    readonly maxLength: number | undefined;
+    /** `w:textInput/w:format/@w:val`. */
+    readonly format: string | undefined;
+    /** `w:textInput/w:default/@w:val`. */
+    readonly defaultText: string | undefined;
+    /** `w:checkBox/w:checked` (`CT_OnOff`) — current checked state. */
+    readonly checked: boolean | undefined;
+    /** `w:checkBox/w:default` (`CT_OnOff`) — default checked state. */
+    readonly defaultChecked: boolean | undefined;
+    /**
+     * `w:ddList/w:listEntry/@w:val` entries in document order.
+     * Empty when kind is not drop-down or no entries are present.
+     */
+    readonly entries: ReadonlyArray<string>;
+    /**
+     * `w:ddList/w:result/@w:val` — zero-based selected index when present.
+     */
+    readonly selected: number | undefined;
+    /**
+     * Entry text at {@link selected}, or `undefined` if index is missing or
+     * out of range.
+     */
+    readonly selectedEntry: string | undefined;
+}
+/**
+ * Customer-facing Word field (PAGE / NUMPAGES base; subclasses for IF / MERGEFIELD).
+ *
+ * Wraps either a simple field (`w:fldSimple`) or a complex field span
+ * (`w:fldChar` / `w:instrText`). Does **not** recalculate Word field results.
+ *
+ * @public
+ */
+export declare class LegacyField {
+    private readonly kind;
+    private readonly simple;
+    private readonly complex;
+    private readonly host;
+    private readonly lockedType;
+    /**
+     * @private
+     */
+    constructor(kind: 'simple' | 'complex', simple: SimpleField | undefined, complex: ComplexField | undefined, host: Paragraph | undefined, lockedType: FieldType);
+    /**
+     * Full field instruction / field code (for example ` PAGE `, ` MERGEFIELD Name `).
+     *
+     * The instruction keyword must remain this field’s {@link fieldType}.
+     */
+    fieldCode: string;
+    /**
+     * Supported field type for this instance (fixed at construction).
+     */
+    readonly fieldType: FieldType;
+    /**
+     * Cached field-result text (read-only). Prefer {@link text} to mutate display text.
+     */
+    readonly fieldValue: string;
+    /**
+     * Cached visible field-result text.
+     */
+    text: string;
+    /**
+     * Character formatting of the first result {@link TextRange}.
+     */
+    readonly characterFormat: import('../document/character-format').CharacterFormat;
+    private readResultText;
+    private writeResultText;
+    private resultRuns;
+    private firstResultRun;
+}
+/**
+ * Conditional `IF` field. Expression lives entirely in {@link Field.fieldCode}.
+ *
+ * @public
+ */
+export declare class LegacyIfField extends LegacyField {
+}
+/**
+ * Mail-merge `MERGEFIELD` with typed switch accessors.
+ *
+ * @public
+ */
+export declare class LegacyMergeField extends LegacyField {
+    fieldName: string;
+    textBefore: string;
+    textAfter: string;
+    readonly dateFormat: string;
+    readonly numberFormat: string;
+    readonly prefix: string;
+}
+/**
+ * Hyperlink facade over either a HYPERLINK field or a picture DrawingML link.
+ *
+ * Distinct from the `w:hyperlink` inline model in `features/hyperlinks`.
+ * The all-in entry exports this type as {@link Hyperlink}; the inline
+ * relationship hyperlink is available from `@syncfusion/ej2-docx/hyperlinks`.
+ *
+ * @public
+ */
+export declare class Hyperlink {
+    private readonly fieldValue;
+    private readonly pictureValue;
+    private pictureTypeValue;
+    private pictureUriValue;
+    /**
+     * @private
+     */
+    constructor(field: Field | LegacyField);
+    /**
+     * @private
+     */
+    constructor(picture: Picture, uri: string, type: HyperlinkType);
+    /**
+     * Underlying field when this hyperlink is field-backed.
+     */
+    readonly field: Field | LegacyField | undefined;
+    /**
+     * Field type when field-backed (used by structure tests).
+     */
+    readonly fieldType: FieldType | undefined;
+    bookmarkName: string;
+    filePath: string;
+    localReference: string;
+    pictureToDisplay: Picture | undefined;
+    textToDisplay: string;
+    type: HyperlinkType;
+    uri: string;
+}
+/**
+ * @private
+ * Test hook */
+export declare function resetFieldsFeatureForTests(): void;
+/**
+ * @private
+ * Register field inline and run-leaf handlers. Idempotent. */
+export declare function registerFieldsFeature(): void;
+/**
+ * Legacy form fields in a paragraph, in document order.
+ *
+ * A form field is detected whenever a begin {@link FieldMark} hosts `w:ffData`
+ * with a typed control child (`textInput` / `checkBox` / `ddList`). Detection
+ * does **not** require a complete complex-field pair (separate + result + end),
+ * so incomplete markers still surface as {@link FormField} views.
+ *
+ * @private
+ */
+export declare function formFieldsInParagraph(paragraph: Paragraph): ReadonlyArray<FormField>;
+/**
+ * Fields in a paragraph, in document order.
+ *
+ * Simple fields (`w:fldSimple`) and complex field spans (`w:fldChar` /
+ * `w:instrText`) are interleaved by paragraph content order. Cached results are
+ * not recalculated.
+ *
+ * @private
+ */
+export declare function fieldsInParagraph(paragraph: Paragraph): ReadonlyArray<Field | LegacyField>;
+/**
+ * Fields across the document, in document order.
+ *
+ * Walks paragraphs via {@link visitParagraphsInDocumentOrder} (main body and
+ * nested paragraph hosts the registry visitor covers). Does not recalculate
+ * field results.
+ *
+ * @private
+ */
+export declare function fieldsInDocument(document: WordDocument): ReadonlyArray<Field | LegacyField>;
+/**
+ * Append an opaque complex field (any instruction, including SEQ for captions).
+ * Not part of the public customer Field API.
+ *
+ * @private
+ */
+export declare function appendOpaqueComplexField(paragraph: Paragraph, instruction: string, options: {
+    result: string;
+}): LegacyField;
+/**
+ * Opaque complex-field instructions in a paragraph (any keyword, including SEQ).
+ *
+ * @private
+ */
+export declare function opaqueComplexFieldInstructionsInParagraph(paragraph: Paragraph): ReadonlyArray<string>;
+/**
+ * First instruction keyword (e.g. SEQ, PAGE) for opaque complex fields.
+ *
+ * @private
+ */
+export declare function fieldInstructionKeyword(instruction: string): string;