@primereact/mcp 11.0.0-rc.2

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

@@ -0,0 +1,249 @@
+# useAutoComplete
+
+Hook that manages autocomplete state, search callbacks, and popup positioning for combobox inputs.
+
+```tsx
+'use client';
+import { useAutoComplete, type UseAutoCompleteCompleteEvent } from '@primereact/headless/autocomplete';
+import { useListboxOption } from '@primereact/headless/listbox';
+import { usePortal } from '@primereact/headless/portal';
+import { usePositioner } from '@primereact/headless/positioner';
+import type { UseListboxInstance } from '@primereact/types/headless/listbox';
+import * as React from 'react';
+import { createPortal } from 'react-dom';
+
+function OptionItem({ option, index, listbox }: { option: unknown; index: number; listbox: UseListboxInstance }) {
+    const { optionProps } = useListboxOption({ option, index, context: listbox });
+
+    return (
+        <li
+            {...optionProps}
+            className="flex items-center px-3 py-2 rounded-md cursor-pointer select-none text-sm outline-none transition-[background-color] duration-200 text-surface-700 dark:text-surface-0 hover:bg-surface-50 dark:hover:bg-surface-800 data-[focused]:bg-surface-100 dark:data-[focused]:bg-surface-800 data-[selected]:bg-surface-100 dark:data-[selected]:bg-surface-800 data-[selected]:text-primary data-[disabled]:pointer-events-none data-[disabled]:opacity-60"
+        >
+            {listbox.getOptionLabel(option)}
+        </li>
+    );
+}
+
+export default function BasicDemo() {
+    const [filteredCountries, setFilteredCountries] = React.useState<string[]>([]);
+
+    const search = (event: UseAutoCompleteCompleteEvent) => {
+        const query = event.query.toLowerCase();
+
+        setFilteredCountries(query ? countries.filter((country) => country.toLowerCase().includes(query)) : [...countries]);
+    };
+
+    const { rootProps, inputProps, listProps, positionerProps, popupProps, state, listbox } = useAutoComplete({
+        options: filteredCountries,
+        onComplete: search
+    });
+
+    const portal = usePortal();
+
+    usePositioner({
+        anchor: state.anchorElement,
+        content: state.positionerElement,
+        side: 'bottom',
+        sideOffset: 4,
+        flip: true,
+        shift: true
+    });
+
+    return (
+        <div className="flex justify-center">
+            <div {...rootProps} className="relative w-full md:w-56">
+                <input
+                    {...inputProps}
+                    placeholder="Search a country..."
+                    className="w-full px-3 py-2 text-sm bg-transparent border border-surface-200 dark:border-surface-700 rounded-lg outline-none text-surface-700 dark:text-surface-0 placeholder:text-surface-400 transition-[border-color] duration-200 focus:border-primary"
+                />
+                {portal.state.mounted &&
+                    state.opened &&
+                    createPortal(
+                        <div {...positionerProps}>
+                            <div
+                                {...popupProps}
+                                className="border border-surface-200 dark:border-surface-700 rounded-lg bg-surface-0 dark:bg-surface-900 shadow-md overflow-hidden"
+                            >
+                                <ul {...listProps} className="list-none m-0 p-1 outline-none max-h-56 overflow-auto">
+                                    {listbox?.getOptions().map((option: unknown, index: number) => (
+                                        <OptionItem key={index} option={option} index={index} listbox={listbox} />
+                                    ))}
+                                </ul>
+                                {filteredCountries.length === 0 && <div className="px-3 py-2 text-sm text-surface-400">No countries found</div>}
+                            </div>
+                        </div>,
+                        document.body
+                    )}
+            </div>
+        </div>
+    );
+}
+
+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'
+];
+```
+
+## Usage
+
+```tsx
+import { useAutoComplete } from '@primereact/headless/autocomplete';
+```
+
+```tsx
+const autocomplete = useAutoComplete({ options: filteredItems, onComplete: search });
+const { rootProps, inputProps, triggerProps, listProps, positionerProps, popupProps, arrowProps } = autocomplete;
+
+<div {...rootProps}>
+    <input {...inputProps} />
+    <button {...triggerProps}></button>
+    <div {...positionerProps}>
+        <div {...popupProps}>
+            <ul {...listProps}>...</ul>
+        </div>
+        <div {...arrowProps} />
+    </div>
+</div>;
+```
+
+`useAutoComplete` composes `useListbox` and `usePopover` internally. See [Primitive](/docs/primitive/components/autocomplete) for a component-based API.
+
+## Features
+
+- **Search callback**, fires `onComplete` with the current query; you own the filtering logic
+- **Popup lifecycle**, open/close state, positioning, keyboard dismissal, and outside-click handling
+- **Listbox integration**, option iteration, selection, and keyboard navigation via the returned `listbox` instance
+- **Controlled or uncontrolled**, both value and input text can be managed externally or internally
+- **Imperative controls**, `show()`, `hide()`, `toggle()`, `focus()`, and `setRendered()`
+
+## Working with callbacks
+
+### onComplete, filter your own data
+
+The hook doesn't filter options for you. Use `onComplete` to run the search against your data source.
+
+```tsx
+const [filtered, setFiltered] = useState(items);
+
+useAutoComplete({
+    options: filtered,
+    onComplete: ({ query }) => {
+        setFiltered(items.filter((item) => item.toLowerCase().includes(query.toLowerCase())));
+    }
+});
+```
+
+### Async search with debounce
+
+Set `delay` to throttle `onComplete` for network requests.
+
+```tsx
+useAutoComplete({
+    options: results,
+    delay: 300,
+    onComplete: async ({ query }) => {
+        const res = await fetch(`/api/search?q=${query}`);
+        setResults(await res.json());
+    }
+});
+```
+
+### Controlled selection
+
+Pass `value` and `onValueChange` to drive the selected option from outside state.
+
+```tsx
+const [selected, setSelected] = useState(null);
+
+useAutoComplete({
+    value: selected,
+    onValueChange: ({ value }) => setSelected(value)
+});
+```
+
+### Controlled input text
+
+`inputValue` and `onInputValueChange` control only the text in the input, independent of `value`.
+
+```tsx
+const [query, setQuery] = useState('');
+
+useAutoComplete({
+    inputValue: query,
+    onInputValueChange: ({ query }) => setQuery(query)
+});
+```
+
+### Object options
+
+When options are objects, map the fields used for labels, values, and disabled state.
+
+```tsx
+useAutoComplete({
+    options: cities,
+    optionLabel: 'name',
+    optionValue: 'code',
+    optionDisabled: 'inactive'
+});
+```
+
+## Styling with data attributes
+
+The hook exposes state through `data-*` attributes on each part. Use them as CSS selectors, no className juggling.
+
+| Scope          | Part              | States                                                              |
+| -------------- | ----------------- | ------------------------------------------------------------------- |
+| `autocomplete` | `trigger`         | `data-positioner-open`                                              |
+| `autocomplete` | `popup`           | `data-open`                                                         |
+| `autocomplete` | `indicator`       | `data-open`, `data-closed`                                          |
+| `listbox`      | `option`          | `data-selected`, `data-unselected`, `data-focused`, `data-disabled` |
+| `listbox`      | `optionindicator` | `data-selected`, `data-unselected`                                  |
+
+```css
+[data-scope='autocomplete'][data-part='indicator'][data-open] {
+    transform: rotate(180deg);
+}
+
+[data-scope='autocomplete'][data-part='popup'][data-open] {
+    border: 1px solid var(--p-content-border-color);
+    border-radius: 6px;
+    box-shadow: 0 4px 12px rgb(0 0 0 / 0.1);
+}
+
+[data-scope='listbox'][data-part='option'][data-focused] {
+    background: var(--p-surface-100);
+}
+```
+
+## API
+
+### useAutoComplete
+
+<DocTable name="useAutoComplete" category="api" />
+
+## Accessibility
+
+Arrow keys navigate suggestions, Enter selects the focused option, Escape dismisses the popup, and typing filters via your onComplete handler. See [Primitive](/docs/primitive/components/autocomplete#accessibility) for full WAI-ARIA compliance details.

package/data/llms/headless/components/avatar/api.json

@@ -0,0 +1,154 @@
+[
+  {
+    "name": "useAvatar",
+    "source": "apps/showcase/assets/apidoc/useavatar.json",
+    "data": {
+      "description": "The useAvatar manages the state and functionality of an Avatar component.",
+      "interfaces": {
+        "UseAvatarProps": {
+          "description": "Defines valid properties in useAvatar.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "delayDuration",
+              "type": "number",
+              "default": "",
+              "description": "The delay duration of the avatar."
+            }
+          ],
+          "methods": []
+        },
+        "UseAvatarState": {
+          "description": "Defines valid state in useAvatar.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "load",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether the avatar's image is loading or not."
+            }
+          ],
+          "methods": []
+        },
+        "UseAvatarRootProps": {
+          "description": "Data attribute props for the Avatar root element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "data-scope",
+              "type": "string",
+              "default": "",
+              "description": "Component scope identifier."
+            },
+            {
+              "name": "data-part",
+              "type": "string",
+              "default": "",
+              "description": "Component part identifier."
+            }
+          ],
+          "methods": []
+        },
+        "UseAvatarExposes": {
+          "description": "Defines the methods and properties exposed by useAvatar.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "state",
+              "type": "UseAvatarState",
+              "default": "",
+              "description": "The state of the useAvatar."
+            },
+            {
+              "name": "rootProps",
+              "type": "UseAvatarRootProps",
+              "default": "",
+              "description": "Pre-built data attribute props for the root element."
+            },
+            {
+              "name": "handleImageLoad",
+              "type": "(src?: string) => void",
+              "default": "",
+              "description": "The method to handle image load."
+            },
+            {
+              "name": "handleImageUnload",
+              "type": "() => void",
+              "default": "",
+              "description": "The method to handle image unload."
+            }
+          ],
+          "methods": []
+        }
+      },
+      "types": {
+        "UseAvatarInstance": {
+          "description": "Instance of useAvatar headless.",
+          "values": "HeadlessInstance<UseAvatarProps, UseAvatarState, UseAvatarExposes>"
+        }
+      },
+      "variables": {}
+    }
+  },
+  {
+    "name": "useAvatarGroup",
+    "source": "apps/showcase/assets/apidoc/useavatargroup.json",
+    "data": {
+      "description": "The useAvatarGroup manages the state and functionality of an AvatarGroup component.",
+      "interfaces": {
+        "UseAvatarGroupProps": {
+          "description": "Defines valid properties in useAvatarGroup.",
+          "relatedProp": "",
+          "props": [],
+          "methods": []
+        },
+        "UseAvatarGroupState": {
+          "description": "Defines valid state in useAvatarGroup.",
+          "relatedProp": "",
+          "props": [],
+          "methods": []
+        },
+        "UseAvatarGroupRootProps": {
+          "description": "Data attribute props for the AvatarGroup root element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "data-scope",
+              "type": "string",
+              "default": "",
+              "description": "Component scope identifier."
+            },
+            {
+              "name": "data-part",
+              "type": "string",
+              "default": "",
+              "description": "Component part identifier."
+            }
+          ],
+          "methods": []
+        },
+        "UseAvatarGroupExposes": {
+          "description": "Defines the methods and properties exposed by useAvatarGroup.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "rootProps",
+              "type": "UseAvatarGroupRootProps",
+              "default": "",
+              "description": "Pre-built data attribute props for the root element."
+            }
+          ],
+          "methods": []
+        }
+      },
+      "types": {
+        "UseAvatarGroupInstance": {
+          "description": "Instance of useAvatarGroup headless.",
+          "values": "HeadlessInstance<UseAvatarGroupProps, UseAvatarGroupState, UseAvatarGroupExposes>"
+        }
+      },
+      "variables": {}
+    }
+  }
+]

package/data/llms/headless/components/avatar.md

@@ -0,0 +1,149 @@
+# useAvatar
+
+Hooks that manage avatar image loading state and group layout.
+
+```tsx
+'use client';
+import { User } from '@primeicons/react/user';
+import { useAvatar } from '@primereact/headless/avatar';
+import { useAvatarGroup } from '@primereact/headless/avatargroup';
+
+export default function BasicDemo() {
+    const { rootProps: groupRootProps } = useAvatarGroup();
+    const avatar1 = useAvatar();
+    const avatar2 = useAvatar();
+    const avatar3 = useAvatar();
+    const avatar4 = useAvatar();
+
+    return (
+        <div className="flex justify-center">
+            <div {...groupRootProps} className="flex items-center -space-x-3">
+                <div
+                    {...avatar1.rootProps}
+                    className="inline-flex items-center justify-center w-8 h-8 rounded-full bg-amber-100 dark:bg-amber-950 text-amber-500 ring-2 ring-surface-0 dark:ring-surface-900 text-sm font-medium"
+                >
+                    AB
+                </div>
+                <div
+                    {...avatar2.rootProps}
+                    className="inline-flex items-center justify-center w-8 h-8 rounded-full bg-blue-100 dark:bg-blue-950 text-blue-500 ring-2 ring-surface-0 dark:ring-surface-900 text-sm font-medium"
+                >
+                    CD
+                </div>
+                <div
+                    {...avatar3.rootProps}
+                    className="inline-flex items-center justify-center w-8 h-8 rounded-full bg-green-100 dark:bg-green-950 text-green-500 ring-2 ring-surface-0 dark:ring-surface-900"
+                >
+                    <User />
+                </div>
+                <div
+                    {...avatar4.rootProps}
+                    className="inline-flex items-center justify-center w-8 h-8 rounded-full bg-surface-200 dark:bg-surface-700 text-surface-800 dark:text-surface-300 ring-2 ring-surface-0 dark:ring-surface-900 text-sm font-medium"
+                >
+                    +3
+                </div>
+            </div>
+        </div>
+    );
+}
+```
+
+## Usage
+
+```tsx
+import { useAvatar } from '@primereact/headless/avatar';
+import { useAvatarGroup } from '@primereact/headless/avatargroup';
+```
+
+```tsx
+const { rootProps, state, handleImageLoad, handleImageUnload } = useAvatar();
+
+return <div {...rootProps}></div>;
+```
+
+`useAvatar` owns the image-loading lifecycle and exposes `state.load` for fallback rendering, while `useAvatarGroup` returns root props for grouping multiple avatars. See [Primitive](/docs/primitive/components/avatar) for a component-based API.
+
+## Features
+
+- **Image loading lifecycle**, attaches `load`/`error` listeners and flips `state.load` so you can swap between image and fallback
+- **Imperative load helpers**, `handleImageLoad(src)` starts a preload and `handleImageUnload()` cleans listeners up
+- **Delayed reveal**, `delayDuration` holds the image hidden for a short window to avoid layout flashes on fast connections
+- **Group layout primitive**, `useAvatarGroup` exposes a root prop object with shared data attributes so child avatars can be styled relative to each other
+- **Data-attribute styling**, scoped `data-scope` / `data-part` attributes on both avatar and group roots
+
+## Working with callbacks
+
+### Preload an image with cleanup
+
+Trigger the preload in an effect and unload on teardown so event listeners never leak.
+
+```tsx
+const { state, handleImageLoad, handleImageUnload } = useAvatar();
+
+React.useEffect(() => {
+    handleImageLoad('https://example.com/photo.png');
+    return () => handleImageUnload();
+}, []);
+```
+
+### Render a fallback until the image resolves
+
+Use `state.load` to decide between the real image and initials, an icon, or a placeholder.
+
+```tsx
+<div {...rootProps}>{state.load ? <img src="https://example.com/photo.png" alt="User" /> : <span>AB</span>}</div>
+```
+
+### Avoid flash on fast networks
+
+Set `delayDuration` so the loaded image only appears after the given delay, which keeps the UI stable when images resolve almost instantly.
+
+```tsx
+const avatar = useAvatar({ delayDuration: 300 });
+```
+
+### Group avatars with shared styling
+
+Wrap a set of avatars in an element spread with `useAvatarGroup`'s `rootProps` to share layout data attributes.
+
+```tsx
+const { rootProps: groupRootProps } = useAvatarGroup();
+
+<div {...groupRootProps}>{/* multiple avatar elements */}</div>;
+```
+
+## Styling with data attributes
+
+Every prop object includes `data-scope` and `data-part` attributes you can target directly from CSS.
+
+```css
+[data-scope='avatar'][data-part='root'] {
+    width: 3rem;
+    height: 3rem;
+    border-radius: 50%;
+    overflow: hidden;
+}
+
+[data-scope='avatargroup'][data-part='root'] {
+    display: flex;
+    align-items: center;
+}
+
+[data-scope='avatargroup'][data-part='root'] > [data-scope='avatar'] {
+    margin-left: -0.75rem;
+}
+```
+
+## API
+
+### useAvatar
+
+<DocTable name="useAvatar" category="api" />
+
+### useAvatarGroup
+
+<DocTable name="useAvatarGroup" category="api" />
+
+## Accessibility
+
+Static visual element, use aria-label for screen reader descriptions. See [Primitive](/docs/primitive/components/avatar#accessibility) for full WAI-ARIA compliance details.

package/data/llms/headless/components/badge/api.json

@@ -0,0 +1,68 @@
+[
+  {
+    "name": "useBadge",
+    "source": "apps/showcase/assets/apidoc/usebadge.json",
+    "data": {
+      "description": "The useBadge manages the state and functionality of a badge component.",
+      "interfaces": {
+        "UseBadgeProps": {
+          "description": "Defines valid properties in useBadge.",
+          "relatedProp": "",
+          "props": [],
+          "methods": []
+        },
+        "UseBadgeState": {
+          "description": "Defines valid state in useBadge.",
+          "relatedProp": "",
+          "props": [],
+          "methods": []
+        },
+        "UseBadgeRootProps": {
+          "description": "Data attribute props for the Badge root element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "data-scope",
+              "type": "string",
+              "default": "",
+              "description": "Component scope identifier."
+            },
+            {
+              "name": "data-part",
+              "type": "string",
+              "default": "",
+              "description": "Component part identifier."
+            },
+            {
+              "name": "data-empty",
+              "type": "string",
+              "default": "",
+              "description": "Present when the badge has no children content."
+            }
+          ],
+          "methods": []
+        },
+        "UseBadgeExposes": {
+          "description": "Defines the methods and properties exposed by useBadge.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "rootProps",
+              "type": "UseBadgeRootProps",
+              "default": "",
+              "description": "Pre-built data attribute props for the root element."
+            }
+          ],
+          "methods": []
+        }
+      },
+      "types": {
+        "UseBadgeInstance": {
+          "description": "Instance of useBadge headless.",
+          "values": "HeadlessInstance<UseBadgeProps, UseBadgeState, UseBadgeExposes>"
+        }
+      },
+      "variables": {}
+    }
+  }
+]