@canva/cli 0.0.1-beta.3 → 0.0.1-beta.30

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} />
+      )}
+    />
+  );
+};

package/templates/data_connector/src/context/app_context.tsx

@@ -0,0 +1,124 @@
+import { createContext, useState, useCallback } from "react";
+import type { RenderSelectionUiParams } from "@canva/intents/data";
+import type { AccessTokenResponse } from "@canva/user";
+import { auth } from "@canva/user";
+import type { APIResponseItem, DataSourceHandler } from "src/api/data_source";
+import { type DataSourceConfig } from "src/api/data_source";
+
+export interface AppContextType {
+  appError: string;
+  setAppError: (value: string) => void;
+  dataParams: RenderSelectionUiParams;
+  isAuthenticated: boolean;
+  accessToken: AccessTokenResponse | undefined;
+  setAccessToken: (token: AccessTokenResponse | undefined) => void;
+  oauth: ReturnType<typeof auth.initOauth>;
+  logout: () => Promise<void>;
+  dataSourceHandler?: DataSourceHandler<DataSourceConfig, APIResponseItem>;
+  setDataSourceHandler: (
+    value: DataSourceHandler<DataSourceConfig, APIResponseItem>,
+  ) => void;
+
+  dataSourceConfig?: DataSourceConfig;
+  setDataSourceConfig: (value: DataSourceConfig) => void;
+  loadDataSource: (title: string, source: DataSourceConfig) => Promise<void>;
+}
+
+export const AppContext = createContext<AppContextType>({
+  appError: "",
+  setAppError: () => {},
+  dataParams: {} as RenderSelectionUiParams,
+  isAuthenticated: false,
+  accessToken: undefined,
+  setAccessToken: () => {},
+  oauth: auth.initOauth(),
+  logout: async () => {},
+  dataSourceHandler: {} as DataSourceHandler<DataSourceConfig, APIResponseItem>,
+  setDataSourceHandler: () => {},
+  dataSourceConfig: {} as DataSourceConfig,
+  setDataSourceConfig: () => {},
+  loadDataSource: async () => {},
+});
+
+/**
+ * Provides application-wide state and methods using React Context.
+ * @param {object} props - The props object.
+ * @param {React.ReactNode} props.children - The children components wrapped by the provider.
+ * @returns {JSX.Element} The provider component.
+ * @description This provider component wraps the entire application to provide application-wide state and methods using React Context.
+ * It manages state related to app errors, filter parameters, and authentication.
+ * It exposes these state values and setter methods to its child components via the AppContext.
+ * For more information on React Context, refer to the official React documentation: {@link https://react.dev/learn/passing-data-deeply-with-context}.
+ */
+export const ContextProvider = ({
+  renderSelectionUiParams,
+  children,
+}: {
+  renderSelectionUiParams: RenderSelectionUiParams;
+  children: React.ReactNode;
+}): JSX.Element => {
+  const [appError, setAppError] = useState<string>("");
+  const [dataParams] = useState<RenderSelectionUiParams>(
+    renderSelectionUiParams,
+  );
+
+  // authentication
+  const [accessToken, setAccessToken] = useState<
+    AccessTokenResponse | undefined
+  >(undefined);
+  const oauth = auth.initOauth();
+  const isAuthenticated = !!accessToken;
+
+  // data handlers
+  const [dataSourceHandler, setDataSourceHandler] =
+    useState<DataSourceHandler<DataSourceConfig, APIResponseItem>>();
+  const [dataSourceConfig, setDataSourceConfig] = useState<DataSourceConfig>();
+
+  // data connection
+  const loadDataSource = useCallback(
+    async (title: string, source: DataSourceConfig) => {
+      const result = await dataParams.updateDataRef({
+        title,
+        source: JSON.stringify(source),
+      });
+      if (result.status === "remote_request_failed") {
+        setAppError(`Failed to load data source: uanble to connect to the API`);
+      } else if (result.status === "app_error") {
+        setAppError(
+          `Failed to load data source: ${result.message || result.status}`,
+        );
+      } else {
+        setAppError("");
+      }
+    },
+    [dataParams],
+  );
+
+  const logout = useCallback(async () => {
+    try {
+      setAccessToken(undefined);
+      await oauth.deauthorize();
+      setAccessToken(null);
+    } catch (error) {
+      setAppError(error instanceof Error ? error.message : "Logout failed");
+    }
+  }, [oauth]);
+
+  const value: AppContextType = {
+    appError,
+    setAppError,
+    dataParams,
+    isAuthenticated,
+    accessToken,
+    setAccessToken,
+    oauth,
+    logout,
+    dataSourceHandler,
+    setDataSourceHandler,
+    dataSourceConfig,
+    setDataSourceConfig,
+    loadDataSource,
+  };
+
+  return <AppContext.Provider value={value}>{children}</AppContext.Provider>;
+};

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

@@ -0,0 +1,2 @@
+export * from "./app_context";
+export * from "./use_app_context";

package/templates/data_connector/src/context/use_app_context.ts

@@ -0,0 +1,17 @@
+import { useContext } from "react";
+import type { AppContextType } from ".";
+import { AppContext } from ".";
+
+/**
+ * A custom React hook to access the application-wide state and methods provided by the ContextProvider using React Context.
+ * @returns {AppContextType} - An object containing application-wide state and methods.
+ * @throws {Error} - Throws an error if used outside the context of a ContextProvider.
+ * @description This hook allows components to access the application-wide state and methods provided by the ContextProvider using React Context. It retrieves the context value using the useContext hook and ensures that the context is available. If used outside the context of an ContextProvider, it throws an error instructing developers to use it within an ContextProvider.
+ */
+export const useAppContext = (): AppContextType => {
+  const context = useContext(AppContext);
+  if (!context) {
+    throw new Error("useAppContext must be used within a ContextProvider");
+  }
+  return context;
+};

package/templates/data_connector/src/entrypoint.tsx

@@ -0,0 +1,73 @@
+import { LoadingIndicator } from "@canva/app-ui-kit";
+import { useEffect } from "react";
+import { useNavigate } from "react-router-dom";
+import { useAppContext } from "./context";
+import {
+  isDataRefEmpty,
+  isLaunchedWithError,
+  isOutdatedSource,
+} from "./utils/data_params";
+import { Paths } from "./routes";
+import { DATA_SOURCES } from "./api/data_sources";
+import type {
+  APIResponseItem,
+  DataSourceConfig,
+  DataSourceHandler,
+} from "./api";
+
+const parseDataSource = (source: string) => {
+  try {
+    return source ? JSON.parse(source) : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+export const Entrypoint = () => {
+  const navigate = useNavigate();
+  const context = useAppContext();
+  const { dataParams, setAppError, setDataSourceHandler } = context;
+
+  useEffect(() => {
+    // if the app was loaded with a populated data ref, we should reload the previous state.
+    // otherwise, if this is a first launch or there is an error, we should navigate to the first screen for a user - selecting a data source
+    let navigateTo: Paths | undefined;
+
+    if (isDataRefEmpty(dataParams)) {
+      // probably a first time launch - the user will need to select a data source
+      navigateTo = Paths.DATA_SOURCE_SELECTION;
+    } else if (
+      isOutdatedSource(dataParams) ||
+      isLaunchedWithError(dataParams)
+    ) {
+      // the configured source does not match the expected data source types
+      // so prompt the user to reconfigure the data source
+      setAppError("The data source configuration needs to be updated.");
+      navigateTo = Paths.DATA_SOURCE_SELECTION;
+    } else {
+      // there is a data ref, so we should parse it and navigate to the appropriate page
+      const dataRef = dataParams.invocationContext.dataSourceRef;
+      const parsedSource = parseDataSource(dataRef?.source ?? "");
+
+      if (parsedSource) {
+        const dataHandler = DATA_SOURCES.find((handler) =>
+          handler.matchSource(parsedSource),
+        );
+        if (dataHandler) {
+          setDataSourceHandler(
+            dataHandler as unknown as DataSourceHandler<
+              DataSourceConfig,
+              APIResponseItem
+            >,
+          );
+          dataHandler.sourceConfig = parsedSource;
+          navigateTo = Paths.DATA_SOURCE_CONFIG;
+        }
+      }
+    }
+
+    navigate(navigateTo || Paths.DATA_SOURCE_SELECTION);
+  }, [dataParams]);
+
+  return <LoadingIndicator />;
+};

package/templates/data_connector/src/home.tsx

@@ -0,0 +1,21 @@
+import { Outlet } from "react-router-dom";
+import { Box, Rows } from "@canva/app-ui-kit";
+import { AppError } from "./components";
+import * as styles from "styles/components.css";
+
+export const Home = () => (
+  <div className={styles.scrollContainer}>
+    <Box
+      justifyContent="center"
+      width="full"
+      alignItems="start"
+      display="flex"
+      height="full"
+    >
+      <Rows spacing="3u">
+        <AppError />
+        <Outlet />
+      </Rows>
+    </Box>
+  </div>
+);

package/templates/data_connector/src/index.tsx

@@ -0,0 +1,69 @@
+import type {
+  RenderSelectionUiParams,
+  FetchDataTableParams,
+  FetchDataTableResult,
+} from "@canva/intents/data";
+import { prepareDataConnector } from "@canva/intents/data";
+import { createRoot } from "react-dom/client";
+import { App } from "./app";
+import { auth } from "@canva/user";
+import { buildDataTableResult, scope } from "./api";
+
+import "@canva/app-ui-kit/styles.css";
+import { Alert, AppUiProvider } from "@canva/app-ui-kit";
+
+const root = createRoot(document.getElementById("root") as Element);
+prepareDataConnector({
+  /**
+   * Fetches structured data from an external source.
+   *
+   * This action is called in two scenarios:
+   *
+   * - During data selection to preview data before import (when {@link RenderSelectionUiParams.updateDataRef} is called).
+   * - When refreshing previously imported data (when the user requests an update).
+   *
+   * @param params - Parameters for the data fetching operation.
+   * @returns A promise resolving to either a successful result with data or an error.
+   */
+  fetchDataTable: async (
+    params: FetchDataTableParams,
+  ): Promise<FetchDataTableResult> => {
+    const oauth = auth.initOauth();
+    const token = await oauth.getAccessToken({ scope });
+    return buildDataTableResult(params, token?.token);
+  },
+
+  /**
+   * Renders a UI component for selecting and configuring data from external sources.
+   * This UI should allow users to browse data sources, apply filters, and select data.
+   * When selection is complete, the implementation must call the `updateDataRef`
+   * callback provided in the params to preview and confirm the data selection.
+   *
+   * @param params - parameters that provide context and configuration for the data selection UI.
+   * Contains invocation context, size limits, and the updateDataRef callback
+   */
+  renderSelectionUi: async (params: RenderSelectionUiParams) => {
+    function render() {
+      root.render(<App dataParams={params} />);
+    }
+
+    render();
+
+    if (module.hot) {
+      module.hot.accept("./app", render);
+      module.hot.accept("./api", render);
+    }
+  },
+});
+
+// TODO: Fallback message if you have not turned on the data connector intent.
+// You can remove this once your app is correctly configured.
+root.render(
+  <AppUiProvider>
+    {/* eslint-disable-next-line formatjs/no-literal-string-in-jsx */}
+    <Alert tone="critical">
+      If you're seeing this, you need to turn on the data connector intent in
+      the developer portal for this app.
+    </Alert>
+  </AppUiProvider>,
+);

package/templates/data_connector/src/pages/data_source_config.tsx

@@ -0,0 +1,9 @@
+import { useAppContext } from "src/context";
+
+export const DataSourceConfig = () => {
+  const { dataSourceHandler } = useAppContext();
+  if (!dataSourceHandler) {
+    return undefined; // should be impossible
+  }
+  return dataSourceHandler.configPage(dataSourceHandler.sourceConfig);
+};

package/templates/data_connector/src/pages/error.tsx

@@ -0,0 +1,37 @@
+import { useNavigate } from "react-router-dom";
+import { Button, Rows, Text } from "@canva/app-ui-kit";
+import { Paths } from "src/routes";
+import * as styles from "styles/components.css";
+import { FormattedMessage, useIntl } from "react-intl";
+
+/**
+ * Bare bones Error Page, please add relevant information and behavior that your app requires.
+ */
+export const ErrorPage = () => {
+  const navigate = useNavigate();
+  const intl = useIntl();
+
+  const onClick = () => {
+    navigate(Paths.ENTRYPOINT);
+  };
+
+  return (
+    <div className={styles.scrollContainer}>
+      <Rows spacing="2u">
+        <Text>
+          <FormattedMessage
+            defaultMessage="Something went wrong."
+            description="A message to indicate that something went wrong, but no more information is available"
+          />
+        </Text>
+        <Button variant="primary" onClick={onClick} stretch={true}>
+          {intl.formatMessage({
+            defaultMessage: "Start over",
+            description:
+              "A button label to clear the error and the prompt and start again",
+          })}
+        </Button>
+      </Rows>
+    </div>
+  );
+};

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

@@ -0,0 +1,4 @@
+export * from "./error";
+export * from "./login";
+export * from "./select_source";
+export * from "./data_source_config";