fix(Field): id generation (#824)

tenphi · web-flow · commit e88acca3b7dc · 2025-10-16T10:46:13.000+02:00
diff --git a/.changeset/mighty-mails-float.md b/.changeset/mighty-mails-float.md
@@ -0,0 +1,5 @@
+---
+"@cube-dev/ui-kit": patch
+---
+
+Generate id even for input components that are not connected to a form.
diff --git a/.changeset/quick-tools-kiss.md b/.changeset/quick-tools-kiss.md
@@ -0,0 +1,5 @@
+---
+"@cube-dev/ui-kit": patch
+---
+
+Prevent form prop from leaking to the DOM.
diff --git a/.cursor/rules/coding.mdc b/.cursor/rules/coding.mdc
@@ -14,3 +14,6 @@ alwaysApply: true
 
 - Use named imports from react (like `useCallback`) instead of using the `React` instance. Avoid: `React.useCallback`.
 - Prefer stable `useEvent` callbacks when it's possible.
+
+# Knowledge rules
+- If you find any essential knowledge that is not yet listed anywhere, then add it to Claude.md file in the nearest folder this knowledge applies to. Create file if it's not yet exist. Make sure this essential knowledge is as compact as possible.
diff --git a/src/components/fields/Checkbox/Checkbox.tsx b/src/components/fields/Checkbox/Checkbox.tsx
@@ -142,6 +142,7 @@ function Checkbox(
     labelPosition,
     inputStyles,
     isHidden,
+    form,
     ...otherProps
   } = props;
 
diff --git a/src/components/fields/Checkbox/CheckboxGroup.tsx b/src/components/fields/Checkbox/CheckboxGroup.tsx
@@ -82,6 +82,7 @@ function CheckboxGroup(props: WithNullableValue<CubeCheckboxGroupProps>, ref) {
     labelProps: baseLabelProps,
     labelSuffix,
     inputStyles,
+    form,
     ...otherProps
   } = props;
   let domRef = useDOMRef(ref);
diff --git a/src/components/fields/ComboBox/ComboBox.tsx b/src/components/fields/ComboBox/ComboBox.tsx
@@ -8,7 +8,6 @@ import React, {
   RefObject,
   useCallback,
   useEffect,
-  useId,
   useMemo,
   useRef,
   useState,
@@ -1031,13 +1030,10 @@ export const ComboBox = forwardRef(function ComboBox<T extends object>(
     onFocus,
     onBlur,
     onKeyDown,
+    form,
     ...otherProps
   } = props;
 
-  // Generate ID for label-input linking if not provided
-  const generatedId = useId();
-  const inputId = id || generatedId;
-
   // Generate a unique ID for this combobox instance
   const comboBoxId = useMemo(() => generateRandomId(), []);
 
@@ -1580,7 +1576,7 @@ export const ComboBox = forwardRef(function ComboBox<T extends object>(
       {prefix ? <div data-element="Prefix">{prefix}</div> : null}
       <ComboBoxInput
         inputRef={inputRef}
-        id={inputId}
+        id={id}
         value={effectiveInputValue}
         placeholder={placeholder}
         isDisabled={isDisabled}
@@ -1688,7 +1684,6 @@ export const ComboBox = forwardRef(function ComboBox<T extends object>(
   const finalProps = {
     ...propsWithoutChildren,
     styles: fieldStyles,
-    labelProps: { ...props.labelProps, for: inputId },
   };
 
   return wrapWithField<Omit<CubeComboBoxProps<T>, 'children'>>(
diff --git a/src/components/fields/FileInput/FileInput.tsx b/src/components/fields/FileInput/FileInput.tsx
@@ -174,6 +174,7 @@ function FileInput(props: CubeFileInputProps, ref) {
     type = 'file',
     inputProps,
     accept,
+    form,
     ...otherProps
   } = props;
 
diff --git a/src/components/fields/FilterListBox/FilterListBox.tsx b/src/components/fields/FilterListBox/FilterListBox.tsx
@@ -6,7 +6,6 @@ import React, {
   ReactNode,
   RefObject,
   useCallback,
-  useId,
   useLayoutEffect,
   useMemo,
   useRef,
@@ -276,13 +275,10 @@ export const FilterListBox = forwardRef(function FilterListBox<
     searchValue: controlledSearchValue,
     onSearchChange,
     _internalCollection,
+    form,
     ...otherProps
   } = props;
 
-  // Generate ID for label-input linking if not provided
-  const generatedId = useId();
-  const inputId = id || generatedId;
-
   // Preserve the original `children` (may be a render function) before we
   // potentially overwrite it.
   let children: ReactNode = renderChildren as ReactNode;
@@ -909,7 +905,7 @@ export const FilterListBox = forwardRef(function FilterListBox<
       )}
       <SearchInputElement
         ref={searchInputRef}
-        id={inputId}
+        id={id}
         data-is-prefix={isLoading ? '' : undefined}
         type="search"
         placeholder={searchPlaceholder}
@@ -1006,14 +1002,6 @@ export const FilterListBox = forwardRef(function FilterListBox<
 
   const finalProps = { ...props, styles: undefined };
 
-  // Ensure labelProps has the for attribute for label-input linking
-  if (!finalProps.labelProps) {
-    finalProps.labelProps = {};
-  }
-  if (!finalProps.labelProps.for) {
-    finalProps.labelProps.for = inputId;
-  }
-
   return wrapWithField<Omit<CubeFilterListBoxProps<T>, 'children'>>(
     filterListBoxField,
     ref,
diff --git a/src/components/fields/FilterPicker/FilterPicker.tsx b/src/components/fields/FilterPicker/FilterPicker.tsx
@@ -7,7 +7,6 @@ import {
   RefObject,
   useCallback,
   useEffect,
-  useId,
   useMemo,
   useRef,
   useState,
@@ -250,6 +249,7 @@ export const FilterPicker = forwardRef(function FilterPicker<T extends object>(
     searchValue,
     onSearchChange,
     sortSelectedToTop: sortSelectedToTopProp,
+    form,
     ...otherProps
   } = props;
 
@@ -260,10 +260,6 @@ export const FilterPicker = forwardRef(function FilterPicker<T extends object>(
 
   styles = extractStyles(otherProps, PROP_STYLES, styles);
 
-  // Generate ID for label-trigger linking if not provided
-  const generatedId = useId();
-  const triggerId = id || generatedId;
-
   // Generate a unique ID for this FilterPicker instance
   const filterPickerId = useMemo(() => generateRandomId(), []);
 
@@ -727,7 +723,7 @@ export const FilterPicker = forwardRef(function FilterPicker<T extends object>(
       <ItemButton
         ref={triggerRef as any}
         data-popover-trigger
-        id={triggerId}
+        id={id}
         type={type}
         theme={validationState === 'invalid' ? 'danger' : theme}
         size={size}
@@ -952,14 +948,6 @@ export const FilterPicker = forwardRef(function FilterPicker<T extends object>(
     styles: undefined,
   };
 
-  // Ensure labelProps has the for attribute for label-trigger linking
-  if (!finalProps.labelProps) {
-    finalProps.labelProps = {};
-  }
-  if (!finalProps.labelProps.for) {
-    finalProps.labelProps.for = triggerId;
-  }
-
   return wrapWithField<Omit<CubeFilterPickerProps<T>, 'children' | 'tooltip'>>(
     filterPickerField,
     ref as any,
diff --git a/src/components/fields/LegacyComboBox/LegacyComboBox.tsx b/src/components/fields/LegacyComboBox/LegacyComboBox.tsx
@@ -208,6 +208,7 @@ export const LegacyComboBox = forwardRef(function LegacyComboBox<
     selectedKey,
     defaultSelectedKey,
     isClearable,
+    form,
     ...otherProps
   } = props;
 
diff --git a/src/components/fields/ListBox/ListBox.tsx b/src/components/fields/ListBox/ListBox.tsx
@@ -10,7 +10,6 @@ import {
   ReactNode,
   RefObject,
   useEffect,
-  useId,
   useLayoutEffect,
   useMemo,
   useRef,
@@ -499,13 +498,10 @@ export const ListBox = forwardRef(function ListBox<T extends object>(
     showSelectAll,
     selectAllLabel,
     allValueProps,
+    form,
     ...otherProps
   } = props;
 
-  // Generate ID for label-listbox linking if not provided
-  const generatedId = useId();
-  const listBoxId = id || generatedId;
-
   const [, forceUpdate] = useState({});
   const lastSelectedKeyRef = useRef<Key | null>(null);
 
@@ -717,7 +713,7 @@ export const ListBox = forwardRef(function ListBox<T extends object>(
   const { listBoxProps } = useListBox(
     {
       ...props,
-      id: listBoxId,
+      id: id,
       'aria-label': props['aria-label'] || label?.toString(),
       isDisabled,
       shouldUseVirtualFocus: shouldUseVirtualFocus ?? false,
@@ -995,14 +991,6 @@ export const ListBox = forwardRef(function ListBox<T extends object>(
 
   const finalProps = { ...props, styles: undefined };
 
-  // Ensure labelProps has the for attribute for label-listbox linking
-  if (!finalProps.labelProps) {
-    finalProps.labelProps = {};
-  }
-  if (!finalProps.labelProps.for) {
-    finalProps.labelProps.for = listBoxId;
-  }
-
   return wrapWithField<Omit<CubeListBoxProps<T>, 'children'>>(
     listBoxField,
     ref,
diff --git a/src/components/fields/RadioGroup/Radio.tsx b/src/components/fields/RadioGroup/Radio.tsx
@@ -186,6 +186,7 @@ function Radio(props: CubeRadioProps, ref) {
     inputStyles,
     type = 'radio',
     'aria-label': ariaLabel,
+    form,
     ...otherProps
   } = props;
 
diff --git a/src/components/fields/RadioGroup/RadioGroup.tsx b/src/components/fields/RadioGroup/RadioGroup.tsx
@@ -84,6 +84,7 @@ function RadioGroup(props: WithNullableValue<CubeRadioGroupProps>, ref) {
     insideForm,
     labelProps: baseLabelProps,
     isSolid,
+    form,
     ...otherProps
   } = props;
   let domRef = useDOMRef(ref);
diff --git a/src/components/fields/Select/Select.tsx b/src/components/fields/Select/Select.tsx
@@ -281,6 +281,7 @@ function Select<T extends object>(
     labelSuffix,
     suffixPosition = 'before',
     isClearable,
+    form,
     ...otherProps
   } = props;
   let state = useSelectState(props);
diff --git a/src/components/fields/Slider/SliderBase.tsx b/src/components/fields/Slider/SliderBase.tsx
@@ -74,6 +74,7 @@ function SliderBase(allProps: SliderBaseProps, ref: DOMRef<HTMLDivElement>) {
     children,
     showValueLabel = true,
     orientation: formOrientation,
+    form,
     ...otherProps
   } = props;
 
diff --git a/src/components/fields/Switch/Switch.tsx b/src/components/fields/Switch/Switch.tsx
@@ -159,6 +159,7 @@ function Switch(props: WithNullableSelected<CubeSwitchProps>, ref) {
     fieldStyles,
     validationState,
     size = 'medium',
+    form,
   } = props;
 
   const id = useId(props.id);
diff --git a/src/components/fields/TextInput/TextInputBase.tsx b/src/components/fields/TextInput/TextInputBase.tsx
@@ -262,6 +262,7 @@ function _TextInputBase(props: CubeTextInputBaseProps, ref) {
     icon,
     maxLength,
     minLength,
+    form,
     ...otherProps
   } = props;
 
@@ -367,7 +368,6 @@ function _TextInputBase(props: CubeTextInputBaseProps, ref) {
         as={ElementType}
         {...mergeProps(inputProps, focusProps, hoverProps)}
         ref={inputRef}
-        form={null}
         rows={multiLine ? rows : undefined}
         mods={modifiers}
         style={textSecurityStyles}
diff --git a/src/components/fields/TextInputMapper/TextInputMapper.tsx b/src/components/fields/TextInputMapper/TextInputMapper.tsx
@@ -98,6 +98,7 @@ function TextInputMapper(
     KeyComponent,
     ValueComponent,
     size = 'medium',
+    form,
   } = props;
 
   function extractLocalValues(
diff --git a/src/components/form/Claude.md b/src/components/form/Claude.md
@@ -0,0 +1,55 @@
+# Form System Essential Knowledge
+
+## ID Generation and Field Connection
+
+### useFieldProps Behavior
+
+`useFieldProps` handles ID generation and label-input connection automatically. It has **two distinct modes**:
+
+#### 1. Form-Connected Fields (with `name` prop)
+- Calls `useField` for full form integration
+- Generates unique IDs using the `createId` mechanism based on field name
+- Manages form state, validation, onChange/onBlur handlers
+- Example: `<TextInput name="email" />` inside a `<Form>`
+
+#### 2. Standalone Fields (no `name` prop)
+- **Does NOT call `useField`** to avoid interference with controlled component behavior
+- Uses React's `useId()` to generate IDs directly
+- Preserves original props including `value` and `onChange` handlers
+- Example: `<RadioGroup value={state} onChange={setState} />` without `name`
+
+### Critical Rule: Don't Call useField for Standalone Fields
+
+**Why**: Calling `useField` for standalone fields creates state management and side effects that interfere with controlled component behavior. This breaks components like RadioGroup in controlled mode.
+
+### Label-Input Connection
+
+`useFieldProps` automatically sets `labelProps.for` to match the field's ID when an ID exists. This ensures proper accessibility and label clicking behavior.
+
+**Components should NOT manually set**:
+- `labelProps.for` 
+- Generate their own IDs using `useId()`
+
+This is handled centrally by `useFieldProps`.
+
+## Field Component Pattern
+
+```tsx
+function MyField(props) {
+  props = useProviderProps(props);
+  props = useFormProps(props);
+  props = useFieldProps(props, { defaultValidationTrigger: 'onBlur' });
+  
+  // Now props.id is set (if needed) and props.labelProps.for matches it
+  // Just use props.id directly, don't generate your own
+  
+  return <input id={props.id} {...otherProps} />;
+}
+```
+
+## ID Generation Examples
+
+- Form field: `username` → `username`, `username_1`, `username_2` (incremental)
+- Standalone: `undefined` → `react-aria-123` (React's useId format)
+- Explicit ID: Always preserved as-is
+
diff --git a/src/components/form/Form/use-field/use-field-props.tsx b/src/components/form/Form/use-field/use-field-props.tsx
@@ -1,4 +1,4 @@
-import { useDebugValue, useRef } from 'react';
+import { useDebugValue, useId, useRef } from 'react';
 
 import { useChainedCallback, useEvent } from '../../../../_internal/index';
 import { mergeProps } from '../../../../utils/react/index';
@@ -54,14 +54,31 @@ export function useFieldProps<
     );
   }
 
-  if (
-    isInsideLegacyField ||
-    isDisabledRef.current === true ||
-    props.name == null
-  ) {
+  if (isInsideLegacyField || isDisabledRef.current === true) {
     return props;
   }
 
+  // For standalone fields (no name), just generate an ID without calling useField
+  const hasName = props.name != null;
+  const generatedId = useId();
+
+  if (!hasName) {
+    // Standalone field - just add generated ID if not provided
+    if (!props.id) {
+      const result = { ...props, id: generatedId };
+
+      if (result.id && !result.labelProps) {
+        result.labelProps = { for: result.id };
+      } else if (result.id && result.labelProps && !result.labelProps.for) {
+        result.labelProps = { ...result.labelProps, for: result.id };
+      }
+
+      return result as Props;
+    }
+    return props;
+  }
+
+  // Form-connected field - use full useField logic
   const field = useField<T, Props>(props, {
     defaultValidationTrigger: params.defaultValidationTrigger,
   });
diff --git a/src/shared/form.ts b/src/shared/form.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@cube-dev/ui-kit": patch
 +---
++
 +Generate id even for input components that are not connected to a form.