@primereact/mcp 11.0.0-rc.2

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

@@ -0,0 +1,533 @@
+[
+  {
+    "name": "useCompare",
+    "source": "apps/showcase/assets/apidoc/usecompare.json",
+    "data": {
+      "description": "The useCompare manages the state and functionality of a compare component.",
+      "interfaces": {
+        "UseCompareChangeEvent": {
+          "description": "Event object for compare change callback.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "value",
+              "type": "number | number[]",
+              "default": "",
+              "description": "The new value of the compare."
+            },
+            {
+              "name": "originalEvent",
+              "type": "E",
+              "default": "",
+              "description": "The original DOM event."
+            }
+          ],
+          "methods": []
+        },
+        "UseCompareProps": {
+          "description": "Defines valid properties in useCompare.",
+          "relatedProp": "",
+          "extendedTypes": "Omit<UseSliderProps, \"minStepsBetweenHandles\">",
+          "props": [
+            {
+              "name": "slideOnHover",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether slider moves on hover."
+            },
+            {
+              "name": "tabIndex",
+              "type": "number",
+              "default": "",
+              "description": "The tab index of the hidden input."
+            },
+            {
+              "name": "ariaLabel",
+              "type": "string",
+              "default": "",
+              "description": "Establishes a string value that labels the component."
+            },
+            {
+              "name": "ariaLabelledby",
+              "type": "string",
+              "default": "",
+              "description": "Establishes relationships between the component and label(s) where its value should be one or more element IDs."
+            },
+            {
+              "name": "onFocus",
+              "type": "(event: FocusEvent<HTMLInputElement>) => void",
+              "default": "",
+              "description": "Callback fired when the hidden input is focused."
+            },
+            {
+              "name": "onBlur",
+              "type": "(event: FocusEvent<HTMLInputElement>) => void",
+              "default": "",
+              "description": "Callback fired when the hidden input loses focus."
+            },
+            {
+              "name": "value",
+              "type": "number | number[]",
+              "default": "",
+              "description": "Value of the component."
+            },
+            {
+              "name": "defaultValue",
+              "type": "number | number[]",
+              "default": "",
+              "description": "The default value for the input when not controlled by  `value` ."
+            },
+            {
+              "name": "min",
+              "type": "number",
+              "default": "0",
+              "description": "Mininum boundary value."
+            },
+            {
+              "name": "max",
+              "type": "number",
+              "default": "100",
+              "description": "Maximum boundary value."
+            },
+            {
+              "name": "orientation",
+              "type": "\"horizontal\" | \"vertical\"",
+              "default": "horizontal",
+              "description": "Orientation of the slider."
+            },
+            {
+              "name": "step",
+              "type": "number",
+              "default": "1",
+              "description": "Step factor to increment/decrement the value."
+            },
+            {
+              "name": "onValueChange",
+              "type": "(event: UseSliderChangeEvent) => void",
+              "default": "",
+              "description": "Callback fired when the ToggleButton's pressed state changes."
+            },
+            {
+              "name": "onValueChangeEnd",
+              "type": "(event: UseSliderChangeEvent) => void",
+              "default": "",
+              "description": "Callback fired when the pointer interaction ends."
+            },
+            {
+              "name": "disabled",
+              "type": "boolean",
+              "default": "false",
+              "description": "Whether the component is disabled."
+            },
+            {
+              "name": "readOnly",
+              "type": "boolean",
+              "default": "false",
+              "description": "Whether the component is read-only."
+            },
+            {
+              "name": "invalid",
+              "type": "boolean",
+              "default": "false",
+              "description": "When present, it specifies that the element should be invalid."
+            }
+          ],
+          "methods": []
+        },
+        "UseCompareState": {
+          "description": "Defines valid state in useCompare.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "value",
+              "type": "number",
+              "default": "",
+              "description": "Current value."
+            },
+            {
+              "name": "isDragging",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether the compare handle is being dragged."
+            }
+          ],
+          "methods": []
+        },
+        "UseCompareRootProps": {
+          "description": "Pre-built props for the compare root element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "ref",
+              "type": "(node: HTMLDivElement) => void",
+              "default": ""
+            },
+            {
+              "name": "data-scope",
+              "type": "\"compare\"",
+              "default": ""
+            },
+            {
+              "name": "data-part",
+              "type": "\"root\"",
+              "default": ""
+            },
+            {
+              "name": "data-orientation",
+              "type": "string",
+              "default": ""
+            },
+            {
+              "name": "data-disabled",
+              "type": "\"\"",
+              "default": ""
+            },
+            {
+              "name": "data-invalid",
+              "type": "\"\"",
+              "default": ""
+            },
+            {
+              "name": "data-dragging",
+              "type": "\"\"",
+              "default": ""
+            },
+            {
+              "name": "onPointerDown",
+              "type": "(event: PointerEvent<HTMLDivElement>) => void",
+              "default": ""
+            },
+            {
+              "name": "onPointerMove",
+              "type": "(event: PointerEvent<HTMLDivElement>) => void",
+              "default": ""
+            },
+            {
+              "name": "onPointerUp",
+              "type": "(event: PointerEvent<HTMLDivElement>) => void",
+              "default": ""
+            }
+          ],
+          "methods": []
+        },
+        "UseCompareHandleProps": {
+          "description": "Pre-built props for the compare handle element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "tabIndex",
+              "type": "-1",
+              "default": ""
+            },
+            {
+              "name": "style",
+              "type": "CSSProperties",
+              "default": ""
+            },
+            {
+              "name": "onPointerDown",
+              "type": "(event: PointerEvent<HTMLDivElement>) => void",
+              "default": ""
+            },
+            {
+              "name": "data-orientation",
+              "type": "string",
+              "default": ""
+            },
+            {
+              "name": "data-disabled",
+              "type": "\"\"",
+              "default": ""
+            },
+            {
+              "name": "data-invalid",
+              "type": "\"\"",
+              "default": ""
+            },
+            {
+              "name": "data-dragging",
+              "type": "\"\"",
+              "default": ""
+            }
+          ],
+          "methods": []
+        },
+        "UseCompareIndicatorProps": {
+          "description": "Pre-built props for the compare indicator element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "data-orientation",
+              "type": "string",
+              "default": ""
+            },
+            {
+              "name": "data-disabled",
+              "type": "\"\"",
+              "default": ""
+            },
+            {
+              "name": "data-invalid",
+              "type": "\"\"",
+              "default": ""
+            },
+            {
+              "name": "data-dragging",
+              "type": "\"\"",
+              "default": ""
+            }
+          ],
+          "methods": []
+        },
+        "UseCompareItemProps": {
+          "description": "Pre-built props for a compare item element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "style",
+              "type": "CSSProperties",
+              "default": ""
+            },
+            {
+              "name": "data-orientation",
+              "type": "string",
+              "default": ""
+            },
+            {
+              "name": "data-disabled",
+              "type": "\"\"",
+              "default": ""
+            },
+            {
+              "name": "data-invalid",
+              "type": "\"\"",
+              "default": ""
+            },
+            {
+              "name": "data-dragging",
+              "type": "\"\"",
+              "default": ""
+            }
+          ],
+          "methods": []
+        },
+        "UseCompareInputProps": {
+          "description": "Pre-built props for the compare hidden input element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "data-scope",
+              "type": "\"slider\"",
+              "default": ""
+            },
+            {
+              "name": "data-part",
+              "type": "\"hidden-input\"",
+              "default": ""
+            },
+            {
+              "name": "type",
+              "type": "\"range\"",
+              "default": ""
+            },
+            {
+              "name": "min",
+              "type": "number",
+              "default": ""
+            },
+            {
+              "name": "max",
+              "type": "number",
+              "default": ""
+            },
+            {
+              "name": "step",
+              "type": "number",
+              "default": ""
+            },
+            {
+              "name": "value",
+              "type": "number",
+              "default": ""
+            },
+            {
+              "name": "disabled",
+              "type": "boolean",
+              "default": ""
+            },
+            {
+              "name": "readOnly",
+              "type": "boolean",
+              "default": ""
+            },
+            {
+              "name": "tabIndex",
+              "type": "number",
+              "default": ""
+            },
+            {
+              "name": "aria-valuemin",
+              "type": "number",
+              "default": ""
+            },
+            {
+              "name": "aria-valuemax",
+              "type": "number",
+              "default": ""
+            },
+            {
+              "name": "aria-valuenow",
+              "type": "number",
+              "default": ""
+            },
+            {
+              "name": "aria-orientation",
+              "type": "\"horizontal\" | \"vertical\"",
+              "default": ""
+            },
+            {
+              "name": "aria-labelledby",
+              "type": "string",
+              "default": ""
+            },
+            {
+              "name": "aria-label",
+              "type": "string",
+              "default": ""
+            },
+            {
+              "name": "style",
+              "type": "CSSProperties",
+              "default": ""
+            },
+            {
+              "name": "onChange",
+              "type": "(event: ChangeEvent<HTMLInputElement>) => void",
+              "default": ""
+            },
+            {
+              "name": "onInput",
+              "type": "(event: FormEvent<HTMLInputElement>) => void",
+              "default": ""
+            },
+            {
+              "name": "onFocus",
+              "type": "(event: FocusEvent<HTMLInputElement>) => void",
+              "default": ""
+            },
+            {
+              "name": "onBlur",
+              "type": "(event: FocusEvent<HTMLInputElement>) => void",
+              "default": ""
+            }
+          ],
+          "methods": []
+        },
+        "UseCompareExposes": {
+          "description": "Defines the methods and properties exposed by useCompare.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "state",
+              "type": "UseCompareState",
+              "default": "",
+              "description": "State object containing current slide value"
+            },
+            {
+              "name": "slider",
+              "type": "UseSliderExposes",
+              "default": "",
+              "description": "The slider instance."
+            },
+            {
+              "name": "getItemStyle",
+              "type": "(position: \"after\" | \"before\") => CSSProperties",
+              "default": "",
+              "description": "Get item clip style."
+            },
+            {
+              "name": "getHandleStyle",
+              "type": "() => CSSProperties",
+              "default": "",
+              "description": "Get handle style."
+            },
+            {
+              "name": "rootProps",
+              "type": "UseCompareRootProps",
+              "default": "",
+              "description": "Pre-built props for the root element."
+            },
+            {
+              "name": "handleProps",
+              "type": "UseCompareHandleProps",
+              "default": "",
+              "description": "Pre-built props for the handle element."
+            },
+            {
+              "name": "inputProps",
+              "type": "UseCompareInputProps",
+              "default": "",
+              "description": "Pre-built props for the hidden input element."
+            },
+            {
+              "name": "indicatorProps",
+              "type": "UseCompareIndicatorProps",
+              "default": "",
+              "description": "Pre-built props for the indicator element."
+            },
+            {
+              "name": "getItemProps",
+              "type": "(position: \"after\" | \"before\") => UseCompareItemProps",
+              "default": "",
+              "description": "Returns pre-built props for an item element by position."
+            },
+            {
+              "name": "onRootPointerDown",
+              "type": "(event: PointerEvent<HTMLDivElement>) => void",
+              "default": "",
+              "description": "Pointer handlers for root."
+            },
+            {
+              "name": "onRootPointerMove",
+              "type": "(event: PointerEvent<HTMLDivElement>) => void",
+              "default": "",
+              "description": "Pointer move handler for root."
+            },
+            {
+              "name": "onRootPointerUp",
+              "type": "(event: PointerEvent<HTMLDivElement>) => void",
+              "default": "",
+              "description": "Pointer up handler for root."
+            },
+            {
+              "name": "updateValueFromPointer",
+              "type": "(event: PointerEvent<HTMLDivElement>) => void",
+              "default": "",
+              "description": "Update value based on pointer position."
+            },
+            {
+              "name": "onHandlePointerDown",
+              "type": "(event: PointerEvent<HTMLDivElement>) => void",
+              "default": "",
+              "description": "Pointer down handler for handle."
+            },
+            {
+              "name": "onInputChange",
+              "type": "(event: ChangeEvent<HTMLInputElement>) => void",
+              "default": "",
+              "description": "Input change handler."
+            }
+          ],
+          "methods": []
+        }
+      },
+      "types": {
+        "UseCompareInstance": {
+          "description": "Instance of useCompare headless.",
+          "values": "HeadlessInstance<UseCompareProps, UseCompareState, UseCompareExposes>"
+        }
+      },
+      "variables": {}
+    }
+  }
+]

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

@@ -0,0 +1,142 @@
+# useCompare
+
+Hook that manages compare slider state, pointer interactions, and clip-path positioning.
+
+```tsx
+'use client';
+import { Code } from '@primeicons/react/code';
+import { useCompare } from '@primereact/headless/compare';
+
+export default function BasicDemo() {
+    const { rootProps, getItemProps, handleProps, indicatorProps, inputProps } = useCompare({ defaultValue: 50 });
+
+    return (
+        <div
+            {...rootProps}
+            className="relative aspect-video max-w-lg mx-auto overflow-hidden rounded-lg cursor-ew-resize select-none"
+            style={{ touchAction: 'none' }}
+        >
+            <div {...getItemProps('after')}>
+                <img src="https://primefaces.org/cdn/primevue/images/compare/island1.jpg" draggable={false} />
+            </div>
+            <div {...getItemProps('before')}>
+                <img src="https://primefaces.org/cdn/primevue/images/compare/island2.jpg" draggable={false} />
+            </div>
+            <div
+                {...handleProps}
+                className="absolute inset-y-0 w-0.5 flex items-center justify-center bg-surface-0 dark:bg-surface-950"
+                style={handleProps.style}
+            >
+                <div
+                    {...indicatorProps}
+                    className="absolute flex items-center justify-center w-6 h-6 rounded-md bg-surface-0 dark:bg-surface-950 shadow-md"
+                >
+                    <Code />
+                </div>
+            </div>
+            <input {...inputProps} />
+        </div>
+    );
+}
+```
+
+## Usage
+
+```tsx
+import { useCompare } from '@primereact/headless/compare';
+```
+
+```tsx
+const compare = useCompare({ defaultValue: 50 });
+
+<div {...compare.rootProps}>
+    <div {...compare.getItemProps('after')}></div>
+    <div {...compare.getItemProps('before')}></div>
+    <div {...compare.handleProps}>
+        <div {...compare.getIndicatorProps()}></div>
+    </div>
+    <input {...compare.inputProps} />
+</div>;
+```
+
+`useCompare` manages pointer tracking, clip-path computation, and keyboard input for a before/after comparison. See [Primitive](/docs/primitive/components/compare) for a component-based API.
+
+## Features
+
+- **Built on `useSlider`**, inherits drag, keyboard, step, and min/max behavior from the slider primitive
+- **Clip-path layout**, `getItemProps('before' | 'after')` returns the CSS for each layer so templates stay declarative
+- **Hover mode**, `slideOnHover` moves the divider as the pointer glides across the component, no drag required
+- **Horizontal and vertical**, flip the layout with a single `orientation` prop
+- **Reactive state**, `state.value` and `state.isDragging` drive overlays, tooltips, and custom cursors
+
+## Working with callbacks
+
+### Controlled value
+
+Use `value` with `onValueChange` when the split must be driven by external state, for example, to persist it or sync multiple compares.
+
+```tsx
+const [value, setValue] = React.useState(50);
+
+const compare = useCompare({
+    value,
+    onValueChange: (e) => setValue(e.value)
+});
+```
+
+### Hover-driven comparison
+
+Enable `slideOnHover` for hero-section comparisons where pointer movement alone should reveal the other image.
+
+```tsx
+const compare = useCompare({ slideOnHover: true });
+```
+
+### Vertical layout
+
+Switch `orientation` to `'vertical'` for top/bottom comparisons.
+
+```tsx
+const compare = useCompare({ orientation: 'vertical' });
+```
+
+### Custom readouts from state
+
+Mirror the current split or drag state into your own UI.
+
+```tsx
+const compare = useCompare({ defaultValue: 50 });
+
+<span>{compare.state.value}%</span>;
+{
+    compare.state.isDragging && <span>Dragging...</span>;
+}
+```
+
+## Styling with data attributes
+
+Prop objects include orientation and state-dependent data attributes.
+
+```css
+[data-orientation='horizontal'] {
+    cursor: ew-resize;
+}
+
+[data-orientation='vertical'] {
+    cursor: ns-resize;
+}
+
+[data-dragging] {
+    cursor: grabbing;
+}
+```
+
+## API
+
+### useCompare
+
+<DocTable name="useCompare" category="api" />
+
+## Accessibility
+
+Arrow keys move the comparison slider, Home/End jump to the edges, and dragging is accessible via pointer or touch. See [Primitive](/docs/primitive/components/compare#accessibility) for full WAI-ARIA compliance details.