@adobe/ccweb-add-on-sdk-types 1.20.1 → 1.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/ccweb-add-on-sdk-types",
-  "version": "1.20.1",
+  "version": "1.22.0",
   "author": "Adobe",
   "license": "MIT",
   "description": "Type definitions for Adobe Creative Cloud Web Add-on SDK.",
@@ -40,7 +40,7 @@
   "dependencies": {
     "tslib": "2.7.0",
     "gl-matrix": "3.3.0",
-    "@swc/helpers": "0.5.12"
+    "@swc/helpers": "0.5.17"
   },
   "devDependencies": {
     "@types/node": "18.18.2",

package/sandbox/express-document-sdk.d.ts

@@ -22,7 +22,7 @@
  * SOFTWARE.
  ********************************************************************************/
 
-import { mat2d } from "gl-matrix";
+import type { mat2d } from "gl-matrix";
 
 /**
  * AddOnData class provides APIs to read, write, remove private metadata to a Node.
@@ -968,7 +968,7 @@ export declare class GridLayoutNode extends Node implements IRectangularNode {
      * Grid Cells are ordered by the y and then x position of their top left corner, i.e. left to right and top to bottom.
      * The children cannot be added or removed.
      */
-    get allChildren(): Readonly<Iterable<Node>>;
+    get allChildren(): Readonly<Iterable<GridCellNode>>;
     /**
      * The background fill of the GridLayout.
      */
@@ -1211,6 +1211,11 @@ export declare class MediaContainerNode extends Node {
  * (as well as its maskShape sibling node).
  */
 export declare abstract class MediaRectangleNode extends Node implements Readonly<IRectangularNode> {
+    /**
+     * Get {@link AddOnData} reference for managing private metadata attached to the media resource displayed by this node.
+     * The same media resource may be reused in multiple places in the document, and all share the same AddOnData state.
+     */
+    get mediaAddOnData(): AddOnData;
     /**
      * Current width of the "full frame" uncropped media, which may not be fully visible due to cropping/clipping by the
      * enclosing media container's maskShape. This size may be different from the original image/video size in pixels, but
@@ -1785,6 +1790,8 @@ declare enum SceneNodeType {
     mediaContainer = "MediaContainer",
     /** Type of MediaContainerNode's "media rectangle" child when it is holding an image */
     imageRectangle = "ImageRectangle",
+    /** Type of MediaContainerNode's "media rectangle" child when it is holding an unknown media type */
+    unknownMediaRectangle = "UnknownMediaRectangle",
     /** Type of PageNode */
     page = "Page",
     /** Type of ComplexShapeNode, representing a complex prepackaged shape with fill and stroke, that appears as a leaf node in the UI */
@@ -1857,7 +1864,7 @@ export declare type SolidColorStrokeWithOptionalType = Omit<SolidColorStroke, "t
 
 /**
  * A StandaloneTextNode represents a text display frame in the scenegraph. It displays an entire piece of text.
- * The StandaloneTextNode does not directly hold the text content and styles – instead it refers to a {@link TextContentModel}.
+ * The StandaloneTextNode does not directly hold the text content and styles – instead it refers to a {@link TextNodeContentModel}.
  *
  * To create new a single-frame piece of text, see {@link Editor.createText}.
  */
@@ -1968,11 +1975,10 @@ declare enum TextAlignment {
 }
 
 /**
- * Represents a complete piece of text content, which may be contained within a single {@link StandaloneTextNode} *or*
- * split across multiple {@link ThreadedTextNode} frames for display.
+ * TextContentModel is an abstract base class representing a complete piece of text content.
  * Use this model to get or modify the text string and the style ranges applied to it.
  */
-export declare class TextContentModel {
+export declare abstract class TextContentModel {
     /**
      * <InlineAlert slots="text" variant="warning"/>
      *
@@ -1987,14 +1993,6 @@ export declare class TextContentModel {
      * Comparing two models using `===` will always fail.
      */
     get id(): string;
-    /**
-     * Get ordered list of all {@link TextNode}s that display this text content in the scenegraph. The text content
-     * starts in the first  {@link ThreadedTextNode} "frame", and then flows into the second node once it has filled the first one. The ending of the
-     * text content may not be visible at all, if the last {@link ThreadedTextNode} "frame" is not large enough to accommodate it.
-     *
-     * If there are multiple {@link ThreadedTextNode}s, all of them must be configured to use {@link AreaTextLayout}.
-     */
-    get allTextNodes(): Readonly<Iterable<TextNode>>;
     /**
      * The complete text string, which may span multiple {@link ThreadedTextNode} "frames" in the scenegraph.
      */
@@ -2119,7 +2117,7 @@ declare enum TextLayout {
 /**
  * TextNode is an abstract base class representing text displayed in the scenegraph, regardless of whether it's a fully
  * self-contained {@link StandaloneTextNode} or one {@link ThreadedTextNode} "frame" of multiple in a larger flow. The
- * APIs on TextNode and its {@link TextContentModel} allow you to generically work with text without needing to know
+ * APIs on TextNode and its {@link TextNodeContentModel} allow you to generically work with text without needing to know
  * which of those subtypes you are dealing with.
  */
 export declare abstract class TextNode extends Node {
@@ -2172,12 +2170,12 @@ export declare abstract class TextNode extends Node {
      * fixed-size frame using {@link AreaTextLayout} does not fit all the (remaining) text.
      *
      * Note: When traversing the scenegraph in search of text content, bear in mind that multiple TextNodes may refer to the
-     * same single {@link TextContentModel}; this can give the impression that the same text is duplicated multiple times when it is
-     * not. Use {@link TextContentModel}.id to determine whether a given piece of text content is unique or if it's already been
+     * same single {@link TextNodeContentModel}; this can give the impression that the same text is duplicated multiple times when it is
+     * not. Use {@link TextNodeContentModel}.id to determine whether a given piece of text content is unique or if it's already been
      * encountered before.
      *
      */
-    get fullContent(): TextContentModel;
+    get fullContent(): TextNodeContentModel;
     /**
      * Helper method to determine if the text is standalone.
      */
@@ -2197,14 +2195,14 @@ export declare abstract class TextNode extends Node {
      * The text string content which is partially *or* fully displayed in this TextNode "frame."
      * WARNING: If a piece of text content flows across several TextNodes, *each* TextNode's `text` getter will return
      * the *entire* text content string.
-     * @deprecated - Use the text getter on {@link TextContentModel} instead. Access it via `TextNode.fullContent.text`.
+     * @deprecated - Use the text getter on {@link TextNodeContentModel} instead. Access it via `TextNode.fullContent.text`.
      */
     get text(): string;
     /**
      * Sets the text content of the TextNode.
      * WARNING: If a piece of text content flows across several TextNodes,
      * *each* TextNode's `text` setter will sets the *entire* text content string.
-     * @deprecated - Use the text setter on {@link TextContentModel} instead. Access it via `TextNode.fullContent.text`.
+     * @deprecated - Use the text setter on {@link TextNodeContentModel} instead. Access it via `TextNode.fullContent.text`.
      */
     set text(textContent: string);
     /**
@@ -2227,6 +2225,22 @@ export declare abstract class TextNode extends Node {
     get layout(): Readonly<AutoWidthTextLayout | AutoHeightTextLayout | AreaTextLayout | UnsupportedTextLayout>;
 }
 
+/**
+ * Represents a complete piece of text content, which may be contained within a single {@link StandaloneTextNode} *or*
+ * split across multiple {@link ThreadedTextNode} frames for display.
+ * Use this model to get or modify the text string and the style ranges applied to it.
+ */
+export declare class TextNodeContentModel extends TextContentModel {
+    /**
+     * Get ordered list of all {@link TextNode}s that display this text content in the scenegraph. The text content
+     * starts in the first  {@link ThreadedTextNode} "frame", and then flows into the second node once it has filled the first one. The ending of the
+     * text content may not be visible at all, if the last {@link ThreadedTextNode} "frame" is not large enough to accommodate it.
+     *
+     * If there are multiple {@link ThreadedTextNode}s, all of them must be configured to use {@link AreaTextLayout}.
+     */
+    get allTextNodes(): Readonly<Iterable<TextNode>>;
+}
+
 /**
  * A range of text in a {@link TextContentModel}.
  */
@@ -2250,7 +2264,7 @@ export declare enum TextScriptStyle {
 /**
  * A ThreadedTextNode represents a text display frame in the scenegraph. It is a subset of longer text that flows across
  * multiple TextNode "frames". Because of this, the TextNode does not directly hold the text content and styles –
- * instead it refers to a {@link TextContentModel}, which may be shared across multiple ThreadedTextNode frames.
+ * instead it refers to a {@link TextNodeContentModel}, which may be shared across multiple ThreadedTextNode frames.
  *
  * APIs are not yet available to create multi-frame text flows.
  */

package/sandbox/index.d.ts

@@ -23,6 +23,6 @@
  ********************************************************************************/
 
 export * from "./express-document-sdk.js";
-export * from "./global.js";
+export type * from "./global.js";
 export * from "./add-on-sdk-document-sandbox.js";
 export { default } from "./add-on-sdk-document-sandbox.js";

package/ui/ui-sdk.d.ts

@@ -151,6 +151,10 @@ export declare enum AppEvent {
      * triggered when drag is complete on the currently dragged element.
      */
     dragend = "dragend",
+    /**
+     * triggered when drag is cancelled on the currently dragged element.
+     */
+    dragcancel = "dragcancel",
 
     /**
      * triggered when the document id is available in the application.
@@ -186,6 +190,7 @@ declare interface AppEventsTypeMap {
     [AppEvent.reset]: undefined;
     [AppEvent.dragstart]: AppDragStartEventData;
     [AppEvent.dragend]: AppDragEndEventData;
+    [AppEvent.dragcancel]: undefined;
 
     [AppEvent.documentIdAvailable]: DocumentIdAvailableEventData;
     [AppEvent.documentLinkAvailable]: DocumentLinkAvailableEventData;
@@ -215,6 +220,11 @@ export declare interface Application extends ApplicationBase {
      * Represents the active document of the host application
      */
     readonly document: Document_2;
+    /**
+     * @experimental - Experimental API
+     * Invoke command/actions in an add-on and handle response.
+     */
+    readonly command: Command;
     /**
      * OAuth 2.0 middleware for handling user authorization.
      */
@@ -661,6 +671,25 @@ export declare enum ColorPickerPlacement {
     right = "right"
 }
 
+/**
+ * @experimental - Experimental API
+ * Provides APIs to handle command execution in the add-on.
+ */
+export declare interface Command {
+    /**
+     * @experimental - Experimental API
+     * Register a handler for handling command execution in the add-on.
+     *
+     * _Note:_ This is similar to a JavaScript event handler.
+     * If there are multiple handlers registered for a command,
+     * each will be invoked when the host application triggers the command.
+     * In most of the cases, one handler per command is the way to go.
+     * @param command - Command triggered from the host application.
+     * @param handler - Handler for command execution.
+     */
+    register(command: string, handler: (params: Record<string, unknown>) => unknown): void;
+}
+
 declare namespace Constants {
     export {
         Range_2 as Range,
@@ -860,15 +889,15 @@ declare interface Document_2 {
     /**
      * Add image/Ps/Ai files to the current page
      */
-    addImage(blob: Blob, attributes?: MediaAttributes): Promise<void>;
+    addImage(blob: Blob, attributes?: MediaAttributes, importAddOnData?: ImportAddOnData): Promise<void>;
     /**
      * Add GIF files to the current page
      */
-    addAnimatedImage(blob: Blob, attributes?: MediaAttributes): Promise<void>;
+    addAnimatedImage(blob: Blob, attributes?: MediaAttributes, importAddOnData?: ImportAddOnData): Promise<void>;
     /**
      * Add video to the current page
      */
-    addVideo(blob: Blob, attributes?: MediaAttributes): Promise<void>;
+    addVideo(blob: Blob, attributes?: MediaAttributes, importAddOnData?: ImportAddOnData): Promise<void>;
     /**
      * Add audio to the current page
      */
@@ -882,6 +911,11 @@ declare interface Document_2 {
      * Get metadata of all or range of pages of the document
      */
     getPagesMetadata(options: PageMetadataOptions): Promise<PageMetadata[]>;
+    /**
+     * @experimental - Experimental API
+     * Get the currently selected page ids.
+     */
+    getSelectedPageIds(): Promise<string[]>;
     /**
      * Get document id
      */
@@ -913,7 +947,7 @@ declare interface Document_2 {
      */
     runPrintQualityCheck(options: PrintQualityCheckOptions): void;
 }
-export { Document_2 as Document };
+export type { Document_2 as Document };
 
 /**
  * The payload data sent when the document's export permission status changes in review and approval workflow.
@@ -1068,6 +1102,10 @@ export declare enum EntrypointType {
      * Widget entrypoint type.
      */
     WIDGET = "widget",
+    /**
+     * Command entrypoint type.
+     */
+    COMMAND = "command",
     /**
      * Script entrypoint type.
      * add-ons with script entrypoint type can use only the document sandbox APIs.
@@ -1188,6 +1226,24 @@ export declare enum FrameRate {
     fps60 = 60
 }
 
+/**
+ * Represents the add-on data for a node.
+ * Note: This support is not present for PSD/AI assets.
+ */
+export declare interface ImportAddOnData {
+    /**
+     * The node add-on data which will persist on the image frame even if the image content is replaced with a
+     * different one. This data can be accessed later via the MediaContainerNode.addOnData API.
+     */
+    nodeAddOnData?: Record<string, string>;
+    /**
+     * The media add-on data which will reset if the image is replaced with a different one. All copies of the
+     * same image in the document will share the same mediaAddOnData. This data can be accessed later via the
+     * MediaRectangleNode.mediaAddOnData API.
+     */
+    mediaAddOnData?: Record<string, string>;
+}
+
 /**
  * Type of input dialog data passed from the add-on.
  */
@@ -1685,6 +1741,13 @@ export declare interface PngRenditionOptions extends RenditionOptions {
     fileSizeLimitUnit?: FileSizeLimitUnit;
 }
 
+export declare interface PptxRenditionOptions extends RenditionOptions {
+    /**
+     * PPTX rendition format
+     */
+    format: RenditionFormat.pptx;
+}
+
 /**
  * @experimental - Experimental API
  * Options for running print quality check
@@ -1818,7 +1881,11 @@ export declare enum RenditionFormat {
     /**
      * PDF format
      */
-    pdf = "application/pdf"
+    pdf = "application/pdf",
+    /**
+     * PPTX format
+     */
+    pptx = "application/vnd.openxmlformats-officedocument.presentationml.presentation"
 }
 
 /**
@@ -1912,7 +1979,11 @@ export declare enum RuntimeType {
     /**
      * Add-On's document model sandbox - JS runtime that hosts add-on code that has direct access to the full model.
      */
-    documentSandbox = "documentSandbox"
+    documentSandbox = "documentSandbox",
+    /**
+     * Runtime that hosts the add-on command logic.
+     */
+    command = "command"
 }
 
 /**
@@ -2072,5 +2143,4 @@ export declare enum VideoResolution {
     custom = "custom"
 }
 
-export { };
-
+export {};