@canva/cli 0.0.1-beta.9 → 1.0.1

package/templates/data_connector/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/data_connector/src/api/connect_client.ts

@@ -0,0 +1,6 @@
+import type { APIResponseItem } from "./data_source";
+
+export interface CanvaItemResponse<T extends APIResponseItem> {
+  continuation: string;
+  items: T[];
+}

package/templates/data_connector/src/api/data_source.ts

@@ -0,0 +1,96 @@
+import type { DataTable } from "@canva/intents/data";
+import { type DataTableColumn, toDataTable } from "src/utils";
+
+/**
+ * This file defines types and classes related to data source configuration, fetching and outputting as a data table.
+ * When data is loaded, the app will save the data source config so that it can be queried again later to refresh the data.
+ * Strongly typed data sources are simple to reload and validate.
+ */
+
+/**
+ * The data source configuration represents all parameters that are needed to represent the data source so that it can be queried again later.
+ * This includes the schema, any filters that are applied to the data source, and any other parameters that are needed to fetch the data.
+ */
+export interface DataSourceConfig {
+  // a unique identifier for the data source that is used to associated the saved data source config with the data source handler
+  schema: string;
+}
+
+/**
+ * the API response item is a generic type that represents the data returned from the API
+ */
+export interface APIResponseItem {
+  id: string;
+}
+
+export class DataAPIError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "APIError";
+  }
+}
+
+/**
+ * The data source handler class defines a particular data source and how to fetch data from it.
+ * In this template, the two data sources are brand templates and designs. Each data source has its own handler.
+ * The handler defines the schema for the data source configuration (what filters are applied to get the requested data), the columns to display, and how to fetch data from the API.
+ * It also defines the UI for how this source is represented on the data source selection page and how to render the data source configuration page where any filters can be set.
+ */
+export class DataSourceHandler<
+  T extends DataSourceConfig,
+  R extends APIResponseItem,
+> {
+  schema: string;
+  constructor(
+    // the configuration for this data source. The default values will be overridden by the user setting filters, or on app launch if the previous state is restored
+    public sourceConfig: T,
+    // the columns to display in the data table output. In this template they are fixed, but they could be dynamic based on the data source and configuration
+    public columns: DataTableColumn<R>[],
+    // the fetch logic for turning the data source configuration into an array of data items to turn into a data table
+    public fetchData: (
+      source: T,
+      authToken: string,
+      rowLimit: number,
+      signal: AbortSignal | undefined,
+    ) => Promise<R[]>,
+    // the UI for the data source selection page. This is where the user chooses which data source to use.
+    public selectionPage: () => JSX.Element,
+    // the UI for the data source configuration page. This is where the user sets any filters or other parameters for the data source.
+    public configPage: (sourceConfig: T) => JSX.Element,
+  ) {
+    this.schema = sourceConfig.schema;
+  }
+
+  /**
+   * A type guard / type predicate to check if the data source configuration matches the schema of this data source handler.
+   * @param source the data source configuration to match against
+   * @returns
+   */
+  matchSource(source: DataSourceConfig): source is T {
+    return source.schema === this.schema;
+  }
+
+  /**
+   * The buildTable function is called to fetch data from the API and return it as a data table.
+   * @param source the data source configuration
+   * @param authToken the auth token to use for the API request
+   * @param rowLimit the maximum number of rows to return
+   * @param signal an optional abort signal to cancel the request
+   * @returns a data table with the data from the API
+   */
+  async fetchAndBuildTable(
+    source: T,
+    authToken: string,
+    rowLimit: number,
+    signal: AbortSignal | undefined,
+  ): Promise<DataTable> {
+    let apiData: R[];
+    try {
+      apiData = await this.fetchData(source, authToken || "", rowLimit, signal);
+    } catch {
+      throw new DataAPIError("Failed to fetch data from API");
+    }
+    // the toDataTable utility takes the API data and the configured columns and turns it into a data table
+    return toDataTable(apiData, this.columns, rowLimit);
+  }
+}

package/templates/data_connector/src/api/data_sources/designs.tsx

@@ -0,0 +1,296 @@
+/* eslint-disable formatjs/no-literal-string-in-object */
+
+import type { SelectOption } from "@canva/app-ui-kit";
+import { Button, DatabaseIcon, HorizontalCard, Rows } from "@canva/app-ui-kit";
+import { useEffect, useState } from "react";
+import { useIntl } from "react-intl";
+import { useNavigate } from "react-router-dom";
+import { Header } from "src/components";
+import {
+  ownershipFilter,
+  sortOrderField,
+} from "src/components/inputs/messages";
+import { SearchFilter } from "src/components/inputs/search_filter";
+import { SelectField } from "src/components/inputs/select_field";
+import { useAppContext } from "src/context";
+import { Paths } from "src/paths";
+import { dateCell, numberCell, stringCell } from "src/utils";
+import type { CanvaItemResponse } from "../connect_client";
+import { DataAPIError, DataSourceHandler } from "../data_source";
+import type { APIResponseItem, DataSourceConfig } from "../data_source";
+
+export interface DesignsDataSource extends DataSourceConfig {
+  query: string;
+  ownership: "any" | "owned" | "shared";
+  sort_by:
+    | "relevance"
+    | "modified_descending"
+    | "modified_ascending"
+    | "title_descending"
+    | "title_ascending";
+}
+
+export interface CanvaDesign extends APIResponseItem {
+  title: string;
+  created_at: number;
+  updated_at: number;
+  page_count: number;
+}
+
+export const designsSource = new DataSourceHandler<
+  DesignsDataSource,
+  CanvaDesign
+>(
+  {
+    schema: "designs/v1",
+    query: "",
+    ownership: "any",
+    sort_by: "relevance",
+  },
+  [
+    {
+      label: "ID",
+      getValue: (design: CanvaDesign) => `ID ${design.id}`,
+      toCell: stringCell,
+    },
+    {
+      label: "Title",
+      getValue: "title",
+      toCell: stringCell,
+    },
+    {
+      label: "Created At",
+      getValue: "created_at",
+      toCell: dateCell,
+    },
+    {
+      label: "Updated At",
+      getValue: "updated_at",
+      toCell: dateCell,
+    },
+    {
+      label: "Page Count",
+      getValue: "page_count",
+      toCell: numberCell,
+    },
+  ],
+  (
+    source: DesignsDataSource,
+    authToken: string,
+    rowLimit: number,
+    signal: AbortSignal | undefined,
+  ) =>
+    getDesigns(
+      authToken,
+      rowLimit,
+      signal,
+      source.query,
+      source.ownership,
+      source.sort_by,
+    ),
+  DesignSelection,
+  DesignsSourceConfig,
+);
+
+export async function getDesigns(
+  authToken: string,
+  rowLimit: number,
+  signal: AbortSignal | undefined,
+  query: string,
+  ownership: string,
+  sort_by: string,
+  continuation?: string,
+  allItems: CanvaDesign[] = [],
+): Promise<CanvaDesign[]> {
+  const baseUrl = `https://api.canva.com/rest/v1/designs`;
+  const params = new URLSearchParams();
+  if (continuation) {
+    params.set("continuation", continuation);
+  } else {
+    if (query) {
+      params.set("query", query);
+    }
+    params.set("ownership", ownership);
+    params.set("sort_by", sort_by);
+  }
+  const url = `${baseUrl}?${params.toString()}`;
+
+  return fetch(url, {
+    headers: {
+      Authorization: `Bearer ${authToken}`,
+    },
+    signal,
+  })
+    .then((response) => {
+      if (!response.ok) {
+        throw new DataAPIError(
+          `Canva Connect response was not ok: ${response.statusText || response.status}`,
+        );
+      }
+      return response.json();
+    })
+    .then((data: CanvaItemResponse<CanvaDesign>) => {
+      const updatedItems = [...allItems, ...data.items];
+
+      if (data.continuation && updatedItems.length < rowLimit) {
+        return getDesigns(
+          authToken,
+          rowLimit,
+          signal,
+          query,
+          ownership,
+          sort_by,
+          data.continuation,
+          updatedItems,
+        );
+      }
+
+      return updatedItems;
+    });
+}
+
+function DesignSelection() {
+  const intl = useIntl();
+  const { setDataSourceHandler } = useAppContext();
+  const navigate = useNavigate();
+
+  const title = intl.formatMessage({
+    defaultMessage: "Designs",
+    description:
+      "Main heading on the designs button displayed when selecting the import type.",
+  });
+
+  const description = intl.formatMessage({
+    defaultMessage: "Query designs",
+    description:
+      "Subtext on the designs selection button displayed when selecting the import type.",
+  });
+
+  const handleClick = () => {
+    setDataSourceHandler(
+      designsSource as unknown as DataSourceHandler<
+        DataSourceConfig,
+        APIResponseItem
+      >,
+    );
+    navigate(Paths.DATA_SOURCE_CONFIG);
+  };
+
+  return (
+    <HorizontalCard
+      key="designs"
+      title={title}
+      thumbnail={{ icon: () => <DatabaseIcon /> }}
+      onClick={handleClick}
+      description={description}
+      ariaLabel={description}
+    />
+  );
+}
+
+function DesignsSourceConfig(sourceConfig: DesignsDataSource) {
+  const intl = useIntl();
+  const { loadDataSource } = useAppContext();
+  const [query, setQuery] = useState<string>(sourceConfig.query);
+  const [ownership, setOwnership] = useState<string>(sourceConfig.ownership);
+  const [sortOrder, setSortOrder] = useState<string>(sourceConfig.sort_by);
+  const [isLoading, setIsLoading] = useState(false);
+
+  const [filterCount, setFilterCount] = useState(0);
+  useEffect(() => {
+    // Update the filter count based on the selected filters
+    // consider a filter to be applied if not set to the default value
+    setFilterCount(
+      (ownership !== "any" ? 1 : 0) + (sortOrder !== "relevance" ? 1 : 0),
+    );
+  }, [ownership, sortOrder]);
+  const resetFilters = () => {
+    setOwnership("any");
+    setSortOrder("relevance");
+  };
+
+  const loadDesigns = async () => {
+    setIsLoading(true);
+    loadDataSource("Canva Designs", {
+      schema: "designs/v1",
+      query,
+      ownership,
+      sort_by: sortOrder,
+    } as DesignsDataSource).then(() => {
+      setIsLoading(false);
+    });
+  };
+
+  const ownershipOptions: SelectOption<string>[] = [
+    { value: "any", label: intl.formatMessage(ownershipFilter.any) },
+    { value: "owned", label: intl.formatMessage(ownershipFilter.owned) },
+    { value: "shared", label: intl.formatMessage(ownershipFilter.shared) },
+  ];
+
+  const sortOrderOptions: SelectOption<string>[] = [
+    { value: "relevance", label: intl.formatMessage(sortOrderField.relevance) },
+    {
+      value: "modified_descending",
+      label: intl.formatMessage(sortOrderField.modifiedDesc),
+    },
+    {
+      value: "modified_ascending",
+      label: intl.formatMessage(sortOrderField.modifiedAsc),
+    },
+    {
+      value: "title_descending",
+      label: intl.formatMessage(sortOrderField.titleDesc),
+    },
+    {
+      value: "title_ascending",
+      label: intl.formatMessage(sortOrderField.titleAsc),
+    },
+  ];
+
+  return (
+    <div>
+      <Rows spacing="2u">
+        <Header
+          title={intl.formatMessage({
+            defaultMessage: "Canva Designs",
+            description: "The header text for the designs data source",
+          })}
+          showBack={true}
+        />
+
+        <SearchFilter
+          value={query}
+          onChange={setQuery}
+          filterCount={filterCount}
+          resetFilters={resetFilters}
+        >
+          <SelectField
+            label={intl.formatMessage(ownershipFilter.label)}
+            options={ownershipOptions}
+            value={ownership}
+            onChange={setOwnership}
+          />
+          <SelectField
+            label={intl.formatMessage(sortOrderField.label)}
+            options={sortOrderOptions}
+            value={sortOrder}
+            onChange={setSortOrder}
+          />
+        </SearchFilter>
+
+        <Button
+          variant="primary"
+          loading={isLoading}
+          onClick={async () => {
+            loadDesigns();
+          }}
+        >
+          {intl.formatMessage({
+            defaultMessage: "Load Designs",
+            description: "Button for saving and applying the query filter",
+          })}
+        </Button>
+      </Rows>
+    </div>
+  );
+}

package/templates/data_connector/src/api/data_sources/index.ts

@@ -0,0 +1,4 @@
+import { designsSource } from "./designs";
+import { brandTemplatesSource } from "./templates";
+
+export const DATA_SOURCES = [designsSource, brandTemplatesSource];