@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

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

@@ -0,0 +1,526 @@
+export * from './catalog';
+export * from './relationship';
+export * from './typed-dom';
+import { WordDocument } from '../document/document';
+import { FeatureRunLeaf } from '../document/feature-run-leaf';
+import { Paragraph } from '../document/paragraph';
+import { FeatureRunParagraphItem, ParagraphItem } from '../document/text-range';
+import { OpenXmlElement } from '../../core/xml/index';
+import { OleObjectCatalog } from './catalog';
+import { OleDrawAspect, OleLinkType, OleUpdateMode, OleWireForm } from './typed-dom';
+/**
+ * @private
+ */
+/**
+ * Feature id for the optional OLE-object module.
+ *
+ * @private
+ */
+export declare const OLE_OBJECT: import("../../core/registry").FeatureId;
+/**
+ * Typed, editable view over a WordprocessingML embedded/linked OLE object
+ * (`w:object` containing an `o:OLEObject`, `w:objectEmbed`, or
+ * `w:objectLink` child).
+ *
+ * @remarks
+ * **Security — never execute.** The library must never activate, open,
+ * automate, or execute OLE, ActiveX, VBA, scripts, or external content.
+ * Binary payload parts (`word/embeddings/*`) are opaque caller data: the
+ * {@link OleObject.payloadBytes} accessor moves bytes in and out verbatim
+ * and nothing in the module inspects, parses, or launches them. Link
+ * targets are stored strings and are never fetched, resolved, or probed.
+ *
+ * One semantic model over two schema-backed wire encodings (fixed at load;
+ * edits never convert forms):
+ * - `office` — `o:OLEObject` (transitional `vml-officeDrawing.xsd`
+ *   `CT_OLEObject`, ECMA-376-4 §19.2.2.20)
+ * - `wml` — `w:objectEmbed` / `w:objectLink` (transitional `wml.xsd`
+ *   `CT_ObjectEmbed`/`CT_ObjectLink`, ECMA-376-1 §17.3.3.20/§17.3.3.21)
+ *
+ * Setters patch only the modeled attribute/child on the stored element;
+ * every unmodeled sibling attribute/child survives verbatim. `undefined`
+ * clears the modeled member (three-state semantics).
+ *
+ * Schema citations: `w:object` (`CT_Object`, transitional `wml.xsd` line
+ * 1167; ECMA-376-1 §17.3.3.19), `CT_OLEObject` + `ST_OLEType` /
+ * `ST_OLEDrawAspect` / `ST_OLEUpdateMode` / `ST_OLELinkType`
+ * (`vml-officeDrawing.xsd` lines 291/475–493), Office behavior
+ * [MS-OI29500] §2.1.1834 (`ObjectID` unsupported on links, regenerated per
+ * save). Relationship type: `OLE_OBJECT_RELATIONSHIP_TYPE`.
+ *
+ * @private
+ */
+export declare class OleObject implements FeatureRunLeaf {
+    private state;
+    private relationshipIdValue;
+    /**
+     * @private Image relationship id from `v:imagedata/@r:id` (TASK-8056
+     * icon/preview media). Distinct from the OLE embed/link `r:id`.
+     */
+    private imageRelationshipIdValue;
+    /**
+     * @private Pending payload registered by embed authoring (TASK-8054);
+     * resolved through the catalog at save. `undefined` for loaded objects
+     * and for pending links.
+     */
+    private pendingPayload;
+    /**
+     * @private True when link authoring registered a pending external target
+     * (TASK-8055) that still awaits save-time materialization.
+     */
+    private pendingLink;
+    /**
+     * @private True when icon/preview media authoring registered pending
+     * image bytes (TASK-8056) that still await save-time materialization.
+     */
+    private pendingIcon;
+    /** @private */
+    constructor(objectElement: OpenXmlElement, oleElement: OpenXmlElement);
+    /**
+     * Which schema encoding this object's `w:object` carries.
+     *
+     * @private
+     */
+    readonly wireForm: OleWireForm;
+    /**
+     * Kind of OLE connection — `embed` (storage part) or `link` (external
+     * target). `undefined` when the stored `@Type` token is unknown
+     * (residual); the WML-native form derives this from
+     * `w:objectEmbed` vs `w:objectLink`.
+     *
+     * @private
+     */
+    linkType: OleLinkType | undefined;
+    /**
+     * Programmatic identifier (`@ProgID` / `@progId`), e.g.
+     * `'Excel.Sheet.12'` or `'Acrobat.WordDocument.DC'`.
+     *
+     * @private
+     */
+    progId: string | undefined;
+    /**
+     * Placeholder shape id (`@ShapeID` / `@shapeId`) — the `v:shape` this
+     * object is visually bound to.
+     *
+     * @private
+     */
+    shapeId: string | undefined;
+    /**
+     * Visual representation (`@DrawAspect` / `@drawAspect`): `content`
+     * (render object content) or `icon` (placeholder icon).
+     * `undefined` = not set / unparseable residual.
+     *
+     * @private
+     */
+    drawAspect: OleDrawAspect | undefined;
+    /**
+     * Embedded-object unique id (`@ObjectID`, office form only — the
+     * WML-native form has no counterpart). Office regenerates this per save
+     * and does not support it on linked objects ([MS-OI29500] §2.1.1834).
+     *
+     * @private
+     */
+    objectId: string | undefined;
+    /**
+     * Link refresh mode (`@UpdateMode` / `@updateMode`): `always` or
+     * `onCall`. Meaningful for linked objects.
+     *
+     * @private
+     */
+    updateMode: OleUpdateMode | undefined;
+    /**
+     * Whether the linked object's appearance is locked
+     * (`o:LockedField` child / `@lockedField`). `undefined` = absent.
+     *
+     * @private
+     */
+    lockedField: boolean | undefined;
+    /**
+     * `o:LinkType` child value (office form only) — e.g.
+     * `'EnhancedMetaFile'`, `'Bitmap'` (`ST_OLELinkType` is an open string).
+     *
+     * @private
+     */
+    linkTypeDescription: string | undefined;
+    /**
+     * Stored LINK-field switches (`o:FieldCodes` child / `@fieldCodes`),
+     * e.g. `'\\f 0'`. Stored verbatim; never interpreted.
+     *
+     * @private
+     */
+    fieldCodes: string | undefined;
+    /**
+     * Original placeholder width from `w:object/@dxaOrig` (points;
+     * wire is `ST_TwipsMeasure`).
+     *
+     * @private
+     */
+    originalWidth: number | undefined;
+    /**
+     * Original placeholder height from `w:object/@dyaOrig` (points;
+     * wire is `ST_TwipsMeasure`).
+     *
+     * @private
+     */
+    originalHeight: number | undefined;
+    /**
+     * `true` when the object is linked (`@Type` = `Link`, or the WML-native
+     * `w:objectLink` form); otherwise treated as embedded.
+     *
+     * @private
+     */
+    readonly linked: boolean;
+    /**
+     * External link target string for linked objects (Main-WordDocument oleObject
+     * relationship with `TargetMode="External"`).
+     *
+     * **Get** returns the pending target registered by
+     * {@link Paragraph.appendOleObject} before the first save, otherwise the
+     * catalog target bound to `relationshipId`. `undefined` for embeds and
+     * when no external relationship is bound.
+     *
+     * **Security — strings only.** The value is a stored path/URI string and is
+     * never fetched, resolved, probed, opened, or executed
+     * (`.agent/policies/security.md`). Callers that need network or filesystem
+     * access must do so outside this library.
+     *
+     * @private
+     */
+    readonly linkTarget: string | undefined;
+    /**
+     * Raw relationship id from `@r:id`, when present. Empty until a pending
+     * authored embed or link is materialized at save (images `Image`
+     * pattern).
+     *
+     * @private
+     */
+    readonly relationshipId: string | undefined;
+    /**
+     * Image relationship id from `v:imagedata/@r:id` (TASK-8056 icon/preview
+     * media). Empty until a pending authored icon is materialized at save.
+     *
+     * @private
+     */
+    readonly imageRelationshipId: string | undefined;
+    /**
+     * Icon/preview image bytes (TASK-8056) — PNG or JPEG only.
+     *
+     * **Get** returns pending icon bytes registered by
+     * {@link Paragraph.appendOleObject} before the first save, otherwise the
+     * catalog icon bytes bound to `imageRelationshipId`. `undefined` when no
+     * icon/preview media is attached. Bytes are copied defensively. The library
+     * never renders, executes, or activates the image
+     * (`.agent/policies/security.md`).
+     *
+     * @private
+     */
+    readonly previewImageBytes: Uint8Array | undefined;
+    /**
+     * Embedded payload bytes — GO program decision Q1 (option A).
+     *
+     * **Get** returns the embedded object's stored bytes: the pending bytes
+     * registered by {@link Paragraph.appendOleObject} before the first save,
+     * otherwise the catalog bytes bound to `relationshipId`. `undefined` for
+     * linked objects (no part exists) and when the embedding part is missing.
+     * The library never interprets these bytes — they are caller data
+     * (`.agent/policies/security.md`); any sandboxing decision is the caller's.
+     *
+     * **Set** replaces the payload bytes byte-for-byte: on pending embeds
+     * (registered bytes swap) and on loaded embeddings (catalog entry marked
+     * dirty; save rewrites the part). Removing bytes (`undefined`) is not
+     * supported — detach by removing the owning run instead. The bytes are
+     * copied defensively on both paths.
+     *
+     * @throws DocxError `content/invalid-ole-object` when setting empty bytes
+     * or bytes on a linked object, or when the owning document (and therefore
+     * its catalog) is unavailable for a loaded-object write.
+     *
+     * @private
+     */
+    payloadBytes: Uint8Array | undefined;
+    /**
+     * Returns the original `w:object` element with modeled edits applied
+     * (unmodeled attributes/children stay byte-identical).
+     *
+     * @private
+     */
+    toOpenXml(): OpenXmlElement;
+    /**
+     * Whether the authored embed or link still awaits save-time
+     * materialization. True between {@link Paragraph.appendOleObject} and the
+     * first {@link WordDocument.saveSync} (or {@link WordDocument.save}).
+     *
+     * @private
+     */
+    isPendingRelationship(): boolean;
+    /**
+     * Bind the materialized relationship id after catalog allocation.
+     * Patches `@r:id` on the stored `o:OLEObject`/`w:object*` element
+     * (patch-in-place: only the id value changes; prefix/position preserved).
+     *
+     * @private
+     */
+    resolveRelationshipId(relationshipId: string): void;
+    /**
+     * Register pending embed bytes + content type (authoring path).
+     *
+     * @private
+     */
+    registerPendingPayload(bytes: Uint8Array, contentType: string): void;
+    /**
+     * Mark this object as a pending external link (authoring path).
+     * The target string lives on the catalog registration.
+     *
+     * @private
+     */
+    registerPendingLinkTarget(): void;
+    /**
+     * Whether authored icon/preview media still awaits save-time
+     * materialization (TASK-8056; {@link PendingIconHost}).
+     *
+     * @private
+     */
+    isPendingIcon(): boolean;
+    /**
+     * Bind the materialized image relationship id after catalog icon
+     * allocation. Patches `v:imagedata/@r:id` (TASK-8056).
+     *
+     * @private
+     */
+    resolveIconRelationshipId(relationshipId: string): void;
+    /**
+     * Mark this object as carrying pending icon/preview media (authoring
+     * path). Bytes live on the catalog registration.
+     *
+     * @private
+     */
+    registerPendingIconMedia(): void;
+    /** Pending content type for catalog mirroring. @private */
+    pendingContentType(): string | undefined;
+    /**
+     * Look up the owning document's OLE catalog, `undefined` when detached or
+     * the feature was not registered at load (authored documents always have
+     * it because `appendOleObject` resolved one to register the payload).
+     *
+     * @private
+     */
+    private lookUpCatalog;
+    /**
+     * Resolve the owning document through the stored element's host run —
+     * tracked by the module when the leaf was bound to a run (authoring) or
+     * parsed under a catalog-active load. Walks up nothing structural: the
+     * catalog contact point is registered at load/append time (see
+     * `bindHostDocument`).
+     *
+     * @private
+     */
+    private owningDocumentOf;
+    /**
+     * Apply one modeled mutation in a single structural pass (patch-in-place).
+     * Invalid enum values throw `DocxError('content/invalid-ole-object')`;
+     * non-positive sizes likewise.
+     */
+    private mutate;
+}
+/** @private Test hook */
+export declare function resetOleObjectFeatureForTests(): void;
+/**
+ * Register the OLE-object run-leaf handler. Idempotent.
+ *
+ * @private
+ */
+export declare function registerOleObjectFeature(): void;
+/**
+ * Whether a run leaf is a modeled OLE object from this module.
+ *
+ * @private
+ */
+export declare function isOleObjectLeaf(item: ParagraphItem): item is FeatureRunParagraphItem & {
+    value: OleObject;
+};
+/**
+ * OLE objects in a paragraph, in document order. Also refreshes the
+ * host-document binding used by {@link OleObject.payloadBytes}.
+ *
+ * @private
+ */
+export declare function oleObjectsInParagraph(paragraph: Paragraph): ReadonlyArray<OleObject>;
+/**
+ * OLE objects in the Main Document body, in document order. Also refreshes
+ * the host-document binding used by {@link OleObject.payloadBytes}.
+ *
+ * @private
+ */
+export declare function oleObjectsInDocument(document: WordDocument): ReadonlyArray<OleObject>;
+/**
+ * Options for {@link Paragraph.appendOleObject}.
+ *
+ * Provide **either** embed payload bytes (`bytes`) **or** a link target
+ * (`linkTarget` / `linkType: 'link'`). Link-only fields (`updateMode`,
+ * `lockedField`, `fieldCodes`) reject on the embed path with
+ * `content/invalid-ole-object` (mirrors `CT_ObjectEmbed` vs `CT_ObjectLink`).
+ *
+ * @private
+ */
+export interface AppendOleObjectOptions {
+    /**
+     * Programmatic identifier of the object — the `@ProgID` token Word
+     * writes, e.g. `'Excel.Sheet.12'`, `'Word.WordDocument.12'`,
+     * `'Acrobat.WordDocument.DC'`. Required and non-empty.
+     */
+    readonly progId: string;
+    /**
+     * Opaque payload bytes for the embedded object (an OLE compound storage,
+     * an `.xlsx`/`.docx`/`.pdf` byte stream, …). Required and non-empty for
+     * the embed path. The library stores these bytes verbatim and never
+     * parses, decompresses, inspects, activates, or launches them. Must not
+     * be combined with a link target.
+     */
+    readonly bytes?: Uint8Array;
+    /**
+     * Connection kind. Defaults to embed when `bytes` is supplied, or link
+     * when `linkTarget` is supplied. Explicit `link` requires a non-empty
+     * `linkTarget`; explicit `embed` rejects link-only fields.
+     */
+    readonly linkType?: OleLinkType;
+    /**
+     * External link target path/URI string stored verbatim on a Main-WordDocument
+     * oleObject relationship with `TargetMode="External"`. Required for the
+     * link path. **Never fetched, resolved, probed, or opened** by this
+     * library (`.agent/policies/security.md`).
+     */
+    readonly linkTarget?: string;
+    /**
+     * Link refresh mode (`Always` | `OnCall`). Defaults to
+     * {@link OleUpdateMode.Always} for links. Rejected on the embed path.
+     */
+    readonly updateMode?: OleUpdateMode;
+    /**
+     * Whether the LINK field is locked (`o:LockedField`). Link path only.
+     */
+    readonly lockedField?: boolean;
+    /**
+     * LINK field switches stored verbatim (e.g. `'\f 0'`); never interpreted.
+     * Link path only (ECMA-376-1 §17.16.5.32).
+     */
+    readonly fieldCodes?: string;
+    /**
+     * Optional open-string `o:LinkType` child (e.g. `'EnhancedMetaFile'`).
+     * Link path only; stored verbatim.
+     */
+    readonly linkTypeDescription?: string;
+    /**
+     * Placeholder width (`w:object/@w:dxaOrig` + `v:shape` style).
+     * @defaultValue 1 inch
+     */
+    readonly width?: number;
+    /**
+     * Placeholder height (`w:object/@w:dyaOrig` + `v:shape` style).
+     * @defaultValue 1 inch
+     */
+    readonly height?: number;
+    /**
+     * Display a placeholder icon instead of the object content
+     * (`@DrawAspect` `Icon` vs `Content`). The library never renders icons;
+     * with no icon bytes (TASK-8056) Word re-renders the placeholder on open
+     * (program GO decision Q3). Product reference XML for linked icons
+     * commonly uses `Icon`.
+     * @defaultValue `false` (content)
+     */
+    readonly displayAsIcon?: boolean;
+    /**
+     * Alternative text (`v:shape/@alt`), e.g. a friendly object name.
+     */
+    readonly name?: string;
+    /**
+     * Extended description stored as `v:shape/@title` (and on
+     * `v:imagedata/@o:title` when {@link iconBytes} is supplied).
+     */
+    readonly description?: string;
+    /**
+     * Icon/preview image bytes (TASK-8056). Must sniff as PNG or JPEG
+     * (`image/png` / `image/jpeg`). When set, the library writes a media
+     * part under `/word/media/`, an image relationship, and
+     * `v:imagedata/@r:id` (ECMA-376-4 §19.2.2.20; ECMA-376-1 §15.2.14).
+     * Does **not** by itself force `@DrawAspect="Icon"` — use
+     * {@link displayAsIcon} for that (program GO Q3). Empty or non-image
+     * bytes throw `content/invalid-ole-object`. Never rendered or executed.
+     */
+    readonly iconBytes?: Uint8Array;
+    /**
+     * Content type for the embedding part. Omit for the default
+     * `application/vnd.openxmlformats-officedocument.oleObject` (ECMA-376-1
+     * §15.2.10 permits any content type). Embed path only; ignored for links
+     * (no part is created). The value is stored as given; the library does
+     * not verify it against the bytes.
+     */
+    readonly contentType?: string;
+}
+/**
+ * Author one embedded or linked OLE object and append it to the paragraph
+ * (receiver-owns R2.1; one statement R3.2).
+ *
+ * **Embed path (TASK-8054):** registers payload bytes with the document
+ * catalog at append (pending-relationship pattern, images/ink precedent);
+ * the embedding part `word/embeddings/oleObject{N}.bin`, its main-document
+ * relationship, and the content-type Override are allocated at save.
+ *
+ * **Link path (TASK-8055):** registers an external target string only —
+ * no package part. Save allocates a Main-WordDocument oleObject relationship
+ * with `TargetMode="External"` using the transitional relationship type
+ * (never the Office 2019 long-path type). The target is **never fetched
+ * or opened** (`.agent/policies/security.md`).
+ *
+ * Returns the created {@link OleObject} view (`relationshipId` empty until
+ * the first save materializes it).
+ *
+ * @example
+ * ```ts
+ * // Embed
+ * const embedded = paragraph.appendOleObject({
+ *   progId: 'Excel.Sheet.12',
+ *   bytes: workbookBytes,
+ *   width: (75.35),
+ *   height: (49.4),
+ *   displayAsIcon: true,
+ * });
+ *
+ * // Link (external target string only — never fetched)
+ * const linked = paragraph.appendOleObject({
+ *   progId: 'Excel.Sheet.12',
+ *   linkTarget: 'C:\\\\Data\\\\report.xlsx',
+ *   updateMode: OleUpdateMode.OnCall,
+ *   lockedField: true,
+ *   fieldCodes: '\\\\f 0',
+ *   displayAsIcon: true,
+ * });
+ * ```
+ *
+ * @throws DocxError `content/invalid-ole-object` on invalid options
+ * (missing `progId`, missing payload/target, link-only fields on embed,
+ * non-positive size).
+ * @throws DocxError `feature/not-registered` when the module is not
+ * registered before load.
+ * @throws DetachedObjectError when the paragraph is not in a document.
+ *
+ * @private
+ */
+export declare function appendOleObjectToParagraph(paragraph: Paragraph, options: AppendOleObjectOptions): OleObject;
+/**
+ * Remove an OLE object run from its paragraph and drop the embedding part
+ * or external link relationship on the next save (GC parity with
+ * `paragraph.appendFeatureRunItem(OLE_OBJECT, object
+ * this paragraph.
+ *
+ * @private
+ */
+export declare function removeOleObject(document: WordDocument, paragraph: Paragraph, object: OleObject): void;
+/**
+ * Package catalog for a loaded document.
+ *
+ * @throws DocxError `feature/not-registered` when the module was not
+ * registered before load.
+ *
+ * @private
+ */
+export declare function oleObjectCatalog(document: WordDocument): OleObjectCatalog;