@ceed/cds 1.24.1-next.3 → 1.26.0

package/dist/components/inputs/Autocomplete.md

@@ -8,10 +8,36 @@ Autocomplete is an enhanced input component that provides real-time suggestions
 <Autocomplete options={['Option1', 'Option2']} />
 ```
 
-| Field   | Description | Default |
-| ------- | ----------- | ------- |
-| label   | —           | —       |
-| loading | —           | —       |
+| Field                 | Description | Default |
+| --------------------- | ----------- | ------- |
+| variant               | —           | —       |
+| color                 | —           | —       |
+| size                  | —           | —       |
+| placeholder           | —           | —       |
+| label                 | —           | —       |
+| helperText            | —           | —       |
+| error                 | —           | —       |
+| required              | —           | —       |
+| disabled              | —           | —       |
+| readOnly              | —           | —       |
+| multiple              | —           | —       |
+| freeSolo              | —           | —       |
+| disableClearable      | —           | —       |
+| autoHighlight         | —           | —       |
+| clearOnEscape         | —           | —       |
+| disableCloseOnSelect  | —           | —       |
+| openOnFocus           | —           | —       |
+| blurOnSelect          | —           | —       |
+| filterSelectedOptions | —           | —       |
+| selectOnFocus         | —           | —       |
+| clearOnBlur           | —           | —       |
+| forcePopupIcon        | —           | —       |
+| loading               | —           | —       |
+| noOptionsText         | —           | —       |
+| loadingText           | —           | —       |
+| limitTags             | —           | —       |
+| value                 | —           | —       |
+| defaultValue          | —           | —       |
 
 > ⚠️ **Usage Warning** ⚠️
 >
@@ -22,6 +48,11 @@ Autocomplete is an enhanced input component that provides real-time suggestions
 > - **Dropdown**: For action menus, not form value selection
 > - **Input**: For free-text entry without predefined options
 
+> 💡 **Use built-in form props**
+>
+> This component natively supports form elements such as `label` and `helperText` props.
+> When building forms, use these built-in props instead of manually composing labels and helper text with Typography.
+
 ## Usage
 
 ```tsx
@@ -42,17 +73,19 @@ function CountrySelector() {
 }
 ```
 
-## Examples
-
-### Playground
+## Variants
 
-Interactive example with basic string options.
+The `variant` prop controls the visual style of the autocomplete input. Available variants: `outlined` (default), `soft`, `solid`, `plain`.
 
 ```tsx
-<Autocomplete options={['Option1', 'Option2']} />
+<Stack gap={2} p={2}>
+  {variants.map(variant => <Autocomplete key={variant} variant={variant} options={sampleOptions} placeholder={variant} label={variant} sx={{
+    maxWidth: 300
+  }} />)}
+</Stack>
 ```
 
-### Sizes
+## Sizes
 
 Available size options: `sm`, `md`, `lg`.
 
@@ -67,7 +100,139 @@ Available size options: `sm`, `md`, `lg`.
 </div>
 ```
 
-### Option Groups
+## Colors
+
+The `color` prop changes the color scheme. Available colors: `primary`, `neutral`, `danger`, `success`, `warning`.
+
+```tsx
+<Stack gap={2} p={2}>
+  {colors.map(color => <Autocomplete key={color} color={color} options={sampleOptions} defaultValue="Apple" label={color} sx={{
+    maxWidth: 300
+  }} />)}
+</Stack>
+```
+
+## States
+
+Autocomplete supports several form states for different interaction contexts.
+
+### Disabled
+
+A disabled autocomplete cannot be focused or interacted with. Use for fields that are temporarily unavailable.
+
+### Read Only
+
+A read-only autocomplete can be focused and its value copied, but cannot be changed. Use when a value should be visible but not editable.
+
+### Error
+
+Set `error` along with `helperText` to indicate validation failures.
+
+### Required
+
+Set `required` to mark the field as required in a form.
+
+```tsx
+<Stack gap={3} p={2} sx={{
+  maxWidth: 300
+}}>
+<Autocomplete label="Disabled" options={sampleOptions} defaultValue="Apple" disabled />
+<Autocomplete label="Read Only" options={sampleOptions} defaultValue="Banana" readOnly />
+<Autocomplete label="Error" options={sampleOptions} error helperText="This field is required" />
+<Autocomplete label="Required" options={sampleOptions} required placeholder="Select a fruit..." />
+</Stack>
+```
+
+## Free Solo
+
+The `freeSolo` prop allows users to type arbitrary values that are not in the options list. This is useful for inputs where the user can either pick a suggestion or enter a custom value.
+
+> ⚠️ **Known limitation**: The component's internal `handleChange` accesses `newValue.value`, which is `undefined` for raw strings in freeSolo mode. Typed arbitrary values may not propagate correctly through `onChange`. Consider using `onInputChange` as an alternative for capturing free-text input.
+
+```tsx
+<Stack gap={2} p={2} sx={{
+  maxWidth: 300
+}}>
+<Autocomplete label="Free Solo" options={sampleOptions} freeSolo placeholder="Type anything..." value={value} onChange={e => setValue(e.target.value)} />
+<Typography level="body-sm" textColor="text.tertiary">
+  Current value: {value ?? '(empty)'}
+</Typography>
+<Typography level="body-xs" textColor="text.tertiary">
+  Note: freeSolo allows arbitrary text input. However, the component&apos;s onChange handler accesses
+  newValue.value which is undefined for raw strings, so typed values may not propagate correctly.
+</Typography>
+</Stack>
+```
+
+## Disable Clearable
+
+Set `disableClearable` to hide the clear (X) button. This forces the user to always have a selection.
+
+```tsx
+<Autocomplete
+  options={sampleOptions}
+  defaultValue="Cherry"
+  disableClearable
+  label="Disable Clearable"
+  sx={{
+  maxWidth: 300
+}}
+/>
+```
+
+## Custom Texts
+
+Customize the messages shown when there are no matching options or while loading.
+
+```tsx
+<Stack gap={3} direction="row" p={2}>
+  <Autocomplete label="Custom No Options Text" options={[]} noOptionsText="No fruits found — try a different search" placeholder="Search fruits..." sx={{
+    minWidth: 280
+  }} />
+  <Autocomplete label="Custom Loading Text" options={[]} loading loadingText="Fetching fruits from the orchard..." placeholder="Loading fruits..." sx={{
+    minWidth: 280
+  }} />
+</Stack>
+```
+
+## Multiple Selection
+
+Enable `multiple` to allow selecting more than one option. Selected values are shown as chips.
+
+```tsx
+<div style={{
+  display: 'flex',
+  flexDirection: 'column',
+  gap: '10px'
+}}>
+<Autocomplete {...args} size="sm" />
+<Autocomplete {...args} size="md" />
+<Autocomplete {...args} size="lg" />
+</div>
+```
+
+### Limit Tags
+
+In multiple mode, use `limitTags` to control how many tags are visible before truncating. Use `filterSelectedOptions` to hide already-selected options from the dropdown.
+
+> 💡 The component uses a custom `renderTags` implementation. JoyUI's `limitTags` truncates the array passed to `renderTags`, so tags will be limited, but the default "+N more" indicator text may not appear.
+
+```tsx
+<Stack gap={3} p={2} sx={{
+  maxWidth: 400
+}}>
+<Stack gap={1}>
+  <Typography level="title-sm">limitTags=2</Typography>
+  <Autocomplete multiple options={sampleOptions} defaultValue={['Apple', 'Banana', 'Cherry', 'Date']} limitTags={2} label="Limit Tags" />
+</Stack>
+<Stack gap={1}>
+  <Typography level="title-sm">filterSelectedOptions</Typography>
+  <Autocomplete multiple options={sampleOptions} defaultValue={['Apple', 'Banana']} filterSelectedOptions label="Filter Selected Options" />
+</Stack>
+</Stack>
+```
+
+## Option Groups
 
 Group options into categories using the `groupBy` function.
 
@@ -95,7 +260,7 @@ Group options into categories using the `groupBy` function.
 />
 ```
 
-### Custom Options
+## Custom Options
 
 Options can include decorators for rich content display.
 
@@ -116,7 +281,28 @@ Options can include decorators for rich content display.
 />
 ```
 
-### Loading State
+## Secondary Text
+
+Options can display a secondary line of text using the `secondaryText` property. This is useful for showing additional context like emails, phone numbers, or descriptions alongside the main label.
+
+```tsx
+<Stack gap={4} direction="row" alignItems="flex-start" p={2}>
+  {sizes.map(size => <Stack key={size} gap={1}>
+  <span style={{
+    color: '#6366f1',
+    fontSize: 12
+  }}>{size}</span>
+  <Autocomplete placeholder="Placeholder" options={optionsWithSecondaryText} value={values[size]} onChange={e => setValues(prev => ({
+    ...prev,
+    [size]: e.target.value
+  }))} sx={{
+    minWidth: 200
+  }} size={size} />
+</Stack>)}
+</Stack>
+```
+
+## Loading State
 
 Show a loading indicator while fetching options.
 
@@ -127,6 +313,8 @@ Show a loading indicator while fetching options.
 />
 ```
 
+## Controlled / Uncontrolled
+
 ### Controlled
 
 Manage value externally with controlled state.
@@ -153,6 +341,67 @@ Manage value externally with controlled state.
 </Stack>
 ```
 
+### Uncontrolled
+
+Let the component manage its own state with `defaultValue`.
+
+```tsx
+<Autocomplete
+  options={['Uncontrolled', 'Controlled']}
+  label="Component Type"
+  defaultValue="Controlled"
+/>
+```
+
+## Virtualization
+
+Autocomplete automatically virtualizes long option lists for performance. This example renders 1,000 options efficiently.
+
+```tsx
+<Autocomplete
+  options={(() => {
+  const res: any[] = [];
+  for (let i = 0; i < 1000; i++) {
+    res.push(i);
+  }
+  return res;
+})()}
+/>
+```
+
+## Behavior Props
+
+These boolean props fine-tune interaction behavior. Toggle them in the Controls panel below to see their effects.
+
+| Prop                   | Default  | Effect                                                         |
+| ---------------------- | -------- | -------------------------------------------------------------- |
+| `autoHighlight`        | `false`  | Automatically highlights the first option when the popup opens |
+| `clearOnEscape`        | `false`  | Clears the input value when the Escape key is pressed          |
+| `disableCloseOnSelect` | `false`  | Keeps the popup open after selecting an option                 |
+| `openOnFocus`          | `false`  | Opens the popup when the input receives focus                  |
+| `blurOnSelect`         | `false`  | Blurs the input after an option is selected                    |
+| `selectOnFocus`        | `false`  | Selects all input text when the input is focused               |
+| `clearOnBlur`          | `true`   | Clears the input text on blur if it doesn't match any option   |
+| `forcePopupIcon`       | `'auto'` | Controls whether the popup icon is always shown                |
+
+```tsx
+<Autocomplete
+  options={sampleOptions}
+  label="Behavior Props"
+  placeholder="Toggle props in the Controls panel..."
+  autoHighlight={false}
+  clearOnEscape={false}
+  disableCloseOnSelect={false}
+  openOnFocus={false}
+  blurOnSelect={false}
+  selectOnFocus={false}
+  clearOnBlur
+  sx={{
+  maxWidth: 400
+}}
+/>
+```
+
 ## When to Use
 
 ### ✅ Good Use Cases
@@ -227,7 +476,7 @@ function UserSearch({ onSelect }) {
             label: user.name,
             secondaryText: user.email,
             startDecorator: <Avatar src={user.avatar} size="sm" />,
-          }))
+          })),
         );
       } finally {
         setLoading(false);
@@ -304,7 +553,7 @@ function AddressAutocomplete({ onAddressSelect }) {
           value: result.placeId,
           label: result.formattedAddress,
           secondaryText: result.city + ', ' + result.country,
-        }))
+        })),
       );
     } finally {
       setLoading(false);
@@ -396,13 +645,7 @@ function ContactSelector() {
     { value: 'michael', label: 'Michael Chen', secondaryText: '(646) 555-0876' },
   ];
 
-  return (
-    <Autocomplete
-      label="Contact"
-      placeholder="Search contacts..."
-      options={contacts}
-    />
-  );
+  return <Autocomplete label="Contact" placeholder="Search contacts..." options={contacts} />;
 }
 ```
 
@@ -443,30 +686,46 @@ function LazyAutocomplete({ fetchOptions }) {
 
 ### Key Props
 
-| Prop            | Type                                     | Default | Description                           |
-| --------------- | ---------------------------------------- | ------- | ------------------------------------- |
-| `options`       | `string[] \| OptionObject[]`             | `[]`    | Array of options (strings or objects) |
-| `value`         | `string \| string[]`                     | -       | Selected value(s) for controlled mode |
-| `defaultValue`  | `string \| string[]`                     | -       | Initial value for uncontrolled mode   |
-| `onChange`      | `(event: { target: { value } }) => void` | -       | Callback when selection changes       |
-| `onInputChange` | `(event: { target: { value } }) => void` | -       | Callback when input text changes      |
-| `label`         | `string`                                 | -       | Label text above the input            |
-| `placeholder`   | `string`                                 | -       | Placeholder text when empty           |
-| `loading`       | `boolean`                                | `false` | Show loading indicator                |
-| `multiple`      | `boolean`                                | `false` | Allow multiple selections             |
-| `groupBy`       | `(option) => string`                     | -       | Function to group options             |
-| `size`          | `'sm' \| 'md' \| 'lg'`                   | `'md'`  | Input size                            |
-| `disabled`      | `boolean`                                | `false` | Disable the input                     |
+| Prop                    | Type                                                           | Default        | Description                                           |
+| ----------------------- | -------------------------------------------------------------- | -------------- | ----------------------------------------------------- |
+| `options`               | `string[] \| OptionObject[]`                                   | `[]`           | Array of options (strings or objects)                 |
+| `value`                 | `string \| string[]`                                           | -              | Selected value(s) for controlled mode                 |
+| `defaultValue`          | `string \| string[]`                                           | -              | Initial value for uncontrolled mode                   |
+| `onChange`              | `(event: { target: { value } }) => void`                       | -              | Callback when selection changes                       |
+| `onInputChange`         | `(event: { target: { value } }) => void`                       | -              | Callback when input text changes                      |
+| `label`                 | `ReactNode`                                                    | -              | Label text above the input                            |
+| `placeholder`           | `string`                                                       | -              | Placeholder text when empty                           |
+| `loading`               | `boolean`                                                      | `false`        | Show loading indicator                                |
+| `multiple`              | `boolean`                                                      | `false`        | Allow multiple selections                             |
+| `groupBy`               | `(option) => string`                                           | -              | Function to group options                             |
+| `size`                  | `'sm' \| 'md' \| 'lg'`                                         | `'md'`         | Input size                                            |
+| `variant`               | `'outlined' \| 'soft' \| 'solid' \| 'plain'`                   | `'outlined'`   | Visual style variant                                  |
+| `color`                 | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'neutral'`    | Color scheme                                          |
+| `disabled`              | `boolean`                                                      | `false`        | Disable the input                                     |
+| `readOnly`              | `boolean`                                                      | `false`        | Make the input read-only (focusable but not editable) |
+| `required`              | `boolean`                                                      | `false`        | Mark the field as required                            |
+| `error`                 | `boolean`                                                      | `false`        | Indicate an error state                               |
+| `helperText`            | `ReactNode`                                                    | -              | Helper text below the input                           |
+| `freeSolo`              | `boolean`                                                      | `false`        | Allow arbitrary values not in the options list        |
+| `disableClearable`      | `boolean`                                                      | `false`        | Hide the clear (X) button                             |
+| `noOptionsText`         | `ReactNode`                                                    | `'No options'` | Text when no options match                            |
+| `loadingText`           | `ReactNode`                                                    | `'Loading…'`   | Text while loading                                    |
+| `limitTags`             | `number`                                                       | `-1`           | Max visible tags in multiple mode (-1 for unlimited)  |
+| `autoHighlight`         | `boolean`                                                      | `false`        | Auto-highlight first option                           |
+| `clearOnEscape`         | `boolean`                                                      | `false`        | Clear value on Escape key                             |
+| `disableCloseOnSelect`  | `boolean`                                                      | `false`        | Keep popup open after selection                       |
+| `openOnFocus`           | `boolean`                                                      | `false`        | Open popup on focus                                   |
+| `filterSelectedOptions` | `boolean`                                                      | `false`        | Hide selected options from dropdown (multiple mode)   |
 
 ### Option Object Structure
 
 ```tsx
 interface OptionObject {
-  value: string;              // Unique value identifier
-  label: string;              // Display text
-  secondaryText?: string;     // Secondary line of text
+  value: string; // Unique value identifier
+  label: string; // Display text
+  secondaryText?: string; // Secondary line of text
   startDecorator?: ReactNode; // Content before label
-  endDecorator?: ReactNode;   // Content after label
+  endDecorator?: ReactNode; // Content after label
 }
 
 // Example option objects
@@ -491,10 +750,7 @@ const options = [
 
 ```tsx
 // Simplest usage with string array
-<Autocomplete
-  label="Fruit"
-  options={['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry']}
-/>
+<Autocomplete label="Fruit" options={['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry']} />
 ```
 
 ### Controlled vs Uncontrolled
@@ -504,23 +760,12 @@ const options = [
 function ControlledExample() {
   const [value, setValue] = useState<string | undefined>();
 
-  return (
-    <Autocomplete
-      value={value}
-      onChange={(e) => setValue(e.target.value)}
-      options={options}
-    />
-  );
+  return <Autocomplete value={value} onChange={(e) => setValue(e.target.value)} options={options} />;
 }
 
 // Uncontrolled - internal state management
 function UncontrolledExample() {
-  return (
-    <Autocomplete
-      defaultValue="option-1"
-      options={options}
-    />
-  );
+  return <Autocomplete defaultValue="option-1" options={options} />;
 }
 ```
 
@@ -554,12 +799,7 @@ function UncontrolledExample() {
 ### Multiple Selection
 
 ```tsx
-<Autocomplete
-  multiple
-  value={['option-1', 'option-2']}
-  options={options}
-  onChange={(e) => setValues(e.target.value)}
-/>
+<Autocomplete multiple value={['option-1', 'option-2']} options={options} onChange={(e) => setValues(e.target.value)} />
 ```
 
 ## Accessibility
@@ -578,7 +818,7 @@ Autocomplete includes comprehensive accessibility features:
 - **Arrow Down**: Open dropdown / move to next option
 - **Arrow Up**: Move to previous option
 - **Enter**: Select focused option
-- **Escape**: Close dropdown
+- **Escape**: Close dropdown (clears value if `clearOnEscape` is enabled)
 - **Tab**: Move focus out of component
 - **Home**: Jump to first option
 - **End**: Jump to last option
@@ -589,7 +829,7 @@ Autocomplete includes comprehensive accessibility features:
 ```tsx
 // Proper labeling for screen readers
 <Autocomplete
-  label="Select a country"  // Announces: "Select a country, combobox"
+  label="Select a country" // Announces: "Select a country, combobox"
   placeholder="Search..."
   options={countries}
 />
@@ -603,6 +843,11 @@ Autocomplete includes comprehensive accessibility features:
 - Focus returns to input when selecting an option
 - Clear visual focus indicators on all interactive elements
 
+### Read Only vs Disabled Semantics
+
+- **`readOnly`**: The input is focusable, its value can be copied, and screen readers announce it as read-only. Use when a value should be visible but not editable.
+- **`disabled`**: The input is not focusable and is skipped in tab order. Use when the field is temporarily unavailable.
+
 ## Best Practices
 
 ### ✅ Do
@@ -611,32 +856,21 @@ Autocomplete includes comprehensive accessibility features:
 
 ```tsx
 // ✅ Good: Clear label and placeholder
-<Autocomplete
-  label="Shipping Country"
-  placeholder="Type to search countries..."
-  options={countries}
-/>
+<Autocomplete label="Shipping Country" placeholder="Type to search countries..." options={countries} />
 ```
 
 2. **Show loading state during async operations**: Keep users informed
 
 ```tsx
 // ✅ Good: Loading indicator while fetching
-<Autocomplete
-  options={options}
-  loading={isLoading}
-  placeholder={isLoading ? 'Loading...' : 'Search...'}
-/>
+<Autocomplete options={options} loading={isLoading} placeholder={isLoading ? 'Loading...' : 'Search...'} />
 ```
 
 3. **Use grouping for better organization**: Help users scan large lists
 
 ```tsx
 // ✅ Good: Logical grouping
-<Autocomplete
-  options={allProducts}
-  groupBy={(product) => product.category}
-/>
+<Autocomplete options={allProducts} groupBy={(product) => product.category} />
 ```
 
 4. **Debounce API searches**: Prevent excessive requests
@@ -649,6 +883,20 @@ useEffect(() => {
 }, [query]);
 ```
 
+5. **Use `disableCloseOnSelect` with `multiple`**: Keep the popup open for batch selection
+
+```tsx
+// ✅ Good: Popup stays open for multiple selections
+<Autocomplete multiple disableCloseOnSelect options={tags} />
+```
+
+6. **Set `limitTags` for constrained layouts**: Prevent tag overflow
+
+```tsx
+// ✅ Good: Show at most 3 tags, truncate the rest
+<Autocomplete multiple limitTags={3} options={allTags} />
+```
+
 ### ❌ Don't
 
 1. **Don't use for small option sets**: Use Select instead
@@ -686,20 +934,36 @@ useEffect(() => {
 
 ```tsx
 // ✅ Good: Handle empty results
-<Autocomplete
-  options={filteredOptions}
-  noOptionsText="No matches found. Try a different search."
-/>
+<Autocomplete options={filteredOptions} noOptionsText="No matches found. Try a different search." />
 ```
 
 4. **Don't block interaction during initial load**: Show placeholders
 
 ```tsx
 // ❌ Bad: Blocking the entire form
-{loading ? <Spinner /> : <Autocomplete options={options} />}
+{
+  loading ? <Spinner /> : <Autocomplete options={options} />;
+}
 
 // ✅ Good: Allow interaction with loading state
-<Autocomplete options={options} loading={loading} />
+<Autocomplete options={options} loading={loading} />;
+```
+
+5. **Don't rely on `freeSolo` for validated input without extra handling**: Validate free-text values
+
+```tsx
+// ❌ Bad: No validation for free-text input
+<Autocomplete freeSolo options={emails} />
+
+// ✅ Good: Validate free-text input via onInputChange
+<Autocomplete
+  freeSolo
+  options={emails}
+  onInputChange={(e) => {
+    const value = e.target.value;
+    setError(!isValidEmail(value));
+  }}
+/>
 ```
 
 ## Performance Considerations
@@ -710,9 +974,7 @@ Autocomplete automatically virtualizes long lists for performance:
 
 ```tsx
 // Handles 1000+ options efficiently
-<Autocomplete
-  options={Array.from({ length: 1000 }, (_, i) => `Option ${i + 1}`)}
-/>
+<Autocomplete options={Array.from({ length: 1000 }, (_, i) => `Option ${i + 1}`)} />
 ```
 
 ### Debounce Search Requests
@@ -739,16 +1001,10 @@ function SearchAutocomplete({ fetchOptions }) {
           setLoading(false);
         }
       }, 300),
-    [fetchOptions]
+    [fetchOptions],
   );
 
-  return (
-    <Autocomplete
-      options={options}
-      loading={loading}
-      onInputChange={(e) => debouncedFetch(e.target.value)}
-    />
-  );
+  return <Autocomplete options={options} loading={loading} onInputChange={(e) => debouncedFetch(e.target.value)} />;
 }
 ```
 
@@ -764,10 +1020,10 @@ const options = useMemo(
       label: item.name,
       startDecorator: <StatusChip status={item.status} />,
     })),
-  [data]
+  [data],
 );
 
-<Autocomplete options={options} />
+<Autocomplete options={options} />;
 ```
 
 ### Lazy Load Options
@@ -793,14 +1049,7 @@ function LazyLoadAutocomplete() {
     }
   };
 
-  return (
-    <Autocomplete
-      options={options}
-      loading={loading}
-      onFocus={loadOptions}
-      onOpen={loadOptions}
-    />
-  );
+  return <Autocomplete options={options} loading={loading} onFocus={loadOptions} onOpen={loadOptions} />;
 }
 ```
 
@@ -828,7 +1077,7 @@ const options = useMemo(
       label: user.name,
       startDecorator: <MemoizedOption option={user} />,
     })),
-  [users]
+  [users],
 );
 ```