@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

package/src/features/ole-object/catalog.d.ts

@@ -0,0 +1,300 @@
+import { WordDocument } from '../document/document';
+import { FeatureMultiPackagePart } from '../document/feature-multi-package-part';
+import { OpcRelationship } from '../../core/opc/relationships';
+import { OpcPackage } from '../../core/opc/package';
+import { PartName } from '../../core/opc/part-name';
+import { ImageType } from '../images/index';
+/**
+ * Minimal structural view of an OLE object the catalog needs for the
+ * pending-embed / pending-link lifecycle (keeps `catalog.ts` free of an
+ * index import; `OleObject` satisfies this structurally).
+ *
+ * @private
+ */
+export interface PendingEmbedHost {
+    /** Whether the authored embed/link still awaits save-time materialization. */
+    isPendingRelationship(): boolean;
+    /** Bind the allocated relationship id at materialization. */
+    resolveRelationshipId(relationshipId: string): void;
+}
+/**
+ * Minimal structural view for pending icon media materialization
+ * (TASK-8056). Distinct from {@link PendingEmbedHost} so embed/link and
+ * icon can materialize independently on the same object.
+ *
+ * @private
+ */
+export interface PendingIconHost {
+    /** Whether authored icon bytes still await save-time materialization. */
+    isPendingIcon(): boolean;
+    /** Bind the allocated image relationship id onto `v:imagedata/@r:id`. */
+    resolveIconRelationshipId(relationshipId: string): void;
+}
+/**
+ * Default content type for authored embedded-object parts (unknown binary
+ * storage). ECMA-376-1 §15.2.10 permits any content type; Word uses this
+ * token for OLE compound storages.
+ *
+ * @private
+ */
+export declare const OLE_OBJECT_DEFAULT_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.oleObject";
+/**
+ * One embedded-object part linked from the Main Document part.
+ *
+ * @private
+ */
+export interface OleObjectPartEntry {
+    /** Full OPC part name, e.g. `/word/embeddings/oleObject1.bin`. */
+    readonly partName: PartName;
+    /** Main-document relationship id pointing at the part. */
+    readonly relationshipId: string;
+    /** Relationship type (`OLE_OBJECT_RELATIONSHIP_TYPE` on load/authored). */
+    readonly relationshipType: string;
+    /** Content type of the part (Override). */
+    readonly contentType: string;
+    /** Opaque payload bytes (embedded objects only; linked has no part). */
+    data: Uint8Array;
+    /** True when the bytes changed since load/last save. */
+    dirty: boolean;
+    /**
+     * @private
+   * Relationship queued for creation at the next save. */
+    pendingRelationship: OpcRelationship | undefined;
+}
+/**
+ * One icon/preview media part linked from the Main Document part
+ * (TASK-8056; ECMA-376-1 §15.2.14 Image Part; VML `v:imagedata`).
+ *
+ * @private
+ */
+export interface OleIconPartEntry {
+    /** Full OPC part name, e.g. `/word/media/image1.png`. */
+    readonly partName: PartName;
+    /** Main-document relationship id pointing at the media part. */
+    readonly relationshipId: string;
+    /** Relationship type (`IMAGE_RELATIONSHIP_TYPE`). */
+    readonly relationshipType: string;
+    /** Sniffed PNG or JPEG content type. */
+    readonly contentType: ImageType;
+    /** Icon/preview image bytes. */
+    data: Uint8Array;
+    /** True when the bytes changed since load/last save. */
+    dirty: boolean;
+    /**
+     * @private
+   * Relationship queued for creation at the next save. */
+    pendingRelationship: OpcRelationship | undefined;
+}
+/**
+ * External (linked) OLE relationship entry — target string only, no part.
+ *
+ * @private
+ */
+interface OleObjectExternalEntry {
+    readonly relationshipId: string;
+    /** Stored target string (path/URI); never fetched. */
+    readonly target: string;
+    /**
+     * Relationship type as loaded. Authored links always use the transitional
+     * oleObject type; long-path is accept-only and never re-emitted.
+     */
+    readonly relationshipType: string;
+    /** Relationship queued for creation at the next save (authored only). */
+    pendingRelationship: OpcRelationship | undefined;
+}
+/**
+ * Package catalog for embedded OLE object parts, linked external targets,
+ * and icon/preview media parts (TASK-8056).
+ *
+ * Loaded from Main-WordDocument relationships of the transitional `oleObject`
+ * type (and the long-path link variant on load only) plus image
+ * relationships whose parts are PNG/JPEG (icon media). Authored
+ * embeds/links/icons register pending entries that are materialized at save.
+ *
+ * @private
+ */
+export declare class OleObjectCatalog implements FeatureMultiPackagePart {
+    private readonly entries;
+    private readonly byRelationshipId;
+    private readonly externalByRelationshipId;
+    private readonly iconEntries;
+    private readonly iconByRelationshipId;
+    private readonly iconHashToRelationshipId;
+    private readonly pendingRemovals;
+    private readonly pendingExternalRemovals;
+    private readonly pendingIconRemovals;
+    private readonly pendingEmbeds;
+    private readonly pendingLinks;
+    private readonly pendingIcons;
+    /**
+     * @private
+     */
+    constructor(entries: Map<PartName, OleObjectPartEntry>, externalByRelationshipId?: Map<string, OleObjectExternalEntry>, iconEntries?: Map<PartName, OleIconPartEntry>);
+    /**
+     * Loaded + pending embedded-object entries (embedded only; linked objects
+     * have no part).
+     *
+     * @private
+     */
+    objects(): ReadonlyArray<OleObjectPartEntry>;
+    /**
+     * Payload bytes for a main-document relationship id (embedded parts only).
+     *
+     * @private
+     */
+    bytesForRelationship(relationshipId: string): Uint8Array | undefined;
+    /**
+     * External target string for a main-document relationship id (linked
+     * objects only). Returns `undefined` for embeds. The string is stored
+     * verbatim and is never fetched, resolved, or opened.
+     *
+     * @private
+     */
+    targetForRelationship(relationshipId: string): string | undefined;
+    /**
+     * Icon/preview image bytes for a main-document image relationship id
+     * (TASK-8056). Returns `undefined` when the id is not an icon media entry.
+     *
+     * @private
+     */
+    iconBytesForRelationship(relationshipId: string): Uint8Array | undefined;
+    /**
+     * @private
+   * Pending payload bytes for a not-yet-materialized embed. */
+    pendingBytesFor(object: PendingEmbedHost): Uint8Array | undefined;
+    /**
+     * @private
+   * Pending external target for a not-yet-materialized link. */
+    pendingTargetFor(object: PendingEmbedHost): string | undefined;
+    /**
+     * @private
+   * Pending icon bytes for a not-yet-materialized icon. */
+    pendingIconBytesFor(object: PendingIconHost): Uint8Array | undefined;
+    /**
+     * @private
+   * Part names already owned by the catalog (embed + icon). */
+    pendingPartNames(): ReadonlyArray<PartName>;
+    /**
+     * @private
+     * Relationship ids already owned by the catalog
+     * (embed + link + icon).
+     */
+    pendingRelationshipIds(): ReadonlyArray<string>;
+    /**
+     * @private
+     * Record embed intent without allocating package ids
+     * (images `registerPendingImage` pattern). `contentType` may be
+     * caller-provided or the module default.
+     */
+    registerPendingEmbed(object: PendingEmbedHost, bytes: Uint8Array, contentType: string): void;
+    /**
+     * @private
+     * Record link intent without allocating package ids
+     * (hyperlinks `registerPendingExternal` pattern). Target is a stored
+     * string only — never fetched.
+     */
+    registerPendingLink(object: PendingEmbedHost, target: string): void;
+    /**
+     * @private
+     * Record icon/preview media intent without allocating package
+     * ids (TASK-8056; images `registerPendingImage` pattern). Bytes must
+     * already be sniffed as PNG or JPEG by the caller.
+     */
+    registerPendingIcon(object: PendingIconHost, bytes: Uint8Array, contentType: ImageType): void;
+    /**
+     * @private
+   * Drop a pending embed removed before save. */
+    discardPendingEmbed(object: PendingEmbedHost): void;
+    /**
+     * @private
+   * Drop a pending link removed before save. */
+    discardPendingLink(object: PendingEmbedHost): void;
+    /**
+     * @private
+   * Drop a pending icon removed before save. */
+    discardPendingIcon(object: PendingIconHost): void;
+    /**
+     * @private
+   * Replace bytes on a not-yet-materialized embed. */
+    updatePendingBytes(object: PendingEmbedHost, bytes: Uint8Array): void;
+    /**
+     * @private
+     * Replace bytes on a loaded entry and mark it dirty
+     * (byte-replace only; the library never interprets OLE storages).
+     */
+    replaceBytes(relationshipId: string, bytes: Uint8Array): void;
+    /**
+     * @private
+     * Queue orphan removal of a part + relationship + content-type
+     * override (GC parity with the images module). For external (link-only)
+     * relationships, removes the relationship entry only — there is no part.
+     */
+    removeEntry(relationshipId: string): void;
+    /**
+     * @private
+     * Queue removal of an icon media part + image relationship
+     * (TASK-8056). Shared media (hash-deduped) is removed only when this is
+     * the last catalog reference; callers must not remove shared icons while
+     * other objects still reference the same relationship id.
+     */
+    removeIconEntry(relationshipId: string): void;
+    /**
+     * @private
+     */
+    isDirty(): boolean;
+    /**
+     * @private
+     * Allocate a new embedding part + main-document relationship
+     * for one pending embed (images `allocatePart` pattern; no dedupe).
+     */
+    allocatePart(bytes: Uint8Array, contentType: string, usedRelIds: ReadonlySet<string>, usedPartNames: ReadonlySet<string>): {
+        entry: OleObjectPartEntry;
+        relationshipId: string;
+    };
+    /**
+     * @private
+     * Allocate an external oleObject relationship for one pending
+     * link (hyperlinks `allocateExternalTarget` pattern). No part is created.
+     * Always emits the transitional oleObject type — never the long-path
+     * accept-only variant.
+     */
+    allocateExternalTarget(target: string, usedRelIds: ReadonlySet<string>): string;
+    /**
+     * @private
+     * Allocate (or reuse via sha256) an icon media part + image
+     * relationship (TASK-8056; images `allocatePart` + hash-dedupe pattern).
+     */
+    allocateIconPart(bytes: Uint8Array, contentType: ImageType, usedRelIds: ReadonlySet<string>, usedPartNames: ReadonlySet<string>): {
+        entry: OleIconPartEntry;
+        relationshipId: string;
+    };
+    /**
+     * @private
+     * Allocate relationship ids (+ part names for embeds/icons) for
+     * pending embeds, links, and icons and resolve each object's `r:id` values
+     * (save-time `materializePending`). The caller supplies the modeled OLE
+     * objects in document order (avoids a circular import of the index listing
+     * helper). Objects that carry a pending registration but were not visited
+     * keep their registration (the next save retries); objects removed before
+     * save are dropped via `discardPendingEmbed` / `discardPendingLink` /
+     * `discardPendingIcon`.
+     */
+    materializePending(document: WordDocument, objects: ReadonlyArray<(PendingEmbedHost & PendingIconHost)>): void;
+    /**
+     * @private
+     */
+    applyToPackage(pkg: OpcPackage, mainPartName: PartName): OpcPackage;
+}
+/**
+ * Load the OLE-object catalog from Main-WordDocument relationships of the
+ * `oleObject` type (and the long-path link variant) plus PNG/JPEG image
+ * relationships used as OLE icon/preview media (TASK-8056).
+ *
+ * Internal oleObject targets load embedded parts; external targets load
+ * link target strings only (no part). Image relationships with PNG/JPEG
+ * content types load into the icon catalog.
+ *
+ * @private
+ */
+export declare function loadOleObjectCatalog(pkg: OpcPackage, mainPartName: PartName): OleObjectCatalog;
+export {};