@adobe/ccweb-add-on-sdk-types 1.10.0 → 1.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/ccweb-add-on-sdk-types",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "author": "Adobe",
   "license": "MIT",
   "description": "Type definitions for Adobe Creative Cloud Web Add-on SDK.",

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

@@ -22,8 +22,6 @@
  * SOFTWARE.
  ********************************************************************************/
 
-/// <reference types="gl-matrix/index.js" />
-
 import { mat2d } from "gl-matrix";
 
 /**
@@ -32,61 +30,31 @@ import { mat2d } from "gl-matrix";
  */
 export declare class AddOnData {
     /**
-     * <InlineAlert slots="text" variant="warning"/>
-     *
-     * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
-     *
-     * @experimental
      * Sets a private metadata entry on the node.
      * @param key - The key for the private metadata entry.
      * @param value - The value for the private metadata entry.
      */
     setItem(key: string, value: string): void;
     /**
-     * <InlineAlert slots="text" variant="warning"/>
-     *
-     * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
-     *
-     * @experimental
      * Retrieves the private metadata value for the specified key on the node.
      * @param key - The key of the private metadata entry to retrieve.
      * @returns The value of the private metadata entry.
      */
     getItem(key: string): string | undefined;
     /**
-     * <InlineAlert slots="text" variant="warning"/>
-     *
-     * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
-     *
-     * @experimental
      * Removes a single private metadata entry on the node.
      * @param key - The key of the private metadata entry to remove.
      */
     removeItem(key: string): void;
     /**
-     * <InlineAlert slots="text" variant="warning"/>
-     *
-     * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
-     *
-     * @experimental
      * Clears all private metadata entries on the node.
      */
     clear(): void;
     /**
-     * <InlineAlert slots="text" variant="warning"/>
-     *
-     * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
-     *
-     * @experimental
      * @returns an array of all keys for the private metadata entries on the node.
      */
     keys(): string[];
     /**
-     * <InlineAlert slots="text" variant="warning"/>
-     *
-     * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
-     *
-     * @experimental
      * @returns an object with the remaining quota for private metadata on the node for this add-on.
      * The object contains the following properties:
      * - sizeInBytes: The remaining quota size in bytes (maximum 3KB).
@@ -124,6 +92,7 @@ declare interface ApiModuleExport {
     constants: unknown;
     colorUtils: ExpressColorUtils;
     fonts: ExpressFonts;
+    viewport: ExpressViewport;
 }
 
 /**
@@ -157,7 +126,7 @@ declare enum ArrowHeadType {
 
 /**
  * ArtboardList represents an ordered list of ArtboardNodes arranged in a timeline sequence, where they are called "scenes."
- * All items in the list are children of a single PageNode.
+ * All items in the list are children of a single {@link PageNode}.
  *
  * ArtboardList also provides APIs for adding/removing artboards from the page. ArtboardList is never empty: it is illegal to
  * remove the last remaining artboard from the list.
@@ -175,8 +144,11 @@ export declare class ArtboardList extends RestrictedItemList<ArtboardNode> {
 
 /**
  * An ArtboardNode represents an artboard object in the scenegraph. All user visual content must be contained on an artboard.
+ * Artboards are always contained on a {@link PageNode}; when a page contains multiple artboards, the artboards represent
+ * "scenes" in a linear timeline sequence.
+ *
+ * To create a new artboard, see {@link ArtboardList.addArtboard}.
  *
- * When multiple artboards exist on a page, the artboards represent "scenes" in a linear timeline sequence.
  * Please note that creating and deleting an artboard in a single frame will crash the editor.
  */
 export declare class ArtboardNode extends VisualNode implements IRectangularNode, ContainerNode {
@@ -246,12 +218,28 @@ export declare class AvailableFont extends BaseFont {
  * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
  *
  * @experimental
- * Base character styles that can be applied to a range of characters.
+ * Base character styles that can be applied to any range of characters.
+ * Excludes font style, which differs between the getter-oriented {@link CharacterStyles} interface and the
+ * setter-oriented {@link CharacterStylesInput}.
  */
 declare interface BaseCharacterStyles {
+    /**
+     * Size of the text in points.
+     */
     fontSize: number;
+    /**
+     * Text color.
+     */
     color: Color;
-    tracking: number;
+    /**
+     * Uniformly adjusts the letter spacing, aka character spacing. Specified as a delta relative to the font's default
+     * spacing, in units of 1/1000 em: positive values increase the spacing, negative values tighten the spacing, and 0
+     * leaves spacing at its default.
+     */
+    letterSpacing: number;
+    /**
+     * Adds an underline to text.
+     */
     underline: boolean;
 }
 
@@ -301,11 +289,6 @@ declare abstract class BaseFont {
  */
 export declare class BaseNode {
     /**
-     * <InlineAlert slots="text" variant="warning"/>
-     *
-     * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
-     *
-     * @experimental
      * Get {@link AddOnData} reference for managing the private metadata on this node for this add-on.
      */
     get addOnData(): AddOnData;
@@ -349,6 +332,47 @@ export declare class BaseNode {
     removeFromParent(): void;
 }
 
+/**
+ * <InlineAlert slots="text" variant="warning"/>
+ *
+ * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
+ *
+ * @experimental
+ * BaseParagraphListStyle interface represents common properties shared between ordered and unordered list types.
+ */
+declare interface BaseParagraphListStyle {
+    /** A value from 0-8 that specifies indent/nesting level. Default is 0 if not provided. */
+    indentLevel?: number;
+}
+
+/**
+ * <InlineAlert slots="text" variant="warning"/>
+ *
+ * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
+ *
+ * @experimental
+ * Base paragraph styles that can be applied to an entire paragraph atomically.
+ * Excludes list style settings, which differ between the getter-oriented {@link ParagraphStyles} interface and the
+ * setter-oriented {@link ParagraphStylesRangeInput}.
+ */
+declare interface BaseParagraphStyles {
+    /**
+     * Space before paragraph (in points). It does not affect the first paragraph. It is additive to previous paragraph's spaceAfter
+     * (adjacent spacing does not merge/collapse together).
+     */
+    spaceBefore: number;
+    /**
+     * Space after paragraph (in points). It does not affect the last paragraph. It is additive to the next paragraph's spaceBefore
+     * (adjacent spacing does not merge/collapse together).
+     */
+    spaceAfter: number;
+    /**
+     * Spacing between lines, aka leading, expressed as a multiple of the font size's default spacing - ex. 1.5 = 150% of normal.
+     * It only affects the space *between* lines, not the space above the first line or below the last line.
+     */
+    lineSpacing: number;
+}
+
 /**
  * Represents a bitmap image resource. Use {@link Editor.loadBitmapImage} to create a BitmapImage, and then {@link Editor.createImageContainer}
  * to display it in the document by creating a MediaContainerNode structure.
@@ -415,7 +439,8 @@ declare enum BlendMode {
  * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
  *
  * @experimental
- * Text styles of a range of characters, even a short span like a single word.
+ * Text styles that can be applied to any range of characters, even a short span like a single word. (Contrast with
+ * ParagraphStyles, which must be applied to an entire paragraph atomically).
  */
 export declare interface CharacterStyles extends BaseCharacterStyles {
     font: Font;
@@ -427,7 +452,11 @@ export declare interface CharacterStyles extends BaseCharacterStyles {
  * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
  *
  * @experimental
- * Input shape of the applyCharacterStyle API.
+ * Variant of {@link CharacterStyles} with all style fields optional, used for applyCharacterStyles(). When using that API,
+ * any fields not specified are left unchanged, preserving the text's existing styles.
+ *
+ * If specified, the font must be of the {@link AvailableFont} type – one that is guaranteed to be available for the current
+ * user to edit with.
  */
 export declare interface CharacterStylesInput extends Partial<BaseCharacterStyles> {
     font?: AvailableFont;
@@ -439,7 +468,10 @@ export declare interface CharacterStylesInput extends Partial<BaseCharacterStyle
  * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
  *
  * @experimental
- * Output shape of the characterStyleRange getter.
+ * A set of {@link CharacterStyles} along with the range of characters they apply to. Seen in the characterStyleRanges getter.
+ *
+ * Note that fonts returned by the getter are *not* guaranteed to be ones the user has rights to edit with, even though they
+ * are visible in the document.
  */
 export declare interface CharacterStylesRange extends CharacterStyles, StyleRange {}
 
@@ -449,7 +481,11 @@ export declare interface CharacterStylesRange extends CharacterStyles, StyleRang
  * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
  *
  * @experimental
- * Input shape of the characterStyleRange setter.
+ * Variant of {@link CharacterStylesRange} with all style fields optional, along with the range of characters they apply to.
+ * Used for the characterStyleRanges setter. When invoking the setter, any fields not specified are reset to their defaults.
+ *
+ * If specified, the font must be of the {@link AvailableFont} type – one that is guaranteed to be available for the current
+ * user to edit with.
  */
 export declare interface CharacterStylesRangeInput extends CharacterStylesInput, StyleRange {}
 
@@ -554,14 +590,34 @@ export declare interface ContainerNode extends VisualNode {
  * Contains the user's current selection state, indicating the content they are focused on.
  */
 export declare class Context {
+    /**
+     * Registers a handler for editor events such as selection change.
+     * The registered callback will be invoked when the specified event occurs.
+     * Note: Do not attempt to make changes to the document in response to a selection change callback because it may destabilize the application.
+     * @param eventName - an editor event name.
+     * @param callback - a callback to be registered for an editor event.
+     * @returns a unique ID for the registered event handler.
+     */
+    on(eventName: EditorEvent, callback: EditorEventHandler): EventHandlerId;
+    /**
+     * Unregisters handlers for editor events like selection change.
+     * @param eventName - an editor event name.
+     * @param handlerId - a unique ID returned by `editor.context.on` API.
+     * Callback that was previously registered will be removed and will no more be invoked when the event occurs.
+     */
+    off(eventName: EditorEvent, handlerId: EventHandlerId): void;
     /**
      * @returns the current selection. Nodes that are locked or otherwise non-editable are never included in the selection.
      */
     get selection(): readonly Node[];
     /**
-     * Sets the current selection, automatically ensuring these rules are met:
-     * - Nodes must be within the current artboard (others are filtered out).
-     * - A node cannot be selected at the same time as its ancestor (descendants are filtered out).
+     * Sets the current selection to an array of {@link Node}.
+     * Accepts a single node as a shortcut for a length-1 array `[node]` or
+     * `undefined` as a shortcut for `[]`, which clears the selection.
+     *
+     * Only node(s) that meet the following criteria can be selected:
+     * - Nodes must be within the current artboard (nodes outside the active artboard are filtered out).
+     * - A node cannot be selected if its ancestor is also selected (descendants are filtered out).
      * - Locked nodes are filtered out (but will still be included in selectionIncludingNonEditable).
      */
     set selection(nodes: Node | readonly Node[] | undefined);
@@ -585,32 +641,6 @@ export declare class Context {
      * @returns The currently viewed page.
      */
     get currentPage(): PageNode;
-    /**
-     * <InlineAlert slots="text" variant="warning"/>
-     *
-     * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
-     *
-     * @experimental
-     * Registers a handler for editor events such as selection change.
-     * The registered callback will be invoked when the specified event occurs.
-     * Note: Do not attempt to make changes to the document in response to a selection change callback because it may destabilize the application.
-     * @param eventName - an editor event name.
-     * @param callback - a callback to be registered for an editor event.
-     * @returns a unique ID for the registered event handler.
-     */
-    on(eventName: EditorEvent, callback: EditorEventHandler): EventHandlerId;
-    /**
-     * <InlineAlert slots="text" variant="warning"/>
-     *
-     * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
-     *
-     * @experimental
-     * Unregisters handlers for editor events like selection change.
-     * @param eventName - an editor event name.
-     * @param handlerId - a unique ID returned by `editor.context.on` API.
-     * Callback that was previously registered will be removed and will no more be invoked when the event occurs.
-     */
-    off(eventName: EditorEvent, handlerId: EventHandlerId): void;
 }
 
 /**
@@ -694,7 +724,7 @@ export declare class Editor {
      * render as a gray placeholder on other clients until it has been uploaded to DCX and then downloaded by those clients.
      * This local client will act as having unsaved changes until the upload has finished.
      *
-     * @param bitmapData - BitmapImage resource (e.g. returned from loadBitmapImage()).
+     * @param bitmapData - BitmapImage resource (e.g. returned from {@link loadBitmapImage}).
      * @param options - Additional configuration:
      *      - initialSize - Size the image is displayed at. Must have the same aspect ratio as bitmapData. Defaults to the
      *        size the image would be created at by a UI drag-drop gesture (typically the image's full size, but scaled down
@@ -760,11 +790,6 @@ export declare class Editor {
 export declare const editor: ExpressEditor;
 
 /**
- * <InlineAlert slots="text" variant="warning"/>
- *
- * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
- *
- * @experimental
  * This enum represents the supported editor events.
  */
 export declare enum EditorEvent {
@@ -772,17 +797,14 @@ export declare enum EditorEvent {
 }
 
 /**
- * <InlineAlert slots="text" variant="warning"/>
- *
- * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
- *
- * @experimental
  * This type represents function signature for the editor event handler callback.
  */
 export declare type EditorEventHandler = () => void;
 
 /**
- * An EllipseNode represents an ellipse object in the scenegraph.
+ * An EllipseNode represents an ellipse or circle shape in the scenegraph.
+ *
+ * To create new ellipse, see {@link Editor.createEllipse}.
  */
 export declare class EllipseNode extends FillableNode {
     /**
@@ -806,11 +828,6 @@ export declare class EllipseNode extends FillableNode {
 }
 
 /**
- * <InlineAlert slots="text" variant="warning"/>
- *
- * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
- *
- * @experimental
  * This type represents unique id of each event handler callback that is registered.
  */
 export declare type EventHandlerId = string;
@@ -834,10 +851,13 @@ declare class ExpressFonts extends Fonts {}
 export declare class ExpressRootNode extends BaseNode {
     /**
      * The pages of the document. All visual content is contained on artboards within the pages.
+     * To create a new page, see {@link PageList.addPage}.
      */
     get pages(): PageList;
 }
 
+declare class ExpressViewport extends Viewport {}
+
 /**
  * Base interface representing any fill in the scenegraph. See {@link FillableNode}.
  * Currently, you can only create {@link ColorFill}s, but you might encounter
@@ -933,6 +953,8 @@ export declare class GridCellNode extends MediaContainerNode {}
 /**
  * A GridLayoutNode represents a grid layout in the scenegraph. The GridLayoutNode is used to create
  * a layout grid that other content can be placed into.
+ *
+ * APIs to create a new grid layout are not yet available.
  */
 export declare class GridLayoutNode extends Node implements Readonly<IRectangularNode> {
     /**
@@ -959,6 +981,8 @@ export declare class GridLayoutNode extends Node implements Readonly<IRectangula
 /**
  * A GroupNode represents a Group object in the scenegraph, which has a collection of generic children as well as a separate,
  * optional vector mask child.
+ *
+ * To create new group, see {@link Editor.createGroup}.
  */
 export declare class GroupNode extends Node implements ContainerNode {
     /**
@@ -997,6 +1021,9 @@ declare interface IFillableNode {
  * ImageRectangleNode is a rectangular node that displays the image media part of a MediaContainerNode. It can only exist
  * within that container parent. Cropping can be adjusted by changing this media's position/rotation (as well as its mask
  * shape sibling node).
+ *
+ * ImageRectangleNodes cannot be created directly; use {@link Editor.createImageContainer} to create the entire
+ * container structure together.
  */
 export declare class ImageRectangleNode extends Node implements Readonly<IRectangularNode> {
     /**
@@ -1077,7 +1104,9 @@ export declare class ItemList<T extends ListItem> extends RestrictedItemList<T>
 }
 
 /**
- * A LineNode represents a simple line object in the scenegraph – a single straight-line segment.
+ * A LineNode represents a simple vector line in the scenegraph – a single straight-line segment.
+ *
+ * To create a new line, see {@link Editor.createLine}.
  */
 export declare class LineNode extends StrokableNode {
     static readonly DEFAULT_START_X = 0;
@@ -1148,6 +1177,9 @@ export declare interface ListItem {}
  * A MediaContainerNode is a multi-node construct that displays media (such as images or video) with optional cropping and
  * clipping to a shape mask. The underlying media asset is always rectangular, but the final appearance of this node is
  * determined by the maskShape which is not necessarily a rectangle.
+ *
+ * To create new media container for a bitmap image, see {@link Editor.createImageContainer}. APIs for creating a
+ * container with other content, such as videos, are not yet available.
  */
 export declare class MediaContainerNode extends Node {
     /**
@@ -1261,7 +1293,9 @@ declare class Node extends VisualNode {
     get transformMatrix(): mat2d;
     /**
      * The node's lock/unlock state. Locked nodes are excluded from the selection (see {@link Context.selection}), and
-     * cannot be edited by the user unless they are unlocked first.
+     * cannot be edited by the user in the UI unless they are unlocked first. Operations on locked nodes using the API
+     * are permitted. However, please consider if modifying a locked node would align with user expectations
+     * before using the API to make changes to locked nodes.
      */
     get locked(): boolean;
     set locked(locked: boolean);
@@ -1274,10 +1308,61 @@ declare class Node extends VisualNode {
 }
 export { Node as Node };
 
+/**
+ * <InlineAlert slots="text" variant="warning"/>
+ *
+ * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
+ *
+ * @experimental
+ * Numbering types used to display ordered lists: 1, A, a, I, i 01, 001.
+ */
+export declare enum OrderedListNumbering {
+    numeric = 1,
+    uppercaseAlpha = 2,
+    lowercaseAlpha = 3,
+    uppercaseRomanNum = 4,
+    lowercaseRomanNum = 5,
+    singleZeroPrefixNumeric = 7,
+    doubleZeroPrefixNumeric = 8
+}
+
+/**
+ * <InlineAlert slots="text" variant="warning"/>
+ *
+ * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
+ *
+ * @experimental
+ * OrderedListStyle represents the style of an ordered list.
+ */
+export declare type OrderedListStyle = Required<OrderedListStyleInput>;
+
+/**
+ * <InlineAlert slots="text" variant="warning"/>
+ *
+ * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
+ *
+ * @experimental
+ * Interface for specifying an ordered list style, such as a numbered list.
+ */
+export declare interface OrderedListStyleInput extends BaseParagraphListStyle {
+    type: ParagraphListType.ordered;
+    /**
+     * The numbering style to use. If undefined, it defaults to a different type depending on the paragraph's indent level.
+     * The defaults for increasing indent are 1, a, i, I, and then they repeat.
+     * These markers and the prefix/postfix strings (if any) are displayed using the same font as the start of the
+     * paragraph's text content.
+     */
+    numbering?: OrderedListNumbering;
+    /** Additional string to display before each sequence number/letter, e.g. "(" */
+    prefix?: string;
+    /** Additional string to display after each sequence number/letter, e.g. ")" or "." */
+    postfix?: string;
+}
+
 /**
  * PageList represents an ordered list of PageNodes, all of which are children of the root node of the document's "scenegraph"
- * artwork tree. A page contains one or more artboards, representing "scenes" in a linear timeline sequence. Those artboards
- * in turn contain all the visual content of the document.
+ * artwork tree (see {@link ExpressRootNode}). A page contains one or more artboards, representing "scenes" in a linear timeline
+ * sequence. Those artboards, in turn, contain all the visual content of the document.
  *
  * PageList also provides APIs for adding/removing pages from the document. PageList is never empty: it is illegal to
  * remove the last remaining page from the list.
@@ -1294,12 +1379,16 @@ export declare class PageList extends RestrictedItemList<PageNode> {
 }
 
 /**
- * A PageNode represents a page in the document. A page contains one or more artboards, representing "scenes" in a linear
- * timeline sequence. Those artboards in turn contain all the visual content of the document.
+ * A PageNode represents a page in the document, a child of the root node of the document's "scenegraph" artwork tree
+ * (see {@link ExpressRootNode}). A page contains one or more artboards, representing "scenes" in a linear timeline
+ * sequence. Those artboards, in turn, contain all the visual content of the document.
+ *
+ * To create new pages, see {@link PageList.addPage}.
  */
 export declare class PageNode extends BaseNode implements Readonly<IRectangularNode> {
     /**
      * The artboards or "scenes" of a page, ordered by timeline sequence.
+     * To create new artboards, see {@link ArtboardList.addArtboard}.
      */
     get artboards(): ArtboardList;
     /**
@@ -1329,8 +1418,73 @@ export declare class PageNode extends BaseNode implements Readonly<IRectangularN
 }
 
 /**
- * A PathNode represents a generic vector path shape in the scenegraph. Paths cannot be created or edited through this API
+ * <InlineAlert slots="text" variant="warning"/>
+ *
+ * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
+ *
+ * @experimental
+ * Indicates list type: see {@link UnorderedListStyleInput} and {@link OrderedListStyleInput}.
+ */
+export declare enum ParagraphListType {
+    unordered = 0,
+    ordered = 1
+}
+
+/**
+ * <InlineAlert slots="text" variant="warning"/>
+ *
+ * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
+ *
+ * @experimental
+ * Text styles that must be applied to an entire paragraph atomically. (Contrast with CharacterStyles which can be applied to
+ * any range of characters, even a short span like one single word).
+ */
+export declare interface ParagraphStyles extends BaseParagraphStyles {
+    list?: OrderedListStyle | UnorderedListStyle;
+}
+
+/**
+ * <InlineAlert slots="text" variant="warning"/>
+ *
+ * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
+ *
+ * @experimental
+ * The variant of {@link ParagraphStyles} with all optional style fields is used to apply ParagraphStyles(). When using that API,
+ * any fields not specified are left unchanged, preserving the text's existing styles.
+ */
+export declare interface ParagraphStylesInput extends Partial<BaseParagraphStyles> {
+    list?: OrderedListStyleInput | UnorderedListStyleInput;
+}
+
+/**
+ * <InlineAlert slots="text" variant="warning"/>
+ *
+ * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
+ *
+ * @experimental
+ * A set of {@link ParagraphStyles} and the text range they apply to. It is seen in the paragraphStyleRanges getter.
+ */
+export declare interface ParagraphStylesRange extends ParagraphStyles, StyleRange {}
+
+/**
+ * <InlineAlert slots="text" variant="warning"/>
+ *
+ * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
+ *
+ * @experimental
+ * A variant of {@link ParagraphStylesRange} with all style fields optional and the text range they apply to. Used for the
+ * paragraphStyleRanges setter. When invoking the setter, any fields not specified are reset to their defaults.
+ *
+ * Paragraphs are separated by newline characters (`\n`). The ranges specified here should align with
+ * those boundaries.
+ */
+export declare interface ParagraphStylesRangeInput extends ParagraphStylesInput, StyleRange {}
+
+/**
+ * A PathNode represents a generic vector path shape in the scenegraph. Paths cannot be edited through this API
  * yet, only read.
+ *
+ * To create new paths, see {@link Editor.createPath}.
  */
 export declare class PathNode extends FillableNode {
     /**
@@ -1403,7 +1557,7 @@ export declare class ReadOnlyItemList<T extends ListItem> {
     /**
      * All items in the list, as a static array. Mutations that occur later are not reflected in an array returned earlier.
      */
-    toArray(): Readonly<T[]>;
+    toArray(): readonly T[];
 }
 
 declare interface Rect {
@@ -1419,7 +1573,9 @@ export declare interface RectangleGeometry {
 }
 
 /**
- * A RectangleNode represents a rectangle object in the scenegraph.
+ * A RectangleNode represents a rectangle shape in the scenegraph.
+ *
+ * To create a new rectangle, see {@link Editor.createRectangle}.
  */
 export declare class RectangleNode extends FillableNode implements IRectangularNode {
     /**
@@ -1733,7 +1889,13 @@ export declare class TextContentModel {
      * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
      *
      * @experimental
-     * The character style ranges of this text content.
+     * The character styles are applied to different ranges of this text content. When setting character styles, any style
+     * properties that are not provided are reset to their defaults (contrast to {@link applyCharacterStyles} which
+     * preserves the text's existing styles for any fields not specified). When *getting* styles, all fields are always
+     * provided.
+     *
+     * Note: existing fonts used in the document, returned by this getter, are not guaranteed to be ones the current user
+     * has rights to edit with. The *setter* only accepts the AvailableFont type which has been verified to be usable.
      */
     get characterStyleRanges(): readonly CharacterStylesRange[];
     set characterStyleRanges(styles: readonly CharacterStylesRangeInput[]);
@@ -1743,11 +1905,41 @@ export declare class TextContentModel {
      * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
      *
      * @experimental
-     * Apply one or more styles to the characters in the given range, leaving other styles in this range unchanged. Does
-     * not modify any styles in the text outside this range.
+     * The styles applied to different paragraphs of this text content.
+     */
+    get paragraphStyleRanges(): readonly ParagraphStylesRange[];
+    /**
+     * <InlineAlert slots="text" variant="warning"/>
+     *
+     * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
+     *
+     * @experimental
+     * Apply styles to different paragraphs of this text content. Any style properties that are not provided are reset to their defaults.
+     * When **getting** styles, all properties are always provided.
+     *
+     * Paragraphs are separated by newline characters (`\n`). The ranges specified here should align with
+     * those boundaries. If multiple ranges provided overlap a single paragraph, the first one to overlap is applied to the
+     * entire paragraph.
+     *
+     * @throws if the text content contains fonts unavailable to the current user and an ordered-list style is being applied.
+     */
+    set paragraphStyleRanges(styles: readonly ParagraphStylesRangeInput[]);
+    /**
+     * <InlineAlert slots="text" variant="warning"/>
+     *
+     * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
+     *
+     * @experimental
+     * Apply one or more styles to the characters in the given range, leaving any style properties that were not specified
+     * unchanged. Does not modify any styles in the text outside this range. Contrast to the {@link characterStyleRanges}
+     * setter, which specifies new style range(s) for the entire text at once, and resets any unspecified properties back to
+     * default styles.
+
      * @param styles - The styles to apply.
-     * @param range - The start and length of character sequence to which the styles should be applied.
-     * If not specified the styles will be applied to the entire piece of text content flow.
+     * @param range -The start and length of the character sequence to which the styles should be applied.
+     * The styles will be applied to the entire text content flow if not specified.
+     * If the specified range doesn't align well with the paragraph boundaries, the range will be expanded to cover the
+     * entire paragraphs, it overlaps.
      */
     applyCharacterStyles(
         styles: CharacterStylesInput,
@@ -1756,12 +1948,37 @@ export declare class TextContentModel {
             length: number;
         }
     ): void;
+    /**
+     * <InlineAlert slots="text" variant="warning"/>
+     *
+     * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
+     *
+     * @experimental
+     * Apply one or more styles to the paragraphs in the given range, leaving any style properties that were not specified
+     * unchanged. Does not modify any styles in the text outside this range. Contrast to the {@link paragraphStyleRanges}
+     * setter, which specifies new style range(s) for the entire text at once, and resets any unspecified properties back to
+     * default styles.
+
+     * @param styles - The styles to apply.
+     * @param range - The start and length of character sequence to which the styles should be applied.
+     * If not specified the styles will be applied to the entire piece of text content flow.
+     */
+    applyParagraphStyles(
+        styles: ParagraphStylesInput,
+        range?: {
+            start: number;
+            length: number;
+        }
+    ): void;
 }
 
 /**
  * A TextNode represents a text display frame in the scenegraph. It may display an entire piece of text, or sometimes just
  * 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 TextNodes.
+ * the text content and styles – instead it refers to a {@link TextContentModel}, which may be shared across multiple TextNode frames.
+ *
+ * To create new a single-frame piece of text, see {@link Editor.createText}. APIs are not yet available to create
+ * multi-frame text flows.
  */
 export declare class TextNode extends Node {
     /**
@@ -1773,6 +1990,7 @@ export declare class TextNode extends Node {
      * 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
      * encountered before.
+     *
      */
     get fullContent(): TextContentModel;
     /**
@@ -1833,10 +2051,11 @@ export declare class TextNode extends Node {
      * Sets the layout mode of the TextNode "frame."
      *
      * If this TextNode is part of a multi-frame text content flow, it must be configured to use {@link AreaTextLayout}. Other
-     * layout modes are only available for single-frame text.
+     * layout modes, except for {@link AreaTextLayout}, are only available for single-frame text.
      *
      * @throws if changing text layout to/from {@link TextType.magicFit} or {@link TextType.circular} layout when the text contains font(s) unavailable to the current user.
-     * @throws if TextNode is part of a multi-frame text content flow and the layout is not {@link AreaTextLayout}.
+     * @throws if {@link TextNode} is part of a multi-frame text content flow and the layout is not {@link AreaTextLayout}.
+     * @throws if {@link TextNode} is not a part of a multi-frame text content flow and the layout is {@link AreaTextLayout}.
      */
     set layout(layout: PointTextLayout | AutoHeightTextLayout | AreaTextLayout);
 }
@@ -1872,6 +2091,37 @@ export declare class UnavailableFont extends BaseFont {
  */
 export declare class UnknownNode extends Node {}
 
+/**
+ * <InlineAlert slots="text" variant="warning"/>
+ *
+ * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
+ *
+ * @experimental
+ * UnorderedListStyle represents the style of an unordered list.
+ */
+export declare type UnorderedListStyle = Required<UnorderedListStyleInput>;
+
+/**
+ * <InlineAlert slots="text" variant="warning"/>
+ *
+ * **IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`.
+ *
+ * @experimental
+ * Interface for specifying an unordered list style, such as a bullet list.
+ */
+export declare interface UnorderedListStyleInput extends BaseParagraphListStyle {
+    type: ParagraphListType.unordered;
+    /**
+     * Marker symbol to use. If undefined, it defaults to a different symbol depending on the paragraph's indent level.
+     * The defaults for increasing indent are: •, ◦, ◼, ◻, and then they repeat.
+     * Markers are always displayed using the default font (SourceSans3 Regular), regardless of the font(s) used in the
+     * paragraph's text content. A default marker is used instead if the default font does not support the symbol.
+     *
+     * Text or Unicode glyphs are accepted to represent the list marker.
+     */
+    marker?: string;
+}
+
 /**
  * <InlineAlert slots="text" variant="warning"/>
  *
@@ -1883,6 +2133,28 @@ export declare interface UnsupportedTextLayout {
     type: TextType.magicFit | TextType.circular;
 }
 
+/**
+ * Represents the area of the canvas that is currently visible on-screen.
+ */
+export declare class Viewport {
+    /**
+     * Adjusts the viewport to make the node's bounds visible on-screen, assuming all bounds are within the artboard bounds.
+     * Makes the node's {@link ArtboardNode} or {@link PageNode} visible if they were not already visible
+     * (which may result in {@link Context.selection} being cleared). It is strongly recommended
+     * to further draw user's attention to the node, set it as the {@link Context.selection} following this call.
+     *
+     * After this call, the value of {@link Context.insertionParent} will always be the node containing {@link ArtboardNode}.
+     *
+     * Note that the node might still not appear visible if:
+     *   - Its animation settings make it invisible at the beginning of the {@link ArtboardNode} "scene".
+     *   - It is obscured underneath other artwork in the z-order.
+     *   - It is hidden by a {@link GroupNode}'s mask or similar cropping.
+     */
+    bringIntoView(node: VisualNode): void;
+}
+
+export declare const viewport: ExpressViewport;
+
 /**
  * <InlineAlert slots="text" variant="warning"/>
  *

package/ui/ui-sdk.d.ts

@@ -238,7 +238,6 @@ declare interface ApplicationBase {
         dragOptions?: DragOptions
     ): DisableDragToDocument;
     /**
-     * @experimental - Experimental API
      * Register iframe with the add-on SDK.
      * @param element - HTMLIframeElement to be registered.
      * @returns UnregisterIframe - Callback to unregister iframe from the add-on SDK.
@@ -371,9 +370,34 @@ export declare enum AuthorizationStatus {
     POPUP_BLOCKED = "POPUP_BLOCKED",
     POPUP_CLOSED = "POPUP_CLOSED",
     POPUP_TIMEOUT = "POPUP_TIMEOUT",
-    FAILED = "FAILED"
+    FAILED = "FAILED",
+    IFRAME_LOAD_FAILED = "IFRAME_LOAD_FAILED"
 }
 
+/**
+ * Request parameters to authorize a user using OAuth 2.0 PKCE based authorization in an iframe.
+ */
+export declare type AuthorizeInsideIframeRequest = AuthorizationRequest & {
+    /**
+     * Relative position of the oauth iframe panel
+     */
+    position?: {
+        top: number;
+        left: number;
+    };
+    /**
+     * Offset from the right and bottom of the Iframe container when the size (windowSize) is not specified.
+     */
+    offset?: {
+        right: number;
+        bottom: number;
+    };
+    /**
+     * Flag to determine if the iframe panel needs to show a header.
+     */
+    showHeader?: boolean;
+};
+
 /**
  * Request parameters to initiate an OAuth 2.0 PKCE based authorization workflow,
  * where the Add-on developer is responsible for handling redirect to his/her owned Redirect URL.
@@ -712,6 +736,19 @@ declare interface Document_2 {
      * Get document name/title
      */
     title(): Promise<string>;
+    /**
+     * Import a Pdf to the document.
+     */
+    importPdf(blob: Blob, attributes: MediaAttributes): void;
+    /**
+     * Import a presentation to the document.
+     */
+    importPresentation(blob: Blob, attributes: MediaAttributes): void;
+    /**
+     * @experimental - Experimental API
+     * Run print quality check
+     */
+    runPrintQualityCheck(options: PrintQualityCheckOptions): void;
 }
 export { Document_2 as Document };
 
@@ -1065,6 +1102,12 @@ export declare interface OAuth {
      * @returns - {@link AuthorizationResult} Authorization result.
      */
     authorizeWithOwnRedirect(request: AuthorizeWithOwnRedirectRequest): Promise<AuthorizationResult>;
+    /**
+     * Authorize a user using OAuth 2.0 PKCE workflow in an iframe.
+     * @param request - {@link AuthorizeInsideIframeRequest} Payload with parameters to be used in the authorization workflow.
+     * @returns - {@link AuthorizationResponse} Response containing a ONE-TIME Authorization Code which can be used to obtain an access token.
+     */
+    authorizeInsideIframe(request: AuthorizeInsideIframeRequest): Promise<AuthorizationResponse>;
 }
 
 /**
@@ -1094,6 +1137,10 @@ export declare interface PageMetadata {
      * Whether page contains timelines
      */
     hasTemporalContent: boolean;
+    /**
+     * Whether the page is blank
+     */
+    isBlank?: boolean;
     /**
      * Pixels per inch of the page
      */
@@ -1102,21 +1149,16 @@ export declare interface PageMetadata {
      * Whether page is ready to print
      */
     isPrintReady?: boolean;
+    /**
+     * Template details of the page
+     */
+    templateDetails?: TemplateDetails;
 }
 
 /**
  * Options for fetching page metadata
  */
-export declare interface PageMetadataOptions {
-    /**
-     * Page range of the document to get the metadata
-     */
-    range: Range_2;
-    /**
-     * Ids of the pages (Only required if the range is "specificPages")
-     */
-    pageIds?: string[];
-}
+export declare interface PageMetadataOptions extends RangeOptions {}
 
 export declare interface PageRendition extends Rendition {
     /**
@@ -1311,6 +1353,12 @@ export declare interface PngRenditionOptions extends RenditionOptions {
     };
 }
 
+/**
+ * @experimental - Experimental API
+ * Options for running print quality check
+ */
+export declare interface PrintQualityCheckOptions extends RangeOptions {}
+
 /**
  * Takes a type and wraps it in a Promise, if it not already is one.
  * This is to avoid `Promise<Promise<T>>`.
@@ -1353,6 +1401,20 @@ declare enum Range_2 {
 }
 export { Range_2 as Range };
 
+/**
+ * Options for providing range of pages
+ */
+export declare interface RangeOptions {
+    /**
+     * Page range of the document
+     */
+    range: Range_2;
+    /**
+     * Ids of the pages (Only required if the range is "specificPages")
+     */
+    pageIds?: string[];
+}
+
 /**
  * Takes the raw type of a remote object or function in the other thread and returns the type as it is visible to
  * the local thread from the proxy return value of `Runtime.apiProxy()`.
@@ -1445,19 +1507,11 @@ export declare enum RenditionIntent {
     print = "print"
 }
 
-export declare interface RenditionOptions {
-    /**
-     * Range of the document to get the rendition
-     */
-    range: Range_2;
+export declare interface RenditionOptions extends RangeOptions {
     /**
      * Format of the rendition
      */
     format: RenditionFormat;
-    /**
-     * Ids of the pages (Only required if the range is "specificPages")
-     */
-    pageIds?: string[];
 }
 
 /**
@@ -1545,6 +1599,20 @@ export declare interface SearchAction extends PanelAction {
 
 export declare type SimpleDialogOptions = AlertDialogOptions | InputDialogOptions;
 
+/**
+ * Represents template data for a page
+ */
+export declare interface TemplateDetails {
+    /**
+     * Unique id of the template
+     */
+    id: string;
+    /**
+     * Creative intent of the template
+     */
+    creativeIntent?: string;
+}
+
 /**
  * Interface that contains methods and properties that are Application UI related.
  */
@@ -1566,7 +1634,6 @@ export declare interface UI {
      */
     readonly locales: string[];
     /**
-     * @experimental - Experimental API
      * Opens an Editor Panel
      * @param panel - one of {@link EditorPanel}
      * @param action - optional action to be performed on the panel {@link PanelAction}
@@ -1590,7 +1657,6 @@ declare type Unpromisify<P> = P extends Promise<infer T> ? T : P;
 declare type UnproxyOrClone<T> = T extends RemoteObject<ProxyMarked> ? Local<T> : T;
 
 /**
- * @experimental - Experimental API
  * Callback to unregister iframe from the add-on SDK.
  */
 declare type UnregisterIframe = () => void;