@canva/design 2.8.1-alpha.1 → 2.8.1-beta.0

package/{alpha.d.ts → beta.d.ts}

@@ -2,7 +2,7 @@
  * @beta
  * Information about a page within a design with fixed or unbounded dimensions.
  */
-declare type AbsolutePageMetadata = {
+export declare type AbsolutePageMetadata = {
     /**
      * The type of page.
      */
@@ -828,17 +828,6 @@ export declare type AppElementClientConfiguration<A extends AppElementData> = {
     render: AppElementRenderer<A>;
 };
 
-/**
- * @alpha
- * Configuration for an App Element
- */
-export declare type AppElementClientConfigurationV2<A extends AppElementData> = {
-    /**
-     * The AppElementRenderer to use when rendering the app element
-     */
-    render: AppElementRendererV2<A>;
-};
-
 /**
  * @public
  * The data associated with an app element.
@@ -874,71 +863,6 @@ export declare type AppElementRenderer<A extends AppElementData> = (appElementDa
  */
 export declare type AppElementRendererOutput = GroupContentAtPoint[];
 
-/**
- * @alpha
- * A return value of {@link AppElementRendererV2} function.
- * It is an array of elements to render within an app element.
- */
-export declare type AppElementRendererOutputV2 = AppElementRendererOutput;
-
-/**
- * @alpha
- * A callback that runs when an app's element is changed.
- *
- * @remarks
- * This callback must return one or more elements to render within the app element.
- */
-export declare type AppElementRendererV2<A extends AppElementData> = (appElementData: A) => AppElementRendererOutputV2;
-
-/**
- * @alpha
- * Apply a template to the current design given a template id.
- *
- * @example Apply a template to the current design
- * ```typescript
- * import {
- *   applyTemplate,
- *   requestBrandTemplates,
- *   type BrandTemplateId,
- * } from "@canva/design";
- *
- * const selection = await requestBrandTemplates();
- * if (selection.status === "aborted") return;
- *
- * const templateId = selection.brandTemplates[0]?.token as BrandTemplateId | undefined;
- * if (!templateId) return;
- *
- * const result = await applyTemplate({
- *   template: { id: templateId },
- *   mode: "overwrite",
- * });
- *
- * if (result.status === "completed") {
- *   // Template was successfully applied
- * }
- * ```
- */
-export declare const applyTemplate: (options: ApplyTemplateOptions) => Promise<ApplyTemplateResult>;
-
-/**
- * @alpha
- * Options for applying a template to a design.
- */
-export declare type ApplyTemplateOptions = {
-    template: {
-        id: BrandTemplateId;
-    };
-    mode: 'overwrite';
-};
-
-/**
- * @alpha
- * Response object from the ApplyTemplate operation.
- */
-export declare type ApplyTemplateResult = {
-    status: 'completed' | 'aborted';
-};
-
 /**
  * @public
  * A unique identifier that references an app runtime process
@@ -991,61 +915,6 @@ export declare type AudioTrack = {
     ref: AudioRef;
 };
 
-/**
- * @alpha
- * Configuration for the Autofill call to request the Data Connector intent implemented by the app
- * and skipping the data preview modal.
- */
-export declare type AutofillDataConnectorNoPreview = {
-    dataSelectionDisplay: 'hide';
-    dataSourceRef: DataSourceRef;
-};
-
-/**
- * @alpha
- * Configuration for the Autofill call to request the Data Connector intent implemented by the app
- * and displaying the data preview modal.
- */
-export declare type AutofillDataConnectorWithPreview = {
-    dataSelectionDisplay: 'show';
-};
-
-/**
- * @alpha
- * Wrapper for the configurations that will query the app owned Data Connector.
- */
-export declare type AutofillFromDataConnector = {
-    type: 'data_connector';
-    withDataConnector: 'self';
-    limit?: DataTableLimit;
-} & (AutofillDataConnectorWithPreview | AutofillDataConnectorNoPreview);
-
-/**
- * @alpha
- * Configuration for providing a fully populated data table to the Autofill call.
- */
-export declare type AutofillFromDataTable = {
-    type: 'data_table';
-    dataTable: DataTable;
-};
-
-/**
- * @alpha
- * A set of options to configure the Autofill call.
- * @param title - an optional title that will be set to the document after Autofill is done.
- */
-export declare type AutofillOptions = {
-    title?: string;
-} & (AutofillFromDataTable | AutofillFromDataConnector);
-
-/**
- * @alpha
- * Response object from the Autofill operation.
- */
-export declare type AutofillResponse = {
-    status: 'success';
-};
-
 /**
  * @public
  * Cell containing a boolean value.
@@ -1121,23 +990,6 @@ export declare type Bounds = {
  */
 export declare type Box = Point & (WidthAndHeight | Width | Height);
 
-/**
- * @alpha
- * A unique identifier that references a brand template.
- */
-export declare type BrandTemplateId = string & {
-    __brandTemplateId: never;
-};
-
-/**
- * @alpha
- * Metadata for a brand template.
- */
-export declare type BrandTemplateMetadata = Omit<TemplateMetadata, 'domain'> & {
-    domain: 'brand';
-    dataset?: DataField[];
-};
-
 /**
  * @public
  * An alias for the BulkCreateLauncher interface, providing access to bulk create related functionality
@@ -1333,7 +1185,7 @@ export declare interface ContentDraft<T> {
 /**
  * @beta
  */
-declare type ContentType = 'richtext' | 'fill';
+export declare type ContentType = 'richtext' | 'fill';
 
 /**
  * @public
@@ -1448,14 +1300,6 @@ export declare type Coordinates = {
  */
 export declare const createRichtextRange: () => RichtextRange;
 
-/**
- * @alpha
- * Session for the `openDesign` callback (current page) when `helpers` is {@link PageHelpersWithTiming}.
- */
-export declare type CurrentPageSessionWithTiming<Page extends DesignEditing.Page = DesignEditing.Page> = Omit<DesignEditing.CurrentPageSession<Page, DesignEditing.PageHelpers>, 'helpers'> & {
-    helpers: PageHelpersWithTiming;
-};
-
 /**
  * @beta
  * Metadata for a data field in a brand template.
@@ -1465,18 +1309,6 @@ export declare type DataField = {
     type: 'image' | 'text' | 'chart';
 };
 
-/**
- * @alpha
- * A representation of the data source that is given to the Data Connector.
- */
-export declare type DataSourceRef = {
-    /**
-     * This 'source' will be passed on to the Data Connector intent.
-     */
-    source: string;
-    title?: string;
-};
-
 /**
  * @public
  * Structured tabular data for import into Canva.
@@ -3183,7 +3015,7 @@ export declare type DesignElement = ImageElement | VideoElement | EmbedElement |
  * @beta
  * Information about the design.
  */
-declare type DesignMetadata = {
+export declare type DesignMetadata = {
     /**
      * The title of the user's design.
      * @remarks
@@ -3219,40 +3051,6 @@ declare type DesignMetadata = {
     dataset?: DataField[];
 };
 
-/**
- * @public
- * Information about the design.
- */
-declare type DesignMetadata_2 = {
-    /**
-     * The title of the user's design.
-     * @remarks
-     * This is optional and will be `undefined` if the user hasn't set a title.
-     */
-    title?: string;
-    /**
-     * The default dimensions that a new page will have when it is added to a design.
-     * It is possible for a user to resize a page without resizing the entire design, e.g. by clicking
-     * "Expand to Whiteboard". However, there will always be a single set of default dimensions for a
-     * design that is applied whenever a new page is created.
-     * @remarks
-     * This is optional and will be `undefined` if the design is unbounded (e.g. Whiteboard or Doc).
-     */
-    defaultPageDimensions?: PageDimensions;
-    /**
-     * The information associated with each page of the design.
-     * @remarks
-     * The order of pages is not guaranteed.
-     */
-    pageMetadata: Iterable<PageMetadata_2>;
-    /**
-     * The duration of the whole design in seconds.
-     * @remarks
-     * This is the precise value, which differs from what is displayed in the UI as duration in Canva UI is formatted differently.
-     */
-    durationInSeconds: number;
-};
-
 /**
  * @beta
  * A callback for operating on all pages of the design.
@@ -3280,16 +3078,16 @@ export declare type DesignOpenCallback = (session: DesignEditing.CurrentPageSess
 
 /**
  * @beta
- * A callback for operating on the current page of the design.
- * @param session - Session received by the `openDesign` callback when opening the current page.
+ * A callback for operating on the design.
  */
-export declare type DesignOpenCurrentPageCallback = (session: DesignEditing.CurrentPageSession) => Promise<void>;
+declare type DesignOpenCallback_2 = DesignOpenCurrentPageCallback | DesignOpenAllPagesCallback;
 
 /**
- * @alpha
- * Callback for `openDesign` when the session exposes {@link PageHelpersWithTiming}.
+ * @beta
+ * A callback for operating on the current page of the design.
+ * @param session - Session received by the `openDesign` callback when opening the current page.
  */
-declare type DesignOpenCurrentPageCallbackWithTiming = (session: CurrentPageSessionWithTiming<DesignEditing.Page>) => Promise<void>;
+export declare type DesignOpenCurrentPageCallback = (session: DesignEditing.CurrentPageSession) => Promise<void>;
 
 /**
  * @beta
@@ -3609,31 +3407,44 @@ export declare type DragStartEvent<E extends Element> = Pick<DragEvent, 'dataTra
 };
 
 /**
- * @public
- * Reads and edits content of the specified type from the user's design.
- * @param options - Options for configuring how a design is read.
- * @param callback - A callback for operating on the read content.
- *
- * @example Read richtext content
- * ```typescript
- * import { editContent } from "@canva/design";
- *
- * await editContent(
- *   { contentType: 'richtext', target: 'current_page' },
- *   async (session) => {
- *     // Do something with the richtext content, e.g. `session.contents`
- *   }
- * );
- * ```
+ * @beta
+ * Reads and edits richtext content from the user's design.
+ * @param options - Options for configuring how a design is read. Must specify `contentType: 'richtext'`.
+ * @param callback - A callback that receives a `RichtextContentSession` for editing.
+ * @returns A promise that resolves when editing is complete.
+ */
+export declare function editContent(options: EditContentOptions & {
+    contentType: 'richtext';
+}, callback: (session: RichtextContentSession) => Promise<void> | void): Promise<void>;
+
+/**
+ * @beta
+ * Reads and edits fill content from the user's design.
+ * @param options - Options for configuring how a design is read. Must specify `contentType: 'fill'`.
+ * @param callback - A callback that receives a `FillContentSession` for editing.
+ * @returns A promise that resolves when editing is complete.
+ */
+export declare function editContent(options: EditContentOptions & {
+    contentType: 'fill';
+}, callback: (session: FillContentSession) => Promise<void> | void): Promise<void>;
+
+/**
+ * @beta
+ * Reads and edits content from the user's design.
+ * @param options - Options for configuring how a design is read. Must specify a content type.
+ * @param callback - A callback that receives a session for editing.
+ * @returns A promise that resolves when editing is complete.
  */
-export declare const editContent: (options: EditContentOptions_2, callback: EditContentCallback_2) => Promise<void>;
+export declare function editContent<T extends ContentType>(options: EditContentOptions & {
+    contentType: T;
+}, callback: (session: ContentTypeMap[T]) => Promise<void> | void): Promise<void>;
 
 /**
  * @beta
  * A callback for reading and updating the requested design content.
  * @param session - Session for reading and updating content in the design.
  */
-declare type EditContentCallback = (session: RichtextContentSession | FillContentSession) => Promise<void> | void;
+export declare type EditContentCallback = (session: RichtextContentSession | FillContentSession) => Promise<void> | void;
 
 /**
  * @public
@@ -3646,7 +3457,7 @@ declare type EditContentCallback_2 = (session: RichtextContentSession) => Promis
  * @beta
  * Options for configuring how the design content is read.
  */
-declare type EditContentOptions = {
+export declare type EditContentOptions = {
     /**
      * The type of content to edit from the user's design
      */
@@ -3991,21 +3802,6 @@ export declare type FontRef = string & {
  **/
 export declare type FontWeight = 'normal' | 'thin' | 'extralight' | 'light' | 'medium' | 'semibold' | 'bold' | 'ultrabold' | 'heavy';
 
-/**
- * @alpha
- * Return metadata for a brand template given its ID.
- *
- * @example Get brand template metadata
- * ```typescript
- * import { getBrandTemplateMetadata, BrandTemplateId } from "@canva/design";
- *
- * const templateId = resolveToken(requestBrandTemplates()) as BrandTemplateId;
- *
- * const metadata = await getBrandTemplateMetadata(templateId);
- * ```
- */
-export declare const getBrandTemplateMetadata: (id: BrandTemplateId) => Promise<BrandTemplateMetadata>;
-
 /**
  * Allows to get the context of currently selected page.
  * @public
@@ -4076,19 +3872,25 @@ export declare const getCurrentPageContext: () => Promise<PageContext>;
 export declare const getDefaultPageDimensions: () => Promise<Dimensions | undefined>;
 
 /**
- * @public
+ * @beta
  * Retrieves information about the design.
+ */
+export declare const getDesignMetadata: () => Promise<DesignMetadata>;
+
+/**
+ * @beta
+ * Retrieves information about the template that was used in a design.
  *
- * @example Get design metadata
+ * @example Get design template metadata
  * ```typescript
- * import { getDesignMetadata } from "@canva/design";
+ * import { getDesignTemplateMetadata } from "@canva/design";
  *
- * const metadata = await getDesignMetadata();
+ * const templateMetadata = await getDesignTemplateMetadata();
  *
- * const { title, defaultPageDimensions,  pageMetadata, durationInSeconds } = metadata;
+ * const { keywords, domain } = templateMetadata;
  * ```
  */
-export declare const getDesignMetadata: () => Promise<DesignMetadata_2>;
+export declare const getDesignTemplateMetadata: () => Promise<DesignTemplateMetadata>;
 
 /**
  * @public
@@ -4436,13 +4238,44 @@ declare type ImageUploadOptions = {
 } & AllOrNone<Dimensions_2>;
 
 /**
- * @alpha
+ * @public
  * @param appElementConfig - Configuration for an AppElementClient
+ *
+ * @example Initialize app element client
+ * ```typescript
+ * import { initAppElement } from "@canva/design";
+ *
+ * const appElement = initAppElement<{ content: string }>({
+ *   render: (data) => {
+ *     return [{
+ *       type: 'text',
+ *       children: [data.content],
+ *       top: 100,
+ *       left: 100,
+ *       width: 200
+ *     }];
+ *   }
+ * });
+ * ```
+ *
+ * @example Initialize V2 app element client
+ * ```typescript
+ * import { initAppElement } from "@canva/design";
+ *
+ * const appElement = initAppElement<{ content: string }>({
+ *   render: (data) => {
+ *     return [{
+ *       type: 'text',
+ *       children: [data.content],
+ *       top: 100,
+ *       left: 100,
+ *       width: 200
+ *     }];
+ *   }
+ * });
+ * ```
  */
-export declare const initAppElement: {
-    <A extends AppElementData>(appElementConfig: AppElementClientConfigurationV2<A>): AppElementClient<A>;
-    <A extends AppElementData>(appElementConfig: AppElementClientConfiguration<A>): AppElementClient<A>;
-};
+export declare const initAppElement: <A extends AppElementData>(appElementConfig: AppElementClientConfiguration<A>) => AppElementClient<A>;
 
 /**
  * @public
@@ -4782,13 +4615,16 @@ declare type NumberDataTableCell = {
 declare type ObjectPrimitive = Boolean | String;
 
 /**
- * @alpha
- * Reads (and optionally updates) the current page of the user's design, with timing support for
- * video timeline elements.
- * @param options - Options for configuring how the current page of the design is read.
- * @param callback - A callback for operating on the current page of the design.
- */
-export declare const openDesign: (options: DesignOpenCurrentPageOptions, callback: DesignOpenCurrentPageCallbackWithTiming) => Promise<void>;
+ * @beta
+ * Reads (and optionally updates) a specified part of the user's design.
+ * @param options - Options for configuring how the design is read.
+ * @param callback - A callback for operating on the design.
+ */
+export declare const openDesign: {
+    (options: DesignOpenCurrentPageOptions, callback: DesignOpenCurrentPageCallback): Promise<void>;
+    (options: DesignOpenAllPagesOptions, callback: DesignOpenAllPagesCallback): Promise<void>;
+    (options: DesignOpenOptions_2, callback: DesignOpenCallback_2): Promise<void>;
+};
 
 /**
  * @public
@@ -4881,55 +4717,11 @@ export declare type PageDimensions = {
     height: number;
 };
 
-/**
- * @alpha
- * {@link DesignEditing.PageHelpers} plus {@link PageHelpersWithTiming.timingFor | timingFor} for **video / fixed pages** with a timeline.
- *
- * @preventInline
- */
-export declare type PageHelpersWithTiming = DesignEditing.PageHelpers & {
-    /**
-     * Timing API for one element on the current page.
-     *
-     * @param elementRef - Must belong to the current page.
-     * @returns A {@link TimingAccessor} for the element.
-     */
-    timingFor(elementRef: DesignEditing.AbsoluteElement): TimingAccessor;
-};
-
 /**
  * @beta
  * Information about a page within a design.
  */
-declare type PageMetadata = AbsolutePageMetadata | UnsupportedPageMetadata;
-
-/**
- * @public
- * Information about a page.
- */
-declare type PageMetadata_2 = {
-
-    /**
-     *
-     * The dimensions of the page, in pixels.
-     *
-     * @remarks
-     * This may be `undefined` because some types of pages don't have dimensions, such as whiteboards.
-     */
-    dimensions?: PageDimensions;
-};
-
-/**
- * @alpha
- * Partial update shape: only listed properties are applied; others stay as they are.
- *
- * @remarks
- * Each key may be the normal value, {@link ResetToDefault} to reset that property to its default, or
- * omitted / **`undefined`** to leave that property **unchanged**.
- */
-export declare type Patch<T extends Record<string, unknown>> = {
-    [K in keyof T]?: T[K] | typeof ResetToDefault;
-};
+export declare type PageMetadata = AbsolutePageMetadata | UnsupportedPageMetadata;
 
 /**
  * @public
@@ -5037,131 +4829,22 @@ export declare type PublishLauncher = {
 };
 
 /**
- * @alpha
- * Requests the Autofill flow to start of the given options. The flow can request data from the app
- * owned Data Connector, or use any given data that is passed in the options object.
- *
- * @param opts - The configuration options for this Autofill flow.
- *
- * @example Basic usage - Open data connector preview dialog to request data
- * ```typescript
- * import { requestAutofillDesign } from "@canva/design";
- * import type { AutofillOptions } from "@canva/design";
- *
- * const opts: AutofillOptions = {
- *   title: 'Updated design',
- *   type: 'data_connector',
- *   dataSelectionDisplay: 'show',
- * };
- *
- * const response = await requestAutofillDesign(element);
- * ```
- *
- * @example Basic usage - Request data from the data connector without preview
- * ```typescript
- * import { requestAutofillDesign } from "@canva/design";
- * import type { AutofillOptions } from "@canva/design";
- *
- * const opts: AutofillOptions = {
- *   title: 'Updated design',
- *   type: 'data_connector',
- *   dataSelectionDisplay: 'hide',
- *   dataSourceRef: { source: 'serialized_content' }
- * };
- *
- * const response = await requestAutofillDesign(element);
- * ```
- *
- * @example Basic usage - Use the data given in the options
- * ```typescript
- * import { requestAutofillDesign } from "@canva/design";
- * import type { AutofillOptions } from "@canva/design";
- *
- * const opts: AutofillOptions = {
- *   title: 'Updated design',
- *   type: 'data_table',
- *   dataTable: // Set the data table containing the data entries for each field.
- * };
- *
- * const response = await requestAutofillDesign(element);
- * ```
- */
-export declare const requestAutofillDesign: (opts: AutofillOptions) => Promise<AutofillResponse>;
-
-/**
- * @alpha
- * Trigger brand template selection panel and returns the selected template token.
- *
- * @example Request brand templates
- * ```typescript
- * import { requestBrandTemplates } from "@canva/design";
- *
- * const response = await requestBrandTemplates();
- *
- * if (response.status === 'aborted') return;
- *
- * const { token } = response.brandTemplates[0];
- * ```
+ * @public
+ * Exports the user's design as one or more static files.
+ * @param request - The request object containing configurations of the design export.
  */
-export declare const requestBrandTemplates: () => Promise<RequestBrandTemplatesResponse>;
+export declare const requestExport: (request: ExportRequest) => Promise<ExportResponse>;
 
 /**
- * @alpha
- * Response object from the RequestBrandTemplate operation.
+ * @public
+ * Provides methods for interacting with a range of formatted text.
  */
-export declare type RequestBrandTemplatesResponse = RequestBrandTemplatesResponseCompleted | RequestBrandTemplatesResponseAborted;
-
-/**
- * @alpha
- * Response object from the RequestBrandTemplate operation that was aborted.
- */
-export declare type RequestBrandTemplatesResponseAborted = {
-    status: 'aborted';
-};
-
-/**
- * @alpha
- * Response object from the RequestBrandTemplate operation completed successfully.
- */
-export declare type RequestBrandTemplatesResponseCompleted = {
-    status: 'completed';
-    brandTemplates: RequestBrandTemplatesResponseContent[];
-};
-
-/**
- * @alpha
- * Response object from the RequestBrandTemplate operation completed successfully.
- */
-export declare type RequestBrandTemplatesResponseContent = {
-    token: string;
-};
-
-/**
- * @public
- * Exports the user's design as one or more static files.
- * @param request - The request object containing configurations of the design export.
- */
-export declare const requestExport: (request: ExportRequest) => Promise<ExportResponse>;
-
-/**
- * @alpha
- * Use in a {@link Patch} to mean “set this property to its default” instead of a concrete value.
- *
- * @remarks
- * String literals like `'default'` are avoided so they cannot clash with future string-valued fields.
- */
-export declare const ResetToDefault: unique symbol;
-
-/**
- * @public
- * Provides methods for interacting with a range of formatted text.
- */
-export declare interface RichtextContentRange extends RichtextRange {
-    /**
-     * Indicates whether the object containing this richtext range has been deleted.
-     */
-    readonly deleted: boolean;
-}
+export declare interface RichtextContentRange extends RichtextRange {
+    /**
+     * Indicates whether the object containing this richtext range has been deleted.
+     */
+    readonly deleted: boolean;
+}
 
 /**
  * @public
@@ -6142,401 +5825,406 @@ export declare type TextRegion = {
 };
 
 /**
- * @alpha
- * Start time and duration for an element on the **video timeline** (seconds).
+ * @public
+ * Provides methods for adding drag and drop behavior to an app.
  */
-export declare type Timing = {
+export declare interface UI {
     /**
-     * Delay from the start of the page’s timeline until this element becomes visible. Minimum `0`.
+     * @deprecated The method has been superseded by `startDragToPoint`.
+     * @public
+     * Adds the specified element or content to a design at the end of a drag event.
+     *
+     * @param event - A drag start event.
+     * @param dragData - Element or content to be added to the design at the end of the drag event.
      */
-    readonly delayInSeconds: number;
+    startDrag<E extends Element>(event: DragStartEvent<E>, dragData: TextDragConfig | AudioDragConfig | EmbedDragConfig | VideoDragConfigForElement<E> | ImageDragConfigForElement<E>): Promise<void>;
+    /**
+     * @public
+     * Adds the specified element or content to fixed designs, which use a coordinate-based positioning system at the end of a drag event.
+     *
+     * @param event - A drag start event.
+     * @param dragData - Element or content to be added to the design at the end of the drag event.
+     */
+    startDragToPoint<E extends Element>(event: DragStartEvent<E>, dragData: TextDragConfig | AudioDragConfig | EmbedDragConfig | VideoDragConfigForElement<E> | ImageDragConfigForElement<E>): Promise<void>;
+    /**
+     * @public
+     * Adds the specified element or content to responsive documents, which slot things into a text stream at the end of a drag event.
+     *
+     * @param event - A drag start event.
+     * @param dragData - Element or content to be added to the design at the end of the drag event.
+     */
+    startDragToCursor<E extends Element>(event: DragStartEvent<E>, dragData: EmbedDragConfig | VideoDragConfigForElement<E> | ImageDragConfigForElement<E>): Promise<void>;
+}
+
+/**
+ * An alias for the UI interface, providing access to ui related functionality
+ * @public
+ */
+export declare const ui: UI;
+
+/**
+ * @beta
+ * Pages that do not have fixed or unbounded dimensions currently do not return metadata.
+ */
+export declare type UnsupportedPageMetadata = {
     /**
-     * How long the element stays visible. A **number** is a duration in seconds (Positive number).
-     * The string **`'until_end_of_page'`** means until the **end of the current page** (default).
+     * The type of page.
      */
-    readonly durationInSeconds: number | 'until_end_of_page';
+    type: 'unsupported';
 };
 
 /**
- * @alpha
- * Read/write timing for a single element. Obtained from {@link PageHelpersWithTiming.timingFor}.
- *
- * @preventInline
+ * @public
+ * A data type that can be used in app element data.
+ */
+export declare type Value = Primitive | ObjectPrimitive | Exclude<Value, undefined>[] | {
+    [key: string]: Value;
+};
+
+/**
+ * @public
+ * Video element or content to be added to the design at the end of a drag event.
  */
-export declare type TimingAccessor = {
+export declare type VideoDragConfig = {
     /**
-     * Reads the element’s current timing.
+     * The type of element.
+     */
+    type: 'video';
+    /**
+     * A function that returns a reference (ref) to a video asset in Canva's backend.
+     */
+    resolveVideoRef: () => Promise<{
+        ref: VideoRef;
+    }>;
+    /**
+     * The dimensions of the preview image.
+     */
+    previewSize: Dimensions;
+    /**
+     * The dimensions of the full-size video.
      *
-     * @returns {@link Timing}
-         *
-         * @remarks
-         * If set(ResetToDefault) and then get(), it will returns `{ startMs: 0, durationMs: 'until_end_of_page' }` instead
-         */
-     get(): Timing;
-     /**
-      * Updates timing on the element, or resets it entirely.
-      *
-      * @param timing - Either:
-      * - **`ResetToDefault`** alone — reset **all** timing to defaults (delay at 0, duration to end of page).
-      * - A **patch object** — merge with current timing. Omitted keys or keys set to `undefined` are
-      *   **unchanged**. Use {@link ResetToDefault} on a key to reset that property to its default.
-      */
-     set(timing: Patch<Timing> | typeof ResetToDefault): Promise<void>;
-    };
-
+     * @remarks
+     * - These dimensions are used when adding the video to the design
+     * - If omitted, the `previewSize` dimensions are used as a fallback.
+     */
+    fullSize?: Dimensions;
     /**
-     * @public
-     * Provides methods for adding drag and drop behavior to an app.
+     * The URL of an image to display under the user's cursor during the drag and drop event.
      */
-    export declare interface UI {
-        /**
-         * @deprecated The method has been superseded by `startDragToPoint`.
-         * @public
-         * Adds the specified element or content to a design at the end of a drag event.
-         *
-         * @param event - A drag start event.
-         * @param dragData - Element or content to be added to the design at the end of the drag event.
-         */
-        startDrag<E extends Element>(event: DragStartEvent<E>, dragData: TextDragConfig | AudioDragConfig | EmbedDragConfig | VideoDragConfigForElement<E> | ImageDragConfigForElement<E>): Promise<void>;
-        /**
-         * @public
-         * Adds the specified element or content to fixed designs, which use a coordinate-based positioning system at the end of a drag event.
-         *
-         * @param event - A drag start event.
-         * @param dragData - Element or content to be added to the design at the end of the drag event.
-         */
-        startDragToPoint<E extends Element>(event: DragStartEvent<E>, dragData: TextDragConfig | AudioDragConfig | EmbedDragConfig | VideoDragConfigForElement<E> | ImageDragConfigForElement<E>): Promise<void>;
-        /**
-         * @public
-         * Adds the specified element or content to responsive documents, which slot things into a text stream at the end of a drag event.
-         *
-         * @param event - A drag start event.
-         * @param dragData - Element or content to be added to the design at the end of the drag event.
-         */
-        startDragToCursor<E extends Element>(event: DragStartEvent<E>, dragData: EmbedDragConfig | VideoDragConfigForElement<E> | ImageDragConfigForElement<E>): Promise<void>;
-    }
+    previewUrl: string;
+};
+
+/**
+ * @public
+ * Video element or content to be added to the design at the end of a drag event.
+ */
+export declare type VideoDragConfigForElement<E extends Element> = E extends HTMLImageElement ? Partial<VideoDragConfig> & Pick<VideoDragConfig, 'type' | 'resolveVideoRef'> : VideoDragConfig;
 
+/**
+ * @public
+ * An element that renders video content.
+ */
+export declare type VideoElement = {
     /**
-     * An alias for the UI interface, providing access to ui related functionality
-     * @public
+     * The type of element.
      */
-    export declare const ui: UI;
-
+    type: 'video';
+    /**
+     * A unique identifier that points to a video asset in Canva's backend.
+     */
+    ref: VideoRef;
+    /**
+     * A description of the video content.
+     *
+     * @remarks
+     * Use `undefined` for content with no description.
+     */
+    altText: AltText | undefined;
     /**
      * @beta
-     * Pages that do not have fixed or unbounded dimensions currently do not return metadata.
+     * Options for configuring the cropping of the video.
      */
-    declare type UnsupportedPageMetadata = {
-        /**
-         * The type of page.
-         */
-        type: 'unsupported';
-    };
-
+    imageBox?: VideoImageBox;
     /**
-     * @public
-     * A data type that can be used in app element data.
+     * @beta
+     * Options for configuring the start, and end of the video.
      */
-    export declare type Value = Primitive | ObjectPrimitive | Exclude<Value, undefined>[] | {
-        [key: string]: Value;
-    };
+    trim?: VideoTrim;
+};
+
+/**
+ * @public
+ * An element that renders video content and has positional properties.
+ */
+export declare type VideoElementAtPoint = VideoElement & Point & (WidthAndHeight | Width | Height);
 
+/**
+ * @public
+ * A video asset that fills a path's interior.
+ */
+export declare type VideoFill = {
     /**
-     * @public
-     * Video element or content to be added to the design at the end of a drag event.
+     * The type of fill.
      */
-    export declare type VideoDragConfig = {
-        /**
-         * The type of element.
-         */
-        type: 'video';
-        /**
-         * A function that returns a reference (ref) to a video asset in Canva's backend.
-         */
-        resolveVideoRef: () => Promise<{
-            ref: VideoRef;
-        }>;
-        /**
-         * The dimensions of the preview image.
-         */
-        previewSize: Dimensions;
-        /**
-         * The dimensions of the full-size video.
-         *
-         * @remarks
-         * - These dimensions are used when adding the video to the design
-         * - If omitted, the `previewSize` dimensions are used as a fallback.
-         */
-        fullSize?: Dimensions;
-        /**
-         * The URL of an image to display under the user's cursor during the drag and drop event.
-         */
-        previewUrl: string;
-    };
-
+    type: 'video';
     /**
-     * @public
-     * Video element or content to be added to the design at the end of a drag event.
+     * A unique identifier that points to a video asset in Canva's backend.
      */
-    export declare type VideoDragConfigForElement<E extends Element> = E extends HTMLImageElement ? Partial<VideoDragConfig> & Pick<VideoDragConfig, 'type' | 'resolveVideoRef'> : VideoDragConfig;
-
+    ref: VideoRef;
     /**
-     * @public
-     * An element that renders video content.
+     * A description of the image content.
+     *
+     * @remarks
+     * Use `undefined` for content with no description.
      */
-    export declare type VideoElement = {
-        /**
-         * The type of element.
-         */
-        type: 'video';
-        /**
-         * A unique identifier that points to a video asset in Canva's backend.
-         */
-        ref: VideoRef;
-        /**
-         * A description of the video content.
-         *
-         * @remarks
-         * Use `undefined` for content with no description.
-         */
-        altText: AltText | undefined;
-    };
+    altText?: AltText;
+};
 
+/**
+ * @beta
+ * Options for configuring the visible portion of a video.
+ */
+export declare type VideoImageBox = {
     /**
-     * @public
-     * An element that renders video content and has positional properties.
+     * The distance of the image box from the top edge of the video, in pixels.
+     */
+    top: number;
+    /**
+     * The distance of the image box from the left edge of the video, in pixels.
+     */
+    left: number;
+    /**
+     * The width of the image box, in pixels.
      */
-    export declare type VideoElementAtPoint = VideoElement & Point & (WidthAndHeight | Width | Height);
+    width: number;
+    /**
+     * The height of the image box, in pixels.
+     */
+    height: number;
+};
+
+/**
+ * @public
+ * The MIME type of a video file that's supported by Canva's backend.
+ *
+ * @remarks
+ * - GIFs are treated as videos, not images.
+ * - `"application/json"` is only used for Lottie files.
+ */
+declare type VideoMimeType = 'video/avi' | 'video/x-msvideo' | 'image/gif' | 'video/x-m4v' | 'video/x-matroska' | 'video/quicktime' | 'video/mp4' | 'video/mpeg' | 'video/webm' | 'application/json';
+
+/**
+ * @public
+ * A unique identifier that references a video asset in Canva's backend.
+ */
+export declare type VideoRef = string & {
+    __videoRef: never;
+};
 
+/**
+ * @public
+ * A unique identifier that points to a video asset in Canva's backend.
+ */
+declare type VideoRef_2 = string & {
+    __videoRef: never;
+};
+
+/**
+ * @beta
+ * Options for configuring the start and end points for video playback.
+ */
+export declare type VideoTrim = {
     /**
-     * @public
-     * A video asset that fills a path's interior.
+     * The start point of the video, in seconds relative to the start of the source video.
      */
-    export declare type VideoFill = {
-        /**
-         * The type of fill.
-         */
-        type: 'video';
-        /**
-         * A unique identifier that points to a video asset in Canva's backend.
-         */
-        ref: VideoRef;
-        /**
-         * A description of the image content.
-         *
-         * @remarks
-         * Use `undefined` for content with no description.
-         */
-        altText?: AltText;
-    };
+    startInSeconds: number;
+    /**
+     * The end point of the video, in seconds relative to the start of the source video.
+     */
+    endInSeconds: number;
+};
 
+/**
+ * @public
+ * Options for uploading a video asset to the user's private media library.
+ */
+declare type VideoUploadOptions = {
     /**
-     * @public
-     * The MIME type of a video file that's supported by Canva's backend.
+     * The type of asset.
+     */
+    type: 'video';
+    /**
+     * A human-readable name for the video asset.
      *
      * @remarks
-     * - GIFs are treated as videos, not images.
-     * - `"application/json"` is only used for Lottie files.
+     * This name is displayed in the user's media library and helps users identify
+     * and find the asset later. If not provided, Canva will generate a name based
+     * on the asset's URL or a unique identifier.
+     *
+     * Requirements:
+     * - Minimum length: 1 character (empty strings are not allowed)
+     * - Maximum length: 255 characters
      */
-    declare type VideoMimeType = 'video/avi' | 'video/x-msvideo' | 'image/gif' | 'video/x-m4v' | 'video/x-matroska' | 'video/quicktime' | 'video/mp4' | 'video/mpeg' | 'video/webm' | 'application/json';
-
+    name?: string;
     /**
-     * @public
-     * A unique identifier that references a video asset in Canva's backend.
+     * The ref of the original asset from which this new asset was derived.
+     *
+     * @remarks
+     * For example, if an app applies an effect to a video, `parentRef` should contain the ref of the original video.
      */
-    export declare type VideoRef = string & {
-        __videoRef: never;
-    };
-
+    parentRef?: VideoRef_2;
     /**
-     * @public
-     * A unique identifier that points to a video asset in Canva's backend.
+     * The URL of the video file to upload.
+     *
+     * @remarks
+     * Requirements:
+     *
+     * - Must use HTTPS
+     * - Must return a `200` status code
+     * - `Content-Type` must match the file's MIME type
+     * - Must be publicly accessible (i.e. not a localhost URL)
+     * - Must not redirect
+     * - Must not contain an IP address
+     * - Maximum length: 4096 characters
+     * - Must not contain whitespace
+     * - Must not contain these characters: `>`, `<`, `{`, `}`, `^`, backticks
+     * - Maximum file size: 1000MB (1GB)
      */
-    declare type VideoRef_2 = string & {
-        __videoRef: never;
-    };
-
+    url: string;
     /**
-     * @public
-     * Options for uploading a video asset to the user's private media library.
+     * The MIME type of the video file.
      */
-    declare type VideoUploadOptions = {
-        /**
-         * The type of asset.
-         */
-        type: 'video';
-        /**
-         * A human-readable name for the video asset.
-         *
-         * @remarks
-         * This name is displayed in the user's media library and helps users identify
-         * and find the asset later. If not provided, Canva will generate a name based
-         * on the asset's URL or a unique identifier.
-         *
-         * Requirements:
-         * - Minimum length: 1 character (empty strings are not allowed)
-         * - Maximum length: 255 characters
-         */
-        name?: string;
-        /**
-         * The ref of the original asset from which this new asset was derived.
-         *
-         * @remarks
-         * For example, if an app applies an effect to a video, `parentRef` should contain the ref of the original video.
-         */
-        parentRef?: VideoRef_2;
-        /**
-         * The URL of the video file to upload.
-         *
-         * @remarks
-         * Requirements:
-         *
-         * - Must use HTTPS
-         * - Must return a `200` status code
-         * - `Content-Type` must match the file's MIME type
-         * - Must be publicly accessible (i.e. not a localhost URL)
-         * - Must not redirect
-         * - Must not contain an IP address
-         * - Maximum length: 4096 characters
-         * - Must not contain whitespace
-         * - Must not contain these characters: `>`, `<`, `{`, `}`, `^`, backticks
-         * - Maximum file size: 1000MB (1GB)
-         */
-        url: string;
-        /**
-         * The MIME type of the video file.
-         */
-        mimeType: VideoMimeType;
-        /**
-         * The URL of a thumbnail video to display while the video is queued for upload.
-         *
-         * @remarks
-         * Requirements:
-         *
-         * - Must use HTTPS
-         * - Must support [Cross-Origin Resource Sharing](https://www.canva.dev/docs/apps/cross-origin-resource-sharing/)
-         * - Maximum length: 4096 characters
-         * - The dimensions of the thumbnail video must match the video's aspect ratio to prevent the thumbnail from appearing squashed or stretched
-         * - Must not be an AVI file. Although our APIs support uploading AVI videos, Canva can't preview them because of native support of browsers
-         */
-        thumbnailVideoUrl?: string;
-        /**
-         * The URL of a thumbnail image to use as a fallback if `thumbnailVideoUrl` isn't provided.
-         * This can be an external URL or a data URL.
-         *
-         * @remarks
-         * Requirements for external URLs:
-         *
-         * - Must use HTTPS
-         * - Must support [Cross-Origin Resource Sharing](https://www.canva.dev/docs/apps/cross-origin-resource-sharing/)
-         * - Must be a PNG, JPEG, or SVG file
-         * - Maximum length: 4096 characters
-         *
-         * Requirements for data URLs:
-         *
-         * - Must include `;base64` for base64-encoded data
-         * - Maximum size: 10MB (10 × 1024 × 1024 characters)
-         * - The dimensions of the thumbnail must match the video's aspect ratio to prevent the thumbnail from appearing squashed or stretched
-         */
-        thumbnailImageUrl: string;
-        /**
-         * A disclosure identifying if the app generated this video using AI.
-         *
-         * @remarks
-         * Helps users make informed decisions about the content they interact with.
-         * See {@link AiDisclosure} for the full definition.
-         *
-         * **App Generated**
-         *
-         * 'app_generated' indicates when the app creates or significantly alters an asset using AI. Includes when
-         * the app requests a third-party service to take similar action on a video using AI.
-         *
-         *  Required for the following cases (this list is not exhaustive):
-         *  | Case                                                             | Reason                               |
-         *  | --                                                               | --                                   |
-         *  | AI generates a new video from scratch                            | Creates new creative content         |
-         *  | AI changes the style of the video e.g. makes it cartoon          | Significantly alters the style       |
-         *  | AI adds subtitles that rely on subjective interpretation         | Creates new creative content         |
-         *  | AI expands a video by generating new content to fill the edges   | Creates new creative content         |
-         *  | AI animates an image                                             | Creates new creative content         |
-         *  | AI fixes defects e.g. blur in a video by generating details      | Creates new creative content         |
-         *  | AI generates a talking head presenter                            | Creates new creative content         |
-         *
-         * **None**
-         *
-         * 'none' indicates when the app doesn't create or significantly alter an asset using AI, or as a part of
-         * a request to third-party hosted content.
-         *
-         * Required for the following cases (this list is not exhaustive):
-         *  | Case                                                     | Reason                                    |
-         *  | --                                                       | --                                        |
-         *  | Asset comes from an asset library                        | Didn't generate the asset itself          |
-         *  | AI corrects red eyes                                     | A minor correction                        |
-         *  | AI adjusts brightness and contrast on a video            | Doesn't change original meaning by itself |
-         *  | AI creates a slow motion effect in a video               | Doesn't change original meaning by itself |
-         *  | AI adds AI word-by-word transcribed subtitles to a video | Doesn't change original meaning by itself |
-         */
-        aiDisclosure: AiDisclosure;
+    mimeType: VideoMimeType;
+    /**
+     * The URL of a thumbnail video to display while the video is queued for upload.
+     *
+     * @remarks
+     * Requirements:
+     *
+     * - Must use HTTPS
+     * - Must support [Cross-Origin Resource Sharing](https://www.canva.dev/docs/apps/cross-origin-resource-sharing/)
+     * - Maximum length: 4096 characters
+     * - The dimensions of the thumbnail video must match the video's aspect ratio to prevent the thumbnail from appearing squashed or stretched
+     * - Must not be an AVI file. Although our APIs support uploading AVI videos, Canva can't preview them because of native support of browsers
+     */
+    thumbnailVideoUrl?: string;
+    /**
+     * The URL of a thumbnail image to use as a fallback if `thumbnailVideoUrl` isn't provided.
+     * This can be an external URL or a data URL.
+     *
+     * @remarks
+     * Requirements for external URLs:
+     *
+     * - Must use HTTPS
+     * - Must support [Cross-Origin Resource Sharing](https://www.canva.dev/docs/apps/cross-origin-resource-sharing/)
+     * - Must be a PNG, JPEG, or SVG file
+     * - Maximum length: 4096 characters
+     *
+     * Requirements for data URLs:
+     *
+     * - Must include `;base64` for base64-encoded data
+     * - Maximum size: 10MB (10 × 1024 × 1024 characters)
+     * - The dimensions of the thumbnail must match the video's aspect ratio to prevent the thumbnail from appearing squashed or stretched
+     */
+    thumbnailImageUrl: string;
+    /**
+     * A disclosure identifying if the app generated this video using AI.
+     *
+     * @remarks
+     * Helps users make informed decisions about the content they interact with.
+     * See {@link AiDisclosure} for the full definition.
+     *
+     * **App Generated**
+     *
+     * 'app_generated' indicates when the app creates or significantly alters an asset using AI. Includes when
+     * the app requests a third-party service to take similar action on a video using AI.
+     *
+     *  Required for the following cases (this list is not exhaustive):
+     *  | Case                                                             | Reason                               |
+     *  | --                                                               | --                                   |
+     *  | AI generates a new video from scratch                            | Creates new creative content         |
+     *  | AI changes the style of the video e.g. makes it cartoon          | Significantly alters the style       |
+     *  | AI adds subtitles that rely on subjective interpretation         | Creates new creative content         |
+     *  | AI expands a video by generating new content to fill the edges   | Creates new creative content         |
+     *  | AI animates an image                                             | Creates new creative content         |
+     *  | AI fixes defects e.g. blur in a video by generating details      | Creates new creative content         |
+     *  | AI generates a talking head presenter                            | Creates new creative content         |
+     *
+     * **None**
+     *
+     * 'none' indicates when the app doesn't create or significantly alter an asset using AI, or as a part of
+     * a request to third-party hosted content.
+     *
+     * Required for the following cases (this list is not exhaustive):
+     *  | Case                                                     | Reason                                    |
+     *  | --                                                       | --                                        |
+     *  | Asset comes from an asset library                        | Didn't generate the asset itself          |
+     *  | AI corrects red eyes                                     | A minor correction                        |
+     *  | AI adjusts brightness and contrast on a video            | Doesn't change original meaning by itself |
+     *  | AI creates a slow motion effect in a video               | Doesn't change original meaning by itself |
+     *  | AI adds AI word-by-word transcribed subtitles to a video | Doesn't change original meaning by itself |
+     */
+    aiDisclosure: AiDisclosure;
 
-    } & AllOrNone<Dimensions_2>;
+} & AllOrNone<Dimensions_2>;
 
+/**
+ * A set of dimensions with an auto-calculated height.
+ */
+declare type Width = {
     /**
-     * A set of dimensions with an auto-calculated height.
+     * A width, in pixels.
+     *
+     * @remarks
+     * - The pixels are relative to their container.
+     * - Minimum: 0
+     * - Maximum: 32767
      */
-    declare type Width = {
-        /**
-         * A width, in pixels.
-         *
-         * @remarks
-         * - The pixels are relative to their container.
-         * - Minimum: 0
-         * - Maximum: 32767
-         */
-        width: number;
-        /**
-         * Indicates that the height should be auto-calculated.
-         */
-        height: 'auto';
-    };
-
+    width: number;
     /**
-     * A set of dimensions, in pixels.
+     * Indicates that the height should be auto-calculated.
      */
-    declare type WidthAndHeight = {
-        /**
-         * A width, in pixels.
-         *
-         * @remarks
-         * - The pixels are relative to their container.
-         * - Minimum: 0
-         * - Maximum: 32767
-         */
-        width: number;
-        /**
-         * A height, in pixels.
-         *
-         * @remarks
-         * - The pixels are relative to their container.
-         * - Minimum: 0
-         * - Maximum: 32767
-         */
-        height: number;
-    };
+    height: 'auto';
+};
 
+/**
+ * A set of dimensions, in pixels.
+ */
+declare type WidthAndHeight = {
     /**
-     * @public
-     * The behavior of zipping the exported files.
+     * A width, in pixels.
      *
      * @remarks
-     * For `png`, `jpg`, and `svg`:
-     * - `auto` (default): Files are zipped together if the design has multiple pages, unzipped if it has one page.
-     * - `always`: Files are always zipped into a single zip file, regardless of page count.
-     * - `never`: Files are never zipped, providing an array of files.
+     * - The pixels are relative to their container.
+     * - Minimum: 0
+     * - Maximum: 32767
+     */
+    width: number;
+    /**
+     * A height, in pixels.
      *
-     * For `video` and `gif`:
-     * - `auto` or `never` (default): Files are never zipped together, regardless of count.
-     * - `always`: Files are always zipped into a single file.
+     * @remarks
+     * - The pixels are relative to their container.
+     * - Minimum: 0
+     * - Maximum: 32767
      */
-    export declare type ZipBehavior = 'auto' | 'always' | 'never';
+    height: number;
+};
+
+/**
+ * @public
+ * The behavior of zipping the exported files.
+ *
+ * @remarks
+ * For `png`, `jpg`, and `svg`:
+ * - `auto` (default): Files are zipped together if the design has multiple pages, unzipped if it has one page.
+ * - `always`: Files are always zipped into a single zip file, regardless of page count.
+ * - `never`: Files are never zipped, providing an array of files.
+ *
+ * For `video` and `gif`:
+ * - `auto` or `never` (default): Files are never zipped together, regardless of count.
+ * - `always`: Files are always zipped into a single file.
+ */
+export declare type ZipBehavior = 'auto' | 'always' | 'never';
 
-    export { }
+export { }