@ceed/ads 1.29.0 → 1.30.0-next.1

package/dist/components/inputs/Autocomplete.md

@@ -8,36 +8,10 @@ Autocomplete is an enhanced input component that provides real-time suggestions
 <Autocomplete options={['Option1', 'Option2']} />
 ```
 
-| 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          | —           | —       |
+| Field   | Description | Default |
+| ------- | ----------- | ------- |
+| label   | —           | —       |
+| loading | —           | —       |
 
 > ⚠️ **Usage Warning** ⚠️
 >
@@ -48,11 +22,6 @@ 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
@@ -73,136 +42,23 @@ function CountrySelector() {
 }
 ```
 
-## Variants
-
-The `variant` prop controls the visual style of the autocomplete input. Available variants: `outlined` (default), `soft`, `solid`, `plain`.
-
-```tsx
-<Stack gap={2} p={2}>
-  {variants.map(variant => <Autocomplete key={variant} variant={variant} options={sampleOptions} placeholder={variant} label={variant} sx={{
-    maxWidth: 300
-  }} />)}
-</Stack>
-```
-
-## Sizes
-
-Available size options: `sm`, `md`, `lg`.
-
-```tsx
-<div style={{
-  display: 'flex',
-  gap: '10px'
-}}>
-<Autocomplete {...args} size="sm" />
-<Autocomplete {...args} size="md" />
-<Autocomplete {...args} size="lg" />
-</div>
-```
-
-## 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
-}}
-/>
-```
+## Examples
 
-## Custom Texts
+### Playground
 
-Customize the messages shown when there are no matching options or while loading.
+Interactive example with basic string options.
 
 ```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>
+<Autocomplete options={['Option1', 'Option2']} />
 ```
 
-## Multiple Selection
+### Sizes
 
-Enable `multiple` to allow selecting more than one option. Selected values are shown as chips.
+Available size options: `sm`, `md`, `lg`.
 
 ```tsx
 <div style={{
   display: 'flex',
-  flexDirection: 'column',
   gap: '10px'
 }}>
 <Autocomplete {...args} size="sm" />
@@ -211,28 +67,7 @@ Enable `multiple` to allow selecting more than one option. Selected values are s
 </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
+### Option Groups
 
 Group options into categories using the `groupBy` function.
 
@@ -260,7 +95,7 @@ Group options into categories using the `groupBy` function.
 />
 ```
 
-## Custom Options
+### Custom Options
 
 Options can include decorators for rich content display.
 
@@ -281,28 +116,7 @@ Options can include decorators for rich content display.
 />
 ```
 
-## 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
+### Loading State
 
 Show a loading indicator while fetching options.
 
@@ -313,8 +127,6 @@ Show a loading indicator while fetching options.
 />
 ```
 
-## Controlled / Uncontrolled
-
 ### Controlled
 
 Manage value externally with controlled state.
@@ -341,67 +153,6 @@ 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
@@ -476,7 +227,7 @@ function UserSearch({ onSelect }) {
             label: user.name,
             secondaryText: user.email,
             startDecorator: <Avatar src={user.avatar} size="sm" />,
-          })),
+          }))
         );
       } finally {
         setLoading(false);
@@ -553,7 +304,7 @@ function AddressAutocomplete({ onAddressSelect }) {
           value: result.placeId,
           label: result.formattedAddress,
           secondaryText: result.city + ', ' + result.country,
-        })),
+        }))
       );
     } finally {
       setLoading(false);
@@ -645,7 +396,13 @@ 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}
+    />
+  );
 }
 ```
 
@@ -686,46 +443,30 @@ 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`                 | `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)   |
+| 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                     |
 
 ### 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
@@ -750,7 +491,10 @@ 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
@@ -760,12 +504,23 @@ 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}
+    />
+  );
 }
 ```
 
@@ -799,7 +554,12 @@ 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
@@ -818,7 +578,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 (clears value if `clearOnEscape` is enabled)
+- **Escape**: Close dropdown
 - **Tab**: Move focus out of component
 - **Home**: Jump to first option
 - **End**: Jump to last option
@@ -829,7 +589,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}
 />
@@ -843,11 +603,6 @@ 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
@@ -856,21 +611,32 @@ 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
@@ -883,20 +649,6 @@ 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
@@ -934,36 +686,20 @@ 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} />;
-```
-
-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));
-  }}
-/>
+<Autocomplete options={options} loading={loading} />
 ```
 
 ## Performance Considerations
@@ -974,7 +710,9 @@ 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
@@ -1001,10 +739,16 @@ 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)}
+    />
+  );
 }
 ```
 
@@ -1020,10 +764,10 @@ const options = useMemo(
       label: item.name,
       startDecorator: <StatusChip status={item.status} />,
     })),
-  [data],
+  [data]
 );
 
-<Autocomplete options={options} />;
+<Autocomplete options={options} />
 ```
 
 ### Lazy Load Options
@@ -1049,7 +793,14 @@ function LazyLoadAutocomplete() {
     }
   };
 
-  return <Autocomplete options={options} loading={loading} onFocus={loadOptions} onOpen={loadOptions} />;
+  return (
+    <Autocomplete
+      options={options}
+      loading={loading}
+      onFocus={loadOptions}
+      onOpen={loadOptions}
+    />
+  );
 }
 ```
 
@@ -1077,7 +828,7 @@ const options = useMemo(
       label: user.name,
       startDecorator: <MemoizedOption option={user} />,
     })),
-  [users],
+  [users]
 );
 ```