@syncfusion/ej2-docx 0.0.0-stage → 35.1.39

package/src/features/drawing/wrap-format.js

@@ -0,0 +1,114 @@
+/**
+ * Public WrapFormat owned by Shape / GroupShape (Shape.md §8).
+ * @packageDocumentation
+ */
+import { assertEnumMember, TEXT_WRAPPING_STYLE_SET, TEXT_WRAPPING_TYPE_SET, TextWrappingType, } from '../images/layout-types';
+/**
+ * Drawing host text-wrap formatting.
+ * @public
+ */
+var WrapFormat = /** @class */ (function () {
+    /** @private */
+    function WrapFormat(owner) {
+        this.owner = owner;
+    }
+    Object.defineProperty(WrapFormat.prototype, "textWrappingStyle", {
+        /** @public */
+        get: function () {
+            return this.owner.readWrapStyle();
+        },
+        set: function (value) {
+            assertEnumMember('textWrappingStyle', value, TEXT_WRAPPING_STYLE_SET);
+            this.owner.writeWrapStyle(value);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(WrapFormat.prototype, "textWrappingType", {
+        /** @public */
+        get: function () {
+            return this.owner.readWrapType();
+        },
+        set: function (value) {
+            if (value === TextWrappingType.Unknown) {
+                throw new RangeError('WrapFormat.textWrappingType cannot be set to TextWrappingType.Unknown');
+            }
+            assertEnumMember('textWrappingType', value, TEXT_WRAPPING_TYPE_SET);
+            this.owner.writeWrapType(value);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(WrapFormat.prototype, "allowOverlap", {
+        /** @public */
+        get: function () {
+            return this.owner.readAllowOverlap();
+        },
+        set: function (value) {
+            if (value !== true && value !== false) {
+                throw new RangeError('WrapFormat.allowOverlap must be a boolean');
+            }
+            this.owner.writeAllowOverlap(value);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(WrapFormat.prototype, "distanceTop", {
+        /** @public */
+        get: function () {
+            return this.owner.readDistanceTop();
+        },
+        set: function (value) {
+            if (typeof value !== 'number' || !Number.isFinite(value)) {
+                throw new RangeError('WrapFormat.distanceTop must be a finite number of points');
+            }
+            this.owner.writeDistanceTop(value);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(WrapFormat.prototype, "distanceBottom", {
+        /** @public */
+        get: function () {
+            return this.owner.readDistanceBottom();
+        },
+        set: function (value) {
+            if (typeof value !== 'number' || !Number.isFinite(value)) {
+                throw new RangeError('WrapFormat.distanceBottom must be a finite number of points');
+            }
+            this.owner.writeDistanceBottom(value);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(WrapFormat.prototype, "distanceLeft", {
+        /** @public */
+        get: function () {
+            return this.owner.readDistanceLeft();
+        },
+        set: function (value) {
+            if (typeof value !== 'number' || !Number.isFinite(value)) {
+                throw new RangeError('WrapFormat.distanceLeft must be a finite number of points');
+            }
+            this.owner.writeDistanceLeft(value);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(WrapFormat.prototype, "distanceRight", {
+        /** @public */
+        get: function () {
+            return this.owner.readDistanceRight();
+        },
+        set: function (value) {
+            if (typeof value !== 'number' || !Number.isFinite(value)) {
+                throw new RangeError('WrapFormat.distanceRight must be a finite number of points');
+            }
+            this.owner.writeDistanceRight(value);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    return WrapFormat;
+}());
+export { WrapFormat };

package/src/features/editable-ranges/index.d.ts

@@ -0,0 +1,494 @@
+import { WordDocument } from '../document/document';
+import { FeatureBlock } from '../document/feature-block';
+import { FeatureInline } from '../document/feature-inline';
+import { Paragraph } from '../document/paragraph';
+import { FeatureInlineParagraphItem, ParagraphItem } from '../document/text-range';
+import { OpenXmlAttribute, OpenXmlElement } from '../../core/xml/index';
+/**
+ * Editor group for an editable range (`ST_EdGrp`, ECMA-376-1 §17.18.21).
+ *
+ * `w:edGrp` on the start marker names the set of users who may edit the range.
+ * ECMA note: `w:ed` (a single editor) takes precedence over the group when both
+ * are present; the library stores both without resolving precedence.
+ *
+ * @private
+ */
+export declare const EditableRangeEditorGroup: {
+    None: string;
+    Everyone: string;
+    Administrators: string;
+    Contributors: string;
+    Editors: string;
+    Owners: string;
+    Current: string;
+};
+export declare type EditableRangeEditorGroup = (typeof EditableRangeEditorGroup)[keyof typeof EditableRangeEditorGroup];
+/**
+ * Physical displacement relative to a custom XML markup element
+ * (`ST_DisplacedByCustomXml`, ECMA-376-1 §17.18.13).
+ *
+ * @private
+ */
+export declare type DisplacedByCustomXml = 'next' | 'prev';
+/**
+ * Editable-range start marker (`w:permStart`, ECMA-376-1 §17.13.7.2).
+ *
+ * Paired with an {@link EditableRangeEnd} by matching {@link EditableRangeStart.rangeId}
+ * (`w:id`). Markers are first-class DOM nodes occupying an exact slot among
+ * paragraph inlines (or body blocks for run-level markers between paragraphs),
+ * so relative order versus runs, bookmarks, fields, and other content is stable.
+ *
+ * @remarks
+ * - `rangeId` maps `w:id` (non-negative after save materialization; a negative
+ *   pending id is allocated on author and remapped before save).
+ * - `editorGroup` maps `w:edGrp` (`ST_EdGrp`); `editor` maps `w:ed`.
+ * - `columnFirst` / `columnLast` map `w:colFirst` / `w:colLast` (zero-based
+ *   table column span).
+ * - Attributes outside the modeled set are preserved verbatim and re-emitted on
+ *   serialization (lossless round-trip).
+ * - `undefined` means the attribute is absent on serialize; assigning a value
+ *   emits it; assigning `undefined` removes it.
+ *
+ * @private
+ */
+export declare class EditableRangeStart implements FeatureInline, FeatureBlock {
+    private rangeIdValue;
+    private editorGroupValue;
+    private editorValue;
+    private columnFirstValue;
+    private columnLastValue;
+    private displacedByCustomXmlValue;
+    private readonly residual;
+    /**
+     * @private
+     */
+    constructor(rangeId: number, options?: {
+        readonly editorGroup?: EditableRangeEditorGroup | undefined;
+        readonly editor?: string | undefined;
+        readonly columnFirst?: number | undefined;
+        readonly columnLast?: number | undefined;
+        readonly displacedByCustomXml?: DisplacedByCustomXml | undefined;
+        readonly residualAttributes?: ReadonlyArray<OpenXmlAttribute> | undefined;
+    });
+    /**
+     * Editable-range identifier shared with the paired end marker (`w:id`).
+     */
+    readonly rangeId: number;
+    /**
+     * @private
+     */
+    setRangeId(rangeId: number): void;
+    /**
+     * @private
+     */
+    isPendingRangeId(): boolean;
+    /**
+     * Editor group allowed to edit the range (`w:edGrp`, `ST_EdGrp`).
+     */
+    editorGroup: EditableRangeEditorGroup | undefined;
+    /**
+     * Single editor allowed to edit the range (`w:ed`) — `DOMAIN\user`,
+     * `user@domain`, or a machine-local `user` form.
+     */
+    editor: string | undefined;
+    /**
+     * Zero-based first table column of the range (`w:colFirst`).
+     */
+    columnFirst: number | undefined;
+    /**
+     * Zero-based last table column of the range (`w:colLast`).
+     */
+    columnLast: number | undefined;
+    /**
+     * Displacement relative to a custom XML markup element
+     * (`w:displacedByCustomXml`).
+     */
+    displacedByCustomXml: DisplacedByCustomXml | undefined;
+    /**
+     * @private
+   * Residual attributes preserved for lossless serialization. */
+    residualAttributes(): ReadonlyArray<OpenXmlAttribute>;
+    /**
+     * @private
+     */
+    releaseContent(): void;
+    toOpenXml(): OpenXmlElement;
+}
+/**
+ * Editable-range end marker (`w:permEnd`, ECMA-376-1 §17.13.7.1).
+ *
+ * Paired with an {@link EditableRangeStart} by matching `w:id`. The end marker
+ * carries only the identifier, optional displacement, and residual attributes.
+ *
+ * @private
+ */
+export declare class EditableRangeEnd implements FeatureInline, FeatureBlock {
+    private rangeIdValue;
+    private displacedByCustomXmlValue;
+    private readonly residual;
+    /**
+     * @private
+     */
+    constructor(rangeId: number, options?: {
+        readonly displacedByCustomXml?: DisplacedByCustomXml | undefined;
+        readonly residualAttributes?: ReadonlyArray<OpenXmlAttribute> | undefined;
+    });
+    /**
+     * Editable-range identifier shared with the paired start marker (`w:id`).
+     */
+    readonly rangeId: number;
+    /**
+     * @private
+     */
+    setRangeId(rangeId: number): void;
+    /**
+     * @private
+     */
+    isPendingRangeId(): boolean;
+    /**
+     * Displacement relative to a custom XML markup element
+     * (`w:displacedByCustomXml`).
+     */
+    displacedByCustomXml: DisplacedByCustomXml | undefined;
+    /**
+     * @private
+   * Residual attributes preserved for lossless serialization. */
+    residualAttributes(): ReadonlyArray<OpenXmlAttribute>;
+    /**
+     * @private
+     */
+    releaseContent(): void;
+    toOpenXml(): OpenXmlElement;
+}
+/**
+ * Live query view over a paired start/end marker pair, resolved by `w:id`.
+ *
+ * The view does not own markup: {@link EditableRangeStart} and
+ * {@link EditableRangeEnd} remain in their host containers (which may be
+ * different paragraphs), and property reads write through to the live start
+ * marker.
+ *
+ * @private
+ */
+export declare class EditableRange {
+    private readonly startMarkerValue;
+    private readonly endMarkerValue;
+    /**
+     * @private
+     */
+    constructor(start: EditableRangeStart, end: EditableRangeEnd);
+    /**
+     * Identifier shared by the paired markers (`w:id`).
+     */
+    readonly rangeId: number;
+    /**
+     * Start marker (`w:permStart`).
+     */
+    readonly startMarker: EditableRangeStart;
+    /**
+     * End marker (`w:permEnd`).
+     */
+    readonly endMarker: EditableRangeEnd;
+    /**
+     * Editor group allowed to edit the range (`w:edGrp` on the start marker).
+     * Assignment writes through to {@link EditableRangeStart.editorGroup}.
+     */
+    editorGroup: EditableRangeEditorGroup | undefined;
+    /**
+     * Single editor allowed to edit the range (`w:ed` on the start marker).
+     * Assignment writes through to {@link EditableRangeStart.editor}.
+     */
+    editor: string | undefined;
+    /**
+     * Zero-based first table column of the range (`w:colFirst`).
+     */
+    readonly columnFirst: number | undefined;
+    /**
+     * Zero-based last table column of the range (`w:colLast`).
+     */
+    readonly columnLast: number | undefined;
+    /**
+     * Whether both markers are paragraph inlines of the same paragraph.
+     *
+     * Requires a document walk; pass the owning document via
+     * {@link editableRangeMarkersShareParagraph}.
+     *
+     * @deprecated Prefer {@link editableRangeMarkersShareParagraph}.
+     * @private
+     */
+    markersShareParagraph(document: WordDocument): boolean;
+}
+/**
+ * Whether both markers of a paired range are inlines of the same paragraph.
+ *
+ * @private
+ */
+export declare function editableRangeMarkersShareParagraph(document: WordDocument, range: EditableRange): boolean;
+/**
+ * Deep-clone a start marker, optionally overriding `rangeId`.
+ *
+ * Residual attributes are copied. Used by paragraph/content clone helpers that
+ * re-insert ranges without sharing live marker instances.
+ *
+ * @private
+ */
+export declare function cloneEditableRangeStart(source: EditableRangeStart, options?: {
+    readonly rangeId?: number;
+}): EditableRangeStart;
+/**
+ * Deep-clone an end marker, optionally overriding `rangeId`.
+ *
+ * @private
+ */
+export declare function cloneEditableRangeEnd(source: EditableRangeEnd, options?: {
+    readonly rangeId?: number;
+}): EditableRangeEnd;
+/**
+ * Clone a paired range’s markers onto a target document with a fresh pending id.
+ *
+ * Returns detached start/end clones (not inserted). Callers insert them into
+ * the desired hosts. Both clones share the same pending id so they pair after
+ * insertion. Does not mutate the source markers.
+ *
+ * @private
+ */
+export declare function cloneEditableRangeForInsert(document: WordDocument, range: EditableRange): {
+    readonly start: EditableRangeStart;
+    readonly end: EditableRangeEnd;
+};
+/**
+ * Remove both markers of a paired editable range; enclosed content is kept.
+ *
+ * Markers may be paragraph inlines and/or body-level feature blocks. After
+ * removal the pair is gone from query APIs; orphan policy does not apply
+ * because both ends are deleted together.
+ *
+ * @param document - Owning document (used for body-level marker removal)
+ * @param range - Pair view from a query or authoring API
+ * @returns Nothing
+ * @throws {@link DocxError} `content/unknown-editable-range` when either marker
+ *   is not found in the document.
+ * @example
+ * ```ts
+ * const [range] = editableRangesInDocument(doc);
+ * if (range) removeEditableRange(doc, range);
+ * ```
+ * @private
+ */
+export declare function removeEditableRange(document: WordDocument, range: EditableRange): void;
+/**
+ * Move a single modeled marker from one paragraph content slot to another.
+ *
+ * Used for same-document reorder tests; does not change `rangeId`. When the
+ * marker is a body-level feature block, it is removed from the body and
+ * inserted as an inline in the target paragraph.
+ *
+ * @private
+ */
+export declare function moveEditableRangeMarkerToParagraph(document: WordDocument, marker: EditableRangeStart | EditableRangeEnd, targetParagraph: Paragraph, inlineIndex: number): void;
+/**
+ * Remap every editable-range marker in a paragraph to fresh pending ids, pairing
+ * starts with ends that share the previous id within the paragraph only.
+ *
+ * Intended for “clone paragraph then insert” flows so positive ids are not
+ * duplicated in the document. Cross-paragraph half-clones keep unpaired markers
+ * with new pending ids (one id per marker).
+ *
+ * @private
+ */
+export declare function remapEditableRangeIdsInParagraphToPending(paragraph: Paragraph): void;
+/**
+ * Clone all editable-range markers found as paragraph inlines, preserving local
+ * pairing by assigning one fresh pending id per former id shared by start/end
+ * in this paragraph.
+ *
+ * Returns new marker instances (not inserted). Non-range inlines are ignored —
+ * callers building a full paragraph clone still need core paragraph clone support.
+ *
+ * @private
+ */
+export declare function cloneEditableRangeMarkersFromParagraph(document: WordDocument, sourceParagraph: Paragraph): {
+    readonly markers: ReadonlyArray<{
+        readonly index: number;
+        readonly marker: EditableRangeStart | EditableRangeEnd;
+    }>;
+};
+declare type EditableRangeMarker = EditableRangeStart | EditableRangeEnd;
+/**
+ * All paired editable ranges in document order of their start markers.
+ *
+ * Walks body-level markers and paragraph inlines (including nested feature
+ * paragraphs such as table cells). Unpaired start/end markers are omitted from
+ * the list but remain in the DOM and continue to serialize.
+ *
+ * @param document - WordDocument whose body is walked
+ * @returns Stable pair views (same start marker → same `EditableRange` object)
+ * @example
+ * ```ts
+ * for (const range of editableRangesInDocument(doc)) {
+ *   console.log(range.rangeId, range.editorGroup);
+ * }
+ * ```
+ * @private
+ */
+export declare function editableRangesInDocument(document: WordDocument): ReadonlyArray<EditableRange>;
+/**
+ * Paired editable ranges whose start marker lies in this paragraph.
+ *
+ * The matching end may be in the same paragraph, a later paragraph, or a
+ * body-level feature block. Unpaired starts in the paragraph are omitted.
+ *
+ * @param paragraph - Paragraph that may host start markers
+ * @returns Subset of {@link editableRangesInDocument} for this paragraph
+ * @example
+ * ```ts
+ * const starts = editableRangesStartingInParagraph(doc.body.paragraphs[0]!);
+ * ```
+ * @private
+ */
+export declare function editableRangesStartingInParagraph(paragraph: Paragraph): ReadonlyArray<EditableRange>;
+/**
+ * First paired editable range with this range identifier, if any.
+ *
+ * When duplicate starts share an id, the first start in document order that
+ * successfully pairs wins (see pairing algorithm).
+ *
+ * @param document - WordDocument to search
+ * @param rangeId - `w:id` value (`EditableRange.rangeId`)
+ * @returns First matching pair, or `undefined`
+ * @example
+ * ```ts
+ * const range = editableRangeById(doc, 0);
+ * ```
+ * @private
+ */
+export declare function editableRangeById(document: WordDocument, rangeId: number): EditableRange | undefined;
+/**
+ * Modeled editable-range markers in document order (paired and unpaired).
+ *
+ * Useful for diagnostics and tests; public authoring stays on pair views.
+ *
+ * @param document - WordDocument whose markers are listed
+ * @returns Start and end markers in document order
+ * @private
+ */
+export declare function editableRangeMarkersInDocument(document: WordDocument): ReadonlyArray<EditableRangeMarker>;
+/**
+ * @private
+ * Allocate a pending (negative) id unique among editable-range markers. */
+export declare function allocatePendingEditableRangeId(document: WordDocument): number;
+/**
+ * Next free non-negative editable-range id for the document (max existing + 1).
+ *
+ * Does not allocate or mutate markers; save-time materialization still remaps
+ * pending negative ids independently.
+ *
+ * @param document - WordDocument to scan
+ * @returns Smallest non-negative id not used by any marker
+ * @private
+ */
+export declare function nextEditableRangeId(document: WordDocument): number;
+/**
+ * @private
+ * Test hook */
+export declare function resetEditableRangesFeatureForTests(): void;
+/**
+ * Register the editable-ranges feature handlers. Idempotent.
+ *
+ * Registers inline handlers (`w:permStart` / `w:permEnd` inside paragraphs),
+ * the matching body block handlers (run-level markers between paragraphs), and
+ * the save-time materialization pass that remaps pending negative identifiers
+ * to the next free non-negative `w:id`. When this module is not imported,
+ * editable-range markup stays opaque and is preserved byte-for-byte.
+ *
+ * @returns Nothing
+ * @example
+ * ```ts
+ * import { registerEditableRangesFeature } from '@syncfusion/ej2-docx/editable-ranges';
+ * registerEditableRangesFeature();
+ * ```
+ * @private
+ */
+export declare function registerEditableRangesFeature(): void;
+/**
+ * Whether paragraph inline content is a modeled editable-range start marker
+ * (`w:permStart`) from this module.
+ *
+ * @private
+ */
+export declare function isEditableRangeStartInline(inline: ParagraphItem): inline is FeatureInlineParagraphItem & {
+    value: EditableRangeStart;
+};
+/**
+ * Whether paragraph inline content is a modeled editable-range end marker
+ * (`w:permEnd`) from this module.
+ *
+ * @private
+ */
+export declare function isEditableRangeEndInline(inline: ParagraphItem): inline is FeatureInlineParagraphItem & {
+    value: EditableRangeEnd;
+};
+/**
+ * Options when wrapping existing paragraph content in an editable range.
+ *
+ * @private
+ */
+export interface EditableRangeWrapOptions {
+    /** Inclusive start index into `paragraph.content` (pre-insert). */
+    startInlineIndex: number;
+    /** Exclusive end index into `paragraph.content` (pre-insert). */
+    endInlineIndex: number;
+    /** Optional editor group (`w:edGrp`). */
+    editorGroup?: EditableRangeEditorGroup;
+    /** Optional single editor name (`w:ed`). */
+    editor?: string;
+    /** Optional first table column index (`w:colFirst`). */
+    columnFirst?: number;
+    /** Optional last table column index (`w:colLast`). */
+    columnLast?: number;
+}
+/**
+ * Wrap an existing same-paragraph content slice in a new editable range.
+ *
+ * Indices refer to the current `paragraph.content` array **before** insertion:
+ * the start marker is inserted at `startInlineIndex`, and the end marker is
+ * inserted so that it follows the original slice
+ * (`endInlineIndex + 1` after the start push). Enclosed content is not copied
+ * or moved. Cross-paragraph authoring is not supported — use load/preserve for
+ * multi-paragraph ranges.
+ *
+ * @param paragraph - Paragraph that owns the inlines to wrap
+ * @param options - Inclusive/exclusive indices and optional editor metadata
+ * @returns Live pair view for the new markers (pending id until save)
+ * @example
+ * ```ts
+ * insertEditableRangeAt(paragraph, {
+ *   startInlineIndex: 1,
+ *   endInlineIndex: 2,
+ *   editorGroup: 'editors',
+ * });
+ * ```
+ * @private
+ */
+export declare function insertEditableRangeAt(paragraph: Paragraph, options: EditableRangeWrapOptions): EditableRange;
+/**
+ * Options for {@link Paragraph.appendEditableRange}.
+ *
+ * @private
+ */
+export interface AppendEditableRangeOptions {
+    /** Optional editor group (`w:edGrp`). */
+    editorGroup?: EditableRangeEditorGroup;
+    /** Optional single editor name (`w:ed`). */
+    editor?: string;
+    /** Optional first table column index (`w:colFirst`). */
+    columnFirst?: number;
+    /** Optional last table column index (`w:colLast`). */
+    columnLast?: number;
+}
+/**
+ * Feature id string for editable-range markers (`editable-ranges`).
+ * @private
+ */
+export declare const EDITABLE_RANGES_FEATURE_ID: import("../../core/registry").FeatureId;
+export {};