@canva/cli 0.0.1-beta.8 → 1.0.0

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

@@ -0,0 +1,99 @@
+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",
+  },
+});
+
+export const filterMenu = defineMessages({
+  search: {
+    defaultMessage: "Search",
+    description: "Label for a search input field",
+  },
+  clear: {
+    defaultMessage: "Clear all",
+    description: "Label for a button to clear all filters",
+  },
+  apply: {
+    defaultMessage: "Apply",
+    description: "Label for a button to apply filters",
+  },
+  count: {
+    defaultMessage: "Filter count",
+    description: "Label for the number of active filters",
+  },
+});

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

@@ -0,0 +1,108 @@
+import {
+  Badge,
+  Box,
+  Button,
+  Column,
+  Columns,
+  Flyout,
+  Rows,
+  SearchInputMenu,
+  SlidersIcon,
+} from "@canva/app-ui-kit";
+import { useState } from "react";
+import { useIntl } from "react-intl";
+import { filterMenu } from "./messages";
+
+interface SearchFilterProps {
+  value: string;
+  onChange: (value: string) => void;
+  filterCount: number;
+  resetFilters: () => void;
+  children?: React.ReactNode;
+}
+
+export const SearchFilter = ({
+  value,
+  onChange,
+  filterCount,
+  resetFilters,
+  children,
+}: SearchFilterProps) => {
+  const intl = useIntl();
+  const [triggerRef, setTriggerRef] = useState<HTMLDivElement | null>(null);
+  const [isFilterMenuOpen, setIsFilterMenuOpen] = useState(false);
+
+  const onFilterClick = () => {
+    setIsFilterMenuOpen(!isFilterMenuOpen);
+  };
+
+  const filterButton = (
+    <Button
+      size="small"
+      variant="tertiary"
+      icon={SlidersIcon}
+      onClick={onFilterClick}
+    />
+  );
+  return (
+    <>
+      <Box paddingStart="0.5u">
+        <SearchInputMenu
+          value={value}
+          placeholder={intl.formatMessage(filterMenu.search)}
+          onChange={(value) => onChange(value)}
+          onClear={() => onChange("")}
+          ref={setTriggerRef}
+          end={
+            filterCount === 0 ? (
+              filterButton
+            ) : (
+              <Badge
+                tone="assist"
+                wrapInset="0"
+                shape="circle"
+                text={filterCount.toString()}
+                ariaLabel={intl.formatMessage(filterMenu.count)}
+              >
+                {filterButton}
+              </Badge>
+            )
+          }
+        />
+      </Box>
+      <Flyout
+        open={isFilterMenuOpen}
+        onRequestClose={() => setIsFilterMenuOpen(false)}
+        width="trigger"
+        trigger={triggerRef}
+        placement="bottom-center"
+        footer={
+          <Box padding="2u" background="surface">
+            <Columns spacing="1u">
+              <Column>
+                <Button variant="secondary" onClick={resetFilters} stretch>
+                  {intl.formatMessage(filterMenu.clear)}
+                </Button>
+              </Column>
+              <Column>
+                <Button
+                  variant="primary"
+                  onClick={() => {
+                    setIsFilterMenuOpen(false);
+                  }}
+                  stretch
+                >
+                  {intl.formatMessage(filterMenu.apply)}
+                </Button>
+              </Column>
+            </Columns>
+          </Box>
+        }
+      >
+        <Box padding="2u">
+          <Rows spacing="2u">{children}</Rows>
+        </Box>
+      </Flyout>
+    </>
+  );
+};

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 type { RenderSelectionUiRequest } from "@canva/intents/data";
+import type { AccessTokenResponse } from "@canva/user";
+import { auth } from "@canva/user";
+import { createContext, useCallback, useState } from "react";
+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;
+  request: RenderSelectionUiRequest;
+  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: () => {},
+  request: {} as RenderSelectionUiRequest,
+  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 = ({
+  renderSelectionUiRequest,
+  children,
+}: {
+  renderSelectionUiRequest: RenderSelectionUiRequest;
+  children: React.ReactNode;
+}): JSX.Element => {
+  const [appError, setAppError] = useState<string>("");
+  const [request] = useState<RenderSelectionUiRequest>(
+    renderSelectionUiRequest,
+  );
+
+  // 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 request.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("");
+      }
+    },
+    [request],
+  );
+
+  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,
+    request,
+    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,70 @@
+import { LoadingIndicator } from "@canva/app-ui-kit";
+import { useEffect } from "react";
+import { useNavigate } from "react-router-dom";
+import type {
+  APIResponseItem,
+  DataSourceConfig,
+  DataSourceHandler,
+} from "./api";
+import { DATA_SOURCES } from "./api/data_sources";
+import { useAppContext } from "./context";
+import { Paths } from "./routes";
+import {
+  isDataRefEmpty,
+  isLaunchedWithError,
+  isOutdatedSource,
+} from "./utils/data_params";
+
+const parseDataSource = (source: string) => {
+  try {
+    return source ? JSON.parse(source) : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+export const Entrypoint = () => {
+  const navigate = useNavigate();
+  const context = useAppContext();
+  const { request, 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(request)) {
+      // probably a first time launch - the user will need to select a data source
+      navigateTo = Paths.DATA_SOURCE_SELECTION;
+    } else if (isOutdatedSource(request) || isLaunchedWithError(request)) {
+      // 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 = request.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);
+  }, [request]);
+
+  return <LoadingIndicator />;
+};

package/templates/data_connector/src/home.tsx

@@ -0,0 +1,21 @@
+import { Box, Rows } from "@canva/app-ui-kit";
+import { Outlet } from "react-router-dom";
+import * as styles from "styles/components.css";
+import { AppError } from "./components";
+
+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,68 @@
+import { Alert, AppUiProvider } from "@canva/app-ui-kit";
+import type {
+  GetDataTableRequest,
+  GetDataTableResponse,
+  RenderSelectionUiRequest,
+} from "@canva/intents/data";
+import { prepareDataConnector } from "@canva/intents/data";
+import { auth } from "@canva/user";
+import { createRoot } from "react-dom/client";
+import { buildDataTableResult, scope } from "./api";
+import { App } from "./app";
+import "@canva/app-ui-kit/styles.css";
+
+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 RenderSelectionUiRequest.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.
+   */
+  getDataTable: async (
+    params: GetDataTableRequest,
+  ): Promise<GetDataTableResponse> => {
+    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 request - parameters that provide context and configuration for the data selection UI.
+   * Contains invocation context, size limits, and the updateDataRef callback
+   */
+  renderSelectionUi: async (request: RenderSelectionUiRequest) => {
+    function render() {
+      root.render(<App request={request} />);
+    }
+
+    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 { Button, Rows, Text } from "@canva/app-ui-kit";
+import { FormattedMessage, useIntl } from "react-intl";
+import { useNavigate } from "react-router-dom";
+import { Paths } from "src/routes";
+import * as styles from "styles/components.css";
+
+/**
+ * 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";