@primereact/mcp 11.0.0-rc.2

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

@@ -0,0 +1,195 @@
+# useRadioButton
+
+Hooks that manage radio button and radio button group state, checked logic, and ARIA attributes.
+
+```tsx
+'use client';
+import { useRadioButton, type UseRadioButtonChangeEvent } from '@primereact/headless/radiobutton';
+import { useRadioButtonGroup } from '@primereact/headless/radiobuttongroup';
+
+const items = [
+    { value: 'standard', label: 'Standard' },
+    { value: 'express', label: 'Express' },
+    { value: 'overnight', label: 'Overnight' }
+];
+
+export default function BasicDemo() {
+    const { rootProps: groupRootProps, state: groupState, updateChange } = useRadioButtonGroup({ defaultValue: 'standard' });
+
+    return (
+        <div className="flex justify-center">
+            <div {...groupRootProps} className="flex flex-col gap-3">
+                {items.map((item) => {
+                    const { rootProps, inputProps, boxProps, indicatorProps } = useRadioButton({
+                        name: 'delivery',
+                        value: item.value,
+                        checked: groupState.value === item.value,
+                        onCheckedChange: (e: UseRadioButtonChangeEvent) => updateChange({ ...e, value: item.value })
+                    });
+
+                    return (
+                        <div key={item.value} className="flex items-center gap-2">
+                            <div
+                                {...rootProps}
+                                className="relative inline-flex items-center has-[input:focus-visible]:outline-1 has-[input:focus-visible]:outline-offset-2 has-[input:focus-visible]:outline-primary has-[input:focus-visible]:outline rounded-full"
+                            >
+                                <input
+                                    {...inputProps}
+                                    value={inputProps.value as string}
+                                    id={`rb-${item.value}`}
+                                    className="absolute inset-0 w-full h-full opacity-0 cursor-pointer appearance-none m-0 p-0 border border-transparent rounded-full"
+                                />
+                                <div
+                                    {...boxProps}
+                                    className="flex items-center justify-center w-[1.125rem] h-[1.125rem] rounded-full border transition-colors duration-200 data-checked:bg-primary data-checked:border-primary data-unchecked:border-surface-300 data-unchecked:hover:border-surface-400"
+                                >
+                                    <span
+                                        {...indicatorProps}
+                                        className="w-2.5 h-2.5 rounded-full bg-primary-contrast transition-transform duration-200 data-unchecked:hidden"
+                                    />
+                                </div>
+                            </div>
+                            <label htmlFor={`rb-${item.value}`} className="cursor-pointer select-none text-sm">
+                                {item.label}
+                            </label>
+                        </div>
+                    );
+                })}
+            </div>
+        </div>
+    );
+}
+```
+
+## Usage
+
+```tsx
+import { useRadioButton } from '@primereact/headless/radiobutton';
+import { useRadioButtonGroup } from '@primereact/headless/radiobuttongroup';
+```
+
+```tsx
+const group = useRadioButtonGroup({ defaultValue: 'a' });
+const { rootProps, inputProps, boxProps, indicatorProps, state } = useRadioButton({
+    value: 'a',
+    checked: group.state.value === 'a',
+    onCheckedChange: (e) => group.updateChange({ ...e, value: 'a' })
+});
+
+<div {...rootProps}>
+    <input {...inputProps} className="sr-only" />
+    <div {...boxProps}>{state.checked && <span {...indicatorProps} />}</div>
+</div>;
+```
+
+`useRadioButton` manages checked state for a single option while `useRadioButtonGroup` manages the shared value across a group. See [Primitive](/docs/primitive/components/radiobutton) for a component-based API.
+
+## Features
+
+- **Composable parts**, spreads props onto `root`, `input`, `box`, and `indicator` elements for full visual control
+- **Group coordination**, `useRadioButtonGroup` holds the selected value and exposes `updateChange` for child radios
+- **Controlled or uncontrolled**, drive via `checked`/`onCheckedChange` or let the hook manage state from `defaultChecked`
+- **Accessible primitives**, hidden native input keeps focus management and keyboard semantics intact
+- **State flags**, `disabled` and `readOnly` emit the appropriate ARIA and `data-*` attributes
+
+## Working with callbacks
+
+### Controlled radio
+
+Pass `checked` and `onCheckedChange` to own the state externally, typical when validation lives outside the component.
+
+```tsx
+const [checked, setChecked] = React.useState(true);
+
+useRadioButton({
+    checked,
+    onCheckedChange: (e) => setChecked(e.checked)
+});
+```
+
+The callback receives `{ originalEvent, checked }` where `checked` is the new boolean.
+
+### Group with shared value
+
+`useRadioButtonGroup` owns the selected value; each radio derives `checked` and forwards events through `updateChange`.
+
+```tsx
+const group = useRadioButtonGroup({ defaultValue: 'a' });
+
+const radioA = useRadioButton({
+    value: 'a',
+    checked: group.state.value === 'a',
+    onCheckedChange: (e) => group.updateChange({ ...e, value: 'a' })
+});
+```
+
+### Controlled group
+
+Lift the group value when you need to react to changes, persist it, or reset from parent state.
+
+```tsx
+const [value, setValue] = React.useState<unknown>('a');
+
+const group = useRadioButtonGroup({
+    value,
+    onValueChange: (e) => setValue(e.value)
+});
+```
+
+### Read-only selection
+
+Use `readOnly` to keep the radio focusable (screen readers still announce it) but prevent state changes, useful for review screens.
+
+```tsx
+useRadioButton({ readOnly: true });
+```
+
+## Styling with data attributes
+
+Every prop object includes `data-scope="radiobutton"` and a `data-part` attribute. State-dependent attributes are added automatically.
+
+| Scope         | Part        | States                          |
+| ------------- | ----------- | ------------------------------- |
+| `radiobutton` | `root`      | `data-checked`, `data-disabled` |
+| `radiobutton` | `box`       | `data-checked`                  |
+| `radiobutton` | `indicator` | `data-checked`                  |
+
+```css
+[data-scope='radiobutton'][data-part='box'] {
+    width: 1.125rem;
+    height: 1.125rem;
+    border: 1px solid #ccc;
+    border-radius: 9999px;
+}
+
+[data-scope='radiobutton'][data-part='box'][data-checked] {
+    background: var(--p-primary-color);
+    border-color: var(--p-primary-color);
+}
+
+[data-scope='radiobutton'][data-part='indicator'][data-checked] {
+    width: 0.625rem;
+    height: 0.625rem;
+    border-radius: 9999px;
+    background: white;
+}
+
+[data-scope='radiobutton'][data-part='root'][data-disabled] {
+    opacity: 0.5;
+    cursor: not-allowed;
+}
+```
+
+## API
+
+### useRadioButton
+
+<DocTable name="useRadioButton" category="api" />
+
+### useRadioButtonGroup
+
+<DocTable name="useRadioButtonGroup" category="api" />
+
+## Accessibility
+
+Arrow keys move between radios in the same group, and the focused radio is automatically selected. See [Primitive](/docs/primitive/components/radiobutton#accessibility) for full WAI-ARIA compliance details.

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

@@ -0,0 +1,347 @@
+[
+  {
+    "name": "useRating",
+    "source": "apps/showcase/assets/apidoc/userating.json",
+    "data": {
+      "description": "The useRating manages the state and functionality of a rating component.",
+      "interfaces": {
+        "UseRatingValueChangeEvent": {
+          "description": "Event fired when the rating value changes.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "originalEvent",
+              "type": "E",
+              "default": "",
+              "description": "The original event that triggered the change."
+            },
+            {
+              "name": "value",
+              "type": "number",
+              "default": "",
+              "description": "The new rating value."
+            }
+          ],
+          "methods": []
+        },
+        "UseRatingProps": {
+          "description": "Defines valid properties in useRating.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "value",
+              "type": "number",
+              "default": "",
+              "description": "Value of the rating."
+            },
+            {
+              "name": "defaultValue",
+              "type": "number",
+              "default": "0",
+              "description": "The default value of the rating."
+            },
+            {
+              "name": "allowHalf",
+              "type": "boolean",
+              "default": "true",
+              "description": "Whether to allow half stars."
+            },
+            {
+              "name": "name",
+              "type": "string",
+              "default": "",
+              "description": "Name used for the hidden radio inputs. Auto-generated if not provided."
+            },
+            {
+              "name": "orientation",
+              "type": "\"horizontal\" | \"vertical\"",
+              "default": "'horizontal'",
+              "description": "The orientation of the rating."
+            },
+            {
+              "name": "disabled",
+              "type": "boolean",
+              "default": "false",
+              "description": "When present, it specifies that the element should be disabled."
+            },
+            {
+              "name": "readOnly",
+              "type": "boolean",
+              "default": "false",
+              "description": "When present, it specifies that component is read-only."
+            },
+            {
+              "name": "invalid",
+              "type": "boolean",
+              "default": "false",
+              "description": "When present, it specifies that the component should have invalid state style."
+            },
+            {
+              "name": "onValueChange",
+              "type": "(event: UseRatingValueChangeEvent) => void",
+              "default": "",
+              "description": "Callback fired when the value changes."
+            }
+          ],
+          "methods": []
+        },
+        "UseRatingState": {
+          "description": "Defines valid state in useRating.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "value",
+              "type": "number",
+              "default": "",
+              "description": "The current value of the rating."
+            },
+            {
+              "name": "hovering",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether the rating is in a hover state."
+            },
+            {
+              "name": "hoveringValue",
+              "type": "number",
+              "default": "",
+              "description": "The value currently being hovered over."
+            }
+          ],
+          "methods": []
+        },
+        "UseRatingRootProps": {
+          "description": "Data attribute props shared by Rating elements.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "data-scope",
+              "type": "string",
+              "default": "",
+              "description": "Component scope identifier."
+            },
+            {
+              "name": "data-part",
+              "type": "string",
+              "default": "",
+              "description": "Component part identifier."
+            },
+            {
+              "name": "data-orientation",
+              "type": "string",
+              "default": "",
+              "description": "Layout orientation."
+            },
+            {
+              "name": "[key: string]",
+              "type": "unknown",
+              "description": ""
+            }
+          ],
+          "methods": []
+        },
+        "UseRatingExposes": {
+          "description": "Defines the methods and properties exposed by useRating.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "state",
+              "type": "UseRatingState",
+              "default": "",
+              "description": "Current state of the rating."
+            },
+            {
+              "name": "inputName",
+              "type": "string",
+              "default": "",
+              "description": "The computed name used for radio inputs (from props.name or auto-generated).\nNamed 'inputName' to avoid collision with withComponent's common.name."
+            },
+            {
+              "name": "rootProps",
+              "type": "UseRatingRootProps",
+              "default": "",
+              "description": "Pre-built props for the root element (data attributes + event handlers)."
+            },
+            {
+              "name": "updateValue",
+              "type": "(event: SyntheticEvent, value: number) => void",
+              "default": "",
+              "description": "Update the rating value."
+            },
+            {
+              "name": "setHoveringValue",
+              "type": "(value: number) => void",
+              "default": "",
+              "description": "Set the hover value (called by On/Off on pointer move)."
+            },
+            {
+              "name": "resolvePointerValue",
+              "type": "(e: MouseEvent<Element, MouseEvent> | PointerEvent<Element>, optionEl: Element, idx: number) => number",
+              "default": "",
+              "description": "Resolves the value to set from a pointer event, taking allowHalf and element position into account."
+            },
+            {
+              "name": "optionProps",
+              "type": "UseRatingRootProps",
+              "default": "",
+              "description": "Pre-built data attribute props for the option element."
+            },
+            {
+              "name": "onProps",
+              "type": "UseRatingRootProps",
+              "default": "",
+              "description": "Pre-built data attribute props for the on-icon element."
+            },
+            {
+              "name": "offProps",
+              "type": "UseRatingRootProps",
+              "default": "",
+              "description": "Pre-built data attribute props for the off-icon element."
+            }
+          ],
+          "methods": []
+        }
+      },
+      "types": {
+        "UseRatingInstance": {
+          "description": "Instance of useRating headless.",
+          "values": "HeadlessInstance<UseRatingProps, UseRatingState, UseRatingExposes>"
+        }
+      },
+      "variables": {}
+    }
+  },
+  {
+    "name": "useRatingOption",
+    "source": "apps/showcase/assets/apidoc/useratingoption.json",
+    "data": {
+      "description": "The useRatingOption manages state and interactions for a single rating option (star).",
+      "interfaces": {
+        "UseRatingOptionProps": {
+          "description": "Defines valid properties in useRatingOption.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "index",
+              "type": "number",
+              "default": "",
+              "description": "The zero-based index of this option within the rating."
+            },
+            {
+              "name": "context",
+              "type": "UseRatingInstance",
+              "default": "",
+              "description": "The parent useRating instance providing state and methods."
+            }
+          ],
+          "methods": []
+        },
+        "UseRatingOptionState": {
+          "description": "Defines valid state in useRatingOption.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "highlighted",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether this option is highlighted (fully or partially filled)."
+            },
+            {
+              "name": "half",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether this option is half-filled."
+            },
+            {
+              "name": "checked",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether this option is the checked/active one."
+            },
+            {
+              "name": "activeValue",
+              "type": "number",
+              "default": "",
+              "description": "The active value (hovering value or committed value)."
+            }
+          ],
+          "methods": []
+        },
+        "UseRatingOptionExposes": {
+          "description": "Defines the methods and properties exposed by useRatingOption.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "state",
+              "type": "UseRatingOptionState",
+              "default": "",
+              "description": "Current state of this option."
+            },
+            {
+              "name": "optionRef",
+              "type": "RefObject<Element>",
+              "default": "",
+              "description": "Ref to the option's root DOM element, used internally for pointer position calculations."
+            },
+            {
+              "name": "optionProps",
+              "type": "Record<string, string | number>",
+              "default": "",
+              "description": "Pre-built data attribute props for the option element."
+            },
+            {
+              "name": "onIconProps",
+              "type": "{ onMouseDown: (e: MouseEvent) => void; onPointerMove: (e: PointerEvent) => void; onClick: (e: MouseEvent) => void }",
+              "default": "",
+              "description": "Pre-built interaction props for the on-icon element."
+            },
+            {
+              "name": "offIconProps",
+              "type": "{ onMouseDown: (e: MouseEvent) => void; onPointerMove: (e: PointerEvent) => void; onClick: (e: MouseEvent) => void }",
+              "default": "",
+              "description": "Pre-built interaction props for the off-icon element."
+            },
+            {
+              "name": "onPointerMove",
+              "type": "(e: PointerEvent) => void",
+              "default": "",
+              "description": "Handle pointer move on On/Off elements (resolves half/full value and sets hovering value)."
+            },
+            {
+              "name": "onClick",
+              "type": "(e: MouseEvent) => void",
+              "default": "",
+              "description": "Handle click on On/Off elements (resolves half/full value and updates value)."
+            },
+            {
+              "name": "onMouseDown",
+              "type": "(e: MouseEvent) => void",
+              "default": "",
+              "description": "Prevent default on mouse down (avoids focus shift)."
+            },
+            {
+              "name": "halfInputProps",
+              "type": "InputHTMLAttributes<HTMLInputElement>",
+              "default": "",
+              "description": "Pre-built props for the half-value sr-only radio input. Null when allowHalf is false."
+            },
+            {
+              "name": "fullInputProps",
+              "type": "InputHTMLAttributes<HTMLInputElement>",
+              "default": "",
+              "description": "Pre-built props for the full-value sr-only radio input."
+            }
+          ],
+          "methods": []
+        }
+      },
+      "types": {
+        "UseRatingOptionInstance": {
+          "description": "Instance of useRatingOption headless.",
+          "values": "HeadlessInstance<UseRatingOptionProps, UseRatingOptionState, UseRatingOptionExposes>"
+        }
+      },
+      "variables": {}
+    }
+  }
+]