From 57ec779a8fa858c8192da9a0a5129afc42bada87 Mon Sep 17 00:00:00 2001
From: Alex Rock <hi@lxrck.com>
Date: Wed, 8 May 2024 01:42:48 -0600
Subject: [PATCH 1/4] feat: add new components, hooks and move current docs to
 a legacy group

---
 apps/embedding/react/components.mdx           | 350 ++++++++++++++++++
 .../react/components/FlatfileProvider.mdx     |  45 +++
 .../react/{new_space.mdx => legacy.mdx}       |   2 +-
 mint.json                                     |  74 +++-
 4 files changed, 452 insertions(+), 19 deletions(-)
 create mode 100644 apps/embedding/react/components.mdx
 create mode 100644 apps/embedding/react/components/FlatfileProvider.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..675c0ecb9
--- /dev/null
+++ b/apps/embedding/react/components.mdx
@@ -0,0 +1,350 @@
+---
+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
+<FlatfileProvider
+    publishableKey={PUBLISHABLE_KEY}
+    config={{
+        mountElement,
+        exitText
+        exitTitle,
+        exitPrimaryButtonText
+        exitSecondaryButtonText,
+        displayAsModal: true,
+    }}
+>
+      <FFApp />
+</FlatfileProvider>
+```
+
+### Space
+
+Configures all Space Creation request data and the `id` for reusing a space
+
+```tsx
+<Space
+  config={{
+    metadata: {
+      sidebarConfig: {
+        showSidebar: true,
+      },
+    },
+  }}
+/>
+```
+
+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 = () => <Space config={{ id: "us_sp_123456" }} />;
+const App = () => {
+  return (
+    <FlatfileProvider accessToken={ACCESS_TOKEN}>
+      <FFApp />
+    </FlatfileProvider>
+  );
+};
+```
+
+### Workbook
+
+Configures all Workbook Creation request data and an new onRecordHooks helper function
+
+Sheets can be passed along in the `config`, `onSubmit` can be added, along with a new `onRecordHooks` helper.
+`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.
+
+```tsx
+<Workbook
+  config={workbook}
+  onSubmit={(sheet) => {
+    console.log("onSubmit", { sheet });
+  }}
+  onRecordHooks={[
+    [
+      "contacts",
+      (record) => {
+        record.set("email", "TEST SHEET RECORD");
+        return record;
+      },
+    ],
+  ]}
+/>
+```
+
+### Sheet
+
+Similar to the Simplified SDK Approach
+
+Configures a Sheet config, with an onRecordHook helper
+
+Note: an `onSubmit` can be added to the Workbook Component for ease of use
+
+```tsx
+<Sheet
+  config={sheet}
+  onRecordHook={(record) => {
+    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 = () => <Document config={document} />;
+```
+
+## 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 (
+    <div className={styles.main}>
+      <div className={styles.description}>
+        <button onClick={togglePortal} >
+          { open ? 'OPEN' : 'CLOSE' } PORTAL
+        </button>
+        <button onClick={() => setLabel('blue')}>blue listener</button>
+        <button onClick={() => setLabel('green')}>green listener</button>
+      </div>
+
+      <Space
+        config={{
+          metadata: {
+            sidebarConfig: {
+              showSidebar: true,
+            },
+          },
+        }}
+      >
+        <Document config={document} />
+        <Workbook
+          config={workbook}
+          onSubmit={(sheet) => {
+            console.log("onSubmit", { sheet });
+          }}
+        >
+          <Sheet
+            config={sheet}
+            onRecordHook={(record) => {
+              record.set("email", "TEST SHEET RECORD");
+              return record;
+            }}
+          />
+          <Sheet config={{ ...sheet, name: "Contacts 2", slug: "contacts2" }} />
+        </Workbook>
+      </Space>
+    </div>
+  )
+}
+
+const App = () => {
+  return (
+    <FlatfileProvider
+      publishableKey={PUBLISHABLE_KEY}
+      config={{
+        mountElement,
+        exitText
+        exitTitle,
+        exitPrimaryButtonText
+        exitSecondaryButtonText,
+        displayAsModal: true,
+      }}
+    >
+      <FFApp />
+    </FlatfileProvider>
+  )
+}
+
+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..b6010cb3f
--- /dev/null
+++ b/apps/embedding/react/components/FlatfileProvider.mdx
@@ -0,0 +1,45 @@
+---
+title: FlatfileProvider Component
+---
+
+`FlatfileProvider` is a React component that serves as a context provider for Flatfile integration.
+It encapsulates all the necessary state and methods required to manage and interact with Flatfile's services.
+This provider component makes use of the Flatfile API and listener to handle data import processes within your application.
+
+## Props
+
+- **`children`**: `ReactNode` - The child components that will have access to the Flatfile context.
+- **`publishableKey`**: `string` - The publishable key provided by Flatfile for authentication.
+- **`accessToken`**: `string` - Access token for secure interaction with the Flatfile API.
+- **`environmentId`**: `string` - Identifier for the environment within Flatfile.
+- **`apiUrl`**: `string` - (Optional) URL of the Flatfile API. Defaults to 'https://platform.flatfile.com/api'.
+- **`config`**: `object` - Configuration options for the Flatfile import.
+
+## State
+
+- **`internalAccessToken`**: `string | undefined` - Manages the internal state of the access token.
+- **`listener`**: `FlatfileListener` - An instance of FlatfileListener to handle browser-based events.
+- **`open`**: `boolean` - State to manage the visibility of the Flatfile import modal.
+- **`sessionSpace`**: `any` - Represents the current session's workspace.
+- **`createSpace`**: `object` - Configuration for creating a new workspace, document, or workbook.
+
+## Methods
+
+- **`addSheet`**: `(newSheet: Flatfile.SheetConfig) => void` - Adds a new sheet to the workbook if it doesn't already exist.
+- **`updateSheet`**: `(sheetSlug: string, sheetUpdates: Partial<Flatfile.SheetConfig>) => void` - Updates properties of an existing sheet.
+- **`updateWorkbook`, `updateDocument`, `updateSpace`**: Functions to update respective configurations.
+
+## Usage
+
+Wrap your component tree with `FlatfileProvider` to provide all child components access to Flatfile functionalities through context.
+
+```jsx
+<FlatfileProvider
+  publishableKey="your-publishable-key"
+  accessToken="your-access-token"
+>
+  <YourComponent />
+</FlatfileProvider>
+```
+
+This setup allows you to manage and interact with Flatfile imports seamlessly across your application.
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..b9155d9b2 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",
+                "creact/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

From e0007a332bf4edbc9af6b11ff80390795aab5333 Mon Sep 17 00:00:00 2001
From: Alex Rock <hi@lxrck.com>
Date: Wed, 8 May 2024 20:17:25 -0600
Subject: [PATCH 2/4] feat: some fixes

---
 apps/embedding/react/components.mdx | 6 +++---
 apps/embedding/react/guide.mdx      | 2 +-
 mint.json                           | 2 +-
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/apps/embedding/react/components.mdx b/apps/embedding/react/components.mdx
index 675c0ecb9..084f0087d 100644
--- a/apps/embedding/react/components.mdx
+++ b/apps/embedding/react/components.mdx
@@ -65,7 +65,7 @@ const App = () => {
 
 Configures all Workbook Creation request data and an new onRecordHooks helper function
 
-Sheets can be passed along in the `config`, `onSubmit` can be added, along with a new `onRecordHooks` helper.
+`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.
 
 ```tsx
@@ -88,9 +88,9 @@ Sheets can be passed along in the `config`, `onSubmit` can be added, along with
 
 ### Sheet
 
-Similar to the Simplified SDK Approach
+The Sheet option is similar to the [Simplified SDK Approach](apps/embedding/reference/simple)..
 
-Configures a Sheet config, with an onRecordHook helper
+Configures a Sheet config, with an `onRecordHook` helper
 
 Note: an `onSubmit` can be added to the Workbook Component for ease of use
 
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.
   </Card>
-  <Card title="Start from scratch" href="../react/new_space" icon="pencil">
+  <Card title="Start from scratch" href="../react/new_space_quickstart" icon="pencil">
     Set up an embedded Flatfile Workbook from beginning to end.
   </Card>
 </CardGroup>
diff --git a/mint.json b/mint.json
index b9155d9b2..58b36978b 100644
--- a/mint.json
+++ b/mint.json
@@ -302,7 +302,7 @@
               "pages": [
                 "apps/embedding/react/guide",
                 "apps/embedding/react/new_space_quickstart",
-                "creact/components",
+                "apps/embedding/react/components",
                 {
                   "group": "Legacy",
                   "icon": "settings",

From c16bab53a068c36d831efc6b0fd2c362d22cf736 Mon Sep 17 00:00:00 2001
From: Alex Rock <hi@lxrck.com>
Date: Wed, 8 May 2024 20:44:53 -0600
Subject: [PATCH 3/4] feat: add more components

---
 apps/embedding/react/components.mdx           | 25 +++++++--
 .../react/components/FlatfileProvider.mdx     | 40 +++-----------
 apps/embedding/react/components/Sheet.mdx     | 55 +++++++++++++++++++
 apps/embedding/react/components/Space.mdx     | 21 +++++++
 apps/embedding/react/components/Workbook.mdx  | 26 +++++++++
 5 files changed, 132 insertions(+), 35 deletions(-)
 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

diff --git a/apps/embedding/react/components.mdx b/apps/embedding/react/components.mdx
index 084f0087d..d8439b8f4 100644
--- a/apps/embedding/react/components.mdx
+++ b/apps/embedding/react/components.mdx
@@ -33,8 +33,16 @@ Learn more about the [FlatfileProvider](/apps/embedding/react/components/Flatfil
 ```
 
 ### 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.
 
-Configures all Space Creation request data and the `id` for reusing a space
+#### 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
 <Space
@@ -68,6 +76,8 @@ Configures all Workbook Creation request data and an new onRecordHooks helper fu
 `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
 <Workbook
   config={workbook}
@@ -87,13 +97,20 @@ Configures all Workbook Creation request data and an new onRecordHooks helper fu
 ```
 
 ### 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.
 
-The Sheet option is similar to the [Simplified SDK Approach](apps/embedding/reference/simple)..
+#### 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.
 
-Configures a Sheet config, with an `onRecordHook` helper
 
-Note: an `onSubmit` can be added to the Workbook Component for ease of use
+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
 <Sheet
   config={sheet}
diff --git a/apps/embedding/react/components/FlatfileProvider.mdx b/apps/embedding/react/components/FlatfileProvider.mdx
index b6010cb3f..32924373e 100644
--- a/apps/embedding/react/components/FlatfileProvider.mdx
+++ b/apps/embedding/react/components/FlatfileProvider.mdx
@@ -1,43 +1,21 @@
 ---
-title: FlatfileProvider Component
+title: FlatfileProvider Component Overview
 ---
 
-`FlatfileProvider` is a React component that serves as a context provider for Flatfile integration.
-It encapsulates all the necessary state and methods required to manage and interact with Flatfile's services.
-This provider component makes use of the Flatfile API and listener to handle data import processes within your application.
+# FlatfileProvider Component Overview
 
-## Props
+`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.
 
-- **`children`**: `ReactNode` - The child components that will have access to the Flatfile context.
-- **`publishableKey`**: `string` - The publishable key provided by Flatfile for authentication.
-- **`accessToken`**: `string` - Access token for secure interaction with the Flatfile API.
-- **`environmentId`**: `string` - Identifier for the environment within Flatfile.
-- **`apiUrl`**: `string` - (Optional) URL of the Flatfile API. Defaults to 'https://platform.flatfile.com/api'.
-- **`config`**: `object` - Configuration options for the Flatfile import.
+## Main Props
 
-## State
+- `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.
 
-- **`internalAccessToken`**: `string | undefined` - Manages the internal state of the access token.
-- **`listener`**: `FlatfileListener` - An instance of FlatfileListener to handle browser-based events.
-- **`open`**: `boolean` - State to manage the visibility of the Flatfile import modal.
-- **`sessionSpace`**: `any` - Represents the current session's workspace.
-- **`createSpace`**: `object` - Configuration for creating a new workspace, document, or workbook.
-
-## Methods
-
-- **`addSheet`**: `(newSheet: Flatfile.SheetConfig) => void` - Adds a new sheet to the workbook if it doesn't already exist.
-- **`updateSheet`**: `(sheetSlug: string, sheetUpdates: Partial<Flatfile.SheetConfig>) => void` - Updates properties of an existing sheet.
-- **`updateWorkbook`, `updateDocument`, `updateSpace`**: Functions to update respective configurations.
-
-## Usage
-
-Wrap your component tree with `FlatfileProvider` to provide all child components access to Flatfile functionalities through context.
+Example usage:
 
 ```jsx
-<FlatfileProvider
-  publishableKey="your-publishable-key"
-  accessToken="your-access-token"
->
+<FlatfileProvider publishableKey="your-publishable-key">
   <YourComponent />
 </FlatfileProvider>
 ```
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 (
+    <Sheet
+      config={sheetConfig}
+      onSubmit={handleSubmit}
+      onRecordHook={handleRecord}
+    />
+  );
+};
+```
+
+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
+<Space config={spaceConfig}>
+    <Workbook config={workbookConfig} />
+</Space>
+```
\ 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
+<Workbook
+  config={workbookConfig}
+  onSubmit={handleWorkbookSubmit}
+  onRecordHooks={recordHooksArray}
+>
+  <Sheet config={sheetConfig} />
+</Workbook>
+```

From 2c554ba1bc41b1ef48ef316c5f0b2fea3378e7e7 Mon Sep 17 00:00:00 2001
From: Alex Rock <hi@lxrck.com>
Date: Fri, 17 May 2024 04:30:02 -0600
Subject: [PATCH 4/4] Update apps/embedding/react/components.mdx

---
 apps/embedding/react/components.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/embedding/react/components.mdx b/apps/embedding/react/components.mdx
index d8439b8f4..e9b068deb 100644
--- a/apps/embedding/react/components.mdx
+++ b/apps/embedding/react/components.mdx
@@ -59,7 +59,7 @@ Example usage for creating a new space:
 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 = () => <Space config={{ id: "us_sp_123456" }} />;
+const FFApp = () => <Space id={"us_sp_123456" } />;
 const App = () => {
   return (
     <FlatfileProvider accessToken={ACCESS_TOKEN}>