@canva/cli 1.10.0 → 1.12.0

package/templates/hello_world/package.json

@@ -19,15 +19,17 @@
     "postinstall": "ts-node ./scripts/copy_env.ts"
   },
   "dependencies": {
-    "@canva/app-i18n-kit": "^1.1.1",
-    "@canva/app-ui-kit": "^5.2.1",
-    "@canva/asset": "^2.2.1",
-    "@canva/design": "^2.7.3",
+    "@canva/app-hooks": "^0.0.0-beta.4",
+    "@canva/app-i18n-kit": "^1.2.0",
+    "@canva/app-ui-kit": "^5.3.0",
+    "@canva/asset": "^2.2.2",
+    "@canva/design": "^2.7.5",
     "@canva/error": "^2.1.0",
+    "@canva/intents": "^2.0.0",
     "@canva/platform": "^2.2.0",
     "@canva/user": "^2.1.1",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
+    "react": "^19.2.1",
+    "react-dom": "^19.2.1",
     "react-intl": "^7.1.11"
   },
   "devDependencies": {
@@ -57,7 +59,7 @@
     "cssnano": "7.1.1",
     "debug": "4.4.1",
     "dotenv": "16.6.0",
-    "express": "4.21.2",
+    "express": "4.22.1",
     "express-basic-auth": "1.2.1",
     "jest": "29.7.0",
     "jest-css-modules-transform": "4.4.2",
@@ -66,7 +68,7 @@
     "jwks-rsa": "3.2.0",
     "mini-css-extract-plugin": "2.9.4",
     "node-fetch": "3.3.2",
-    "node-forge": "1.3.1",
+    "node-forge": "1.3.2",
     "nodemon": "3.0.1",
     "open": "8.4.2",
     "postcss-loader": "8.1.1",

package/templates/hello_world/src/index.tsx

@@ -1,22 +1,4 @@
-import { AppI18nProvider } from "@canva/app-i18n-kit";
-import { AppUiProvider } from "@canva/app-ui-kit";
-import { createRoot } from "react-dom/client";
-import { App } from "./app";
-import "@canva/app-ui-kit/styles.css";
+import { prepareDesignEditor } from "@canva/intents/design";
+import designEditor from "./intents/design_editor";
 
-const root = createRoot(document.getElementById("root") as Element);
-function render() {
-  root.render(
-    <AppI18nProvider>
-      <AppUiProvider>
-        <App />
-      </AppUiProvider>
-    </AppI18nProvider>,
-  );
-}
-
-render();
-
-if (module.hot) {
-  module.hot.accept("./app", render);
-}
+prepareDesignEditor(designEditor);

package/templates/hello_world/src/{app.tsx → intents/design_editor/app.tsx}

@@ -1,15 +1,23 @@
+import { useFeatureSupport } from "@canva/app-hooks";
 import { Button, Rows, Text } from "@canva/app-ui-kit";
+import { addElementAtCursor, addElementAtPoint } from "@canva/design";
 import { requestOpenExternalUrl } from "@canva/platform";
 import { FormattedMessage, useIntl } from "react-intl";
-import { useAddElement } from "utils/use_add_element";
 import * as styles from "styles/components.css";
 
 export const DOCS_URL = "https://www.canva.dev/docs/apps/";
 
 export const App = () => {
-  const addElement = useAddElement();
+  const isSupported = useFeatureSupport();
+  const addElement = [addElementAtPoint, addElementAtCursor].find((fn) =>
+    isSupported(fn),
+  );
 
   const onClick = () => {
+    if (!addElement) {
+      return;
+    }
+
     addElement({
       type: "text",
       children: ["Hello world!"],
@@ -43,7 +51,22 @@ export const App = () => {
             }}
           />
         </Text>
-        <Button variant="primary" onClick={onClick} stretch>
+        <Button
+          variant="primary"
+          onClick={onClick}
+          disabled={!addElement}
+          tooltipLabel={
+            !addElement
+              ? intl.formatMessage({
+                  defaultMessage:
+                    "This feature is not supported in the current page",
+                  description:
+                    "Tooltip label for when a feature is not supported in the current design",
+                })
+              : undefined
+          }
+          stretch
+        >
           {intl.formatMessage({
             defaultMessage: "Do something cool",
             description:

package/templates/hello_world/src/intents/design_editor/index.tsx

@@ -0,0 +1,25 @@
+import "@canva/app-ui-kit/styles.css";
+import { AppI18nProvider } from "@canva/app-i18n-kit";
+import { AppUiProvider } from "@canva/app-ui-kit";
+import type { DesignEditorIntent } from "@canva/intents/design";
+import { createRoot } from "react-dom/client";
+import { App } from "./app";
+
+async function render() {
+  const root = createRoot(document.getElementById("root") as Element);
+
+  root.render(
+    <AppI18nProvider>
+      <AppUiProvider>
+        <App />
+      </AppUiProvider>
+    </AppI18nProvider>,
+  );
+}
+
+const designEditor: DesignEditorIntent = { render };
+export default designEditor;
+
+if (module.hot) {
+  module.hot.accept("./app", render);
+}

package/templates/hello_world/src/{tests → intents/design_editor/tests}/app.tests.tsx

@@ -1,11 +1,13 @@
 /* eslint-disable formatjs/no-literal-string-in-jsx */
+import { useFeatureSupport } from "@canva/app-hooks";
 import { TestAppI18nProvider } from "@canva/app-i18n-kit";
 import { TestAppUiProvider } from "@canva/app-ui-kit";
+import { addElementAtCursor, addElementAtPoint } from "@canva/design";
+import type { Feature } from "@canva/platform";
 import { requestOpenExternalUrl } from "@canva/platform";
 import { fireEvent, render } from "@testing-library/react";
 import type { RenderResult } from "@testing-library/react";
 import type { ReactNode } from "react";
-import { useAddElement } from "utils/use_add_element";
 import { App, DOCS_URL } from "../app";
 
 function renderInTestProvider(node: ReactNode): RenderResult {
@@ -17,33 +19,35 @@ function renderInTestProvider(node: ReactNode): RenderResult {
   );
 }
 
-jest.mock("utils/use_add_element");
+jest.mock("@canva/app-hooks");
 
 // This test demonstrates how to test code that uses functions from the Canva Apps SDK
 // For more information on testing with the Canva Apps SDK, see https://www.canva.dev/docs/apps/testing/
 describe("Hello World Tests", () => {
-  // Mocking the useAddElement hook
-  const mockAddElement = jest.fn();
-  const mockAddUseElement = jest.mocked(useAddElement);
+  const mockIsSupported = jest.fn();
+  const mockUseFeatureSupport = jest.mocked(useFeatureSupport);
   const mockRequestOpenExternalUrl = jest.mocked(requestOpenExternalUrl);
 
   beforeEach(() => {
     jest.resetAllMocks();
-    mockAddUseElement.mockReturnValue(mockAddElement);
+    mockIsSupported.mockImplementation(
+      (fn: Feature) => fn === addElementAtPoint,
+    );
+    mockUseFeatureSupport.mockReturnValue(mockIsSupported);
     mockRequestOpenExternalUrl.mockResolvedValue({ status: "completed" });
   });
 
-  // this test uses a mock in place of the useAddElement hook
+  // this test uses a mock in place of the useFeatureSupport hook
   it("should add a text element when the button is clicked", () => {
     // assert that the mocks are in the expected clean state
-    expect(mockAddUseElement).not.toHaveBeenCalled();
-    expect(mockAddElement).not.toHaveBeenCalled();
+    expect(mockUseFeatureSupport).not.toHaveBeenCalled();
+    expect(addElementAtPoint).not.toHaveBeenCalled();
 
     const result = renderInTestProvider(<App />);
 
     // the hook should have been called in the render process but not the callback
-    expect(mockAddUseElement).toHaveBeenCalled();
-    expect(mockAddElement).not.toHaveBeenCalled();
+    expect(mockUseFeatureSupport).toHaveBeenCalled();
+    expect(addElementAtPoint).not.toHaveBeenCalled();
 
     // get a reference to the do something cool button element
     const doSomethingCoolBtn = result.getByRole("button", {
@@ -53,8 +57,10 @@ describe("Hello World Tests", () => {
     // programmatically simulate clicking the button
     fireEvent.click(doSomethingCoolBtn);
 
-    // we expect that addElement has been called by the button's click handler
-    expect(mockAddElement).toHaveBeenCalled();
+    // we expect that addElementAtPoint has been called by the button's click handler
+    expect(mockIsSupported).toHaveBeenCalledWith(addElementAtPoint);
+    expect(mockIsSupported).not.toHaveBeenCalledWith(addElementAtCursor);
+    expect(addElementAtPoint).toHaveBeenCalled();
   });
 
   // this test uses a mock in place of the @canva/platform requestOpenExternalUrl function

package/templates/hello_world/styles/components.css

@@ -36,3 +36,21 @@
 .scrollContainer:focus-within::-webkit-scrollbar-thumb {
   visibility: visible;
 }
+
+/* Main container for the content publisher preview UI */
+.previewContainer {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-direction: column;
+  width: 100%;
+  height: 100%;
+}
+
+/* Wrapper for the content publisher post preview */
+.previewWrapper {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: calc(400px + 32px + 2px); /* Image width + padding + border */
+}

package/templates/mls/README.md

@@ -0,0 +1,81 @@
+# Real Estate MLS App
+
+## Running this app
+
+### Step 1: Start the local development server
+
+To start the development server, run the following command:
+
+```bash
+npm install
+npm start
+```
+
+The server becomes available at <http://localhost:8080>.
+
+The app's source code is in the `src/app.tsx` file.
+
+### Step 2: Preview the app
+
+The local development server only exposes a JavaScript bundle, so you can't preview an app by visiting <http://localhost:8080>. You can only preview an app via the Canva editor.
+
+To preview an app:
+
+1. Create an app via the [Developer Portal](https://www.canva.com/developers/apps).
+2. Select **App source > Development URL**.
+3. In the **Development URL** field, enter the URL of the development server.
+4. Click **Preview**. This opens the Canva editor (and the app) in a new tab.
+5. Click **Open**. (This screen only appears when using an app for the first time.)
+
+The app will appear in the side panel.
+
+<details>
+  <summary>Previewing apps in Safari</summary>
+
+By default, the development server is not HTTPS-enabled. This is convenient, as there's no need for a security certificate, but it prevents apps from being previewed in Safari.
+
+**Why Safari requires the development server to be HTTPS-enabled?**
+
+Canva itself is served via HTTPS and most browsers prevent HTTPS pages from loading scripts via non-HTTPS connections. Chrome and Firefox make exceptions for local servers, such as `localhost`, but Safari does not, so if you're using Safari, the development server must be HTTPS-enabled.
+
+To learn more, see [Loading mixed-content resources](https://developer.mozilla.org/en-US/docs/Web/Security/Mixed_content#loading_mixed-content_resources).
+
+To preview apps in Safari:
+
+1. Start the development server with HTTPS enabled:
+
+```bash
+npm start --use-https
+```
+
+2. Navigate to <https://localhost:8080>.
+3. Bypass the invalid security certificate warning:
+   1. Click **Show details**.
+   2. Click **Visit website**.
+4. In the Developer Portal, set the app's **Development URL** to <https://localhost:8080>.
+5. Click preview (or refresh your app if it's already open).
+
+You need to bypass the invalid security certificate warning every time you start the local server. A similar warning will appear in other browsers (and will need to be bypassed) whenever HTTPS is enabled.
+
+</details>
+
+### Step 3 (Optional): Enable Hot Module Replacement
+
+By default, every time you make a change to an app, you have to reload the entire app to see the results of those changes. If you enable [Hot Module Replacement](https://webpack.js.org/concepts/hot-module-replacement/) (HMR), changes will be reflected without a full reload, which significantly speeds up the development loop.
+
+**Note:** HMR does **not** work while running the development server in a Docker container.
+
+To enable HMR:
+
+1. Navigate to an app via the [Your apps](https://www.canva.com/developers/apps).
+1. Select **Security** -> **Credentials** -> **.env file**.
+1. Copy the `.env` file contents.
+1. Paste the contents into the starter kit's `.env` file. For example:
+
+   ```bash
+   CANVA_APP_ORIGIN=https://app-aabbccddeeff.canva-apps.com
+   CANVA_HMR_ENABLED=true
+   ```
+
+1. Restart the local development server.
+1. Reload the app manually to ensure that HMR takes effect.

package/templates/mls/canva-app.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://www.canva.dev/schemas/app/v1/manifest-schema.json",
+  "manifest_schema_version": 1,
+  "runtime": {
+    "permissions": [
+      {
+        "name": "canva:design:content:read",
+        "type": "mandatory"
+      },
+      {
+        "name": "canva:design:content:write",
+        "type": "mandatory"
+      },
+      {
+        "name": "canva:asset:private:write",
+        "type": "mandatory"
+      }
+    ]
+  },
+  "intent": {
+    "design_editor": {
+      "enrolled": true
+    }
+  }
+}

package/templates/mls/declarations/declarations.d.ts

@@ -0,0 +1,29 @@
+declare module "*.css" {
+  const styles: { [className: string]: string };
+  export = styles;
+}
+
+declare module "*.jpg" {
+  const content: string;
+  export default content;
+}
+
+declare module "*.jpeg" {
+  const content: string;
+  export default content;
+}
+
+declare module "*.png" {
+  const content: string;
+  export default content;
+}
+
+declare module "*.svg" {
+  const content: React.FunctionComponent<{
+    size?: "tiny" | "small" | "medium" | "large";
+    className?: string;
+  }>;
+  export default content;
+}
+
+declare const BACKEND_HOST: string;

package/templates/mls/eslint.config.mjs

@@ -0,0 +1,14 @@
+import canvaPlugin from "@canva/app-eslint-plugin";
+
+export default [
+  {
+    ignores: [
+      "**/node_modules/",
+      "**/dist",
+      "**/*.d.ts",
+      "**/*.d.tsx",
+      "**/*.config.*",
+    ],
+  },
+  ...canvaPlugin.configs.apps,
+];

package/templates/mls/jest.config.mjs

@@ -0,0 +1,36 @@
+import { pathsToModuleNameMapper } from "ts-jest";
+import tsconfig from "./tsconfig.json" with { type: "json" };
+
+const { compilerOptions } = tsconfig;
+
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+
+export default {
+  preset: "ts-jest",
+  testEnvironment: "jsdom",
+  testRegex: "(/(tests|__tests__)/.*\\.(tests))\\.tsx?$",
+  modulePathIgnorePatterns: ["./internal/", "./node_modules/"],
+  modulePaths: [compilerOptions.baseUrl],
+  moduleNameMapper: pathsToModuleNameMapper(compilerOptions.paths),
+  transform: {
+    ".+\\.(css)$": "jest-css-modules-transform",
+    "^.+\\.tsx?$": [
+      "ts-jest",
+      {
+        astTransformers: {
+          before: [
+            {
+              path: "@formatjs/ts-transformer/ts-jest-integration",
+              options: {
+                overrideIdFn: "[sha512:contenthash:base64:6]",
+                ast: true,
+              },
+            },
+          ],
+        },
+      },
+    ],
+  },
+  setupFiles: ["<rootDir>/jest.setup.ts"],
+  setupFilesAfterEnv: ["@testing-library/jest-dom"],
+};

package/templates/mls/jest.setup.ts

@@ -0,0 +1,37 @@
+// For usage information, see the README.md file.
+
+// Import Canva SDK testing utilities
+import * as asset from "@canva/asset/test";
+import * as design from "@canva/design/test";
+import * as error from "@canva/error/test";
+import * as platform from "@canva/platform/test";
+import * as user from "@canva/user/test";
+import { TextEncoder } from "util";
+
+// jsdom doesn't provide TextEncoder by default, so we polyfill it from Node's util module
+global.TextEncoder = TextEncoder as unknown as typeof global.TextEncoder;
+
+/*
+  Initialize test environments for each Canva SDK package
+  This sets up the necessary test infrastructure before mocking the actual SDK methods
+*/
+asset.initTestEnvironment();
+design.initTestEnvironment();
+error.initTestEnvironment();
+platform.initTestEnvironment();
+user.initTestEnvironment();
+
+/*
+  Mock all Canva SDK packages except @canva/error
+  This allows tests to run without making real API calls to Canva's services
+*/
+jest.mock("@canva/asset");
+jest.mock("@canva/design");
+jest.mock("@canva/platform");
+jest.mock("@canva/user");
+
+/*
+  Important: @canva/error should not be mocked
+  Use it to simulate API error responses from other mocks by throwing CanvaError instances
+  This allows testing of error handling scenarios
+*/

package/templates/mls/package.json

@@ -0,0 +1,117 @@
+{
+  "private": true,
+  "name": "real_estate_mls",
+  "description": "A Real Estate MLS reference app built with the Canva Apps SDK.",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "author": "Canva Pty Ltd.",
+  "scripts": {
+    "extract": "formatjs extract \"src/**/*.{ts,tsx}\" --out-file dist/messages_en.json",
+    "build": "webpack --config webpack.config.ts --mode production && npm run extract",
+    "format": "prettier '**/*.{css,ts,tsx}' --no-config --write",
+    "format:check": "prettier '**/*.{css,ts,tsx}' --no-config --check --ignore-path",
+    "format:file": "prettier $1 --no-config --write",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "lint:types": "tsc",
+    "start": "ts-node ./scripts/start/start.ts",
+    "start:preview": "npm run start -- --preview",
+    "test": "jest --no-cache",
+    "test:watch": "jest --watchAll",
+    "test:update": "npm run test -- -u",
+    "postinstall": "ts-node ./scripts/copy_env.ts"
+  },
+  "dependencies": {
+    "@canva/app-hooks": "^0.0.0-beta.4",
+    "@canva/app-i18n-kit": "^1.2.0",
+    "@canva/app-ui-kit": "^5.3.0",
+    "@canva/asset": "^2.2.2",
+    "@canva/design": "^2.7.5",
+    "@canva/error": "^2.1.0",
+    "@canva/intents": "^2.0.0",
+    "@canva/platform": "^2.2.0",
+    "@canva/user": "^2.1.1",
+    "@tanstack/react-query": "5.87.1",
+    "@types/react-infinite-scroller": "1.2.5",
+    "clsx": "2.1.1",
+    "loglevel": "1.9.2",
+    "react": "^19.2.1",
+    "react-dom": "^19.2.1",
+    "react-hook-form": "7.66.0",
+    "react-infinite-scroller": "1.2.6",
+    "react-intl": "^7.1.11",
+    "react-router-dom": "7.8.2"
+  },
+  "devDependencies": {
+    "@canva/app-eslint-plugin": "^1.0.0-beta.7",
+    "@canva/cli": ">= 0.0.1-beta.13",
+    "@formatjs/cli": "6.7.2",
+    "@formatjs/ts-transformer": "3.14.0",
+    "@ngrok/ngrok": "1.5.2",
+    "@pmmmwh/react-refresh-webpack-plugin": "0.6.1",
+    "@svgr/webpack": "8.1.0",
+    "@testing-library/jest-dom": "6.8.0",
+    "@testing-library/react": "16.3.0",
+    "@testing-library/user-event": "14.6.1",
+    "@types/express": "4.17.21",
+    "@types/express-serve-static-core": "5.0.7",
+    "@types/jest": "29.5.14",
+    "@types/jsonwebtoken": "9.0.10",
+    "@types/node": "20.19.2",
+    "@types/node-fetch": "2.6.13",
+    "@types/node-forge": "1.3.14",
+    "@types/nodemon": "1.19.6",
+    "@types/react": "19.2.2",
+    "@types/react-dom": "19.2.1",
+    "@types/webpack-env": "1.18.8",
+    "chalk": "4.1.2",
+    "cli-table3": "0.6.5",
+    "css-loader": "7.1.2",
+    "css-modules-typescript-loader": "4.0.1",
+    "cssnano": "7.1.1",
+    "debug": "4.4.1",
+    "dotenv": "16.6.0",
+    "express": "4.22.1",
+    "express-basic-auth": "1.2.1",
+    "jest": "29.7.0",
+    "jest-css-modules-transform": "4.4.2",
+    "jest-environment-jsdom": "29.7.0",
+    "jsonwebtoken": "9.0.2",
+    "jwks-rsa": "3.2.0",
+    "mini-css-extract-plugin": "2.9.4",
+    "node-fetch": "3.3.2",
+    "node-forge": "1.3.2",
+    "nodemon": "3.0.1",
+    "open": "8.4.2",
+    "postcss-loader": "8.1.1",
+    "prettier": "3.6.2",
+    "react-refresh": "0.17.0",
+    "style-loader": "4.0.0",
+    "terser-webpack-plugin": "5.3.14",
+    "tree-kill": "1.2.2",
+    "ts-jest": "29.4.1",
+    "ts-loader": "9.5.4",
+    "ts-node": "10.9.2",
+    "typescript": "5.9.2",
+    "url-loader": "4.1.1",
+    "webpack": "5.99.9",
+    "webpack-cli": "6.0.1",
+    "webpack-dev-server": "5.2.2",
+    "yargs": "17.7.2"
+  },
+  "overrides": {
+    "react-infinite-scroller": {
+      "react": "$react"
+    }
+  },
+  "keywords": [
+    "canva-apps-sdk"
+  ],
+  "engines": {
+    "node": "^18 || ^20.10.0",
+    "npm": "^9 || ^10"
+  },
+  "canvaCliMetadata": {
+    "name": "@canva/cli",
+    "version": "1.1.0"
+  }
+}

package/templates/mls/scripts/copy_env.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+import fs from "fs";
+import path from "path";
+
+const envPath = path.resolve(__dirname, "..", ".env");
+const templatePath = path.resolve(__dirname, "..", ".env.template");
+
+if (!fs.existsSync(templatePath)) {
+  console.warn(".env.template file does not exist, skipping copy of .env file");
+} else if (!fs.existsSync(envPath)) {
+  fs.copyFileSync(templatePath, envPath);
+}