@canva/cli 0.0.1-beta.2 → 0.0.1-beta.20

package/templates/hello_world/scripts/start/context.ts

@@ -3,8 +3,10 @@ import * as path from "path";
 
 interface CliArgs {
   example?: string;
-  useHttps?: boolean;
-  ngrok?: boolean;
+  useHttps: boolean;
+  ngrok: boolean;
+  preview: boolean;
+  overrideFrontendPort?: number;
 }
 
 interface EnvVars {
@@ -45,7 +47,7 @@ export class Context {
   }
 
   get ngrokEnabled() {
-    return !!this.args.ngrok;
+    return this.args.ngrok;
   }
 
   get hmrEnabled() {
@@ -53,7 +55,7 @@ export class Context {
   }
 
   get httpsEnabled() {
-    return !!this.args.useHttps;
+    return this.args.useHttps;
   }
 
   get frontendEntryPath() {
@@ -69,11 +71,11 @@ export class Context {
   }
 
   get frontendUrl() {
-    return `${this.protocol}://localhost:${this.envVars.frontendPort}`;
+    return `${this.protocol}://localhost:${this.frontendPort}`;
   }
 
   get frontendPort() {
-    return this.envVars.frontendPort;
+    return this.args.overrideFrontendPort || this.envVars.frontendPort;
   }
 
   get developerBackendEntryPath(): string | undefined {
@@ -117,6 +119,10 @@ export class Context {
     return this.envVars.appId;
   }
 
+  get openPreview(): boolean {
+    return this.args.preview;
+  }
+
   private get protocol(): "https" | "http" {
     return this.httpsEnabled ? "https" : "http";
   }

package/templates/hello_world/scripts/start/start.ts

@@ -23,6 +23,17 @@ yargs(hideBin(process.argv))
     default:
       process.env.npm_config_use_https?.toLocaleLowerCase().trim() === "true",
   })
+  .option("override-frontend-port", {
+    description:
+      "Port to run the local development server on. Overrides the frontend port set in the .env file.",
+    type: "number",
+    alias: "p",
+  })
+  .option("preview", {
+    description: "Open the app in Canva.",
+    type: "boolean",
+    default: false,
+  })
   .command(
     "$0",
     "Starts local development",

package/templates/hello_world/scripts/start/tests/start.tests.ts

@@ -0,0 +1,61 @@
+/* eslint-disable no-console */
+
+import type { ChildProcess } from "child_process";
+import { spawn } from "child_process";
+import * as treeKill from "tree-kill";
+
+describe("start script", () => {
+  let serverProcess: ChildProcess;
+
+  afterEach(() => {
+    if (serverProcess?.pid && !serverProcess.exitCode) {
+      treeKill(serverProcess.pid);
+    }
+  });
+
+  it("should execute 'npm run start' and start a dev server", async () => {
+    const testServerPort = 8089;
+    serverProcess = await spawn(
+      `npm run start -- -p ${testServerPort} --no-preview`,
+      {
+        shell: true,
+      },
+    );
+
+    if (!serverProcess.pid) {
+      throw new Error("Unable to start server");
+    }
+
+    // wait for the server to start and collect output until it reports the running URL
+    let output = "";
+    await new Promise<void>((resolve, reject) => {
+      serverProcess.stdout?.on("data", (data) => {
+        output += data.toString();
+        if (output.includes("Development URL")) {
+          resolve();
+        }
+      });
+
+      serverProcess.stderr?.on("data", (data) => {
+        console.error("Server process error: ", data.toString());
+        reject();
+      });
+
+      // timeout and fail test if the server hasn't correctly started in 10 seconds
+      setTimeout(() => {
+        if (serverProcess?.pid && !serverProcess.exitCode) {
+          treeKill(serverProcess.pid);
+        }
+        reject(new Error("Test timed out"));
+      }, 10000);
+    });
+
+    // check that the server is running and accessible
+    const expectedServerURL = `http://localhost:${testServerPort}`;
+    expect(output).toContain(expectedServerURL);
+    expect(serverProcess.exitCode).toBeNull();
+
+    // clean up
+    treeKill(serverProcess.pid);
+  }, 15000); // 15 seconds timeout to allow for the server to start
+});

package/templates/hello_world/src/app.tsx

@@ -1,16 +1,31 @@
 import { Button, Rows, Text } from "@canva/app-ui-kit";
-import { addElementAtPoint } 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 = () => {
-    addElementAtPoint({
+    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="aWBg0w aZskFA u16U_g"
+      >
+        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="_5KtATA LQzFZw VgvqkQ _8ERLTg rV61VQ LQzFZw VgvqkQ _4_iekA _3oHQrw j34Zww aqbYPg _3FvZZg"
+        type="button"
+      >
+        <span
+          class="khPe7Q"
+        >
+          Do something cool
+        </span>
+      </button>
+      <button
+        class="_5KtATA LQzFZw VgvqkQ _8ERLTg Z3nT2A LQzFZw VgvqkQ _4_iekA j34Zww aqbYPg _3FvZZg"
+        type="button"
+      >
+        <span
+          class="khPe7Q"
+        >
+          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;
+};

package/templates/hello_world/utils/use_feature_support.ts

@@ -0,0 +1,28 @@
+import { features } from "@canva/platform";
+import type { Feature } from "@canva/platform";
+import { useState, useEffect } from "react";
+
+/**
+ * This hook allows re-rendering of a React component whenever
+ * the state of feature support changes in Canva.
+ *
+ * @returns isSupported - callback to inspect a Canva SDK method.
+ **/
+export function useFeatureSupport() {
+  // Store a wrapped function that checks feature support
+  const [isSupported, setIsSupported] = useState(() => {
+    return (...args: Feature[]) => features.isSupported(...args);
+  });
+
+  useEffect(() => {
+    // create new function ref when feature support changes to trigger
+    // re-render
+    return features.registerOnSupportChange(() => {
+      setIsSupported(() => {
+        return (...args: Feature[]) => features.isSupported(...args);
+      });
+    });
+  }, []);
+
+  return isSupported;
+}

package/templates/{dam/webpack.config.cjs → hello_world/webpack.config.ts}

@@ -1,30 +1,33 @@
-require("dotenv").config();
-const path = require("path");
-const TerserPlugin = require("terser-webpack-plugin");
-const { DefinePlugin, optimize } = require("webpack");
-const chalk = require("chalk");
-const { transform } = require("@formatjs/ts-transformer");
+import type { Configuration } from "webpack";
+import { DefinePlugin, optimize } from "webpack";
+import * as path from "path";
+import * as TerserPlugin from "terser-webpack-plugin";
+import { transform } from "@formatjs/ts-transformer";
+import * as chalk from "chalk";
+import { config } from "dotenv";
+import { Configuration as DevServerConfiguration } from "webpack-dev-server";
 
-/**
- *
- * @param {Object} [options]
- * @param {string} [options.appEntry=./src/index.tsx]
- * @param {string} [options.backendHost]
- * @param {Object} [options.devConfig]
- * @param {number} [options.devConfig.port]
- * @param {boolean} [options.devConfig.enableHmr]
- * @param {boolean} [options.devConfig.enableHttps]
- * @param {string} [options.devConfig.appOrigin]
- * @param {string} [options.devConfig.appId] - Deprecated in favour of appOrigin
- * @param {string} [options.devConfig.certFile]
- * @param {string} [options.devConfig.keyFile]
- * @returns {Object}
- */
-function buildConfig({
+config();
+
+type DevConfig = {
+  port: number;
+  enableHmr: boolean;
+  enableHttps: boolean;
+  appOrigin?: string;
+  appId?: string; // Deprecated in favour of appOrigin
+  certFile?: string;
+  keyFile?: string;
+};
+
+export function buildConfig({
   devConfig,
   appEntry = path.join(process.cwd(), "src", "index.tsx"),
   backendHost = process.env.CANVA_BACKEND_HOST,
-} = {}) {
+}: {
+  devConfig?: DevConfig;
+  appEntry?: string;
+  backendHost?: string;
+} = {}): Configuration & DevServerConfiguration {
   const mode = devConfig ? "development" : "production";
 
   if (!backendHost) {
@@ -173,32 +176,23 @@ function buildConfig({
       }),
       // Apps can only submit a single JS file via the developer portal
       new optimize.LimitChunkCountPlugin({ maxChunks: 1 }),
-    ],
+    ].filter(Boolean),
     ...buildDevConfig(devConfig),
   };
 }
 
-/**
- *
- * @param {Object} [options]
- * @param {number} [options.port]
- * @param {boolean} [options.enableHmr]
- * @param {boolean} [options.enableHttps]
- * @param {string} [options.appOrigin]
- * @param {string} [options.appId] - Deprecated in favour of appOrigin
- * @param {string} [options.certFile]
- * @param {string} [options.keyFile]
- * @returns {Object|null}
- */
-function buildDevConfig(options) {
+function buildDevConfig(options?: DevConfig): {
+  devtool?: string;
+  devServer?: DevServerConfiguration;
+} {
   if (!options) {
-    return null;
+    return {};
   }
 
   const { port, enableHmr, appOrigin, appId, enableHttps, certFile, keyFile } =
     options;
 
-  let devServer = {
+  let devServer: DevServerConfiguration = {
     server: enableHttps
       ? {
           type: "https",
@@ -265,6 +259,4 @@ function buildDevConfig(options) {
   };
 }
 
-module.exports = () => buildConfig();
-
-module.exports.buildConfig = buildConfig;
+export default buildConfig;

package/templates/common/conf/eslint-i18n.mjs

@@ -1,23 +0,0 @@
-import formatjs from "eslint-plugin-formatjs";
-
-export default [
-  {
-    plugins: {
-      formatjs,
-    },
-    rules: {
-      "formatjs/no-invalid-icu": "error",
-      "formatjs/no-literal-string-in-jsx": "error",
-      "formatjs/enforce-description": "error",
-      "formatjs/enforce-default-message": "error",
-      "formatjs/enforce-placeholders": "error",
-      "formatjs/no-id": "error",
-      "formatjs/no-emoji": "error",
-      "formatjs/no-useless-message": "error",
-      "formatjs/no-multiple-plurals": "error",
-      "formatjs/no-offset": "error",
-      "formatjs/blocklist-elements": [2, ["selectordinal"]],
-      "formatjs/no-complex-selectors": "error",
-    }
-  }
-];

package/templates/dam/backend/database/database.ts

@@ -1,42 +0,0 @@
-import * as fs from "fs/promises";
-import * as path from "path";
-
-/**
- * This file creates a "database" out of a JSON file. It's only for
- * demonstration purposes. A real app should use a real database.
- */
-const DATABASE_FILE_PATH = path.join(__dirname, "db.json");
-
-interface Database<T> {
-  read(): Promise<T>;
-  write(data: T): Promise<void>;
-}
-
-export class JSONFileDatabase<T> implements Database<T> {
-  constructor(private readonly seedData: T) {}
-
-  // Creates a database file if one doesn't already exist
-  private async init(): Promise<void> {
-    try {
-      // Do nothing, since the database is initialized
-      await fs.stat(DATABASE_FILE_PATH);
-    } catch {
-      const file = JSON.stringify(this.seedData);
-      await fs.writeFile(DATABASE_FILE_PATH, file);
-    }
-  }
-
-  // Loads and parses the database file
-  async read(): Promise<T> {
-    await this.init();
-    const file = await fs.readFile(DATABASE_FILE_PATH, "utf8");
-    return JSON.parse(file);
-  }
-
-  // Overwrites the database file with provided data
-  async write(data: T): Promise<void> {
-    await this.init();
-    const file = JSON.stringify(data);
-    await fs.writeFile(DATABASE_FILE_PATH, file);
-  }
-}