@syncfusion/ej2-docx 0.0.0-stage → 35.1.39

package/src/features/mail-merge/index.d.ts

@@ -0,0 +1,113 @@
+import { FeatureMultiPackagePart } from '../document/feature-multi-package-part';
+import { OpcPackage } from '../../core/opc/package';
+import { PartName } from '../../core/opc/part-name';
+/**
+ * @private Word recipientData relationship (`[MS-OI29500]` §2.1.378). */
+export declare const RECIPIENT_DATA_RELATIONSHIP_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/recipientData";
+/**
+ * @private Strict Mail Merge Recipient Data relationship (ECMA-376-1 §17.14.28). */
+export declare const STRICT_RECIPIENT_DATA_RELATIONSHIP_TYPE = "http://purl.oclc.org/ooxml/officeDocument/relationships/mailMergeRecipientData";
+/**
+ * @private Transitional mail merge data source (ECMA-376-4 §9.6). */
+export declare const MAIL_MERGE_SOURCE_RELATIONSHIP_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/mailMergeSource";
+/**
+ * @private Strict mail merge data source (ECMA-376-1 §11.7). */
+export declare const STRICT_MAIL_MERGE_SOURCE_RELATIONSHIP_TYPE = "http://purl.oclc.org/ooxml/officeDocument/relationships/mailMergeSource";
+/**
+ * @private Transitional mail merge header source (ECMA-376-4 §9.7). */
+export declare const MAIL_MERGE_HEADER_SOURCE_RELATIONSHIP_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/mailMergeHeaderSource";
+/**
+ * @private Strict mail merge header source (ECMA-376-1 §11.8). */
+export declare const STRICT_MAIL_MERGE_HEADER_SOURCE_RELATIONSHIP_TYPE = "http://purl.oclc.org/ooxml/officeDocument/relationships/mailMergeHeaderSource";
+/**
+ * @private Mail Merge Recipient Data content type (ECMA-376-1 / `[MS-OI29500]`). */
+export declare const RECIPIENT_DATA_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.mailMergeRecipientData+xml";
+/** `ST_MailMergeDocType` (Transitional `wml.xsd`).
+ * @private
+ */
+export declare type MailMergeDocumentType = 'catalog' | 'envelopes' | 'mailingLabels' | 'formLetters' | 'email' | 'fax';
+/** `ST_MailMergeDest` (Transitional `wml.xsd`).
+ * @private
+ */
+export declare type MailMergeDestination = 'newDocument' | 'printer' | 'email' | 'fax';
+interface MailMergeMetadata {
+    readonly present: boolean;
+    readonly mainDocumentType: MailMergeDocumentType | undefined;
+    readonly dataType: string | undefined;
+    readonly destination: MailMergeDestination | undefined;
+}
+/**
+ * Preserve-only mail merge metadata catalog.
+ * Recipient data and data-source relationships are never fetched, executed, or
+ * mutated; connection strings and queries remain opaque.
+ * @private
+ */
+export declare class MailMergeCatalog implements FeatureMultiPackagePart {
+    private readonly metadata;
+    private readonly recipientsBytes;
+    private readonly recipientCount;
+    private readonly sourceTargets;
+    /**
+     * @private
+     */
+    constructor(metadata: MailMergeMetadata, recipientsBytes: Uint8Array | undefined, recipientCount: number, sourceTargets: ReadonlyArray<string>);
+    /**
+     * Whether `w:mailMerge` is present on the WordDocument Settings part.
+     *
+     * @private
+     */
+    present(): boolean;
+    /**
+     * `w:mainDocumentType/@w:val`, or `undefined` when absent or unrecognized.
+     *
+     * @private
+     */
+    mainDocumentType(): MailMergeDocumentType | undefined;
+    /**
+     * `w:dataType/@w:val`, or `undefined` when absent.
+     *
+     * @private
+     */
+    dataType(): string | undefined;
+    /**
+     * `w:destination/@w:val`, or `undefined` when absent or unrecognized.
+     *
+     * @private
+     */
+    destination(): MailMergeDestination | undefined;
+    /**
+     * Whether a Mail Merge Recipient Data part is related from settings.
+     *
+     * @private
+     */
+    hasRecipientsPart(): boolean;
+    /**
+     * Number of `recipientData` children in the recipients part.
+     *
+     * @private
+     */
+    recipientRecordCount(): number;
+    /**
+     * External mail-merge data-source relationship targets. Never fetched.
+     *
+     * @private
+     */
+    dataSourceTargets(): ReadonlyArray<string>;
+    /**
+     * @private
+     */
+    isDirty(): boolean;
+    /**
+     * @private
+     */
+    applyToPackage(pkg: OpcPackage, mainPartName: PartName): OpcPackage;
+}
+/**
+ * @private
+ * Test hook */
+export declare function resetMailMergeFeatureForTests(): void;
+/**
+ * @private
+ * Register the mail-merge multi-part handler. Idempotent. */
+export declare function registerMailMergeFeature(): void;
+export {};

package/src/features/mail-merge/index.js

@@ -0,0 +1,315 @@
+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 };
+        }
+    };
+};
+import { DocxError } from '../../core/errors/docx-error';
+import { WordDocument } from '../document/document';
+import { elementChildren, isWml } from '../document/wml';
+import { partByName, relationshipsForPart } from '../../core/opc/package';
+import { resolveInternalTarget } from '../../core/opc/part-name';
+import { TargetMode } from '../../core/opc/relationships';
+import { featureId, registerFeature, registerFeatureMultiPartHandler, } from '../../core/registry/index';
+import { parseXml, WML_TRANSITIONAL_NAMESPACE } from '../../core/xml/index';
+var MAIL_MERGE = featureId('mail-merge');
+var utf8Decoder = new TextDecoder('utf-8');
+/** Transitional settings relationship (ECMA-376-4 §9.2.3). */
+var SETTINGS_RELATIONSHIP_TYPE = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings';
+/** Strict settings relationship (ECMA-376-1 §11.3.3). */
+var STRICT_SETTINGS_RELATIONSHIP_TYPE = 'http://purl.oclc.org/ooxml/officeDocument/relationships/settings';
+/**
+ * @private Word recipientData relationship (`[MS-OI29500]` §2.1.378). */
+export var RECIPIENT_DATA_RELATIONSHIP_TYPE = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/recipientData';
+/**
+ * @private Strict Mail Merge Recipient Data relationship (ECMA-376-1 §17.14.28). */
+export var STRICT_RECIPIENT_DATA_RELATIONSHIP_TYPE = 'http://purl.oclc.org/ooxml/officeDocument/relationships/mailMergeRecipientData';
+/**
+ * @private Transitional mail merge data source (ECMA-376-4 §9.6). */
+export var MAIL_MERGE_SOURCE_RELATIONSHIP_TYPE = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/mailMergeSource';
+/**
+ * @private Strict mail merge data source (ECMA-376-1 §11.7). */
+export var STRICT_MAIL_MERGE_SOURCE_RELATIONSHIP_TYPE = 'http://purl.oclc.org/ooxml/officeDocument/relationships/mailMergeSource';
+/**
+ * @private Transitional mail merge header source (ECMA-376-4 §9.7). */
+export var MAIL_MERGE_HEADER_SOURCE_RELATIONSHIP_TYPE = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/mailMergeHeaderSource';
+/**
+ * @private Strict mail merge header source (ECMA-376-1 §11.8). */
+export var STRICT_MAIL_MERGE_HEADER_SOURCE_RELATIONSHIP_TYPE = 'http://purl.oclc.org/ooxml/officeDocument/relationships/mailMergeHeaderSource';
+/**
+ * @private Mail Merge Recipient Data content type (ECMA-376-1 / `[MS-OI29500]`). */
+export var RECIPIENT_DATA_CONTENT_TYPE = 'application/vnd.openxmlformats-officedocument.wordprocessingml.mailMergeRecipientData+xml';
+var SETTINGS_RELATIONSHIP_TYPES = [
+    SETTINGS_RELATIONSHIP_TYPE,
+    STRICT_SETTINGS_RELATIONSHIP_TYPE,
+];
+var RECIPIENT_DATA_RELATIONSHIP_TYPES = [
+    RECIPIENT_DATA_RELATIONSHIP_TYPE,
+    STRICT_RECIPIENT_DATA_RELATIONSHIP_TYPE,
+];
+var DATA_SOURCE_RELATIONSHIP_TYPES = [
+    MAIL_MERGE_SOURCE_RELATIONSHIP_TYPE,
+    STRICT_MAIL_MERGE_SOURCE_RELATIONSHIP_TYPE,
+    MAIL_MERGE_HEADER_SOURCE_RELATIONSHIP_TYPE,
+    STRICT_MAIL_MERGE_HEADER_SOURCE_RELATIONSHIP_TYPE,
+];
+function wmlAttribute(element, localName) {
+    var found = element.attributes.find(function (attribute) { return attribute.localName === localName &&
+        (attribute.namespaceUri === WML_TRANSITIONAL_NAMESPACE || attribute.namespaceUri === ''); });
+    return found == null ? undefined : found.value;
+}
+function parseDocumentType(raw) {
+    switch (raw) {
+        case 'catalog':
+        case 'envelopes':
+        case 'mailingLabels':
+        case 'formLetters':
+        case 'email':
+        case 'fax':
+            return raw;
+        default:
+            return undefined;
+    }
+}
+function parseDestination(raw) {
+    switch (raw) {
+        case 'newDocument':
+        case 'printer':
+        case 'email':
+        case 'fax':
+            return raw;
+        default:
+            return undefined;
+    }
+}
+function findWmlChild(children, localName) {
+    return children.find(function (child) { return isWml(child, localName); });
+}
+function parseMailMergeMetadata(settingsRoot) {
+    if (settingsRoot === undefined || !isWml(settingsRoot, 'settings')) {
+        return { present: false, mainDocumentType: undefined, dataType: undefined, destination: undefined };
+    }
+    var mailMerge = findWmlChild(elementChildren(settingsRoot), 'mailMerge');
+    if (mailMerge === undefined) {
+        return { present: false, mainDocumentType: undefined, dataType: undefined, destination: undefined };
+    }
+    var children = elementChildren(mailMerge);
+    var typeElement = findWmlChild(children, 'mainDocumentType');
+    var dataTypeElement = findWmlChild(children, 'dataType');
+    var destinationElement = findWmlChild(children, 'destination');
+    return {
+        present: true,
+        mainDocumentType: parseDocumentType(typeElement === undefined ? undefined : wmlAttribute(typeElement, 'val')),
+        dataType: dataTypeElement === undefined ? undefined : wmlAttribute(dataTypeElement, 'val'),
+        destination: parseDestination(destinationElement === undefined ? undefined : wmlAttribute(destinationElement, 'val')),
+    };
+}
+function countRecipientRecords(bytes) {
+    var e_1, _a;
+    if (bytes === undefined) {
+        return 0;
+    }
+    var root = parseXml(utf8Decoder.decode(bytes));
+    if (root.localName !== 'recipients') {
+        return 0;
+    }
+    var count = 0;
+    try {
+        for (var _b = __values(elementChildren(root)), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var child = _c.value;
+            if (child.localName === 'recipientData') {
+                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;
+}
+function firstRelatedPart(pkg, source, relationshipTypes) {
+    var e_2, _a;
+    try {
+        for (var _b = __values(relationshipsForPart(pkg, source).items), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var rel = _c.value;
+            if (relationshipTypes.indexOf(rel.type) === -1 || rel.targetMode === TargetMode.External) {
+                continue;
+            }
+            var target = resolveInternalTarget(rel.target, source);
+            var part = partByName(pkg, target);
+            if (part !== undefined) {
+                return { name: part.name, data: part.data };
+            }
+        }
+    }
+    catch (e_2_1) { e_2 = { error: e_2_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_2) throw e_2.error; }
+    }
+    return undefined;
+}
+function collectExternalTargets(pkg, source, relationshipTypes) {
+    var e_3, _a;
+    var targets = [];
+    try {
+        for (var _b = __values(relationshipsForPart(pkg, source).items), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var rel = _c.value;
+            if (relationshipTypes.indexOf(rel.type) === -1 || rel.targetMode !== TargetMode.External) {
+                continue;
+            }
+            targets.push(rel.target);
+        }
+    }
+    catch (e_3_1) { e_3 = { error: e_3_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_3) throw e_3.error; }
+    }
+    return targets;
+}
+/**
+ * Preserve-only mail merge metadata catalog.
+ * Recipient data and data-source relationships are never fetched, executed, or
+ * mutated; connection strings and queries remain opaque.
+ * @private
+ */
+var MailMergeCatalog = /** @class */ (function () {
+    /**
+     * @private
+     */
+    function MailMergeCatalog(metadata, recipientsBytes, recipientCount, sourceTargets) {
+        this.metadata = metadata;
+        this.recipientsBytes = recipientsBytes;
+        this.recipientCount = recipientCount;
+        this.sourceTargets = sourceTargets;
+    }
+    /**
+     * Whether `w:mailMerge` is present on the WordDocument Settings part.
+     *
+     * @private
+     */
+    MailMergeCatalog.prototype.present = function () {
+        return this.metadata.present;
+    };
+    /**
+     * `w:mainDocumentType/@w:val`, or `undefined` when absent or unrecognized.
+     *
+     * @private
+     */
+    MailMergeCatalog.prototype.mainDocumentType = function () {
+        return this.metadata.mainDocumentType;
+    };
+    /**
+     * `w:dataType/@w:val`, or `undefined` when absent.
+     *
+     * @private
+     */
+    MailMergeCatalog.prototype.dataType = function () {
+        return this.metadata.dataType;
+    };
+    /**
+     * `w:destination/@w:val`, or `undefined` when absent or unrecognized.
+     *
+     * @private
+     */
+    MailMergeCatalog.prototype.destination = function () {
+        return this.metadata.destination;
+    };
+    /**
+     * Whether a Mail Merge Recipient Data part is related from settings.
+     *
+     * @private
+     */
+    MailMergeCatalog.prototype.hasRecipientsPart = function () {
+        return this.recipientsBytes !== undefined;
+    };
+    /**
+     * Number of `recipientData` children in the recipients part.
+     *
+     * @private
+     */
+    MailMergeCatalog.prototype.recipientRecordCount = function () {
+        return this.recipientCount;
+    };
+    /**
+     * External mail-merge data-source relationship targets. Never fetched.
+     *
+     * @private
+     */
+    MailMergeCatalog.prototype.dataSourceTargets = function () {
+        return this.sourceTargets;
+    };
+    /**
+     * @private
+     */
+    MailMergeCatalog.prototype.isDirty = function () {
+        return false;
+    };
+    /**
+     * @private
+     */
+    MailMergeCatalog.prototype.applyToPackage = function (pkg, mainPartName) {
+        void mainPartName;
+        return pkg;
+    };
+    return MailMergeCatalog;
+}());
+export { MailMergeCatalog };
+function loadMailMerge(pkg, mainPartName) {
+    var settingsPart = firstRelatedPart(pkg, mainPartName, SETTINGS_RELATIONSHIP_TYPES);
+    if (settingsPart === undefined) {
+        return new MailMergeCatalog({ present: false, mainDocumentType: undefined, dataType: undefined, destination: undefined }, undefined, 0, []);
+    }
+    var settingsRoot = parseXml(utf8Decoder.decode(settingsPart.data));
+    var metadata = parseMailMergeMetadata(settingsRoot);
+    var recipients = firstRelatedPart(pkg, settingsPart.name, RECIPIENT_DATA_RELATIONSHIP_TYPES);
+    var sourceTargets = collectExternalTargets(pkg, settingsPart.name, DATA_SOURCE_RELATIONSHIP_TYPES);
+    return new MailMergeCatalog(metadata, recipients == null ? undefined : recipients.data, countRecipientRecords(recipients == null ? undefined : recipients.data), sourceTargets);
+}
+var registered = false;
+/**
+ * @private
+ * Test hook */
+export function resetMailMergeFeatureForTests() {
+    registered = false;
+}
+/**
+ * @private
+ * Register the mail-merge multi-part handler. Idempotent. */
+export function registerMailMergeFeature() {
+    if (registered) {
+        return;
+    }
+    registered = true;
+    registerFeature({ id: MAIL_MERGE });
+    registerFeatureMultiPartHandler({
+        featureId: MAIL_MERGE,
+        relationshipTypes: RECIPIENT_DATA_RELATIONSHIP_TYPES,
+        loadParts: function (pkg, ctx) {
+            return loadMailMerge(pkg, ctx.mainPartName);
+        },
+    });
+}
+Object.defineProperty(WordDocument.prototype, 'mailMerge', {
+    get: function () {
+        var part = this.featurePart(MAIL_MERGE);
+        if (part === undefined || !(part instanceof MailMergeCatalog)) {
+            throw new DocxError('feature/not-registered', 'Mail merge catalog was not loaded; call registerMailMergeFeature() before WordDocument.open');
+        }
+        return part;
+    },
+});
+registerMailMergeFeature();