@canva/intents 0.0.0-beta.2

package/beta.d.ts

@@ -0,0 +1,975 @@
+/**
+ * @beta
+ * {@link FetchDataTableError} indicating custom error occurred in the app's implementation.
+ * This can be used to indicate specific issues that are not covered by other error types.
+ */
+declare type AppError = {
+  /**
+   * A custom error occurred in your app.
+   *
+   * Return this for application-specific errors that don't fit
+   * the other categories. Include a descriptive message explaining
+   * the error to the user.
+   */
+  status: "app_error";
+  /**
+   * Optional message explaining the error.
+   */
+  message?: string;
+};
+
+/**
+ * @beta
+ * {@link InvocationContext} indicating a custom error occurred during data refresh.
+ * Triggered when fetchDataTable returned 'app_error' status.
+ * UI should display the error message and help users recover.
+ */
+declare type AppErrorInvocationContext = {
+  /**
+   * A custom error occurred during data refresh.
+   *
+   * This occurs when `fetchDataTable` returned 'app_error' during a refresh attempt.
+   * Your UI should display the error message and help users recover from the specific
+   * issue.
+   */
+  reason: "app_error";
+  /**
+   * The data source reference that caused the error during refresh.
+   */
+  dataSourceRef?: DataSourceRef;
+  /**
+   * The error message to display to the user.
+   */
+  message?: string;
+};
+
+/**
+ * @beta
+ * Cell containing a boolean value.
+ *
+ * @example Creating a boolean cell
+ * ```ts
+ * import type { BooleanDataTableCell } from '@canva/intents/data';
+ *
+ * const isActiveCell: BooleanDataTableCell = {
+ *   type: 'boolean',
+ *   value: true
+ * };
+ * ```
+ *
+ * @example Creating a boolean cell with false value
+ * ```ts
+ * import type { BooleanDataTableCell } from '@canva/intents/data';
+ *
+ * const isCompleteCell: BooleanDataTableCell = {
+ *   type: 'boolean',
+ *   value: false
+ * };
+ * ```
+ *
+ * @example Creating an empty boolean cell
+ * ```ts
+ * import type { BooleanDataTableCell } from '@canva/intents/data';
+ *
+ * const emptyBooleanCell: BooleanDataTableCell = {
+ *   type: 'boolean',
+ *   value: undefined
+ * };
+ * ```
+ */
+export declare type BooleanDataTableCell = {
+  /**
+   * Indicates this cell contains a boolean value.
+   */
+  type: "boolean";
+  /**
+   * Boolean value (true or false).
+   *
+   * Use `undefined` for an empty cell.
+   */
+  value: boolean | undefined;
+};
+
+/**
+ * @beta
+ * Configuration for a table column.
+ */
+export declare type ColumnConfig = {
+  /**
+   * Name for the column, displayed as header text.
+   *
+   * If `undefined`, the column will have no header text.
+   */
+  name: string | undefined;
+  /**
+   * Expected data type for cells in this column.
+   *
+   * Use a specific `DataType` for columns with consistent types,
+   * or `'variant'` for columns that may contain mixed types.
+   */
+  type: DataType | "variant";
+};
+
+declare namespace data {
+  export {
+    prepareDataConnector,
+    DataConnectorIntent,
+    FetchDataTableParams,
+    RenderSelectionUiParams,
+    InvocationContext,
+    FetchDataTableResult,
+    FetchDataTableCompleted,
+    DataTableMetadata,
+    FetchDataTableError,
+    ValidationError,
+    InternalError,
+    UpdateDataRefResult,
+    DataSourceRef,
+    DataTableLimit,
+    DataType,
+    DataTable,
+    ColumnConfig,
+    DataTableRow,
+    DataTableCell,
+    DateDataTableCell,
+    StringDataTableCell,
+    NumberDataTableCell,
+    NumberCellMetadata,
+    BooleanDataTableCell,
+  };
+}
+export { data };
+
+/**
+ * @beta
+ * Main interface for implementing the Data Connector intent.
+ *
+ * Implementing the Data Connector intent enables apps to import external data into Canva.
+ * This allows users to select, preview, and refresh data from external sources.
+ */
+export declare type DataConnectorIntent = {
+  /**
+   * Fetches structured data from an external source.
+   *
+   * This action is called in two scenarios:
+   *
+   * - During data selection to preview data before import (when {@link RenderSelectionUiParams.updateDataRef} is called).
+   * - When refreshing previously imported data (when the user requests an update).
+   *
+   * @param params - Parameters for the data fetching operation.
+   * @returns A promise resolving to either a successful result with data or an error.
+   *
+   * @example Fetching data from an external source
+   * ```ts
+   * import type { FetchDataTableParams, FetchDataTableResult } from '@canva/intents/data';
+   *
+   * async function fetchDataTable(params: FetchDataTableParams): Promise<FetchDataTableResult> {
+   *   const { dataSourceRef, limit, signal } = params;
+   *
+   *   // Check if the operation has been aborted.
+   *   if (signal.aborted) {
+   *     return { status: 'app_error', message: 'The data fetch operation was cancelled.' };
+   *   }
+   *
+   *   // ... data fetching logic using dataSourceRef, limit, and signal ...
+   *
+   *   // Placeholder for a successful result.
+   *   return {
+   *     status: 'completed',
+   *     dataTable: { rows: [{ cells: [{ type: 'string', value: 'Fetched data' }] }] }
+   *   };
+   * }
+   * ```
+   */
+  fetchDataTable: (
+    params: FetchDataTableParams,
+  ) => Promise<FetchDataTableResult>;
+  /**
+   * Renders a user interface for selecting and configuring data from your external sources.
+   *
+   * @param params - Configuration and callbacks for the data selection UI.
+   *
+   * @example Rendering a data selection UI
+   * ```ts
+   * import type { RenderSelectionUiParams } from '@canva/intents/data';
+   *
+   * async function renderSelectionUi(params: RenderSelectionUiParams): Promise<void> {
+   *   // UI rendering logic.
+   *   // Example: if user selects data 'ref123'.
+   *   const selectedRef = { source: 'ref123', title: 'My Selected Table' };
+   *   try {
+   *     const result = await params.updateDataRef(selectedRef);
+   *     if (result.status === 'completed') {
+   *       console.log('Selection valid and preview updated.');
+   *     } else {
+   *       console.error('Selection error:', result.status);
+   *     }
+   *   } catch (error) {
+   *      console.error('An unexpected error occurred during data ref update:', error);
+   *   }
+   * }
+   * ```
+   */
+  renderSelectionUi: (params: RenderSelectionUiParams) => void;
+};
+
+/**
+ * @beta
+ * {@link InvocationContext} indicating initial data selection flow or edit of existing data.
+ */
+declare type DataSelectionInvocationContext = {
+  /**
+   * Initial data selection or editing existing data.
+   *
+   * This is the standard flow when:
+   *
+   * - A user is selecting data for the first time
+   * - A user is editing a previous selection
+   *
+   * If `dataSourceRef` is provided, this indicates an edit flow, and you should
+   * pre-populate your UI with this selection.
+   */
+  reason: "data_selection";
+  /**
+   * If dataSourceRef is provided, this is an edit of existing data flow and UI should be pre-populated.
+   */
+  dataSourceRef?: DataSourceRef;
+};
+
+/**
+ * @beta
+ * Reference to an external data source that can be used to fetch data.
+ * Created by Data Connector apps and stored by Canva for data refresh operations.
+ *
+ * You create this object in your data selection UI and pass it to the
+ * `updateDataRef` callback. Canva stores this reference and uses it for
+ * future data refresh operations.
+ *
+ * Maximum size: 5KB
+ *
+ * @example Defining how to locate external data
+ * ```ts
+ * const dataSourceRef: DataSourceRef = {
+ *   source: JSON.stringify({
+ *     reportId: "monthly_sales_001",
+ *     filters: { year: 2023, region: "NA" }
+ *   }),
+ *   title: "Monthly Sales Report (NA, 2023)"
+ * };
+ * ```
+ */
+export declare type DataSourceRef = {
+  /**
+   * Information needed to identify and retrieve data from your source.
+   *
+   * This string should contain all the information your app needs to
+   * fetch the exact data selection later. Typically, this is a serialized
+   * object with query parameters, identifiers, or filters.
+   *
+   * You are responsible for encoding and decoding this value appropriately.
+   *
+   * Maximum size: 5KB
+   */
+  source: string;
+  /**
+   * A human-readable description of the data reference.
+   *
+   * This title may be displayed to users in the Canva interface to help
+   * them identify the data source.
+   *
+   * Maximum length: 255 characters
+   */
+  title?: string;
+};
+
+/**
+ * @beta
+ * {@link ValidationError} indicating the data source reference {@link DataSourceRef} exceeds the 5KB size limit.
+ */
+declare type DataSourceRefLimitExceeded = {
+  /**
+   * The data source reference exceeds the 5KB size limit.
+   *
+   * Your app should reduce the size of the `DataSourceRef.source` string.
+   */
+  status: "data_source_ref_limit_exceeded";
+};
+
+/**
+ * @beta
+ * {@link ValidationError} indicating the data source title {@link DataSourceRef.title} exceeds the 255 character limit.
+ */
+declare type DataSourceTitleLimitExceed = {
+  /**
+   * The data source title exceeds the 255 character limit.
+   *
+   * Your app should provide a shorter title for the data source.
+   */
+  status: "data_source_title_limit_exceeded";
+};
+
+/**
+ * @beta
+ * Structured tabular data for import into Canva.
+ *
+ * This format allows you to provide typed data with proper formatting
+ * to ensure it displays correctly in Canva designs.
+ *
+ * @example Creating a data table
+ * ```ts
+ * import type { ColumnConfig, DataTableCell, DataTable, DataTableRow } from '@canva/intents/data';
+ *
+ * const myTable: DataTable = {
+ *   columnConfigs: [
+ *     { name: 'Name', type: 'string' },
+ *     { name: 'Age', type: 'number' },
+ *     { name: 'Subscribed', type: 'boolean' },
+ *     { name: 'Join Date', type: 'date' }
+ *   ],
+ *   rows: [
+ *     {
+ *       cells: [
+ *         { type: 'string', value: 'Alice' },
+ *         { type: 'number', value: 30 },
+ *         { type: 'boolean', value: true },
+ *         { type: 'date', value: Math.floor(new Date('2023-01-15').getTime() / 1000) }
+ *       ]
+ *     },
+ *     {
+ *       cells: [
+ *         { type: 'string', value: 'Bob' },
+ *         { type: 'number', value: 24 },
+ *         { type: 'boolean', value: false },
+ *         { type: 'date', value: Math.floor(new Date('2022-07-20').getTime() / 1000) }
+ *       ]
+ *     }
+ *   ]
+ * };
+ * ```
+ */
+export declare type DataTable = {
+  /**
+   * Column definitions with names and data types.
+   *
+   * These help Canva interpret and display your data correctly.
+   */
+  columnConfigs?: ColumnConfig[];
+  /**
+   * The data rows containing the actual values.
+   *
+   * Each row contains an array of cells with typed data values.
+   */
+  rows: DataTableRow[];
+};
+
+/**
+ * @beta
+ * Generic type for table cells that resolves to a specific cell type.
+ */
+export declare type DataTableCell<T extends DataType = DataType> = {
+  date: DateDataTableCell;
+  string: StringDataTableCell;
+  number: NumberDataTableCell;
+  boolean: BooleanDataTableCell;
+}[T];
+
+/**
+ * @beta
+ * {@link ValidationError} indicating the data table format is invalid.
+ *
+ * This can happen due to:
+ *
+ * - {@link DataType} mismatches (e.g., a number in a string-typed column, a number value in a string cell type)
+ * - Unsupported cell types
+ * - Inconsistent column configurations (e.g., the number of columns in the data table does not match the number of {@link ColumnConfig})
+ */
+declare type DataTableInvalidFormat = {
+  /**
+   * The data table format is invalid.
+   *
+   * This error occurs due to:
+   *
+   * - Data type mismatches (e.g., number in string column)
+   * - Unsupported cell types
+   * - Inconsistent column configurations
+   *
+   * Your app should ensure the data conforms to the expected format.
+   */
+  status: "data_table_invalid_format";
+};
+
+/**
+ * @beta
+ * Maximum dimensions for imported data tables.
+ */
+export declare type DataTableLimit = {
+  /**
+   * The maximum number of rows allowed.
+   *
+   * Your app should ensure data does not exceed this limit.
+   */
+  row: number;
+  /**
+   * The maximum number of columns allowed.
+   *
+   * Your app should ensure data does not exceed this limit.
+   */
+  column: number;
+};
+
+/**
+ * @beta
+ * {@link ValidationError} indicating that the data table exceeds the allowed limits.
+ *
+ * This can happen when:
+ * - Number of rows exceeds the row limit
+ * - Number of columns exceeds the column limit
+ * - Total data size exceeds 200KB
+ */
+declare type DataTableLimitExceeded = {
+  /**
+   * The data exceeds the maximum allowed limits.
+   *
+   * This error occurs when:
+   *
+   * - Number of rows exceeds the row limit
+   * - Number of columns exceeds the column limit
+   * - Total data size exceeds the allowed size limit
+   *
+   * Your app should help users select a subset of their data,
+   * or provide filtering options to reduce the data size.
+   */
+  status: "data_table_limit_exceeded";
+};
+
+/**
+ * @beta
+ * Metadata providing additional context about the imported data.
+ */
+export declare type DataTableMetadata = {
+  /**
+   * A human-readable description of the dataset.
+   *
+   * This description helps users understand what data they are importing.
+   */
+  description?: string;
+  /**
+   * Information about the data provider or source.
+   */
+  providerInfo?: {
+    /**
+     * Name of the data provider.
+     */
+    name: string;
+    /**
+     * URL to the provider's website or related resource.
+     */
+    url?: string;
+  };
+};
+
+/**
+ * @beta
+ * {@link ValidationError} indicating the provided data table metadata is invalid (e.g not a valid OXML formatting string in {@link NumberCellMetadata.formatting}).
+ */
+declare type DataTableMetadataInvalid = {
+  /**
+   * The provided metadata is invalid.
+   *
+   * This typically happens with invalid formatting patterns in {@link NumberCellMetadata.formatting} strings.
+   */
+  status: "data_table_metadata_invalid";
+};
+
+/**
+ * @beta
+ * A row in the data table.
+ *
+ * @example Creating a single row of data cells
+ * ```ts
+ * import type { DataTableCell, DataTableRow } from '@canva/intents/data';
+ *
+ * const row: DataTableRow = {
+ *   cells: [
+ *     { type: 'string', value: 'Product Alpha' },
+ *     { type: 'number', value: 199.99 },
+ *     { type: 'boolean', value: true }
+ *   ]
+ * };
+ * ```
+ */
+export declare type DataTableRow = {
+  /**
+   * Array of cells containing the data values.
+   *
+   * Each cell must have a type that matches the corresponding column definition (if provided).
+   */
+  cells: DataTableCell<DataType>[];
+};
+
+/**
+ * @beta
+ * Data types supported for table cells.
+ */
+export declare type DataType = "string" | "number" | "date" | "boolean";
+
+/**
+ * @beta
+ * Cell containing a date value.
+ *
+ * @example Creating a date cell
+ * ```ts
+ * import type { DateDataTableCell } from '@canva/intents/data';
+ *
+ * const todayCell: DateDataTableCell = {
+ *   type: 'date',
+ *   value: Math.floor(Date.now() / 1000) // Unix timestamp in seconds
+ * };
+ *
+ * const emptyDateCell: DateDataTableCell = {
+ *   type: 'date',
+ *   value: undefined
+ * };
+ * ```
+ */
+export declare type DateDataTableCell = {
+  /**
+   * Indicates this cell contains a date value.
+   */
+  type: "date";
+  /**
+   * Unix timestamp in seconds representing the date.
+   *
+   * Use `undefined` for an empty cell.
+   */
+  value: number | undefined;
+};
+
+declare namespace design {
+  export { prepareDesignEditor, DesignEditorIntent };
+}
+export { design };
+
+/**
+ * @beta
+ *
+ * Main interface for implementing the DesignEditor intent.
+ *
+ * Implementing the DesignEditor Intent enables apps to assist users in editing designs,
+ * by presenting interactive and creative tooling alongside the Canva design surface.
+ */
+export declare type DesignEditorIntent = {
+  /**
+   * Renders the UI containing the app’s functionality.
+   *
+   * @example
+   * ```tsx
+   * function render() {
+   *   // render your UI using your preferred framework
+   * }
+   * ```
+   */
+  render: () => void;
+};
+
+/**
+ * @beta
+ * Successful result from `fetchDataTable` action.
+ */
+export declare type FetchDataTableCompleted = {
+  /**
+   * Indicates the fetch operation completed successfully
+   */
+  status: "completed";
+  /**
+   * The fetched data formatted as a data table.
+   */
+  dataTable: DataTable;
+  /**
+   * Optional metadata providing additional context about the data.
+   */
+  metadata?: DataTableMetadata;
+};
+
+/**
+ * @beta
+ * Error results that can be returned from `fetchDataTable` method.
+ */
+export declare type FetchDataTableError =
+  | OutdatedSourceRefError
+  | RemoteRequestFailedError
+  | AppError;
+
+/**
+ * @beta
+ * Parameters for the fetchDataTable action.
+ */
+export declare type FetchDataTableParams = {
+  /**
+   * Reference to the data source to fetch.
+   *
+   * This contains the information needed to identify and retrieve the specific data
+   * that was previously selected by the user.
+   *
+   * Use this to query your external data service.
+   */
+  dataSourceRef: DataSourceRef;
+  /**
+   * Maximum row and column limits for the imported data.
+   *
+   * Your app must ensure the returned data does not exceed these limits.
+   *
+   * If the requested data would exceed these limits, either:
+   *
+   * - Truncate the data to fit within limits, or
+   * - Return a 'data_table_limit_exceeded' error
+   */
+  limit: DataTableLimit;
+  /**
+   * Standard DOM AbortSignal for cancellation support.
+   *
+   * Your app should monitor this signal and abort any ongoing operations if it becomes aborted.
+   */
+  signal: AbortSignal;
+};
+
+/**
+ * @beta
+ * Result returned from the `fetchDataTable` action.
+ */
+export declare type FetchDataTableResult =
+  | FetchDataTableCompleted
+  | FetchDataTableError;
+
+/**
+ * @beta
+ * System errors that may occur during data operations.
+ */
+export declare type InternalError = {
+  /**
+   * An unexpected system error occurred.
+   *
+   * These errors are typically not related to your app's implementation
+   * but indicate issues with the platform.
+   */
+  status: "internal_error";
+  /**
+   * The cause of the error.
+   */
+  cause?: unknown;
+};
+
+/**
+ * @beta
+ * Information explaining why the data selection UI was launched.
+ */
+export declare type InvocationContext =
+  | DataSelectionInvocationContext
+  | OutdatedSourceRefInvocationContext
+  | AppErrorInvocationContext;
+
+/**
+ * @beta
+ * Formatting metadata for number cells.
+ *
+ * @example Formatting as currency
+ * ```ts
+ * import type { NumberDataTableCell } from '@canva/intents/data';
+ *
+ * const currencyCell: NumberDataTableCell = {
+ *   type: 'number',
+ *   value: 1234.57,
+ *   metadata: { formatting: '[$$]#,##0.00' }
+ * };
+ * ```
+ *
+ * @example Formatting as a percentage
+ * ```ts
+ * import type { NumberDataTableCell } from '@canva/intents/data';
+ *
+ * const percentCell: NumberDataTableCell = {
+ *   type: 'number',
+ *   value: 0.1234,
+ *   metadata: { formatting: '0.00%' }
+ * };
+ * ```
+ *
+ * @example Applying a thousands separator
+ * ```ts
+ * import type { NumberDataTableCell } from '@canva/intents/data';
+ *
+ * const largeNumberCell: NumberDataTableCell = {
+ *   type: 'number',
+ *   value: 1234567.89234,
+ *   metadata: { formatting: '#,##0.00' }
+ * };
+ * ```
+ */
+export declare type NumberCellMetadata = {
+  /**
+   * Formatting pattern using Office Open XML Format.
+   *
+   * These patterns control how numbers are displayed to users,
+   * including currency symbols, decimal places, and separators.
+   */
+  formatting?: string;
+};
+
+/**
+ * @beta
+ * Cell containing a numeric value.
+ *
+ * @example Creating a number cell
+ * ```ts
+ * import type { NumberCellMetadata, NumberDataTableCell } from '@canva/intents/data';
+ *
+ * const priceCell: NumberDataTableCell = {
+ *   type: 'number',
+ *   value: 29.99,
+ *   metadata: { formatting: '[$$]#,##0.00' }
+ * };
+ *
+ * const quantityCell: NumberDataTableCell = {
+ *   type: 'number',
+ *   value: 150
+ * };
+ *
+ * const emptyNumberCell: NumberDataTableCell = {
+ *   type: 'number',
+ *   value: undefined
+ * };
+ * ```
+ */
+export declare type NumberDataTableCell = {
+  /**
+   * Indicates this cell contains a number value.
+   */
+  type: "number";
+  /**
+   * Numeric value within safe integer range.
+   *
+   * Valid range: `Number.MIN_SAFE_INTEGER` to `Number.MAX_SAFE_INTEGER`
+   *
+   * Invalid values:
+   *
+   * - Infinity or -Infinity
+   * - NaN
+   * - Negative zero (-0)
+   * - Denormalized numbers
+   *
+   * Use `undefined` for an empty cell.
+   */
+  value: number | undefined;
+  /**
+   * Optional formatting information for displaying the number.
+   *
+   * @example Applying display formatting to a number
+   * ```ts
+   * import type { NumberCellMetadata } from '@canva/intents/data';
+   *
+   * const currencyFormatting: NumberCellMetadata = { formatting: '[$USD]#,##0.00' };
+   * const percentageFormatting: NumberCellMetadata = { formatting: '0.00%' };
+   * ```
+   */
+  metadata?: NumberCellMetadata;
+};
+
+/**
+ * @beta
+ * {@link FetchDataTableError} indicating the data source reference is no longer valid.
+ * This will trigger a re-selection flow for the user.
+ */
+declare type OutdatedSourceRefError = {
+  /**
+   * The data source reference is no longer valid.
+   *
+   * Return this error when the DataSourceRef cannot be used to retrieve data,
+   * for example:
+   *
+   * - The referenced dataset has been deleted
+   * - Access permissions have changed
+   * - The structure of the data has fundamentally changed
+   *
+   * This will trigger a re-selection flow, allowing the user to choose a new
+   * data source.
+   */
+  status: "outdated_source_ref";
+};
+
+/**
+ * @beta
+ * {@link InvocationContext} indicating an error occurred because the previously selected data source reference is no longer valid.
+ * Triggered when fetchDataTable returned 'outdated_source_ref' during data refresh.
+ * UI should guide the user to reselect or reconfigure their data.
+ */
+declare type OutdatedSourceRefInvocationContext = {
+  /**
+   * Previously selected data source reference is no longer valid.
+   *
+   * This occurs when `fetchDataTable` returned 'outdated_source_ref' during a
+   * refresh attempt. Your UI should guide the user to select a new data source
+   * or update their selection.
+   *
+   * The outdated reference is provided to help you suggest an appropriate replacement.
+   */
+  reason: "outdated_source_ref";
+  /**
+   * The outdated data source reference that caused the error during refresh.
+   */
+  dataSourceRef?: DataSourceRef;
+};
+
+/**
+ * @beta
+ *
+ * Prepares the `DataConnectorIntent`.
+ */
+declare const prepareDataConnector: (
+  implementation: DataConnectorIntent,
+) => void;
+
+/**
+ * @beta
+ *
+ * Prepares a {@link DesignEditorIntent|DesignEditor Intent}.
+ *
+ * @example
+ * ```tsx
+ * import { prepareDesignEditor } from '@canva/intents/design';
+ *
+ * function render() {
+ *   // render your UI using your preferred framework
+ * }
+ *
+ * prepareDesignEditor({
+ *   render,
+ * });
+ * ```
+ */
+declare const prepareDesignEditor: (implementation: DesignEditorIntent) => void;
+
+/**
+ * @beta
+ * {@link FetchDataTableError} indicating failure to fetch data from the external source.
+ * Typically due to network issues or API failures.
+ */
+declare type RemoteRequestFailedError = {
+  /**
+   * Failed to fetch data from the external source.
+   *
+   * Return this error for network issues, API failures, or other
+   * connectivity problems that prevent data retrieval.
+   */
+  status: "remote_request_failed";
+};
+
+/**
+ * @beta
+ * Parameters for rendering the data selection UI.
+ */
+export declare type RenderSelectionUiParams = {
+  /**
+   * Context information about why the data selection UI is being launched.
+   *
+   * Use this to adapt your UI for different scenarios:
+   *
+   * - 'data_selection': Initial data selection or editing existing data
+   * - 'outdated_source_ref': Previous reference is no longer valid, guide user to reselect
+   * - 'app_error': Custom error occurred, show error message and recovery options
+   *
+   * When `dataSourceRef` is provided, pre-populate your UI with this selection.
+   */
+  invocationContext: InvocationContext;
+  /**
+   * Maximum allowed rows and columns for the imported data.
+   *
+   * Your UI should inform users of these constraints and prevent or warn about
+   * selections that would exceed them. This helps users understand why certain
+   * data sets might not be available for selection.
+   */
+  limit: DataTableLimit;
+  /**
+   * Callback to preview selected data before finalizing import.
+   *
+   * Call this function when the user selects data to:
+   *
+   * 1. Show a preview of the selected data to the user
+   * 2. Validate that the selection meets system requirements
+   *
+   * Calling this function will trigger your `fetchDataTable` implementation.
+   * Wait for the promise to resolve to determine if the selection is valid.
+   *
+   * @param dataSourceRef - Reference object identifying the selected data
+   * @returns Promise resolving to success or an error result
+   */
+  updateDataRef: (dataSourceRef: DataSourceRef) => Promise<UpdateDataRefResult>;
+};
+
+/**
+ * @beta
+ * Cell containing a text value.
+ *
+ * @example Creating a string cell
+ * ```ts
+ * import type { StringDataTableCell } from '@canva/intents/data';
+ *
+ * const nameCell: StringDataTableCell = {
+ *   type: 'string',
+ *   value: 'John Doe'
+ * };
+ *
+ * const emptyStringCell: StringDataTableCell = {
+ *   type: 'string',
+ *   value: undefined
+ * };
+ * ```
+ */
+export declare type StringDataTableCell = {
+  /**
+   * Indicates this cell contains a string value.
+   */
+  type: "string";
+  /**
+   * Text content of the cell.
+   *
+   * Maximum length: 10,000 characters
+   *
+   * Use `undefined` for an empty cell.
+   */
+  value: string | undefined;
+};
+
+/**
+ * @beta
+ * Successful result from the {@link RenderSelectionUiParams.updateDataRef} callback.
+ */
+declare type UpdateDataRefCompleted = {
+  /**
+   * The data selection was successful and can be previewed.
+   */
+  status: "completed";
+};
+
+/**
+ * @beta
+ * Result returned from the {@link RenderSelectionUiParams.updateDataRef} callback.
+ * Indicates whether {@link DataSourceRef} update succeeded or failed.
+ */
+export declare type UpdateDataRefResult =
+  | UpdateDataRefCompleted
+  | FetchDataTableError
+  | ValidationError
+  | InternalError;
+
+/**
+ * @beta
+ * Validation errors that can occur when processing data.
+ */
+export declare type ValidationError =
+  | DataTableLimitExceeded
+  | DataTableInvalidFormat
+  | DataTableMetadataInvalid
+  | DataSourceRefLimitExceeded
+  | DataSourceTitleLimitExceed;
+
+export {};