@canva/design 1.9.0 → 1.10.0-beta.1

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

@@ -5,6 +5,20 @@
  */
 export declare function addAudioTrack(audioTrack: AudioTrack): Promise<void>;
 
+/**
+ * @beta
+ * Adds a native element to the user's design.
+ * @param element - The element to add to the user's design.
+ */
+export declare function addNativeElement(
+  element:
+    | NativeElement
+    | NativeElementWithBox
+    | NativeTableElement
+    | NativeRichtextElement
+    | NativeRichtextElementWithBox
+): Promise<void>;
+
 /**
  * @public
  * Adds a native element to the user's design.
@@ -30,6 +44,23 @@ export declare function addPage(opts?: {
   title?: string;
 }): Promise<void>;
 
+/**
+ * @public
+ * Describes any alt-text that will be added for a11y.
+ */
+export declare type AltText = {
+  /**
+   * The text that will appear as alt-text.
+   */
+  text: string;
+  /**
+   * An optional property that will determine whether text is shown in just the editor or both editor and view mode.
+   * If set to true, alt-text will only be rendered inside the editor.
+   * If set to false or omitted, alt-text will be rendered in both the editor and in view only mode.
+   */
+  decorative: boolean | undefined;
+};
+
 /**
  * @public
  * A callback that runs when an app element's data is created or updated,
@@ -151,6 +182,24 @@ export declare type AudioTrack = {
   ref: AudioRef;
 };
 
+/**
+ * @beta
+ * The boundaries of a rich text region.
+ */
+export declare type Bounds = {
+  /**
+   * The index of the character from which the region starts.
+   *
+   * @remarks
+   * A value of `0` means the region starts from the first character.
+   */
+  index: number;
+  /**
+   * The length of the text region.
+   */
+  length: number;
+};
+
 /**
  * @public
  * The dimensions, position, and rotation of an element.
@@ -160,6 +209,31 @@ export declare type AudioTrack = {
  */
 export declare type Box = Position & (WidthAndHeight | Width | Height);
 
+/**
+ * @beta
+ * A cell for a NativeTableElement. Cells can have text content and a background color.
+ * A cell can also be sized by setting the colSpan and rowSpan values for how many columns
+ * and rows the cell occupies respectively.
+ */
+export declare type Cell = {
+  /**
+   * The text content of the table cell
+   */
+  text?: NativeTextElement;
+  /**
+   * The background of the table cell
+   */
+  fill?: Pick<Fill, "color">;
+  /**
+   * How many columns this cell occupies
+   */
+  colSpan?: number;
+  /**
+   * How many rows this cell occupies
+   */
+  rowSpan?: number;
+};
+
 declare type CommonImageDragConfig = {
   /**
    * The type of element.
@@ -198,6 +272,20 @@ export declare interface ContentDraft<T> {
   save(): Promise<void>;
 }
 
+/**
+ * @beta
+ * A type of content that can be read from a user's design.
+ */
+export declare type ContentType = "richtext";
+
+/**
+ * @beta
+ * Options for configuring where content in a design should be queried from.
+ */
+declare type ContextOptions = {
+  context: "current_page";
+};
+
 /**
  * @public
  * Represents X and Y coordinates.
@@ -213,6 +301,12 @@ export declare type Coordinates = {
   y: number;
 };
 
+/**
+ * @beta
+ * Creates a new RichtextRange object, which contains methods to manipulate text.
+ */
+export declare function createRichtextRange(): RichtextRange;
+
 /**
  * @public
  * Provides methods for interacting with design overlay
@@ -231,7 +325,7 @@ export declare type DesignOverlay = {
 };
 
 /**
- * @public
+ * @beta
  * Provides methods for interacting with the user's selected content, such as images or text.
  */
 export declare type DesignSelection = {
@@ -312,6 +406,14 @@ export declare type DragStartEvent<E extends Element> = Pick<
   currentTarget: E;
 };
 
+/**
+ * @beta
+ * Options for configuring how a design is read.
+ */
+export declare type EditContentOptions<T extends ContentType> = {
+  contentType: T;
+} & ContextOptions;
+
 /**
  * @public
  * Options for making an `HTMLElement` draggable.
@@ -646,6 +748,50 @@ export declare function initAppElement<A extends AppElementData>(
   appElementConfig: AppElementClientConfiguration<A>
 ): AppElementClient<A>;
 
+/**
+ * @beta
+ *
+ * Inline formatting values for richtext
+ */
+export declare type InlineFormatting = {
+  /**
+   * The color of the text as a hex code.
+   *
+   * @remarks
+   * The hex code must include all six characters and be prefixed with a # symbol
+   * (e.g. #ff0099). The default value is #000000.
+   */
+  color?: string;
+  /**
+   * The weight (thickness) of the font.
+   *
+   * @remarks
+   * The available font weights depend on the font.
+   *
+   * @defaultValue 'normal'
+   */
+  fontWeight?: FontWeight;
+  /**
+   * The style of the font.
+   * @defaultValue 'normal'
+   */
+  fontStyle?: "normal" | "italic";
+  /**
+   * The decoration of the text.
+   * @defaultValue 'none'
+   */
+  decoration?: "none" | "underline";
+  /**
+   * The strikethrough of the text.
+   * @defaultValue 'none'
+   */
+  strikethrough?: "none" | "strikethrough";
+  /**
+   * A url that the underlying text will link to
+   */
+  link?: string;
+};
+
 /**
  * @public
  * A native element.
@@ -765,6 +911,10 @@ export declare type NativeImageElement = {
    * The type of element.
    */
   type: "IMAGE";
+  /**
+   * An optional object to describe alt-text that may be applied to an image.
+   */
+  altText?: AltText;
 } & (
   | {
       /**
@@ -800,6 +950,34 @@ export declare type NativeImageElement = {
  */
 export declare type NativeImageElementWithBox = NativeImageElement & Box;
 
+/**
+ * @beta
+ * An element that renders richtext.
+ */
+export declare type NativeRichtextElement = {
+  /**
+   * The type of element.
+   */
+  type: "RICHTEXT";
+  /**
+   * An object containing rich text which exposes methods to manipulate the text.
+   */
+  range: RichtextRange;
+};
+
+/**
+ * @beta
+ * An element that renders richtext.
+ *
+ * @remarks
+ * This type includes properties for controlling the position and dimensions of the
+ * element.
+ * It will be positioned and sized relative to its parent container.
+ * The parent container may be an app element, or the current page.
+ */
+export declare type NativeRichtextElementWithBox = NativeRichtextElement &
+  TextBox;
+
 /**
  * @public
  * An element that renders a vector shape.
@@ -863,6 +1041,23 @@ export declare type NativeSimpleElementWithBox = Exclude<
   NativeGroupElementWithBox
 >;
 
+/**
+ * @beta
+ * An element that renders a table.
+ */
+export declare type NativeTableElement = {
+  /**
+   * The type of element.
+   */
+  type: "TABLE";
+  /**
+   * The rows of the table. Each row contains an array of cells, 1 cell per column in the row.
+   */
+  rows: {
+    cells: Cell[];
+  }[];
+};
+
 /**
  * @public
  * An element that renders text.
@@ -944,6 +1139,10 @@ export declare type NativeVideoElement = {
    * A unique identifier that references a video asset in Canva's backend.
    */
   ref: VideoRef;
+  /**
+   * An optional object to describe alt-text that may be applied to a video.
+   */
+  altText?: AltText;
 };
 
 /**
@@ -1099,6 +1298,50 @@ declare type Position = {
  */
 declare type Primitive = undefined | null | number | boolean | string;
 
+/**
+ * @beta
+ * A snapshot of content returned by a query.
+ *
+ * @remarks
+ * The snapshot is known as the *draft*.
+ */
+export declare interface QueryContentDraft<T> {
+  /**
+   * The individual content items returned by a query.
+   */
+  readonly contents: readonly T[];
+  /**
+   * 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>;
+}
+
+/**
+ * @beta
+ * The result of querying content in a design.
+ */
+export declare type QueryResult<T extends ContentType> = {
+  ["richtext"]: QueryContentDraft<
+    RichtextRange & {
+      readonly deleted: boolean;
+    }
+  >;
+}[T];
+
+/**
+ * @beta
+ * Reads 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 queried content.
+ */
+export declare function readContent<T extends ContentType>(
+  options: EditContentOptions<T>,
+  callback: (draft: QueryResult<T>) => Promise<void> | void
+): Promise<void>;
+
 /**
  * @public
  * Exports the user's design as one or more static files.
@@ -1109,13 +1352,127 @@ export declare function requestExport(
 ): Promise<ExportResponse>;
 
 /**
- * @public
+ * @beta
+ *
+ * Formatting values for richtext
+ */
+export declare type RichtextFormatting = InlineFormatting & {
+  /**
+   * @public
+   * A reference to the font to use for this text element.
+   */
+  fontRef?: FontRef;
+  /**
+   * The size of the text, in pixels.
+   *
+   * @remarks
+   * This must be an integer between 1 and 1000.
+   * In the UI of the Canva editor, this number is shown as points (pts), not pixels.
+   */
+  fontSize?: number;
+  /**
+   * The alignment of the text.
+   * @defaultValue 'start'
+   */
+  textAlign?: "start" | "center" | "end" | "justify";
+  /**
+   * The list indentation level of the current paragraph.
+   */
+  listLevel?: number;
+  /**
+   * The appearance of the marker for list items.
+   *
+   * @remarks
+   * This property only has an effect if `listLevel` is a number greater than 0.
+   *
+   * @defaultValue 'none'
+   */
+  listMarker?:
+    | "none"
+    | "disc"
+    | "circle"
+    | "square"
+    | "decimal"
+    | "lower-alpha"
+    | "lower-roman"
+    | "checked"
+    | "unchecked";
+};
+
+/**
+ * @beta
+ *
+ * An object containing rich text which exposes methods to manipulate the text.
+ * This is generated from a selection, with a range created for each instance of text in the selection.
+ * For example, if a table is currently selected, a range will be created for each cell.
+ * If only part of the text of an element is selected, then only that part will be represented in the range.
+ */
+export declare type RichtextRange = {
+  /**
+   * Formats all paragraphs that overlap the given bounds. The newline character separates text into
+   * distinct paragraphs. Newline separator is treated as the final character of each paragraph.
+   * All paragraphs that overlap the given bounds will be formatted in their entirety.
+   * @param bounds - The region of text overlapping the paragraphs to apply the formatting.
+   * @param formatting - The formatting to apply to the paragraph(s).
+   */
+  formatParagraph(bounds: Bounds, formatting: RichtextFormatting): void;
+  /**
+   * Formats a given region of rich text with inline formatting.
+   * @param bounds - The region of text to apply the formatting.
+   * @param formatting - The inline formatting to apply to the region of text.
+   */
+  formatText(bounds: Bounds, formatting: InlineFormatting): void;
+  /**
+   * Appends characters to the rich text range.
+   * Appended characters can be formatted with inline formatting properties.
+   * @param characters - The characters to append to the rich text range.
+   * @param formatting - The inline formatting to apply to the appended text.
+   */
+  appendText(
+    characters: string,
+    formatting?: InlineFormatting
+  ): {
+    bounds: Bounds;
+  };
+  /**
+   * Replaces a region of the rich text range with the specified characters.
+   * Replaced characters can be formatted with inline formatting properties.
+   * @param bounds - The region of text to be replaced.
+   * @param characters - The replacement characters.
+   * @param formatting - The inline formatting to apply to the replaced text.
+   */
+  replaceText(
+    bounds: Bounds,
+    characters: string,
+    formatting?: InlineFormatting
+  ): {
+    bounds: Bounds;
+  };
+  /**
+   * Returns the current state of the rich text range as plain text.
+   *
+   * @remarks
+   * If this range is a draft, this includes any changes to the text that have not been committed.
+   */
+  readPlaintext(): string;
+  /**
+   * Returns the current state of the rich text range as an array of text regions.
+   * Each region is an object that contains the text itself and its formatting.
+   *
+   * @remarks
+   * If this range is a draft, this array includes any changes to the text that have not been committed.
+   */
+  readTextRegions(): TextRegion[];
+};
+
+/**
+ * @beta
  * An alias for the DesignSelection interface, providing access to design selection related functionality
  */
 export declare const selection: DesignSelection;
 
 /**
- * @public
+ * @beta
  * Information about the user's selection. To access the selected content, call the `read` method.
  */
 export declare interface SelectionEvent<Scope extends SelectionScope> {
@@ -1150,13 +1507,17 @@ export declare interface SelectionEvent<Scope extends SelectionScope> {
 }
 
 /**
- * @public
+ * @beta
  * The type of content that apps can detect selection changes on.
  */
-export declare type SelectionScope = "plaintext" | "image" | "video";
+export declare type SelectionScope =
+  | "plaintext"
+  | "image"
+  | "video"
+  | "richtext";
 
 /**
- * @public
+ * @beta
  * The selected content.
  *
  * @remarks
@@ -1190,6 +1551,10 @@ export declare type SelectionValue<Scope extends SelectionScope> = {
      */
     ref: VideoRef;
   };
+  /**
+   * The selected content when {@link SelectionScope} is `"richtext"`.
+   */
+  ["richtext"]: RichtextRange;
 }[Scope];
 
 /**
@@ -1306,6 +1671,39 @@ export declare type TextAttributes = {
   decoration?: "none" | "underline";
 };
 
+/**
+ * @beta
+ */
+declare type TextBox = {
+  /**
+   * The width of the element. This must be an integer between 0 and 32767.
+   */
+  width?: number;
+  /**
+   * The distance from the top edge of the container.
+   *
+   * @remarks
+   * This must be an integer between -32768 and 32767. This property doesn't have
+   * any effect if the app element only contains a single element.
+   */
+  top: number;
+  /**
+   * The distance from the left edge of the container.
+   *
+   * @remarks
+   * This must be an integer between -32768 and 32767. This property doesn't have
+   * any effect if the app element only contains a single element.
+   */
+  left: number;
+  /**
+   * The rotation of the element, in degrees.
+   *
+   * @remarks
+   * This must be an integer between -180 and 180.
+   */
+  rotation?: number;
+};
+
 /**
  * @public
  * Options for defining the drag-and-drop behavior of a text element.
@@ -1339,6 +1737,26 @@ export declare type TextDragConfig = {
    * @defaultValue 'none'
    */
   decoration?: "none" | "underline";
+  /**
+   * @beta
+   * A unique identifier that references a font asset in Canva's backend.
+   */
+  fontRef?: FontRef;
+};
+
+/**
+ * @beta
+ * A region of rich text.
+ */
+export declare type TextRegion = {
+  /**
+   * The plain text content of the region.
+   */
+  text: string;
+  /**
+   * The formatting of the region.
+   */
+  formatting?: Partial<RichtextFormatting>;
 };
 
 /**

package/lib/cjs/sdk/design/beta.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: all[name]
+    });
+}
+_export(exports, {
+    selection: function() {
+        return selection;
+    },
+    addNativeElement: function() {
+        return addNativeElement;
+    },
+    createRichtextRange: function() {
+        return createRichtextRange;
+    },
+    readContent: function() {
+        return readContent;
+    }
+});
+_export_star(require("./public"), exports);
+function _export_star(from, to) {
+    Object.keys(from).forEach(function(k) {
+        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
+            Object.defineProperty(to, k, {
+                enumerable: true,
+                get: function() {
+                    return from[k];
+                }
+            });
+        }
+    });
+    return from;
+}
+const { canva } = window;
+const selection = canva.designInteraction.selection;
+function addNativeElement(element) {
+    return canva.designInteraction.addNativeElement(element);
+}
+function createRichtextRange() {
+    return canva.designInteraction.createRichtextRange();
+}
+function readContent(options, callback) {
+    return canva.designInteraction.readContent(options, callback);
+}

package/lib/esm/sdk/design/beta.js

@@ -0,0 +1,26 @@
+const { canva } = window;
+/**
+ * @beta
+ * An alias for the DesignSelection interface, providing access to design selection related functionality
+ */ export const selection = canva.designInteraction.selection;
+/**
+ * @internal
+ * @param element
+ */ export function addNativeElement(element) {
+    return canva.designInteraction.addNativeElement(element);
+}
+/**
+ * @beta
+ * Creates a new RichtextRange object, which contains methods to manipulate text.
+ */ export function createRichtextRange() {
+    return canva.designInteraction.createRichtextRange();
+}
+/**
+ * @beta
+ * Reads 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 queried content.
+ */ export function readContent(options, callback) {
+    return canva.designInteraction.readContent(options, callback);
+}
+export * from './public';

package/package.json

@@ -1,25 +1,25 @@
 {
   "name": "@canva/design",
-  "version": "1.9.0",
+  "version": "1.10.0-beta.1",
   "description": "The Canva Apps SDK design library",
   "author": "Canva Pty Ltd.",
   "license": "SEE LICENSE IN LICENSE.md FILE",
   "peerDependencies": {
     "@canva/error": "^1.0.0"
   },
-  "main": "./lib/cjs/sdk/design/index.js",
-  "module": "./lib/esm/sdk/design/index.js",
+  "main": "./lib/cjs/sdk/design/beta.js",
+  "module": "./lib/esm/sdk/design/beta.js",
   "exports": {
     ".": {
       "require": {
-        "types": "./index.d.ts",
-        "default": "./lib/cjs/sdk/design/index.js"
+        "types": "./beta.d.ts",
+        "default": "./lib/cjs/sdk/design/beta.js"
       },
       "import": {
-        "types": "./index.d.ts",
-        "default": "./lib/esm/sdk/design/index.js"
+        "types": "./beta.d.ts",
+        "default": "./lib/esm/sdk/design/beta.js"
       }
     }
   },
-  "typings": "./index.d.ts"
-}
+  "typings": "./beta.d.ts"
+}

package/lib/cjs/sdk/design/index.js

@@ -1,19 +0,0 @@
-// Copyright 2023 Canva Inc. All Rights Reserved.
-"use strict";
-Object.defineProperty(exports, "__esModule", {
-    value: true
-});
-_export_star(require("./public"), exports);
-function _export_star(from, to) {
-    Object.keys(from).forEach(function(k) {
-        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
-            Object.defineProperty(to, k, {
-                enumerable: true,
-                get: function() {
-                    return from[k];
-                }
-            });
-        }
-    });
-    return from;
-}

package/lib/esm/sdk/design/index.js

@@ -1,2 +0,0 @@
-// Copyright 2023 Canva Inc. All Rights Reserved.
-export * from './public';