@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

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

@@ -0,0 +1,75 @@
+import { FontTablePart } from './font-table';
+/**
+ * Dictionary of primary → alternate font names (`w:font/@w:name` → `w:altName/@w:val`).
+ *
+ * Facade over {@link FontTablePart} / {@link FontTableFont.alternateName} — not a
+ * separate string store. Entries exist only for fonts with a modeled non-empty
+ * alternate (ECMA-376-1 §17.8.3.1).
+ *
+ * **Preferred public entry:** {@link WordDocument.fontSubstitutionTable}. Prefer this
+ * over {@link fontTableFor} for substitution-only workflows (TASK-8067). Use
+ * `fontTableFor` for full `CT_Font` catalog metadata (panose, embeds, residual).
+ *
+ * Lookup keys are case-insensitive (locale-independent lower-case), matching
+ * {@link FontTablePart.font}. Stored primary casing is preserved on alternate-only
+ * updates; new rows keep the trimmed caller primary casing.
+ *
+ * @private
+ */
+export interface FontSubstitutionTable extends Iterable<[string, string]> {
+    /** Number of fonts that currently declare a non-empty alternate name. */
+    readonly size: number;
+    /**
+     * Upsert a substitution. Creates a minimal `w:font` row when the primary is absent.
+     *
+     * @returns `this` for chaining.
+     * @throws DocxError `content/unsupported` when either name is null, undefined,
+     * empty, or whitespace-only after trim.
+     */
+    set(primaryFont: string, alternateFont: string): this;
+    /** Alternate for `primaryFont`, or `undefined` when absent / no `w:altName`. */
+    get(primaryFont: string): string | undefined;
+    /** Whether a modeled non-empty alternate exists for `primaryFont`. */
+    has(primaryFont: string): boolean;
+    /**
+     * Clear alternate on the matching font row only. Keeps `w:font` and other metadata.
+     *
+     * @returns `true` when an alternate was removed; `false` when nothing changed.
+     */
+    delete(primaryFont: string): boolean;
+    /**
+     * Clear alternate on every font row. Keeps all rows and non-altName metadata.
+     */
+    clear(): void;
+    entries(): IterableIterator<[string, string]>;
+    keys(): IterableIterator<string>;
+    values(): IterableIterator<string>;
+    [Symbol.iterator](): IterableIterator<[string, string]>;
+}
+/**
+ * {@link FontSubstitutionTable} backed by a live {@link FontTablePart}.
+ *
+ * @private
+ * Constructed by the font-table feature host (`WordDocument.fontSubstitutionTable`).
+ */
+export declare class FontSubstitutionTableImpl implements FontSubstitutionTable {
+    private readonly part;
+    /**
+     * @private
+     */
+    constructor(part: FontTablePart);
+    /**
+     * @private
+   * Live part this facade projects (same instance as {@link fontTableFor}). */
+    boundPart(): FontTablePart;
+    readonly size: number;
+    set(primaryFont: string, alternateFont: string): this;
+    get(primaryFont: string): string | undefined;
+    has(primaryFont: string): boolean;
+    delete(primaryFont: string): boolean;
+    clear(): void;
+    entries(): IterableIterator<[string, string]>;
+    keys(): IterableIterator<string>;
+    values(): IterableIterator<string>;
+    [Symbol.iterator](): IterableIterator<[string, string]>;
+}

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

@@ -0,0 +1,257 @@
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (_) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+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;
+};
+import { DocxError } from '../../core/errors/docx-error';
+/**
+ * Runtime validation for public `set` boundaries (TS types are `string`).
+ */
+function requireTrimmedFontName(value, role) {
+    if (value === null || value === undefined) {
+        throw new DocxError('content/unsupported', role + " must not be empty");
+    }
+    var trimmed = String(value).trim();
+    if (trimmed.length === 0) {
+        throw new DocxError('content/unsupported', role + " must not be empty");
+    }
+    return trimmed;
+}
+function substitutionPairs(part) {
+    var e_1, _a;
+    var pairs = [];
+    try {
+        for (var _b = __values(part.fonts()), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var font = _c.value;
+            var alternate = font.alternateName;
+            if (alternate !== undefined && alternate.trim().length > 0) {
+                pairs.push([font.name, alternate]);
+            }
+        }
+    }
+    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 pairs;
+}
+/**
+ * {@link FontSubstitutionTable} backed by a live {@link FontTablePart}.
+ *
+ * @private
+ * Constructed by the font-table feature host (`WordDocument.fontSubstitutionTable`).
+ */
+var FontSubstitutionTableImpl = /** @class */ (function () {
+    /**
+     * @private
+     */
+    function FontSubstitutionTableImpl(part) {
+        this.part = part;
+    }
+    /**
+     * @private
+   * Live part this facade projects (same instance as {@link fontTableFor}). */
+    FontSubstitutionTableImpl.prototype.boundPart = function () {
+        return this.part;
+    };
+    Object.defineProperty(FontSubstitutionTableImpl.prototype, "size", {
+        get: function () {
+            return substitutionPairs(this.part).length;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    FontSubstitutionTableImpl.prototype.set = function (primaryFont, alternateFont) {
+        var primary = requireTrimmedFontName(primaryFont, 'Font name');
+        var alternate = requireTrimmedFontName(alternateFont, 'Alternate font name');
+        var entry = this.part.appendFont(primary);
+        entry.alternateName = alternate;
+        return this;
+    };
+    FontSubstitutionTableImpl.prototype.get = function (primaryFont) {
+        var __ts33_0;
+        if (primaryFont === null || primaryFont === undefined) {
+            return undefined;
+        }
+        var key = String(primaryFont).trim();
+        if (key.length === 0) {
+            return undefined;
+        }
+        var alternate = ((__ts33_0 = this.part.font(key)), __ts33_0 == null ? undefined : __ts33_0.alternateName);
+        if (alternate === undefined || alternate.trim().length === 0) {
+            return undefined;
+        }
+        return alternate;
+    };
+    FontSubstitutionTableImpl.prototype.has = function (primaryFont) {
+        return this.get(primaryFont) !== undefined;
+    };
+    FontSubstitutionTableImpl.prototype.delete = function (primaryFont) {
+        if (primaryFont === null || primaryFont === undefined) {
+            return false;
+        }
+        var key = String(primaryFont).trim();
+        if (key.length === 0) {
+            return false;
+        }
+        var entry = this.part.font(key);
+        if (entry === undefined) {
+            return false;
+        }
+        if (entry.alternateName === undefined || entry.alternateName.trim().length === 0) {
+            return false;
+        }
+        entry.alternateName = undefined;
+        return true;
+    };
+    FontSubstitutionTableImpl.prototype.clear = function () {
+        var e_2, _a;
+        try {
+            for (var _b = __values(this.part.fonts()), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var font = _c.value;
+                if (font.alternateName !== undefined) {
+                    font.alternateName = undefined;
+                }
+            }
+        }
+        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; }
+        }
+    };
+    FontSubstitutionTableImpl.prototype.entries = function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [5 /*yield**/, __values(substitutionPairs(this.part))];
+                case 1:
+                    _a.sent();
+                    return [2 /*return*/];
+            }
+        });
+    };
+    FontSubstitutionTableImpl.prototype.keys = function () {
+        var e_3, _a, _b, _c, _d, primary, e_3_1;
+        return __generator(this, function (_e) {
+            switch (_e.label) {
+                case 0:
+                    _e.trys.push([0, 5, 6, 7]);
+                    _b = __values(substitutionPairs(this.part)), _c = _b.next();
+                    _e.label = 1;
+                case 1:
+                    if (!!_c.done) return [3 /*break*/, 4];
+                    _d = __read(_c.value, 1), primary = _d[0];
+                    return [4 /*yield*/, primary];
+                case 2:
+                    _e.sent();
+                    _e.label = 3;
+                case 3:
+                    _c = _b.next();
+                    return [3 /*break*/, 1];
+                case 4: return [3 /*break*/, 7];
+                case 5:
+                    e_3_1 = _e.sent();
+                    e_3 = { error: e_3_1 };
+                    return [3 /*break*/, 7];
+                case 6:
+                    try {
+                        if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+                    }
+                    finally { if (e_3) throw e_3.error; }
+                    return [7 /*endfinally*/];
+                case 7: return [2 /*return*/];
+            }
+        });
+    };
+    FontSubstitutionTableImpl.prototype.values = function () {
+        var e_4, _a, _b, _c, _d, alternate, e_4_1;
+        return __generator(this, function (_e) {
+            switch (_e.label) {
+                case 0:
+                    _e.trys.push([0, 5, 6, 7]);
+                    _b = __values(substitutionPairs(this.part)), _c = _b.next();
+                    _e.label = 1;
+                case 1:
+                    if (!!_c.done) return [3 /*break*/, 4];
+                    _d = __read(_c.value, 2), alternate = _d[1];
+                    return [4 /*yield*/, alternate];
+                case 2:
+                    _e.sent();
+                    _e.label = 3;
+                case 3:
+                    _c = _b.next();
+                    return [3 /*break*/, 1];
+                case 4: return [3 /*break*/, 7];
+                case 5:
+                    e_4_1 = _e.sent();
+                    e_4 = { error: e_4_1 };
+                    return [3 /*break*/, 7];
+                case 6:
+                    try {
+                        if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+                    }
+                    finally { if (e_4) throw e_4.error; }
+                    return [7 /*endfinally*/];
+                case 7: return [2 /*return*/];
+            }
+        });
+    };
+    FontSubstitutionTableImpl.prototype[Symbol.iterator] = function () {
+        return this.entries();
+    };
+    return FontSubstitutionTableImpl;
+}());
+export { FontSubstitutionTableImpl };

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

@@ -0,0 +1,255 @@
+import { NamespaceDeclaration, OpenXmlAttribute, OpenXmlChild, OpenXmlElement } from '../../core/xml/index';
+/**
+ * Font family values for `w:family/@w:val` (`ST_FontFamily`, Transitional `wml.xsd`).
+ *
+ * @private
+ */
+export declare const FontFamily: {
+    Decorative: string;
+    Modern: string;
+    Roman: string;
+    Script: string;
+    Swiss: string;
+    Auto: string;
+};
+/**
+ * @private
+ */
+export declare type FontFamily = (typeof FontFamily)[keyof typeof FontFamily];
+/**
+ * Pitch values for `w:pitch/@w:val` (`ST_Pitch`, Transitional `wml.xsd`).
+ *
+ * @private
+ */
+export declare const FontPitch: {
+    Fixed: string;
+    Variable: string;
+    Default: string;
+};
+/**
+ * @private
+ */
+export declare type FontPitch = (typeof FontPitch)[keyof typeof FontPitch];
+/**
+ * Embedded font face slot (`w:embedRegular` / `Bold` / `Italic` / `BoldItalic`).
+ *
+ * @private
+ */
+export declare const FontEmbedSlot: {
+    Regular: string;
+    Bold: string;
+    Italic: string;
+    BoldItalic: string;
+};
+/**
+ * @private
+ */
+export declare type FontEmbedSlot = (typeof FontEmbedSlot)[keyof typeof FontEmbedSlot];
+/**
+ * Unicode / code-page bitmasks from `w:sig` (`CT_FontSig`).
+ * Values are stored hex strings (`ST_UcharHexNumber` / long-hex attributes).
+ *
+ * Required attributes per Transitional `wml.xsd`: `usb0`–`usb3`, `csb0`, `csb1`.
+ *
+ * @private
+ */
+export interface FontSignature {
+    readonly usb0: string;
+    readonly usb1: string;
+    readonly usb2: string;
+    readonly usb3: string;
+    readonly csb0: string;
+    readonly csb1: string;
+}
+/**
+ * One embedded font relationship reference on a font row (`CT_FontRel`).
+ *
+ * Metadata only — binary ODTTF authoring / decode is out of scope.
+ *
+ * @private
+ */
+export interface FontEmbedRef {
+    /**
+     * @private
+     */
+    readonly slot: FontEmbedSlot;
+    /**
+     * @private
+   * `r:id` targeting the font part relationship. */
+    readonly relationshipId: string;
+    /**
+     * @private
+   * Optional `w:fontKey`. */
+    readonly fontKey: string | undefined;
+    /**
+     * @private
+   * Optional `w:subsetted`. */
+    readonly subsetted: boolean | undefined;
+}
+interface ModeledEmbed {
+    slot: FontEmbedSlot;
+    relationshipId: string;
+    fontKey: string | undefined;
+    subsetted: boolean | undefined;
+    extraAttributes: OpenXmlAttribute[];
+    children: OpenXmlChild[];
+    namespaceDeclarations: NamespaceDeclaration[];
+}
+/**
+ * One `w:font` row in `fontTable.xml` (`CT_Font`, Transitional `wml.xsd`).
+ *
+ * Models the full schema child sequence after `w:name`:
+ * `altName`, `panose1`, `charset`, `family`, `notTrueType`, `pitch`, `sig`,
+ * `embedRegular`, `embedBold`, `embedItalic`, `embedBoldItalic`, then residual
+ * unknown children.
+ *
+ * Substitution remains `w:altName` (ECMA-376-1 §17.8.3.1). Embed APIs expose
+ * relationship metadata only; they do not author or decode ODTTF binaries.
+ * `clearEmbed` drops the corresponding child element (markup only); package
+ * orphan cleanup of the target part is not performed in this MVP.
+ *
+ * @private
+ */
+export declare class FontTableFont {
+    private readonly nameValue;
+    private alternateNameValue;
+    private panoseValue;
+    private charsetValue;
+    private familyValue;
+    /** Invalid-on-load family string preserved for round-trip when typed family is unset. */
+    private familyRawValue;
+    private notTrueTypeValue;
+    private pitchValue;
+    private pitchRawValue;
+    private signatureValue;
+    private readonly embeds;
+    private readonly residualChildren;
+    private readonly extraAttributes;
+    private readonly markDirty;
+    /**
+     * @private
+     */
+    constructor(name: string, options: {
+        readonly alternateName?: string | undefined;
+        readonly panose?: string | undefined;
+        readonly charset?: string | undefined;
+        readonly family?: FontFamily | undefined;
+        readonly familyRaw?: string | undefined;
+        readonly notTrueType?: boolean | undefined;
+        readonly pitch?: FontPitch | undefined;
+        readonly pitchRaw?: string | undefined;
+        readonly signature?: FontSignature | undefined;
+        readonly embeds?: ReadonlyArray<ModeledEmbed>;
+        readonly residualChildren?: ReadonlyArray<OpenXmlElement>;
+        readonly extraAttributes?: ReadonlyArray<OpenXmlAttribute>;
+    }, markDirty: () => void);
+    /**
+     * Primary name from `w:font/@w:name` (stored casing preserved).
+     *
+     * @public
+     */
+    readonly name: string;
+    /**
+     * Alternate name list as stored on `w:altName/@w:val`, or `undefined` if absent.
+     *
+     * ECMA-376-1 §17.8.3.1: comma-delimited list; writers may set a single name or a
+     * full list string. Assign `undefined` (or empty / whitespace-only) to remove
+     * `w:altName`; the font entry is kept. Empty `w:val` is never emitted.
+     *
+     * @public
+     */
+    alternateName: string | undefined;
+    /**
+     * Split {@link alternateName} on commas; empty segments (adjacent commas) dropped
+     * per ECMA. Empty array when no `altName`.
+     *
+     * @public
+     */
+    readonly alternateNames: ReadonlyArray<string>;
+    /**
+     * PANOSE-1 classification from `w:panose1/@w:val` (`ST_Panose`), or `undefined`.
+     * Stored as the attribute string. Assign `undefined` / empty to clear.
+     *
+     * @public
+     */
+    panose: string | undefined;
+    /**
+     * Character set from `w:charset/@w:val` (`ST_UcharHexNumber`), or `undefined`.
+     * Stored as the attribute string. Assign `undefined` / empty to clear.
+     *
+     * @public
+     */
+    charset: string | undefined;
+    /**
+     * Font family from `w:family/@w:val` (`ST_FontFamily`), or `undefined` when
+     * absent or not a known enumeration value on load.
+     *
+     * @throws RangeError when assigning a string that is not a {@link FontFamily} value.
+     *
+     * @public
+     */
+    family: FontFamily | undefined;
+    /**
+     * `w:notTrueType` (`CT_OnOff`). `true` when the element is present without `val`
+     * or with a true `ST_OnOff` value; `false` when explicitly off; `undefined` when
+     * the child is absent.
+     *
+     * @public
+     */
+    notTrueType: boolean | undefined;
+    /**
+     * Pitch from `w:pitch/@w:val` (`ST_Pitch`), or `undefined` when absent or not a
+     * known enumeration value on load.
+     *
+     * @throws RangeError when assigning a string that is not a {@link FontPitch} value.
+     *
+     * @public
+     */
+    pitch: FontPitch | undefined;
+    /**
+     * Supported Unicode / code-page bitmasks from `w:sig` (`CT_FontSig`), or
+     * `undefined` when the child is absent or missing a required attribute.
+     *
+     * @public
+     */
+    signature: FontSignature | undefined;
+    /**
+     * Embedded font relationship metadata for each modeled embed child present on
+     * this row, in schema slot order.
+     *
+     * @public
+     */
+    embedRefs(): ReadonlyArray<FontEmbedRef>;
+    /**
+     * Embed metadata for `slot`, or `undefined` when that child is absent.
+     *
+     * @public
+     */
+    embedRef(slot: FontEmbedSlot): FontEmbedRef | undefined;
+    /**
+     * Drop the embed child for `slot` from this font row (markup only).
+     * Does not remove package parts or relationships targeted by `r:id`.
+     * No-op when the slot is already absent.
+     *
+     * @public
+     */
+    clearEmbed(slot: FontEmbedSlot): void;
+    /**
+     * @private
+     */
+    serialize(): OpenXmlElement;
+}
+/**
+ * Parse one `w:font` element into a {@link FontTableFont}, or `undefined` when
+ * `@w:name` is missing/empty.
+ *
+ * @private
+ */
+export declare function parseFontTableFont(element: OpenXmlElement, markDirty: () => void): FontTableFont | undefined;
+/**
+ * Create a minimal font entry (`@w:name` only).
+ *
+ * @private
+ */
+export declare function createFontTableFont(name: string, markDirty: () => void): FontTableFont;
+export {};