@primereact/mcp 11.0.0-rc.2

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

@@ -0,0 +1,336 @@
+[
+  {
+    "name": "useTabs",
+    "source": "apps/showcase/assets/apidoc/usetabs.json",
+    "data": {
+      "description": "The useTabs manages the state and functionality of a tabs component.",
+      "interfaces": {
+        "UseTabsChangeEvent": {
+          "description": "Event fired when the tabs's checked state changes.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "value",
+              "type": "string | number",
+              "default": "",
+              "description": "The value of the tabs."
+            }
+          ],
+          "methods": []
+        },
+        "UseTabsProps": {
+          "description": "Defines valid properties in useTabs.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "value",
+              "type": "string | number",
+              "default": "undefined",
+              "description": "Value of the active tab. Use for controlled mode."
+            },
+            {
+              "name": "defaultValue",
+              "type": "string | number",
+              "default": "undefined",
+              "description": "Default value of the active tab. Use for uncontrolled mode."
+            },
+            {
+              "name": "selectOnFocus",
+              "type": "boolean",
+              "default": "false",
+              "description": "When enabled, the focused tab is activated."
+            },
+            {
+              "name": "scrollStrategy",
+              "type": "false | \"center\" | \"nearest\" | ((content: HTMLElement, tab: HTMLElement) => void)",
+              "default": "'nearest'",
+              "description": "Defines how the active tab is scrolled into view when it changes.\n-  `'nearest'` : scrolls only if the tab is clipped or too close to an edge, with padding.\n-  `'center'` : always centers the active tab in the viewport.\n-  `false` : disables auto-scrolling.\n-  `function` : a custom scroll function receiving the content element and active tab element."
+            },
+            {
+              "name": "tabIndex",
+              "type": "number",
+              "default": "0",
+              "description": "The tabIndex of the active tab."
+            },
+            {
+              "name": "onValueChange",
+              "type": "(event: UseTabsChangeEvent) => void",
+              "default": "",
+              "description": "Callback fired when the tabs's value changes."
+            }
+          ],
+          "methods": []
+        },
+        "UseTabsState": {
+          "description": "Defines valid state in useTabs.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "activeTab",
+              "type": "string | number",
+              "default": "",
+              "description": "Value of the active tab or an array of values in multiple mode."
+            },
+            {
+              "name": "canScrollPrev",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether the previous scroll button should be enabled."
+            },
+            {
+              "name": "canScrollNext",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether the next scroll button should be enabled."
+            }
+          ],
+          "methods": []
+        },
+        "UseTabsTabProps": {
+          "description": "Props returned by getTabProps for a tab element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "role",
+              "type": "\"tab\"",
+              "default": "",
+              "description": "The role of the tab element."
+            },
+            {
+              "name": "tabIndex",
+              "type": "number",
+              "default": "",
+              "description": "The tabIndex of the tab element."
+            },
+            {
+              "name": "ref",
+              "type": "RefObject<HTMLButtonElement>",
+              "default": "",
+              "description": "Ref for the active tab element."
+            },
+            {
+              "name": "disabled",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether the tab is disabled."
+            },
+            {
+              "name": "aria-selected",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether the tab is selected."
+            },
+            {
+              "name": "aria-disabled",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether the tab is disabled (aria)."
+            },
+            {
+              "name": "aria-controls",
+              "type": "string",
+              "default": "",
+              "description": "The id of the tabpanel controlled by this tab."
+            },
+            {
+              "name": "data-active",
+              "type": "\"\"",
+              "default": "",
+              "description": "Present when the tab is active."
+            },
+            {
+              "name": "data-disabled",
+              "type": "\"\"",
+              "default": "",
+              "description": "Present when the tab is disabled."
+            },
+            {
+              "name": "data-can-scroll-prev",
+              "type": "\"\"",
+              "default": "",
+              "description": "Present when the tab list can scroll to the previous page."
+            },
+            {
+              "name": "data-can-scroll-next",
+              "type": "\"\"",
+              "default": "",
+              "description": "Present when the tab list can scroll to the next page."
+            },
+            {
+              "name": "onClick",
+              "type": "(event: MouseEvent<HTMLButtonElement>) => void",
+              "default": "",
+              "description": "Click event handler for the tab."
+            },
+            {
+              "name": "onFocus",
+              "type": "(event: FocusEvent<HTMLButtonElement>) => void",
+              "default": "",
+              "description": "Focus event handler for the tab."
+            },
+            {
+              "name": "onKeyDown",
+              "type": "(event: KeyboardEvent<HTMLButtonElement>) => void",
+              "default": "",
+              "description": "Keyboard event handler for the tab."
+            }
+          ],
+          "methods": []
+        },
+        "UseTabsIndicatorProps": {
+          "description": "Props returned by getIndicatorProps for the active tab indicator element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "ref",
+              "type": "RefObject<HTMLSpanElement>",
+              "default": "",
+              "description": "Ref for the active bar element."
+            },
+            {
+              "name": "style",
+              "type": "CSSProperties",
+              "default": "",
+              "description": "CSS custom properties for positioning the indicator."
+            }
+          ],
+          "methods": []
+        },
+        "UseTabsExposes": {
+          "description": "Defines the methods and properties exposed by useTabs.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "updateValue",
+              "type": "(value: string | number) => void",
+              "default": "",
+              "description": "The method to update the value of the active tab."
+            },
+            {
+              "name": "isItemActive",
+              "type": "(key: string | number) => boolean",
+              "default": "",
+              "description": "The method to check if the tab is active."
+            },
+            {
+              "name": "focusTab",
+              "type": "(tabElement: HTMLElement, direction: \"next\" | \"previous\" | \"first\" | \"last\") => void",
+              "default": "",
+              "description": "Moves focus to a tab in the given direction."
+            },
+            {
+              "name": "onTabKeyDown",
+              "type": "(event: KeyboardEvent<HTMLButtonElement>, value: string | number) => void",
+              "default": "",
+              "description": "Keyboard event handler for tabs."
+            },
+            {
+              "name": "onTabClick",
+              "type": "(event: MouseEvent<HTMLButtonElement>, value: string | number) => void",
+              "default": "",
+              "description": "Click event handler for tabs."
+            },
+            {
+              "name": "onTabFocus",
+              "type": "(event: FocusEvent<HTMLButtonElement>, value: string | number) => void",
+              "default": "",
+              "description": "Focus event handler for tabs."
+            },
+            {
+              "name": "scrollPrev",
+              "type": "() => void",
+              "default": "",
+              "description": "Scrolls the tab list to the previous page."
+            },
+            {
+              "name": "scrollNext",
+              "type": "() => void",
+              "default": "",
+              "description": "Scrolls the tab list to the next page."
+            },
+            {
+              "name": "updateScrollState",
+              "type": "() => void",
+              "default": "",
+              "description": "Updates the scroll button visibility state."
+            },
+            {
+              "name": "onContentScroll",
+              "type": "() => void",
+              "default": "",
+              "description": "Scroll event handler for the content container."
+            },
+            {
+              "name": "contentRef",
+              "type": "RefObject<HTMLDivElement>",
+              "default": "",
+              "description": "Ref for the scroll content container."
+            },
+            {
+              "name": "prevButtonRef",
+              "type": "RefObject<HTMLButtonElement>",
+              "default": "",
+              "description": "Ref for the previous scroll button."
+            },
+            {
+              "name": "nextButtonRef",
+              "type": "RefObject<HTMLButtonElement>",
+              "default": "",
+              "description": "Ref for the next scroll button."
+            },
+            {
+              "name": "activeBarRef",
+              "type": "RefObject<HTMLElement>",
+              "default": "",
+              "description": "Ref for the active bar element."
+            },
+            {
+              "name": "activeTabRef",
+              "type": "RefObject<HTMLElement>",
+              "default": "",
+              "description": "Ref for the active tab element."
+            },
+            {
+              "name": "updateActiveBar",
+              "type": "() => void",
+              "default": "",
+              "description": "Updates the active bar position and size based on the active tab."
+            },
+            {
+              "name": "scrollStateAttrs",
+              "type": "Record<string, \"\">",
+              "default": "",
+              "description": "Pre-built data attributes reflecting scroll state (data-can-scroll-prev, data-can-scroll-next)."
+            },
+            {
+              "name": "contentProps",
+              "type": "{ onScroll: () => void; data-can-scroll-prev?: \"\"; data-can-scroll-next?: \"\" }",
+              "default": "",
+              "description": "Pre-built props for the scroll content container, includes onScroll handler and scroll state attributes."
+            },
+            {
+              "name": "getTabProps",
+              "type": "(value: string | number, disabled?: boolean) => UseTabsTabProps",
+              "default": "",
+              "description": "Returns accessibility and interaction props for a tab element."
+            },
+            {
+              "name": "getIndicatorProps",
+              "type": "() => UseTabsIndicatorProps",
+              "default": "",
+              "description": "Returns props for the active tab indicator element."
+            }
+          ],
+          "methods": []
+        }
+      },
+      "types": {
+        "UseTabsInstance": {
+          "description": "Instance of useTabs headless.",
+          "values": "HeadlessInstance<UseTabsProps, UseTabsState, UseTabsExposes>"
+        }
+      },
+      "variables": {}
+    }
+  }
+]

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

@@ -0,0 +1,158 @@
+# useTabs
+
+Hook that manages tab selection state, keyboard navigation, and scrollable overflow.
+
+```tsx
+'use client';
+import { useTabs } from '@primereact/headless/tabs';
+
+export default function BasicDemo() {
+    const { getTabProps, getIndicatorProps, isItemActive } = useTabs({ defaultValue: 'tab1' });
+
+    return (
+        <div>
+            <div className="relative flex border-b border-surface-200 dark:border-surface-700">
+                {items.map((item) => {
+                    const active = isItemActive(item.value);
+
+                    return (
+                        <button
+                            key={item.value}
+                            {...getTabProps(item.value)}
+                            className={`px-4 py-3 text-sm font-semibold cursor-pointer transition-colors select-none focus-visible:outline-1 focus-visible:-outline-offset-1 focus-visible:outline-primary ${active ? 'text-primary' : 'text-surface-500 dark:text-surface-400 hover:text-surface-700 dark:hover:text-surface-200'}`}
+                        >
+                            {item.title}
+                        </button>
+                    );
+                })}
+                <span
+                    {...getIndicatorProps()}
+                    className="absolute block -bottom-px left-[var(--px-active-bar-left)] h-0.5 w-[var(--px-active-bar-width)] bg-primary transition-all duration-200 ease-out"
+                />
+            </div>
+            <div className="p-4 text-surface-700 dark:text-surface-200">
+                {items.map((item) => {
+                    const active = isItemActive(item.value);
+
+                    return (
+                        <div key={item.value} role="tabpanel" style={{ display: active ? 'block' : 'none' }}>
+                            <h2 className="text-lg font-bold">{item.title}</h2>
+                            <p className="mt-1 text-surface-500 dark:text-surface-400">{item.content}</p>
+                        </div>
+                    );
+                })}
+            </div>
+        </div>
+    );
+}
+
+const items = [
+    { value: 'tab1', title: 'Account Info', content: 'Update your personal information such as name, email address, and profile picture.' },
+    { value: 'tab2', title: 'Payment', content: 'Manage your subscription plan, view invoices, and update your payment method.' },
+    { value: 'tab3', title: 'Preferences', content: 'Customize how the application looks and behaves to match your personal preferences.' }
+];
+```
+
+## Usage
+
+```tsx
+import { useTabs } from '@primereact/headless/tabs';
+```
+
+```tsx
+const { getTabProps, getIndicatorProps, isItemActive, state, contentRef, contentProps } = useTabs({ defaultValue: 'tab1' });
+
+<div role="tablist" ref={contentRef} {...contentProps}>
+    <button {...getTabProps('tab1')}>Tab 1</button>
+    <button {...getTabProps('tab2')}>Tab 2</button>
+    <button {...getTabProps('tab3', true)}>Tab 3 (disabled)</button>
+    <span {...getIndicatorProps()} />
+</div>;
+```
+
+`useTabs` manages active tab state, keyboard focus cycling, scroll navigation, and active indicator positioning, see [Primitive](/docs/primitive/components/tabs) for a component-based API.
+
+## Features
+
+- **Per-tab prop getter**, `getTabProps(value, disabled?)` returns ARIA roles, keyboard handlers, and focus bookkeeping for any tab you render
+- **Animated active indicator**, `getIndicatorProps()` wires a ref and CSS variables that track the active tab's size and position
+- **Scrollable tab lists**, `scrollPrev`/`scrollNext` plus `canScrollPrev`/`canScrollNext` flags power overflow buttons with zero measurement code
+- **Configurable scroll strategy**, pick `'nearest'`, `'center'`, disable, or plug in a custom function to scroll the active tab into view
+- **Controlled or uncontrolled**, manage the active value externally or let the hook track it internally
+- **Imperative selection**, `updateValue()` changes tabs programmatically and `isItemActive()` queries the current selection
+
+## Working with callbacks
+
+### Controlled active tab
+
+Drive the active tab from parent state by pairing `value` with `onValueChange`.
+
+```tsx
+const [activeTab, setActiveTab] = React.useState('tab1');
+
+const tabs = useTabs({
+    value: activeTab,
+    onValueChange: (e) => setActiveTab(e.value)
+});
+```
+
+### Activate on focus
+
+Set `selectOnFocus` so arrow-key navigation activates tabs instantly rather than waiting for Enter or Space, the pattern used by automatic tablists.
+
+```tsx
+const tabs = useTabs({ defaultValue: 'tab1', selectOnFocus: true });
+```
+
+### Scrollable overflow with prev/next buttons
+
+Wire `contentRef`, `prevButtonRef`, and `nextButtonRef` into your layout, then use the scroll helpers to drive visibility and clicks.
+
+```tsx
+const tabs = useTabs({ defaultValue: '0' });
+```
+
+### Animated active indicator
+
+Spread `getIndicatorProps()` on a bar element, the hook sets a ref plus CSS custom properties so you can animate position and size entirely in CSS.
+
+| Variable              | Description                           |
+| --------------------- | ------------------------------------- |
+| `--active-bar-width`  | Width of the active tab element       |
+| `--active-bar-height` | Height of the active tab element      |
+| `--active-bar-left`   | Left offset of the active tab element |
+| `--active-bar-top`    | Top offset of the active tab element  |
+
+```tsx
+<span
+    {...getIndicatorProps()}
+    style={{
+        width: 'var(--px-active-bar-width)',
+        left: 'var(--px-active-bar-left)',
+        transition: 'all 200ms ease'
+    }}
+/>
+```
+
+## Styling with data attributes
+
+The `scrollStateAttrs` bundle spreads `data-can-scroll-prev` and `data-can-scroll-next` onto any element so scroll button visibility can be controlled in CSS.
+
+```css
+[data-can-scroll-prev] .scroll-prev {
+    display: flex;
+}
+[data-can-scroll-next] .scroll-next {
+    display: flex;
+}
+```
+
+## API
+
+### useTabs
+
+<DocTable name="useTabs" category="api" />
+
+## Accessibility
+
+Arrow keys move between tabs, Home/End jump to first/last, and Enter activates the focused tab. See [Primitive](/docs/primitive/components/tabs#accessibility) for full WAI-ARIA compliance details.

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

@@ -0,0 +1,62 @@
+[
+  {
+    "name": "useTag",
+    "source": "apps/showcase/assets/apidoc/usetag.json",
+    "data": {
+      "description": "The useTag manages the state and functionality of a tag component.",
+      "interfaces": {
+        "UseTagProps": {
+          "description": "Defines valid properties in useTag.",
+          "relatedProp": "",
+          "props": [],
+          "methods": []
+        },
+        "UseTagState": {
+          "description": "Defines valid state in useTag.",
+          "relatedProp": "",
+          "props": [],
+          "methods": []
+        },
+        "UseTagRootProps": {
+          "description": "Data attribute props for the Tag 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": []
+        },
+        "UseTagExposes": {
+          "description": "Defines the methods and properties exposed by useTag.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "rootProps",
+              "type": "UseTagRootProps",
+              "default": "",
+              "description": "Pre-built data attribute props for the root element."
+            }
+          ],
+          "methods": []
+        }
+      },
+      "types": {
+        "UseTagInstance": {
+          "description": "Instance of useTag headless.",
+          "values": "HeadlessInstance<UseTagProps, UseTagState, UseTagExposes>"
+        }
+      },
+      "variables": {}
+    }
+  }
+]

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

@@ -0,0 +1,121 @@
+# useTag
+
+Hook that provides data attributes for building custom categorization labels.
+
+```tsx
+'use client';
+import { Check } from '@primeicons/react/check';
+import { ExclamationTriangle } from '@primeicons/react/exclamation-triangle';
+import { InfoCircle } from '@primeicons/react/info-circle';
+import { useTag } from '@primereact/headless/tag';
+
+const tags = [
+    { label: 'Active', icon: Check, bg: 'bg-green-100 text-green-700' },
+    { label: 'Info', icon: InfoCircle, bg: 'bg-blue-100 text-blue-700' },
+    { label: 'Warning', icon: ExclamationTriangle, bg: 'bg-amber-100 text-amber-700' }
+];
+
+export default function BasicDemo() {
+    return (
+        <div className="flex items-center justify-center flex-wrap gap-2">
+            {tags.map((tag) => {
+                const { rootProps } = useTag();
+                const Icon = tag.icon;
+
+                return (
+                    <span
+                        key={tag.label}
+                        {...rootProps}
+                        className={`inline-flex items-center gap-1.5 px-3 py-1 rounded-full text-xs font-semibold ${tag.bg}`}
+                    >
+                        <Icon className="w-3 h-3" />
+                        {tag.label}
+                    </span>
+                );
+            })}
+        </div>
+    );
+}
+```
+
+## Usage
+
+```tsx
+import { useTag } from '@primereact/headless/tag';
+```
+
+```tsx
+const { rootProps } = useTag();
+
+return <span {...rootProps} className="tag"></span>;
+```
+
+`useTag` returns spread-ready `rootProps` with scoped data attributes, color, shape, icons, and interactivity are handled with your own markup and CSS. See [Primitive](/docs/primitive/components/tag) for a component-based API.
+
+## Features
+
+- **Spread-ready root props**, a single object you can drop onto any element
+- **Zero-state**, no internal state or effects, suitable for purely visual labels
+- **Styling hooks**, `data-scope="tag"` and `data-part="root"` selectors for targeted styling
+- **Markup-agnostic**, render as a `span`, `a`, `button`, or any component that forwards standard props
+
+## Working with callbacks
+
+### Compose with icons
+
+Place icon components alongside the label inside the tag element.
+
+```tsx
+const { rootProps } = useTag();
+
+<span {...rootProps} className="tag">
+    <CheckIcon />
+    Active
+</span>;
+```
+
+### Pill shape
+
+Apply border-radius via inline styles or classes to create pill-shaped tags.
+
+```tsx
+<span {...rootProps} style={{ borderRadius: '9999px' }}>
+    Pill
+</span>
+```
+
+### Interactive tags
+
+Render the tag as a `<button>` when it should be clickable, `rootProps` spreads onto any valid element.
+
+```tsx
+<button {...rootProps} onClick={handleClick}>
+    Clickable
+</button>
+```
+
+## Styling with data attributes
+
+The root prop object includes `data-scope="tag"` and `data-part="root"` for targeted styling.
+
+```css
+[data-scope='tag'][data-part='root'] {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.25rem;
+    padding: 0.25rem 0.75rem;
+    font-size: 0.75rem;
+    font-weight: 600;
+    border-radius: 0.375rem;
+}
+```
+
+## API
+
+### useTag
+
+<DocTable name="useTag" category="api" />
+
+## Accessibility
+
+Static label, Tab skips it unless a close button is present, which activates on Enter or Space. See [Primitive](/docs/primitive/components/tag#accessibility) for full WAI-ARIA compliance details.