@syncfusion/ej2-docx 0.0.0-stage → 35.1.39

package/src/features/bibliography/index.js

@@ -0,0 +1,290 @@
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+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 { partByName, relationshipsForPart } from '../../core/opc/package';
+import { resolveInternalTarget } from '../../core/opc/part-name';
+import { featureId, registerFeature, registerFeatureMultiPartHandler, } from '../../core/registry/index';
+import { parseXml } from '../../core/xml/index';
+var BIBLIOGRAPHY = featureId('bibliography');
+var utf8Decoder = new TextDecoder('utf-8');
+/**
+ * @private
+ * Transitional bibliography namespace (ECMA-376-4 §13.2.3). */
+export var BIBLIOGRAPHY_NAMESPACE = 'http://schemas.openxmlformats.org/officeDocument/2006/bibliography';
+/**
+ * @private
+ * Strict bibliography namespace (ECMA-376-1 §15.2.3). */
+export var BIBLIOGRAPHY_STRICT_NAMESPACE = 'http://purl.oclc.org/ooxml/officeDocument/bibliography';
+/**
+ * @private
+ * Transitional customXml relationship used by Bibliography parts (ECMA-376-1 §15.2.3). */
+export var BIBLIOGRAPHY_CUSTOM_XML_RELATIONSHIP_TYPE = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/customXml';
+/**
+ * @private
+ * Strict customXml relationship used by Bibliography parts. */
+export var STRICT_BIBLIOGRAPHY_CUSTOM_XML_RELATIONSHIP_TYPE = 'http://purl.oclc.org/ooxml/officeDocument/relationships/customXml';
+/**
+ * @private
+ * Bibliography part content type (ECMA-376-1 §15.2.3). */
+export var BIBLIOGRAPHY_CONTENT_TYPE = 'application/xml';
+var CUSTOM_XML_RELATIONSHIP_TYPES = [
+    BIBLIOGRAPHY_CUSTOM_XML_RELATIONSHIP_TYPE,
+    STRICT_BIBLIOGRAPHY_CUSTOM_XML_RELATIONSHIP_TYPE,
+];
+var EMPTY_METADATA = {
+    present: false,
+    sourceCount: 0,
+    styleName: undefined,
+    selectedStyle: undefined,
+    sourceTags: [],
+};
+function isBibliographyNamespace(namespaceUri) {
+    return namespaceUri === BIBLIOGRAPHY_NAMESPACE || namespaceUri === BIBLIOGRAPHY_STRICT_NAMESPACE;
+}
+function bibliographyAttribute(element, localName) {
+    var found = element.attributes.find(function (attribute) { return attribute.localName === localName &&
+        (isBibliographyNamespace(attribute.namespaceUri) || attribute.namespaceUri === ''); });
+    return found == null ? undefined : found.value;
+}
+function bibliographyChildElements(element) {
+    return element.children.filter(function (child) { return child.kind === 'element' && isBibliographyNamespace(child.namespaceUri); });
+}
+function bibliographyText(element) {
+    var e_1, _a;
+    try {
+        for (var _b = __values(element.children), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var child = _c.value;
+            if (child.kind === 'text' && child.value.length > 0) {
+                return child.value;
+            }
+        }
+    }
+    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 undefined;
+}
+function parseBibliographyMetadata(root) {
+    var e_2, _a, e_3, _b;
+    if (root.localName !== 'Sources' || !isBibliographyNamespace(root.namespaceUri)) {
+        return undefined;
+    }
+    var sourceTags = [];
+    var sourceCount = 0;
+    try {
+        for (var _c = __values(bibliographyChildElements(root)), _d = _c.next(); !_d.done; _d = _c.next()) {
+            var child = _d.value;
+            if (child.localName !== 'Source') {
+                continue;
+            }
+            sourceCount += 1;
+            try {
+                for (var _e = __values(bibliographyChildElements(child)), _f = _e.next(); !_f.done; _f = _e.next()) {
+                    var field = _f.value;
+                    if (field.localName !== 'Tag') {
+                        continue;
+                    }
+                    var tag = bibliographyText(field);
+                    if (tag !== undefined && tag.length > 0) {
+                        sourceTags.push(tag);
+                    }
+                    break;
+                }
+            }
+            catch (e_3_1) { e_3 = { error: e_3_1 }; }
+            finally {
+                try {
+                    if (_f && !_f.done && (_b = _e.return)) _b.call(_e);
+                }
+                finally { if (e_3) throw e_3.error; }
+            }
+        }
+    }
+    catch (e_2_1) { e_2 = { error: e_2_1 }; }
+    finally {
+        try {
+            if (_d && !_d.done && (_a = _c.return)) _a.call(_c);
+        }
+        finally { if (e_2) throw e_2.error; }
+    }
+    return {
+        present: true,
+        sourceCount: sourceCount,
+        styleName: bibliographyAttribute(root, 'StyleName'),
+        selectedStyle: bibliographyAttribute(root, 'SelectedStyle'),
+        sourceTags: sourceTags,
+    };
+}
+function parseBibliographyMetadataFromBytes(bytes) {
+    if (bytes.byteLength === 0) {
+        return undefined;
+    }
+    try {
+        var root = parseXml(utf8Decoder.decode(bytes));
+        return parseBibliographyMetadata(root);
+    }
+    catch (_a) {
+        return undefined;
+    }
+}
+/**
+ * Preserve-only bibliography sources catalog linked from the Main Document via a
+ * `customXml` relationship. Source field content is opaque; style name and tags
+ * are read-only metadata. No source editor or mutation API is provided.
+ *
+ * @private
+ */
+var BibliographyCatalog = /** @class */ (function () {
+    /**
+     * @private
+     */
+    function BibliographyCatalog(metadata) {
+        this.metadata = metadata;
+    }
+    /**
+     * Whether a Bibliography part (`b:Sources` root) was found.
+     *
+     * @public
+     */
+    BibliographyCatalog.prototype.present = function () {
+        return this.metadata.present;
+    };
+    /**
+     * Count of `b:Source` children under `b:Sources`.
+     *
+     * @public
+     */
+    BibliographyCatalog.prototype.sourceCount = function () {
+        return this.metadata.sourceCount;
+    };
+    /**
+     * `b:Sources/@StyleName`, or `undefined` when absent.
+     *
+     * @public
+     */
+    BibliographyCatalog.prototype.styleName = function () {
+        return this.metadata.styleName;
+    };
+    /**
+     * `b:Sources/@SelectedStyle`, or `undefined` when absent.
+     *
+     * @public
+     */
+    BibliographyCatalog.prototype.selectedStyle = function () {
+        return this.metadata.selectedStyle;
+    };
+    /**
+     * `b:Source/b:Tag` text values in document order.
+     *
+     * @public
+     */
+    BibliographyCatalog.prototype.sourceTags = function () {
+        return this.metadata.sourceTags;
+    };
+    /**
+     * @private
+     */
+    BibliographyCatalog.prototype.isDirty = function () {
+        return false;
+    };
+    /**
+     * @private
+     */
+    BibliographyCatalog.prototype.applyToPackage = function (pkg, mainPartName) {
+        void mainPartName;
+        return pkg;
+    };
+    return BibliographyCatalog;
+}());
+export { BibliographyCatalog };
+function loadBibliographyCatalog(pkg, mainPartName) {
+    var e_4, _a;
+    try {
+        for (var _b = __values(relationshipsForPart(pkg, mainPartName).items), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var rel = _c.value;
+            if (CUSTOM_XML_RELATIONSHIP_TYPES.indexOf(rel.type) === -1) {
+                continue;
+            }
+            var itemPartName = resolveInternalTarget(rel.target, mainPartName);
+            var itemPart = partByName(pkg, itemPartName);
+            if (itemPart === undefined) {
+                continue;
+            }
+            var metadata = parseBibliographyMetadataFromBytes(itemPart.data);
+            if (metadata === undefined) {
+                continue;
+            }
+            return new BibliographyCatalog(metadata);
+        }
+    }
+    catch (e_4_1) { e_4 = { error: e_4_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_4) throw e_4.error; }
+    }
+    return new BibliographyCatalog(__assign({}, EMPTY_METADATA));
+}
+var registered = false;
+/**
+ * @private
+ * Test hook */
+export function resetBibliographyFeatureForTests() {
+    registered = false;
+}
+/**
+ * @private
+ * Register the bibliography detection handler. Idempotent. */
+export function registerBibliographyFeature() {
+    if (registered) {
+        return;
+    }
+    registered = true;
+    registerFeature({ id: BIBLIOGRAPHY });
+    registerFeatureMultiPartHandler({
+        featureId: BIBLIOGRAPHY,
+        relationshipTypes: CUSTOM_XML_RELATIONSHIP_TYPES,
+        loadParts: function (pkg, ctx) {
+            return loadBibliographyCatalog(pkg, ctx.mainPartName);
+        },
+    });
+}
+/**
+ * Bibliography catalog for a document. Requires {@link registerBibliographyFeature}.
+ *
+ * @throws DocxError `UNKNOWN_FEATURE` when the module was not registered before load.
+ *
+ * @private
+ */
+export function bibliographyFor(document) {
+    var part = document.featurePart(BIBLIOGRAPHY);
+    if (part === undefined || !(part instanceof BibliographyCatalog)) {
+        throw new DocxError('feature/not-registered', 'Bibliography catalog was not loaded; call registerBibliographyFeature() before WordDocument.open');
+    }
+    return part;
+}
+registerBibliographyFeature();

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

@@ -0,0 +1,331 @@
+import { WordDocument } from '../document/document';
+import { FeatureInline } from '../document/feature-inline';
+import { Paragraph } from '../document/paragraph';
+import { FeatureInlineParagraphItem, InlineContent } from '../document/text-range';
+import { OpenXmlAttribute, OpenXmlElement } from '../../core/xml/index';
+/**
+ * Bookmark range start marker (`w:bookmarkStart`, ECMA-376-1 §17.13.6.2).
+ *
+ * Paired with a {@link BookmarkEnd} that shares the same internal package id.
+ * Public surface is {@link BookmarkStart.name} and optional table column span
+ * (`firstColumn` / `lastColumn`). Pairing id stays internal.
+ *
+ * @remarks
+ * - `name` maps `w:name`; empty or whitespace-only names are rejected.
+ * - `firstColumn` / `lastColumn` map `w:colFirst` / `w:colLast` (zero-based).
+ * - `undefined` means the column attribute is absent on serialize.
+ * - Residual attributes outside the modeled set round-trip verbatim.
+ *
+ * @public
+ */
+export declare class BookmarkStart implements FeatureInline {
+    private bookmarkIdValue;
+    private nameValue;
+    private firstColumnValue;
+    private lastColumnValue;
+    private readonly residual;
+    /**
+     * @private
+     */
+    constructor(bookmarkId: number, name: string, options?: {
+        readonly firstColumn?: number | undefined;
+        readonly lastColumn?: number | undefined;
+        readonly residualAttributes?: ReadonlyArray<OpenXmlAttribute> | undefined;
+    });
+    /**
+     * Bookmark identifier shared with the paired end marker (`w:id`).
+     *
+     * @private
+     */
+    readonly bookmarkId: number;
+    /**
+     * Bookmark name (`w:name`). Must be non-empty and not whitespace-only.
+     *
+     * Setting an invalid name throws {@link DocxError} with code
+     * `content/invalid-bookmark`.
+     */
+    name: string;
+    /**
+     * Zero-based first table column of the bookmark (`w:colFirst`).
+     *
+     * `undefined` means the attribute is absent. Assigning `undefined` clears it.
+     */
+    firstColumn: number | undefined;
+    /**
+     * Zero-based last table column of the bookmark (`w:colLast`).
+     *
+     * `undefined` means the attribute is absent. Assigning `undefined` clears it.
+     */
+    lastColumn: number | undefined;
+    /**
+     * Assigns the package `w:id` used to pair start and end markers.
+     *
+     * @private
+     */
+    setBookmarkId(bookmarkId: number): void;
+    /**
+     * Whether this marker still holds a temporary negative id before save materialization.
+     *
+     * @private
+     */
+    isPendingBookmarkId(): boolean;
+    /**
+     * @private
+     * Residual attributes preserved for lossless serialization.
+     */
+    residualAttributes(): ReadonlyArray<OpenXmlAttribute>;
+    /**
+     * No-op detach hook for {@link FeatureInline} parity.
+     *
+     * @private
+     */
+    releaseContent(): void;
+    /**
+     * Serializes this marker to `w:bookmarkStart`.
+     *
+     * @private
+     */
+    toOpenXml(): OpenXmlElement;
+}
+/**
+ * Bookmark range end marker (`w:bookmarkEnd`, ECMA-376-1 §17.13.6.1).
+ *
+ * Closes the range opened by a matching {@link BookmarkStart}. Pairing uses the
+ * internal package id; {@link BookmarkEnd.name} is a public convenience mirror
+ * of the start name when paired (settable independently for authoring symmetry
+ * with DocIO). OOXML `bookmarkEnd` serializes `w:id` only.
+ *
+ * @public
+ */
+export declare class BookmarkEnd implements FeatureInline {
+    private bookmarkIdValue;
+    private nameValue;
+    /**
+     * @private
+     */
+    constructor(bookmarkId: number, name?: string);
+    /**
+     * Bookmark identifier shared with the paired start marker (`w:id`).
+     *
+     * @private
+     */
+    readonly bookmarkId: number;
+    /**
+     * Bookmark name convenience on the end marker (DocIO parity).
+     *
+     * Empty string is allowed on the end marker itself (schema has no `w:name`
+     * on `bookmarkEnd`). When set to a non-empty value, whitespace-only is
+     * rejected. Pairing always uses internal id, never this name.
+     */
+    name: string;
+    /**
+     * Assigns the package `w:id` used to pair start and end markers.
+     *
+     * @private
+     */
+    setBookmarkId(bookmarkId: number): void;
+    /**
+     * Whether this marker still holds a temporary negative id before save materialization.
+     *
+     * @private
+     */
+    isPendingBookmarkId(): boolean;
+    /**
+     * No-op detach hook for {@link FeatureInline} parity.
+     *
+     * @private
+     */
+    releaseContent(): void;
+    /**
+     * Serializes this marker to `w:bookmarkEnd`.
+     *
+     * @private
+     */
+    toOpenXml(): OpenXmlElement;
+}
+/**
+ * Live view over a paired {@link BookmarkStart} / {@link BookmarkEnd}.
+ *
+ * Does not own markup or cache enclosed content: markers remain paragraph
+ * inlines (possibly in different paragraphs). Property reads/writes for name
+ * and column span go through the start marker. Empty ranges and arbitrary
+ * content between markers are valid.
+ *
+ * Discover via {@link WordDocument.bookmarks} / {@link BookmarkCollection}.
+ *
+ * @public
+ */
+export declare class Bookmark {
+    private readonly startMarkerValue;
+    private readonly endMarkerValue;
+    /**
+     * @private
+     */
+    constructor(start: BookmarkStart, end: BookmarkEnd);
+    /**
+     * Bookmark name (`w:name` on the start marker). Read-only on the pair view;
+     * rename via {@link BookmarkStart.name} / {@link bookmarkStart}.
+     */
+    readonly name: string;
+    /**
+     * Start marker for this bookmark.
+     */
+    readonly bookmarkStart: BookmarkStart;
+    /**
+     * End marker for this bookmark.
+     */
+    readonly bookmarkEnd: BookmarkEnd;
+    /**
+     * Zero-based first table column (`w:colFirst` on the start marker).
+     */
+    firstColumn: number | undefined;
+    /**
+     * Zero-based last table column (`w:colLast` on the start marker).
+     */
+    lastColumn: number | undefined;
+    /**
+     * Identifier shared by the start and end markers (`w:id`).
+     *
+     * @private
+     */
+    readonly bookmarkId: number;
+    /**
+     * Start marker (internal alias of {@link bookmarkStart}).
+     *
+     * @private
+     */
+    readonly startMarker: BookmarkStart;
+    /**
+     * End marker (internal alias of {@link bookmarkEnd}).
+     *
+     * @private
+     */
+    readonly endMarker: BookmarkEnd;
+}
+/**
+ * All paired bookmarks in document order of their start markers.
+ *
+ * Orphan start/end markers are omitted from the list but remain in the DOM
+ * and continue to serialize.
+ *
+ * @private
+ */
+export declare function bookmarksInDocument(document: WordDocument): ReadonlyArray<Bookmark>;
+/**
+ * Named bookmarks whose start marker lives in `paragraph`, in document order.
+ *
+ * Cross-paragraph bookmarks are included when their **start** is in this
+ * paragraph. Orphans are omitted.
+ *
+ * @private
+ */
+export declare function bookmarksInParagraph(paragraph: Paragraph): ReadonlyArray<Bookmark>;
+/**
+ * First paired bookmark whose name matches exactly (case-sensitive), document order.
+ *
+ * @private
+ */
+export declare function bookmarkByName(document: WordDocument, name: string): Bookmark | undefined;
+/**
+ * Remove start and end markers of a paired bookmark; enclosed content is kept.
+ *
+ * Markers may live in different paragraphs. Throws
+ * {@link DocxError} `content/unknown-bookmark` when either marker is missing.
+ *
+ * @private
+ */
+export declare function removeBookmark(document: WordDocument, bookmark: Bookmark): void;
+/**
+ * Live query collection of paired bookmarks on a {@link WordDocument}.
+ *
+ * Members are stable {@link Bookmark} views for the current start/end pairing.
+ * Index properties refresh on {@link count} / mutation helpers.
+ *
+ * @public
+ */
+export declare class BookmarkCollection implements Iterable<Bookmark> {
+    private readonly document;
+    private cachedLength;
+    /**
+     * @private
+     */
+    constructor(document: WordDocument);
+    /**
+     * Number of paired bookmarks in document order.
+     *
+     * @public
+     */
+    readonly count: number;
+    /**
+     * Bookmark at zero-based `index`, or `undefined` when out of range.
+     *
+     * @public
+     */
+    itemAt(index: number): Bookmark | undefined;
+    /**
+     * First bookmark whose name matches exactly (case-sensitive).
+     *
+     * @public
+     */
+    findByName(name: string): Bookmark | undefined;
+    /**
+     * Remove markers for `bookmark`; content between markers is preserved.
+     *
+     * @throws DocxError `content/unknown-bookmark` when markers are detached.
+     * @public
+     */
+    remove(bookmark: Bookmark): void;
+    /**
+     * Remove the bookmark at zero-based `index`.
+     *
+     * @throws RangeError when `index` is out of range.
+     * @public
+     */
+    removeAt(index: number): void;
+    /**
+     * Remove every paired bookmark’s markers; content is preserved.
+     *
+     * @public
+     */
+    clear(): void;
+    [Symbol.iterator](): Iterator<Bookmark>;
+    /**
+     * Refresh numeric index properties from the current pairing.
+     *
+     * @private
+     */
+    rebuildIndexProperties(): void;
+}
+export interface BookmarkCollection {
+    readonly [index: number]: Bookmark;
+}
+/**
+ * Stable public {@link BookmarkCollection} for `document`.
+ *
+ * @private
+ */
+export declare function bookmarkCollectionFor(document: WordDocument): BookmarkCollection;
+/**
+ * @private
+ * Test hook */
+export declare function resetBookmarksFeatureForTests(): void;
+/**
+ * @private
+ * Register bookmark inline handlers. Idempotent. */
+export declare function registerBookmarksFeature(): void;
+/**
+ * Whether paragraph inline content is a modeled bookmark start from this module.
+ *
+ * @private
+ */
+export declare function isBookmarkStartInline(inline: InlineContent): inline is FeatureInlineParagraphItem & {
+    value: BookmarkStart;
+};
+/**
+ * Whether paragraph inline content is a modeled bookmark end from this module.
+ *
+ * @private
+ */
+export declare function isBookmarkEndInline(inline: InlineContent): inline is FeatureInlineParagraphItem & {
+    value: BookmarkEnd;
+};