Fix pre-configured props handling issues v2 (#18872)

* Fix pre-configured props handling in forms

## Issues Fixed

### Issue 1: Remote options not loading with pre-configured values
- **Problem**: When mounting ComponentFormContainer with pre-configured props, remote options dropdowns showed "No options" even though the API returned data
- **Root Cause**: queryDisabledIdx initialization used _configuredProps (empty) instead of actual configuredProps, incorrectly blocking queries. RemoteOptionsContainer also didn't sync cached query data with component state on remount
- **Files**: form-context.tsx, RemoteOptionsContainer.tsx

### Issue 2: Optional props not auto-enabling when pre-configured
- **Problem**: Optional fields with saved values were hidden when switching back to a previously configured component
- **Root Cause**: enabledOptionalProps reset on component change, never re-enabling optional fields that had values
- **File**: form-context.tsx

### Issue 3: Optional prop values lost during state sync
- **Problem**: Optional field values were discarded during the state synchronization effect if the field wasn't enabled
- **Root Cause**: Sync effect skipped disabled optional props entirely
- **File**: form-context.tsx

## Fixes Applied

### form-context.tsx
1. Fixed queryDisabledIdx initialization to use configuredProps instead of _configuredProps
   - Changed dependency from _configuredProps to component.key
   - Ensures blocking index is calculated from actual current values including parent-passed props

2. Added useEffect to auto-enable optional props with values
   - Runs when component key or configurableProps/configuredProps change
   - Automatically enables any optional props that have values in configuredProps
   - Ensures optional fields with saved values are shown on mount

3. Modified sync effect to preserve optional prop values
   - Optional props that aren't enabled still have their values preserved
   - Prevents data loss during state synchronization

### RemoteOptionsContainer.tsx
1. Destructured data from useQuery return
   - Added data to destructured values to track query results

2. Modified queryFn to return pageable object
   - Changed from returning just raw data array to returning full newPageable state object
   - Enables proper state syncing

3. Added useEffect to sync pageable state with query data
   - Handles both fresh API calls and React Query cached returns
   - When cached data is returned, queryFn doesn't run but useEffect syncs the state
   - Ensures options populate correctly on component remount

## Expected Behavior After Fixes

✓ Remote option fields load correctly when mounting with pre-configured values
✓ Dropdown shows fetched options even when using cached data
✓ Optional fields with saved values are automatically enabled and visible
✓ No data loss when switching between components
✓ Smooth component switching with all values and options preserved

🤖 Generated with Claude Code

Co-Authored-By: Claude <[email protected]>

* fix: clear dropdown options when dependent field changes

When a dependent field changes (e.g., Channel Type: "Channels" → "User/Direct Message"),
the Channel dropdown should replace its options instead of accumulating them.

The fix uses page-based logic to determine whether to replace or append options:
- page === 0 (fresh query): Replace options with new data
- page > 0 (pagination): Append options to existing data

When dependent fields change, the useEffect resets page to 0, which triggers
the queryFn to replace options instead of appending. This prevents accumulation
of options from different queries.

Additionally, the allValues Set is reset on fresh queries to ensure deduplication
starts fresh, not carrying over values from the previous query.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* fix: prevent duplicate API calls from race condition in form state

When a field value changes, two /configure API calls were being made:
1. First call with empty configured_props: {}
2. Second call with correct configured_props: {field: value}

Root cause: In setConfiguredProp, updateConfiguredPropsQueryDisabledIdx was called
synchronously, updating queryDisabledIdx state before configuredProps state update
completed. This caused children to re-render twice with mismatched state.

Fix: Move queryDisabledIdx update to a reactive useEffect that watches configuredProps
changes. This ensures both state updates complete before children re-render, preventing
the duplicate API call with stale data.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* fix: handle integer dropdown values and error states properly

Two related fixes to prevent field value loss and crashes:

1. Preserve label-value format for integer props
When integer properties with remoteOptions (like worksheetId) are selected
from dropdowns, the values are stored in label-value format: {__lv: {label, value}}.
The sync effect was incorrectly deleting these values because they weren't
pure numbers. Now preserves __lv format for remote option dropdowns.

2. Return proper pageable structure on error in RemoteOptionsContainer
When /configure returns an error, queryFn was returning [] instead of
the expected pageable object {page, data, prevContext, values}. This caused
pageable.data.map() to crash. Now returns proper structure on error to
prevent crashes and display error message correctly.

Fixes:
- Worksheet ID field no longer resets after dynamic props reload
- No more crash when clearing app field

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* style: fix eslint formatting errors

* fix: add type annotations for PropOptionValue Sets

* fix: handle multi-select integer fields with __lv format

Previously, multi-select integer fields (e.g., Worksheet ID(s)) displayed
"[object Object]" instead of proper labels when populated with pre-configured
values. This occurred because:

1. form-context.tsx only checked for single __lv objects, not arrays
2. ControlSelect.tsx tried to sanitize entire arrays instead of individual items

Changes:
- form-context.tsx: Check for both single __lv objects and arrays of __lv objects
  to preserve multi-select values during sync
- ControlSelect.tsx: Extract array contents from __lv wrapper and map each item
  through sanitizeOption for proper rendering

This completes the fix for pre-configured props handling with remote options.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Code cleanup and PR feedback

* More PR feedback and code cleanup

* Version and changelog

* PR feedback

* Update form-context.tsx

* some code cleanup

* more cleanup

---------

Co-authored-by: Roopak Nijhara <[email protected]>
Co-authored-by: Claude <[email protected]>

Author: 3 people

packages/connect-react/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 # Changelog
 
+## [2.1.1] - 2025-10-27
+
+### Fixed
+
+- Fixed optional props being removed when loading saved configurations
+- Optional props with values now automatically display as enabled
+- Improved handling of label-value format for remote options in multi-select fields
+
 ## [2.1.0] - 2025-10-10
 
 ### Added

packages/connect-react/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipedream/connect-react",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "Pipedream Connect library for React",
   "files": [
     "dist"

packages/connect-react/src/components/ControlSelect.tsx

@@ -16,11 +16,18 @@ import CreatableSelect from "react-select/creatable";
 import type { BaseReactSelectProps } from "../hooks/customization-context";
 import { useCustomize } from "../hooks/customization-context";
 import { useFormFieldContext } from "../hooks/form-field-context";
-import { LabelValueOption } from "../types";
+import type {
+  LabelValueOption,
+  RawPropOption,
+} from "../types";
 import {
   isOptionWithLabel,
   sanitizeOption,
 } from "../utils/type-guards";
+import {
+  isArrayOfLabelValueWrapped,
+  isLabelValueWrapped,
+} from "../utils/label-value";
 import { LoadMoreButton } from "./LoadMoreButton";
 
 // XXX T and ConfigurableProp should be related
@@ -85,15 +92,25 @@ export function ControlSelect<T extends PropOptionValue>({
       return null;
     }
 
+    // Handle __lv-wrapped values (single object or array) returned from remote options
+    if (isLabelValueWrapped<T>(rawValue)) {
+      const lvContent = rawValue.__lv;
+      if (Array.isArray(lvContent)) {
+        return lvContent.map((item) => sanitizeOption<T>(item as RawPropOption<T>));
+      }
+      return sanitizeOption<T>(lvContent as RawPropOption<T>);
+    }
+
+    if (isArrayOfLabelValueWrapped<T>(rawValue)) {
+      return rawValue.map((item) => sanitizeOption<T>(item as RawPropOption<T>));
+    }
+
     if (Array.isArray(rawValue)) {
       // if simple, make lv (XXX combine this with other place this happens)
       if (!isOptionWithLabel(rawValue[0])) {
         return rawValue.map((o) =>
           selectOptions.find((item) => item.value === o) || sanitizeOption(o as T));
       }
-    } else if (rawValue && typeof rawValue === "object" && "__lv" in (rawValue as Record<string, unknown>)) {
-      // Extract the actual option from __lv wrapper and sanitize to LV
-      return sanitizeOption(((rawValue as Record<string, unknown>).__lv) as T);
     } else if (!isOptionWithLabel(rawValue)) {
       const lvOptions = selectOptions?.[0] && isOptionWithLabel(selectOptions[0]);
       if (lvOptions) {

packages/connect-react/src/hooks/form-context.tsx

@@ -36,6 +36,7 @@ import {
 } from "../types";
 import { resolveUserId } from "../utils/resolve-user-id";
 import { isConfigurablePropOfType } from "../utils/type-guards";
+import { hasLabelValueFormat } from "../utils/label-value";
 
 export type AnyFormFieldContext = Omit<FormFieldContext<ConfigurableProp>, "onChange"> & {
   onChange: (value: unknown) => void;
@@ -169,6 +170,7 @@ export const FormContextProvider = <T extends ConfigurableProps>({
   }, [
     component.key,
   ]);
+
   // XXX pass this down? (in case we make it hash or set backed, but then also provide {add,remove} instead of set)
   const optionalPropIsEnabled = (prop: ConfigurableProp) => enabledOptionalProps[prop.name];
 
@@ -354,13 +356,35 @@ export const FormContextProvider = <T extends ConfigurableProps>({
     setErrors(_errors);
   };
 
+  const preserveIntegerValue = (prop: ConfigurableProp, value: unknown) => {
+    if (prop.type !== "integer" || typeof value === "number") {
+      return value;
+    }
+    return hasLabelValueFormat(value)
+      ? value
+      : undefined;
+  };
+
   useEffect(() => {
-    // Initialize queryDisabledIdx on load so that we don't force users
-    // to reconfigure a prop they've already configured whenever the page
-    // or component is reloaded
-    updateConfiguredPropsQueryDisabledIdx(_configuredProps)
+    // Initialize queryDisabledIdx using actual configuredProps (includes parent-passed values in controlled mode)
+    // instead of _configuredProps which starts empty. This ensures that when mounting with pre-configured
+    // values, remote options queries are not incorrectly blocked.
+    updateConfiguredPropsQueryDisabledIdx(configuredProps)
   }, [
-    _configuredProps,
+    component.key,
+    configurableProps,
+    enabledOptionalProps,
+  ]);
+
+  // Update queryDisabledIdx reactively when configuredProps changes.
+  // This prevents race conditions where queryDisabledIdx updates synchronously before
+  // configuredProps completes its state update, causing duplicate API calls with stale data.
+  useEffect(() => {
+    updateConfiguredPropsQueryDisabledIdx(configuredProps);
+  }, [
+    configuredProps,
+    configurableProps,
+    enabledOptionalProps,
   ]);
 
   useEffect(() => {
@@ -386,8 +410,13 @@ export const FormContextProvider = <T extends ConfigurableProps>({
       if (skippablePropTypes.includes(prop.type)) {
         continue;
       }
-      // if prop.optional and not shown, we skip and do on un-collapse
+      // if prop.optional and not shown, we still preserve the value if it exists
+      // This prevents losing saved values for optional props that haven't been enabled yet
       if (prop.optional && !optionalPropIsEnabled(prop)) {
+        const value = configuredProps[prop.name as keyof ConfiguredProps<T>];
+        if (value !== undefined) {
+          newConfiguredProps[prop.name as keyof ConfiguredProps<T>] = value;
+        }
         continue;
       }
       const value = configuredProps[prop.name as keyof ConfiguredProps<T>];
@@ -397,10 +426,14 @@ export const FormContextProvider = <T extends ConfigurableProps>({
           newConfiguredProps[prop.name as keyof ConfiguredProps<T>] = prop.default as any; // eslint-disable-line @typescript-eslint/no-explicit-any
         }
       } else {
-        if (prop.type === "integer" && typeof value !== "number") {
+        // Preserve label-value format from remote options dropdowns for integer props.
+        // Remote options store values as {__lv: {label: "...", value: ...}} (or arrays of __lv objects).
+        // For integer props we drop anything that isn't number or label-value formatted to avoid corrupt data.
+        const preservedValue = preserveIntegerValue(prop, value);
+        if (preservedValue === undefined) {
           delete newConfiguredProps[prop.name as keyof ConfiguredProps<T>];
         } else {
-          newConfiguredProps[prop.name as keyof ConfiguredProps<T>] = value;
+          newConfiguredProps[prop.name as keyof ConfiguredProps<T>] = preservedValue as any; // eslint-disable-line @typescript-eslint/no-explicit-any
         }
       }
     }
@@ -409,6 +442,8 @@ export const FormContextProvider = <T extends ConfigurableProps>({
     }
   }, [
     configurableProps,
+    enabledOptionalProps,
+    configuredProps,
   ]);
 
   // clear all props on user change
@@ -440,9 +475,6 @@ export const FormContextProvider = <T extends ConfigurableProps>({
     if (prop.reloadProps) {
       setReloadPropIdx(idx);
     }
-    if (prop.type === "app" || prop.remoteOptions) {
-      updateConfiguredPropsQueryDisabledIdx(newConfiguredProps);
-    }
     const errs = propErrors(prop, value);
     const newErrors = {
       ...errors,
@@ -478,6 +510,23 @@ export const FormContextProvider = <T extends ConfigurableProps>({
     setEnabledOptionalProps(newEnabledOptionalProps);
   };
 
+  // Auto-enable optional props with saved values so dependent dynamic props reload correctly
+  useEffect(() => {
+    for (const prop of configurableProps) {
+      if (!prop.optional) continue;
+      if (enabledOptionalProps[prop.name]) continue;
+      const value = configuredProps[prop.name as keyof ConfiguredProps<T>];
+      if (value === undefined) continue;
+      optionalPropSetEnabled(prop, true);
+    }
+  }, [
+    component.key,
+    configurableProps,
+    configuredProps,
+    enabledOptionalProps,
+    optionalPropSetEnabled,
+  ]);
+
   const checkPropsNeedConfiguring = () => {
     const _propsNeedConfiguring = []
     for (const prop of configurableProps) {

packages/connect-react/src/utils/label-value.ts

@@ -0,0 +1,50 @@
+import type { PropOptionValue } from "@pipedream/sdk";
+import type { RawPropOption } from "../types";
+
+/**
+ * Utilities for detecting and handling label-value (__lv) format
+ * used by Pipedream components to preserve display labels for option values.
+ */
+
+/**
+ * Shape returned by remote options when values include their original label.
+ * The wrapped payload may itself be a single option or an array of options.
+ */
+export type LabelValueWrapped<T extends PropOptionValue = PropOptionValue> = Extract<RawPropOption<T>, { __lv: unknown }>;
+
+/**
+ * Runtime type guard for the label-value wrapper.
+ * @param value - The value to check
+ * @returns true if value is an object with a non-null __lv payload
+ */
+export function isLabelValueWrapped<T extends PropOptionValue = PropOptionValue>(
+  value: unknown,
+): value is LabelValueWrapped<T> {
+  if (!value || typeof value !== "object") return false;
+  if (!("__lv" in value)) return false;
+
+  const lvContent = (value as LabelValueWrapped<T>).__lv;
+  return lvContent != null;
+}
+
+/**
+ * Checks if every entry in an array is a label-value wrapper.
+ * @param value - The value to check
+ * @returns true if all entries are wrapped and contain non-null payloads
+ */
+export function isArrayOfLabelValueWrapped<T extends PropOptionValue = PropOptionValue>(
+  value: unknown,
+): value is Array<LabelValueWrapped<T>> {
+  if (!Array.isArray(value) || value.length === 0) return false;
+
+  return value.every((item) => isLabelValueWrapped<T>(item));
+}
+
+/**
+ * Checks if a value has the label-value format (either single or array)
+ * @param value - The value to check
+ * @returns true if value is in __lv format (single or array)
+ */
+export function hasLabelValueFormat(value: unknown): boolean {
+  return isLabelValueWrapped(value) || isArrayOfLabelValueWrapped(value);
+}