@canva/cli 0.0.1-beta.28 → 0.0.1-beta.29

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

@@ -0,0 +1,287 @@
+/* eslint-disable formatjs/no-literal-string-in-object */
+import { useAppContext } from "src/context";
+import type { APIResponseItem, DataSourceConfig } from "../data_source";
+import { DataAPIError, DataSourceHandler } from "../data_source";
+import type { CanvaItemResponse } from "../connect_client";
+import { dateCell, stringCell } from "src/utils";
+import type { SelectOption } from "@canva/app-ui-kit";
+import {
+  Button,
+  HorizontalCard,
+  Rows,
+  TableMergedHeaderCellsIcon,
+} from "@canva/app-ui-kit";
+import { useIntl } from "react-intl";
+import {
+  datasetFilter,
+  ownershipFilter,
+  sortOrderField,
+} from "src/components/inputs/messages";
+import { SelectField } from "src/components/inputs/select_field";
+import { Header } from "src/components";
+import { useNavigate } from "react-router-dom";
+import { Paths } from "src/routes";
+import { useState } from "react";
+
+export interface BrandTemplatesDataSource extends DataSourceConfig {
+  dataset: "any" | "non_empty" | "empty";
+  ownership: "any" | "owned" | "shared";
+  sort_by:
+    | "relevance"
+    | "modified_descending"
+    | "modified_ascending"
+    | "title_descending"
+    | "title_ascending";
+}
+
+export interface CanvaBrandTemplate extends APIResponseItem {
+  title: string;
+  created_at: number;
+  updated_at: number;
+  view_url: string;
+  create_url: string;
+}
+
+export const brandTemplatesSource = new DataSourceHandler<
+  BrandTemplatesDataSource,
+  CanvaBrandTemplate
+>(
+  {
+    schema: "brand_templates/v1",
+    dataset: "any",
+    ownership: "any",
+    sort_by: "relevance",
+  },
+  [
+    {
+      label: "ID",
+      getValue: (template: CanvaBrandTemplate) => `ID ${template.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: "View URL",
+      getValue: "view_url",
+      toCell: stringCell,
+    },
+    {
+      label: "Create URL",
+      getValue: "create_url",
+      toCell: stringCell,
+    },
+  ],
+  (
+    source: BrandTemplatesDataSource,
+    authToken: string,
+    rowLimit: number,
+    signal: AbortSignal | undefined,
+  ) =>
+    getBrandTemplates(
+      authToken,
+      rowLimit,
+      signal,
+      source.dataset,
+      source.ownership,
+      source.sort_by,
+    ),
+  BrandTemplatesSelection,
+  BrandTemplatesSourceConfig,
+);
+
+export async function getBrandTemplates(
+  authToken: string,
+  rowLimit: number,
+  signal: AbortSignal | undefined,
+  ownership: string,
+  dataset: string,
+  sort_by: string,
+  continuation?: string,
+  allItems: CanvaBrandTemplate[] = [],
+): Promise<CanvaBrandTemplate[]> {
+  const baseUrl = `https://api.canva.com/rest/v1/brand-templates`;
+  const url = continuation
+    ? `${baseUrl}?continuation=${continuation}`
+    : `${baseUrl}?ownership=${ownership}&dataset=${dataset}&sort_by=${sort_by}`;
+
+  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<CanvaBrandTemplate>) => {
+      const updatedItems = [...allItems, ...data.items];
+
+      if (data.continuation && updatedItems.length < rowLimit) {
+        return getBrandTemplates(
+          authToken,
+          rowLimit,
+          signal,
+          ownership,
+          dataset,
+          sort_by,
+          data.continuation,
+          updatedItems,
+        );
+      }
+
+      return updatedItems;
+    });
+}
+
+function BrandTemplatesSelection() {
+  const intl = useIntl();
+  const { setDataSourceHandler } = useAppContext();
+  const navigate = useNavigate();
+
+  const title = intl.formatMessage({
+    defaultMessage: "Brand Templates",
+    description:
+      "Main heading on the brand templates button displayed when selecting the import type.",
+  });
+
+  const description = intl.formatMessage({
+    defaultMessage: "Query brand templates",
+    description:
+      "Subtext on the brand templates button displayed when selecting the import type.",
+  });
+
+  const handleClick = () => {
+    setDataSourceHandler(
+      brandTemplatesSource as unknown as DataSourceHandler<
+        DataSourceConfig,
+        APIResponseItem
+      >,
+    );
+    navigate(Paths.DATA_SOURCE_CONFIG);
+  };
+
+  return (
+    <HorizontalCard
+      key="brand-templates"
+      title={title}
+      thumbnail={{ icon: () => <TableMergedHeaderCellsIcon /> }}
+      onClick={handleClick}
+      description={description}
+      ariaLabel={description}
+    />
+  );
+}
+
+function BrandTemplatesSourceConfig(sourceConfig: BrandTemplatesDataSource) {
+  const { loadDataSource } = useAppContext();
+  const [ownership, setOwnership] = useState<string>(sourceConfig.ownership);
+  const [sortOrder, setSortOrder] = useState<string>(sourceConfig.sort_by);
+  const [dataset, setDataset] = useState<string>(sourceConfig.dataset);
+  const [isLoading, setIsLoading] = useState(false);
+  const intl = useIntl();
+
+  const loadTemplates = async () => {
+    loadDataSource("Canva Brand Templates", {
+      schema: "brand_templates/v1",
+      ownership,
+      dataset,
+      sort_by: sortOrder,
+    } as BrandTemplatesDataSource).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),
+    },
+  ];
+
+  const datasetOptions: SelectOption<string>[] = [
+    { value: "any", label: intl.formatMessage(datasetFilter.any) },
+    { value: "non_empty", label: intl.formatMessage(datasetFilter.nonEmpty) },
+    { value: "empty", label: intl.formatMessage(datasetFilter.empty) },
+  ];
+
+  return (
+    <div>
+      <Header
+        title={intl.formatMessage({
+          defaultMessage: "Canva Brand Templates",
+          description: "The header text for the brand templates data source",
+        })}
+        showBack={true}
+      />
+      <Rows spacing="2u">
+        <SelectField
+          label={intl.formatMessage(ownershipFilter.label)}
+          options={ownershipOptions}
+          value={ownership}
+          onChange={setOwnership}
+        />
+        <SelectField
+          label={intl.formatMessage(datasetFilter.label)}
+          options={datasetOptions}
+          value={dataset}
+          onChange={setDataset}
+        />
+        <SelectField
+          label={intl.formatMessage(sortOrderField.label)}
+          options={sortOrderOptions}
+          value={sortOrder}
+          onChange={setSortOrder}
+        />
+        <Button
+          variant="primary"
+          loading={isLoading}
+          onClick={async () => {
+            loadTemplates();
+          }}
+        >
+          {intl.formatMessage({
+            defaultMessage: "Load Templates",
+            description: "Button for saving and applying the query filter",
+          })}
+        </Button>
+      </Rows>
+    </div>
+  );
+}

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

@@ -0,0 +1,51 @@
+import type {
+  FetchDataTableParams,
+  FetchDataTableResult,
+} from "@canva/intents/data";
+import { DATA_SOURCES } from "./data_sources";
+import {
+  appError,
+  completeDataTable,
+  outdatedSourceRef,
+  remoteRequestFailed,
+} from "src/utils/fetch_result";
+import { DataAPIError } from ".";
+
+/**
+ * This function handles parsing the data fetch parameters and calling the appropriate handler for the data source.
+ * @param fetchParams
+ * @param authToken
+ * @returns
+ */
+export const buildDataTableResult = async (
+  fetchParams: FetchDataTableParams,
+  authToken?: string,
+): Promise<FetchDataTableResult> => {
+  const source = JSON.parse(fetchParams.dataSourceRef.source);
+  const rowLimit = fetchParams.limit.row - 1; // -1 for the header row
+
+  const dataHandler = DATA_SOURCES.find((handler) =>
+    handler.matchSource(source),
+  );
+  if (!dataHandler) {
+    // the configured source does not match the expected data source type
+    // return an error result which will prompt the user to reconfigure the data source
+    return outdatedSourceRef();
+  }
+  try {
+    const dataTable = await dataHandler.fetchAndBuildTable(
+      source,
+      authToken || "",
+      rowLimit,
+      fetchParams.signal,
+    );
+    return completeDataTable(dataTable);
+  } catch (error) {
+    if (error instanceof DataAPIError) {
+      return remoteRequestFailed();
+    }
+    return appError(
+      error instanceof Error ? error.message : "An unknown error occurred",
+    );
+  }
+};

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

@@ -0,0 +1,4 @@
+export * from "./connect_client";
+export * from "./fetch_data_table";
+export * from "./data_source";
+export * from "./oauth";

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

@@ -0,0 +1,8 @@
+/**
+ * The scopes to request as part of the OAuth flow.
+ * These scopes are required to read the user's designs and brand templates.
+ *
+ * @see https://www.canva.dev/docs/apps/authenticating-users/oauth/#overview - for more information about using the @canva/user package to support OAuth login.
+ * @see https://www.canva.dev/docs/connect/appendix/scopes/ - for a full list of Canva Connect API scopes.
+ */
+export const scope = new Set(["design:meta:read", "brandtemplate:meta:read"]);

package/templates/data_connector/src/api/tests/data_source.test.tsx

@@ -0,0 +1,99 @@
+/* eslint-disable formatjs/no-literal-string-in-object */
+/* eslint-disable formatjs/no-literal-string-in-jsx */
+import type { DataSourceConfig, APIResponseItem } from "../data_source";
+import { DataSourceHandler, DataAPIError } from "../data_source";
+import { toDataTable } from "src/utils";
+
+// Mock dependencies
+jest.mock("src/utils", () => ({
+  toDataTable: jest.fn().mockReturnValue({ rows: [] }),
+}));
+
+describe("DataSourceHandler", () => {
+  // Test interface
+  interface TestConfig extends DataSourceConfig {
+    testField: string;
+  }
+
+  interface TestResponse extends APIResponseItem {
+    name: string;
+  }
+
+  // Test data
+  const mockConfig: TestConfig = {
+    schema: "test/v1",
+    testField: "value",
+  };
+
+  const mockColumns = [
+    {
+      label: "ID",
+      getValue: (item: TestResponse) => `ID ${item.id}`,
+      toCell: jest.fn().mockReturnValue({ type: "string", value: "id-123" }),
+    },
+    {
+      label: "Name",
+      getValue: "name" as const,
+      toCell: jest.fn().mockReturnValue({ type: "string", value: "Test Name" }),
+    },
+  ];
+
+  const mockFetchData = jest.fn();
+  const mockSelectionPage = jest.fn().mockReturnValue(<div>Selection</div>);
+  const mockConfigPage = jest.fn().mockReturnValue(<div>Config</div>);
+
+  let handler: DataSourceHandler<TestConfig, TestResponse>;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    handler = new DataSourceHandler<TestConfig, TestResponse>(
+      mockConfig,
+      mockColumns,
+      mockFetchData,
+      mockSelectionPage,
+      mockConfigPage,
+    );
+  });
+
+  test("creates handler with correct schema", () => {
+    expect(handler.schema).toBe("test/v1");
+    expect(handler.sourceConfig).toEqual(mockConfig);
+  });
+
+  test("matchSource returns true for matching schema", () => {
+    const result = handler.matchSource({ schema: "test/v1" });
+    expect(result).toBe(true);
+  });
+
+  test("matchSource returns false for non-matching schema", () => {
+    const result = handler.matchSource({ schema: "wrong/v1" });
+    expect(result).toBe(false);
+  });
+
+  test("fetchAndBuildTable calls fetchData with correct parameters", async () => {
+    const mockData = [{ id: "id-123", name: "Test Item" }];
+    mockFetchData.mockResolvedValueOnce(mockData);
+
+    const authToken = "test-token";
+    const rowLimit = 10;
+    const signal = new AbortController().signal;
+
+    await handler.fetchAndBuildTable(mockConfig, authToken, rowLimit, signal);
+
+    expect(mockFetchData).toHaveBeenCalledWith(
+      mockConfig,
+      authToken,
+      rowLimit,
+      signal,
+    );
+    expect(toDataTable).toHaveBeenCalledWith(mockData, mockColumns, rowLimit);
+  });
+
+  test("fetchAndBuildTable throws DataAPIError when fetchData fails", async () => {
+    mockFetchData.mockRejectedValueOnce(new Error("Network error"));
+
+    await expect(
+      handler.fetchAndBuildTable(mockConfig, "token", 10, undefined),
+    ).rejects.toThrow(DataAPIError);
+  });
+});

package/templates/data_connector/src/app.tsx

@@ -0,0 +1,24 @@
+import { createHashRouter, RouterProvider } from "react-router-dom";
+import { ContextProvider } from "./context";
+import { routes } from "./routes";
+import { AppUiProvider } from "@canva/app-ui-kit";
+import { AppI18nProvider } from "@canva/app-i18n-kit";
+import { ErrorBoundary } from "react-error-boundary";
+import { ErrorPage } from "./pages";
+import type { RenderSelectionUiParams } from "@canva/intents/data";
+
+export const App = ({
+  dataParams,
+}: {
+  dataParams: RenderSelectionUiParams;
+}) => (
+  <AppI18nProvider>
+    <AppUiProvider>
+      <ErrorBoundary fallback={<ErrorPage />}>
+        <ContextProvider renderSelectionUiParams={dataParams}>
+          <RouterProvider router={createHashRouter(routes)} />
+        </ContextProvider>
+      </ErrorBoundary>
+    </AppUiProvider>
+  </AppI18nProvider>
+);

package/templates/data_connector/src/components/app_error.tsx

@@ -0,0 +1,15 @@
+import { Alert } from "@canva/app-ui-kit";
+import { useAppContext } from "src/context";
+
+export const AppError = () => {
+  const { appError, setAppError } = useAppContext();
+  if (!appError) {
+    return null;
+  }
+
+  return (
+    <Alert tone="critical" onDismiss={() => setAppError("")}>
+      {appError}
+    </Alert>
+  );
+};

package/templates/data_connector/src/components/footer.tsx

@@ -0,0 +1,26 @@
+import { Rows, Button } from "@canva/app-ui-kit";
+import { useIntl } from "react-intl";
+import { useAppContext } from "src/context";
+
+export const Footer = () => {
+  const { isAuthenticated, logout } = useAppContext();
+  const intl = useIntl();
+
+  return (
+    <Rows spacing="1u">
+      {isAuthenticated && (
+        <Button
+          variant="tertiary"
+          onClick={async () => {
+            logout();
+          }}
+        >
+          {intl.formatMessage({
+            defaultMessage: "Log Out",
+            description: "Button for logging out of the data source",
+          })}
+        </Button>
+      )}
+    </Rows>
+  );
+};

package/templates/data_connector/src/components/header.tsx

@@ -0,0 +1,40 @@
+import { useNavigate } from "react-router-dom";
+import {
+  ArrowLeftIcon,
+  Box,
+  Button,
+  Column,
+  Columns,
+  Title,
+} from "@canva/app-ui-kit";
+import { Paths } from "src/routes";
+
+export const Header = ({
+  title,
+  showBack,
+}: {
+  title: string;
+  showBack: boolean;
+}) => {
+  const navigate = useNavigate();
+  return (
+    <Box paddingBottom="1u">
+      <Columns spacing="0" alignY="center" align="start">
+        {showBack && (
+          <Column width="content">
+            <Button
+              onClick={() => navigate(Paths.DATA_SOURCE_SELECTION)}
+              icon={ArrowLeftIcon}
+              variant="tertiary"
+            />
+          </Column>
+        )}
+        <Column>
+          <Title size="small" lineClamp={1}>
+            {title}
+          </Title>
+        </Column>
+      </Columns>
+    </Box>
+  );
+};

package/templates/data_connector/src/components/index.ts

@@ -0,0 +1,3 @@
+export * from "./app_error";
+export * from "./footer";
+export * from "./header";

package/templates/data_connector/src/components/inputs/messages.tsx

@@ -0,0 +1,80 @@
+import { defineMessages } from "react-intl";
+
+export const ownershipFilter = defineMessages({
+  label: {
+    defaultMessage: "Filter by Ownership",
+    description: "Label for a select control to filter designs by ownership",
+  },
+  description: {
+    defaultMessage:
+      "Filter the list of designs based on the user's ownership of the designs",
+    description: "Subtitle for a select control to filter designs by ownership",
+  },
+  any: {
+    defaultMessage: "Any (default)",
+    description: "Default option for ownership filter",
+  },
+  owned: {
+    defaultMessage: "Owned by me",
+    description: "Option for ownership filter",
+  },
+  shared: {
+    defaultMessage: "Shared with me",
+    description: "Option for ownership filter",
+  },
+});
+
+export const datasetFilter = defineMessages({
+  label: {
+    defaultMessage: "Filter by Dataset",
+    description: "Label for a select control to filter designs by dataset",
+  },
+  description: {
+    defaultMessage:
+      "Filter the list of brand templates based on the dataset definitions",
+    description: "Subtitle for a select control to filter designs by dataset",
+  },
+  any: {
+    defaultMessage: "Any (default)",
+    description: "Default option for dataset filter",
+  },
+  nonEmpty: {
+    defaultMessage: "Templates with one or more data fields defined",
+    description: "Option for dataset filter",
+  },
+  empty: {
+    defaultMessage: "Templates with no data fields defined",
+    description: "Option for dataset filter",
+  },
+});
+
+export const sortOrderField = defineMessages({
+  label: {
+    defaultMessage: "Sort by",
+    description: "Label for a select control to sort designs",
+  },
+  description: {
+    defaultMessage: "Sort the list of designs",
+    description: "Subtitle for a select control to sort designs",
+  },
+  relevance: {
+    defaultMessage: "Relevance (default)",
+    description: "Default option for sort order",
+  },
+  modifiedDesc: {
+    defaultMessage: "Last modified - descending",
+    description: "Option for sort order",
+  },
+  modifiedAsc: {
+    defaultMessage: "Last modified - ascending",
+    description: "Option for sort order",
+  },
+  titleDesc: {
+    defaultMessage: "Title - descending",
+    description: "Option for sort order",
+  },
+  titleAsc: {
+    defaultMessage: "Title - ascending",
+    description: "Option for sort order",
+  },
+});

package/templates/data_connector/src/components/inputs/select_field.tsx

@@ -0,0 +1,26 @@
+import type { SelectOption } from "@canva/app-ui-kit";
+import { FormField, Select } from "@canva/app-ui-kit";
+
+interface SelectFieldProps {
+  value: string;
+  onChange: (value: string) => void;
+  label: string;
+  options: SelectOption<string>[];
+}
+
+export const SelectField = ({
+  value,
+  onChange,
+  label,
+  options,
+}: SelectFieldProps) => {
+  return (
+    <FormField
+      label={label}
+      value={value}
+      control={(props) => (
+        <Select {...props} options={options} onChange={onChange} />
+      )}
+    />
+  );
+};