@primereact/mcp 11.0.0-rc.2

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

@@ -0,0 +1,262 @@
+# useSelect
+
+Hook that manages select dropdown state, keyboard navigation, and popup positioning.
+
+```tsx
+'use client';
+import { Check } from '@primeicons/react/check';
+import { ChevronDown } from '@primeicons/react/chevron-down';
+import { useListboxOption } from '@primereact/headless/listbox';
+import { usePortal } from '@primereact/headless/portal';
+import { usePositioner } from '@primereact/headless/positioner';
+import { useSelect } from '@primereact/headless/select';
+import type { UseListboxInstance } from '@primereact/types/headless/listbox';
+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="group flex items-center gap-2 px-2.5 py-1.5 my-1 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"
+        >
+            <span className="flex items-center justify-center w-4 h-4 invisible group-data-[selected]:visible">
+                <Check className="w-3.5 h-3.5" />
+            </span>
+            <span>{listbox.getOptionLabel(option)}</span>
+        </li>
+    );
+}
+
+export default function BasicDemo() {
+    const select = useSelect({ options: countries, optionLabel: 'name' });
+    const { rootProps, triggerProps, indicatorProps, listProps, positionerProps, popupProps, state, listbox, getSelectedOptionLabel } = select;
+    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">
+                <button
+                    {...triggerProps}
+                    className="flex items-center justify-between w-full px-3 py-2 text-sm border border-surface-200 dark:border-surface-700 rounded-lg bg-transparent cursor-pointer select-none text-surface-700 dark:text-surface-0 transition-[border-color] duration-200 hover:border-surface-300 dark:hover:border-surface-600 focus-visible:outline-1 focus-visible:outline-primary focus-visible:-outline-offset-1"
+                >
+                    <span className={getSelectedOptionLabel() ? '' : 'text-surface-400'}>
+                        {(getSelectedOptionLabel() as string) ?? 'Select a Country'}
+                    </span>
+                    <span {...indicatorProps} className="flex items-center transition-transform duration-200 data-open:rotate-180">
+                        <ChevronDown className="w-4 h-4" />
+                    </span>
+                </button>
+                {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>
+                            </div>
+                        </div>,
+                        document.body
+                    )}
+            </div>
+        </div>
+    );
+}
+
+const countries = [
+    { name: 'Argentina', code: 'AR' },
+    { name: 'Australia', code: 'AU' },
+    { name: 'Brazil', code: 'BR' },
+    { name: 'Canada', code: 'CA' },
+    { name: 'China', code: 'CN' },
+    { name: 'Egypt', code: 'EG' },
+    { name: 'France', code: 'FR' },
+    { name: 'Germany', code: 'DE' },
+    { name: 'India', code: 'IN' },
+    { name: 'Italy', code: 'IT' },
+    { name: 'Japan', code: 'JP' },
+    { name: 'Mexico', code: 'MX' },
+    { name: 'Netherlands', code: 'NL' },
+    { name: 'Norway', code: 'NO' },
+    { name: 'Poland', code: 'PL' },
+    { name: 'South Korea', code: 'KR' },
+    { name: 'Spain', code: 'ES' },
+    { name: 'Sweden', code: 'SE' },
+    { name: 'Switzerland', code: 'CH' },
+    { name: 'Turkey', code: 'TR' },
+    { name: 'United Kingdom', code: 'GB' },
+    { name: 'United States', code: 'US' }
+];
+```
+
+## Usage
+
+```tsx
+import { useSelect } from '@primereact/headless/select';
+```
+
+```tsx
+const select = useSelect({ options: cities, optionLabel: 'name' });
+const { rootProps, triggerProps, listProps, positionerProps, popupProps, arrowProps, state, listbox } = select;
+```
+
+`useSelect` composes `useListbox` and `usePopover` internally. See [Primitive](/docs/primitive/components/select) for a component-based API.
+
+## Features
+
+- **Popup lifecycle**, open/close state, positioning, focus trap, and Escape/outside-click dismissal
+- **Listbox integration**, option iteration, selection, and keyboard navigation via the returned `listbox` instance
+- **Controlled or uncontrolled**, value, popup visibility, and filter text can each be managed externally or internally
+- **Filtering**, dedicated `filterProps` for a search input inside the popup with locale-aware comparison
+- **Selection modes**, single, multiple, and meta-key-based additive selection
+- **Imperative controls**, `show()`, `hide()`, `toggle()`, `focus()`, `getSelectedOptionLabel()`, and `hasValue()`
+
+## Working with callbacks
+
+### Controlled selection
+
+Pass `value` and `onValueChange` to drive the selection from outside state.
+
+```tsx
+const [selected, setSelected] = React.useState(null);
+
+const select = useSelect({
+    value: selected,
+    onValueChange: (e) => setSelected(e.value)
+});
+
+<div {...rootProps}>
+    <button {...triggerProps}></button>
+    <div {...positionerProps}>
+        <div {...popupProps}>
+            <ul {...listProps}></ul>
+        </div>
+        <div {...arrowProps} />
+    </div>
+</div>;
+```
+
+### Controlled popup visibility
+
+Use `open` with `onOpenChange` to react to open/close transitions, useful for analytics, coordinating with other overlays, or animating custom wrappers.
+
+```tsx
+const [open, setOpen] = React.useState(false);
+
+const select = useSelect({
+    options: cities,
+    optionLabel: 'name',
+    open,
+    onOpenChange: (e) => setOpen(e.value)
+});
+```
+
+### Filtering inside the popup
+
+Render a search input wired through `filterProps` and drive the query with `filterValue` / `onFilterValueChange`.
+
+```tsx
+const [filterValue, setFilterValue] = React.useState('');
+
+const select = useSelect({
+    options: cities,
+    optionLabel: 'name',
+    filterValue,
+    onFilterValueChange: (e) => setFilterValue(e.query)
+});
+
+<input {...select.filterProps} placeholder="Search..." />;
+```
+
+### Object options with grouping
+
+Map object fields with `optionLabel`, `optionValue`, `optionDisabled`, and `optionKey`; add `optionGroupLabel` / `optionGroupChildren` for grouped structures.
+
+```tsx
+const select = useSelect({
+    options: groupedCities,
+    optionLabel: 'label',
+    optionValue: 'code',
+    optionDisabled: 'inactive',
+    optionKey: 'code',
+    optionGroupLabel: 'label',
+    optionGroupChildren: 'items'
+});
+```
+
+### Multiple selection with meta key
+
+Combine `multiple` and `metaKeySelection` to require Cmd/Ctrl for additive selection, matching native multi-select semantics.
+
+```tsx
+const select = useSelect({ multiple: true, metaKeySelection: true });
+```
+
+## 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                                                              |
+| --------- | ----------------- | ------------------------------------------------------------------- |
+| `select`  | `trigger`         | `data-positioner-open`                                              |
+| `select`  | `popup`           | `data-open`                                                         |
+| `select`  | `indicator`       | `data-open`, `data-closed`                                          |
+| `listbox` | `option`          | `data-selected`, `data-unselected`, `data-focused`, `data-disabled` |
+| `listbox` | `optionindicator` | `data-selected`, `data-unselected`                                  |
+
+```css
+[data-scope='select'][data-part='trigger']:focus-visible {
+    outline: 2px solid var(--p-primary-color);
+    outline-offset: -2px;
+}
+
+[data-scope='select'][data-part='indicator'][data-open] {
+    transform: rotate(180deg);
+}
+
+[data-scope='select'][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);
+}
+
+[data-scope='listbox'][data-part='option'][data-selected] {
+    background: var(--p-primary-color);
+    color: var(--p-primary-contrast-color);
+}
+```
+
+## API
+
+### useSelect
+
+<DocTable name="useSelect" category="api" />
+
+## Accessibility
+
+Arrow keys move focus through options, Enter or Space selects, Home/End jump to first/last, and type-ahead search matches by label. See [Primitive](/docs/primitive/components/select#accessibility) for full WAI-ARIA compliance details.

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

@@ -0,0 +1,433 @@
+[
+  {
+    "name": "useSidebar",
+    "source": "apps/showcase/assets/apidoc/usesidebar.json",
+    "data": {
+      "description": "The useSidebar manages the state and functionality of a sidebar component.",
+      "interfaces": {
+        "UseSidebarOpenChangeEvent": {
+          "description": "Event fired when the sidebar's open state changes.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "originalEvent",
+              "type": "E",
+              "default": "",
+              "description": "The original event that triggered the change, if any."
+            },
+            {
+              "name": "value",
+              "type": "boolean",
+              "default": "",
+              "description": "The value of the sidebar open state."
+            }
+          ],
+          "methods": []
+        },
+        "UseSidebarProps": {
+          "description": "Defines valid properties in useSidebar.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "layout",
+              "type": "UseSidebarLayoutExposes",
+              "default": "",
+              "description": "Layout context for registering/notifying within a Sidebar.Layout."
+            },
+            {
+              "name": "id",
+              "type": "string",
+              "default": "",
+              "description": "Unique identifier for the sidebar, used by Trigger target."
+            },
+            {
+              "name": "side",
+              "type": "\"left\" | \"right\"",
+              "default": "'left'",
+              "description": "Sidebar position."
+            },
+            {
+              "name": "variant",
+              "type": "\"sidebar\" | \"floating\" | \"inset\"",
+              "default": "'sidebar'",
+              "description": "Visual variant of the sidebar."
+            },
+            {
+              "name": "collapsible",
+              "type": "\"icon\" | \"none\" | \"offcanvas\"",
+              "default": "'icon'",
+              "description": "Collapse behavior."
+            },
+            {
+              "name": "overlay",
+              "type": "boolean",
+              "default": "false",
+              "description": "Whether the sidebar overlays content instead of pushing it."
+            },
+            {
+              "name": "open",
+              "type": "boolean",
+              "default": "",
+              "description": "Controls the open state of the sidebar."
+            },
+            {
+              "name": "defaultOpen",
+              "type": "boolean",
+              "default": "true",
+              "description": "Initial open state."
+            },
+            {
+              "name": "onOpenChange",
+              "type": "(event: UseSidebarOpenChangeEvent) => void",
+              "default": "",
+              "description": "Callback when the open state changes."
+            },
+            {
+              "name": "openOnHover",
+              "type": "boolean",
+              "default": "false",
+              "description": "Whether the sidebar opens on hover."
+            },
+            {
+              "name": "hoverOpenDelay",
+              "type": "number",
+              "default": "50",
+              "description": "Delay before opening on hover (ms)."
+            },
+            {
+              "name": "hoverCloseDelay",
+              "type": "number",
+              "default": "100",
+              "description": "Delay before closing on hover leave (ms)."
+            },
+            {
+              "name": "dismissable",
+              "type": "boolean",
+              "default": "true",
+              "description": "Whether clicking the backdrop closes the sidebar."
+            },
+            {
+              "name": "hideOnOutsideClick",
+              "type": "boolean",
+              "default": "true",
+              "description": "When  `overlay`  is true, clicking inside the  `Sidebar.Main`  area collapses the sidebar.\nClicks on a  `Sidebar.Trigger`  are excluded so opening via the trigger is not immediately undone."
+            },
+            {
+              "name": "closeOnEscape",
+              "type": "boolean",
+              "default": "true",
+              "description": "When  `overlay`  is true, pressing Escape collapses the sidebar."
+            },
+            {
+              "name": "width",
+              "type": "string",
+              "default": "'16rem'",
+              "description": "Sidebar width when expanded."
+            },
+            {
+              "name": "iconWidth",
+              "type": "string",
+              "default": "'3rem'",
+              "description": "Sidebar width when collapsed to icon mode."
+            }
+          ],
+          "methods": []
+        },
+        "UseSidebarState": {
+          "description": "Defines valid state in useSidebar.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "open",
+              "type": "boolean",
+              "default": ""
+            },
+            {
+              "name": "displayState",
+              "type": "\"expanded\" | \"collapsed\"",
+              "default": ""
+            }
+          ],
+          "methods": []
+        },
+        "UseSidebarExposes": {
+          "description": "Defines the methods and properties exposed by useSidebar.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "state",
+              "type": "UseSidebarState",
+              "default": ""
+            },
+            {
+              "name": "toggle",
+              "type": "(event?: SyntheticEvent) => void",
+              "default": ""
+            },
+            {
+              "name": "expand",
+              "type": "(event?: SyntheticEvent) => void",
+              "default": ""
+            },
+            {
+              "name": "collapse",
+              "type": "(event?: SyntheticEvent) => void",
+              "default": ""
+            },
+            {
+              "name": "rootProps",
+              "type": "Record<string, unknown>",
+              "default": ""
+            },
+            {
+              "name": "spacerProps",
+              "type": "Record<string, unknown>",
+              "default": ""
+            },
+            {
+              "name": "asideProps",
+              "type": "Record<string, unknown>",
+              "default": ""
+            },
+            {
+              "name": "panelProps",
+              "type": "Record<string, unknown>",
+              "default": ""
+            },
+            {
+              "name": "contentProps",
+              "type": "Record<string, unknown>",
+              "default": ""
+            },
+            {
+              "name": "headerProps",
+              "type": "Record<string, unknown>",
+              "default": ""
+            },
+            {
+              "name": "footerProps",
+              "type": "Record<string, unknown>",
+              "default": ""
+            },
+            {
+              "name": "triggerProps",
+              "type": "Record<string, unknown>",
+              "default": ""
+            },
+            {
+              "name": "railProps",
+              "type": "Record<string, unknown>",
+              "default": ""
+            },
+            {
+              "name": "mainProps",
+              "type": "Record<string, unknown>",
+              "default": ""
+            },
+            {
+              "name": "backdropProps",
+              "type": "Record<string, unknown>",
+              "default": ""
+            },
+            {
+              "name": "variant",
+              "type": "\"sidebar\" | \"floating\" | \"inset\"",
+              "default": ""
+            },
+            {
+              "name": "collapsible",
+              "type": "\"icon\" | \"none\" | \"offcanvas\"",
+              "default": ""
+            },
+            {
+              "name": "side",
+              "type": "\"left\" | \"right\"",
+              "default": ""
+            },
+            {
+              "name": "overlay",
+              "type": "boolean",
+              "default": ""
+            },
+            {
+              "name": "openOnHover",
+              "type": "boolean",
+              "default": ""
+            }
+          ],
+          "methods": []
+        }
+      },
+      "types": {
+        "UseSidebarInstance": {
+          "description": "Instance of useSidebar headless.",
+          "values": "HeadlessInstance<UseSidebarProps, UseSidebarState, UseSidebarExposes>"
+        }
+      },
+      "variables": {}
+    }
+  },
+  {
+    "name": "useSidebarLayout",
+    "source": "apps/showcase/assets/apidoc/usesidebarlayout.json",
+    "data": {
+      "description": "",
+      "interfaces": {
+        "UseSidebarLayoutProps": {
+          "description": "",
+          "relatedProp": "",
+          "props": [],
+          "methods": []
+        },
+        "UseSidebarLayoutState": {
+          "description": "",
+          "relatedProp": "",
+          "props": [],
+          "methods": []
+        },
+        "UseSidebarLayoutExposes": {
+          "description": "",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "setSidebar",
+              "type": "(id: string, entry: SidebarRegistryEntry) => void",
+              "default": "",
+              "description": "Publish a sidebar entry to the layout. Pass  `null`  to remove the sidebar\n(called from the cleanup of the publishing effect on unmount)."
+            },
+            {
+              "name": "toggle",
+              "type": "(target?: string, event?: SyntheticEvent) => void",
+              "default": ""
+            },
+            {
+              "name": "collapse",
+              "type": "(target?: string, event?: SyntheticEvent) => void",
+              "default": ""
+            },
+            {
+              "name": "backdropProps",
+              "type": "{ data-scope: \"sidebar\"; data-part: \"backdrop\"; onClick: () => void; data-state: \"open\" | \"closed\" }",
+              "default": ""
+            },
+            {
+              "name": "mainProps",
+              "type": "{ onClick?: (event: MouseEvent) => void; inert?: boolean; aria-hidden?: boolean }",
+              "default": ""
+            },
+            {
+              "name": "backdropMotionProps",
+              "type": "{ visible: boolean }",
+              "default": ""
+            }
+          ],
+          "methods": []
+        }
+      },
+      "types": {
+        "UseSidebarLayoutInstance": {
+          "description": "",
+          "values": "HeadlessInstance<UseSidebarLayoutProps, UseSidebarLayoutState, UseSidebarLayoutExposes>"
+        }
+      },
+      "variables": {}
+    }
+  },
+  {
+    "name": "useSidebarMenuItem",
+    "source": "apps/showcase/assets/apidoc/usesidebarmenuitem.json",
+    "data": {
+      "description": "",
+      "interfaces": {
+        "UseSidebarMenuItemProps": {
+          "description": "",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "collapsible",
+              "type": "boolean",
+              "default": ""
+            },
+            {
+              "name": "open",
+              "type": "boolean",
+              "default": ""
+            },
+            {
+              "name": "defaultOpen",
+              "type": "boolean",
+              "default": ""
+            },
+            {
+              "name": "disabled",
+              "type": "boolean",
+              "default": ""
+            },
+            {
+              "name": "onOpenChange",
+              "type": "(event: { originalEvent: SyntheticEvent; value: boolean }) => void",
+              "default": ""
+            }
+          ],
+          "methods": []
+        },
+        "UseSidebarMenuItemState": {
+          "description": "",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "isCollapsible",
+              "type": "boolean",
+              "default": ""
+            },
+            {
+              "name": "open",
+              "type": "boolean",
+              "default": ""
+            }
+          ],
+          "methods": []
+        },
+        "UseSidebarMenuItemExposes": {
+          "description": "",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "state",
+              "type": "UseSidebarMenuItemState",
+              "default": ""
+            },
+            {
+              "name": "toggle",
+              "type": "(event?: SyntheticEvent) => void",
+              "default": ""
+            },
+            {
+              "name": "triggerProps",
+              "type": "Record<string, unknown>",
+              "default": ""
+            },
+            {
+              "name": "contentProps",
+              "type": "Record<string, unknown>",
+              "default": ""
+            },
+            {
+              "name": "rootProps",
+              "type": "Record<string, unknown>",
+              "default": ""
+            }
+          ],
+          "methods": []
+        }
+      },
+      "types": {
+        "UseSidebarMenuItemInstance": {
+          "description": "",
+          "values": "HeadlessInstance<UseSidebarMenuItemProps, UseSidebarMenuItemState, UseSidebarMenuItemExposes>"
+        }
+      },
+      "variables": {}
+    }
+  }
+]