@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

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

@@ -0,0 +1,356 @@
+export * from './attached-template';
+export * from './compat-settings';
+export * from './document-background';
+export * from './document-protection';
+export * from './document-settings-facades';
+export * from './document-settings-values';
+export * from './footnote-properties';
+export * from './settings-children';
+export * from './web-settings';
+export * from './zoom';
+import { WordDocument } from '../document/document';
+import { FeaturePackagePart } from '../document/feature-package-part';
+import { PartName } from '../../core/opc/part-name';
+import { OpenXmlAttribute, NamespaceDeclaration } from '../../core/xml/index';
+import { AttachedTemplate } from './attached-template';
+import { CompatSettings } from './compat-settings';
+import { DocumentProtection, DocumentProtectionFlags } from './document-protection';
+import { Background } from './document-background';
+import { EndnoteProperties, FootnoteProperties } from './footnote-properties';
+import { SettingsViewChild, SettingsChild, DocumentViewType } from './settings-children';
+import { ZoomSettings } from './zoom';
+import { CharacterSpacingControl } from './document-settings-values';
+import { CompatibilityMode } from './compat-settings';
+/**
+ * @private
+ * Transitional settings relationship (ECMA-376-4 §9.2.3). */
+export declare const SETTINGS_RELATIONSHIP_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings";
+/**
+ * @private
+ * Strict settings relationship (ECMA-376-1 §11.3.3). */
+export declare const STRICT_SETTINGS_RELATIONSHIP_TYPE = "http://purl.oclc.org/ooxml/officeDocument/relationships/settings";
+/**
+ * @private
+ * ECMA-376-1 §11.3.3 WordDocument Settings content type. */
+export declare const SETTINGS_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.settings+xml";
+/**
+ * @private
+ * Transitional attached-template relationship (ECMA-376-4 §14.12.22). */
+export declare const ATTACHED_TEMPLATE_RELATIONSHIP_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/attachedTemplate";
+/**
+ * @private
+ * Strict attached-template relationship (ECMA-376-1 §11.4). */
+export declare const STRICT_ATTACHED_TEMPLATE_RELATIONSHIP_TYPE = "http://purl.oclc.org/ooxml/officeDocument/relationships/attachedTemplate";
+/**
+ * @private
+ */
+export declare const SETTINGS_PART_NAME: PartName;
+/**
+ * In-memory WordDocument Settings part (`word/settings.xml`).
+ *
+ * Children are a typed ordered graph: modeled OnOff / protection / attachedTemplate /
+ * compat nodes plus opaque shells for the rest of `CT_Settings`.
+ *
+ * @private
+ */
+export declare class SettingsPart implements FeaturePackagePart {
+    private readonly rootAttributes;
+    private readonly rootNamespaceDeclarations;
+    private readonly children;
+    private dirty;
+    /**
+     * @private
+     */
+    constructor(rootAttributes: ReadonlyArray<OpenXmlAttribute>, rootNamespaceDeclarations: ReadonlyArray<NamespaceDeclaration>, children: SettingsChild[], dirty: boolean);
+    private findOnOff;
+    private setOnOff;
+    /**
+     * `w:evenAndOddHeaders` as a boolean, or `undefined` when the element is absent.
+     *
+     * @public
+     */
+    evenAndOddHeaders(): boolean | undefined;
+    /**
+     * Set or clear `w:evenAndOddHeaders`. `undefined` removes the element.
+     *
+     * @public
+     */
+    setEvenAndOddHeaders(value: boolean | undefined): void;
+    /**
+     * `w:trackRevisions` as a boolean, or `undefined` when the element is absent.
+     *
+     * @public
+     */
+    trackRevisions(): boolean | undefined;
+    /**
+     * Set or clear `w:trackRevisions`. `undefined` removes the element.
+     *
+     * @public
+     */
+    setTrackRevisions(value: boolean | undefined): void;
+    /**
+     * Modeled `w:documentProtection` flags snapshot. Password/hash attributes are omitted.
+     *
+     * Prefer {@link documentProtectionNode} when the typed class is needed.
+     *
+     * @public
+     */
+    documentProtection(): DocumentProtectionFlags | undefined;
+    /**
+     * First-class `w:documentProtection` node, or `undefined` when absent.
+     *
+     * @public
+     */
+    documentProtectionNode(): DocumentProtection | undefined;
+    /**
+     * Replace or remove `w:documentProtection`. Clearing the element also drops preserved
+     * password/hash attributes. Flag-only updates keep leftover attributes on the existing node.
+     *
+     * @public
+     */
+    setDocumentProtection(flags: DocumentProtectionFlags | undefined): void;
+    /**
+     * Whether `w:attachedTemplate` is present in settings.
+     *
+     * @public
+     */
+    hasAttachedTemplate(): boolean;
+    /**
+     * First-class `w:attachedTemplate` node, or `undefined` when absent.
+     *
+     * @public
+     */
+    attachedTemplate(): AttachedTemplate | undefined;
+    /**
+     * `r:id` on `w:attachedTemplate`, or `undefined` when absent.
+     *
+     * @public
+     */
+    attachedTemplateRelationshipId(): string | undefined;
+    /**
+     * First-class `w:compat` node, or `undefined` when absent.
+     *
+     * Mutations on the returned node (for example {@link CompatSettings.setNoColumnBalance})
+     * mark the settings part dirty.
+     *
+     * @public
+     */
+    compat(): CompatSettings | undefined;
+    /**
+     * Ensure a `w:compat` node exists and return it.
+     *
+     * @private
+     */
+    ensureCompat(): CompatSettings;
+    /**
+     * Names from `w:compat/w:compatSetting/@w:name`, in document order.
+     *
+     * @public
+     */
+    compatSettingNames(): ReadonlyArray<string>;
+    /**
+     * Count of `w:compatSetting` children under `w:compat`.
+     *
+     * @public
+     */
+    compatSettingCount(): number;
+    /**
+     * `w:displayBackgroundShape` as a boolean, or `undefined` when the element is absent.
+     *
+     * @public
+     */
+    displayBackgroundShape(): boolean | undefined;
+    /**
+     * Set or clear `w:displayBackgroundShape`. `undefined` removes the element.
+     *
+     * @private
+     */
+    setDisplayBackgroundShape(value: boolean | undefined): void;
+    /**
+     * First-class `w:view` child, or `undefined` when absent.
+     *
+     * @private
+     */
+    view(): SettingsViewChild | undefined;
+    /**
+     * Set or clear `w:view`. `undefined` removes the element.
+     *
+     * Accepts a known {@link DocumentViewType}, wire string, or modeled child.
+     *
+     * @private
+     */
+    setView(value: DocumentViewType | string | SettingsViewChild | undefined): void;
+    /**
+     * First-class `w:zoom` node, or `undefined` when absent.
+     *
+     * @public
+     */
+    zoom(): ZoomSettings | undefined;
+    /**
+     * Set `w:zoom` from a {@link ZoomSettings} instance, or remove it when `undefined`.
+     *
+     * @public
+     */
+    setZoom(value: ZoomSettings | undefined): void;
+    /**
+     * First-class `w:footnotePr` node, or `undefined` when absent.
+     *
+     * Mutations on the returned node mark the settings part dirty.
+     *
+     * @public
+     */
+    footnoteProperties(): FootnoteProperties | undefined;
+    /**
+     * Ensure a `w:footnotePr` node exists and return it.
+     *
+     * @public
+     */
+    ensureFootnoteProperties(): FootnoteProperties;
+    /**
+     * Replace or clear `w:footnotePr`. `undefined` removes the element.
+     *
+     * @public
+     */
+    setFootnoteProperties(value: FootnoteProperties | undefined): void;
+    /**
+     * First-class `w:endnotePr` node, or `undefined` when absent.
+     *
+     * Mutations on the returned node mark the settings part dirty.
+     *
+     * @public
+     */
+    endnoteProperties(): EndnoteProperties | undefined;
+    /**
+     * Ensure a `w:endnotePr` node exists and return it.
+     *
+     * @public
+     */
+    ensureEndnoteProperties(): EndnoteProperties;
+    /**
+     * Replace or clear `w:endnotePr`. `undefined` removes the element.
+     *
+     * @public
+     */
+    setEndnoteProperties(value: EndnoteProperties | undefined): void;
+    /**
+     * `w:defaultTabStop/@w:val` in plain points, or `undefined` when the element is absent.
+     * Wire unit is twips (`ST_TwipsMeasure`); conversion is at the parse/serialize boundary.
+     *
+     * The default value in Word is half an inch (`720` twips → `36` points).
+     *
+     * @public
+     */
+    defaultTabStop(): number | undefined;
+    /**
+     * Set or clear `w:defaultTabStop`. `undefined` removes the element.
+     *
+     * @param value - Plain points (e.g. `36` = 0.5 inch). Serialized as twips on the wire.
+     *
+     * @public
+     */
+    setDefaultTabStop(value: number | undefined): void;
+    /**
+     * `w:characterSpacingControl/@w:val`, or `undefined` when the element is absent.
+     *
+     * @public
+     */
+    characterSpacingControl(): CharacterSpacingControl | undefined;
+    /**
+     * Set or clear `w:characterSpacingControl`. `undefined` removes the element.
+     *
+     * @public
+     */
+    setCharacterSpacingControl(value: CharacterSpacingControl | undefined): void;
+    /**
+     * `compatibilityMode` from `w:compat/w:compatSetting[@w:name='compatibilityMode']/@w:val`.
+     *
+     * Common values: `"15"` = Word 2013+, `"14"` = Word 2010, `"12"` = Word 2007.
+     * Returns `undefined` when the `w:compat` element or the named setting is absent.
+     *
+     * @public
+     */
+    compatibilityMode(): string | undefined;
+    /**
+     * Set Word `compatibilityMode` on `w:compat`, creating the compat block when needed.
+     *
+     * @param value Wire token or {@link CompatibilityMode}.
+     * @private
+     */
+    setCompatibilityMode(value: string | CompatibilityMode): void;
+    /**
+     * `w:compat/w:noColumnBalance` (`CT_OnOff`) — do not balance multi-column section
+     * content. See {@link CompatSettings.noColumnBalance}.
+     *
+     * Returns `undefined` when `w:compat` or the element is absent (Word default:
+     * balance columns). Layout engines are out of scope for this library.
+     *
+     * @private
+     */
+    noColumnBalance(): boolean | undefined;
+    /**
+     * Set or clear `w:compat/w:noColumnBalance`. Creates `w:compat` when needed.
+     * Pass `undefined` to remove the element. Marks the settings part dirty.
+     *
+     * @private
+     */
+    setNoColumnBalance(value: boolean | undefined): void;
+    /**
+     * @private
+     */
+    isDirty(): boolean;
+    /**
+     * @private
+     */
+    serialize(): Uint8Array;
+}
+/**
+ * Creates a new {@link SettingsPart} pre-populated with the canonical Word-2013
+ * default settings and marked **dirty** so `WordDocument.saveSync` always writes
+ * `settings.xml` — even when no further mutation is made.
+ *
+ * Emitted children (matching Microsoft Word for a minimal new document):
+ * - `w:zoom val="none" percent="100"`
+ * - `w:defaultTabStop val="720"` (wire twips; DOM value is `36` points)
+ * - `w:characterSpacingControl val="doNotCompress"`
+ * - `w:compat` with five Word-2013 compat settings
+ * - `w:clrSchemeMapping`
+ *
+ * @private
+ */
+export declare function createDefaultSettingsPart(): SettingsPart;
+/**
+ * @private
+ * Test hook */
+export declare function resetSettingsFeatureForTests(): void;
+/**
+ * @private
+ * Register the document-settings package-part handler. Idempotent. */
+export declare function registerSettingsFeature(): void;
+/**
+ * Settings catalog for a document. Requires {@link registerSettingsFeature}.
+ *
+ * On {@link WordDocument.create} (and any document that has no settings state yet), the first
+ * access attaches a default {@link SettingsPart} pre-populated with canonical Word-2013
+ * settings (zoom, defaultTabStop, characterSpacingControl, compat, clrSchemeMapping) and
+ * marked dirty so that `WordDocument.saveSync` **always** materializes `/word/settings.xml`,
+ * its content-type override, and its Main Document relationship — even when no further
+ * mutation is made. This matches the OOXML conformance requirement that a DOCX file
+ * contains a settings part by default.
+ *
+ * @throws DocxError `UNKNOWN_FEATURE` when the module was not registered.
+ *
+ * @private
+ */
+export declare function settingsFor(document: WordDocument): SettingsPart;
+/**
+ * Attached template relationship target from the settings part, without fetching.
+ *
+ * @private
+ */
+export declare function attachedTemplateTarget(document: WordDocument): string | undefined;
+/**
+ * Main Document page background metadata. Requires {@link registerSettingsFeature}.
+ *
+ * @private
+ */
+export declare function backgroundFor(document: WordDocument): Background;