@canva/cli 0.0.1-beta.1 → 0.0.1-beta.11

package/templates/hello_world/eslint.config.mjs

@@ -1,11 +1,9 @@
-import typescriptEslint from "@typescript-eslint/eslint-plugin";
-import jest from "eslint-plugin-jest";
-import react from "eslint-plugin-react";
-import globals from "globals";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import js from "@eslint/js";
 import { FlatCompat } from "@eslint/eslintrc";
+import general from "./conf/eslint-general.mjs";
+import i18n from "./conf/eslint-i18n.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -22,8 +20,6 @@ export default [
       "**/dist",
       "**/*.d.ts",
       "**/*.d.tsx",
-      "**/sdk",
-      "**/internal",
       "**/*.config.*",
     ],
   },
@@ -34,276 +30,8 @@ export default [
     "plugin:@typescript-eslint/strict",
     "plugin:@typescript-eslint/stylistic",
     "plugin:react/recommended",
-    "plugin:jest/recommended"
+    "plugin:jest/recommended",
   ),
-  {
-    plugins: {
-      "@typescript-eslint": typescriptEslint,
-      jest,
-      react,
-    },
-    languageOptions: {
-      globals: {
-        ...globals.serviceworker,
-        ...globals.browser,
-      },
-    },
-    settings: {
-      react: {
-        version: "detect",
-      },
-    },
-    rules: {
-      "@typescript-eslint/no-non-null-assertion": "warn",
-      "@typescript-eslint/no-empty-function": "off",
-      "@typescript-eslint/consistent-type-imports": "error",
-      "@typescript-eslint/no-explicit-any": "warn",
-      "@typescript-eslint/no-empty-interface": "warn",
-      "@typescript-eslint/consistent-type-definitions": "off",
-      "@typescript-eslint/explicit-member-accessibility": [
-        "error",
-        {
-          accessibility: "no-public",
-          overrides: {
-            parameterProperties: "off",
-          },
-        },
-      ],
-      "@typescript-eslint/naming-convention": [
-        "error",
-        {
-          selector: "typeLike",
-          format: ["PascalCase"],
-          leadingUnderscore: "allow",
-        },
-      ],
-      "no-invalid-this": "off",
-      "@typescript-eslint/no-invalid-this": "error",
-      "@typescript-eslint/no-unused-expressions": [
-        "error",
-        {
-          allowShortCircuit: true,
-          allowTernary: true,
-        },
-      ],
-      "no-unused-vars": "off",
-      "@typescript-eslint/no-unused-vars": [
-        "error",
-        {
-          vars: "all",
-          varsIgnorePattern: "^_",
-          args: "none",
-          ignoreRestSiblings: true,
-        },
-      ],
-      "@typescript-eslint/no-require-imports": "error",
-      "jest/no-restricted-matchers": [
-        "error",
-        {
-          toContainElement:
-            "toContainElement is not recommended as it encourages testing the internals of the components",
-          toContainHTML:
-            "toContainHTML is not recommended as it encourages testing the internals of the components",
-          toHaveAttribute:
-            "toHaveAttribute is not recommended as it encourages testing the internals of the components",
-          toHaveClass:
-            "toHaveClass is not recommended as it encourages testing the internals of the components",
-          toHaveStyle:
-            "toHaveStyle is not recommended as it encourages testing the internals of the components",
-        },
-      ],
-      "react/jsx-curly-brace-presence": [
-        "error",
-        {
-          props: "never",
-          children: "never",
-        },
-      ],
-      "react/jsx-tag-spacing": [
-        "error",
-        {
-          closingSlash: "never",
-          beforeSelfClosing: "allow",
-          afterOpening: "never",
-          beforeClosing: "allow",
-        },
-      ],
-      "react/self-closing-comp": "error",
-      "react/no-unescaped-entities": "off",
-      "react/jsx-uses-react": "off",
-      "react/react-in-jsx-scope": "off",
-      "default-case": "error",
-      eqeqeq: [
-        "error",
-        "always",
-        {
-          null: "never",
-        },
-      ],
-      "no-caller": "error",
-      "no-console": "error",
-      "no-eval": "error",
-      "no-inner-declarations": "error",
-      "no-new-wrappers": "error",
-      "no-restricted-globals": [
-        "error",
-        {
-          name: "fit",
-          message: "Don't focus tests",
-        },
-        {
-          name: "fdescribe",
-          message: "Don't focus tests",
-        },
-        {
-          name: "length",
-          message:
-            "Undefined length - Did you mean to use window.length instead?",
-        },
-        {
-          name: "name",
-          message: "Undefined name - Did you mean to use window.name instead?",
-        },
-        {
-          name: "status",
-          message:
-            "Undefined status - Did you mean to use window.status instead?",
-        },
-        {
-          name: "spyOn",
-          message: "Don't use spyOn directly, use jest.spyOn",
-        },
-      ],
-      "no-restricted-properties": [
-        "error",
-        {
-          property: "bind",
-          message: "Don't o.f.bind(o, ...), use () => o.f(...)",
-        },
-        {
-          object: "ReactDOM",
-          property: "findDOMNode",
-          message: "Don't use ReactDOM.findDOMNode() as it is deprecated",
-        },
-      ],
-      "no-restricted-syntax": [
-        "error",
-        {
-          selector: "AccessorProperty, TSAbstractAccessorProperty",
-          message:
-            "Accessor property syntax is not allowed, use getter and setters.",
-        },
-        {
-          selector: "PrivateIdentifier",
-          message:
-            "Private identifiers are not allowed, use TypeScript private fields.",
-        },
-        {
-          selector:
-            "JSXOpeningElement[name.name = /^[A-Z]/] > JSXAttribute[name.name = /-/]",
-          message:
-            "Passing hyphenated props to custom components is not type-safe. Prefer a camelCased equivalent if available. (See https://github.com/microsoft/TypeScript/issues/55182)",
-        },
-        {
-          selector:
-            "CallExpression[callee.object.name='window'][callee.property.name='open']",
-          message:
-            "Apps are currently not allowed to open popups, or new tabs via browser APIs. Please use `requestOpenExternalUrl` from `@canva/platform` to link to external URLs. To learn more, see https://www.canva.dev/docs/apps/api/platform-request-open-external-url/",
-        },
-      ],
-      "no-return-await": "error",
-      "no-throw-literal": "error",
-      "no-undef-init": "error",
-      "no-var": "error",
-      "object-shorthand": "error",
-      "prefer-const": [
-        "error",
-        {
-          destructuring: "all",
-        },
-      ],
-      "prefer-object-spread": "error",
-      "prefer-rest-params": "error",
-      "prefer-spread": "error",
-      radix: "error",
-    },
-  },
-  {
-    files: ["**/*.tsx"],
-    rules: {
-      "react/no-deprecated": "error",
-      "react/forbid-elements": [
-        "error",
-        {
-          forbid: [
-            {
-              element: "video",
-              message:
-                "Don't use HTML video directly. Instead, use the App UI Kit <VideoCard /> as this respects users' auto-playing preferences",
-            },
-            {
-              element: "em",
-              message:
-                "Don't use <em> to italicize text. Canva's UI fonts don't support italic font style.",
-            },
-            {
-              element: "i",
-              message:
-                "Don't use <i> to italicize text. Canva's UI fonts don't support italic font style.",
-            },
-            {
-              element: "iframe",
-              message:
-                "Canva Apps aren't allowed to contain iframes. You should either recreate the UI you want to show in the iframe in the app directly, or link to your page via a `<Link>` tag.  For more info see https://www.canva.dev/docs/apps/content-security-policy/#what-is-and-isnt-allowed",
-            },
-            {
-              element: "script",
-              message:
-                "Script tags are not allowed in Canva SDK Apps. You should import JavaScript modules instead. For more info see https://www.canva.dev/docs/apps/content-security-policy/#what-is-and-isnt-allowed",
-            },
-            {
-              element: "a",
-              message:
-                "Don't use <a> tags. Instead, use the <Link> component from the App UI Kit, and remember to open the url via the requestOpenExternalUrl method from @canva/platform.",
-            },
-            {
-              element: "img",
-              message:
-                "Have you considered using <ImageCard /> from the App UI Kit instead?",
-            },
-            {
-              element: "embed",
-              message:
-                "Have you considered using <EmbedCard /> from the App UI Kit instead?",
-            },
-            {
-              element: "audio",
-              message:
-                "Have you considered using <AudioCard /> from the App UI Kit instead?",
-            },
-            {
-              element: "button",
-              message:
-                "Rather than using the native HTML <button> element, use the <Button> component from the App UI Kit for consistency and accessibility.",
-            },
-            {
-              element: "input",
-              message:
-                "Wherever possible, prefer using the form inputs from the App UI Kit for consistency and accessibility (TextInput, Checkbox, FileInput, etc).",
-            },
-            {
-              element: "base",
-              message:
-                "The <base> tag is not supported in Canva Apps. We recommend using hash-based routing. For more on what is and isn't allowed in Canva Apps see https://www.canva.dev/docs/apps/content-security-policy/#what-is-and-isnt-allowed",
-            },
-            {
-              element: "link",
-              message:
-                "If you're trying to include a css stylesheet, we recommend importing css using React, or using embedded stylesheets. For more on what is and isn't allowed in Canva Apps see https://www.canva.dev/docs/apps/content-security-policy/#what-is-and-isnt-allowed",
-            },
-          ],
-        },
-      ],
-    },
-  },
+  ...general,
+  ...i18n,
 ];

package/templates/hello_world/package.json

@@ -3,7 +3,7 @@
   "name": "empty-template",
   "description": "An empty Canva App",
   "scripts": {
-    "extract": "formatjs extract 'src/**/*.{ts,tsx}' --out-file dist/messages_en.json",
+    "extract": "formatjs extract \"src/**/*.{ts,tsx}\" --out-file dist/messages_en.json",
     "build": "webpack --config webpack.config.cjs --mode production && npm run extract",
     "format": "prettier '**/*.{css,ts,tsx}' --no-config --write",
     "format:check": "prettier '**/*.{css,ts,tsx}' --no-config --check --ignore-path",
@@ -13,61 +13,79 @@
     "lint:types": "tsc",
     "start": "ts-node ./scripts/start/start.ts",
     "test": "jest --no-cache",
-    "test:watch": "jest --watchAll"
+    "test:watch": "jest --watchAll",
+    "test:update": "npm run test -- -u",
+    "postinstall": "ts-node ./scripts/copy-env.ts"
   },
   "dependencies": {
-    "@canva/app-ui-kit": "^3.8.0",
-    "@canva/app-i18n-kit": "^0.0.1-beta.5",
-    "@canva/design": "^1.10.0",
-    "@canva/error": "^1.1.0",
+    "@canva/app-i18n-kit": "^1.0.2",
+    "@canva/app-ui-kit": "^4.4.0",
+    "@canva/asset": "^2.1.0",
+    "@canva/design": "^2.3.0",
+    "@canva/error": "^2.1.0",
+    "@canva/platform": "^2.1.0",
+    "@canva/user": "^2.1.0",
     "react": "18.3.1",
     "react-dom": "18.3.1",
-    "react-intl": "6.6.8"
+    "react-intl": "6.8.7"
   },
   "devDependencies": {
-    "@eslint/eslintrc": "3.1.0",
-    "@eslint/js": "9.9.0",
-    "@formatjs/cli": "6.2.12",
-    "@formatjs/ts-transformer": "3.13.14",
+    "@eslint/eslintrc": "3.2.0",
+    "@eslint/js": "9.16.0",
+    "@formatjs/cli": "6.3.14",
+    "@formatjs/ts-transformer": "3.13.26",
     "@ngrok/ngrok": "1.4.1",
+    "@pmmmwh/react-refresh-webpack-plugin": "0.5.15",
     "@svgr/webpack": "8.1.0",
-    "@types/jest": "29.5.12",
+    "@testing-library/react": "16.1.0",
+    "@types/express": "4.17.21",
+    "@types/express-serve-static-core": "4.19.6",
+    "@types/jest": "29.5.14",
+    "@types/jsonwebtoken": "9.0.7",
     "@types/node": "20.10.0",
-    "@types/node-fetch": "2.6.11",
+    "@types/node-fetch": "2.6.12",
     "@types/node-forge": "1.3.11",
     "@types/nodemon": "1.19.6",
-    "@types/react": "18.3.4",
-    "@types/react-dom": "18.3.0",
+    "@types/react": "18.3.12",
+    "@types/react-dom": "18.3.1",
     "@types/webpack-env": "1.18.5",
-    "@typescript-eslint/eslint-plugin": "8.2.0",
-    "@typescript-eslint/parser": "8.2.0",
+    "@typescript-eslint/eslint-plugin": "8.18.0",
+    "@typescript-eslint/parser": "8.18.0",
     "chalk": "4.1.2",
     "cli-table3": "0.6.5",
     "css-loader": "7.1.2",
     "css-modules-typescript-loader": "4.0.1",
-    "cssnano": "7.0.5",
-    "debug": "4.3.6",
-    "dotenv": "16.4.5",
-    "eslint": "9.9.0",
-    "eslint-plugin-jest": "28.8.0",
-    "eslint-plugin-react": "7.35.0",
+    "cssnano": "7.0.6",
+    "debug": "4.4.0",
+    "dotenv": "16.4.7",
+    "eslint": "9.16.0",
+    "eslint-plugin-formatjs": "5.2.8",
+    "eslint-plugin-jest": "28.9.0",
+    "eslint-plugin-react": "7.37.2",
+    "express": "4.21.2",
+    "express-basic-auth": "1.2.1",
     "jest": "29.7.0",
-    "mini-css-extract-plugin": "2.9.1",
+    "jest-css-modules-transform": "4.4.2",
+    "jest-environment-jsdom": "29.7.0",
+    "jsonwebtoken": "9.0.2",
+    "jwks-rsa": "3.1.0",
+    "mini-css-extract-plugin": "2.9.2",
     "node-fetch": "3.3.2",
     "node-forge": "1.3.1",
     "nodemon": "3.0.1",
     "postcss-loader": "8.1.1",
-    "prettier": "3.3.3",
+    "prettier": "3.4.2",
+    "react-refresh": "0.16.0",
     "style-loader": "4.0.0",
     "terser-webpack-plugin": "5.3.10",
-    "ts-jest": "29.2.4",
+    "ts-jest": "29.2.5",
     "ts-loader": "9.5.1",
     "ts-node": "10.9.2",
     "typescript": "5.5.4",
     "url-loader": "4.1.1",
-    "webpack": "5.94.0",
+    "webpack": "5.97.1",
     "webpack-cli": "5.1.4",
-    "webpack-dev-server": "5.0.4",
+    "webpack-dev-server": "5.1.0",
     "yargs": "17.7.2"
   }
 }

package/templates/hello_world/scripts/copy-env.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import * as fs from "fs";
+import * as path from "path";
+
+const envPath = path.resolve(__dirname, "..", ".env");
+const templatePath = path.resolve(__dirname, "..", ".env.template");
+
+if (!fs.existsSync(envPath)) {
+  fs.copyFileSync(templatePath, envPath);
+}

package/templates/hello_world/src/app.tsx

@@ -1,16 +1,31 @@
 import { Button, Rows, Text } from "@canva/app-ui-kit";
-import { addNativeElement } from "@canva/design";
+import { requestOpenExternalUrl } from "@canva/platform";
 import { FormattedMessage, useIntl } from "react-intl";
 import * as styles from "styles/components.css";
+import { useAddElement } from "utils/use_add_element";
+
+export const DOCS_URL = "https://www.canva.dev/docs/apps/";
 
 export const App = () => {
+  const addElement = useAddElement();
+
   const onClick = () => {
-    addNativeElement({
-      type: "TEXT",
+    addElement({
+      type: "text",
       children: ["Hello world!"],
     });
   };
 
+  const openExternalUrl = async (url: string) => {
+    const response = await requestOpenExternalUrl({
+      url,
+    });
+
+    if (response.status === "aborted") {
+      // user decided not to navigate to the link
+    }
+  };
+
   const intl = useIntl();
 
   return (
@@ -35,6 +50,13 @@ export const App = () => {
               "Button text to do something cool. Creates a new text element when pressed.",
           })}
         </Button>
+        <Button variant="secondary" onClick={() => openExternalUrl(DOCS_URL)}>
+          {intl.formatMessage({
+            defaultMessage: "Open Canva Apps SDK docs",
+            description:
+              "Button text to open Canva Apps SDK docs. Opens an external URL when pressed.",
+          })}
+        </Button>
       </Rows>
     </div>
   );

package/templates/hello_world/src/tests/__snapshots__/app.tests.tsx.snap

@@ -0,0 +1,45 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Hello World Tests should have a consistent snapshot 1`] = `
+<div>
+  <div
+    class="scrollContainer"
+  >
+    <div
+      class="jv_R6g"
+      style="--NZu1Zw: 16px;"
+    >
+      <p
+        class="fFOiLQ _5Ob_nQ fM_HdA"
+      >
+        To make changes to this app, edit the 
+        <code>
+          src/app.tsx
+        </code>
+         file, then close and reopen the app in the editor to preview the changes.
+      </p>
+      <button
+        class="_1QoxDw Qkd66A tYI0Vw o4TrkA zKTE_w Qkd66A tYI0Vw lsXp_w ubW6qw cwOZMg zQlusQ uRvRjQ"
+        type="button"
+      >
+        <span
+          class="_38oWvQ"
+        >
+          Do something cool
+        </span>
+      </button>
+      <button
+        class="_1QoxDw Qkd66A tYI0Vw o4TrkA NT2yCg Qkd66A tYI0Vw lsXp_w cwOZMg zQlusQ uRvRjQ"
+        type="button"
+      >
+        <span
+          class="_38oWvQ"
+        >
+          Open Canva Apps SDK docs
+        </span>
+      </button>
+    </div>
+  </div>
+  ,
+</div>
+`;

package/templates/hello_world/src/tests/app.tests.tsx

@@ -0,0 +1,86 @@
+/* eslint-disable formatjs/no-literal-string-in-jsx */
+import React from "react";
+import type { RenderResult } from "@testing-library/react";
+import { fireEvent, render } from "@testing-library/react";
+import { TestAppI18nProvider } from "@canva/app-i18n-kit";
+import { TestAppUiProvider } from "@canva/app-ui-kit";
+import { requestOpenExternalUrl } from "@canva/platform";
+import { useAddElement } from "utils/use_add_element";
+import { App, DOCS_URL } from "../app";
+
+function renderInTestProvider(node: React.ReactNode): RenderResult {
+  return render(
+    // In a test environment, you should wrap your apps in `TestAppI18nProvider` and `TestAppUiProvider`, rather than `AppI18nProvider` and `AppUiProvider`
+    <TestAppI18nProvider>
+      <TestAppUiProvider>{node}</TestAppUiProvider>,
+    </TestAppI18nProvider>,
+  );
+}
+
+jest.mock("utils/use_add_element");
+
+// 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 mockRequestOpenExternalUrl = jest.mocked(requestOpenExternalUrl);
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+    mockAddUseElement.mockReturnValue(mockAddElement);
+    mockRequestOpenExternalUrl.mockResolvedValue({ status: "completed" });
+  });
+
+  // this test uses a mock in place of the useAddElement 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();
+
+    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();
+
+    // get a reference to the do something cool button element
+    const doSomethingCoolBtn = result.getByRole("button", {
+      name: "Do something cool",
+    });
+
+    // programmatically simulate clicking the button
+    fireEvent.click(doSomethingCoolBtn);
+
+    // we expect that addElement has been called by the button's click handler
+    expect(mockAddElement).toHaveBeenCalled();
+  });
+
+  // this test uses a mock in place of the @canva/platform requestOpenExternalUrl function
+  it("should call `requestOpenExternalUrl` when the button is clicked", () => {
+    expect(mockRequestOpenExternalUrl).not.toHaveBeenCalled();
+
+    const result = renderInTestProvider(<App />);
+
+    // get a reference to the Apps SDK button by name
+    const sdkButton = result.getByRole("button", {
+      name: "Open Canva Apps SDK docs",
+    });
+
+    expect(mockRequestOpenExternalUrl).not.toHaveBeenCalled();
+    fireEvent.click(sdkButton);
+    expect(mockRequestOpenExternalUrl).toHaveBeenCalled();
+
+    // assert that the requestOpenExternalUrl function was called with the expected arguments
+    expect(mockRequestOpenExternalUrl.mock.calls[0][0]).toEqual({
+      url: DOCS_URL,
+    });
+  });
+
+  // this test demonstrates the use of a snapshot test
+  it("should have a consistent snapshot", () => {
+    const result = renderInTestProvider(<App />);
+    expect(result.container).toMatchSnapshot();
+  });
+});

package/templates/hello_world/utils/use_add_element.ts

@@ -0,0 +1,48 @@
+import type {
+  EmbedElement,
+  ImageElement,
+  RichtextElement,
+  TableElement,
+  TextElement,
+  VideoElement,
+} from "@canva/design";
+import { addElementAtCursor, addElementAtPoint } from "@canva/design";
+import { useFeatureSupport } from "./use_feature_support";
+import { features } from "@canva/platform";
+import { useEffect, useState } from "react";
+
+type AddElementParams =
+  | ImageElement
+  | VideoElement
+  | EmbedElement
+  | TextElement
+  | RichtextElement
+  | TableElement;
+
+export const useAddElement = () => {
+  const isSupported = useFeatureSupport();
+
+  // Store a wrapped addElement function that checks feature support
+  const [addElement, setAddElement] = useState(() => {
+    return (element: AddElementParams) => {
+      if (features.isSupported(addElementAtPoint)) {
+        return addElementAtPoint(element);
+      } else if (features.isSupported(addElementAtCursor)) {
+        return addElementAtCursor(element);
+      }
+    };
+  });
+
+  useEffect(() => {
+    const addElement = (element: AddElementParams) => {
+      if (isSupported(addElementAtPoint)) {
+        return addElementAtPoint(element);
+      } else if (isSupported(addElementAtCursor)) {
+        return addElementAtCursor(element);
+      }
+    };
+    setAddElement(() => addElement);
+  }, [isSupported]);
+
+  return addElement;
+};