@canva/cli 1.11.0 → 1.13.0

package/templates/mls/scripts/start/app_runner.ts

@@ -0,0 +1,223 @@
+/* eslint-disable no-console */
+import { generatePreviewUrl } from "@canva/cli";
+import ngrok from "@ngrok/ngrok";
+import chalk from "chalk";
+import Table from "cli-table3";
+import nodemon from "nodemon";
+import open from "open";
+import os from "os";
+import webpack from "webpack";
+import WebpackDevServer from "webpack-dev-server";
+import { buildConfig } from "../../webpack.config";
+import type { Certificate } from "../ssl/ssl";
+import { createOrRetrieveCertificate } from "../ssl/ssl";
+import type { Context } from "./context";
+
+export const infoChalk = chalk.blue.bold;
+export const warnChalk = chalk.bgYellow.bold;
+export const errorChalk = chalk.bgRed.bold;
+export const highlightChalk = chalk.greenBright.bold;
+export const linkChalk = chalk.cyan;
+
+/**
+ * Returns the appropriate modifier key text based on the user's operating system.
+ * @returns "cmd" for macOS, "ctrl" for Windows and Linux
+ */
+export function getModifierKey(): string {
+  const platform = os.platform();
+  switch (platform) {
+    case "darwin": // macOS
+      return "cmd";
+    case "win32": // Windows
+      return "ctrl";
+    default: // Linux and others
+      return "ctrl";
+  }
+}
+
+export class AppRunner {
+  async run(ctx: Context) {
+    console.log(
+      infoChalk("Info:"),
+      `Starting development server for ${highlightChalk(ctx.entryDir)}\n`,
+    );
+
+    if (!ctx.hmrEnabled) {
+      console.log(
+        `${infoChalk(
+          "Note:",
+        )} Hot Module Replacement (HMR) not enabled. To enable it, please refer to the instructions in the ${highlightChalk(
+          "README.md",
+        )}\n`,
+      );
+    }
+
+    let cert: Certificate | undefined;
+    if (ctx.httpsEnabled) {
+      try {
+        cert = await createOrRetrieveCertificate();
+      } catch (err) {
+        console.log(
+          errorChalk("Error:"),
+          "Unable to generate SSL certificate.",
+        );
+        throw err;
+      }
+    }
+
+    const table = new Table({
+      colWidths: [30, 80],
+      wordWrap: true,
+      wrapOnWordBoundary: true,
+    });
+
+    const server = await this.runWebpackDevServer(ctx, table, cert);
+
+    await this.maybeRunBackendServer(ctx, table, cert, server);
+
+    await this.generateAndOpenPreviewUrl(ctx.openPreview, table);
+
+    console.log(table.toString(), "\n");
+
+    console.log(
+      `${infoChalk(
+        "Note:",
+      )} For instructions on how to set up the app via the Developer Portal, see the ${highlightChalk(
+        "README.md",
+      )}.\n`,
+    );
+  }
+
+  private readonly maybeRunBackendServer = async (
+    ctx: Context,
+    table: Table.Table,
+    cert: Certificate | undefined,
+    webpackDevServer: WebpackDevServer,
+  ) => {
+    if (!ctx.developerBackendEntryPath) {
+      return;
+    }
+
+    // App ID must be set when running a backend example
+    if (!ctx.appId) {
+      console.log(
+        errorChalk("Error:"),
+        `'CANVA_APP_ID' environment variable is undefined. Refer to the instructions in the ${highlightChalk(
+          "README.md",
+        )} on starting a backend example.`,
+      );
+      throw new Error("'CANVA_APP_ID' env variable not set.");
+    }
+
+    await new Promise((resolve) => {
+      const nodemonServer = nodemon({
+        script: ctx.developerBackendEntryPath,
+        ext: "ts",
+        env: {
+          SHOULD_ENABLE_HTTPS: ctx.httpsEnabled,
+          HTTPS_CERT_FILE: cert?.certFile || "",
+          HTTPS_KEY_FILE: cert?.keyFile || "",
+        },
+      });
+
+      nodemonServer.on("start", resolve);
+
+      nodemonServer.on("crash", async () => {
+        console.log(errorChalk("Shutting down local server.\n"));
+
+        await webpackDevServer.stop();
+        process.exit(1);
+      });
+    });
+
+    if (ctx.ngrokEnabled) {
+      console.log(
+        warnChalk("Warning:"),
+        `ngrok exposes a local port via a public URL. Be mindful of what's exposed and shut down the server when it's not in use.\n`,
+      );
+    }
+
+    let url = ctx.backendUrl;
+    if (ctx.ngrokEnabled) {
+      try {
+        const ngrokListener = await ngrok.forward({
+          addr: ctx.backendPort,
+          // requires an `NGROK_AUTHTOKEN` env var to be set
+          authtoken_from_env: true,
+        });
+        url = ngrokListener.url() ?? url;
+      } catch (err) {
+        console.log(
+          errorChalk("Error:"),
+          `Unable to start ngrok server: ${err}`,
+        );
+      }
+    }
+
+    table.push(["Base URL (Backend)", linkChalk(url)]);
+  };
+
+  private readonly runWebpackDevServer = async (
+    ctx: Context,
+    table: Table.Table,
+    cert: Certificate | undefined,
+  ): Promise<WebpackDevServer> => {
+    const runtimeWebpackConfig = buildConfig({
+      appEntry: ctx.frontendEntryPath,
+      backendHost: ctx.backendHost,
+      devConfig: {
+        port: ctx.frontendPort,
+        enableHmr: ctx.hmrEnabled,
+        appId: ctx.appId,
+        appOrigin: ctx.appOrigin,
+        enableHttps: ctx.httpsEnabled,
+        ...cert,
+      },
+    });
+
+    const compiler = webpack(runtimeWebpackConfig);
+    const server = new WebpackDevServer(
+      runtimeWebpackConfig.devServer,
+      compiler,
+    );
+    await server.start();
+
+    table.push(["Development URL (Frontend)", linkChalk(ctx.frontendUrl)]);
+
+    return server;
+  };
+
+  /**
+   * Calls the Canva CLI to generate a preview URL for the app
+   */
+  private readonly generateAndOpenPreviewUrl = async (
+    openPreview: boolean,
+    table: Table.Table,
+  ) => {
+    const previewCellHeader = { content: "Preview your app in Canva" };
+
+    const generatePreviewResult = await generatePreviewUrl();
+
+    if (!generatePreviewResult.success) {
+      table.push([
+        previewCellHeader,
+        { content: warnChalk(generatePreviewResult.message) },
+      ]);
+      return;
+    }
+
+    const modifierKey = getModifierKey();
+
+    table.push([
+      previewCellHeader,
+      {
+        content: `Preview URL (${modifierKey} + click)`,
+        href: generatePreviewResult.data,
+      },
+    ]);
+
+    if (openPreview) {
+      open(generatePreviewResult.data);
+    }
+  };
+}

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

@@ -0,0 +1,171 @@
+import fs from "fs";
+import path from "path";
+
+interface CliArgs {
+  example?: string;
+  useHttps: boolean;
+  ngrok: boolean;
+  preview: boolean;
+  overrideFrontendPort?: number;
+}
+
+interface EnvVars {
+  frontendPort: number;
+  backendPort: number;
+  hmrEnabled: boolean;
+  appId?: string;
+  appOrigin?: string;
+  backendHost?: string;
+}
+
+export class Context {
+  private readonly envVars: EnvVars;
+
+  constructor(
+    private env: NodeJS.ProcessEnv = process.env,
+    private readonly args: CliArgs,
+  ) {
+    this.envVars = this.parseAndValidateEnvironmentVariables();
+  }
+
+  static get srcDir() {
+    const src = path.join(Context.rootDir, "src");
+
+    if (!fs.existsSync(src)) {
+      throw new Error(`Directory does not exist: ${src}`);
+    }
+
+    return src;
+  }
+
+  static get readmeDir() {
+    return path.join(Context.rootDir, "README.md");
+  }
+
+  get entryDir() {
+    return Context.srcDir;
+  }
+
+  get ngrokEnabled() {
+    return this.args.ngrok;
+  }
+
+  get hmrEnabled() {
+    return this.envVars.hmrEnabled;
+  }
+
+  get httpsEnabled() {
+    return this.args.useHttps;
+  }
+
+  get frontendEntryPath() {
+    const frontendEntryPath = path.join(this.entryDir, "index.tsx");
+
+    if (!fs.existsSync(frontendEntryPath)) {
+      throw new Error(
+        `Entry point for frontend does not exist: ${frontendEntryPath}`,
+      );
+    }
+
+    return frontendEntryPath;
+  }
+
+  get frontendUrl() {
+    return `${this.protocol}://localhost:${this.frontendPort}`;
+  }
+
+  get frontendPort() {
+    return this.args.overrideFrontendPort || this.envVars.frontendPort;
+  }
+
+  get developerBackendEntryPath(): string | undefined {
+    const developerBackendEntryPath = path.join(
+      Context.rootDir,
+      "backend",
+      "server.ts",
+    );
+
+    if (!fs.existsSync(developerBackendEntryPath)) {
+      return undefined;
+    }
+
+    return developerBackendEntryPath;
+  }
+
+  get backendUrl() {
+    return `${this.protocol}://localhost:${this.envVars.backendPort}`;
+  }
+
+  get backendHost() {
+    let backendHost = this.envVars.backendHost;
+
+    // if there's no custom URL provided by the developer, we fallback to our localhost backend
+    if (!backendHost || backendHost.trim() === "") {
+      backendHost = this.backendUrl;
+    }
+
+    return backendHost;
+  }
+
+  get backendPort() {
+    return this.envVars.backendPort;
+  }
+
+  get appOrigin(): string | undefined {
+    return this.envVars.appOrigin;
+  }
+
+  get appId(): string | undefined {
+    return this.envVars.appId;
+  }
+
+  get openPreview(): boolean {
+    return this.args.preview;
+  }
+
+  private get protocol(): "https" | "http" {
+    return this.httpsEnabled ? "https" : "http";
+  }
+
+  private static get rootDir() {
+    return path.join(process.cwd());
+  }
+
+  private parseAndValidateEnvironmentVariables(): EnvVars {
+    const {
+      CANVA_FRONTEND_PORT,
+      CANVA_BACKEND_PORT,
+      CANVA_BACKEND_HOST,
+      CANVA_APP_ID,
+      CANVA_APP_ORIGIN,
+      CANVA_HMR_ENABLED,
+    } = this.env;
+
+    if (!CANVA_FRONTEND_PORT) {
+      throw new Error(
+        "CANVA_FRONTEND_PORT environment variable is not defined",
+      );
+    }
+
+    if (!CANVA_BACKEND_PORT) {
+      throw new Error("CANVA_BACKEND_PORT environment variable is not defined");
+    }
+
+    const envVars: EnvVars = {
+      frontendPort: parseInt(CANVA_FRONTEND_PORT, 10),
+      backendPort: parseInt(CANVA_BACKEND_PORT, 10),
+      hmrEnabled: CANVA_HMR_ENABLED?.toLowerCase().trim() === "true",
+      appId: CANVA_APP_ID,
+      appOrigin: CANVA_APP_ORIGIN,
+      backendHost: CANVA_BACKEND_HOST,
+    };
+
+    if (envVars.hmrEnabled && envVars.appOrigin == null) {
+      throw new Error(
+        "CANVA_HMR_ENABLED environment variable is TRUE, but CANVA_APP_ORIGIN is not set. Refer to the instructions in the README.md on configuring HMR.",
+      );
+    }
+
+    return envVars;
+  }
+}

package/templates/mls/scripts/start/start.ts

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import { AppRunner } from "./app_runner";
+import { Context } from "./context";
+
+const appRunner = new AppRunner();
+
+yargs(hideBin(process.argv))
+  .version(false)
+  .help()
+  .option("ngrok", {
+    description: "Run backend server via ngrok.",
+    type: "boolean",
+    // npm swallows command line args instead of forwarding to the script
+    default:
+      process.env.npm_config_ngrok?.toLocaleLowerCase().trim() === "true",
+  })
+  .option("use-https", {
+    description: "Start local development server on HTTPS.",
+    type: "boolean",
+    // npm swallows commands line args instead of forwarding to the script
+    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",
+    () => {},
+    (args) => {
+      const ctx = new Context(process.env, args);
+      appRunner.run(ctx);
+    },
+  )
+  .parse();

package/templates/mls/src/__tests__/app.tests.tsx

@@ -0,0 +1,11 @@
+import { screen } from "@testing-library/react";
+import React from "react";
+import { App } from "../intents/design_editor/app";
+import { renderInTestProvider } from "./utils";
+
+describe("App", () => {
+  it("should render the app and start at the office selection page", () => {
+    renderInTestProvider(<App />);
+    expect(screen.getByText(/select office/i)).toBeInTheDocument();
+  });
+});

package/templates/mls/src/__tests__/office_selection_page.tests.tsx

@@ -0,0 +1,72 @@
+import { screen, waitFor } from "@testing-library/react";
+import React from "react";
+import { OfficeSelectionPage } from "../pages/office_selection_page/office_selection_page";
+import { renderInTestProvider, renderWithUserEvent } from "./utils";
+const mockNavigate = jest.fn();
+
+jest.mock("react-router-dom", () => ({
+  ...jest.requireActual("react-router-dom"),
+  useNavigate: () => mockNavigate,
+}));
+
+const mockOffices = [
+  { id: "office1", name: "Murray Street" },
+  { id: "office2", name: "Jermaine Street" },
+];
+// Mock the adapter module
+jest.mock("../adapter.ts", () => ({
+  fetchOffices: jest.fn().mockResolvedValue(mockOffices),
+}));
+
+describe("Office selection page", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("should require a selection of office to continue", async () => {
+    const { user } = renderWithUserEvent(<OfficeSelectionPage />);
+
+    // Should start at office selection page
+    expect(screen.getByText(/select office/i)).toBeInTheDocument();
+
+    // Click the Continue button to submit the form (should show validation error first)
+    const continueButton = screen.getByText("Continue");
+    user.click(continueButton);
+
+    // Should show validation error
+    await waitFor(() => {
+      expect(screen.getByText(/please select an office/i)).toBeInTheDocument();
+    });
+  });
+
+  it("should render user account information", async () => {
+    renderInTestProvider(<OfficeSelectionPage />);
+
+    // Should show user account section
+    expect(screen.getByText("Account")).toBeInTheDocument();
+    expect(screen.getAllByText("Alex Chen")[0]).toBeInTheDocument();
+    expect(screen.getByText("alex.chen@example.com")).toBeInTheDocument();
+  });
+
+  it("should navigate to loading page once user selects an office", async () => {
+    const { user } = renderWithUserEvent(<OfficeSelectionPage />);
+    const office = mockOffices[0];
+
+    if (!office) {
+      throw new Error("No mock office found");
+    }
+
+    user.click(screen.getByText("Select office"));
+    await waitFor(() => {
+      expect(screen.getByText(office.name)).toBeInTheDocument();
+    });
+    user.click(screen.getByText(office.name));
+    user.click(screen.getByText("Continue"));
+    await waitFor(() => {
+      expect(mockNavigate).toHaveBeenCalledTimes(1);
+      expect(mockNavigate).toHaveBeenCalledWith("/loading", {
+        state: { office },
+      });
+    });
+  });
+});

package/templates/mls/src/__tests__/utils.tsx

@@ -0,0 +1,19 @@
+import { TestAppI18nProvider } from "@canva/app-i18n-kit";
+import { TestAppUiProvider } from "@canva/app-ui-kit";
+import { render } from "@testing-library/react";
+import type { RenderResult } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+export const renderWithUserEvent = (node: React.ReactNode) => {
+  const user = userEvent.setup();
+  renderInTestProvider(node);
+  return { user };
+};
+
+export function renderInTestProvider(node: React.ReactNode): RenderResult {
+  return render(
+    <TestAppI18nProvider>
+      <TestAppUiProvider>{node}</TestAppUiProvider>
+    </TestAppI18nProvider>,
+  );
+}

package/templates/mls/src/adapter.ts

@@ -0,0 +1,126 @@
+import { agents, listings } from "./data";
+import type { Agent, Office, Property } from "./real_estate.type";
+
+// TODO (App Developer): replace with the real API call
+export const fetchAgents = async (
+  office?: Office | null,
+  query?: string,
+  continuation?: string,
+  sortBy?: string,
+): Promise<{ agents: Agent[]; continuation?: string }> => {
+  // eslint-disable-next-line no-console
+  console.log("fetchingAgents", { query, continuation, office });
+
+  if (office?.id === "listings-only-office" || office?.id === "empty-office") {
+    return { agents: [], continuation: undefined };
+  }
+
+  if (office?.id === "error-office" || query === "error") {
+    throw new Error("Error fetching agents");
+  }
+  // Apply sorting
+  if (sortBy) {
+    const [field, direction] = sortBy.split("-");
+
+    if (field === "name") {
+      agents.sort((a, b) => {
+        const comparison = a.name.localeCompare(b.name);
+        return direction === "asc" ? comparison : -comparison;
+      });
+    }
+  }
+
+  // Simulate a delay
+  await new Promise((resolve) => setTimeout(resolve, 10));
+
+  let filteredAgents = agents;
+
+  // Apply search query
+  if (query) {
+    filteredAgents = filteredAgents.filter(
+      (agent) =>
+        agent.name.toLowerCase().includes(query.toLowerCase()) ||
+        (agent.officeId &&
+          agent.officeId.toLowerCase().includes(query.toLowerCase())),
+    );
+  }
+
+  if (filteredAgents.length === 0) {
+    return { agents: [], continuation: undefined };
+  }
+
+  return {
+    agents: filteredAgents,
+    continuation:
+      continuation && !query ? `${Number(continuation) + 1}` : undefined,
+  };
+};
+
+// TODO (App Developer): replace with real API calls
+export const fetchListings = async (
+  office?: Office | null,
+  query?: string,
+  propertyType?: string | null,
+  sortBy?: string | null,
+  continuation?: string,
+): Promise<{ listings: Property[]; continuation?: string }> => {
+  // eslint-disable-next-line no-console
+  console.log("fetchingListings", {
+    query,
+    continuation,
+    propertyType,
+    sortBy,
+  });
+  // Simulate a delay
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+
+  if (office?.id === "empty-office" || office?.id === "agents-only-office") {
+    return { listings: [], continuation: undefined };
+  }
+
+  if (office?.id === "error-office" || query === "error") {
+    throw new Error("Error fetching listings");
+  }
+
+  let filteredListings = listings;
+
+  // Example filters
+  // Apply property type filter
+  if (propertyType) {
+    filteredListings = filteredListings.filter(
+      (listing) =>
+        listing.listingType.toLowerCase() === propertyType.toLowerCase(),
+    );
+  }
+
+  // Apply sorting filter
+  if (sortBy) {
+    filteredListings = [...filteredListings].sort((a, b) => {
+      const aPrice = parseFloat(a.price.replace(/[$,]/g, ""));
+      const bPrice = parseFloat(b.price.replace(/[$,]/g, ""));
+      return sortBy === "price-asc" ? aPrice - bPrice : bPrice - aPrice;
+    });
+  }
+
+  // Apply search query
+  if (query) {
+    filteredListings = filteredListings.filter(
+      (listing) =>
+        listing.address.toLowerCase().includes(query.toLowerCase()) ||
+        listing.suburb.toLowerCase().includes(query.toLowerCase()) ||
+        listing.description.toLowerCase().includes(query.toLowerCase()) ||
+        listing.name.toLowerCase().includes(query.toLowerCase()) ||
+        listing.title.toLowerCase().includes(query.toLowerCase()),
+    );
+  }
+
+  if (filteredListings.length === 0) {
+    return { listings: [], continuation: undefined };
+  }
+
+  return {
+    listings: filteredListings,
+    continuation:
+      continuation && !query ? `${Number(continuation) + 1}` : undefined,
+  };
+};