@syncfusion/ej2-docx 0.0.0-stage → 35.1.39

package/src/features/sections/margins.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Live page margins for a section (`CT_PageMar` left/top/right/bottom).
+ *
+ * Header distance, footer distance, and gutter remain internal on PageSetup
+ * and are not part of this public surface.
+ *
+ * @public
+ */
+export declare class Margins {
+    private leftValue;
+    private topValue;
+    private rightValue;
+    private bottomValue;
+    /**
+     * @private
+     */
+    constructor(left: number, top: number, right: number, bottom: number);
+    /**
+     * When all four sides share one value, returns that value; otherwise the
+     * left margin (DocIO-style convenience read).
+     */
+    all: number;
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    /**
+     * @private
+     */
+    snapshot(): {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+    /**
+     * @private
+     */
+    replace(left: number, top: number, right: number, bottom: number): void;
+}

package/src/features/sections/margins.js

@@ -0,0 +1,105 @@
+import { validateSectionLength } from './section-validation';
+/**
+ * Live page margins for a section (`CT_PageMar` left/top/right/bottom).
+ *
+ * Header distance, footer distance, and gutter remain internal on PageSetup
+ * and are not part of this public surface.
+ *
+ * @public
+ */
+var Margins = /** @class */ (function () {
+    /**
+     * @private
+     */
+    function Margins(left, top, right, bottom) {
+        this.leftValue = left;
+        this.topValue = top;
+        this.rightValue = right;
+        this.bottomValue = bottom;
+    }
+    Object.defineProperty(Margins.prototype, "all", {
+        /**
+         * When all four sides share one value, returns that value; otherwise the
+         * left margin (DocIO-style convenience read).
+         */
+        get: function () {
+            if (this.leftValue === this.topValue &&
+                this.topValue === this.rightValue &&
+                this.rightValue === this.bottomValue) {
+                return this.leftValue;
+            }
+            return this.leftValue;
+        },
+        set: function (value) {
+            var next = validateSectionLength(value, 'margins.all');
+            this.leftValue = next;
+            this.topValue = next;
+            this.rightValue = next;
+            this.bottomValue = next;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Margins.prototype, "left", {
+        get: function () {
+            return this.leftValue;
+        },
+        set: function (value) {
+            this.leftValue = validateSectionLength(value, 'margins.left');
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Margins.prototype, "top", {
+        get: function () {
+            return this.topValue;
+        },
+        set: function (value) {
+            this.topValue = validateSectionLength(value, 'margins.top');
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Margins.prototype, "right", {
+        get: function () {
+            return this.rightValue;
+        },
+        set: function (value) {
+            this.rightValue = validateSectionLength(value, 'margins.right');
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Margins.prototype, "bottom", {
+        get: function () {
+            return this.bottomValue;
+        },
+        set: function (value) {
+            this.bottomValue = validateSectionLength(value, 'margins.bottom');
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * @private
+     */
+    Margins.prototype.snapshot = function () {
+        return {
+            left: this.leftValue,
+            top: this.topValue,
+            right: this.rightValue,
+            bottom: this.bottomValue,
+        };
+    };
+    /**
+     * @private
+     */
+    Margins.prototype.replace = function (left, top, right, bottom) {
+        this.leftValue = validateSectionLength(left, 'margins.left');
+        this.topValue = validateSectionLength(top, 'margins.top');
+        this.rightValue = validateSectionLength(right, 'margins.right');
+        this.bottomValue = validateSectionLength(bottom, 'margins.bottom');
+    };
+    return Margins;
+}());
+export { Margins };

package/src/features/sections/page-number-style.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Page number formats (`ST_NumberFormat` subset used for page numbers).
+ *
+ * Canonical enum lives in core. Wire helpers stay feature-local.
+ *
+ * Maps to `w:pgNumType/@w:fmt`.
+ *
+ * @public
+ */
+export { PageNumberStyle } from '../document/page-setup';
+import { PageNumberStyle } from '../document/page-setup';
+/** Wire tokens accepted for `w:pgNumType/@w:fmt`. */
+export declare const PAGE_NUMBER_STYLE_WIRE: ReadonlySet<string>;
+/**
+ * @private
+ */
+export declare function isPageNumberStyleWire(value: string): boolean;
+/**
+ * @private
+ */
+export declare function pageNumberStyleFromWire(value: string | undefined): PageNumberStyle;

package/src/features/sections/page-number-style.js

@@ -0,0 +1,62 @@
+/**
+ * Page number formats (`ST_NumberFormat` subset used for page numbers).
+ *
+ * Canonical enum lives in core. Wire helpers stay feature-local.
+ *
+ * Maps to `w:pgNumType/@w:fmt`.
+ *
+ * @public
+ */
+export { PageNumberStyle } from '../document/page-setup';
+import { PageNumberStyle } from '../document/page-setup';
+/** Wire tokens accepted for `w:pgNumType/@w:fmt`. */
+export var PAGE_NUMBER_STYLE_WIRE = new Set([
+    'decimal',
+    'upperRoman',
+    'lowerRoman',
+    'upperLetter',
+    'lowerLetter',
+    'ordinal',
+    'cardinalText',
+    'ordinalText',
+    'numberInDash',
+    'chicago',
+]);
+/**
+ * @private
+ */
+export function isPageNumberStyleWire(value) {
+    return PAGE_NUMBER_STYLE_WIRE.has(value);
+}
+/**
+ * @private
+ */
+export function pageNumberStyleFromWire(value) {
+    if (value === undefined || !isPageNumberStyleWire(value)) {
+        return PageNumberStyle.Arabic;
+    }
+    switch (value) {
+        case 'decimal':
+            return PageNumberStyle.Arabic;
+        case 'upperRoman':
+            return PageNumberStyle.UpperRoman;
+        case 'lowerRoman':
+            return PageNumberStyle.LowerRoman;
+        case 'upperLetter':
+            return PageNumberStyle.UpperLetter;
+        case 'lowerLetter':
+            return PageNumberStyle.LowerLetter;
+        case 'ordinal':
+            return PageNumberStyle.Ordinal;
+        case 'cardinalText':
+            return PageNumberStyle.CardinalText;
+        case 'ordinalText':
+            return PageNumberStyle.OrdinalText;
+        case 'numberInDash':
+            return PageNumberStyle.NumberInDash;
+        case 'chicago':
+            return PageNumberStyle.Chicago;
+        default:
+            return PageNumberStyle.Arabic;
+    }
+}

package/src/features/sections/page-orientation.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Page orientation (`ST_PageOrientation`).
+ *
+ * Canonical definition lives in core so {@link Section.pageSetup} can type
+ * against it without a core→feature import. Re-exported here for the sections
+ * feature public surface.
+ *
+ * @public
+ */
+export { PageOrientation } from '../document/page-setup';

package/src/features/sections/page-orientation.js

@@ -0,0 +1,10 @@
+/**
+ * Page orientation (`ST_PageOrientation`).
+ *
+ * Canonical definition lives in core so {@link Section.pageSetup} can type
+ * against it without a core→feature import. Re-exported here for the sections
+ * feature public surface.
+ *
+ * @public
+ */
+export { PageOrientation } from '../document/page-setup';

package/src/features/sections/page-setup.d.ts

@@ -0,0 +1,435 @@
+import { BorderStyle, LineNumberingMode, PageBorderOffsetFrom, PageBordersApplyType, PageOrientation, PageNumberStyle, PageSetup as PageSetupContract, PrinterPaperTray, SizeF, VerticalAlignment, PageBorder as PageBorderContract, PageBorders as PageBordersContract } from '../document/page-setup';
+import { Color } from '../document/color';
+import { SectionPropertiesModel } from '../document/section-properties-model';
+import { OpenXmlAttribute, OpenXmlElement } from '../../core/xml/index';
+import { ColumnCollection } from './column-collection';
+import { Margins } from './margins';
+import { SectionBreakCode } from './section-break-code';
+export { BorderStyle, LineNumberingMode, PageBorderOffsetFrom, PageBordersApplyType, PageOrientation, PageNumberStyle, PrinterPaperTray, SizeF, VerticalAlignment, };
+/** @deprecated Prefer {@link VerticalAlignment}. Kept for internal parse bags. */
+export declare type SectionVerticalAlignment = VerticalAlignment | 'top' | 'center' | 'both' | 'bottom';
+/** Header or footer reference type (`ST_HdrFtr`) — wire tokens until odd rename. */
+export declare type HeaderFooterReferenceType = 'default' | 'first' | 'even';
+/**
+ * Where a header/footer target lives.
+ *
+ * @private
+ */
+export interface HeaderFooterTarget {
+    readonly kind: 'header' | 'footer';
+    readonly refType: HeaderFooterReferenceType;
+}
+/**
+ * Section link to a header or footer part (`CT_HdrFtrRef`).
+ *
+ * @private
+ */
+export interface HeaderFooterReference extends HeaderFooterTarget {
+    readonly relationshipId: string;
+}
+/** When line numbers restart counting (`ST_LineNumberRestart`). @private */
+export declare type LineNumberRestart = 'newPage' | 'newSection' | 'continuous';
+/**
+ * Parse bag for line numbering (`w:lnNumType` / `CT_LineNumber`).
+ *
+ * @private
+ */
+export interface LineNumbering {
+    readonly countBy: number;
+    readonly restart?: LineNumberRestart | undefined;
+    readonly startAt?: number | undefined;
+    readonly distanceFromText?: number | undefined;
+}
+/**
+ * Chapter-page numbering options (`w:pgNumType` chapter group).
+ *
+ * @private
+ */
+export interface ChapterNumbering {
+    readonly headingLevel: number;
+    readonly separator: 'hyphen' | 'period' | 'colon' | 'emDash' | 'enDash';
+}
+/**
+ * Parse bag for printer trays (`w:paperSrc` / `CT_PaperSource`).
+ *
+ * @private
+ */
+export interface PaperSource {
+    readonly firstPageTray?: number | undefined;
+    readonly otherPagesTray?: number | undefined;
+}
+/** Line style subset for page borders (parse bag). @private */
+export declare type PageBorderStyle = 'nil' | 'none' | 'single' | 'thick' | 'double' | 'dotted' | 'dashed' | 'dotDash' | 'dotDotDash' | 'triple' | 'thinThickSmallGap' | 'thickThinSmallGap' | 'thinThickThinSmallGap' | 'thinThickMediumGap' | 'thickThinMediumGap' | 'thinThickThinMediumGap' | 'thinThickLargeGap' | 'thickThinLargeGap' | 'thinThickThinLargeGap' | 'wave' | 'doubleWave' | 'dashSmallGap' | 'dashDotStroked' | 'threeDEmboss' | 'threeDEngrave' | 'outset' | 'inset';
+/**
+ * One page-border edge parse bag.
+ *
+ * @private
+ */
+export interface ParsedPageBorder {
+    readonly style: PageBorderStyle;
+    readonly widthPoints: number;
+    readonly offsetPoints: number;
+    readonly color: string;
+}
+/**
+ * Page border frame parse bag (`CT_PageBorders`).
+ *
+ * @private
+ */
+export interface ParsedPageBorders {
+    readonly applyTo: 'allPages' | 'firstPage' | 'notFirstPage';
+    readonly measureFrom: 'text' | 'page';
+    readonly zOrder: 'front' | 'back';
+    readonly top?: ParsedPageBorder | undefined;
+    readonly left?: ParsedPageBorder | undefined;
+    readonly bottom?: ParsedPageBorder | undefined;
+    readonly right?: ParsedPageBorder | undefined;
+}
+/**
+ * Values applied atomically by {@link PageSetup.createFromParsedValues}.
+ *
+ * @private
+ */
+export interface PageSetupParsedValues {
+    readonly attributes?: ReadonlyArray<OpenXmlAttribute>;
+    readonly prefix?: ReadonlyArray<OpenXmlElement>;
+    readonly suffix?: ReadonlyArray<OpenXmlElement>;
+    readonly headerFooterReferences?: ReadonlyArray<HeaderFooterReference>;
+    readonly breakCode?: SectionBreakCode;
+    readonly pageWidth: number;
+    readonly pageHeight: number;
+    readonly orientation?: PageOrientation;
+    readonly marginLeft: number;
+    readonly marginTop: number;
+    readonly marginRight: number;
+    readonly marginBottom: number;
+    readonly headerDistance?: number;
+    readonly footerDistance?: number;
+    readonly gutter?: number;
+    readonly paperSource?: PaperSource;
+    readonly pageBorders?: ParsedPageBorders;
+    readonly lineNumbering?: LineNumbering;
+    readonly pageStartingNumber?: number;
+    readonly restartPageNumbering?: boolean;
+    readonly pageNumberStyle?: PageNumberStyle;
+    readonly chapterNumbering?: ChapterNumbering;
+    readonly columns?: ColumnCollection;
+    readonly verticalAlignment?: VerticalAlignment | SectionVerticalAlignment;
+    readonly bidi?: boolean;
+    readonly differentFirstPage?: boolean;
+    readonly pageNumberingPresent?: boolean;
+}
+/**
+ * Live page-border edge — public surface is {@link space} only.
+ *
+ * @public
+ */
+export declare class PageBorder implements PageBorderContract {
+    private spaceValue;
+    private styleValue;
+    private colorWireValue;
+    private widthPointsValue;
+    /**
+     * @private
+     */
+    constructor();
+    space: number;
+    /**
+     * @private
+     */
+    readonly style: BorderStyle;
+    /**
+     * @private
+     */
+    readonly colorWire: string;
+    /**
+     * @private
+     */
+    readonly widthPoints: number;
+    /**
+     * @private
+     */
+    applyCommon(style: BorderStyle, colorWire: string, widthPoints: number): void;
+    /**
+     * @private
+     */
+    loadFromParsed(edge: ParsedPageBorder): void;
+    /**
+     * @private
+     */
+    toParsed(): ParsedPageBorder | undefined;
+    /**
+     * @private
+     */
+    cloneInto(target: PageBorder): void;
+}
+/**
+ * Live page borders — common style/color/width plus four edges.
+ *
+ * @public
+ */
+export declare class PageBorders implements PageBordersContract {
+    private borderTypeValue;
+    private colorPublicValue;
+    /** Wire color when the public Color cannot express the loaded token. */
+    private colorWireOverride;
+    private lineWidthValue;
+    private readonly topEdge;
+    private readonly bottomEdge;
+    private readonly leftEdge;
+    private readonly rightEdge;
+    private applyToValue;
+    private measureFromValue;
+    private zOrderValue;
+    /**
+     * @private
+     */
+    constructor();
+    borderType: BorderStyle;
+    color: Color;
+    lineWidth: number;
+    readonly top: PageBorder;
+    readonly bottom: PageBorder;
+    readonly left: PageBorder;
+    readonly right: PageBorder;
+    /**
+     * @private
+     */
+    readonly applyTo: ParsedPageBorders['applyTo'];
+    /**
+     * @private
+     */
+    setApplyTo(value: ParsedPageBorders['applyTo']): void;
+    /**
+     * @private
+     */
+    readonly measureFrom: ParsedPageBorders['measureFrom'];
+    /**
+     * @private
+     */
+    setMeasureFrom(value: ParsedPageBorders['measureFrom']): void;
+    /**
+     * @private
+     */
+    readonly zOrder: ParsedPageBorders['zOrder'];
+    /**
+     * @private
+     */
+    loadFromParsed(bag: ParsedPageBorders): void;
+    /**
+     * @private
+     */
+    toParsed(): ParsedPageBorders | undefined;
+    /**
+     * @private
+     */
+    copyFrom(source: PageBorders): void;
+    private stampCommonToEdges;
+    private resolveColorWire;
+}
+/**
+ * Live section page setup (`CT_SectPr` model) — public surface per architecture §§4–12.
+ *
+ * Implements the core {@link PageSetupContract} public contract and internal
+ * {@link SectionPropertiesModel} for dual-hold serialization.
+ *
+ * @public
+ */
+export declare class PageSetup implements PageSetupContract, SectionPropertiesModel {
+    private attributes;
+    private prefix;
+    private suffix;
+    private headerFooterReferencesValue;
+    private breakCodeValue;
+    private readonly pageSizeValue;
+    private orientationValue;
+    private readonly marginsValue;
+    private headerDistanceValue;
+    private footerDistanceValue;
+    private gutterValue;
+    private firstPageTrayValue;
+    private otherPagesTrayValue;
+    private paperSourcePresent;
+    private readonly bordersValue;
+    private lineNumberingPresent;
+    private lineNumberingDistanceFromTextValue;
+    private lineNumberingModeValue;
+    private lineNumberingStartValueValue;
+    private lineNumberingStepValue;
+    private pageStartingNumberValue;
+    private restartPageNumberingValue;
+    private pageNumberStyleValue;
+    private chapterNumberingValue;
+    /** True when `w:pgNumType` was present or numbering props were authored. */
+    private pageNumberingPresent;
+    private readonly columnsValue;
+    private verticalAlignmentValue;
+    private bidiValue;
+    private differentFirstPageValue;
+    /**
+     * @private
+     */
+    private constructor();
+    /**
+     * US Letter defaults (architecture § letter factory).
+     *
+     * @private
+     */
+    static createDefaultLetter(): PageSetup;
+    /**
+     * Atomic load-path construction — does not call public setters in sequence
+     * (avoids orientation last-write-wins side effects during parse).
+     *
+     * @private
+     */
+    static createFromParsedValues(values: PageSetupParsedValues): PageSetup;
+    /**
+     * @private
+     */
+    cloneDeep(): PageSetup;
+    /**
+     * Page orientation. Setter swaps width/height only when needed (architecture §7).
+     */
+    orientation: PageOrientation;
+    /**
+     * Live page size (stable identity). Setter copies width/height and derives orientation.
+     */
+    pageSize: SizeF;
+    /**
+     * Live margins instance (stable identity for the life of this PageSetup).
+     */
+    readonly margins: Margins;
+    /**
+     * Distance from page top to header (`w:pgMar/@w:header`), points.
+     */
+    headerDistance: number;
+    /**
+     * Distance from page bottom to footer (`w:pgMar/@w:footer`), points.
+     */
+    footerDistance: number;
+    /**
+     * Live page borders (stable identity).
+     */
+    readonly borders: PageBorders;
+    /**
+     * First-page printer tray (`w:paperSrc/@w:first`).
+     */
+    firstPageTray: PrinterPaperTray;
+    /**
+     * Other-pages printer tray (`w:paperSrc/@w:other`).
+     */
+    otherPagesTray: PrinterPaperTray;
+    /**
+     * Different first page (`w:titlePg`).
+     */
+    differentFirstPage: boolean;
+    /**
+     * Different odd and even pages — document-scoped via settings `w:evenAndOddHeaders`.
+     */
+    differentOddAndEvenPages: boolean;
+    /**
+     * Starting page number when restart is enabled (`w:pgNumType/@w:start`).
+     */
+    pageStartingNumber: number;
+    /**
+     * When `true`, write `w:start` with {@link pageStartingNumber}; when `false`, omit start.
+     */
+    restartPageNumbering: boolean;
+    /**
+     * Page number format (`w:pgNumType/@w:fmt`). Always emitted when numbering state is set.
+     */
+    pageNumberStyle: PageNumberStyle;
+    /**
+     * Distance from text to line numbers (`w:lnNumType/@w:distance`), points.
+     */
+    lineNumberingDistanceFromText: number;
+    /**
+     * Line-number restart mode (`w:lnNumType/@w:restart`).
+     */
+    lineNumberingMode: LineNumberingMode;
+    /**
+     * Line-number start value (one-based public API).
+     *
+     * Maps to zero-based `w:lnNumType/@w:start` as `wire = api - 1`.
+     * Example: API `1` ↔ `w:start="0"`.
+     */
+    lineNumberingStartValue: number;
+    /**
+     * Line-number count-by step (`w:lnNumType/@w:countBy`).
+     */
+    lineNumberingStep: number;
+    /**
+     * Section break kind. Public on {@link Section}; kept here for serialize.
+     *
+     * @private
+     */
+    /**
+    * @private
+    */
+    breakCode: SectionBreakCode;
+    /**
+     * Text columns collection (Section exposes the same instance).
+     *
+     * @private
+     */
+    readonly columns: ColumnCollection;
+    /**
+     * @private
+     */
+    readonly headerFooterReferences: ReadonlyArray<HeaderFooterReference>;
+    /**
+     * @private
+     */
+    headerFooterReferenceId(kind: 'header' | 'footer', refType: HeaderFooterReferenceType): string | undefined;
+    headerFooterReferenceId(target: HeaderFooterTarget): string | undefined;
+    /**
+     * @private
+     */
+    setHeaderFooterReference(kind: 'header' | 'footer', refType: HeaderFooterReferenceType, relationshipId: string | undefined): void;
+    setHeaderFooterReference(target: HeaderFooterTarget, relationshipId: string | undefined): void;
+    /**Gutter margin (`w:pgMar/@w:gutter`), points.
+     */
+    gutter: number;
+    /**
+     * Vertical text alignment on the page (`w:vAlign` / `ST_VerticalJc`).
+     */
+    verticalAlignment: VerticalAlignment;
+    /**
+     * Right-to-left section layout (`w:bidi`, ECMA-376-1 §17.6.1).
+     */
+    bidi: boolean;
+    /**
+     * Page border offset origin (`w:pgBorders/@w:offsetFrom`).
+     */
+    pageBorderOffsetFrom: PageBorderOffsetFrom;
+    /**
+     * Which pages receive page borders (`w:pgBorders/@w:display`).
+     */
+    pageBordersApplyType: PageBordersApplyType;
+    /**
+     * @private
+     */
+    /**
+    * @private
+    */
+    chapterNumbering: ChapterNumbering | undefined;
+    /**
+     * @private
+     */
+    private snapshotPaperSource;
+    /**
+     * @private
+     */
+    private snapshotLineNumbering;
+    /**
+     * Serialize `w:sectPr` in EG_SectPrContents order.
+     *
+     * @private
+     */
+    toOpenXml(): OpenXmlElement;
+}
+/**
+ * @private
+ * Default letter section factory (replaces `defaultLetterSection`).
+ */
+export declare function defaultLetterPageSetup(): PageSetup;