@canva/design 0.0.1-rc.1 → 1.4.0

package/README.md

@@ -0,0 +1,73 @@
+# @canva/design
+
+A package for Canva's Apps SDK that provides methods for interacting with a user's design.
+
+![](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)
+
+## Table of contents
+
+- [Introduction](#introduction)
+- [Installation](#installation)
+- [Usage](#usage)
+- [API reference](#api-reference)
+- [Related packages](#related-packages)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Introduction
+
+`@canva/design` is an npm package for Canva's [Apps SDK](https://www.canva.dev/docs/apps). It provides methods for interacting with a user's design. For example, the `addPage` method adds a page to the user's design, while `requestExport` exports the user's design as one or more static files.
+
+**Note:** To get up and running with the Apps SDK, check out [the quick start guide](https://www.canva.dev/docs/apps/quick-start).
+
+## Installation
+
+```bash
+npm install @canva/design
+```
+
+## Usage
+
+1. Import a method or namespace from the `@canva/design` package:
+
+   ```ts
+   import { addPage } from '@canva/design';
+   ```
+
+2. Call a method, passing in the required arguments (if any):
+
+   ```ts
+   await addPage();
+   ```
+
+## API reference
+
+- [`addAudioTrack`](https://www.canva.dev/docs/apps/api/design-add-audio-track)
+- [`addNativeElement`](https://www.canva.dev/docs/apps/api/design-add-native-element)
+- [`addPage`](https://www.canva.dev/docs/apps/api/design-add-page)
+- [`getCurrentPageContext`](https://www.canva.dev/docs/apps/api/design-get-current-page-context)
+- [`getDefaultPageDimensions`](https://www.canva.dev/docs/apps/api/design-get-default-page-dimensions)
+- [`initAppElement`](https://www.canva.dev/docs/apps/api/design-init-app-element)
+- [`requestExport`](https://www.canva.dev/docs/apps/api/design-request-export)
+- [`selection.registerOnChange`](https://www.canva.dev/docs/apps/api/design-selection-register-on-change)
+- [`setCurrentPageBackground`](https://www.canva.dev/docs/apps/api/design-set-current-page-background)
+- [`ui.startDrag`](https://www.canva.dev/docs/apps/api/design-ui-start-drag)
+
+## Related packages
+
+The Apps SDK is made up of the following packages:
+
+- [`@canva/app-ui-kit`](https://www.npmjs.com/package/@canva/app-ui-kit) - React-based component library for creating apps that mimic the look and feel of Canva.
+- [`@canva/asset`](https://www.npmjs.com/package/@canva/asset) - Provides methods for working with assets, such as image and video files.
+- [`@canva/design`](https://www.npmjs.com/package/@canva/design) - Provides methods for interacting with the user's design, such as creating elements.
+- [`@canva/error`](https://www.npmjs.com/package/@canva/error) - Provides a `CanvaError` class for handling errors.
+- [`@canva/platform`](https://www.npmjs.com/package/@canva/platform) - Provides utility methods, such as a method for opening external links.
+- [`@canva/user`](https://www.npmjs.com/package/@canva/user) - Provides methods for accessing user data and authenticating users.
+
+## Contributing
+
+We're actively developing this package but are not currently accepting third-party contributions. If you'd like to request any changes or additions to the package, submit a feature request via the [Canva Developers Community](https://community.canva.dev/).
+
+## License
+
+See the `LICENSE.md` file.

package/index.d.ts

@@ -22,7 +22,10 @@ export declare function addNativeElement(
 export declare function addPage(opts?: {
   /**  Elements to be added to the page */
   elements?: NativeElementWithBox[];
-
+  /**
+   * The page background. This can be a solid color, an image or a video.
+   **/
+  background?: PageBackgroundFill;
   /**  A page title which must be no longer than 255 characters */
   title?: string;
 }): Promise<void>;
@@ -94,7 +97,10 @@ export declare type AppElementRenderer<A extends AppElementData> = (
  * A return value of {@link AppElementRenderer} function.
  * It is an array of elements to render within an app element.
  */
-export declare type AppElementRendererOutput = NativeSimpleElementWithBox[];
+export declare type AppElementRendererOutput = Exclude<
+  NativeSimpleElementWithBox,
+  NativeVideoElementWithBox
+>[];
 
 /**
  * @public
@@ -164,6 +170,29 @@ declare type CommonImageDragConfig = {
   previewSize: Dimensions;
 };
 
+/**
+ * @public
+ * A snapshot of some part of the document content.
+ *
+ * @remarks
+ * You can mutate the values in the `contents` array and then persist those changes with the `save` method.
+ */
+export declare interface ContentDraft<T> {
+  /**
+   * The selected content.
+   */
+  readonly contents: readonly T[];
+  /**
+   * Saves changes made to items in the `contents` array.
+   * Once saved, those changes are reflected in the user's design.
+   *
+   * @remarks
+   * Any other changes to the content since calling the `read` method, such as the user editing the content directly, will be overwritten.
+   * Only properties that are different from the original state are written to the design.
+   */
+  save(): Promise<void>;
+}
+
 /**
  * @public
  * Represents X and Y coordinates.
@@ -179,6 +208,29 @@ export declare type Coordinates = {
   y: number;
 };
 
+/**
+ * @public
+ * Provides methods for interacting with the user's selected content, such as images or text.
+ */
+export declare type DesignSelection = {
+  /**
+   * Registers a callback that runs when a user selects an element that contains the specified type of content.
+   *
+   * @remarks
+   * The callback fires immediately if content is already selected.
+   */
+  registerOnChange<Scope extends SelectionScope>(opts: {
+    /**
+     * The type of content that, when selected, triggers the `onChange` callback.
+     */
+    scope: Scope;
+    /**
+     * The callback to run when the selection changes.
+     */
+    onChange(event: SelectionEvent<Scope>): void;
+  }): () => void;
+};
+
 /**
  * @public
  * Represents a width and a height.
@@ -442,6 +494,21 @@ export declare type Fill = {
   asset?: ImageFill | VideoFill;
 };
 
+/**
+ * @public
+ * Font weights supported in the SDK.
+ **/
+declare type FontWeight =
+  | "normal"
+  | "thin"
+  | "extralight"
+  | "light"
+  | "medium"
+  | "semibold"
+  | "bold"
+  | "ultrabold"
+  | "heavy";
+
 /**
  * Allows to get the context of currently selected page.
  * @public
@@ -658,7 +725,6 @@ export declare type NativeImageElement = {
   | {
       /**
        * A data URL that contains the image data.
-       * @deprecated Instead, use the `upload` method from the `@canva/asset` package and pass the returned asset reference into the `ref` property.
        */
       dataUrl: string;
       /**
@@ -853,6 +919,12 @@ export declare type NativeVideoElementWithBox = NativeVideoElement & Box;
  */
 declare type ObjectPrimitive = Boolean | String;
 
+/**
+ * @public
+ * The appearance of a page's background.
+ */
+export declare type PageBackgroundFill = Pick<Fill, "asset" | "color">;
+
 /**
  * @public
  * Page context
@@ -934,9 +1006,9 @@ declare type Position = {
  * The types of primitive values that can be stored within an app element's data.
  *
  * @remarks
- * All types of primitives are supported except for symbols, bigints and undefined.
+ * All types of primitives are supported except for symbols and bigints.
  */
-declare type Primitive = null | number | boolean | string;
+declare type Primitive = undefined | null | number | boolean | string;
 
 /**
  * @public
@@ -947,6 +1019,90 @@ export declare function requestExport(
   request: ExportRequest
 ): Promise<ExportResponse>;
 
+/**
+ * @public
+ * An alias for the DesignSelection interface, providing access to design selection related functionality
+ */
+export declare const selection: DesignSelection;
+
+/**
+ * @public
+ * Information about the user's selection. To access the selected content, call the `read` method.
+ */
+export declare interface SelectionEvent<Scope extends SelectionScope> {
+  /**
+   * The type of content that's selected.
+   */
+  readonly scope: Scope;
+  /**
+   * The number of selected elements.
+   */
+  readonly count: number;
+  /**
+   * Creates a snapshot of the selected content and returns a *draft* object.
+   * The draft has a mutable `contents` property for making changes to the selected content.
+   * Any changes made to `contents` are not immediately persisted or reflected in the user's design.
+   * To persist the changes, call the `save` method that's available via the draft.
+   *
+   * @example Replacing text
+   * ```
+   * const draft = await selectionEvent.read();
+   *
+   * for(const content of draft.contents) {
+   *     // This change won't immediately appear in the user's design
+   *     content.text = "This is the new text";
+   * }
+   *
+   * // The changes will now appear in the user's design
+   * await draft.save();
+   * ```
+   */
+  read(): Promise<ContentDraft<SelectionValue<Scope>>>;
+}
+
+/**
+ * @public
+ * The type of content that apps can detect selection changes on.
+ */
+export declare type SelectionScope = "plaintext" | "image";
+
+/**
+ * @public
+ * The selected content.
+ *
+ * @remarks
+ * The value depends on the {@link SelectionScope}.
+ */
+export declare type SelectionValue<Scope extends SelectionScope> = {
+  /**
+   * The selected content when {@link SelectionScope} is `"plaintext"`.
+   */
+  ["plaintext"]: {
+    /**
+     * The text content of the element as plain text.
+     */
+    text: string;
+  };
+  /**
+   * The selected content when {@link SelectionScope} is `"image"`.
+   */
+  ["image"]: {
+    /**
+     * A unique identifier that points to an image asset in Canva's backend.
+     */
+    ref: ImageRef;
+  };
+}[Scope];
+
+/**
+ * @public
+ * Updates the background of the user's current page. The background can be a solid color,
+ * an image or a video.
+ */
+export declare function setCurrentPageBackground(
+  opts: PageBackgroundFill
+): Promise<void>;
+
 /**
  * @public
  * A path that defines the shape of a shape element.
@@ -1029,10 +1185,11 @@ declare type TextAttributes = {
    * (e.g. #ff0099). The default value is #000000.
    */
   color?: string;
+
   /**
    * The weight of the font. The default value is 'normal'.
    */
-  fontWeight?: "normal" | "bold";
+  fontWeight?: FontWeight;
   /**
    * The style of the font. The default value is 'normal'.
    */
@@ -1273,7 +1430,7 @@ export declare type UserSuppliedVideoDragData = {
 export declare type Value =
   | Primitive
   | ObjectPrimitive
-  | Value[]
+  | Exclude<Value, undefined>[]
   | {
       [key: string]: Value;
     };

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

@@ -1,7 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.initAppElement = exports.getCurrentPageContext = exports.addAudioTrack = exports.addNativeElement = exports.ui = exports.requestExport = exports.getDefaultPageDimensions = exports.addPage = void 0;
+exports.initAppElement = exports.getCurrentPageContext = exports.addAudioTrack = exports.addNativeElement = exports.ui = exports.requestExport = exports.getDefaultPageDimensions = exports.setCurrentPageBackground = exports.addPage = exports.selection = void 0;
 const { canva } = window;
+/**
+ * @public
+ * An alias for the DesignSelection interface, providing access to design selection related functionality
+ */
+exports.selection = canva.designInteraction.selection;
 /**
  * @public
  * Adds a new page immediately after the currently selected page.
@@ -11,6 +16,15 @@ function addPage(opts) {
     return canva.designInteraction.addPage(opts);
 }
 exports.addPage = addPage;
+/**
+ * @public
+ * Updates the background of the user's current page. The background can be a solid color,
+ * an image or a video.
+ */
+function setCurrentPageBackground(opts) {
+    return canva.designInteraction.setCurrentPageBackground(opts);
+}
+exports.setCurrentPageBackground = setCurrentPageBackground;
 /**
  * @public
  * Gets the default dimensions that a new page will have when it is added to a design.

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

@@ -1,4 +1,9 @@
 const { canva } = window;
+/**
+ * @public
+ * An alias for the DesignSelection interface, providing access to design selection related functionality
+ */
+export const selection = canva.designInteraction.selection;
 /**
  * @public
  * Adds a new page immediately after the currently selected page.
@@ -7,6 +12,14 @@ const { canva } = window;
 export function addPage(opts) {
     return canva.designInteraction.addPage(opts);
 }
+/**
+ * @public
+ * Updates the background of the user's current page. The background can be a solid color,
+ * an image or a video.
+ */
+export function setCurrentPageBackground(opts) {
+    return canva.designInteraction.setCurrentPageBackground(opts);
+}
 /**
  * @public
  * Gets the default dimensions that a new page will have when it is added to a design.

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@canva/design",
-  "version": "0.0.1-rc.1",
+  "version": "1.4.0",
   "description": "The Canva Apps SDK design library",
   "author": "Canva Pty Ltd.",
   "license": "SEE LICENSE IN LICENSE.md FILE",
   "peerDependencies": {
-    "@canva/error": "^0.0.1-rc.1"
+    "@canva/error": "^1.0.0"
   },
   "main": "lib/cjs/sdk/design/index.js",
   "module": "lib/esm/sdk/design/index.js",
@@ -16,4 +16,4 @@
     }
   },
   "typings": "./index.d.ts"
-}
+}