@pipedream/connect-react 1.0.0-preview.1

package/LICENSE

@@ -0,0 +1,41 @@
+Pipedream Source Available License Version 1.0
+ 
+This Pipedream Source Available License Agreement Version 1.0 (this “Agreement”) sets forth the terms on which Pipedream, Inc., a Delaware corporation (“Pipedream”) makes available certain software (the “Software”). By installing, downloading, accessing, using or distributing the Software, you agree to the terms of this Agreement. If you do not agree to such terms, you must not use the Software. If you are receiving the Software on behalf of a legal entity, you represent and warrant that you have the actual authority to agree to the terms and conditions of this Agreement on behalf of such entity. “Licensee” means you, an individual, or the entity on whose behalf you are receiving the Software.
+ 
+LICENSE GRANT AND CONDITIONS.
+ 
+1.1  License. Subject to the terms and conditions of this Agreement, Pipedream hereby grants to Licensee a non-exclusive, royalty-free, worldwide, non-transferable, non-sublicenseable license during the term of this Agreement to use, prepare modifications and derivative works, distribute (including without limitation in source code or object code form) and reproduce copies of the Software (the “License”). Licensee is not granted the right to, and Licensee shall not, exercise the License for an Excluded Purpose. For purposes of this Agreement, “Excluded Purpose” means any commercial use of the software including, but not limited to, making available any software-as-a-service, platform-as-a-service, infrastructure-as-a-service or other online service that competes with the Software or any other Pipedream products or services.
+ 
+1.2  Conditions. In consideration of the License, Licensee’s distribution of the Software is subject to the following conditions:
+ 
+a. Licensee must cause any Software modified by Licensee to carry prominent notices stating that Licensee modified the Software.
+ 
+b. On each Software copy, Licensee shall reproduce and not remove or alter all Pipedream or third party copyright or other proprietary notices contained in the Software, and Licensee must provide this with each copy: “This software is made available by Pipedream, Inc., under the terms of the Pipedream Source Available License, Version 1.0 located at https://github.com/PipedreamHQ/pipedream/blob/master/LICENSE. By installing, downloading, accessing, using or distributing the Software, you agree to the terms of such License Agreement.”
+ 
+1.3  Modifications. Licensee may add its own copyright notices to modifications made by Licensee and may provide additional or different license terms and conditions for use, reproduction, or distribution of Licensee’s modifications. While redistributing the Software or modifications thereof, Licensee may choose to offer, for a fee or free of charge, support, warranty, indemnity, or other obligations. Licensee, and not Pipedream, will be responsible for any such obligations.
+ 
+1.4  No Sublicensing. The License does not include the right to sublicense the Software; provided, however, that any recipient to which Licensee provides the Software may exercise the License so long as such recipient agrees to the terms and conditions of this Agreement.
+ 
+TERM AND TERMINATION.
+ 
+This Agreement will continue unless and until earlier terminated as set forth herein. If Licensee breaches any of its conditions or obligations under this Agreement, this Agreement will terminate automatically and the License will terminate automatically and permanently.
+ 
+INTELLECTUAL PROPERTY.
+ 
+As between the parties, Pipedream retains all right, title, and interest in the Software, and all intellectual property rights therein. Pipedream hereby reserves all rights not expressly granted to Licensee in this Agreement. Pipedream reserves all rights in its trademarks and service marks, and no licenses thereto are granted by this Agreement.
+ 
+DISCLAIMER.
+ 
+PIPEDREAM HEREBY DISCLAIMS ANY AND ALL WARRANTIES AND CONDITIONS, EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE, AND SPECIFICALLY DISCLAIMS ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, WITH RESPECT TO THE SOFTWARE.
+ 
+LIMITATION OF LIABILITY.
+ 
+PIPEDREAM WILL NOT BE LIABLE FOR ANY DAMAGES OF ANY KIND, INCLUDING BUT NOT LIMITED TO, LOST PROFITS OR ANY CONSEQUENTIAL, SPECIAL, INCIDENTAL, INDIRECT, OR DIRECT DAMAGES, HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, ARISING OUT OF THIS AGREEMENT. THE FOREGOING SHALL APPLY TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW.
+ 
+GENERAL.
+ 
+6.1  Governing Law. This Agreement will be governed by and interpreted in accordance with the laws of the state of California, without reference to its conflict of laws principles. If Licensee is located outside of the United States, any dispute, controversy or claim arising out of or relating to this Agreement will be referred to and finally determined by arbitration in accordance with the JAMS International Arbitration Rules. The tribunal will consist of one arbitrator. Judgment upon the award rendered by the arbitrator may be entered in any court having jurisdiction thereof. All disputes including arbitrations shall take place in Santa Clara County, California. The language to be used in any such proceedings shall be English.
+ 
+6.2.  Assignment. Licensee is not authorized to assign its rights under this Agreement to any third party. Pipedream may freely assign its rights under this Agreement to any third party.
+ 
+6.3.  Other. This Agreement is the entire agreement between the parties regarding the subject matter hereof. No amendment or modification of this Agreement will be valid or binding upon the parties unless made in writing and signed by the duly authorized representatives of both parties. In the event that any provision, including without limitation any condition, of this Agreement is held to be unenforceable, this Agreement and all licenses and rights granted hereunder will immediately terminate. Waiver by Pipedream of a breach of any provision of this Agreement or the failure by Pipedream to exercise any right hereunder will not be construed as a waiver of any subsequent breach of that right or as a waiver of any other right.

package/README.md

@@ -0,0 +1,430 @@
+# Pipedream Connect-React
+
+> [!IMPORTANT]
+> This package is in early preview and is undergoing rapid development, polish, and expanding customization capabilities.
+>
+> Please join [our community](https://pipedream.com/support) or reach out to `connect@pipedream.com` with feedback.
+
+## Installation and usage
+
+```sh
+% npm install --save @pipedream/connect-react
+```
+
+Then use the `ComponentFormContainer` component in your app (see below for props
+and customization).
+
+> [!NOTE]
+> To run the example below, set the following environment variables in `.env.local`.
+>
+> `PIPEDREAM_ALLOWED_ORIGINS`
+>
+> Make sure this matches the origin of your app, e.g.
+>
+> ```sh
+> # One domain — note the array
+> PIPEDREAM_ALLOWED_ORIGINS=["https://example.com"]
+>
+> # Multiple domains
+> PIPEDREAM_ALLOWED_ORIGINS=["https://example.com", "http://localhost:3000"]
+> ```
+>
+> `PIPEDREAM_CLIENT_ID`
+>
+> Create a [Pipedream API OAuth client](https://pipedream.com/docs/rest-api/auth#creating-an-oauth-client) and enter its client ID here.
+>
+> `PIPEDREAM_CLIENT_SECRET`
+>
+> Your OAuth client secret. **This is a secret, and should not be exposed to your frontend**.
+>
+> `PIPEDREAM_PROJECT_ID`
+>
+> [Create a Pipedream project](https://pipedream.com/projects) and [copy its ID](https://pipedream.com/docs/projects#finding-your-projects-id).
+
+```typescript
+/* actions.ts */
+"use server";
+import { createBackendClient } from "@pipedream/sdk/server";
+
+const {
+  NODE_ENV,
+  PIPEDREAM_ALLOWED_ORIGINS,
+  PIPEDREAM_CLIENT_ID,
+  PIPEDREAM_CLIENT_SECRET,
+  PIPEDREAM_PROJECT_ID,
+} = process.env;
+
+const allowedOrigins = JSON.parse(PIPEDREAM_ALLOWED_ORIGINS || "[]");
+
+const client = createBackendClient({
+  environment: NODE_ENV,
+  projectId: PIPEDREAM_PROJECT_ID,
+  credentials: {
+    clientId: PIPEDREAM_CLIENT_ID,
+    clientSecret: PIPEDREAM_CLIENT_SECRET,
+  },
+});
+
+export async function fetchToken(opts: { externalUserId: string }) {
+  return await client.createConnectToken({
+    external_user_id: opts.externalUserId,
+    allowed_origins: PIPEDREAM_ALLOWED_ORIGINS,
+  });
+}
+
+/* page.tsx */
+"use client";
+import { useState } from "react";
+import { createFrontendClient } from "@pipedream/sdk/browser";
+import {
+  ComponentFormContainer,
+  FrontendClientProvider,
+} from "@pipedream/connect-react";
+import { fetchToken } from "./actions";
+
+export default function Page() {
+  // https://pipedream.com/docs/connect/api#external-users
+  const userId = "my-authed-user-id";
+  const client = createFrontendClient({
+    environment: "development",
+    externalUserId: userId,
+    tokenCallback: fetchToken,
+  });
+  const [configuredProps, setConfiguredProps] = useState({
+    text: "hello slack!",
+  });
+  return (
+    <>
+      <div>My application</div>
+      <FrontendClientProvider client={client}>
+        <ComponentFormContainer
+          userId={userId}
+          componentKey="slack-send-message"
+          configuredProps={configuredProps}
+          onUpdateConfiguredProps={setConfiguredProps}
+        />
+      </FrontendClientProvider>
+    </>
+  );
+}
+```
+
+## Components and Props
+
+### `FrontendClientProvider`
+
+Necessary wrapper to provide the frontend client to other components.
+
+```typescript
+type Props = {
+  client: typeof import("@pipedream/sdk/browser").createFrontendClient;
+};
+```
+
+### `ComponentFormContainer`
+
+Loader component for `ComponentForm`.
+
+```typescript
+type ComponentFormContainerProps = {
+  /** action (or trigger) to look up in the [Pipedream Registry](https://github.com/PipedreamHQ/pipedream/tree/master/components) */
+  componentKey: string;
+} & Omit<ComponentFormProps, "component">; // see below
+```
+
+### `ComponentForm`
+
+```typescript
+type ComponentFormProps = {
+  component: typeof import("@pipedream/sdk").V1Component;
+  /** External user configuring the form */
+  userId: string;
+  /** Form configured values */
+  configuredProps?: Record<string, any>;
+  /** Filtering configurable props */
+  propNames?: string[];
+  /** Shows submit button + callback when clicked */
+  onSubmit: (ctx: FormContext) => Awaitable<void>;
+  /** To control and store configured values on form updates, can be used to call actionRun or triggerDeploy */
+  onUpdateConfiguredProps: (v: Record<string, any>) => void;
+  /** Hide optional props section */
+  hideOptionalProps: boolean;
+};
+```
+
+## Customization
+
+Style individual components using the `CustomizeProvider` and a `CustomizationConfig`.
+
+```tsx
+<FrontendClientProvider client={client}>
+  <CustomizeProvider {...customizationConfig}>
+    <ComponentFormContainer
+      key="slack-send-message"
+      configuredProps={configuredProps}
+      onUpdateConfiguredProps={setConfiguredProps}
+    />
+  </CustomizeProvider>
+</FrontendClientProvider>
+```
+
+```typescript
+type CustomizationConfig = {
+  classNames?: CustomClassNamesConfig;
+  classNamePrefix?: string;
+  components?: CustomComponentsConfig;
+  styles?: CustomStylesConfig;
+  theme?: CustomThemeConfig;
+  unstyled?: boolean;
+};
+```
+
+### The `classNames` prop
+
+Not to be confused with the `className` prop, `classNames` takes an object with
+keys to represent the inner components of a `ComponentForm`. Each inner
+component takes a callback function with the following signature:
+
+```tsx
+<CustomizeProvider
+  classNames={{
+    controlInput: ({ prop }) =>
+      prop.type === "number" ? "border-red-600" : "border-blue-600",
+  }}
+/>
+```
+
+#### Note on CSS specificity
+
+If you're using the `classNames` API and you're trying to override some base
+styles with the same level of specificity, you must ensure that your provided
+styles are declared later than the styles from `@pipedream/connect-react`
+(e.g. the link or style tag in the head of your HTML document) in order for them
+to take precedence.
+
+### The `classNamePrefix` prop
+
+If you provide the `classNamePrefix` prop, all inner elements will be given a
+`className` with the provided prefix.
+
+### The `components` prop
+
+You can rewrite individual inner components with the `components` prop. If you
+want to respect other customizations, such as `styles`, `classNames` or `theme`,
+use the `useCustomize` hook to integrate your base styles with the customization
+framework.
+
+In this example, we're replacing the default `Label` inner component with a version
+that adds a checkmark to highlight required props.
+
+```tsx
+import type { CSSProperties } from "react";
+import type { ConfigurableProp, LabelProps } from "@pipedream/connect-react";
+import { useCustomize } from "@pipedream/connect-react";
+
+export function CustomLabel<T extends ConfigurableProp>(props: LabelProps<T>) {
+  const { text, field } = props;
+  const { id } = field;
+
+  const { getProps, theme } = useCustomize();
+
+  const baseStyles: CSSProperties = {
+    color: theme.colors.neutral90,
+    fontWeight: 450,
+    gridArea: "label",
+    textTransform: "capitalize",
+    lineHeight: "1.5",
+  };
+
+  const required =
+    !field.prop.optional && !["alert", "app"].includes(field.prop.type) ? (
+      field.prop.type == "boolean" ? (
+        typeof field.value != "undefined"
+      ) : !!field.value ? (
+        <span
+          style={{ color: "#12b825", fontSize: "small", marginLeft: "0.5rem" }}
+        >
+          {" "}
+          ✓
+        </span>
+      ) : (
+        <span
+          style={{ color: "#d0d0d0", fontSize: "small", marginLeft: "0.5rem" }}
+        >
+          {" "}
+          ✓
+        </span>
+      )
+    ) : (
+      ""
+    );
+  return (
+    <label htmlFor={id} {...getProps("label", baseStyles, props)}>
+      {text}
+      {required}
+    </label>
+  );
+}
+```
+
+Then we apply the custom component using `CustomizeProvider`.
+
+```tsx
+import { CustomLabel } from "./CustomLabel";
+
+<CustomizeProvider
+  components={{
+    Label: CustomLabel,
+  }}
+/>;
+```
+
+### The `styles` prop
+
+The recommended way to provide custom styles is to use the `styles` prop. Each inner
+component takes either a CSSProperties object or a callback function with the following
+signature:
+
+```tsx
+<CustomizeProvider
+  styles={{
+    label: { fontSize: "80%" },
+    controlInput: (base, { theme }) => ({
+      ...base,
+      borderTop: 0,
+      borderLeft: 0,
+      borderRight: 0,
+      border: "solid",
+      borderColor: theme.colors.primary,
+      backgroundColor: theme.colors.neutral0,
+    }),
+  }}
+/>
+```
+
+Note that when using the callback function, the `styles` prop has access to `theme`
+customizations as well.
+
+### The `theme` prop
+
+The default styles are derived from a theme object, which can be customized using
+the `theme` prop.
+
+```tsx
+<CustomizeProvider
+  theme={{
+    borderRadius: 0,
+    colors: {
+      primary: "hsl(200, 100%, 60%)",
+      primary75: "hsl(200, 100%, 55%)",
+      primary50: "hsl(200, 100%, 40%)",
+      primary25: "hsl(200, 100%, 35%)",
+
+      danger: "#DE350B",
+      dangerLight: "#FFBDAD",
+
+      neutral0: "hsl(200, 50%, 97%)",
+      neutral5: "hsl(200, 50%, 95%)",
+      neutral10: "hsl(200, 50%, 90%)",
+      neutral20: "hsl(200, 50%, 80%)",
+      neutral30: "hsl(200, 50%, 70%)",
+      neutral40: "hsl(200, 50%, 60%)",
+      neutral50: "hsl(200, 50%, 50%)",
+      neutral60: "hsl(200, 50%, 40%)",
+      neutral70: "hsl(200, 50%, 30%)",
+      neutral80: "hsl(200, 50%, 20%)",
+      neutral90: "hsl(200, 50%, 10%)",
+    },
+    spacing: {
+      baseUnit: 4,
+      controlHeight: 10,
+      menuGutter: 6,
+    },
+  }}
+/>
+```
+
+### The `unstyled` prop
+
+While it is always possible to override default styling, you may prefer to start
+from completely unstyled components. Add the `unstyled` prop to remove all styling.
+
+```tsx
+<CustomizeProvider unstyled={true} />
+```
+
+## Inner components
+
+The following list shows all of the customizable inner components used in a
+`ComponentForm`.
+
+```typescript
+export type CustomizableProps = {
+  componentForm: ComponentProps<typeof ComponentForm>;
+  connectButton: ComponentProps<typeof ControlApp> &
+    FormFieldContext<ConfigurableProp>;
+  controlAny: ComponentProps<typeof ControlAny> &
+    FormFieldContext<ConfigurableProp>;
+  controlApp: ComponentProps<typeof ControlApp> &
+    FormFieldContext<ConfigurableProp>;
+  controlBoolean: ComponentProps<typeof ControlBoolean> &
+    FormFieldContext<ConfigurableProp>;
+  controlInput: ComponentProps<typeof ControlInput> &
+    FormFieldContext<ConfigurableProp>;
+  controlSubmit: ComponentProps<typeof ControlSubmit>;
+  description: ComponentProps<typeof Description>;
+  error: ComponentProps<typeof Errors>;
+  errors: ComponentProps<typeof Errors>;
+  field: ComponentProps<typeof Field>;
+  heading: ComponentProps<typeof ComponentForm>;
+  label: ComponentProps<typeof Label>;
+  optionalFields: ComponentProps<typeof ComponentForm>;
+  optionalFieldButton: ComponentProps<typeof OptionalFieldButton>;
+};
+```
+
+Internally, `@pipedream/connect-react` uses `react-select` to implement complex
+dropdown components.
+
+```typescript
+export type ReactSelectComponents = {
+  controlAppSelect: typeof ControlApp;
+  controlSelect: typeof ControlSelect;
+};
+```
+
+Customizing dropdown components is very similar to customizing other inner components
+except each dropdown supports deeper customization of elements within `react-select`
+
+```tsx
+<CustomizeProvider
+  styles={{
+    controlSelect: {
+      control: (base, { theme }) => ({
+        ...base,
+        borderRadius: 0,
+        borderColor: theme.colors.primary25,
+        fontSize: "small",
+        maxHeight: "36px",
+      }),
+    },
+  }}
+/>
+```
+
+See [React Select](https://react-select.com/) for more details on the
+customization options available.
+
+## Hooks
+
+- `useCustomize` — _see above_
+- `useFormContext`
+- `useFormFieldContext`
+- `useFrontendClient` — _allows use of provided Pipedream frontendClient_
+- `useAccounts` — _react-query wrapper to list Pipedream connect accounts (for app, external user, etc.)_
+- `useApp` — _react-query wrapper to retrieve a Pipedream app_
+- `useApps` — _react-query wrapper to list Pipedream apps_
+- `useComponent` — _react-query wrapper to retrieve a Pipedream component (action or trigger)_
+- `useComponents` — _react-query wrapper to list Pipedream components (actions or triggers)_
+
+See [hooks](./src/hooks) folder for details.