@primereact/mcp 11.0.0-rc.2

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

@@ -0,0 +1,311 @@
+[
+  {
+    "name": "usePaginator",
+    "source": "apps/showcase/assets/apidoc/usepaginator.json",
+    "data": {
+      "description": "The usePaginator manages the state and functionality of a Paginator component.",
+      "interfaces": {
+        "UsePaginatorChangeEvent": {
+          "description": "Defines the change event object for usePaginator.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "originalEvent",
+              "type": "SyntheticEvent<Element, Event>",
+              "default": "",
+              "description": "The original event that triggered the change."
+            },
+            {
+              "name": "value",
+              "type": "number",
+              "default": "",
+              "description": "The new page number."
+            }
+          ],
+          "methods": []
+        },
+        "UsePaginatorProps": {
+          "description": "Defines valid properties in usePaginator.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "defaultPage",
+              "type": "number",
+              "default": "1",
+              "description": "Default page number."
+            },
+            {
+              "name": "page",
+              "type": "number",
+              "default": "",
+              "description": "Current page number (controlled)."
+            },
+            {
+              "name": "total",
+              "type": "number",
+              "default": "0",
+              "description": "Total number of items."
+            },
+            {
+              "name": "itemsPerPage",
+              "type": "number",
+              "default": "10",
+              "description": "Number of items per page."
+            },
+            {
+              "name": "onPageChange",
+              "type": "(event: UsePaginatorChangeEvent) => void",
+              "default": "",
+              "description": "Callback fired when the page changes."
+            },
+            {
+              "name": "siblings",
+              "type": "number",
+              "default": "2",
+              "description": "Number of sibling pages to show on each side of current page."
+            },
+            {
+              "name": "edges",
+              "type": "number",
+              "default": "1",
+              "description": "Number of edge pages to show at the beginning and end."
+            },
+            {
+              "name": "disabled",
+              "type": "boolean",
+              "default": "false",
+              "description": "Whether the paginator is disabled."
+            },
+            {
+              "name": "showEllipsis",
+              "type": "boolean",
+              "default": "true",
+              "description": "Whether to show ellipsis."
+            }
+          ],
+          "methods": []
+        },
+        "UsePaginatorState": {
+          "description": "Defines valid state in usePaginator.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "activePage",
+              "type": "number",
+              "default": "",
+              "description": "Current active page number."
+            },
+            {
+              "name": "canPrev",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether the previous page is available."
+            },
+            {
+              "name": "canNext",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether the next page is available."
+            },
+            {
+              "name": "totalPages",
+              "type": "number",
+              "default": "",
+              "description": "Total number of pages."
+            }
+          ],
+          "methods": []
+        },
+        "UsePaginatorNavProps": {
+          "description": "Pre-built props for a paginator navigation button.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "onClick",
+              "type": "() => void",
+              "default": "",
+              "description": "Click handler for the navigation button."
+            },
+            {
+              "name": "disabled",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether the button is disabled."
+            },
+            {
+              "name": "aria-label",
+              "type": "string",
+              "default": "",
+              "description": "Accessible label for the navigation button."
+            },
+            {
+              "name": "data-disabled",
+              "type": "string",
+              "default": "",
+              "description": "Data attribute for disabled state."
+            }
+          ],
+          "methods": []
+        },
+        "UsePaginatorPagesProps": {
+          "description": "Pre-built props for the pages container element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "data-scope",
+              "type": "\"paginator\"",
+              "default": ""
+            },
+            {
+              "name": "data-part",
+              "type": "\"pages\"",
+              "default": ""
+            },
+            {
+              "name": "aria-label",
+              "type": "string",
+              "default": "",
+              "description": "Accessible label for the pages container."
+            }
+          ],
+          "methods": []
+        },
+        "UsePaginatorPageProps": {
+          "description": "Pre-built props for a paginator page button.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "onClick",
+              "type": "() => void",
+              "default": "",
+              "description": "Click handler for the page button."
+            },
+            {
+              "name": "disabled",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether the button is disabled."
+            },
+            {
+              "name": "aria-label",
+              "type": "string",
+              "default": "",
+              "description": "Accessible label for the page button."
+            },
+            {
+              "name": "aria-current",
+              "type": "\"page\"",
+              "default": "",
+              "description": "ARIA current page indicator."
+            },
+            {
+              "name": "data-active",
+              "type": "string",
+              "default": "",
+              "description": "Data attribute for active state."
+            },
+            {
+              "name": "data-disabled",
+              "type": "string",
+              "default": "",
+              "description": "Data attribute for disabled state."
+            }
+          ],
+          "methods": []
+        },
+        "UsePaginatorExposes": {
+          "description": "Defines the return type of usePaginator.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "getAriaLabel",
+              "type": "(labelType: string) => string",
+              "default": "",
+              "description": "Returns the aria label for the given label type from locale config."
+            },
+            {
+              "name": "prev",
+              "type": "() => void",
+              "default": "",
+              "description": "Go to previous page."
+            },
+            {
+              "name": "next",
+              "type": "() => void",
+              "default": "",
+              "description": "Go to next page."
+            },
+            {
+              "name": "first",
+              "type": "() => void",
+              "default": "",
+              "description": "Go to first page."
+            },
+            {
+              "name": "last",
+              "type": "() => void",
+              "default": "",
+              "description": "Go to last page."
+            },
+            {
+              "name": "handlePage",
+              "type": "(page?: number) => void",
+              "default": "",
+              "description": "Set the current page."
+            },
+            {
+              "name": "pages",
+              "type": "PaginatorPageItem[]",
+              "default": "",
+              "description": "Pages array."
+            },
+            {
+              "name": "firstProps",
+              "type": "UsePaginatorNavProps",
+              "default": "",
+              "description": "Pre-built props for the first page button."
+            },
+            {
+              "name": "prevProps",
+              "type": "UsePaginatorNavProps",
+              "default": "",
+              "description": "Pre-built props for the previous page button."
+            },
+            {
+              "name": "nextProps",
+              "type": "UsePaginatorNavProps",
+              "default": "",
+              "description": "Pre-built props for the next page button."
+            },
+            {
+              "name": "lastProps",
+              "type": "UsePaginatorNavProps",
+              "default": "",
+              "description": "Pre-built props for the last page button."
+            },
+            {
+              "name": "pagesProps",
+              "type": "UsePaginatorPagesProps",
+              "default": "",
+              "description": "Pre-built props for the pages container."
+            },
+            {
+              "name": "getPageProps",
+              "type": "(value: number) => UsePaginatorPageProps",
+              "default": "",
+              "description": "Returns pre-built props for a specific page button."
+            }
+          ],
+          "methods": []
+        }
+      },
+      "types": {
+        "UsePaginatorInstance": {
+          "description": "Instance of usePaginator headless.",
+          "values": "HeadlessInstance<UsePaginatorProps, UsePaginatorState, UsePaginatorExposes>"
+        }
+      },
+      "variables": {}
+    }
+  }
+]

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

@@ -0,0 +1,187 @@
+# usePaginator
+
+Hook that manages pagination state, page calculations, and accessible navigation prop objects.
+
+```tsx
+'use client';
+
+import { AngleDoubleLeft } from '@primeicons/react/angle-double-left';
+import { AngleDoubleRight } from '@primeicons/react/angle-double-right';
+import { AngleLeft } from '@primeicons/react/angle-left';
+import { AngleRight } from '@primeicons/react/angle-right';
+import { EllipsisH } from '@primeicons/react/ellipsis-h';
+import { usePaginator } from '@primereact/headless/paginator';
+
+export default function BasicDemo() {
+    const { rootProps, firstProps, prevProps, nextProps, lastProps, pagesProps, pages, getPageProps } = usePaginator({ total: 100, itemsPerPage: 5 });
+
+    return (
+        <nav {...rootProps} className="flex items-center justify-center gap-1">
+            <button
+                {...firstProps}
+                className="inline-flex items-center justify-center size-9 rounded-full border-0 bg-transparent text-surface-500 dark:text-surface-400 cursor-pointer select-none hover:bg-surface-100 dark:hover:bg-surface-800 disabled:opacity-60 disabled:pointer-events-none focus-visible:outline focus-visible:outline-1 focus-visible:outline-primary focus-visible:outline-offset-2"
+            >
+                <AngleDoubleLeft className="size-4" />
+            </button>
+            <button
+                {...prevProps}
+                className="inline-flex items-center justify-center size-9 rounded-full border-0 bg-transparent text-surface-500 dark:text-surface-400 cursor-pointer select-none hover:bg-surface-100 dark:hover:bg-surface-800 disabled:opacity-60 disabled:pointer-events-none focus-visible:outline focus-visible:outline-1 focus-visible:outline-primary focus-visible:outline-offset-2"
+            >
+                <AngleLeft className="size-4" />
+            </button>
+            <span {...pagesProps} className="flex items-center gap-1">
+                {pages.map((page, index) =>
+                    page.type === 'page' ? (
+                        <button
+                            key={index}
+                            {...getPageProps(page.value!)}
+                            className="inline-flex items-center justify-center size-9 rounded-full border-0 bg-transparent text-surface-500 dark:text-surface-400 text-sm cursor-pointer select-none hover:bg-[var(--p-content-hover-background)] dark:hover:bg-surface-800 data-[active]:bg-[var(--p-highlight-background)] data-[active]:text-[var(--p-highlight-color)] data-[active]:hover:bg-[var(--p-highlight-background)] disabled:opacity-60 disabled:pointer-events-none focus-visible:outline focus-visible:outline-1 focus-visible:outline-primary focus-visible:outline-offset-2"
+                        >
+                            {page.value}
+                        </button>
+                    ) : (
+                        <span key={index} className="inline-flex items-center justify-center size-9 text-surface-400 dark:text-surface-500">
+                            <EllipsisH className="size-4" />
+                        </span>
+                    )
+                )}
+            </span>
+            <button
+                {...nextProps}
+                className="inline-flex items-center justify-center size-9 rounded-full border-0 bg-transparent text-surface-500 dark:text-surface-400 cursor-pointer select-none hover:bg-surface-100 dark:hover:bg-surface-800 disabled:opacity-60 disabled:pointer-events-none focus-visible:outline focus-visible:outline-1 focus-visible:outline-primary focus-visible:outline-offset-2"
+            >
+                <AngleRight className="size-4" />
+            </button>
+            <button
+                {...lastProps}
+                className="inline-flex items-center justify-center size-9 rounded-full border-0 bg-transparent text-surface-500 dark:text-surface-400 cursor-pointer select-none hover:bg-surface-100 dark:hover:bg-surface-800 disabled:opacity-60 disabled:pointer-events-none focus-visible:outline focus-visible:outline-1 focus-visible:outline-primary focus-visible:outline-offset-2"
+            >
+                <AngleDoubleRight className="size-4" />
+            </button>
+        </nav>
+    );
+}
+```
+
+## Usage
+
+```tsx
+import { usePaginator } from '@primereact/headless/paginator';
+```
+
+```tsx
+const paginator = usePaginator({ total: 100, itemsPerPage: 10 });
+
+<nav {...paginator.rootProps}>
+    <button {...paginator.firstProps}></button>
+    <button {...paginator.prevProps}></button>
+    <span {...paginator.pagesProps}>
+        {paginator.pages.map((page, i) => (
+            <button key={i} {...paginator.getPageProps(page.value!)}></button>
+```
+
+`usePaginator` computes page ranges, ellipsis positions, and pre-built ARIA props for navigation buttons. See [Primitive](/docs/primitive/components/paginator) for a component-based API.
+
+## Features
+
+- **Page range algorithm**, builds a compact list of buttons using `siblings`, `edges`, and automatic ellipsis insertion
+- **Navigation prop objects**, `firstProps`, `prevProps`, `nextProps`, `lastProps`, and `getPageProps(page)` pre-wire clicks and disabled state
+- **Controlled or uncontrolled**, use `page` / `onPageChange` for external state or `defaultPage` for internal state
+- **Reactive state**, `state.activePage`, `state.totalPages`, `state.canPrev`, `state.canNext` for custom indicators and summaries
+- **Iterable pages collection**, `pages` array with `type: 'page' | 'ellipsis'` entries for rendering any custom layout
+
+## Working with callbacks
+
+### onPageChange, controlled pagination
+
+Pair `page` with `onPageChange` when pagination is driven by URL state, query params, or a parent store.
+
+```tsx
+const [page, setPage] = React.useState(1);
+
+const paginator = usePaginator({
+    page,
+    total: 100,
+    itemsPerPage: 10,
+    onPageChange: (e) => setPage(e.value)
+});
+```
+
+### Tuning the page window
+
+`siblings` controls how many buttons sit on either side of the active page; `edges` controls how many are pinned at the start and end. Disable `showEllipsis` to render all pages inline.
+
+```tsx
+const paginator = usePaginator({
+    total: 100,
+    itemsPerPage: 5,
+    siblings: 2,
+    edges: 1
+});
+```
+
+### Rendering pages with ellipsis gaps
+
+Iterate `pages` and branch on `type` to render both page buttons and gap indicators.
+
+```tsx
+paginator.pages.map((item, i) =>
+    item.type === 'page' ? (
+        <button key={i} {...paginator.getPageProps(item.value!)}>
+            {item.value}
+        </button>
+    ) : (
+        <span key={i}>...</span>
+    )
+);
+```
+
+### Building a custom summary
+
+Use reactive state to render text like "Page 3 of 10" or disable external controls in sync with the paginator.
+
+```tsx
+const paginator = usePaginator({ total: 100, itemsPerPage: 10 });
+
+<span>
+    Page {paginator.state.activePage} of {paginator.state.totalPages}
+</span>;
+```
+
+### Syncing with a data source
+
+Respond to page changes to fetch a new slice of data.
+
+```tsx
+const paginator = usePaginator({
+    total,
+    itemsPerPage: 20,
+    onPageChange: (e) => fetchPage(e.value)
+});
+```
+
+## Styling with data attributes
+
+Prop objects include data attributes for styling active, disabled, and navigation states.
+
+```css
+[data-active] {
+    background: var(--p-primary-color);
+    color: var(--p-primary-contrast-color);
+}
+
+[data-disabled] {
+    opacity: 0.5;
+    pointer-events: none;
+}
+```
+
+## API
+
+### usePaginator
+
+<DocTable name="usePaginator" category="api" />
+
+## Accessibility
+
+Arrow keys move through page buttons, Home/End jump to first/last page, and Enter activates the focused page. See [Primitive](/docs/primitive/components/paginator#accessibility) for full WAI-ARIA compliance details.

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

@@ -0,0 +1,195 @@
+[
+  {
+    "name": "usePanel",
+    "source": "apps/showcase/assets/apidoc/usepanel.json",
+    "data": {
+      "description": "The usePanel manages the state and functionality of a panel component.",
+      "interfaces": {
+        "UsePanelOpenChangeEvent": {
+          "description": "Event object for the onToggle callback.",
+          "relatedProp": "",
+          "extendedTypes": "UseCollapsibleOpenChangeEvent<E>",
+          "props": [
+            {
+              "name": "originalEvent",
+              "type": "E",
+              "default": "",
+              "description": "The original event that triggered the change."
+            },
+            {
+              "name": "value",
+              "type": "boolean",
+              "default": "",
+              "description": "The value of the collapsible."
+            }
+          ],
+          "methods": []
+        },
+        "UsePanelProps": {
+          "description": "Props for the usePanel hook.",
+          "relatedProp": "",
+          "extendedTypes": "Omit<UseCollapsibleProps, \"onOpenChange\">",
+          "props": [
+            {
+              "name": "open",
+              "type": "boolean",
+              "default": "false",
+              "description": "Controls the open state of the collapsible."
+            },
+            {
+              "name": "defaultOpen",
+              "type": "boolean",
+              "default": "false",
+              "description": "Defines the initial open state of the collapsible."
+            },
+            {
+              "name": "disabled",
+              "type": "boolean",
+              "default": "false",
+              "description": "When disabled, the component cannot be interacted with."
+            },
+            {
+              "name": "tabIndex",
+              "type": "number",
+              "default": "0",
+              "description": "Index of the element in tabbing order."
+            },
+            {
+              "name": "onOpen",
+              "type": "(event?: SyntheticEvent) => void",
+              "default": "",
+              "description": "Callback triggered when the content is opened."
+            },
+            {
+              "name": "onClose",
+              "type": "(event?: SyntheticEvent) => void",
+              "default": "",
+              "description": "Callback triggered when the content is closed."
+            },
+            {
+              "name": "onOpenChange",
+              "type": "(event: UsePanelOpenChangeEvent) => void",
+              "default": "",
+              "description": "Callback triggered when the content's toggle state changes."
+            }
+          ],
+          "methods": []
+        },
+        "UsePanelState": {
+          "description": "Defines valid state in usePanel.",
+          "relatedProp": "",
+          "extendedTypes": "UseCollapsibleState",
+          "props": [
+            {
+              "name": "open",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether the collapsible content is open or not."
+            }
+          ],
+          "methods": []
+        },
+        "UsePanelIndicatorProps": {
+          "description": "Props for the panel indicator 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-open",
+              "type": "string",
+              "default": "",
+              "description": "Present when the panel is open."
+            },
+            {
+              "name": "data-closed",
+              "type": "string",
+              "default": "",
+              "description": "Present when the panel is closed."
+            }
+          ],
+          "methods": []
+        },
+        "UsePanelExposes": {
+          "description": "Defines the methods and properties exposed by usePanel.",
+          "relatedProp": "",
+          "extendedTypes": "Omit<UseCollapsibleExposes, \"state\">",
+          "props": [
+            {
+              "name": "open",
+              "type": "(event?: SyntheticEvent) => void",
+              "default": "",
+              "description": "The method to open the collapsible content."
+            },
+            {
+              "name": "close",
+              "type": "(event?: SyntheticEvent) => void",
+              "default": "",
+              "description": "The method to close the collapsible content."
+            },
+            {
+              "name": "toggle",
+              "type": "(event?: SyntheticEvent) => void",
+              "default": "",
+              "description": "The method to toggle the collapsible content."
+            },
+            {
+              "name": "rootProps",
+              "type": "UseCollapsibleRootProps",
+              "default": "",
+              "description": "Pre-built data attribute props for the root element.\nIncludes data-disabled, data-open/closed."
+            },
+            {
+              "name": "triggerProps",
+              "type": "UseCollapsibleTriggerProps",
+              "default": "",
+              "description": "Pre-built props for the trigger element.\nIncludes type, ARIA, data attributes, and onClick handler."
+            },
+            {
+              "name": "contentProps",
+              "type": "UseCollapsibleContentProps",
+              "default": "",
+              "description": "Pre-built props for the content element.\nIncludes id, role, ARIA, and data attributes."
+            },
+            {
+              "name": "state",
+              "type": "UsePanelState",
+              "default": "",
+              "description": "The state of the usePanel."
+            },
+            {
+              "name": "indicatorProps",
+              "type": "UsePanelIndicatorProps",
+              "default": "",
+              "description": "Pre-built props for the indicator element.\nIncludes data-open/closed attributes."
+            },
+            {
+              "name": "onTriggerClick",
+              "type": "(event?: SyntheticEvent) => void",
+              "default": "",
+              "description": "Callback to be invoked when the trigger is clicked."
+            }
+          ],
+          "methods": []
+        }
+      },
+      "types": {
+        "UsePanelInstance": {
+          "description": "Instance of usePanel headless.",
+          "values": "HeadlessInstance<UsePanelProps, UsePanelState, UsePanelExposes>"
+        }
+      },
+      "variables": {}
+    }
+  }
+]