@dev-fastn-ai/react-core 2.3.6 → 2.3.8

package/README.md

@@ -257,6 +257,22 @@ interface ConnectorField {
     | Primitive
     | Primitive[];
   readonly optionsSource?: SelectOptionSource;
+  readonly configs?: {
+    selection?: {
+      enable?: boolean;
+      type?: "MAPPING" | string;
+      isAddFields?: boolean;
+      isEditKeys?: boolean;
+      source?: {
+        flowId: string;
+        isSameProject: boolean;
+      };
+      destination?: {
+        flowId: string;
+        isSameProject: boolean;
+      };
+    };
+  };
 }
 ```
 
@@ -561,6 +577,7 @@ The form fields handle different value types based on the field type:
 - **Select fields**: Always return `{ label: string, value: string }` objects
 - **Multi-select fields**: Always return `{ label: string, value: string }[]` arrays
 - **Google Drive picker fields**: Always return `{ label: string, value: string }` objects or arrays
+- **Mapping fields**: Always return `{ label: string, value: string }[]` arrays where `label` is the source field and `value` is the destination field
 - **Other fields**: Return primitive values (string, number, boolean)
 
 ```tsx
@@ -584,6 +601,13 @@ const formData = {
     { label: "document2.pdf", value: "file_id_2" }
   ],
   
+  // Mapping field - array of mapping objects
+  fieldMappings: [
+    { label: "First Name", value: "user_first_name" },
+    { label: "Email Address", value: "user_email" },
+    { label: "Phone Number", value: "user_phone" }
+  ],
+  
   // Text field - primitive
   webhookUrl: "https://hooks.slack.com/...",
   
@@ -781,6 +805,438 @@ function GoogleFilesPickerField({ field, value, onChange, isMulti = false }) {
 }
 ```
 
+### **Mapping Fields**
+
+Mapping fields allow users to create relationships between source fields and destination fields. They are commonly used for data transformation scenarios where you need to map fields from one system to another (e.g., mapping CSV columns to database fields, or API response fields to form inputs).
+
+#### **Field Type and Value Structure**
+
+Mapping fields use the `ConnectorFieldType.MAPPING` type and always work with arrays of mapping objects:
+
+```tsx
+// Mapping field value structure
+const mappingValue = [
+  {
+    label: "Source Field Name",    // The source field identifier
+    value: "destination_value"     // The selected destination field value
+  },
+  {
+    label: "Email Address",
+    value: "user_email"
+  },
+  {
+    label: "Full Name", 
+    value: "display_name"
+  }
+];
+```
+
+#### **Field Configuration**
+
+Mapping fields require specific configuration in the `ConnectorField`:
+
+```tsx
+interface MappingFieldConfig {
+  // Field type must be "mapping"
+  type: "mapping";
+  
+  // Configuration for source and destination options
+  configs: {
+    selection: {
+      // Enable mapping functionality
+      enable: true;
+      type: "MAPPING";
+      
+      // Configuration for adding/editing fields
+      isAddFields?: boolean;    // Allow users to add new source fields
+      isEditKeys?: boolean;     // Allow users to edit source field names
+      
+      // Source options configuration
+      source: {
+        flowId: string;         // ID of the flow providing source options
+        isSameProject: boolean; // Whether source is in same project
+      };
+      
+      // Destination options configuration  
+      destination: {
+        flowId: string;         // ID of the flow providing destination options
+        isSameProject: boolean; // Whether destination is in same project
+      };
+    };
+  };
+  
+  // Options source for dynamic loading
+  optionsSource: {
+    getOptions: (pagination, context, searchQuery) => Promise<OptionsResult>;
+  };
+}
+```
+
+#### **Complete Mapping Field Component**
+
+Here's a full implementation of a mapping field component using the `useFieldOptions` hook:
+
+```tsx
+import { useCallback, useState, useEffect } from "react";
+import { useFieldOptions } from "@fastn-ai/react-core";
+import Select from "react-select";
+
+interface MappingFieldProps {
+  field: ConnectorField;
+  value: MappingValue[];
+  onChange: (value: MappingValue[]) => void;
+}
+
+interface MappingValue {
+  label: string;  // Source field name
+  value: string;  // Destination field value
+}
+
+function MappingField({ field, value, onChange }: MappingFieldProps) {
+  // Get mapping-specific functions from useFieldOptions
+  const {
+    selectionConfig,
+    getSourceOptions,
+    getDestinationOptions,
+  } = useFieldOptions(field);
+
+  const mappingValue = Array.isArray(value) ? value : [];
+  
+  // State for source and destination options
+  const [sourceOptions, setSourceOptions] = useState<SelectOption[]>([]);
+  const [destinationOptions, setDestinationOptions] = useState<SelectOption[]>([]);
+  const [sourceLoading, setSourceLoading] = useState(false);
+  const [destinationLoading, setDestinationLoading] = useState(false);
+
+  // Initialize source options from existing mappings
+  const initialSourceOptions = mappingValue.length > 0
+    ? mappingValue.map((item) => ({
+        label: item.label,
+        value: item.label,
+      }))
+    : [];
+
+  // Load source options
+  const loadSourceOptions = useCallback(async () => {
+    setSourceLoading(true);
+    try {
+      const result = await getSourceOptions({ id: "configurationId" });
+      const rawOptions = result?.options || [];
+      
+      const newSourceOptions = Array.isArray(rawOptions)
+        ? rawOptions.map((option) =>
+            typeof option === "string" 
+              ? { label: option, value: option } 
+              : option
+          )
+        : [];
+      setSourceOptions(newSourceOptions);
+    } catch (err) {
+      console.error("Error loading source options:", err);
+    } finally {
+      setSourceLoading(false);
+    }
+  }, [getSourceOptions]);
+
+  // Load destination options
+  const loadDestinationOptions = useCallback(async () => {
+    setDestinationLoading(true);
+    try {
+      const result = await getDestinationOptions({ id: "configurationId" });
+      const rawOptions = result?.options || [];
+      
+      const newDestinationOptions = Array.isArray(rawOptions)
+        ? rawOptions.map((option) =>
+            typeof option === "string" 
+              ? { label: option, value: option } 
+              : option
+          )
+        : [];
+      setDestinationOptions(newDestinationOptions);
+    } catch (err) {
+      console.error("Error loading destination options:", err);
+    } finally {
+      setDestinationLoading(false);
+    }
+  }, [getDestinationOptions]);
+
+  // Load options on mount
+  useEffect(() => {
+    // Load source options only if no existing mappings
+    if (mappingValue.length === 0) {
+      loadSourceOptions();
+    } else {
+      setSourceOptions(initialSourceOptions);
+    }
+    loadDestinationOptions();
+  }, []);
+
+  // Add new mapping field
+  const handleAddField = () => {
+    const newFieldLabel = `Field ${sourceOptions.length + 1}`;
+    const newSourceOption = {
+      label: newFieldLabel,
+      value: newFieldLabel,
+    };
+
+    setSourceOptions([...sourceOptions, newSourceOption]);
+    
+    const newMappingValue = [
+      ...mappingValue,
+      {
+        label: newFieldLabel,
+        value: "",
+      },
+    ];
+    onChange(newMappingValue);
+  };
+
+  // Remove mapping field
+  const handleRemoveField = (sourceOption: SelectOption, index: number) => {
+    const newSourceOptions = sourceOptions.filter((_, i) => i !== index);
+    setSourceOptions(newSourceOptions);
+
+    const newMappingValue = mappingValue.filter(
+      (mapping) => mapping.label !== sourceOption.label
+    );
+    onChange(newMappingValue);
+  };
+
+  // Update source field label
+  const handleSourceLabelChange = (index: number, sourceOption: SelectOption, newLabel: string) => {
+    const newSourceOptions = [...sourceOptions];
+    newSourceOptions[index] = {
+      ...sourceOption,
+      label: newLabel,
+    };
+    setSourceOptions(newSourceOptions);
+
+    const existingIndex = mappingValue.findIndex(
+      (mapping) => mapping.label === sourceOption.label
+    );
+    if (existingIndex >= 0) {
+      const newMappingValue = [...mappingValue];
+      newMappingValue[existingIndex] = {
+        label: newLabel,
+        value: newMappingValue[existingIndex].value,
+      };
+      onChange(newMappingValue);
+    }
+  };
+
+  // Update destination mapping
+  const handleDestinationChange = (sourceOption: SelectOption, selected: SelectOption | null) => {
+    const existingIndex = mappingValue.findIndex(
+      (mapping) => mapping.label === sourceOption.label
+    );
+
+    let newValue;
+    if (existingIndex >= 0) {
+      // Update existing mapping
+      newValue = [...mappingValue];
+      newValue[existingIndex] = {
+        label: sourceOption.label,
+        value: selected?.value || "",
+      };
+    } else {
+      // Add new mapping
+      newValue = [
+        ...mappingValue,
+        {
+          label: sourceOption.label,
+          value: selected?.value || "",
+        },
+      ];
+    }
+    onChange(newValue);
+  };
+
+  return (
+    <div className="mapping-field-container">
+      {/* Field label and add button */}
+      <div className="mapping-field-header">
+        <label className="field-label">
+          {field.label}
+          {field.required && <span className="required"> *</span>}
+        </label>
+        
+        {selectionConfig?.isAddFields && (
+          <button
+            type="button"
+            onClick={handleAddField}
+            className="add-field-btn"
+          >
+            + Add Field
+          </button>
+        )}
+      </div>
+
+      {/* Loading state */}
+      {sourceLoading ? (
+        <div className="loading-message">Loading source options...</div>
+      ) : sourceOptions.length > 0 ? (
+        /* Mapping rows */
+        sourceOptions.map((sourceOption, index) => (
+          <div key={index} className="mapping-row">
+            {/* Source field (editable if configured) */}
+            <div className="source-field">
+              {selectionConfig?.isEditKeys ? (
+                <EditableLabel
+                  value={sourceOption.label}
+                  onSave={(newLabel) => 
+                    handleSourceLabelChange(index, sourceOption, newLabel)
+                  }
+                />
+              ) : (
+                <span className="source-label">{sourceOption.label}</span>
+              )}
+            </div>
+
+            {/* Arrow separator */}
+            <div className="mapping-arrow">→</div>
+
+            {/* Destination field selector */}
+            <div className="destination-field">
+              <Select
+                value={(() => {
+                  const mapping = mappingValue.find(
+                    (mapping) => mapping.label === sourceOption.label
+                  );
+                  return mapping 
+                    ? destinationOptions.find(
+                        (option) => option.value === mapping.value
+                      ) || null
+                    : null;
+                })()}
+                onChange={(selected) => 
+                  handleDestinationChange(sourceOption, selected)
+                }
+                options={destinationOptions}
+                isLoading={destinationLoading}
+                placeholder="Select destination..."
+                className="destination-select"
+                noOptionsMessage={() => 
+                  destinationLoading 
+                    ? "Loading destination options..." 
+                    : "No destination options found"
+                }
+              />
+            </div>
+
+            {/* Remove field button */}
+            {selectionConfig?.isAddFields && (
+              <button
+                type="button"
+                onClick={() => handleRemoveField(sourceOption, index)}
+                className="remove-field-btn"
+              >
+                🗑️
+              </button>
+            )}
+          </div>
+        ))
+      ) : (
+        <div className="no-options-message">No source options available</div>
+      )}
+
+      {field.description && (
+        <div className="field-description">{field.description}</div>
+      )}
+    </div>
+  );
+}
+```
+
+#### **useFieldOptions Hook for Mapping Fields**
+
+The `useFieldOptions` hook provides specialized functions for mapping fields:
+
+```tsx
+const {
+  // Configuration from field.configs.selection
+  selectionConfig: {
+    isAddFields: boolean;    // Allow adding new source fields
+    isEditKeys: boolean;     // Allow editing source field names
+    source: {               // Source options configuration
+      flowId: string;
+      isSameProject: boolean;
+    };
+    destination: {          // Destination options configuration
+      flowId: string;
+      isSameProject: boolean;
+    };
+  },
+  
+  // Function to load source options
+  getSourceOptions: (context: any) => Promise<OptionsResult>;
+  
+  // Function to load destination options  
+  getDestinationOptions: (context: any) => Promise<OptionsResult>;
+  
+  // Standard field options (for non-mapping fields)
+  options: SelectOption[];
+  loading: boolean;
+  // ... other standard options
+} = useFieldOptions(field);
+```
+
+#### **Mapping Field Usage Example**
+
+```tsx
+function ConfigurationForm({ configurationId }) {
+  const { data: configurationForm } = useConfigurationForm({ configurationId });
+  const [formData, setFormData] = useState({});
+
+  return (
+    <form>
+      {configurationForm?.fields.map((field) => {
+        if (field.type === "mapping") {
+          return (
+            <MappingField
+              key={field.key}
+              field={field}
+              value={formData[field.key] || []}
+              onChange={(value) =>
+                setFormData((prev) => ({ ...prev, [field.key]: value }))
+              }
+            />
+          );
+        }
+        
+        // Handle other field types...
+        return <FormField key={field.key} field={field} />;
+      })}
+    </form>
+  );
+}
+```
+
+#### **Common Mapping Field Use Cases**
+
+1. **CSV Column Mapping**: Map CSV headers to database fields
+2. **API Response Mapping**: Map API response fields to form inputs  
+3. **Data Transformation**: Map source data fields to destination schema
+4. **Integration Field Mapping**: Map fields between different systems (CRM to Email Marketing, etc.)
+
+```tsx
+// Example mapping values for different use cases
+
+// CSV to Database mapping
+const csvMappingValue = [
+  { label: "First Name", value: "user_first_name" },
+  { label: "Last Name", value: "user_last_name" },
+  { label: "Email", value: "user_email" },
+  { label: "Phone", value: "user_phone" }
+];
+
+// API Response to Form mapping  
+const apiMappingValue = [
+  { label: "api_user_id", value: "userId" },
+  { label: "api_user_email", value: "email" },
+  { label: "api_user_profile", value: "profile" }
+];
+```
+
 ### **Generic Form Field Component**
 
 Create a reusable component that handles different field types with proper value handling:
@@ -872,6 +1328,15 @@ function FormField({ field, value, onChange }) {
         />
       );
       
+    case "mapping":
+      return (
+        <MappingField 
+          field={field} 
+          value={value || []} 
+          onChange={onChange}
+        />
+      );
+      
     default:
       return (
         <div className="field-container">

package/dist/{react-core/src/core → core}/provider.d.ts

@@ -1,6 +1,6 @@
 import { QueryClient } from "@tanstack/react-query";
-import { Fastn } from "../../../core/src/index";
-import type { FastnConfig } from "../../../core/src/types";
+import { Fastn } from "@dev-fastn-ai/core";
+import type { FastnConfig } from "@dev-fastn-ai/core";
 export declare const FastnProvider: ({ children, config, queryClient, }: {
     children: React.ReactNode;
     config: FastnConfig;

package/dist/{react-core/src/core → core}/use-configuration-form.d.ts

@@ -1,2 +1,2 @@
 import { GetConfigurationFormInput } from "@dev-fastn-ai/core";
-export declare const useConfigurationForm: (input: GetConfigurationFormInput) => import("@tanstack/react-query").UseQueryResult<import("../../../core/src").ConfigurationForm, Error>;
+export declare const useConfigurationForm: (input: GetConfigurationFormInput) => import("@tanstack/react-query").UseQueryResult<import("@dev-fastn-ai/core").ConfigurationForm, Error>;

package/dist/{react-core/src/core → core}/use-configurations.d.ts

@@ -1,2 +1,2 @@
 import { GetConfigurationsInput } from "@dev-fastn-ai/core";
-export declare const useConfigurations: (input: GetConfigurationsInput) => import("@tanstack/react-query").UseQueryResult<import("../../../core/src").Configuration[], Error>;
+export declare const useConfigurations: (input: GetConfigurationsInput) => import("@tanstack/react-query").UseQueryResult<import("@dev-fastn-ai/core").Configuration[], Error>;

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

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

package/dist/{react-core/src/core → core}/use-field-options.d.ts

@@ -1,4 +1,4 @@
-import type { ConnectorField, SelectOption } from "@dev-fastn-ai/core";
+import type { ConnectorField, SelectOption, OptionsResult } from "@dev-fastn-ai/core";
 /**
  * Custom hook to manage async select field options with search, pagination, and error handling using React Query.
  *
@@ -23,6 +23,9 @@ import type { ConnectorField, SelectOption } from "@dev-fastn-ai/core";
  * ```
  */
 export declare function useFieldOptions(field: ConnectorField): {
+    getSourceOptions: (context: any) => Promise<OptionsResult | null>;
+    getDestinationOptions: (context: any) => Promise<OptionsResult | null>;
+    selectionConfig: any;
     options: SelectOption[];
     loading: boolean;
     loadingMore: boolean;