@primereact/mcp 11.0.0-rc.2

package/data/llms/hooks/gettingstarted/setup.md

@@ -0,0 +1,54 @@
+# Setup
+
+Install @primereact/hooks and start using it in any React project.
+
+## Install
+
+`@primereact/hooks` is a standalone package. Install it on its own:
+
+```bash
+npm install @primereact/hooks
+```
+
+If you already use `primereact`, the hooks are bundled, you don't need a separate install, but you can still depend on `@primereact/hooks` directly if you prefer explicit versioning.
+
+Peer dependency: **React 18+**.
+
+## Import
+
+Each hook has its own sub-path entry for optimal tree-shaking:
+
+```tsx
+import { useFilter } from '@primereact/hooks/use-filter';
+import { useLocalStorage } from '@primereact/hooks/use-local-storage';
+import { useMatchMedia } from '@primereact/hooks/use-match-media';
+```
+
+The root entry re-exports everything when convenience matters more than the last few bytes:
+
+```tsx
+import { useFilter, useLocalStorage } from '@primereact/hooks';
+```
+
+## TypeScript
+
+Types ship with the package. Generic hooks infer from the data you pass in:
+
+```tsx
+interface Customer {
+    id: number;
+    name: string;
+    country: string;
+}
+
+const { filteredData } = useFilter<Customer>({
+    data: customers,
+    field: 'name',
+    value: query
+});
+// filteredData is Customer[]
+```
+
+## SSR / Next.js
+
+Hooks can be imported from server components without extra setup. Any file that touches the DOM is marked `'use client'` internally, so it moves to the client boundary on demand.

package/data/llms/hooks/use-attr-selector.md

@@ -0,0 +1,25 @@
+# useAttrSelector
+
+Produce a stable, unique string from React.useId, handy for scoping CSS and DOM selectors.
+
+## Usage
+
+```tsx
+import { useAttrSelector } from '@primereact/hooks/use-attr-selector';
+```
+
+```tsx
+const selector = useAttrSelector('panel-'); // e.g. "panel-r0"
+```
+
+Pass an optional prefix; the hook strips colons and other delimiters React adds to `useId()` so the result is safe to use inside attribute selectors like `[data-scope="panel-r0"]`.
+
+## Signature
+
+```ts
+function useAttrSelector(prefix?: string): string;
+```
+
+## When to use it
+
+Reach for this when you need a unique string that also works as a CSS selector fragment, scoped styles, data attributes, or query targets inside a single component instance.

package/data/llms/hooks/use-controlled-state.md

@@ -0,0 +1,31 @@
+# useControlledState
+
+State that works controlled or uncontrolled, following the React convention of value + onChange with a defaultValue fallback.
+
+## Usage
+
+```tsx
+import { useControlledState } from '@primereact/hooks/use-controlled-state';
+```
+
+```tsx
+const [value, setValue, isControlled] = useControlledState({
+    value: props.value,
+    defaultValue: props.defaultValue,
+    onChange: props.onChange
+});
+```
+
+When the parent passes `value`, the hook stays controlled and delegates every update through `onChange`. When `value` is `undefined`, it owns the state internally, `defaultValue` seeds the first render.
+
+## Signature
+
+```ts
+function useControlledState<T, E = T>(options: { value?: T; defaultValue?: T; onChange?: (next: E) => void }): [T | undefined, (next: T | ((prev?: T) => T)) => void, boolean];
+```
+
+The returned tuple is `[value, setValue, isControlled]`. `isControlled` is a boolean frozen at mount, matching how React decides controlled vs uncontrolled inputs.
+
+## When to use it
+
+Any reusable component that exposes both `value` / `onChange` and a `defaultValue`. This hook handles the glue so you don't branch on `value === undefined` everywhere.

package/data/llms/hooks/use-event-listener.md

@@ -0,0 +1,37 @@
+# useEventListener
+
+Attach DOM event listeners declaratively, with automatic cleanup and a bind/unbind pair for manual control.
+
+## Usage
+
+```tsx
+import { useEventListener } from '@primereact/hooks/use-event-listener';
+```
+
+```tsx
+const [bind, unbind] = useEventListener({
+    target: 'document',
+    type: 'click',
+    listener: (event) => console.log(event),
+    when: true
+});
+```
+
+The listener is attached when `when` is `true` and torn down automatically on unmount. Toggle `when` to pause without unmounting.
+
+## Options
+
+- `target`, `'document' | 'window' | 'body' | HTMLElement | (() => HTMLElement) | Ref | string | null`. Accepts a selector string, a ref, or a function that resolves the element on demand.
+- `type`, event name, e.g. `'click'`, `'keydown'`, or a custom event.
+- `listener`, handler function.
+- `options?`, standard `addEventListener` options (`capture`, `passive`, `once`).
+- `when?`, defaults to `true`; set `false` to disable.
+
+## Manual control
+
+The returned `[bind, unbind]` lets you attach/detach imperatively, useful when you want to listen in response to a user action rather than a prop:
+
+```tsx
+<button onClick={() => bind()}>Listen</button>
+<button onClick={() => unbind()}>Stop</button>
+```

package/data/llms/hooks/use-filter.md

@@ -0,0 +1,312 @@
+# useFilter
+
+Generic filter hook for flat collections, with built-in match modes, accent-insensitive matching, locale support, and custom matcher registration.
+
+## Usage
+
+```tsx
+import { useFilter } from '@primereact/hooks/use-filter';
+```
+
+```tsx
+const { filteredData, value, setValue, isFiltered } = useFilter({
+    data: products,
+    field: ['name', 'category'],
+    matchMode: 'contains'
+});
+```
+
+`useFilter` is a framework-level hook from `@primereact/hooks` that takes arbitrary data plus one or more filter rules and returns the filtered result. The same built-in matcher registry powers DataTable's filter feature, so behaviour stays consistent across any component built on top of it.
+
+## Signature
+
+```ts
+function useFilter<T, TMode extends string = BuiltInMatchMode>(options: UseFilterOptions<T, TMode>): UseFilterReturn<T, TMode>;
+```
+
+## Rules
+
+A rule targets one field (or an array of fields for multi-field search) with a value and a match mode.
+
+```tsx
+defaultRules: [
+    { field: 'name', value: 'iphone', matchMode: 'startsWith' },
+    { field: ['name', 'category', 'description'], value: 'blue' },
+    { field: 'price', value: [100, 500], matchMode: 'between' }
+];
+```
+
+Composite rules carry multiple constraints tied by an AND/OR operator:
+
+```tsx
+{
+    field: 'name',
+    operator: 'and',
+    constraints: [
+        { value: 'A', matchMode: 'startsWith' },
+        { value: 'Z', matchMode: 'notEquals' }
+    ]
+}
+```
+
+## Basic
+
+For the common "single field/multi-field search" case you can skip the `rules` array and use the `field` / `value` / `matchMode` shorthand.
+
+```tsx
+'use client';
+import { ProductService, type Product } from '@/shared/services/product.service';
+import { Search } from '@primeicons/react/search';
+import { useFilter } from '@primereact/hooks/use-filter';
+import { IconField } from '@primereact/ui/iconfield';
+import { InputText } from '@primereact/ui/inputtext';
+import { Tag } from '@primereact/ui/tag';
+import Image from 'next/image';
+import * as React from 'react';
+
+const statusSeverity: Record<string, 'success' | 'warn' | 'danger'> = {
+    INSTOCK: 'success',
+    LOWSTOCK: 'warn',
+    OUTOFSTOCK: 'danger'
+};
+
+export default function BasicDemo() {
+    const [products, setProducts] = React.useState<Product[]>([]);
+
+    React.useEffect(() => {
+        setProducts(ProductService.getProductsData().slice(0, 12));
+    }, []);
+
+    const [search, setSearch] = React.useState('');
+
+    const { filteredData } = useFilter<Product>({
+        data: products,
+        field: ['name', 'category', 'code'],
+        value: search,
+        matchMode: 'contains'
+    });
+
+    return (
+        <div className="w-full flex flex-col gap-3">
+            <IconField.Root className="w-full sm:max-w-sm">
+                <IconField.Inset>
+                    <Search />
+                </IconField.Inset>
+                <InputText
+                    type="search"
+                    placeholder="Search name, category, code..."
+                    value={search}
+                    onChange={(e: any) => setSearch(e.target.value)}
+                    className="w-full"
+                />
+            </IconField.Root>
+            <div className="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 gap-3">
+                {filteredData.map((item) => (
+                    <div key={item.id} className="p-3 border border-surface-200 dark:border-surface-700 rounded-md flex items-center gap-3">
+                        <div className="relative shrink-0 w-12 h-12 rounded-md shadow overflow-hidden">
+                            <Image
+                                src={`https://primefaces.org/cdn/primevue/images/product/${item.image}`}
+                                alt={item.name}
+                                fill
+                                sizes="48px"
+                                className="object-cover"
+                            />
+                        </div>
+                        <div className="flex flex-col gap-1 flex-1 min-w-0">
+                            <span className="font-medium truncate">{item.name}</span>
+                            <span className="text-xs text-surface-500 dark:text-surface-400 truncate">{item.code}</span>
+                            <div className="flex flex-wrap items-center gap-2 mt-1">
+                                <Tag severity="secondary">{item.category}</Tag>
+                                <Tag severity={statusSeverity[item.inventoryStatus] ?? 'secondary'}>{item.inventoryStatus}</Tag>
+                            </div>
+                        </div>
+                    </div>
+                ))}
+            </div>
+            {filteredData.length === 0 && (
+                <div className="p-4 text-center text-sm text-surface-500 dark:text-surface-400">No products match the search.</div>
+            )}
+        </div>
+    );
+}
+```
+
+## Advanced, multi-rule + custom matcher
+
+Pass `matchers` to register an ad-hoc matcher for a single hook instance. The cursor API (`rule(index)`) gives a typed handle per rule.
+
+```tsx
+'use client';
+import { ProductService, type Product } from '@/shared/services/product.service';
+import { ChevronDown } from '@primeicons/react/chevron-down';
+import { Search } from '@primeicons/react/search';
+import { useFilter, type FilterMatcher } from '@primereact/hooks/use-filter';
+import { Button } from '@primereact/ui/button';
+import { IconField } from '@primereact/ui/iconfield';
+import { InputText } from '@primereact/ui/inputtext';
+import { Select, type SelectValueChangeEvent } from '@primereact/ui/select';
+import { Tag } from '@primereact/ui/tag';
+import * as React from 'react';
+
+const statusOptions = [
+    { label: 'All statuses', value: '' },
+    { label: 'In Stock', value: 'INSTOCK' },
+    { label: 'Low Stock', value: 'LOWSTOCK' },
+    { label: 'Out of Stock', value: 'OUTOFSTOCK' }
+];
+
+const extraMatchers: Record<string, FilterMatcher> = {
+    expensive: (value) => Number(value) >= 100
+};
+
+export default function AdvancedDemo() {
+    const [products, setProducts] = React.useState<Product[]>([]);
+
+    React.useEffect(() => {
+        setProducts(ProductService.getProductsData().slice(0, 12));
+    }, []);
+
+    const { filteredData, rule, isFiltered, clearAll } = useFilter<Product, 'contains' | 'equals' | 'expensive'>({
+        data: products,
+        defaultRules: [
+            { field: 'name', value: null, matchMode: 'contains' },
+            { field: 'inventoryStatus', value: null, matchMode: 'equals' },
+            { field: 'price', value: null, matchMode: 'expensive' }
+        ],
+        matchers: extraMatchers
+    });
+
+    const nameRule = rule(0);
+    const statusRule = rule(1);
+    const priceRule = rule(2);
+
+    return (
+        <div className="w-full flex flex-col gap-3">
+            <div className="flex flex-wrap items-center gap-2">
+                <IconField.Root className="w-full sm:w-auto sm:flex-1 sm:max-w-xs">
+                    <IconField.Inset>
+                        <Search />
+                    </IconField.Inset>
+                    <InputText
+                        type="search"
+                        placeholder="Name contains..."
+                        size="small"
+                        value={(nameRule?.value as string) ?? ''}
+                        onChange={(e: any) => nameRule?.setValue(e.target.value)}
+                        className="w-full"
+                    />
+                </IconField.Root>
+
+                <Select.Root
+                    value={(statusRule?.value as string) ?? ''}
+                    onValueChange={(e: SelectValueChangeEvent) => statusRule?.setValue(e.value || null)}
+                    options={statusOptions}
+                    optionLabel="label"
+                    optionValue="value"
+                    size="small"
+                >
+                    <Select.Trigger className="w-full sm:w-40">
+                        <Select.Value placeholder="Status" />
+                        <Select.Indicator>
+                            <ChevronDown />
+                        </Select.Indicator>
+                    </Select.Trigger>
+                    <Select.Portal>
+                        <Select.Positioner>
+                            <Select.Popup>
+                                <Select.List />
+                            </Select.Popup>
+                        </Select.Positioner>
+                    </Select.Portal>
+                </Select.Root>
+
+                <Button
+                    variant={priceRule?.value === true ? undefined : 'outlined'}
+                    severity={priceRule?.value === true ? 'primary' : 'secondary'}
+                    size="small"
+                    onClick={() => priceRule?.setValue(priceRule?.value === true ? null : true)}
+                >
+                    ≥ $100
+                </Button>
+
+                {isFiltered && (
+                    <Button variant="text" size="small" onClick={clearAll}>
+                        Clear
+                    </Button>
+                )}
+            </div>
+
+            <div className="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 gap-3">
+                {filteredData.map((item) => (
+                    <div key={item.id} className="p-3 border border-surface-200 dark:border-surface-700 rounded-md flex flex-col gap-1">
+                        <span className="font-medium">{item.name}</span>
+                        <span className="text-xs text-surface-500 dark:text-surface-400">{item.code}</span>
+                        <div className="flex items-center justify-between mt-2">
+                            <Tag severity="secondary">{item.category}</Tag>
+                            <span className="font-semibold">${item.price}</span>
+                        </div>
+                    </div>
+                ))}
+            </div>
+            {filteredData.length === 0 && (
+                <div className="p-4 text-center text-sm text-surface-500 dark:text-surface-400">No products match the filters.</div>
+            )}
+        </div>
+    );
+}
+```
+
+## Global matcher registry
+
+For matchers you want available everywhere, `registerMatcher` writes into a shared table the hook consults alongside the built-ins.
+
+```tsx
+import { registerMatcher } from '@primereact/hooks/use-filter';
+
+registerMatcher('greaterThanAvg', (value, filter) => Number(value) > Number(filter));
+```
+
+Local `matchers` option always wins when both are present. Call `unregisterMatcher(name)` to remove an entry (useful in tests).
+
+## Lazy (server-side)
+
+Set `lazy: true` to skip client-side filtering. `filteredData` is returned unchanged. Whenever the rules settle (respecting `filterDelay`), `onLazyLoad` fires with the current rule set, typically you turn that into a request and replace `data` with the server response.
+
+```tsx
+const [data, setData] = React.useState<Customer[]>([]);
+const [query, setQuery] = React.useState('');
+
+useFilter<Customer>({
+    data,
+    lazy: true,
+    field: ['name', 'country'],
+    value: query,
+    onValueChange: (v) => setQuery((v as string) ?? ''),
+    filterDelay: 300,
+    onLazyLoad: async ({ rules }) => {
+        const res = await fetch('/api/customers?' + toQuery(rules));
+        setData(await res.json());
+    }
+});
+```
+
+## Cursor API
+
+Setters by index:
+
+```tsx
+const { setValue, setMatchMode, setOperator, setConstraintValue } = useFilter({ ... });
+
+setValue(0, 'amy');
+setConstraintValue(0, 1, 'Z');
+```
+
+Or scoped by rule:
+
+```tsx
+const { rule } = useFilter({ ... });
+
+rule(0)?.setValue('amy');
+rule('name')?.addConstraint('equals');
+rule('name')?.constraint(1)?.setValue('Z');
+```

package/data/llms/hooks/use-hot-key.md

@@ -0,0 +1,40 @@
+# useHotKey
+
+Bind keyboard shortcuts with modifier combinations, single key or array of keys, with enable flag for scoping.
+
+## Usage
+
+```tsx
+import { useHotKey } from '@primereact/hooks/use-hot-key';
+```
+
+```tsx
+useHotKey('ctrl+k', (event) => {
+    event.preventDefault();
+    openCommandPalette();
+});
+```
+
+Modifiers are case-insensitive and accept aliases: `ctrl`/`control`, `cmd`/`meta`/`command`, `alt`/`option`, `shift`. The special strings `space` and `spacebar` resolve to the space key.
+
+Pass an array of specs to bind multiple shortcuts to the same handler:
+
+```tsx
+useHotKey(['ctrl+k', 'meta+k'], openCommandPalette);
+```
+
+## Signature
+
+```ts
+function useHotKey(
+    keys: string | string[],
+    handler: (event: KeyboardEvent) => void,
+    options?: {
+        target?: Document | HTMLElement | null;
+        event?: 'keydown' | 'keyup' | 'keypress';
+        when?: boolean;
+    }
+): void;
+```
+
+Defaults: listens on `document` for `keydown` while `when` is true. Pass a target element to scope shortcuts to a specific region.

package/data/llms/hooks/use-id.md

@@ -0,0 +1,24 @@
+# useId
+
+Stable unique identifier with an optional explicit override.
+
+## Usage
+
+```tsx
+import { useId } from '@primereact/hooks/use-id';
+```
+
+```tsx
+const id = useId(); // e.g. "pr_id_r0"
+const fixed = useId('my-panel'); // "my-panel"
+```
+
+Pass a value to opt out of the generated id, useful for components that accept an optional `id` prop but need a fallback.
+
+## Signature
+
+```ts
+function useId(initialValue?: string): string;
+```
+
+Internally wraps `React.useId()` and strips the characters React inserts (`:`, `«`, `»`) so the result is safe to use in selectors and HTML attributes.

package/data/llms/hooks/use-intersection-observer.md

@@ -0,0 +1,42 @@
+# useIntersectionObserver
+
+A thin wrapper over the IntersectionObserver API with imperative observe/unobserve controls.
+
+## Usage
+
+```tsx
+import { useIntersectionObserver } from '@primereact/hooks/use-intersection-observer';
+```
+
+```tsx
+const ref = React.useRef<HTMLDivElement>(null);
+const { observe, isIntersecting } = useIntersectionObserver({
+    threshold: 0.5,
+    onIntersect: (entries) => console.log(entries)
+});
+
+React.useEffect(() => {
+    if (ref.current) observe(ref.current);
+}, [observe]);
+
+return <div ref={ref}>{isIntersecting ? 'visible' : 'off-screen'}</div>;
+```
+
+## Options
+
+Standard `IntersectionObserverInit` fields (`root`, `rootMargin`, `threshold`) plus:
+
+- `disabled?`, skip creating the observer entirely.
+- `onIntersect?(entries, observer)`, called on every intersection change.
+- `fallback?()`, invoked when `IntersectionObserver` is unavailable.
+
+## Returns
+
+- `entries`, current entries from the last callback.
+- `isIntersecting`, `true` if any observed element is intersecting.
+- `observe(el)`, `unobserve(el)`, `disconnect()`, imperative controls.
+- `observer`, the underlying `IntersectionObserver` instance (or `null` when disabled).
+
+## When to use it
+
+Pick this hook when you need direct control, observing multiple elements, toggling dynamically, or integrating with virtualization. For simple "is this one element visible" cases, you may prefer the lighter-weight visibility patterns built on top of it.

package/data/llms/hooks/use-is-mobile.md

@@ -0,0 +1,24 @@
+# useIsMobile
+
+Boolean flag that flips when the viewport crosses a mobile breakpoint.
+
+## Usage
+
+```tsx
+import { useIsMobile } from '@primereact/hooks/use-is-mobile';
+```
+
+```tsx
+const isMobile = useIsMobile(); // default breakpoint: 768px
+const isTablet = useIsMobile(1024); // custom breakpoint
+```
+
+Returns `true` when the viewport width is **below** the breakpoint. Implemented on top of `useMatchMedia`, so it updates live as the window resizes.
+
+## Signature
+
+```ts
+function useIsMobile(breakpoint?: number): boolean;
+```
+
+Default breakpoint is 768px. Pass any max-width you care about, the hook resolves the corresponding media query for you.