@canva/design 2.4.1 → 2.6.0

package/index.d.ts

@@ -358,7 +358,7 @@ export declare type ContentType = "richtext";
  * @public
  * Options for configuring where content in a design should be queried from.
  */
-declare type ContextOptions = {
+export declare type ContextOptions = {
   target: "current_page";
 };
 
@@ -383,6 +383,1503 @@ export declare type Coordinates = {
  */
 export declare const createRichtextRange: () => RichtextRange;
 
+/**
+ * @public
+ * Describes a part of a design.
+ */
+export declare type DesignContext = DesignContextOptions["type"];
+
+/**
+ * @public
+ * Options for configuring which part of a design to read.
+ */
+declare type DesignContextOptions = {
+  /**
+   * The type of context.
+   */
+  type: "current_page";
+};
+
+/**
+ * @public
+ * Provides methods for reading and updating the structure and content of a design.
+ */
+export declare namespace DesignEditing {
+  /**
+   * @public
+   * Options for creating an image fill in the element state builder
+   */
+  export type ImageFillOpts = {
+    /**
+     * The type of media.
+     */
+    type: "image";
+    /**
+     * A unique identifier that points to an image asset in Canva's backend.
+     */
+    imageRef: ImageRef;
+    /**
+     * If `true`, the image is flipped horizontally.
+     */
+    flipX?: boolean;
+    /**
+     * If `true`, the image is flipped vertically.
+     */
+    flipY?: boolean;
+  };
+  /**
+   * @public
+   * Options for creating a video fill in the element state builder
+   */
+  export type VideoFillOpts = {
+    /**
+     * The type of media.
+     */
+    type: "video";
+    /**
+     * A unique identifier that points to a video asset in Canva's backend.
+     */
+    videoRef: VideoRef;
+    /**
+     * If `true`, the video is flipped horizontally.
+     */
+    flipX?: boolean;
+    /**
+     * If `true`, the video is flipped vertically.
+     */
+    flipY?: boolean;
+  };
+  /**
+   * @public
+   * Options for creating a media fill in the element state builder
+   */
+  export type MediaContainerOpts = ImageFillOpts | VideoFillOpts;
+  /**
+   * @public
+   * Options for creating a fill in the element state builder
+   */
+  export type FillOpts =
+    | {
+        colorContainer: ColorContainerOpts;
+        mediaContainer?: MediaContainerOpts;
+      }
+    | {
+        colorContainer?: ColorContainerOpts;
+        mediaContainer: MediaContainerOpts;
+      };
+  /**
+   * @public
+   * Options for creating a fill of a shape in the element state builder
+   */
+  export type PathFillOpts =
+    | {
+        colorContainer: ColorContainerOpts;
+        mediaContainer?: MediaContainerOpts;
+        isMediaEditable?: boolean;
+      }
+    | {
+        colorContainer?: ColorContainerOpts;
+        mediaContainer: MediaContainerOpts;
+        isMediaEditable?: boolean;
+      };
+  /**
+   * @public
+   */
+  export type ColorContainerOpts = SolidFillState;
+  /**
+   * @public
+   * Options for creating a stroke in the element state builder
+   */
+  export type StrokeOpts = {
+    /**
+     * The weight (thickness) of the stroke.
+     *
+     * @remarks
+     * - Minimum: 0
+     * - Maximum: 100
+     */
+    weight: number;
+    /**
+     * The color of the stroke.
+     */
+    colorContainer: ColorContainerOpts;
+  };
+  /**
+   * @public
+   * Options for creating a shape path in the element state builder
+   */
+  export type PathOpts = {
+    d: string;
+    /**
+     * Describes how a fill is filled with color or media.
+     *
+     * @remarks
+     * If both `media` and `color` are defined, `media` takes precedence.
+     */
+    fill?: PathFillOpts;
+    /**
+     * The outline of the path.
+     */
+    stroke?: StrokeOpts;
+  };
+  /**
+   * @public
+   * Options for creating a rect element.
+   */
+  export type CreateRectElementOpts = {
+    /**
+     * The distance from the top edge of the container, in pixels.
+     *
+     * @remarks
+     * - The pixels are relative to their container.
+     * - Minimum: -32768
+     * - Maximum: 32767
+     */
+    top: number;
+    /**
+     * The distance from the left edge of the container, in pixels.
+     *
+     * @remarks
+     * - The pixels are relative to their container.
+     * - Minimum: -32768
+     * - Maximum: 32767
+     */
+    left: number;
+    /**
+     * A rotation, in degrees.
+     *
+     * @remarks
+     * - Minimum: -180
+     * - Maximum: 180
+     */
+    rotation?: number;
+    /**
+     * Transparency as a percentage.
+     *
+     * @remarks
+     * - Minimum: 0
+     * - Maximum: 1
+     */
+    transparency?: number;
+    /**
+     * A width, in pixels.
+     */
+    width: number;
+    /**
+     * A height, in pixels.
+     */
+    height: number;
+    /**
+     * Describes how a fill is filled with color or media.
+     *
+     * @remarks
+     * If both `media` and `color` are defined, `media` takes precedence.
+     */
+    fill?: FillOpts;
+    /**
+     * The outline of the rect.
+     */
+    stroke?: StrokeOpts;
+  };
+  /**
+   * @public
+   * Options for creating a shape element.
+   */
+  export type CreateShapeElementOpts = {
+    /**
+     * The distance from the top edge of the container, in pixels.
+     *
+     * @remarks
+     * - The pixels are relative to their container.
+     * - Minimum: -32768
+     * - Maximum: 32767
+     */
+    top: number;
+    /**
+     * The distance from the left edge of the container, in pixels.
+     *
+     * @remarks
+     * - The pixels are relative to their container.
+     * - Minimum: -32768
+     * - Maximum: 32767
+     */
+    left: number;
+    /**
+     * A rotation, in degrees.
+     *
+     * @remarks
+     * - Minimum: -180
+     * - Maximum: 180
+     */
+    rotation?: number;
+    /**
+     * Transparency as a percentage.
+     *
+     * @remarks
+     * - Minimum: 0
+     * - Maximum: 1
+     */
+    transparency?: number;
+    /**
+     * A width, in pixels.
+     */
+    width: number;
+    /**
+     * A height, in pixels.
+     */
+    height: number;
+    /**
+     * The scale and cropping of the shape.
+     */
+    readonly viewBox: AlignedBoxState;
+    /**
+     * The paths that define the structure of the shape.
+     *
+     * @remarks
+     * - Must have between 1 and 30 paths.
+     * - Total size of all paths must not exceed 2kb.
+     * - Maximum of 6 unique fill colors across all paths.
+     */
+    paths: PathOpts[];
+  };
+  /**
+   * @public
+   * Options for creating an embed element.
+   */
+  export type CreateEmbedElementOpts = {
+    /**
+     * The distance from the top edge of the container, in pixels.
+     *
+     * @remarks
+     * - The pixels are relative to their container.
+     * - Minimum: -32768
+     * - Maximum: 32767
+     */
+    top: number;
+    /**
+     * The distance from the left edge of the container, in pixels.
+     *
+     * @remarks
+     * - The pixels are relative to their container.
+     * - Minimum: -32768
+     * - Maximum: 32767
+     */
+    left: number;
+    /**
+     * A rotation, in degrees.
+     *
+     * @remarks
+     * - Minimum: -180
+     * - Maximum: 180
+     */
+    rotation?: number;
+    /**
+     * Transparency as a percentage.
+     *
+     * @remarks
+     * - Minimum: 0
+     * - Maximum: 1
+     */
+    transparency?: number;
+    /**
+     * A width, in pixels.
+     */
+    width: number;
+    /**
+     * A height, in pixels.
+     */
+    height: number;
+    /**
+     * The URL of the rich media.
+     *
+     * @remarks
+     * This URL must be supported by the Iframely API.
+     */
+    url: string;
+  };
+  /**
+   * @public
+   * Options for creating a text element.
+   */
+  export type CreateTextElementOpts = {
+    /**
+     * The distance from the top edge of the container, in pixels.
+     *
+     * @remarks
+     * - The pixels are relative to their container.
+     * - Minimum: -32768
+     * - Maximum: 32767
+     */
+    top: number;
+    /**
+     * The distance from the left edge of the container, in pixels.
+     *
+     * @remarks
+     * - The pixels are relative to their container.
+     * - Minimum: -32768
+     * - Maximum: 32767
+     */
+    left: number;
+    /**
+     * A width, in pixels.
+     */
+    width: number;
+    /**
+     * The text content.
+     */
+    text: {
+      regions: readonly TextRegion[];
+    };
+    /**
+     * A rotation, in degrees.
+     *
+     * @remarks
+     * - Minimum: -180
+     * - Maximum: 180
+     */
+    rotation?: number;
+    /**
+     * Transparency as a percentage.
+     *
+     * @remarks
+     * - Minimum: 0
+     * - Maximum: 1
+     */
+    transparency?: number;
+  };
+  /**
+   * @public
+   * Provides methods for creating element states.
+   *
+   * @remarks
+   * These methods don't add the elements to the design. They only return elements that can
+   * be added to a design, such as with the `insertAfter` method.
+   *
+   * @preventInline
+   */
+  export interface ElementStateBuilder {
+    /**
+     * Creates a rect element state.
+     * @param opts - Options for creating the rect element.
+     */
+    createRectElement(opts: CreateRectElementOpts): RectElementState;
+    /**
+     * Creates a shape element state.
+     * @param opts - Options for creating the shape element.
+     */
+    createShapeElement(opts: CreateShapeElementOpts): ShapeElementState;
+    /**
+     * Creates an embed element state.
+     * @param opts - Options for creating the embed element.
+     */
+    createEmbedElement(opts: CreateEmbedElementOpts): EmbedElementState;
+    /**
+     * Creates a text element state.
+     * @param opts - Options for creating the text element.
+     */
+    createTextElement(opts: CreateTextElementOpts): TextElementState;
+    /**
+     * Creates a richtext range.
+     */
+    createRichtextRange(): RichtextRange;
+  }
+  /**
+   * @public
+   * Async methods for handling more complex operations.
+   */
+  export interface AsyncOperations {
+    /**
+     * Group specified elements.
+     *
+     * @param opts - Options for grouping elements.
+     *
+     * @returns a new group element containing all the given elements.
+     */
+    group(opts: AsyncOperationsGroupOpts): Promise<GroupElement>;
+    /**
+     * Ungroup a group element.
+     *
+     * @param opts - Options for ungrouping a group element.
+     *
+     * @returns new elements that are ungrouped from the given group.
+     */
+    ungroup(
+      opts: AsyncOperationsUngroupOpts,
+    ): Promise<readonly AbsoluteElement[]>;
+  }
+  /**
+   * @public
+   * Options for `group` operation.
+   */
+  export interface AsyncOperationsGroupOpts {
+    /**
+     * Elements to be grouped.
+     */
+    elements: readonly Exclude<GroupContentElement, UnsupportedElement>[];
+  }
+  /**
+   * @public
+   * Options for `ungroup` operation.
+   */
+  export interface AsyncOperationsUngroupOpts {
+    /**
+     * Group element to be ungroup.
+     */
+    element: GroupElement;
+  }
+  /**
+   * @public
+   * Helpers for use with supported pages.
+   *
+   * @remarks
+   * Not applicable to unsupported pages.
+   *
+   * @preventInline
+   */
+  export type PageHelpers = AsyncOperations & {
+    /**
+     * Build an element state that can be used to create an element with the `insert` methods of
+     * the page's element list
+     */
+    elementStateBuilder: DesignEditing.ElementStateBuilder;
+  };
+  /**
+   * @public
+   * The result of reading part of a design when the context is the current page.
+   */
+  export type CurrentPageResult<
+    Page = DesignEditing.Page,
+    Helpers = DesignEditing.PageHelpers,
+  > = Readonly<{
+    /**
+     * The current page of the design.
+     */
+    page: Page;
+    /**
+     * These are various utilities that allow apps to do more complex operations on the page.
+     */
+    helpers: Helpers;
+    /**
+     * Saves any changes made during the session while keeping the transaction open.
+     *
+     * @remarks
+     * - Any changes in the session are only reflected in the design after this method is called.
+     * - Once this method is called, further changes in the session can still be made.
+     */
+    sync(): Promise<void>;
+  }>;
+  /**
+   * A function called for each item in the list.
+   *
+   * @param item - The current item in the list.
+   * @param index - The index of the current item.
+   */
+  export type ForEachCallback<M> = (item: M, index: number) => void;
+  /**
+   * A function that determines if an item should be included in the result.
+   *
+   * @param item - The item to test.
+   * @returns `true` if the item should be included, otherwise `false`.
+   */
+  export type FilterPredicate<M> = (item: M) => boolean;
+  /**
+   * A type predicate function that determines if an item is of a specific type.
+   *
+   * @param item - The item to test.
+   * @returns `true` if the item is of type `C`, otherwise `false`.
+   */
+  export type TypeFilterPredicate<M, C extends M> = (item: M) => item is C;
+  /**
+   * @public
+   * A list that cannot be changed.
+   *
+   * @preventInline
+   */
+  export interface ReadableList<M> {
+    /**
+     * Gets the number of items in the list.
+     *
+     * @returns The number of items.
+     */
+    count(): number;
+    /**
+     * Converts the list to an array.
+     *
+     * @returns An array containing all items. The items are the same as in the list.
+     */
+    toArray(): readonly M[];
+    /**
+     * Executes a function for each item in the list.
+     *
+     * @param callback - The function to run for each item.
+     */
+    forEach(callback: ForEachCallback<M>): void;
+    /**
+     * Creates a new array with items that match a specific type.
+     *
+     * @param filter - A function that checks if an item is of type `C`.
+     * @returns An array of items that are of type `C`.
+     */
+    filter<C extends M>(filter: TypeFilterPredicate<M, C>): readonly C[];
+    /**
+     * Creates a new array with items that pass a test.
+     *
+     * @param filter - A function that tests each item. Returns `true` to keep the item.
+     * @returns An array of items that passed the test.
+     */
+    filter(filter: FilterPredicate<M>): readonly M[];
+  }
+  /**
+   * @public
+   * A list of items that can be read.
+   *
+   * @preventInline
+   */
+  export interface ListState<T> extends Iterable<T | undefined> {
+    join(separator?: string): string;
+    slice(start?: number, end?: number): EditableListState<T>;
+    indexOf(searchElement: T, fromIndex?: number): number;
+    lastIndexOf(searchElement: T, fromIndex?: number): number;
+    every<S extends T>(
+      predicate: (value: T, index: number) => value is S,
+    ): this is ListState<S>;
+    every(predicate: (value: T, index: number) => unknown): boolean;
+    some(predicate: (value: T, index: number) => unknown): boolean;
+    forEach(callbackFn: (value: T, index: number) => void): void;
+    map<U>(callbackFn: (value: T, index: number) => U): EditableListState<U>;
+    filter<S extends T>(
+      predicate: (value: T, index: number) => value is S,
+    ): S[];
+    filter(predicate: (value: T, index: number) => unknown): T[];
+    reduce(
+      callbackFn: (
+        previousValue: T,
+        currentValue: T,
+        currentIndex: number,
+      ) => T,
+      initialValue?: T,
+    ): T;
+    reduce<U>(
+      callbackFn: (
+        previousValue: U,
+        currentValue: T,
+        currentIndex: number,
+      ) => U,
+      initialValue: U,
+    ): U;
+    reduceRight(
+      callbackFn: (
+        previousValue: T,
+        currentValue: T,
+        currentIndex: number,
+      ) => T,
+      initialValue?: T,
+    ): T;
+    reduceRight<U>(
+      callbackFn: (
+        previousValue: U,
+        currentValue: T,
+        currentIndex: number,
+      ) => U,
+      initialValue: U,
+    ): U;
+    find<S extends T>(
+      predicate: (value: T | undefined, index: number) => value is S,
+    ): S | undefined;
+    find(
+      predicate: (value: T | undefined, index: number) => unknown,
+    ): T | undefined;
+    flatMap<U>(
+      callback: (value: T, index: number, array: T[]) => U | readonly U[],
+    ): U[];
+    readonly length: number;
+    readonly [n: number]: T;
+  }
+  /**
+   * @public
+   * A list of items that can be read and updated.
+   */
+  export type EditableListState<T> = ListState<T> & {
+    length: number;
+    pop(): T | undefined;
+    push(...items: T[]): number;
+    shift(): T | undefined;
+    splice(start: number, deleteCount?: number): EditableListState<T>;
+    splice(
+      start: number,
+      deleteCount: number,
+      ...items: T[]
+    ): EditableListState<T>;
+    unshift(...items: T[]): number;
+    [n: number]: T;
+  };
+  /**
+   * @public
+   * A list of items that can be read and updated.
+   *
+   * @preventInline
+   */
+  export interface List<S, M> extends ReadableList<M> {
+    /**
+     * Adds a copy of an item to the list and places it right before another item.
+     *
+     * @param ref - The existing item to place the new item before.
+     * If `ref` is `undefined`, the new item is added at the end of the list.
+     * If `ref` does not exist in the list, the operation fails.
+     *
+     * @param item - The item to add. A copy of this item will be inserted.
+     *
+     * @returns
+     * The added item, or `undefined` if the operation failed.
+     */
+    insertBefore(ref: M | undefined, item: S): M | undefined;
+    /**
+     * Adds a copy of an item to the list and places it right after another item.
+     *
+     * @param ref - The existing item to place the new item after.
+     * If `ref` is `undefined`, the new item is added at the end of the list.
+     * If `ref` does not exist in the list, the operation fails.
+     *
+     * @param item - The item to add. A copy of this item will be inserted.
+     *
+     * @returns
+     * The added item, or `undefined` if the operation failed.
+     */
+    insertAfter(ref: M | undefined, item: S): M | undefined;
+    /**
+     * Moves an existing item to a new position right before another item.
+     *
+     * @param ref - The existing item to move the item before.
+     * If `ref` is `undefined`, the item is moved to the end of the list.
+     * If `ref` does not exist in the list, the operation fails.
+     *
+     * @param item - The item to move.
+     * The operation fails if the item is not already in the list.
+     */
+    moveBefore(ref: M | undefined, item: M): void;
+    /**
+     * Moves an existing item to a new position right after another item.
+     *
+     * @param ref - The existing item to move the item after.
+     * If `ref` is `undefined`, the item is moved to the end of the list.
+     * If `ref` does not exist in the list, the operation fails.
+     *
+     * @param item - The item to move.
+     * The operation fails if the item is not already in the list.
+     */
+    moveAfter(ref: M | undefined, item: M): void;
+    /**
+     * Removes an item from the list.
+     *
+     * @param item - The item to remove from the list.
+     */
+    delete(item: M): void;
+  }
+  /**
+   * @public
+   * Represents something that's not supported by the Apps SDK.
+   */
+  export interface Unsupported {
+    readonly type: "unsupported";
+  }
+  /**
+   * @public
+   * A state that creates a set of dimensions.
+   */
+  export interface DimensionsState {
+    /**
+     * A width, in pixels.
+     */
+    readonly width: number;
+    /**
+     * A height, in pixels.
+     */
+    readonly height: number;
+  }
+  /**
+   * @public
+   * A set of dimensions.
+   */
+  export type Dimensions = DimensionsState;
+  /**
+   * @public
+   * A state that creates an image fill.
+   */
+  export interface ImageFillState {
+    /**
+     * The type of media.
+     */
+    readonly type: "image";
+    /**
+     * A unique identifier that points to an image asset in Canva's backend.
+     */
+    readonly imageRef: ImageRef;
+    /**
+     * If `true`, the image is flipped horizontally.
+     */
+    flipX: boolean;
+    /**
+     * If `true`, the image is flipped vertically.
+     */
+    flipY: boolean;
+  }
+  /**
+   * @public
+   * An image that fills the interior of a media.
+   */
+  export type ImageFill = ImageFillState;
+  /**
+   * @public
+   * A state that creates a video fill.
+   */
+  export interface VideoFillState {
+    /**
+     * The type of media.
+     */
+    readonly type: "video";
+    /**
+     * A unique identifier that points to a video asset in Canva's backend.
+     */
+    readonly videoRef: VideoRef;
+    /**
+     * If `true`, the video is flipped horizontally.
+     */
+    flipX: boolean;
+    /**
+     * If `true`, the video is flipped vertically.
+     */
+    flipY: boolean;
+  }
+  /**
+   * @public
+   * A video that fills the interior of a media.
+   */
+  export type VideoFill = VideoFillState;
+  /**
+   * @public
+   * A state that creates a media fill.
+   */
+  export type MediaFillState = ImageFillState | VideoFillState;
+  /**
+   * @public
+   * A media item that fills an interior.
+   */
+  export type MediaFill = ImageFill | VideoFill;
+  /**
+   * @public
+   * A state that creates a solid color fill.
+   */
+  export interface SolidFillState {
+    /**
+     * The type of color.
+     */
+    readonly type: "solid";
+    /**
+     * The color of the fill.
+     * This must be a valid, six-digit hex code, prefixed with a `#` symbol.
+     *
+     * @remarks
+     * - Must be six characters long.
+     * - Must start with a `#`.
+     * - Must use lowercase letters.
+     * @example "#ff0099"
+     */
+    color: string;
+  }
+  /**
+   * @public
+   * A solid color that fills an interior.
+   */
+  export type SolidFill = SolidFillState;
+  /**
+   * @public
+   * A state that creates a color fill.
+   */
+  export type ColorFillState = SolidFillState | Unsupported;
+  /**
+   * @public
+   * A color that fills an interior.
+   */
+  export type ColorFill = SolidFill | Unsupported;
+  /**
+   * @public
+   * A state that creates a fill with color or media.
+   *
+   * @remarks
+   * If both `media` and `color` are defined, `media` takes precedence.
+   */
+  export interface FillState {
+    /**
+     * The media fill for the path, if any.
+     */
+    mediaContainer: MediaFillState | undefined;
+    /**
+     * The color fill for the path, if any.
+     */
+    colorContainer: ColorFillState | undefined;
+  }
+  /**
+   * @public
+   * A state that creates a shape path fill with color or media.
+   *
+   * @remarks
+   * If both `media` and `color` are defined, `media` takes precedence.
+   */
+  export interface PathFillState {
+    /**
+     * Defines whether the media fill is editable.
+     */
+    isMediaEditable: boolean;
+    /**
+     * The media fill for the path, if any.
+     */
+    mediaContainer: MediaFillState | undefined;
+    /**
+     * The color fill for the path, if any.
+     */
+    colorContainer: ColorFillState | undefined;
+  }
+  /**
+   * @public
+   * Describes how a fill of a shape path is filled with color or media.
+   *
+   * @remarks
+   * If both `media` and `color` are defined, `media` takes precedence.
+   */
+  export type PathFill =
+    | PathFillWithEditableMedia
+    | PathFillWithNonEditableMedia;
+  export interface PathFillWithEditableMedia {
+    readonly isMediaEditable: true;
+    /**
+     * A media fill, if any.
+     */
+    readonly mediaContainer: {
+      set(state: MediaFillState | undefined): void;
+      ref: MediaFill | undefined;
+    };
+    /**
+     * A color fill, if any.
+     */
+    readonly colorContainer: {
+      set(state: SolidFillState | undefined): void;
+      ref: ColorFill | undefined;
+    };
+  }
+  export interface PathFillWithNonEditableMedia {
+    readonly isMediaEditable: false;
+    /**
+     * A media fill, if any.
+     * MediaFill is not editable
+     */
+    readonly mediaContainer: {
+      ref: MediaFill | undefined;
+    };
+    /**
+     * A color fill, if any.
+     */
+    readonly colorContainer: {
+      set(state: SolidFillState | undefined): void;
+      ref: ColorFill | undefined;
+    };
+  }
+  /**
+   * @public
+   * Describes how a fill is filled with color or media.
+   *
+   * @remarks
+   * If both `media` and `color` are defined, `media` takes precedence.
+   *
+   * @preventInline
+   */
+  export interface Fill {
+    /**
+     * A media fill, if any.
+     */
+    readonly mediaContainer: {
+      set(state: MediaFillState | undefined): void;
+      ref: MediaFill | undefined;
+    };
+    /**
+     * A color fill, if any.
+     */
+    readonly colorContainer: {
+      set(state: SolidFillState | undefined): void;
+      ref: ColorFill | undefined;
+    };
+  }
+  /**
+   * @public
+   * A state that creates the scale and cropping of a shape.
+   *
+   * @remarks
+   * This is similar to the `viewBox` attribute of an `SVGElement`.
+   */
+  export interface AlignedBoxState {
+    /**
+     * The distance of the shape from the top edge of the element, in pixels.
+     */
+    readonly top: number;
+    /**
+     * The distance of the shape from the left edge of the element, in pixels.
+     */
+    readonly left: number;
+    /**
+     * The width of the view box, in pixels.
+     */
+    readonly width: number;
+    /**
+     * The height of the view box, in pixels.
+     */
+    readonly height: number;
+  }
+  /**
+   * @public
+   * The scale and cropping of a shape.
+   *
+   * @remarks
+   * This is similar to the `viewBox` attribute of an `SVGElement`.
+   */
+  export type AlignedBox = AlignedBoxState;
+  /**
+   * @public
+   * A state that creates a path that defines the structure of a shape element.
+   */
+  export interface PathState {
+    /**
+     * The shape of the path.
+     *
+     * @remarks
+     * This is similar to the `d` attribute of an SVG's `path` element, with some limitations:
+     *
+     * - Must start with an `M` command.
+     * - Only one `M` command is allowed.
+     * - `Q` and `T` commands are not permitted.
+     * - The path must be closed using a `Z` command or matching start and end coordinates.
+     */
+    readonly d: string;
+    /**
+     * The appearance of the path's interior.
+     */
+    readonly fill: PathFillState;
+    /**
+     * The stroke (outline) of the path, if any.
+     */
+    readonly stroke: StrokeState | undefined;
+  }
+  /**
+   * @public
+   * A path that defines the structure of a shape element.
+   *
+   * @preventInline
+   */
+  export type Path = {
+    /**
+     * The shape of the path.
+     *
+     * @remarks
+     * This is similar to the `d` attribute of an SVG's `path` element, with some limitations:
+     *
+     * - Must start with an `M` command.
+     * - Only one `M` command is allowed.
+     * - `Q` and `T` commands are not permitted.
+     * - The path must be closed using a `Z` command or matching start and end coordinates.
+     */
+    readonly d: string;
+    /**
+     * The appearance of the path's interior.
+     */
+    readonly fill: PathFill;
+    /**
+     * The stroke (outline) of the path, if any.
+     */
+    readonly stroke: Stroke | undefined;
+  };
+  /**
+   * @public
+   * A state that creates an outline, such as the border of an element.
+   */
+  export interface StrokeState {
+    /**
+     * The weight (thickness) of the stroke.
+     *
+     * @remarks
+     * - Minimum: 0
+     * - Maximum: 100
+     */
+    weight: number;
+    /**
+     * The color of the stroke.
+     */
+    colorContainer: ColorFillState;
+  }
+  /**
+   * @public
+   * Represents an outline, such as the border of an element.
+   *
+   * @preventInline
+   */
+  export type Stroke = {
+    /**
+     * The weight (thickness) of the stroke.
+     *
+     * @remarks
+     * - Minimum: 0
+     * - Maximum: 100
+     */
+    weight: number;
+    /**
+     * The color of the stroke.
+     */
+    readonly colorContainer: {
+      ref: ColorFill;
+      set(state: SolidFillState): void;
+    };
+  };
+  /**
+   * @public
+   * The basic properties of the state of an element.
+   *
+   * @remarks
+   * These properties are shared by all elements in a design.
+   */
+  export interface ElementState extends DimensionsState {
+    /**
+     * If `true`, the element is locked and cannot be modified.
+     */
+    readonly locked: boolean;
+    /**
+     * The distance from the top edge of the container, in pixels.
+     *
+     * @remarks
+     * - The pixels are relative to their container.
+     * - Minimum: -32768
+     * - Maximum: 32767
+     */
+    readonly top: number;
+    /**
+     * The distance from the left edge of the container, in pixels.
+     *
+     * @remarks
+     * - The pixels are relative to their container.
+     * - Minimum: -32768
+     * - Maximum: 32767
+     */
+    readonly left: number;
+    /**
+     * A rotation, in degrees.
+     *
+     * @remarks
+     * - Minimum: -180
+     * - Maximum: 180
+     */
+    readonly rotation: number;
+    /**
+     * Transparency as a percentage.
+     *
+     * @remarks
+     * - Minimum: 0
+     * - Maximum: 1
+     */
+    readonly transparency: number;
+  }
+  /**
+   * @public
+   * The basic properties of an element.
+   *
+   * @remarks
+   * These properties are shared by all elements in a design.
+   */
+  export type Element = DimensionsState & {
+    /**
+     * If `true`, the element is locked and cannot be modified.
+     */
+    readonly locked: boolean;
+    /**
+     * The distance from the top edge of the container, in pixels.
+     *
+     * @remarks
+     * - The pixels are relative to their container.
+     * - Minimum: -32768
+     * - Maximum: 32767
+     */
+    top: number;
+    /**
+     * The distance from the left edge of the container, in pixels.
+     *
+     * @remarks
+     * - The pixels are relative to their container.
+     * - Minimum: -32768
+     * - Maximum: 32767
+     */
+    left: number;
+    /**
+     * A rotation, in degrees.
+     *
+     * @remarks
+     * - Minimum: -180
+     * - Maximum: 180
+     */
+    rotation: number;
+    /**
+     * Transparency as a percentage.
+     *
+     * @remarks
+     * - Minimum: 0
+     * - Maximum: 1
+     */
+    transparency: number;
+  };
+  /**
+   * @public
+   * A state that creates a rectangular element.
+   */
+  export interface RectState {
+    /**
+     * The type of content.
+     */
+    readonly type: "rect";
+    /**
+     * The appearance of the rectangle's interior.
+     */
+    readonly fill: FillState;
+    /**
+     * The outline of the rectangle.
+     */
+    readonly stroke: StrokeState;
+  }
+  /**
+   * @public
+   * Represents a rectangular element.
+   */
+  export type Rect = {
+    /**
+     * The element type
+     */
+    readonly type: "rect";
+    readonly fill: Fill;
+    /**
+     * The outline of the rectangle.
+     */
+    readonly stroke: Stroke;
+  };
+  /**
+   * @public
+   * A state that creates a vector shape element.
+   */
+  export interface ShapeState {
+    /**
+     * The type of content.
+     */
+    readonly type: "shape";
+    /**
+     * The scale and cropping of the shape.
+     */
+    readonly viewBox: AlignedBoxState;
+    /**
+     * The paths that define the structure of the shape.
+     *
+     * @remarks
+     * - Must have between 1 and 30 paths.
+     * - Total size of all paths must not exceed 2kb.
+     * - Maximum of 6 unique fill colors across all paths.
+     */
+    readonly paths: ListState<PathState>;
+  }
+  /**
+   * @public
+   * Represents a vector shape element.
+   */
+  export type Shape = {
+    /**
+     * The type of content.
+     */
+    readonly type: "shape";
+    /**
+     * The scale and cropping of the shape.
+     */
+    readonly viewBox: AlignedBox;
+    /**
+     * The paths that define the structure of the shape.
+     */
+    readonly paths: ReadableList<Path>;
+  };
+  /**
+   * @public
+   * A state that creates group content.
+   */
+  export interface GroupState {
+    /**
+     * The type of content.
+     */
+    readonly type: "group";
+    /**
+     * The elements that exist within the group.
+     */
+    readonly contents: ListState<GroupContentElementState>;
+  }
+  /**
+   * @public
+   * Represents group content.
+   */
+  export type Group = {
+    /**
+     * The type of content.
+     */
+    readonly type: "group";
+    /**
+     * The elements that exist within the group.
+     */
+    readonly contents: ReadableList<GroupContentElement>;
+  };
+  /**
+   * @public
+   * A state that creates rich media content.
+   */
+  export interface EmbedState {
+    /**
+     * The type of content.
+     */
+    readonly type: "embed";
+    /**
+     * The URL of the rich media.
+     *
+     * @remarks
+     * This URL must be supported by the Iframely API.
+     */
+    readonly url: string;
+  }
+  /**
+   * @public
+   * Represents rich media content.
+   */
+  export type Embed = EmbedState;
+  /**
+   * @public
+   * A state that creates text content.
+   */
+  export interface TextState {
+    /**
+     * The type of content.
+     */
+    readonly type: "text";
+    /**
+     * The text content.
+     */
+    readonly text: {
+      regions: ListState<TextRegion>;
+    };
+  }
+  /**
+   * @public
+   * Represents text content.
+   */
+  export type Text = {
+    readonly type: "text";
+    readonly text: RichtextRange;
+  };
+  /**
+   * @public
+   * A state that creates a rectangle element.
+   *
+   * @remarks
+   * The rectangle can be filled with image content, video content, or a solid color.
+   */
+  export type RectElementState = RectState & ElementState;
+  /**
+   * @public
+   * An element that renders a rectangle.
+   *
+   * @remarks
+   * The rectangle can be filled with image content, video content, or a solid color.
+   */
+  export type RectElement = Rect & Element;
+  /**
+   * @public
+   * A state that creates a vector shape element.
+   */
+  export type ShapeElementState = ShapeState & ElementState;
+  /**
+   * @public
+   * An element that renders a vector shape.
+   */
+  export type ShapeElement = Shape & Element;
+  /**
+   * @public
+   * A state that creates a group element.
+   */
+  export type GroupElementState = GroupState & ElementState;
+  /**
+   * @public
+   * An element that renders a group of other elements.
+   */
+  export type GroupElement = Group & Element;
+  /**
+   * @public
+   * A state that creates an embed element, such as a YouTube video.
+   */
+  export type EmbedElementState = EmbedState & ElementState;
+  /**
+   * @public
+   * An element that embeds rich media, such as a YouTube video.
+   */
+  export type EmbedElement = Embed & Element;
+  /**
+   * @public
+   * A state that creates a text element.
+   */
+  export type TextElementState = TextState & ElementState;
+  /**
+   * @public
+   * An element that renders text content.
+   */
+  export type TextElement = Text & Element;
+  /**
+   * @public
+   * An element state that is not supported by the Apps SDK.
+   */
+  export type UnsupportedElementState = Unsupported & ElementState;
+  /**
+   * @public
+   * An element that is not supported by the Apps SDK.
+   */
+  export type UnsupportedElement = Unsupported & Readonly<Element>;
+  /**
+   * @public
+   * An element state that can exist in a group content state.
+   */
+  export type GroupContentElementState =
+    | RectElementState
+    | ShapeElementState
+    | EmbedElementState
+    | TextElementState
+    | UnsupportedElementState;
+  /**
+   * @public
+   * An element that can exist in a group element.
+   *
+   * @preventInline
+   */
+  export type GroupContentElement =
+    | RectElement
+    | ShapeElement
+    | EmbedElement
+    | TextElement
+    | UnsupportedElement;
+  /**
+   * @public
+   * An element state that can exist on an absolute page state.
+   *
+   * @preventInline
+   */
+  export type AbsoluteElementState =
+    | RectElementState
+    | ShapeElementState
+    | GroupElementState
+    | EmbedElementState
+    | TextElementState
+    | UnsupportedElementState;
+  /**
+   * @public
+   * An element that can exist on an absolute page.
+   *
+   * @preventInline
+   */
+  export type AbsoluteElement =
+    | RectElement
+    | ShapeElement
+    | GroupElement
+    | EmbedElement
+    | TextElement
+    | UnsupportedElement;
+  /**
+   * @public
+   * A list of elements.
+   *
+   * @preventInline
+   */
+  export interface ElementList
+    extends List<AbsoluteElementState, AbsoluteElement> {
+    insertBefore(
+      ref: AbsoluteElement | undefined,
+      state: EmbedElementState,
+    ): EmbedElement;
+    insertBefore(
+      ref: AbsoluteElement | undefined,
+      state: TextElementState,
+    ): TextElement;
+    insertBefore(
+      ref: AbsoluteElement | undefined,
+      state: ShapeElementState,
+    ): ShapeElement;
+    insertBefore(
+      ref: AbsoluteElement | undefined,
+      state: RectElementState,
+    ): RectElement;
+    insertAfter(
+      ref: AbsoluteElement | undefined,
+      state: EmbedElementState,
+    ): EmbedElement;
+    insertAfter(
+      ref: AbsoluteElement | undefined,
+      state: TextElementState,
+    ): TextElement;
+    insertAfter(
+      ref: AbsoluteElement | undefined,
+      state: ShapeElementState,
+    ): ShapeElement;
+    insertAfter(
+      ref: AbsoluteElement | undefined,
+      state: RectElementState,
+    ): RectElement;
+  }
+
+  /**
+   * @public
+   * A page with either fixed or unbounded dimensions.
+   *
+   * @preventInline
+   */
+  export type AbsolutePage = {
+    /**
+     * The type of page.
+     */
+    readonly type: "absolute";
+    /**
+     * If `true`, the page is locked and cannot be modified.
+     */
+    readonly locked: boolean;
+    /**
+     * The dimensions of the page. `dimensions` is undefined for whiteboard pages.
+     */
+    readonly dimensions: Dimensions | undefined;
+    /**
+     * The background of the page. `background` is undefined for whiteboard pages.
+     */
+    readonly background: Fill | undefined;
+    /**
+     * The elements on the page.
+     *
+     * @remarks
+     * Elements are rendered in the order they appear in the list.
+     * Later elements appear on top of earlier ones.
+     */
+    readonly elements: ElementList;
+  };
+  /**
+   * @public
+   * A page in a design.
+   *
+   * @remarks
+   * - Currently, only absolute pages are supported.
+   * - Other page types are represented as `Unsupported`.
+   * - Additional page types may be supported in future releases.
+   */
+  export type Page = AbsolutePage | Unsupported;
+  {
+  }
+}
+
 /**
  * @public
  * An element that's natively supported by the Canva editor.
@@ -397,6 +1894,21 @@ export declare type DesignElement =
   | RichtextElement
   | TableElement;
 
+/**
+ * @public
+ * A callback for reading and updating part of a design.
+ * @param session - The result of reading part of a design.
+ */
+export declare type DesignOpenCallback = (
+  session: DesignEditing.CurrentPageResult,
+) => Promise<void>;
+
+/**
+ * @public
+ * Options for configuring which part of a design to read.
+ */
+export declare type DesignOpenOptions = DesignContextOptions;
+
 /**
  * @public
  * Provides methods for managing the lifecycle of overlays, such as selected image overlays.
@@ -499,19 +2011,9 @@ export declare const editContent: (
  * A callback for reading and updating the requested design content.
  * @param session - The result of reading the content in the design.
  */
-export declare type EditContentCallback = (session: {
-  /**
-   * The individual content items returned by a query.
-   */
-  readonly contents: readonly RichtextContentRange[];
-  /**
-   * Commits any changes made to the items in the `contents` array.
-   *
-   * @remarks
-   * An app must call this method for any changes to be reflected in the user's design.
-   */
-  sync(): Promise<void>;
-}) => Promise<void> | void;
+export declare type EditContentCallback = (
+  session: RichtextContentSession,
+) => Promise<void> | void;
 
 /**
  * @public
@@ -1137,6 +2639,19 @@ export declare type NativeVideoElementWithBox = VideoElementAtPoint;
  */
 declare type ObjectPrimitive = Boolean | String;
 
+/**
+ * @public
+ *
+ * Reads a specified part of the user's design and returns all elements in that part.
+ *
+ * @param options - Options for configuring how the design is read.
+ * @param callback - A callback for operating on the design.
+ */
+export declare const openDesign: (
+  options: DesignOpenOptions,
+  callback: DesignOpenCallback,
+) => Promise<void>;
+
 /**
  * @public
  * An alias for the DesignOverlay interface, providing access to design overlay related functionality
@@ -1325,6 +2840,15 @@ export declare interface RichtextContentRange extends RichtextRange {
   readonly deleted: boolean;
 }
 
+/**
+ * @public
+ * Session for reading and updating richtext content in a user's design.
+ */
+export declare interface RichtextContentSession {
+  readonly contents: readonly RichtextContentRange[];
+  sync(): Promise<void>;
+}
+
 /**
  * @public
  * An element that renders richtext content.