@syncfusion/ej2-docx 0.0.0-stage → 35.1.39

package/src/features/images/caption-authoring-api.d.ts

@@ -0,0 +1,33 @@
+import { Paragraph } from '../document/paragraph';
+import { CaptionNumberingFormat, CaptionPosition } from './caption-enums';
+import { Picture } from './index';
+/**
+ * Caption authoring entry installed by `./captions.js` when fields + styles are
+ * available. Kept as a soft registry so the always-on images graph does not
+ * static-import those optional modules into `dist/index.js`.
+ */
+export declare type AddCaptionToPicture = (picture: Picture, captionName: string, numberingFormat: CaptionNumberingFormat, position: CaptionPosition) => Paragraph;
+/**
+ * @private
+ * Installed by the captions authoring module on load. */
+export declare function providePictureCaptionAuthoring(impl: AddCaptionToPicture): void;
+/**
+ * @private
+ * Resolve the installed caption authoring implementation.
+ * @throws DocxError when captions authoring was not loaded (fields/styles path).
+ */
+export declare function requirePictureCaptionAuthoring(): AddCaptionToPicture;
+/**
+ * @deprecated Use {@link AddCaptionToPicture} instead.
+ */
+export declare type AddCaptionToImage = AddCaptionToPicture;
+/**
+ * @private
+ * @deprecated Use {@link providePictureCaptionAuthoring} instead.
+ */
+export declare function provideImageCaptionAuthoring(impl: AddCaptionToPicture): void;
+/**
+ * @private
+ * @deprecated Use {@link requirePictureCaptionAuthoring} instead.
+ */
+export declare function requireImageCaptionAuthoring(): AddCaptionToPicture;

package/src/features/images/caption-authoring-api.js

@@ -0,0 +1,33 @@
+import { DocxError } from '../../core/errors/docx-error';
+var addCaptionToPictureImpl;
+/**
+ * @private
+ * Installed by the captions authoring module on load. */
+export function providePictureCaptionAuthoring(impl) {
+    addCaptionToPictureImpl = impl;
+}
+/**
+ * @private
+ * Resolve the installed caption authoring implementation.
+ * @throws DocxError when captions authoring was not loaded (fields/styles path).
+ */
+export function requirePictureCaptionAuthoring() {
+    if (addCaptionToPictureImpl === undefined) {
+        throw new DocxError('feature/not-registered', 'Picture caption authoring is not loaded; import @syncfusion/ej2-docx/images (or load captions authoring with fields and styles) before addCaption');
+    }
+    return addCaptionToPictureImpl;
+}
+/**
+ * @private
+ * @deprecated Use {@link providePictureCaptionAuthoring} instead.
+ */
+export function provideImageCaptionAuthoring(impl) {
+    providePictureCaptionAuthoring(impl);
+}
+/**
+ * @private
+ * @deprecated Use {@link requirePictureCaptionAuthoring} instead.
+ */
+export function requireImageCaptionAuthoring() {
+    return requirePictureCaptionAuthoring();
+}

package/src/features/images/caption-enums.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Numbering formats for image-caption `SEQ` fields.
+ *
+ * Each value maps to the corresponding general-formatting switch of the `SEQ`
+ * field instruction (ECMA-376-1 §17.16.5 switch table).
+ *
+ * @public
+ */
+export declare const CaptionNumberingFormat: {
+    /** `\* ARABIC` — decimal digits (`1`, `2`, `3`). */
+    Arabic: string;
+    /** `\* ROMAN` — uppercase Roman numerals (`I`, `II`, `III`). */
+    UpperCaseRoman: string;
+    /** `\* roman` — lowercase Roman numerals (`i`, `ii`, `iii`). */
+    LowerCaseRoman: string;
+    /** `\* ALPHABETIC` — uppercase letters (`A`, `B`, … `Z`, `AA`). */
+    UpperCaseLetter: string;
+    /** `\* alphabetic` — lowercase letters (`a`, `b`, … `z`, `aa`). */
+    LowerCaseLetter: string;
+};
+/** One of the {@link CaptionNumberingFormat} tokens. @public */
+export declare type CaptionNumberingFormat = (typeof CaptionNumberingFormat)[keyof typeof CaptionNumberingFormat];
+/**
+ * Position of a caption paragraph relative to the image's paragraph.
+ *
+ * @public
+ */
+export declare const CaptionPosition: {
+    /** Caption paragraph immediately before the image paragraph. */
+    Above: string;
+    /** Caption paragraph immediately after the image paragraph. */
+    Below: string;
+};
+/** One of the {@link CaptionPosition} tokens. @public */
+export declare type CaptionPosition = (typeof CaptionPosition)[keyof typeof CaptionPosition];
+/**
+ * Word `SEQ` general-formatting switch for each numbering format
+ * (ECMA-376-1 §17.16.5 switch table; tokens must not be invented beyond these).
+ *
+ * @private
+ */
+export declare const CAPTION_FORMAT_SWITCH: Readonly<Record<CaptionNumberingFormat, string>>;
+/**
+ * @private
+ */
+export declare const CAPTION_NUMBERING_FORMATS: ReadonlySet<string>;
+/**
+ * @private
+ */
+export declare const CAPTION_POSITIONS: ReadonlySet<string>;
+/** Format a 1-based sequence value per the numbering format (Word display rules). */
+export declare function formatSequenceValue(value: number, format: CaptionNumberingFormat): string;

package/src/features/images/caption-enums.js

@@ -0,0 +1,141 @@
+var __values = (this && this.__values) || function (o) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator], i = 0;
+    if (m) return m.call(o);
+    return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+};
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+var _a;
+import { objectValues } from '../../core/compat/object-compat';
+/**
+ * Numbering formats for image-caption `SEQ` fields.
+ *
+ * Each value maps to the corresponding general-formatting switch of the `SEQ`
+ * field instruction (ECMA-376-1 §17.16.5 switch table).
+ *
+ * @public
+ */
+export var CaptionNumberingFormat = {
+    /** `\* ARABIC` — decimal digits (`1`, `2`, `3`). */
+    Arabic: 'arabic',
+    /** `\* ROMAN` — uppercase Roman numerals (`I`, `II`, `III`). */
+    UpperCaseRoman: 'upperCaseRoman',
+    /** `\* roman` — lowercase Roman numerals (`i`, `ii`, `iii`). */
+    LowerCaseRoman: 'lowerCaseRoman',
+    /** `\* ALPHABETIC` — uppercase letters (`A`, `B`, … `Z`, `AA`). */
+    UpperCaseLetter: 'upperCaseLetter',
+    /** `\* alphabetic` — lowercase letters (`a`, `b`, … `z`, `aa`). */
+    LowerCaseLetter: 'lowerCaseLetter',
+};
+/**
+ * Position of a caption paragraph relative to the image's paragraph.
+ *
+ * @public
+ */
+export var CaptionPosition = {
+    /** Caption paragraph immediately before the image paragraph. */
+    Above: 'above',
+    /** Caption paragraph immediately after the image paragraph. */
+    Below: 'below',
+};
+/**
+ * Word `SEQ` general-formatting switch for each numbering format
+ * (ECMA-376-1 §17.16.5 switch table; tokens must not be invented beyond these).
+ *
+ * @private
+ */
+export var CAPTION_FORMAT_SWITCH = (_a = {},
+    _a[CaptionNumberingFormat.Arabic] = 'ARABIC',
+    _a[CaptionNumberingFormat.UpperCaseRoman] = 'ROMAN',
+    _a[CaptionNumberingFormat.LowerCaseRoman] = 'roman',
+    _a[CaptionNumberingFormat.UpperCaseLetter] = 'ALPHABETIC',
+    _a[CaptionNumberingFormat.LowerCaseLetter] = 'alphabetic',
+    _a);
+/**
+ * @private
+ */
+export var CAPTION_NUMBERING_FORMATS = new Set(objectValues(CaptionNumberingFormat));
+/**
+ * @private
+ */
+export var CAPTION_POSITIONS = new Set(objectValues(CaptionPosition));
+/** Format a 1-based sequence value per the numbering format (Word display rules). */
+export function formatSequenceValue(value, format) {
+    if (format === CaptionNumberingFormat.Arabic) {
+        return String(value);
+    }
+    if (format === CaptionNumberingFormat.UpperCaseRoman ||
+        format === CaptionNumberingFormat.LowerCaseRoman) {
+        var roman = toRoman(value);
+        return format === CaptionNumberingFormat.UpperCaseRoman ? roman : roman.toLowerCase();
+    }
+    return toAlphabetic(value, format === CaptionNumberingFormat.UpperCaseLetter);
+}
+var ROMAN_STEPS = [
+    [1000, 'M'],
+    [900, 'CM'],
+    [500, 'D'],
+    [400, 'CD'],
+    [100, 'C'],
+    [90, 'XC'],
+    [50, 'L'],
+    [40, 'XL'],
+    [10, 'X'],
+    [9, 'IX'],
+    [5, 'V'],
+    [4, 'IV'],
+    [1, 'I'],
+];
+function toRoman(value) {
+    var e_1, _a;
+    var remaining = value;
+    var out = '';
+    try {
+        for (var ROMAN_STEPS_1 = __values(ROMAN_STEPS), ROMAN_STEPS_1_1 = ROMAN_STEPS_1.next(); !ROMAN_STEPS_1_1.done; ROMAN_STEPS_1_1 = ROMAN_STEPS_1.next()) {
+            var _b = __read(ROMAN_STEPS_1_1.value, 2), step = _b[0], glyph = _b[1];
+            while (remaining >= step) {
+                out += glyph;
+                remaining -= step;
+            }
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (ROMAN_STEPS_1_1 && !ROMAN_STEPS_1_1.done && (_a = ROMAN_STEPS_1.return)) _a.call(ROMAN_STEPS_1);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    return out;
+}
+/** 1→`A` … 26→`Z`, 27→`AA` (Word alphabetic wrap). */
+function toAlphabetic(value, upper) {
+    var remaining = value;
+    var out = '';
+    while (remaining > 0) {
+        var digit = ((remaining - 1) % 26) + 1;
+        var char = String.fromCharCode((upper ? 64 : 96) + digit);
+        out = char + out;
+        remaining = Math.floor((remaining - 1) / 26);
+    }
+    return out;
+}

package/src/features/images/caption-host.d.ts

@@ -0,0 +1,10 @@
+import { WordDocument } from '../document/document';
+import { Picture } from './index';
+/**
+ * @private
+ * Bind a picture to its owning document (load + authoring paths). */
+export declare function bindCaptionHostDocument(picture: Picture, document: WordDocument): void;
+/**
+ * @private
+ * Host document of a picture, when bound. */
+export declare function hostDocumentOf(picture: Picture): WordDocument | undefined;

package/src/features/images/caption-host.js

@@ -0,0 +1,21 @@
+/**
+ * Owning-document contact point for inline-picture leaves. Authored pictures bind
+ * their owning document at `appendImage`; loaded pictures bind during body parse
+ * (module-level WeakMap, keyed by the picture instance).
+ *
+ * Kept free of fields/styles imports so always-on images registration can bind
+ * hosts without pulling optional feature modules into the core bundle.
+ */
+var hostDocuments = new WeakMap();
+/**
+ * @private
+ * Bind a picture to its owning document (load + authoring paths). */
+export function bindCaptionHostDocument(picture, document) {
+    hostDocuments.set(picture, document);
+}
+/**
+ * @private
+ * Host document of a picture, when bound. */
+export function hostDocumentOf(picture) {
+    return hostDocuments.get(picture);
+}

package/src/features/images/captions.d.ts

@@ -0,0 +1,13 @@
+import { Paragraph } from '../document/paragraph';
+import { CaptionNumberingFormat as CaptionNumberingFormatValue, CaptionPosition as CaptionPositionValue } from './caption-enums';
+import { Picture } from './index';
+/**
+ * Build the caption paragraph and insert it relative to the picture paragraph.
+ * @private
+ */
+export declare function addCaptionToPicture(picture: Picture, captionName: string, numberingFormat: CaptionNumberingFormatValue, position: CaptionPositionValue): Paragraph;
+/**
+ * @deprecated Use {@link addCaptionToPicture} instead.
+ * @private
+ */
+export declare function addCaptionToImage(image: Picture, captionName: string, numberingFormat: CaptionNumberingFormatValue, position: CaptionPositionValue): Paragraph;

package/src/features/images/captions.js

@@ -0,0 +1,142 @@
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+var __spread = (this && this.__spread) || function () {
+    for (var ar = [], i = 0; i < arguments.length; i++) ar = ar.concat(__read(arguments[i]));
+    return ar;
+};
+var __values = (this && this.__values) || function (o) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator], i = 0;
+    if (m) return m.call(o);
+    return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+};
+/**
+* Picture caption authoring. Imports fields + styles; must not be pulled into the
+* always-on core graph. Loaded from the images public feature entry
+* (`@syncfusion/ej2-docx/images`) so `addCaption` works without embedding those optionals in
+* `dist/index.js`.
+*/
+import { DetachedObjectError, DocxError } from '../../core/errors/docx-error';
+import { ParagraphAlignment } from '../document/alignment';
+import { visitParagraphsInDocumentOrder } from '../../core/registry/index';
+import { appendOpaqueComplexField, fieldInstructionKeyword, opaqueComplexFieldInstructionsInParagraph } from '../fields/index';
+import { stylesFor } from '../styles/index';
+import { providePictureCaptionAuthoring } from './caption-authoring-api';
+import { CAPTION_FORMAT_SWITCH, CAPTION_NUMBERING_FORMATS, CAPTION_POSITIONS, CaptionPosition as CaptionPos, formatSequenceValue, } from './caption-enums';
+import { hostDocumentOf } from './caption-host';
+import { picturesInParagraph } from './index';
+/** Built-in caption paragraph style id (`w:pStyle w:val="Caption"`). */
+var CAPTION_STYLE_ID = 'Caption';
+function assertEnumMember(label, value, allowed) {
+    if (!allowed.has(value)) {
+        if (label === 'format') {
+            throw new DocxError('content/invalid-image-caption-format', "Invalid " + label + " value \"" + value + "\"; expected one of: " + __spread(allowed).join(', '));
+        }
+        throw new DocxError('content/invalid-image-caption-position', "Invalid " + label + " value \"" + value + "\"; expected one of: " + __spread(allowed).join(', '));
+    }
+}
+/**
+ * Locate the body paragraph containing `picture`.
+ *
+ * @throws DetachedObjectError when the picture is not attached to a paragraph in
+ * a document body.
+ */
+function paragraphForPicture(document, picture) {
+    var blocks = document.listBlocks();
+    for (var index = 0; index < blocks.length; index += 1) {
+        var block = blocks[index];
+        if (block === undefined || block.type !== 'paragraph') {
+            continue;
+        }
+        if (picturesInParagraph(block.paragraph).indexOf(picture) !== -1) {
+            return { paragraph: block.paragraph, blockIndex: index };
+        }
+    }
+    throw new DetachedObjectError('This picture is not attached to a paragraph in a document body; captions require a main-body picture paragraph');
+}
+/**
+ * Count existing `SEQ <identifier>` complex fields (any switch) in document order.
+ */
+function countSeqFields(document, identifier) {
+    var count = 0;
+    visitParagraphsInDocumentOrder(document, function (paragraph) {
+        var e_1, _a;
+        var __ts33_0;
+        try {
+            for (var _b = __values(opaqueComplexFieldInstructionsInParagraph(paragraph)), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var instruction = _c.value;
+                if (fieldInstructionKeyword(instruction) !== 'SEQ') {
+                    continue;
+                }
+                if ((((__ts33_0 = instruction.trim().split(/\s+/)[1]), __ts33_0 != null ? __ts33_0 : '')) === identifier) {
+                    count += 1;
+                }
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+    });
+    return count;
+}
+/**
+ * Build the caption paragraph and insert it relative to the picture paragraph.
+ * @private
+ */
+export function addCaptionToPicture(picture, captionName, numberingFormat, position) {
+    if (typeof captionName !== 'string' || captionName.trim().length === 0) {
+        throw new DocxError('content/invalid-image-caption-name', 'Caption name must be a non-empty string (not null, undefined, empty, or whitespace-only)');
+    }
+    assertEnumMember('format', String(numberingFormat), CAPTION_NUMBERING_FORMATS);
+    assertEnumMember('position', String(position), CAPTION_POSITIONS);
+    var document = hostDocumentOf(picture);
+    if (document === undefined) {
+        throw new DetachedObjectError('This picture is not attached to a document; attach it with paragraph.appendImage() before adding a caption');
+    }
+    var blockIndex = paragraphForPicture(document, picture).blockIndex;
+    var name = captionName.trim();
+    stylesFor(document).ensureParagraphStyle(CAPTION_STYLE_ID);
+    var instruction = "SEQ " + name + " \\* " + CAPTION_FORMAT_SWITCH[numberingFormat];
+    // Insert first (attaches the paragraph), then populate: Paragraph setters
+    // and appendText/appendField require an attached paragraph.
+    var caption = document.insertParagraphAtBlockIndex(position === CaptionPos.Above ? blockIndex : blockIndex + 1);
+    caption.styleId = CAPTION_STYLE_ID;
+    var captionFormat = caption.paragraphFormat;
+    captionFormat.beforeSpacing = 1.5;
+    captionFormat.afterSpacing = 12;
+    captionFormat.horizontalAlignment = ParagraphAlignment.Center;
+    caption.appendText(name + " ");
+    var result = formatSequenceValue(countSeqFields(document, name) + 1, numberingFormat);
+    appendOpaqueComplexField(caption, instruction, { result: result });
+    return caption;
+}
+/**
+ * @deprecated Use {@link addCaptionToPicture} instead.
+ * @private
+ */
+export function addCaptionToImage(image, captionName, numberingFormat, position) {
+    return addCaptionToPicture(image, captionName, numberingFormat, position);
+}
+providePictureCaptionAuthoring(addCaptionToPicture);

package/src/features/images/host-codec.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Picture DrawingML host decode/encode helpers (`wp:inline` / `wp:anchor` + `pic:pic`).
+ *
+ * Schema cites (Transitional `dml-wordprocessingDrawing.xsd`):
+ * - `CT_Inline`, `CT_Anchor`, `EG_WrapType`
+ * - `CT_PosH` / `CT_PosV` (align XOR posOffset; relativeFrom required)
+ * - `ST_RelFromH`, `ST_RelFromV`, `ST_AlignH`, `ST_AlignV`
+ * DrawingML main: `a:xfrm` rot/flipH/flipV; `a:CT_NonVisualDrawingProps` name/descr/title
+ * Locks: `a:graphicFrameLocks/@noChangeAspect`
+ *
+ * Anchor promotion defaults mirror ink host-codec minimal Word-like anchor
+ * (distL/R 114300, relativeHeight 251658240, layoutInCell 1, allowOverlap 1,
+ * positionH column posOffset 0, positionV paragraph posOffset 0, wrapNone).
+ *
+ * @packageDocumentation
+ */
+import { Emus } from '../document/length';
+import { OpenXmlElement } from '../../core/xml/index';
+import { HorizontalAlignment as HorizontalAlignmentType, HorizontalOrigin as HorizontalOriginType, PicturePlacement as PicturePlacementType, TextWrappingStyle as TextWrappingStyleType, VerticalAlignment as VerticalAlignmentType, VerticalOrigin as VerticalOriginType } from './layout-types';
+/**
+ * @private
+ * Decoded picture host state. */
+export interface PictureHostState {
+    readonly placement: PicturePlacementType;
+    readonly wrapping: TextWrappingStyleType;
+    readonly widthEmu: Emus;
+    readonly heightEmu: Emus;
+    readonly relationshipId: string;
+    readonly name: string;
+    readonly title: string | undefined;
+    readonly description: string | undefined;
+    readonly lockAspectRatio: boolean;
+    readonly rotation: number;
+    readonly flipHorizontal: boolean;
+    readonly flipVertical: boolean;
+    readonly horizontalOrigin: HorizontalOriginType | undefined;
+    readonly verticalOrigin: VerticalOriginType | undefined;
+    readonly horizontalPosition: number | undefined;
+    readonly verticalPosition: number | undefined;
+    readonly horizontalAlignment: HorizontalAlignmentType | undefined;
+    readonly verticalAlignment: VerticalAlignmentType | undefined;
+    readonly docPrId: number;
+    /**
+     * DrawingML picture hyperlink relationship id (`a:hlinkClick/@r:id` on
+     * `wp:docPr` / `pic:cNvPr`), when present.
+     */
+    readonly hyperlinkRelationshipId: string | undefined;
+    /** Original drawing element for residual preservation on dirty rebuild. */
+    readonly preservedHost: OpenXmlElement;
+}
+/**
+ * @private
+ * Encode input for picture host serialization. */
+export interface EncodePictureHostInput {
+    readonly placement: PicturePlacementType;
+    readonly wrapping: TextWrappingStyleType;
+    readonly widthEmu: Emus;
+    readonly heightEmu: Emus;
+    readonly relationshipId: string;
+    readonly name: string;
+    readonly title: string | undefined;
+    readonly description: string | undefined;
+    readonly lockAspectRatio: boolean;
+    readonly rotation: number;
+    readonly flipHorizontal: boolean;
+    readonly flipVertical: boolean;
+    readonly horizontalOrigin: HorizontalOriginType;
+    readonly verticalOrigin: VerticalOriginType;
+    readonly horizontalPosition: number | undefined;
+    readonly verticalPosition: number | undefined;
+    readonly horizontalAlignment: HorizontalAlignmentType | undefined;
+    readonly verticalAlignment: VerticalAlignmentType | undefined;
+    readonly docPrId: number;
+    readonly preservedHost: OpenXmlElement | undefined;
+    /**
+     * When true, rebuild position/wrap from modeled fields (user mutated layout).
+     * When false and preservedHost has matching placement, reuse residual position/wrap.
+     */
+    readonly layoutDirty: boolean;
+    /**
+     * Optional external hyperlink relationship id emitted as
+     * `a:hlinkClick/@r:id` under `wp:docPr` and `pic:cNvPr`.
+     */
+    readonly hyperlinkRelationshipId: string | undefined;
+}
+/**
+ * Decode a picture `w:drawing` (inline or anchor with `a:blip` embed).
+ *
+ * @private
+ */
+export declare function decodePictureHost(drawing: OpenXmlElement): PictureHostState | undefined;
+/**
+ * Encode a modeled picture host into `w:drawing`.
+ *
+ * @private
+ */
+export declare function encodePictureHost(input: EncodePictureHostInput): OpenXmlElement;
+/**
+ * Whether wrapping requires an anchor host.
+ *
+ * @private
+ */
+export declare function wrappingRequiresAnchor(wrapping: TextWrappingStyleType): boolean;