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

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";

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

@@ -0,0 +1,145 @@
+import {
+  Button,
+  LoadingIndicator,
+  Rows,
+  Title,
+  Text,
+  Box,
+} from "@canva/app-ui-kit";
+import { useState, useEffect, useCallback } from "react";
+import * as styles from "styles/components.css";
+import { useAppContext } from "../context";
+import { useNavigate } from "react-router-dom";
+import { Paths } from "../routes";
+import { Header } from "src/components";
+import { useIntl, FormattedMessage, defineMessages } from "react-intl";
+import { scope } from "src/api";
+
+export const Login = () => {
+  const intl = useIntl();
+  const navigate = useNavigate();
+  const { oauth, setAccessToken, isAuthenticated } = useAppContext();
+
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    // Redirect if already authenticated
+    if (isAuthenticated) {
+      navigate(Paths.ENTRYPOINT);
+      return;
+    }
+
+    // check if the user is already authenticated
+    retrieveAndSetToken();
+  }, [isAuthenticated]);
+
+  const authorize = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      await oauth.requestAuthorization({ scope });
+      await retrieveAndSetToken();
+    } catch (error) {
+      setError(error instanceof Error ? error.message : "Unknown error");
+      setLoading(false);
+    }
+  }, [oauth]);
+
+  // you MUST call getAccessToken every time you need a token, as the token may expire.
+  // Canva will handle caching and refreshing the token for you.
+  const retrieveAndSetToken = useCallback(
+    async (forceRefresh = false) => {
+      try {
+        const token = await oauth.getAccessToken({ forceRefresh, scope });
+        setAccessToken(token);
+        setLoading(false);
+      } catch (error) {
+        setError(error instanceof Error ? error.message : "Unknown error");
+        setLoading(false);
+      }
+    },
+    [oauth, setAccessToken],
+  );
+
+  return (
+    <div className={styles.scrollContainer}>
+      <Box
+        justifyContent="center"
+        width="full"
+        alignItems="center"
+        display="flex"
+        height="full"
+      >
+        {error && (
+          <Rows spacing="2u">
+            <Title>
+              <FormattedMessage {...loginMessages.authorizationError} />
+            </Title>
+            <Text>{error}</Text>
+            <Button variant="primary" onClick={authorize}>
+              {intl.formatMessage(loginMessages.tryAgain)}
+            </Button>
+          </Rows>
+        )}
+        {loading && <LoadingIndicator />}
+        {!loading && !error && (
+          <Rows spacing="2u">
+            <Header
+              title={intl.formatMessage(loginMessages.signInRequired)}
+              showBack={false}
+            />
+            <Text>
+              <FormattedMessage {...loginMessages.dataConnectorsOAuth} />
+            </Text>
+            <Text>
+              <FormattedMessage {...loginMessages.exampleDemonstration} />
+            </Text>
+            <Text>
+              <FormattedMessage {...loginMessages.setupInstructions} />
+            </Text>
+            <Button variant="primary" onClick={authorize}>
+              {intl.formatMessage(loginMessages.signIntoCanva)}
+            </Button>
+          </Rows>
+        )}
+      </Box>
+    </div>
+  );
+};
+
+const loginMessages = defineMessages({
+  authorizationError: {
+    defaultMessage: "Authorization error",
+    description:
+      "Title displayed when there is an error during OAuth authorization",
+  },
+  tryAgain: {
+    defaultMessage: "Try again",
+    description: "Button text to retry authorization after an error occurs",
+  },
+  signInRequired: {
+    defaultMessage: "Sign in required",
+    description:
+      "Header title for the login page indicating authentication is needed",
+  },
+  dataConnectorsOAuth: {
+    defaultMessage:
+      "Data connectors can use OAuth to authenticate with other platforms.",
+    description: "Body text shown when the user is prompted to sign in",
+  },
+  exampleDemonstration: {
+    defaultMessage:
+      "This example demonstrates how to do this with the Canva Connect API.",
+    description: "Body text shown when the user is prompted to sign in",
+  },
+  setupInstructions: {
+    defaultMessage:
+      "For set up instructions please see the README.md in the root folder.",
+    description: "Body text shown when the user is prompted to sign in",
+  },
+  signIntoCanva: {
+    defaultMessage: "Sign into Canva",
+    description: "Button text for initiating Canva authentication",
+  },
+});

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

@@ -0,0 +1,24 @@
+import { Box, Rows } from "@canva/app-ui-kit";
+import { useIntl } from "react-intl";
+import { DATA_SOURCES } from "src/api/data_sources";
+import { Footer, Header } from "src/components";
+
+export const SelectSource = () => {
+  const intl = useIntl();
+
+  return (
+    <Box paddingEnd="2u" paddingTop="2u">
+      <Rows spacing="1u" align="start">
+        <Header
+          title={intl.formatMessage({
+            defaultMessage: "What would you like to import? ",
+            description: "The header text for the data source selection view",
+          })}
+          showBack={false}
+        />
+        {DATA_SOURCES.map((handler) => handler.selectionPage())}
+        <Footer />
+      </Rows>
+    </Box>
+  );
+};

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

@@ -0,0 +1,2 @@
+export * from "./routes";
+export * from "./protected_route";

package/templates/data_connector/src/routes/protected_route.tsx

@@ -0,0 +1,25 @@
+import { useEffect } from "react";
+import { useNavigate } from "react-router-dom";
+import { useAppContext } from "../context";
+import { Paths } from "../routes";
+
+interface ProtectedRouteProps {
+  children: React.ReactNode;
+}
+
+/**
+ * A component that protects routes from unauthorized access.
+ * If the user is not authenticated, they will be redirected to the login page.
+ */
+export const ProtectedRoute = ({ children }: ProtectedRouteProps) => {
+  const { isAuthenticated } = useAppContext();
+  const navigate = useNavigate();
+
+  useEffect(() => {
+    if (!isAuthenticated) {
+      navigate(Paths.LOGIN);
+    }
+  }, [isAuthenticated, navigate]);
+
+  return <>{children}</>;
+};

package/templates/data_connector/src/routes/routes.tsx

@@ -0,0 +1,46 @@
+import { Entrypoint } from "src/entrypoint";
+import { Home } from "src/home";
+import { ErrorPage, Login, DataSourceConfig, SelectSource } from "src/pages";
+import { ProtectedRoute } from "./protected_route";
+
+export enum Paths {
+  ENTRYPOINT = "/",
+  LOGIN = "/login",
+  DATA_SOURCE_SELECTION = "/data-source-selection",
+  DATA_SOURCE_CONFIG = "/data-source-config",
+  ERRORS = "/errors/:retry",
+}
+
+export const routes = [
+  {
+    path: Paths.ENTRYPOINT,
+    element: <Home />,
+    errorElement: <ErrorPage />,
+    children: [
+      {
+        index: true,
+        element: <Entrypoint />,
+      },
+      {
+        path: Paths.LOGIN,
+        element: <Login />,
+      },
+      {
+        path: Paths.DATA_SOURCE_SELECTION,
+        element: (
+          <ProtectedRoute>
+            <SelectSource />
+          </ProtectedRoute>
+        ),
+      },
+      {
+        path: Paths.DATA_SOURCE_CONFIG,
+        element: (
+          <ProtectedRoute>
+            <DataSourceConfig />
+          </ProtectedRoute>
+        ),
+      },
+    ],
+  },
+];

package/templates/data_connector/src/utils/data_params.ts

@@ -0,0 +1,17 @@
+import type { RenderSelectionUiParams } from "@canva/intents/data";
+
+export const isLaunchedWithError = (dataParams: RenderSelectionUiParams) => {
+  return dataParams.invocationContext.reason === "app_error";
+};
+
+export const isOutdatedSource = (dataParams: RenderSelectionUiParams) => {
+  return dataParams.invocationContext.reason === "outdated_source_ref";
+};
+
+export const isDataRefEmpty = (dataParams: RenderSelectionUiParams) => {
+  return (
+    !dataParams?.invocationContext ||
+    (!isLaunchedWithError(dataParams) &&
+      !dataParams.invocationContext.dataSourceRef?.source)
+  );
+};