From 0adef139f5ebeb2d5d6b50a8950735fc5c5b9e63 Mon Sep 17 00:00:00 2001 From: Alex Rock Date: Fri, 17 May 2024 04:30:51 -0600 Subject: [PATCH] feat: more comprehensive React docs (#1141) * feat: add new components, hooks and move current docs to a legacy group * feat: some fixes * feat: add more components * Update apps/embedding/react/components.mdx --- apps/embedding/react/components.mdx | 367 ++++++++++++++++++ .../react/components/FlatfileProvider.mdx | 23 ++ apps/embedding/react/components/Sheet.mdx | 55 +++ apps/embedding/react/components/Space.mdx | 21 + apps/embedding/react/components/Workbook.mdx | 26 ++ apps/embedding/react/guide.mdx | 2 +- .../react/{new_space.mdx => legacy.mdx} | 2 +- mint.json | 74 +++- 8 files changed, 550 insertions(+), 20 deletions(-) create mode 100644 apps/embedding/react/components.mdx create mode 100644 apps/embedding/react/components/FlatfileProvider.mdx create mode 100644 apps/embedding/react/components/Sheet.mdx create mode 100644 apps/embedding/react/components/Space.mdx create mode 100644 apps/embedding/react/components/Workbook.mdx rename apps/embedding/react/{new_space.mdx => legacy.mdx} (99%) diff --git a/apps/embedding/react/components.mdx b/apps/embedding/react/components.mdx new file mode 100644 index 000000000..e9b068deb --- /dev/null +++ b/apps/embedding/react/components.mdx @@ -0,0 +1,367 @@ +--- +title: "React Components" +description: "Configure your Space in React" +icon: "react" +--- + +## Components + +### FlatfileProvider + +`FlatfileProvider` is a comprehensive React component designed for integrating Flatfile's import capabilities into your application. +It can be initialized using either a `publishableKey` or an `accessToken`, providing flexibility depending on your authentication flow. +The component allows for extensive customization of the embedded iFrame through styling parameters, ensuring that the import modal matches your application's aesthetics. +It maintains the configuration necessary for creating and managing Spaces, Workbooks, and Documents within Flatfile. +Additionally, `FlatfileProvider` manages a client-side listener to handle browser-based events, ensuring a seamless user interaction with the import process. + +Learn more about the [FlatfileProvider](/apps/embedding/react/components/FlatfileProvider) + +```tsx + + + +``` + +### Space +The `Space` component from the `@flatfile/react` package is utilized to define a collaborative environment or workspace within Flatfile's import system. It can be configured to create a new space or to reuse an existing one by providing a space ID. + +#### Main Props + +- `config`: Sets up the configuration for a new space, including theming and metadata. +- `id`: An optional prop that, when provided, indicates the specific existing space to be reused instead of creating a new one. + +Learn more about the [Space](/apps/embedding/react/components/Space) + +Example usage for creating a new space: + +```tsx + +``` + +When you want to re-use a space, you'll need to pass an `accessToken` to the `FlatfileProvider`, then this is where you'll add the `id` of the Space you want to re-use. + +```tsx +const FFApp = () => ; +const App = () => { + return ( + + + + ); +}; +``` + +### Workbook + +Configures all Workbook Creation request data and an new onRecordHooks helper function + +`onSubmit` and a new `onRecordHooks` helper can be added to the Workbook. A Workbook object containing the sheets can be passed along in the `config`. +`onRecordHooks` takes an array of record hooks. Each one can take a slug for manually setting each per sheet. Otherwise, if no slug is added, it will apply the record hook to the corresponding sheet in the Workbook index. + +Learn more about the [Workbook](/apps/embedding/react/components/Workbook) + +```tsx + { + console.log("onSubmit", { sheet }); + }} + onRecordHooks={[ + [ + "contacts", + (record) => { + record.set("email", "TEST SHEET RECORD"); + return record; + }, + ], + ]} +/> +``` + +### Sheet +The `Sheet` component from the `@flatfile/react` package integrates Flatfile's data import functionality into React applications. It simplifies configuring the data import process and managing the lifecycle of data submission and record handling. + +#### Main Props + +- `config`: Defines the structure and settings of the data to be imported. +- `onSubmit`: A callback function that is triggered upon successful data submission. +- `onRecordHook`: A function that allows for custom record manipulation during the import process. +- `submitSettings`: Customizes the behavior of the data submission process. + + +The Sheet option is similar to the [Simplified SDK Approach](apps/embedding/reference/simple).. +Learn more about the [Sheet](/apps/embedding/react/components/Sheet) + +Example usage: +```tsx + { + record.set("email", "TEST SHEET RECORD"); + return record; + }} + onSubmit={(sheet) => { + console.log("onSubmit", { sheet }); + }} +/> +``` + +### Document + +Configures a Document to be added to the Space. Takes a simple `Flatfile.DocumentConfig` as a param. + +```tsx +const FFApp = () => ; +``` + +## React Hooks 🪝 + +### useFlatfile + +This Hook exposes a few handy functions for integrating with the FlatfileProvider + +- `openPortal()`: Opens the iFrame. This will create the underlying Space, Workbook and configure if necessary or open the Space provided. +- `closePortal()`: Closes the iFrame. +- `open`: current open status +- `listener`: Current listener +- `setListener()`: manually sets the listener + +### useListener + +This Hook exposes and adds any logic to the current listener with conditional dependencies + +```tsx +useListener( + (listener) => { + listener.on("**", (event) => { + console.log("initialListener Event => ", event.topic); + // Handle the workbook:deleted event + }); + }, + [label] +); +``` + +### usePlugin + +This Hook exposes and adds a plugin to the current listener with conditional dependencies + +```tsx +usePlugin( + recordHook("contacts", (record, event) => { + console.log("recordHook", { event }); + record.set("lastName", label); + return record; + }), + [label] +); +``` + +### useEvent + +This Hook exposes any event coming from the iFrame to respond to with proper filtering + +```tsx +useEvent("workbook:created", (event) => { + console.log("workbook:created", { event }); +}); + +useEvent("*:created", (event) => { + console.log({ topic: event.topic }); +}); + +useEvent("job:ready", { job: "sheet:submitActionFg" }, async (event) => { + const { jobId } = event.context; + try { + await api.jobs.ack(jobId, { + info: "Getting started.", + progress: 10, + }); + + // Make changes after cells in a Sheet have been updated + console.log("Make changes here when an action is clicked"); + const records = await event.data; + + console.log({ records }); + + await api.jobs.complete(jobId, { + outcome: { + message: "This is now complete.", + }, + }); + + // Probably a bad idea to close the portal here but just as an example + await sleep(3000); + closePortal(); + } catch (error: any) { + console.error("Error:", error.stack); + + await api.jobs.fail(jobId, { + outcome: { + message: "This job encountered an error.", + }, + }); + } +}); +``` + +## Full Example: + +```tsx +import { FlatfileProvider, Sheet, Space, Workbook, DocumentConfig } from "@flatfile/react"; +import { useFlatfile, useListener, usePlugin, useEvent } from "@flatfile/react"; +import { recordHook } from "@flatfile/plugin-record-hook"; +import { workbook } from "./workbook"; +import { listener as importedListener } from './listener' + +const FFApp = () => { + const { open, openPortal, closePortal } = useFlatfile() + + const [lastName, setLastName] = useState('Rock') + const togglePortal = () => { + open ? closePortal() : openPortal() + } + useListener( + (listener) => { + listener.on('**', (event) => { + console.log('initialListener Event => ', event.topic) + // Handle the workbook:deleted event + }) + importedListener + }, + [lastName] + ) + + // import file directly + useListener(importedListener, []) + + usePlugin( + recordHook('contacts', (record, event) => { + console.log('recordHook', { event }) + record.set('lastName', label) + return record + }), + [lastName] + ) + + useEvent('workbook:created', (event) => { + console.log('workbook:created', { event }) + }) + + useEvent('*:created', (event) => { + console.log({ topic: event.topic }) + }) + + useEvent('job:ready', { job: 'sheet:submitActionFg' }, async (event) => { + const { jobId } = event.context + try { + await api.jobs.ack(jobId, { + info: 'Getting started.', + progress: 10, + }) + + // Make changes after cells in a Sheet have been updated + console.log('Make changes here when an action is clicked') + const records = await event.data + + console.log({ records }) + + await api.jobs.complete(jobId, { + outcome: { + message: 'This is now complete.', + }, + }) + + // Probably a bad idea to close the portal here but just as an example + await sleep(3000) + closePortal() + } catch (error: any) { + console.error('Error:', error.stack) + + await api.jobs.fail(jobId, { + outcome: { + message: 'This job encountered an error.', + }, + }) + } + }) + + return ( +
+
+ + + +
+ + + + { + console.log("onSubmit", { sheet }); + }} + > + { + record.set("email", "TEST SHEET RECORD"); + return record; + }} + /> + + + +
+ ) +} + +const App = () => { + return ( + + + + ) +} + +export default App + +``` diff --git a/apps/embedding/react/components/FlatfileProvider.mdx b/apps/embedding/react/components/FlatfileProvider.mdx new file mode 100644 index 000000000..32924373e --- /dev/null +++ b/apps/embedding/react/components/FlatfileProvider.mdx @@ -0,0 +1,23 @@ +--- +title: FlatfileProvider Component Overview +--- + +# FlatfileProvider Component Overview + +`FlatfileProvider` is a context provider for the `@flatfile/react` package that wraps your application's components where Flatfile's import functionality will be used. It initializes and provides the Flatfile import system to its child components. + +## Main Props + +- `publishableKey`: The key provided by Flatfile to authenticate your application. +- `accessToken`: An alternative to `publishableKey` for authentication, typically used for server-side operations. +- `children`: React nodes for nested components, which can include `Space`, `Workbook`, or `Sheet` components. + +Example usage: + +```jsx + + + +``` + +This setup allows you to manage and interact with Flatfile imports seamlessly across your application. diff --git a/apps/embedding/react/components/Sheet.mdx b/apps/embedding/react/components/Sheet.mdx new file mode 100644 index 000000000..1ba770a0d --- /dev/null +++ b/apps/embedding/react/components/Sheet.mdx @@ -0,0 +1,55 @@ +--- +title: "Sheet Component Overview" +--- + +# Sheet Component Overview + +The `Sheet` component is a fundamental part of the `@flatfile/react` package, designed to handle the configuration and management of a single data sheet within a Flatfile import process. It provides a declarative way to define the structure, validation, and manipulation of data records. + +## Main Props + +- `config`: An object that defines the sheet's configuration, including its name, slug, and fields. + + - `name`: The human-readable name of the sheet. + - `slug`: A unique identifier for the sheet, used for referencing in the import process. + - `fields`: An array of objects defining the structure and constraints of each field in the sheet. + +- `onSubmit`: A callback function that is invoked when the sheet's data is successfully submitted. It receives the submitted data as an argument. + +- `onRecordHook`: A function that allows for custom manipulation of each record during the import process. It is called for each record and can modify, validate, or enrich the record data. + +- `submitSettings`: An object for customizing the behavior of the sheet's submission process, such as handling errors or setting a completion message. + +Example usage: + +```tsx +const App = () => { + const sheetConfig: Flatfile.SheetConfig = { + name: "Users", + slug: "users", + fields: [ + { key: "name", label: "Name", type: "string" }, + { key: "email", label: "Email", type: "string" }, + ], + }; + const handleSubmit = (data) => { + console.log("Submitted data:", data); + }; + const handleRecord = (record) => { + record.set("name", record.get("name").toUpperCase()); + }; + return ( + + ); +}; +``` + +In this example, the `Sheet` component is configured with a `config` object that defines the structure of the "Users" sheet. The `onSubmit` callback logs the submitted data, while the `onRecordHook` function modifies each record by converting the "name" field to uppercase. + +The `Sheet` component simplifies the process of defining and managing data sheets within a Flatfile import workflow, making it easier to create custom import experiences in your React application. + +For more details, refer to the code in the `Sheet.tsx` file in the [Flatfile SDK](https://github.com/FlatFilers/flatfile-core-libraries/blob/main/packages/react/src/components/Sheet.tsx) diff --git a/apps/embedding/react/components/Space.mdx b/apps/embedding/react/components/Space.mdx new file mode 100644 index 000000000..7369b8c5b --- /dev/null +++ b/apps/embedding/react/components/Space.mdx @@ -0,0 +1,21 @@ +--- +title: Space Component Overview +--- + +# Space Component Overview + +The `Space` component within the `@flatfile/react` package is used to define a workspace in Flatfile's import system. It encapsulates `Workbook` components and provides a context for the entire import process. + +## Main Props + +- `config`: Sets up the configuration for a new space, including theming and metadata. +- `id`: An optional prop that, when provided, indicates the specific existing space to be reused instead of creating a new one. +- `children`: React nodes for nested components, typically `Workbook`, `Sheet`, or `Document` components. + +Example usage: + +```tsx + + + +``` \ No newline at end of file diff --git a/apps/embedding/react/components/Workbook.mdx b/apps/embedding/react/components/Workbook.mdx new file mode 100644 index 000000000..2d04baba7 --- /dev/null +++ b/apps/embedding/react/components/Workbook.mdx @@ -0,0 +1,26 @@ +--- +title: Workbook Component Overview +--- + +# Workbook Component Overview + +The `Workbook` component is a key part of the `@flatfile/react` package, designed to manage multiple `Sheet` components as a collection. It represents a workbook within Flatfile's import system, allowing for the configuration of multiple sheets and associated actions. + +## Main Props + +- `config`: Configuration for the workbook, including its sheets and actions. +- `onSubmit`: Callback function executed when the workbook is submitted. +- `onRecordHooks`: Array of hooks for custom record processing. +- `children`: React nodes for nested components, typically `Sheet` components. + +Example usage: + +```tsx + + + +``` diff --git a/apps/embedding/react/guide.mdx b/apps/embedding/react/guide.mdx index 7d2410ab0..27eaf1f7b 100644 --- a/apps/embedding/react/guide.mdx +++ b/apps/embedding/react/guide.mdx @@ -22,7 +22,7 @@ First, decide if you want to start from scratch or make changes to an existing p > Clone the create-flatfile-react example project in GitHub. - + Set up an embedded Flatfile Workbook from beginning to end. diff --git a/apps/embedding/react/new_space.mdx b/apps/embedding/react/legacy.mdx similarity index 99% rename from apps/embedding/react/new_space.mdx rename to apps/embedding/react/legacy.mdx index 1fc0afbae..2e179de2c 100644 --- a/apps/embedding/react/new_space.mdx +++ b/apps/embedding/react/legacy.mdx @@ -1,5 +1,5 @@ --- -title: "Embed a new Space" +title: "Embed a new Space " description: "Create a new Space every time Flatfile is opened." icon: "plus" --- diff --git a/mint.json b/mint.json index 1c37c02a7..58b36978b 100644 --- a/mint.json +++ b/mint.json @@ -176,7 +176,10 @@ "navigation": [ { "group": "Documentation", - "pages": ["overview", "starter-projects"] + "pages": [ + "overview", + "starter-projects" + ] }, { "group": "Highlights", @@ -188,7 +191,10 @@ }, { "group": "Core Libraries", - "pages": ["changelog/sdks/core/cli", "changelog/sdks/core/listener"] + "pages": [ + "changelog/sdks/core/cli", + "changelog/sdks/core/listener" + ] }, { "group": "Embedded Wrappers", @@ -223,7 +229,9 @@ }, { "group": "Automation", - "pages": ["changelog/sdks/plugins/automations/automap"] + "pages": [ + "changelog/sdks/plugins/automations/automap" + ] }, { "group": "Export", @@ -243,7 +251,9 @@ }, { "group": "Migrations", - "pages": ["changelog/sdks/plugins/migrations/dxp-configure"] + "pages": [ + "changelog/sdks/plugins/migrations/dxp-configure" + ] }, { "group": "Core", @@ -292,11 +302,15 @@ "pages": [ "apps/embedding/react/guide", "apps/embedding/react/new_space_quickstart", + "apps/embedding/react/components", { - "group": "Advanced", + "group": "Legacy", "icon": "settings", - "pages": ["apps/embedding/react/new_space"] + "pages": [ + "apps/embedding/react/legacy" + ] } + ] }, { @@ -308,7 +322,9 @@ { "group": "Advanced", "icon": "settings", - "pages": ["apps/embedding/vue/reuse_space"] + "pages": [ + "apps/embedding/vue/reuse_space" + ] } ] }, @@ -378,7 +394,9 @@ }, { "group": "By Integration", - "pages": ["guides/bubble-io"] + "pages": [ + "guides/bubble-io" + ] }, { "group": "Orchestration", @@ -402,7 +420,9 @@ }, { "group": "Upgrade", - "pages": ["upgrade/overview"] + "pages": [ + "upgrade/overview" + ] }, { "group": "Portal - version 2", @@ -436,7 +456,10 @@ }, { "group": "Core Architecture", - "pages": ["developer-tools/environment", "developer-tools/spaces"] + "pages": [ + "developer-tools/environment", + "developer-tools/spaces" + ] }, { "group": "Security", @@ -474,11 +497,15 @@ }, { "group": "Mapping", - "pages": ["developer-tools/mapping-libraries/flatfile-mapping-python"] + "pages": [ + "developer-tools/mapping-libraries/flatfile-mapping-python" + ] }, { "group": "Plugins", - "pages": ["plugins-docs/overview"] + "pages": [ + "plugins-docs/overview" + ] }, { "group": "Extractors", @@ -492,7 +519,9 @@ { "group": "More in development", "icon": "clock", - "pages": ["plugins-docs/extractors/doc-extractor"] + "pages": [ + "plugins-docs/extractors/doc-extractor" + ] } ] }, @@ -513,7 +542,10 @@ }, { "group": "Export", - "pages": ["plugins-docs/export/workbook", "plugins-docs/export/webhook"] + "pages": [ + "plugins-docs/export/workbook", + "plugins-docs/export/webhook" + ] }, { "group": "Schemas", @@ -525,7 +557,9 @@ { "group": "More in development", "icon": "clock", - "pages": ["plugins-docs/schemas/convert-graphql"] + "pages": [ + "plugins-docs/schemas/convert-graphql" + ] } ] }, @@ -536,13 +570,17 @@ { "group": "More in development", "icon": "clock", - "pages": ["plugins-docs/datasets/countries"] + "pages": [ + "plugins-docs/datasets/countries" + ] } ] }, { "group": "Migrations", - "pages": ["plugins-docs/migrations/dxp-configure"] + "pages": [ + "plugins-docs/migrations/dxp-configure" + ] }, { "group": "Core", @@ -601,4 +639,4 @@ "url": "upgrade" } ] -} +} \ No newline at end of file