@primereact/mcp 11.0.0-rc.2

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

@@ -0,0 +1,181 @@
+# usePositioner
+
+Hook that positions a floating element relative to an anchor with automatic flip, shift, and arrow support.
+
+```tsx
+'use client';
+import { usePortal } from '@primereact/headless/portal';
+import { usePositioner } from '@primereact/headless/positioner';
+import * as React from 'react';
+import { createPortal } from 'react-dom';
+
+export default function BasicDemo() {
+    const [open, setOpen] = React.useState(false);
+    const [anchorEl, setAnchorEl] = React.useState<HTMLElement | null>(null);
+    const [contentEl, setContentEl] = React.useState<HTMLDivElement | null>(null);
+
+    const portal = usePortal();
+
+    const positioner = usePositioner({
+        anchor: anchorEl ?? undefined,
+        content: contentEl ?? undefined,
+        side: 'bottom',
+        sideOffset: 8,
+        flip: true,
+        shift: true
+    });
+
+    return (
+        <>
+            <div className="flex justify-center">
+                <button
+                    ref={setAnchorEl}
+                    onClick={() => setOpen((prev) => !prev)}
+                    className="px-3 py-1.5 rounded-lg border border-gray-200 bg-white hover:bg-gray-50 text-sm font-medium cursor-pointer transition"
+                >
+                    {open ? 'Hide' : 'Show'} Tooltip
+                </button>
+            </div>
+            {portal.state.mounted &&
+                open &&
+                createPortal(
+                    <div
+                        ref={setContentEl}
+                        className="bg-gray-900 text-white text-xs rounded-md px-3 py-1.5 shadow-lg"
+                        data-side={positioner.state.actualSide}
+                    >
+                        Positioned on {positioner.state.actualSide ?? 'bottom'}
+                    </div>,
+                    document.body
+                )}
+        </>
+    );
+}
+```
+
+## Usage
+
+```tsx
+import { usePositioner } from '@primereact/headless/positioner';
+```
+
+```tsx
+const [anchorEl, setAnchorEl] = React.useState<HTMLElement | null>(null);
+const [contentEl, setContentEl] = React.useState<HTMLDivElement | null>(null);
+
+const positioner = usePositioner({
+    anchor: anchorEl,
+    content: contentEl,
+    side: 'bottom',
+    sideOffset: 8,
+    flip: true
+});
+
+<>
+    <button ref={setAnchorEl}></button>
+    <div ref={setContentEl}></div>
+</>;
+```
+
+`usePositioner` computes placement for a floating element relative to an anchor, handling overflow with flip/shift and exposing the computed placement for styling. It powers `Popover.Positioner`, `Select.Positioner`, and similar primitives.
+
+## Features
+
+- **Dual-mode positioning**, uses the native CSS Anchor Positioning API when available and falls back to JavaScript otherwise
+- **Overflow handling**, `flip` moves the content to the opposite side and `shift` slides it along the cross-axis to stay within the viewport
+- **Placement reporting**, `state.actualSide` / `state.actualAlign` reflect the final placement after flip and shift
+- **Arrow-aware offsets**, passing an arrow element auto-derives `sideOffset` from its size and injects CSS variables for positioning
+- **Responsive updates**, RAF-throttled scroll/resize listeners plus ResizeObserver on both anchor and content
+- **Imperative recalculation**, `updatePlacement()` forces a new layout when content dimensions change outside the observed events
+
+## Working with callbacks
+
+### Pick preferred placement
+
+Use `side` and `align` to express the preferred edge and cross-axis alignment.
+
+```tsx
+usePositioner({ anchor, content, side: 'top', align: 'start' });
+```
+
+`side` accepts `'top'`, `'right'`, `'bottom'`, or `'left'`. `align` accepts `'start'`, `'center'`, or `'end'`.
+
+### Attach an arrow
+
+Pass an arrow element and the hook exposes CSS variables for positioning the arrow tip, derived from the final placement.
+
+```tsx
+usePositioner({ anchor, content, arrow: arrowEl });
+```
+
+```css
+var(--px-placer-arrow-x)      /* center X of arrow */
+var(--px-placer-arrow-y)      /* center Y of arrow */
+var(--px-placer-arrow-left)   /* left offset of arrow */
+var(--px-placer-arrow-top)    /* top offset of arrow */
+var(--px-transform-origin)    /* transform origin pointing to anchor */
+```
+
+### React to placement changes
+
+Register `onPlacementChange` to run logic when `flip` or `shift` moves the content, for example, swapping an arrow direction or updating an aria-live message.
+
+```tsx
+usePositioner({
+    anchor,
+    content,
+    onPlacementChange: ({ side, align }) => setPlacement({ side, align })
+});
+```
+
+### Constrain placement inside a container
+
+Pass a `boundary` element (JavaScript fallback mode) to keep the floating element inside a specific scroll region instead of the viewport.
+
+```tsx
+usePositioner({ anchor, content, boundary: containerEl });
+```
+
+### Hide when the anchor leaves the viewport
+
+Enable `hideWhenDetached` so the content hides automatically once the anchor scrolls out of the boundary.
+
+```tsx
+usePositioner({ anchor, content, hideWhenDetached: true });
+```
+
+### Force a recompute
+
+Call `updatePlacement()` after imperative content changes (such as loading data) so the hook picks up the new dimensions.
+
+```tsx
+const positioner = usePositioner({ anchor, content });
+
+positioner.updatePlacement();
+```
+
+## Styling with data attributes
+
+The hook writes `data-side` and `data-align` on the content and arrow element for placement-aware CSS.
+
+```css
+[data-side='bottom'] {
+    margin-top: 4px;
+}
+[data-side='top'] {
+    margin-bottom: 4px;
+}
+[data-side='bottom'][data-align='start'] {
+    /* bottom-start placement */
+}
+```
+
+## API
+
+### usePositioner
+
+<DocTable name="usePositioner" category="api" />
+
+## Accessibility
+
+`usePositioner` is a structural positioning utility. It does not introduce ARIA roles or keyboard interactions. Accessibility concerns are handled by the consumer component (e.g., [Popover](/docs/primitive/components/popover#accessibility), Tooltip, Select).

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

@@ -0,0 +1,87 @@
+[
+  {
+    "name": "useProgressBar",
+    "source": "apps/showcase/assets/apidoc/useprogressbar.json",
+    "data": {
+      "description": "The useProgressBar manages the state and functionality of a progress bar component.",
+      "interfaces": {
+        "UseProgressBarProps": {
+          "description": "Defines valid properties in useProgressBar.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "value",
+              "type": "number",
+              "default": "",
+              "description": "Current value of the progress."
+            },
+            {
+              "name": "max",
+              "type": "number",
+              "default": "",
+              "description": "Defines the mode of the progress"
+            },
+            {
+              "name": "min",
+              "type": "number",
+              "default": "",
+              "description": "Defines the mode of the progress"
+            },
+            {
+              "name": "formatter",
+              "type": "(value: number) => string",
+              "default": "",
+              "description": "Custom formatter function to format the display value"
+            }
+          ],
+          "methods": []
+        },
+        "UseProgressBarState": {
+          "description": "Defines valid state in useProgressBar.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "computedValue",
+              "type": "number",
+              "default": "",
+              "description": "Current value of the progress."
+            },
+            {
+              "name": "formattedValue",
+              "type": "string",
+              "default": "",
+              "description": "Current value of the progress in percentage format and fixed to 2 decimal places."
+            }
+          ],
+          "methods": []
+        },
+        "UseProgressBarExposes": {
+          "description": "Defines the methods and properties exposed by useProgressBar.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "rootProps",
+              "type": "{ data-scope: \"progressbar\"; data-part: \"root\" }",
+              "default": "",
+              "description": "Prop getter for the root element."
+            },
+            {
+              "name": "trackProps",
+              "type": "{ data-scope: \"progressbar\"; data-part: \"track\"; role: \"progressbar\"; aria-valuemin: number; aria-valuenow: number; aria-valuemax: number }",
+              "default": "",
+              "description": "Prop getter for the track element containing ARIA progressbar attributes."
+            }
+          ],
+          "methods": []
+        }
+      },
+      "types": {
+        "UseProgressBarInstance": {
+          "description": "Instance of useProgressBar headless.",
+          "values": "HeadlessInstance<UseProgressBarProps, UseProgressBarState, UseProgressBarExposes>"
+        }
+      },
+      "variables": {}
+    }
+  }
+]

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

@@ -0,0 +1,122 @@
+# useProgressBar
+
+Hook that normalizes progress values to a percentage range and provides ARIA attributes.
+
+```tsx
+'use client';
+import { useProgressBar } from '@primereact/headless/progressbar';
+
+export default function BasicDemo() {
+    const { rootProps, trackProps, state } = useProgressBar({ value: 50 });
+
+    return (
+        <div className="flex flex-col gap-6 max-w-lg mx-auto">
+            <div {...rootProps}>
+                <div {...trackProps} className="h-5 rounded-full bg-surface-100 dark:bg-surface-800 overflow-hidden">
+                    <div
+                        className="flex items-center justify-center h-full bg-primary rounded-full transition-all duration-500"
+                        style={{ width: state.computedValue + '%' }}
+                    >
+                        <span className="flex items-center justify-center text-xs font-semibold text-surface-200">{state.formattedValue}</span>
+                    </div>
+                </div>
+            </div>
+        </div>
+    );
+}
+```
+
+## Usage
+
+```tsx
+import { useProgressBar } from '@primereact/headless/progressbar';
+```
+
+```tsx
+const { rootProps, trackProps, state } = useProgressBar({ value: 50 });
+
+<div {...rootProps}>
+    <div {...trackProps}>
+        <div style={{ width: state.computedValue + '%' }}></div>
+    </div>
+</div>;
+```
+
+`useProgressBar` normalizes a value within `min`/`max` bounds and returns spread-ready prop objects with ARIA attributes, see [Primitive](/docs/primitive/components/progressbar) for a component-based API.
+
+## Features
+
+- **Value normalization**, `state.computedValue` converts any raw value in the `min`/`max` range into a 0-100 percentage
+- **Formatted display text**, `state.formattedValue` renders via a default `percent` formatter or your custom one
+- **ARIA attributes**, `rootProps` carries `aria-valuenow`, `aria-valuemin`, and `aria-valuemax`
+- **Custom range**, configurable `min` and `max` with a console error guard when bounds are invalid
+- **Reactive state**, `state` is safe to read from custom labels or indicators that sit outside the track
+
+## Working with callbacks
+
+### Working with a custom range
+
+Set `min` and `max` to match your data model. The returned `computedValue` is always expressed as a percentage so your styles stay range-agnostic.
+
+```tsx
+const { state } = useProgressBar({ value: 50, min: 0, max: 200 });
+
+state.computedValue; // 25
+```
+
+### Custom formatted labels
+
+Pass a `formatter` to control the text rendered in `state.formattedValue`. Handy for fractional, ratio, or localized displays.
+
+```tsx
+const { state } = useProgressBar({
+    value: 50,
+    formatter: (value) => `${value}/100`
+});
+
+state.formattedValue; // '50/100'
+```
+
+### Rendering a label alongside the track
+
+Read `state.computedValue` and `state.formattedValue` to render progress text wherever you need it, no extra calls required.
+
+```tsx
+const { state } = useProgressBar({ value: 75 });
+
+<span>{Math.round(state.computedValue ?? 0)}%</span>;
+<span>{state.formattedValue}</span>;
+```
+
+## Styling with data attributes
+
+The prop objects include `data-scope="progressbar"` and `data-part` for styling.
+
+| Scope         | Part    |
+| ------------- | ------- |
+| `progressbar` | `root`  |
+| `progressbar` | `track` |
+
+```css
+[data-scope='progressbar'][data-part='root'] {
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+}
+
+[data-scope='progressbar'][data-part='track'] {
+    height: 1.25rem;
+    border-radius: 9999px;
+    overflow: hidden;
+}
+```
+
+## API
+
+### useProgressBar
+
+<DocTable name="useProgressBar" category="api" />
+
+## Accessibility
+
+Value is exposed via aria-valuenow, aria-valuemin, and aria-valuemax for screen readers. See [Primitive](/docs/primitive/components/progressbar#accessibility) for full WAI-ARIA compliance details.