@primereact/mcp 11.0.0-rc.2

package/data/llms/primitive/components/autocomplete.md

@@ -0,0 +1,344 @@
+# AutoComplete
+
+An unstyled autocomplete input component with real-time search, keyboard navigation, and popup positioning.
+
+<DocPrimitiveIntro description="Build fully custom autocomplete inputs with complete control over layout and styling." />
+
+```tsx
+'use client';
+import { AutoComplete, type AutoCompleteCompleteEvent } from 'primereact/autocomplete';
+import * as React from 'react';
+import styles from './basic-demo.module.css';
+
+const countries = [
+    'Argentina',
+    'Australia',
+    'Brazil',
+    'Canada',
+    'China',
+    'Egypt',
+    'France',
+    'Germany',
+    'India',
+    'Italy',
+    'Japan',
+    'Mexico',
+    'Netherlands',
+    'Norway',
+    'Poland',
+    'South Korea',
+    'Spain',
+    'Sweden',
+    'Switzerland',
+    'Turkey',
+    'United Kingdom',
+    'United States'
+];
+
+export default function BasicDemo() {
+    const [filteredCountries, setFilteredCountries] = React.useState<string[]>([]);
+
+    const search = (event: AutoCompleteCompleteEvent) => {
+        const query = event.query.toLowerCase();
+
+        setFilteredCountries(query ? countries.filter((country) => country.toLowerCase().includes(query)) : [...countries]);
+    };
+
+    return (
+        <div className={styles.wrapper}>
+            <AutoComplete.Root options={filteredCountries} onComplete={search} className={styles.root}>
+                <AutoComplete.Input placeholder="Search a country..." className={styles.input} />
+                <AutoComplete.Portal>
+                    <AutoComplete.Positioner sideOffset={4}>
+                        <AutoComplete.Popup className={styles.popup}>
+                            <AutoComplete.List className={styles.list} style={{ maxHeight: '14rem' }} />
+                            <AutoComplete.Empty className={styles.empty}>No countries found</AutoComplete.Empty>
+                        </AutoComplete.Popup>
+                    </AutoComplete.Positioner>
+                </AutoComplete.Portal>
+            </AutoComplete.Root>
+        </div>
+    );
+}
+```
+
+<DocPrimitiveLinks name="AutoComplete" />
+
+## Features
+
+- Compound component API with sub-components: `Root`, `Input`, `Trigger`, `Indicator`, `Clear`, `Portal`, `Positioner`, `Popup`, `List`, `Option`, `OptionIndicator`, `Arrow`, `Header`, `Footer`, `Empty`, `Value`
+- Real-time search via `onComplete` callback with configurable delay and minimum length
+- Force selection mode that clears unmatched input on blur
+- Option grouping with `optionGroupLabel` and `optionGroupChildren`
+- Built-in clear button and trigger toggle support
+
+## Usage
+
+```tsx
+import { AutoComplete } from 'primereact/autocomplete';
+```
+
+```tsx
+<AutoComplete.Root>
+    <AutoComplete.Input />
+    <AutoComplete.Trigger>
+        <AutoComplete.Indicator />
+    </AutoComplete.Trigger>
+    <AutoComplete.Clear />
+    <AutoComplete.Portal>
+        <AutoComplete.Positioner>
+            <AutoComplete.Popup>
+                <AutoComplete.Header />
+                <AutoComplete.List>
+                    <AutoComplete.Option>
+                        <AutoComplete.OptionIndicator />
+                    </AutoComplete.Option>
+                </AutoComplete.List>
+                <AutoComplete.Empty />
+                <AutoComplete.Footer />
+            </AutoComplete.Popup>
+        </AutoComplete.Positioner>
+    </AutoComplete.Portal>
+</AutoComplete.Root>
+```
+
+## Behavior
+
+### Motion Animation
+
+```tsx
+<AutoComplete.Popup motionProps={{ name: 'p-autocomplete' }}>...</AutoComplete.Popup>
+```
+
+See [Motion](/docs/primitive/components/motion) for animation phases, CSS variables, and hide strategies.
+
+### Polymorphic Rendering
+
+Use `as` on any sub-component to change the rendered HTML element.
+
+```tsx
+<AutoComplete.Input as={CustomInput} />
+<AutoComplete.Trigger as="div">...</AutoComplete.Trigger>
+```
+
+### Render Function Children
+
+`AutoComplete.List` accepts a render function as children, providing access to the component instance for custom option rendering.
+
+```tsx
+<AutoComplete.List>
+    {(instance) =>
+        instance.options?.map((option, index) => (
+            <AutoComplete.Option key={index} index={index}>
+                {instance.listbox?.getOptionLabel(option)}
+            </AutoComplete.Option>
+        ))
+    }
+</AutoComplete.List>
+```
+
+## Pass Through
+
+<DocPTViewer name="autocomplete-pt" components={['AutoCompleteRoot']} />
+
+## API
+
+### AutoCompleteRoot
+
+<DocTable name="AutoCompleteRoot" category="api" />
+
+| Attribute    | Value            |
+| ------------ | ---------------- |
+| `data-scope` | `"autocomplete"` |
+| `data-part`  | `"root"`         |
+
+<DocTable name="AutoCompleteRoot" category="pt" />
+
+### AutoCompleteInput
+
+<DocTable name="AutoCompleteInput" category="api" />
+
+| Attribute    | Value            |
+| ------------ | ---------------- |
+| `data-scope` | `"autocomplete"` |
+| `data-part`  | `"input"`        |
+
+<DocTable name="AutoCompleteInput" category="pt" />
+
+### AutoCompleteTrigger
+
+<DocTable name="AutoCompleteTrigger" category="api" />
+
+| Attribute              | Value                      |
+| ---------------------- | -------------------------- |
+| `data-scope`           | `"autocomplete"`           |
+| `data-part`            | `"trigger"`                |
+| `data-positioner-open` | Present when popup is open |
+
+<DocTable name="AutoCompleteTrigger" category="pt" />
+
+### AutoCompleteIndicator
+
+<DocTable name="AutoCompleteIndicator" category="api" />
+
+| Attribute     | Value                        |
+| ------------- | ---------------------------- |
+| `data-scope`  | `"autocomplete"`             |
+| `data-part`   | `"indicator"`                |
+| `data-open`   | Present when popup is open   |
+| `data-closed` | Present when popup is closed |
+
+<DocTable name="AutoCompleteIndicator" category="pt" />
+
+### AutoCompleteClear
+
+<DocTable name="AutoCompleteClear" category="api" />
+
+| Attribute    | Value            |
+| ------------ | ---------------- |
+| `data-scope` | `"autocomplete"` |
+| `data-part`  | `"clear"`        |
+
+<DocTable name="AutoCompleteClear" category="pt" />
+
+### AutoCompletePortal
+
+<DocTable name="AutoCompletePortal" category="api" />
+
+<DocTable name="AutoCompletePortal" category="pt" />
+
+### AutoCompletePositioner
+
+<DocTable name="AutoCompletePositioner" category="api" />
+
+| Attribute    | Value                                                     |
+| ------------ | --------------------------------------------------------- |
+| `data-side`  | `"top"` \| `"bottom"` \| `"left"` \| `"right"`, placement |
+| `data-align` | `"start"` \| `"center"` \| `"end"`, alignment             |
+
+**CSS Custom Properties**
+
+The positioner element exposes CSS custom properties for layout and transform control.
+
+| CSS Variable                | Description                              |
+| --------------------------- | ---------------------------------------- |
+| `--available-height`        | Available vertical space in pixels       |
+| `--available-width`         | Available horizontal space in pixels     |
+| `--transform-origin`        | Computed transform origin for animations |
+| `--positioner-anchor-width` | Width of the anchor/trigger element      |
+
+<DocTable name="AutoCompletePositioner" category="pt" />
+
+### AutoCompletePopup
+
+<DocTable name="AutoCompletePopup" category="api" />
+
+| Attribute    | Value                      |
+| ------------ | -------------------------- |
+| `data-scope` | `"autocomplete"`           |
+| `data-part`  | `"popup"`                  |
+| `data-open`  | Present when popup is open |
+
+<DocTable name="AutoCompletePopup" category="pt" />
+
+### AutoCompleteList
+
+<DocTable name="AutoCompleteList" category="api" />
+
+| Attribute    | Value            |
+| ------------ | ---------------- |
+| `data-scope` | `"autocomplete"` |
+| `data-part`  | `"list"`         |
+
+<DocTable name="AutoCompleteList" category="pt" />
+
+### AutoCompleteOption
+
+<DocTable name="AutoCompleteOption" category="api" />
+
+| Attribute         | Value                   |
+| ----------------- | ----------------------- |
+| `data-selected`   | Present when selected   |
+| `data-unselected` | Present when unselected |
+| `data-focused`    | Present when focused    |
+| `data-disabled`   | Present when disabled   |
+
+<DocTable name="AutoCompleteOption" category="pt" />
+
+### AutoCompleteOptionIndicator
+
+<DocTable name="AutoCompleteOptionIndicator" category="api" />
+
+| Attribute         | Value                   |
+| ----------------- | ----------------------- |
+| `data-selected`   | Present when selected   |
+| `data-unselected` | Present when unselected |
+
+<DocTable name="AutoCompleteOptionIndicator" category="pt" />
+
+### AutoCompleteHeader
+
+<DocTable name="AutoCompleteHeader" category="api" />
+
+<DocTable name="AutoCompleteHeader" category="pt" />
+
+### AutoCompleteFooter
+
+<DocTable name="AutoCompleteFooter" category="api" />
+
+<DocTable name="AutoCompleteFooter" category="pt" />
+
+### AutoCompleteEmpty
+
+<DocTable name="AutoCompleteEmpty" category="api" />
+
+<DocTable name="AutoCompleteEmpty" category="pt" />
+
+### AutoCompleteArrow
+
+<DocTable name="AutoCompleteArrow" category="api" />
+
+| Attribute    | Value                                                     |
+| ------------ | --------------------------------------------------------- |
+| `data-side`  | `"top"` \| `"bottom"` \| `"left"` \| `"right"`, placement |
+| `data-align` | `"start"` \| `"center"` \| `"end"`, alignment             |
+
+The arrow element exposes CSS custom properties for dynamic positioning:
+
+| CSS Variable          | Description                    |
+| --------------------- | ------------------------------ |
+| `--placer-arrow-x`    | Horizontal offset of arrow     |
+| `--placer-arrow-y`    | Vertical offset of arrow       |
+| `--placer-arrow-left` | Left position of arrow element |
+| `--placer-arrow-top`  | Top position of arrow element  |
+
+<DocTable name="AutoCompleteArrow" category="pt" />
+
+### AutoCompleteValue
+
+<DocTable name="AutoCompleteValue" category="api" />
+
+<DocTable name="AutoCompleteValue" category="pt" />
+
+## Accessibility
+
+### Screen Reader
+
+`AutoComplete.Root` uses a combobox pattern. The input has `role="combobox"` with `aria-autocomplete`, `aria-haspopup` and `aria-expanded` attributes. The relation between the input and the popup is created with `aria-controls` and `aria-activedescendant` attribute is used to instruct screen reader which option to read during keyboard navigation within the popup list. Options have `role="option"` with `aria-selected` to indicate the current selection. The clear button has an `aria-label` for screen reader accessibility. Provide an accessible name with `aria-label`, `aria-labelledby`, or an associated label element.
+
+### Keyboard Support
+
+| Key                       | Function                                                                 |
+| ------------------------- | ------------------------------------------------------------------------ |
+| `tab`                     | Moves focus to the autocomplete element.                                 |
+| `any printable character` | Opens the popup and displays matching suggestions.                       |
+| `enter`                   | Selects the focused option and closes the popup.                         |
+| `escape`                  | Closes the popup.                                                        |
+| `arrow down`              | Opens the popup or moves focus to the next option.                       |
+| `arrow up`                | Opens the popup or moves focus to the previous option.                   |
+| `arrow left`              | Removes the visual focus from the current option and moves input cursor. |
+| `arrow right`             | Removes the visual focus from the current option and moves input cursor. |
+| `home`                    | Moves focus to the first option.                                         |
+| `end`                     | Moves focus to the last option.                                          |
+| `pageUp`                  | Jumps visual focus to the first option.                                  |
+| `pageDown`                | Jumps visual focus to the last option.                                   |