@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

package/src/features/font-table/font-table.d.ts

@@ -0,0 +1,128 @@
+import { WordDocument } from '../document/document';
+import { FeaturePackagePart } from '../document/feature-package-part';
+import { NamespaceDeclaration, OpenXmlAttribute, OpenXmlElement } from '../../core/xml/index';
+import { FontTableFont } from './font-table-entry';
+/**
+ * @private
+ * Transitional font table relationship (ECMA-376-4 §9.2.5). */
+export declare const FONT_TABLE_RELATIONSHIP_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/fontTable";
+/**
+ * @private
+ * Strict font table relationship (ECMA-376-1 §11.3.5). */
+export declare const STRICT_FONT_TABLE_RELATIONSHIP_TYPE = "http://purl.oclc.org/ooxml/officeDocument/relationships/fontTable";
+/**
+ * @private
+ * ECMA-376-1 §11.3.5 Font Table content type. */
+export declare const FONT_TABLE_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.fontTable+xml";
+/**
+ * @private
+ */
+export declare const FONT_TABLE_PART_NAME: import("../../core/opc/part-name").PartName;
+/**
+ * In-memory Font Table part (`word/fontTable.xml`).
+ *
+ * Clean loads stay byte-preserving until the first mutation. Dirty serialize
+ * rebuilds `w:fonts` from entry models + residual children (ECMA-376-1 §11.3.5 /
+ * §17.8). Each `w:font` emits the `CT_Font` child sequence (altName through
+ * embed slots) then residual unknown children.
+ *
+ * @private
+ */
+export declare class FontTablePart implements FeaturePackagePart {
+    private bytes;
+    private dirty;
+    private readonly fontEntries;
+    private readonly rootExtrasBeforeFonts;
+    private readonly rootExtrasAfterFonts;
+    private readonly rootAttributes;
+    private readonly rootNamespaceDeclarations;
+    /**
+     * @private
+     */
+    constructor(bytes: Uint8Array | undefined, fontEntries: FontTableFont[], rootExtrasBeforeFonts: ReadonlyArray<OpenXmlElement>, rootExtrasAfterFonts: ReadonlyArray<OpenXmlElement>, rootAttributes: ReadonlyArray<OpenXmlAttribute>, rootNamespaceDeclarations: ReadonlyArray<NamespaceDeclaration>, dirty: boolean);
+    /**
+     * Declared font names from `w:font/@w:name` in document order (stored casing).
+     *
+     * @public
+     */
+    fontNames(): ReadonlyArray<string>;
+    /**
+     * Whether a font name appears in the table (case-insensitive).
+     *
+     * @public
+     */
+    hasFont(name: string): boolean;
+    /**
+     * Font table entries in document order.
+     *
+     * @public
+     */
+    fonts(): ReadonlyArray<FontTableFont>;
+    /**
+     * Entry for `name`, or `undefined` when absent. Lookup is case-insensitive;
+     * stored `@w:name` casing is unchanged.
+     *
+     * @public
+     */
+    font(name: string): FontTableFont | undefined;
+    /**
+     * Ensure a minimal `w:font/@w:name` row exists and return it.
+     * If present (case-insensitive), returns the existing entry without duplicating.
+     *
+     * @throws DocxError `content/unsupported` when `name` is empty or whitespace-only.
+     *
+     * @public
+     */
+    appendFont(name: string): FontTableFont;
+    /**
+     * Declared substitute string for `name` (`w:altName/@w:val`), or `undefined`.
+     * Case-insensitive name lookup. Does not create entries.
+     *
+     * Prefer {@link WordDocument.fontSubstitutionTable} `.get(name)` for substitution
+     * workflows (TASK-8067). This helper remains a thin catalog alias to
+     * {@link FontTableFont.alternateName}.
+     *
+     * @public
+     */
+    substituteFont(name: string): string | undefined;
+    /**
+     * @private
+     */
+    isDirty(): boolean;
+    /**
+     * @private
+     */
+    markDirty(): void;
+    /**
+     * @private
+     */
+    serialize(): Uint8Array;
+}
+/**
+ * @private
+ * Test hook */
+export declare function resetFontTableFeatureForTests(): void;
+/**
+ * @private
+ * Register the font table package-part handler. Idempotent. */
+export declare function registerFontTableFeature(): void;
+/**
+ * Font table catalog for a document (`fontTable.xml` / `CT_FontsList`).
+ *
+ * **Public dual export (TASK-8067):** Prefer {@link WordDocument.fontSubstitutionTable}
+ * for alternate-name dictionary workflows (`get`/`set`/`delete`/`clear`/iteration).
+ * Use `fontTableFor` only for the full catalog — panose, family, pitch, charset,
+ * signature, embed relationship metadata, residual unknown markup, and
+ * `appendFont` / `font` / `fonts`.
+ *
+ * When the feature is registered but no part is attached yet (for example
+ * {@link WordDocument.create} before the handler ran at load, or registration after
+ * load), attaches an empty not-dirty {@link FontTablePart} so authoring works
+ * without a prior load of `fontTable.xml`.
+ *
+ * @throws DocxError `feature/not-registered` when a non-{@link FontTablePart}
+ * value occupies the feature slot, or when the feature cannot be ensured.
+ *
+ * @private
+ */
+export declare function fontTableFor(document: WordDocument): FontTablePart;

package/src/features/font-table/font-table.js

@@ -0,0 +1,313 @@
+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 };
+        }
+    };
+};
+import { DocxError } from '../../core/errors/docx-error';
+import { elementChildren, isWml, wmlElement } from '../document/wml';
+import { partName } from '../../core/opc/part-name';
+import { featureId, registerFeature, registerFeaturePartHandler, } from '../../core/registry/index';
+import { parseXml, serializeXml, WML_TRANSITIONAL_NAMESPACE } from '../../core/xml/index';
+import { createFontTableFont, parseFontTableFont } from './font-table-entry';
+var FONT_TABLE = featureId('font-table');
+/**
+ * @private
+ * Transitional font table relationship (ECMA-376-4 §9.2.5). */
+export var FONT_TABLE_RELATIONSHIP_TYPE = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/fontTable';
+/**
+ * @private
+ * Strict font table relationship (ECMA-376-1 §11.3.5). */
+export var STRICT_FONT_TABLE_RELATIONSHIP_TYPE = 'http://purl.oclc.org/ooxml/officeDocument/relationships/fontTable';
+/**
+ * @private
+ * ECMA-376-1 §11.3.5 Font Table content type. */
+export var FONT_TABLE_CONTENT_TYPE = 'application/vnd.openxmlformats-officedocument.wordprocessingml.fontTable+xml';
+/**
+ * @private
+ */
+export var FONT_TABLE_PART_NAME = partName('/word/fontTable.xml');
+var utf8Decoder = new TextDecoder('utf-8');
+var utf8Encoder = new TextEncoder();
+/** Locale-independent lower-case key for font name lookup. */
+function fontLookupKey(name) {
+    return name.toLowerCase();
+}
+/**
+ * In-memory Font Table part (`word/fontTable.xml`).
+ *
+ * Clean loads stay byte-preserving until the first mutation. Dirty serialize
+ * rebuilds `w:fonts` from entry models + residual children (ECMA-376-1 §11.3.5 /
+ * §17.8). Each `w:font` emits the `CT_Font` child sequence (altName through
+ * embed slots) then residual unknown children.
+ *
+ * @private
+ */
+var FontTablePart = /** @class */ (function () {
+    /**
+     * @private
+     */
+    function FontTablePart(bytes, fontEntries, rootExtrasBeforeFonts, rootExtrasAfterFonts, rootAttributes, rootNamespaceDeclarations, dirty) {
+        this.bytes = bytes;
+        this.fontEntries = fontEntries;
+        this.rootExtrasBeforeFonts = __spread(rootExtrasBeforeFonts);
+        this.rootExtrasAfterFonts = __spread(rootExtrasAfterFonts);
+        this.rootAttributes = __spread(rootAttributes);
+        this.rootNamespaceDeclarations =
+            rootNamespaceDeclarations.length > 0
+                ? __spread(rootNamespaceDeclarations) : [{ prefix: 'w', namespaceUri: WML_TRANSITIONAL_NAMESPACE }];
+        this.dirty = dirty;
+    }
+    /**
+     * Declared font names from `w:font/@w:name` in document order (stored casing).
+     *
+     * @public
+     */
+    FontTablePart.prototype.fontNames = function () {
+        return this.fontEntries.map(function (entry) { return entry.name; });
+    };
+    /**
+     * Whether a font name appears in the table (case-insensitive).
+     *
+     * @public
+     */
+    FontTablePart.prototype.hasFont = function (name) {
+        return this.font(name) !== undefined;
+    };
+    /**
+     * Font table entries in document order.
+     *
+     * @public
+     */
+    FontTablePart.prototype.fonts = function () {
+        return this.fontEntries;
+    };
+    /**
+     * Entry for `name`, or `undefined` when absent. Lookup is case-insensitive;
+     * stored `@w:name` casing is unchanged.
+     *
+     * @public
+     */
+    FontTablePart.prototype.font = function (name) {
+        var key = fontLookupKey(name);
+        return this.fontEntries.find(function (entry) { return fontLookupKey(entry.name) === key; });
+    };
+    /**
+     * Ensure a minimal `w:font/@w:name` row exists and return it.
+     * If present (case-insensitive), returns the existing entry without duplicating.
+     *
+     * @throws DocxError `content/unsupported` when `name` is empty or whitespace-only.
+     *
+     * @public
+     */
+    FontTablePart.prototype.appendFont = function (name) {
+        var _this = this;
+        var trimmed = name.trim();
+        if (trimmed.length === 0) {
+            throw new DocxError('content/unsupported', 'Font name must not be empty');
+        }
+        var existing = this.font(trimmed);
+        if (existing !== undefined) {
+            return existing;
+        }
+        // Preserve caller casing (trimmed ends only).
+        var created = createFontTableFont(trimmed, function () {
+            _this.markDirty();
+        });
+        this.fontEntries.push(created);
+        this.markDirty();
+        return created;
+    };
+    /**
+     * Declared substitute string for `name` (`w:altName/@w:val`), or `undefined`.
+     * Case-insensitive name lookup. Does not create entries.
+     *
+     * Prefer {@link WordDocument.fontSubstitutionTable} `.get(name)` for substitution
+     * workflows (TASK-8067). This helper remains a thin catalog alias to
+     * {@link FontTableFont.alternateName}.
+     *
+     * @public
+     */
+    FontTablePart.prototype.substituteFont = function (name) {
+        var __ts33_0;
+        return ((__ts33_0 = this.font(name)), __ts33_0 == null ? undefined : __ts33_0.alternateName);
+    };
+    /**
+     * @private
+     */
+    FontTablePart.prototype.isDirty = function () {
+        return this.dirty;
+    };
+    /**
+     * @private
+     */
+    FontTablePart.prototype.markDirty = function () {
+        this.dirty = true;
+        this.bytes = undefined;
+    };
+    /**
+     * @private
+     */
+    FontTablePart.prototype.serialize = function () {
+        if (!this.dirty) {
+            if (this.bytes !== undefined) {
+                return this.bytes;
+            }
+            return new Uint8Array(0);
+        }
+        var children = __spread(this.rootExtrasBeforeFonts, this.fontEntries.map(function (entry) { return entry.serialize(); }), this.rootExtrasAfterFonts);
+        var root = wmlElement('fonts', {
+            namespaceDeclarations: this.rootNamespaceDeclarations,
+            attributes: this.rootAttributes,
+            children: children,
+        });
+        return utf8Encoder.encode(serializeXml(root));
+    };
+    return FontTablePart;
+}());
+export { FontTablePart };
+function parseFontTableRoot(root, markDirty) {
+    var e_1, _a;
+    var fontEntries = [];
+    var rootExtrasBeforeFonts = [];
+    var rootExtrasAfterFonts = [];
+    var sawFont = false;
+    try {
+        for (var _b = __values(elementChildren(root)), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var child = _c.value;
+            if (isWml(child, 'font')) {
+                sawFont = true;
+                var entry = parseFontTableFont(child, markDirty);
+                if (entry !== undefined) {
+                    fontEntries.push(entry);
+                }
+                continue;
+            }
+            if (sawFont) {
+                rootExtrasAfterFonts.push(child);
+            }
+            else {
+                rootExtrasBeforeFonts.push(child);
+            }
+        }
+    }
+    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 {
+        fontEntries: fontEntries,
+        rootExtrasBeforeFonts: rootExtrasBeforeFonts,
+        rootExtrasAfterFonts: rootExtrasAfterFonts,
+        rootAttributes: __spread(root.attributes),
+        rootNamespaceDeclarations: __spread(root.namespaceDeclarations),
+    };
+}
+function loadFontTablePart(part) {
+    if (part === undefined) {
+        return new FontTablePart(undefined, [], [], [], [], [], false);
+    }
+    var root = parseXml(utf8Decoder.decode(part.data));
+    if (!isWml(root, 'fonts')) {
+        return new FontTablePart(part.data, [], [], [], [], [], false);
+    }
+    // Entries close over this holder so markDirty works before/after construction.
+    var holder = { part: undefined };
+    var markDirty = function () {
+        if (holder.part !== undefined) {
+            holder.part.markDirty();
+        }
+    };
+    var parsed = parseFontTableRoot(root, markDirty);
+    var result = new FontTablePart(part.data, parsed.fontEntries, parsed.rootExtrasBeforeFonts, parsed.rootExtrasAfterFonts, parsed.rootAttributes, parsed.rootNamespaceDeclarations, false);
+    holder.part = result;
+    return result;
+}
+var fontTableRegistered = false;
+/**
+ * @private
+ * Test hook */
+export function resetFontTableFeatureForTests() {
+    fontTableRegistered = false;
+}
+/**
+ * @private
+ * Register the font table package-part handler. Idempotent. */
+export function registerFontTableFeature() {
+    if (fontTableRegistered) {
+        return;
+    }
+    fontTableRegistered = true;
+    registerFeature({ id: FONT_TABLE });
+    registerFeaturePartHandler({
+        featureId: FONT_TABLE,
+        relationshipTypes: [FONT_TABLE_RELATIONSHIP_TYPE, STRICT_FONT_TABLE_RELATIONSHIP_TYPE],
+        defaultRelativeTarget: 'fontTable.xml',
+        partName: FONT_TABLE_PART_NAME,
+        contentType: FONT_TABLE_CONTENT_TYPE,
+        loadPart: function (part, ctx) {
+            void ctx;
+            return loadFontTablePart(part);
+        },
+    });
+}
+/**
+ * Font table catalog for a document (`fontTable.xml` / `CT_FontsList`).
+ *
+ * **Public dual export (TASK-8067):** Prefer {@link WordDocument.fontSubstitutionTable}
+ * for alternate-name dictionary workflows (`get`/`set`/`delete`/`clear`/iteration).
+ * Use `fontTableFor` only for the full catalog — panose, family, pitch, charset,
+ * signature, embed relationship metadata, residual unknown markup, and
+ * `appendFont` / `font` / `fonts`.
+ *
+ * When the feature is registered but no part is attached yet (for example
+ * {@link WordDocument.create} before the handler ran at load, or registration after
+ * load), attaches an empty not-dirty {@link FontTablePart} so authoring works
+ * without a prior load of `fontTable.xml`.
+ *
+ * @throws DocxError `feature/not-registered` when a non-{@link FontTablePart}
+ * value occupies the feature slot, or when the feature cannot be ensured.
+ *
+ * @private
+ */
+export function fontTableFor(document) {
+    registerFontTableFeature();
+    var existing = document.featurePart(FONT_TABLE);
+    if (existing instanceof FontTablePart) {
+        return existing;
+    }
+    if (existing !== undefined) {
+        throw new DocxError('feature/not-registered', 'Font table part was not loaded; call registerFontTableFeature() or registerStylesFeature() before WordDocument.open');
+    }
+    // Absent only: empty catalog (not dirty). First mutation dirties and save emits the part.
+    var empty = new FontTablePart(undefined, [], [], [], [], [], false);
+    document.setFeaturePart(FONT_TABLE, empty);
+    return empty;
+}

package/src/features/font-table/index.d.ts

@@ -0,0 +1,27 @@
+export * from './font-substitution-table';
+export * from './font-table-entry';
+export * from './font-table';
+/**
+ * Font Table feature (`word/fontTable.xml`).
+ *
+ * Owns the declarative font catalog (`CT_FontsList` / `CT_Font`), including
+ * `w:altName` substitution and typed metadata (`panose1`, `charset`, `family`,
+ * `notTrueType`, `pitch`, `sig`, embed relationship slots). Binary ODTTF
+ * authoring remains out of scope (ECMA-376-1 §11.3.5, §17.8).
+ *
+ * Public substitution entry: {@link WordDocument.fontSubstitutionTable}.
+ *
+ * @packageDocumentation
+ */
+import { WordDocument } from '../document/document';
+import { FontSubstitutionTable } from './font-substitution-table';
+/**
+ * WordDocument-owned font substitution dictionary for `document`.
+ *
+ * Same object identity on every access for a given document. Backed by the
+ * document’s {@link FontTablePart} (ensured on first access).
+ *
+ * @private
+ * Prefer {@link WordDocument.fontSubstitutionTable}.
+ */
+export declare function fontSubstitutionTableFor(document: WordDocument): FontSubstitutionTable;

package/src/features/font-table/index.js

@@ -0,0 +1,48 @@
+export * from './font-substitution-table';
+export * from './font-table-entry';
+export * from './font-table';
+/**
+ * Font Table feature (`word/fontTable.xml`).
+ *
+ * Owns the declarative font catalog (`CT_FontsList` / `CT_Font`), including
+ * `w:altName` substitution and typed metadata (`panose1`, `charset`, `family`,
+ * `notTrueType`, `pitch`, `sig`, embed relationship slots). Binary ODTTF
+ * authoring remains out of scope (ECMA-376-1 §11.3.5, §17.8).
+ *
+ * Public substitution entry: {@link WordDocument.fontSubstitutionTable}.
+ *
+ * @packageDocumentation
+ */
+import { WordDocument } from '../document/document';
+import { FontSubstitutionTableImpl } from './font-substitution-table';
+import { fontTableFor, registerFontTableFeature } from './font-table';
+/** Stable `WordDocument` → substitution table identity (TASK-8066). */
+var substitutionTables = new WeakMap();
+/**
+ * WordDocument-owned font substitution dictionary for `document`.
+ *
+ * Same object identity on every access for a given document. Backed by the
+ * document’s {@link FontTablePart} (ensured on first access).
+ *
+ * @private
+ * Prefer {@link WordDocument.fontSubstitutionTable}.
+ */
+export function fontSubstitutionTableFor(document) {
+    registerFontTableFeature();
+    var cached = substitutionTables.get(document);
+    if (cached !== undefined) {
+        return cached;
+    }
+    var part = fontTableFor(document);
+    var table = new FontSubstitutionTableImpl(part);
+    substitutionTables.set(document, table);
+    return table;
+}
+Object.defineProperty(WordDocument.prototype, 'fontSubstitutionTable', {
+    configurable: true,
+    enumerable: false,
+    get: function () {
+        return fontSubstitutionTableFor(this);
+    },
+});
+registerFontTableFeature();

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

@@ -0,0 +1,97 @@
+import { WordDocument } from '../document/document';
+import { FeaturePackagePart } from '../document/feature-package-part';
+/**
+ * @private
+ * Transitional glossary document relationship (ECMA-376-4 §9.2.8). */
+export declare const GLOSSARY_DOCUMENT_RELATIONSHIP_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/glossaryDocument";
+/**
+ * @private
+ * Strict glossary document relationship (ECMA-376-1 §11.3.8). */
+export declare const STRICT_GLOSSARY_DOCUMENT_RELATIONSHIP_TYPE = "http://purl.oclc.org/ooxml/officeDocument/relationships/glossaryDocument";
+/**
+ * @private
+ * ECMA-376-1 §11.3.8 Glossary WordDocument content type. */
+export declare const GLOSSARY_DOCUMENT_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.document.glossary+xml";
+/**
+ * @private
+ */
+export declare const GLOSSARY_DOCUMENT_PART_NAME: import("../../core/opc/part-name").PartName;
+interface DocPartSummary {
+    readonly name: string;
+    readonly category: string | undefined;
+    readonly gallery: string | undefined;
+}
+interface GlossaryMetadata {
+    readonly docParts: ReadonlyArray<DocPartSummary>;
+}
+/**
+ * Preserve-only Glossary WordDocument part (`glossary/document.xml`).
+ * Building-block body content is opaque; name/category/gallery metadata is
+ * read-only catalog access. No building-block editor or mutation API is provided.
+ *
+ * @private
+ */
+export declare class GlossaryDocumentPart implements FeaturePackagePart {
+    private readonly bytes;
+    private readonly metadata;
+    private readonly dirty;
+    /**
+     * @private
+     */
+    constructor(bytes: Uint8Array | undefined, metadata: GlossaryMetadata, dirty: boolean);
+    /**
+     * Whether the glossary part was present in the package.
+     *
+     * @public
+     */
+    present(): boolean;
+    /**
+     * Count of `w:docParts/w:docPart` entries with a readable `w:name`.
+     *
+     * @public
+     */
+    docPartCount(): number;
+    /**
+     * `w:docPartPr/w:name/@w:val` values in document order.
+     *
+     * @public
+     */
+    docPartNames(): ReadonlyArray<string>;
+    /**
+     * `w:category/w:name/@w:val` for a doc part name, or `undefined` when absent.
+     *
+     * @public
+     */
+    docPartCategory(name: string): string | undefined;
+    /**
+     * `w:category/w:gallery/@w:val` for a doc part name, or `undefined` when absent.
+     *
+     * @public
+     */
+    docPartGallery(name: string): string | undefined;
+    /**
+     * @private
+     */
+    isDirty(): boolean;
+    /**
+     * @private
+     */
+    serialize(): Uint8Array;
+}
+/**
+ * @private
+ * Test hook */
+export declare function resetGlossaryFeatureForTests(): void;
+/**
+ * @private
+ * Register the glossary document package-part handler. Idempotent. */
+export declare function registerGlossaryFeature(): void;
+/**
+ * Glossary document catalog for a package. Requires {@link registerGlossaryFeature}.
+ *
+ * @throws DocxError `UNKNOWN_FEATURE` when the module was not registered before load.
+ *
+ * @private
+ */
+export declare function glossaryFor(document: WordDocument): GlossaryDocumentPart;
+export {};