@dev-fastn-ai/react-core 2.4.4 → 2.4.6

package/CHANGELOG.md

@@ -5,13 +5,6 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
-
-### Added
-- `useFieldOptions` hook now supports passing context data to `getOptions` and `loadMore` methods
-- Context parameter allows passing form data or additional parameters for dynamic option filtering
-- Support for cascading dropdowns and context-dependent option loading
-
 ## [1.0.0] - 2024-01-XX
 
 ### Added

package/README.md

@@ -603,7 +603,8 @@ For fields of type `select` or `multi-select`, use the `useFieldOptions` hook to
 ```tsx
 import { useFieldOptions } from "@fastn-ai/react-core";
 
-function SelectField({ field, value, onChange, isMulti = false }) {
+function SelectField({ field, value, onChange, isMulti = false, context = {} }) {
+  // context contains all form values and is used to fetch dependent options
   const {
     options,
     loading,
@@ -613,7 +614,7 @@ function SelectField({ field, value, onChange, isMulti = false }) {
     error,
     search,
     totalLoadedOptions,
-  } = useFieldOptions(field,context);
+  } = useFieldOptions(field, context);
 
   function handleInputChange(e) {
     search(e.target.value);
@@ -715,10 +716,10 @@ function SelectField({ field, value, onChange, isMulti = false }) {
 
 ### **Google Drive Picker Fields**
 
-For Google Drive file picker fields, handle the file selection flow. These fields also work with `{ label, value }` objects:
+For Google Drive file picker fields, handle the file selection flow. These fields also work with `{ label, value }` objects and support file type filtering:
 
 ```tsx
-function GoogleFilesPickerField({ field, value, onChange, isMulti = false }) {
+function GoogleFilesPickerField({ field, value, onChange, isMulti = false, context = {} }) {
   async function handlePickFiles() {
     if (field.optionsSource?.openGoogleFilesPicker) {
       await field.optionsSource.openGoogleFilesPicker({
@@ -743,6 +744,7 @@ function GoogleFilesPickerField({ field, value, onChange, isMulti = false }) {
           console.error("Google Files Picker error:", pickerError);
           alert("Failed to pick files: " + pickerError);
         },
+        fileTypes: field?.optionsSource?.fileTypes,
       });
     }
   }
@@ -786,7 +788,7 @@ function GoogleFilesPickerField({ field, value, onChange, isMulti = false }) {
 Create a reusable component that handles different field types with proper value handling:
 
 ```tsx
-function FormField({ field, value, onChange }) {
+function FormField({ field, value, onChange, context = {} }) {
   switch (field.type) {
     case "text":
     case "email":
@@ -839,6 +841,7 @@ function FormField({ field, value, onChange }) {
           value={value} 
           onChange={onChange} 
           isMulti={false}
+          context={context}
         />
       );
       
@@ -849,6 +852,7 @@ function FormField({ field, value, onChange }) {
           value={value} 
           onChange={onChange} 
           isMulti={true}
+          context={context}
         />
       );
       
@@ -859,6 +863,7 @@ function FormField({ field, value, onChange }) {
           value={value} 
           onChange={onChange} 
           isMulti={false}
+          context={context}
         />
       );
       
@@ -869,6 +874,7 @@ function FormField({ field, value, onChange }) {
           value={value} 
           onChange={onChange} 
           isMulti={true}
+          context={context}
         />
       );
       
@@ -886,6 +892,186 @@ function FormField({ field, value, onChange }) {
 
 ---
 
+## 🔗 Field Context Passing
+
+The React Core library supports **dynamic field dependencies** where form fields can access and respond to values from other fields in real-time. This enables complex form workflows where the options or behavior of one field depends on the selection made in another field.
+
+### **How Context Passing Works**
+
+When a user selects a value in one field, that value becomes available to all other fields through the `context` parameter. This allows dependent fields to:
+
+- Load different options based on the parent field's selection
+- Show/hide fields based on other field values
+- Update their behavior dynamically
+
+### **Implementation Example**
+
+Here's how to implement context passing in your form components:
+
+```tsx
+import { useConfigurationForm } from "@fastn-ai/react-core";
+
+function ConfigurationForm({ configurationId, connectorId, configuration }) {
+  const { data: configurationForm, isLoading, error } = useConfigurationForm({
+    configurationId,
+    connectorId,
+    configuration,
+  });
+
+  return (
+    <Formik
+      initialValues={initialValues}
+      onSubmit={handleSubmit}
+    >
+      {({ values, setFieldValue, setFieldTouched, errors, touched }) => (
+        <Form>
+          {configurationForm.fields
+            .filter((field) => !field.hidden)
+            .map((field) => (
+              <FormField
+                key={field.name}
+                field={field}
+                form={{ values, errors, touched }}
+                setFieldValue={setFieldValue}
+                setFieldTouched={setFieldTouched}
+                context={values} // Pass all form values as context
+              />
+            ))}
+        </Form>
+      )}
+    </Formik>
+  );
+}
+
+// FormField component that passes context to individual fields
+function FormField({ field, form, setFieldValue, setFieldTouched, context }) {
+  const handleChange = useCallback(
+    (value) => {
+      setFieldValue(field.name, value);
+      setFieldTouched(field.name, true);
+    },
+    [field.name, setFieldValue, setFieldTouched]
+  );
+
+  switch (field.type) {
+    case "select":
+    case "multi-select":
+      return (
+        <SelectField
+          field={field}
+          onChange={handleChange}
+          value={form.values[field.name]}
+          isMulti={field.type === "multi-select"}
+          context={context} // Pass context to SelectField
+        />
+      );
+    // ... other field types
+  }
+}
+
+// SelectField component that uses context
+function SelectField({ field, onChange, value, isMulti, context }) {
+  // The useFieldOptions hook receives the context and can use it
+  // to fetch options based on other field values
+  const {
+    options,
+    loading,
+    loadingMore,
+    hasNext,
+    loadMore,
+    error,
+    search,
+    refresh,
+    totalLoadedOptions,
+  } = useFieldOptions(field, context);
+
+  const handleChange = useCallback(
+    (selected) => {
+      onChange(selected);
+      // When this field changes, the context is automatically updated
+      // and passed to all other fields
+    },
+    [onChange]
+  );
+
+  // ... rest of component implementation
+}
+```
+
+### **Context Structure**
+
+The `context` parameter contains all current form values in the following structure:
+
+```tsx
+// Example context object
+const context = {
+  workspace: { label: "My Workspace", value: "ws_123" },
+  channel: { label: "General", value: "ch_456" },
+  webhookUrl: "https://hooks.slack.com/...",
+  enableNotifications: true,
+  // ... other field values
+};
+```
+
+### **Use Cases**
+
+1. **Workspace → Channel Selection**: When a user selects a workspace, the channel field loads only channels from that workspace.
+
+2. **Database → Table Selection**: When a database is selected, the table field shows only tables from that database.
+
+3. **Conditional Field Display**: Show/hide fields based on other field values.
+
+4. **Dynamic Option Loading**: Load different options based on parent field selections.
+
+### **Best Practices**
+
+1. **Always pass context**: Make sure to pass the `context` parameter to all field components that need access to other field values.
+
+2. **Handle loading states**: When context changes, dependent fields may need to reload their options, so handle loading states appropriately.
+
+3. **Optimize re-renders**: Use `useCallback` and `useMemo` to prevent unnecessary re-renders when context changes.
+
+4. **Error handling**: Handle cases where context-dependent operations fail gracefully.
+
+### **Advanced Example: Multi-level Dependencies**
+
+```tsx
+// Example: Workspace → Channel → User selection
+function MultiLevelSelectForm() {
+  const [formValues, setFormValues] = useState({});
+
+  return (
+    <div>
+      {/* Workspace selection */}
+      <SelectField
+        field={workspaceField}
+        value={formValues.workspace}
+        onChange={(value) => setFormValues(prev => ({ ...prev, workspace: value }))}
+        context={formValues}
+      />
+
+      {/* Channel selection - depends on workspace */}
+      <SelectField
+        field={channelField}
+        value={formValues.channel}
+        onChange={(value) => setFormValues(prev => ({ ...prev, channel: value }))}
+        context={formValues} // Has access to workspace value
+      />
+
+      {/* User selection - depends on both workspace and channel */}
+      <SelectField
+        field={userField}
+        value={formValues.user}
+        onChange={(value) => setFormValues(prev => ({ ...prev, user: value }))}
+        context={formValues} // Has access to both workspace and channel values
+      />
+    </div>
+  );
+}
+```
+
+---
+
 ### **Error Handling and Loading States**
 
 ```tsx

package/dist/core/use-connectors.d.ts

@@ -1 +1 @@
-export declare const useConnectors: () => import("@tanstack/react-query").UseQueryResult<import("@dev-fastn-ai/core").Connector[], Error>;
+export declare const useConnectors: () => import("@tanstack/react-query").UseQueryResult<import("@fastn-ai/core").Connector[], Error>;

package/dist/core/use-field-options.d.ts

@@ -23,7 +23,7 @@ import type { ConnectorField, SelectOption, FormData } from "@fastn-ai/core";
  * // Pagination is managed with infinite query
  * ```
  */
-export declare function useFieldOptions(field: ConnectorField, context?: FormData): {
+export declare function useFieldOptions(field: ConnectorField, context?: FormData | object): {
     options: SelectOption[];
     loading: boolean;
     loadingMore: boolean;

package/dist/index.d.ts

@@ -41,7 +41,7 @@ declare const useConnectors: () => _tanstack_react_query.UseQueryResult<_fastn_a
  * // Pagination is managed with infinite query
  * ```
  */
-declare function useFieldOptions(field: ConnectorField, context?: FormData): {
+declare function useFieldOptions(field: ConnectorField, context?: FormData | object): {
     options: SelectOption[];
     loading: boolean;
     loadingMore: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-fastn-ai/react-core",
-  "version": "2.4.4",
+  "version": "2.4.6",
   "description": "React hooks and components for integrating Fastn AI connector marketplace into your applications. Built on top of @fastn-ai/core with React Query for optimal performance.",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
@@ -52,15 +52,15 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/fastn-ai/react-core.git"
+    "url": "https://github.com/dev-fastn-ai/react-core.git"
   },
   "bugs": {
-    "url": "https://github.com/fastn-ai/react-core/issues"
+    "url": "https://github.com/dev-fastn-ai/react-core/issues"
   },
   "homepage": "https://docs.fastn.ai",
   "dependencies": {
     "@dev-fastn-ai/core": "^2.0.7",
-    "@fastn-ai/core": "^1.0.4",
+    "@fastn-ai/core": "^1.0.5",
     "@types/lodash": "^4.17.20",
     "lodash": "^4.17.21"
   },
@@ -89,4 +89,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}