@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

package/src/features/settings/compat-settings.d.ts

@@ -0,0 +1,216 @@
+/**
+ * `w:compat` / `w:compatSetting` DOM (`CT_Compat` / `CT_CompatSetting`, Transitional `wml.xsd`).
+ *
+ * MVP: detect/list `compatSetting` name/uri/val; model selected nested OnOff flags
+ * (`noColumnBalance`); preserve remaining nested OnOff flags and unknown children in
+ * document order. Compatibility *engine* / layout behavior is out of scope.
+ *
+ * @public
+ */
+import { OpenXmlElement } from '../../core/xml/index';
+/**
+ * Word compatibility engine level from
+ * `w:compat/w:compatSetting[@w:name='compatibilityMode']/@w:val`.
+ *
+ * Wire values are ECMA-376 / Word practice: `"12"` | `"14"` | `"15"`.
+ *
+ * @public
+ */
+export declare enum CompatibilityMode {
+    /** Word 2007 compatibility (`"12"`). */
+    Word2007 = "12",
+    /** Word 2010 compatibility (`"14"`). */
+    Word2010 = "14",
+    /** Word 2013 and later compatibility (`"15"`). */
+    Word2013 = "15"
+}
+/**
+ * One `w:compatSetting` entry (`CT_CompatSetting`).
+ * Preserve-only infrastructure; not part of the supported public surface.
+ *
+ * @private
+ */
+export declare class CompatSetting {
+    private readonly settingName;
+    private readonly settingUri;
+    private readonly settingVal;
+    private readonly attributes;
+    private readonly elementChildren;
+    private readonly namespaceDeclarations;
+    private constructor();
+    /**
+     * @private
+     */
+    static fromElement(element: OpenXmlElement): CompatSetting;
+    /**
+     * Build a `w:compatSetting` with standard `name` / `uri` / `val` attributes.
+     *
+     * @private
+     */
+    static create(name: string, uri: string, val: string): CompatSetting;
+    /**
+     * `w:name` value, if present.
+     *
+     * @private
+     */
+    name(): string | undefined;
+    /**
+     * `w:uri` value, if present.
+     *
+     * @private
+     */
+    uri(): string | undefined;
+    /**
+     * `w:val` value, if present.
+     *
+     * @private
+     */
+    val(): string | undefined;
+    /**
+     * @private
+     */
+    serialize(): OpenXmlElement;
+}
+/**
+ * First-class `w:compat` container.
+ *
+ * @public
+ */
+export declare class CompatSettings {
+    private readonly children;
+    private readonly attributes;
+    private readonly namespaceDeclarations;
+    private onDirty;
+    private constructor();
+    /**
+     * @private
+     */
+    static fromElement(element: OpenXmlElement): CompatSettings;
+    /**
+     * @private
+     * Empty `w:compat` shell used when authors need a first-class OnOff under compat.
+     */
+    static createEmpty(onDirty?: () => void): CompatSettings;
+    /**
+     * @private
+     * Bind dirty callback after SettingsPart wraps the node.
+     */
+    bindDirty(onDirty: () => void): void;
+    private markDirty;
+    private findOnOff;
+    private setOnOff;
+    /**
+     * `w:compatSetting` entries in document order.
+     *
+     * @private
+     */
+    settings(): ReadonlyArray<CompatSetting>;
+    /**
+     * Names from `w:compatSetting/@w:name`, in document order (empty names skipped).
+     *
+     * @private
+     */
+    settingNames(): ReadonlyArray<string>;
+    /**
+     * Count of `w:compatSetting` children.
+     *
+     * @private
+     */
+    settingCount(): number;
+    /**
+     * Returns the `w:val` of the first `w:compatSetting` matching `name`, or
+     * `undefined` when not found.
+     *
+     * @private
+     */
+    setting(name: string): string | undefined;
+    /**
+     * Word compatibility mode from
+     * `w:compat` / `w:compatSetting[@w:name='compatibilityMode']/@w:val`.
+     *
+     * Reports the document’s declared compatibility engine level when present.
+     * Common values:
+     * - `"15"` — Word 2013 and later
+     * - `"14"` — Word 2010
+     * - `"12"` — Word 2007
+     *
+     * Returns `undefined` when the setting is absent. This method does not change
+     * layout or feature behavior; it only reads the stored attribute value.
+     *
+     * @returns Compatibility mode string, or `undefined` if not set.
+     *
+     * @example
+     * ```ts
+     * const settings = settingsFor(document);
+     * const mode = settings.compat()?.compatibilityMode();
+     * // "15" for typical Word 2013+ documents
+     * ```
+     *
+     * @public
+     */
+    compatibilityMode(): string | undefined;
+    /**
+     * Set or replace the first `w:compatSetting[@w:name='compatibilityMode']`.
+     *
+     * Uses Microsoft Office Word URI and preserves other compat settings / order.
+     * Creates a new entry at the end of the settings list when absent.
+     *
+     * @param value Wire token (`"12"` | `"14"` | `"15"`) or {@link CompatibilityMode}.
+     * @private
+     */
+    setCompatibilityMode(value: string | CompatibilityMode): void;
+    /**
+     * Whether multi-column section content should **not** be balanced across columns
+     * (`w:compat/w:noColumnBalance`, `CT_OnOff`, ECMA-376 Part 4 transitional
+     * migration features).
+     *
+     * When the element is present and on (`true`, including bare element with no
+     * `w:val`), consumers should fill columns top-to-bottom sequentially instead of
+     * balancing line heights across columns. When absent, Word’s default is to
+     * **balance** multi-column content (this method returns `undefined`).
+     *
+     * This library stores and round-trips the flag only; it does not implement a
+     * layout engine. Column geometry remains on section properties
+     * (`SectionProperties.textColumns` / `equalWidthColumns`).
+     *
+     * @returns `true`/`false` when the element is present; `undefined` when absent.
+     *
+     * @example
+     * ```ts
+     * const compat = settingsFor(document).compat();
+     * if (compat?.noColumnBalance() === true) {
+     *   // sequential column fill requested
+     * }
+     * ```
+     *
+     * @private
+     */
+    noColumnBalance(): boolean | undefined;
+    /**
+     * Set or clear `w:compat/w:noColumnBalance`.
+     *
+     * - `true` — emit bare `w:noColumnBalance` (OnOff true)
+     * - `false` — emit `w:noColumnBalance w:val="0"` / false form via serializeOnOff
+     * - `undefined` — remove the element
+     *
+     * Marks the owning settings part dirty when a dirty callback is bound.
+     *
+     * @private
+     */
+    setNoColumnBalance(value: boolean | undefined): void;
+    /**
+     * Creates the default Word-2013 compat settings block.
+     *
+     * Matches the `w:compat` element emitted by Microsoft Word for new documents:
+     * `compatibilityMode=15`, `overrideTableStyleFontSizeAndJustification=1`,
+     * `enableOpenTypeFeatures=1`, `doNotFlipMirrorIndents=1`,
+     * `differentiateMultirowTableHeaders=1`.
+     *
+     * @private
+     */
+    static createDefault(): CompatSettings;
+    /**
+     * @private
+     */
+    serialize(): OpenXmlElement;
+}