@primereact/mcp 11.0.0-rc.2

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

@@ -0,0 +1,183 @@
+# useToggleButton
+
+Hooks that manage toggle button pressed state and group value selection with single or multiple modes.
+
+```tsx
+'use client';
+import { AlignCenter } from '@primeicons/react/align-center';
+import { AlignJustify } from '@primeicons/react/align-justify';
+import { AlignLeft } from '@primeicons/react/align-left';
+import { AlignRight } from '@primeicons/react/align-right';
+import { Bookmark } from '@primeicons/react/bookmark';
+import { useToggleButton, type UseToggleButtonChangeEvent } from '@primereact/headless/togglebutton';
+import { useToggleButtonGroup } from '@primereact/headless/togglebuttongroup';
+
+const alignOptions = [
+    { value: 'left', icon: AlignLeft },
+    { value: 'center', icon: AlignCenter },
+    { value: 'right', icon: AlignRight },
+    { value: 'justify', icon: AlignJustify }
+];
+
+export default function BasicDemo() {
+    const toggle = useToggleButton();
+    const rootProps = toggle.getRootProps(false, false);
+    const indicatorProps = toggle.getIndicatorProps(false, false);
+
+    const group = useToggleButtonGroup({ allowEmpty: false });
+
+    return (
+        <div className="flex flex-col items-center gap-6">
+            <button
+                {...rootProps}
+                className="inline-flex items-center justify-center size-8 rounded-lg border border-surface-200 dark:border-surface-700 bg-surface-100 dark:bg-surface-900 text-surface-500 dark:text-surface-400 data-[pressed]:text-primary data-[pressed]:border-primary/30 data-[pressed]:bg-primary/10 cursor-pointer select-none transition-colors duration-200 focus-visible:outline-1 focus-visible:outline-offset-2 focus-visible:outline-primary disabled:opacity-60 disabled:pointer-events-none"
+            >
+                <span {...indicatorProps}>
+                    <Bookmark />
+                </span>
+            </button>
+
+            <div {...group.rootProps} className="inline-flex rounded-lg border border-surface-200 dark:border-surface-700">
+                {alignOptions.map((option) => {
+                    const btn = useToggleButton({
+                        pressed: group.isPressed(group.state.value, option.value),
+                        onPressedChange: (e: UseToggleButtonChangeEvent) => group.updateChange({ ...e, value: option.value })
+                    });
+                    const btnRootProps = btn.getRootProps(false, false);
+                    const Icon = option.icon;
+
+                    return (
+                        <button
+                            key={option.value}
+                            {...btnRootProps}
+                            className="inline-flex items-center justify-center size-8 bg-surface-100 dark:bg-surface-900 text-surface-500 dark:text-surface-400 data-[pressed]:bg-primary data-[pressed]:text-primary-contrast border-r border-surface-200 dark:border-surface-700 last:border-r-0 cursor-pointer select-none transition-colors duration-200 focus-visible:outline-1 focus-visible:outline-offset-2 focus-visible:outline-primary focus-visible:z-10 disabled:opacity-60 disabled:pointer-events-none"
+                        >
+                            <Icon className="size-4" />
+                        </button>
+                    );
+                })}
+            </div>
+        </div>
+    );
+}
+```
+
+## Usage
+
+```tsx
+import { useToggleButton } from '@primereact/headless/togglebutton';
+import { useToggleButtonGroup } from '@primereact/headless/togglebuttongroup';
+```
+
+```tsx
+const toggle = useToggleButton();
+
+<button {...toggle.getRootProps()}>
+    <span {...toggle.getIndicatorProps()}></span>
+</button>;
+```
+
+`useToggleButton` manages a boolean pressed state and returns prop getter functions for root and indicator elements. `useToggleButtonGroup` coordinates multiple toggle buttons with single or multiple selection. See [Primitive](/docs/primitive/components/togglebutton) for a component-based API.
+
+## Features
+
+- **Prop getter API**, `getRootProps` and `getIndicatorProps` accept resolved disabled and invalid state at call time
+- **Controlled or uncontrolled**, `pressed`/`onPressedChange` for owned state, `defaultPressed` for hook-managed state
+- **Group coordination**, `useToggleButtonGroup` manages shared value and exposes `isPressed` / `updateChange` for children
+- **Single or multiple**, group switches between radio-like and multi-select behavior via the `multiple` flag
+- **Minimum selection**, group `allowEmpty` guarantees at least one button stays pressed when set to `false`
+
+## Working with callbacks
+
+### Controlled pressed state
+
+Pass `pressed` and `onPressedChange` to own the state externally, required when toggles drive other UI or persist across reloads.
+
+```tsx
+const [pressed, setPressed] = React.useState(false);
+
+useToggleButton({
+    pressed,
+    onPressedChange: (e) => setPressed(e.pressed)
+});
+```
+
+### Dynamic disabled / invalid
+
+`getRootProps(disabled, invalid)` accepts booleans so you can compute state at render time from form context.
+
+```tsx
+const rootProps = toggle.getRootProps(isSubmitting, hasError);
+```
+
+### Group as a formatting toolbar
+
+Use `useToggleButtonGroup` with `multiple: true` to build a toolbar where each button represents an independent flag.
+
+```tsx
+const group = useToggleButtonGroup({ multiple: true });
+
+const bold = useToggleButton({
+    pressed: group.isPressed(group.state.value, 'bold'),
+    onPressedChange: (e) => group.updateChange({ ...e, value: 'bold' })
+});
+```
+
+### Require a selection
+
+Set `allowEmpty: false` when the group represents a mandatory choice like view mode or alignment.
+
+```tsx
+const group = useToggleButtonGroup({ allowEmpty: false, defaultValue: 'left' });
+```
+
+### Read live state for custom UI
+
+Expose `state.pressed` or `state.value` to show counts, icons, or status text derived from the current selection.
+
+```tsx
+const group = useToggleButtonGroup({ multiple: true });
+// group.state.value: unknown[]
+
+const toggle = useToggleButton();
+// toggle.state.pressed: boolean
+```
+
+## Styling with data attributes
+
+The prop getters include data attributes for styling.
+
+| Scope               | Part   | States                          |
+| ------------------- | ------ | ------------------------------- |
+| `togglebutton`      | `root` | `data-pressed`, `data-disabled` |
+| `togglebuttongroup` | `root` | `data-multiple`                 |
+
+```css
+button[data-pressed] {
+    background-color: var(--p-primary-color);
+    color: var(--p-primary-contrast-color);
+}
+
+button[data-disabled] {
+    pointer-events: none;
+    opacity: 0.6;
+}
+
+[data-scope='togglebuttongroup'][data-multiple] {
+    /* styles for multi-select group */
+}
+```
+
+## API
+
+### useToggleButton
+
+<DocTable name="useToggleButton" category="api" />
+
+### useToggleButtonGroup
+
+<DocTable name="useToggleButtonGroup" category="api" />
+
+## Accessibility
+
+Space or Enter toggles the pressed state while focused. See [Primitive](/docs/primitive/components/togglebutton#accessibility) for full WAI-ARIA compliance details.

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

@@ -0,0 +1,326 @@
+[
+  {
+    "name": "useToggleSwitch",
+    "source": "apps/showcase/assets/apidoc/usetoggleswitch.json",
+    "data": {
+      "description": "The useToggleSwitch manages the state and functionality of a toggle switch component.",
+      "interfaces": {
+        "UseToggleSwitchChangeEvent": {
+          "description": "Event fired when the toggle switch's checked state changes.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "originalEvent",
+              "type": "E",
+              "default": "",
+              "description": "The original event that triggered the change."
+            },
+            {
+              "name": "checked",
+              "type": "boolean",
+              "default": "",
+              "description": "The checked state of the toggle switch."
+            }
+          ],
+          "methods": []
+        },
+        "UseToggleSwitchProps": {
+          "description": "Defines valid properties in useToggleSwitch.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "checked",
+              "type": "boolean",
+              "default": "",
+              "description": "When present, it specifies the input's checked state."
+            },
+            {
+              "name": "defaultChecked",
+              "type": "boolean",
+              "default": "",
+              "description": "The default value for the input when not controlled by  `checked`  and  `onCheckedChange` ."
+            },
+            {
+              "name": "disabled",
+              "type": "boolean",
+              "default": "false",
+              "description": "Whether the toggle switch is disabled."
+            },
+            {
+              "name": "invalid",
+              "type": "boolean",
+              "default": "false",
+              "description": "When present, it specifies that the toggle switch value is invalid."
+            },
+            {
+              "name": "tabIndex",
+              "type": "number",
+              "default": "",
+              "description": "Index of the element in tabbing order."
+            },
+            {
+              "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": "FocusEventHandler<HTMLInputElement>",
+              "default": "",
+              "description": "Callback function that is called when the toggle switch is focused."
+            },
+            {
+              "name": "onBlur",
+              "type": "FocusEventHandler<HTMLInputElement>",
+              "default": "",
+              "description": "Callback function that is called when the toggle switch loses focus."
+            },
+            {
+              "name": "onCheckedChange",
+              "type": "(event: UseToggleSwitchChangeEvent) => void",
+              "default": "",
+              "description": "Callback fired when the toggle switch's checked state changes."
+            }
+          ],
+          "methods": []
+        },
+        "UseToggleSwitchState": {
+          "description": "Defines valid state in useToggleSwitch.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "checked",
+              "type": "boolean",
+              "default": "",
+              "description": "The checked state of the useToggleSwitch."
+            }
+          ],
+          "methods": []
+        },
+        "UseToggleSwitchRootProps": {
+          "description": "Pre-built props for the toggle switch root element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "data-checked",
+              "type": "\"\"",
+              "default": "",
+              "description": "Data attribute when checked."
+            },
+            {
+              "name": "data-unchecked",
+              "type": "\"\"",
+              "default": "",
+              "description": "Data attribute when unchecked."
+            },
+            {
+              "name": "data-disabled",
+              "type": "\"\"",
+              "default": "",
+              "description": "Data attribute when disabled."
+            },
+            {
+              "name": "data-invalid",
+              "type": "\"\"",
+              "default": "",
+              "description": "Data attribute when invalid."
+            }
+          ],
+          "methods": []
+        },
+        "UseToggleSwitchInputProps": {
+          "description": "Pre-built props for the toggle switch input element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "type",
+              "type": "\"checkbox\"",
+              "default": "",
+              "description": "Input type."
+            },
+            {
+              "name": "role",
+              "type": "\"switch\"",
+              "default": "",
+              "description": "ARIA role."
+            },
+            {
+              "name": "checked",
+              "type": "boolean",
+              "default": "",
+              "description": "Checked state."
+            },
+            {
+              "name": "aria-checked",
+              "type": "boolean",
+              "default": "",
+              "description": "ARIA checked state."
+            },
+            {
+              "name": "aria-invalid",
+              "type": "true",
+              "default": "",
+              "description": "ARIA invalid state."
+            },
+            {
+              "name": "tabIndex",
+              "type": "number",
+              "default": "",
+              "description": "Tab index."
+            },
+            {
+              "name": "aria-labelledby",
+              "type": "string",
+              "default": "",
+              "description": "ID of the element that labels the toggle switch."
+            },
+            {
+              "name": "aria-label",
+              "type": "string",
+              "default": "",
+              "description": "ARIA label."
+            },
+            {
+              "name": "onFocus",
+              "type": "FocusEventHandler<HTMLInputElement>",
+              "default": "",
+              "description": "Focus handler."
+            },
+            {
+              "name": "onBlur",
+              "type": "FocusEventHandler<HTMLInputElement>",
+              "default": "",
+              "description": "Blur handler."
+            },
+            {
+              "name": "onChange",
+              "type": "(event: UseToggleSwitchChangeEvent) => void",
+              "default": "",
+              "description": "Change handler."
+            }
+          ],
+          "methods": []
+        },
+        "UseToggleSwitchControlProps": {
+          "description": "Pre-built props for the toggle switch control element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "data-checked",
+              "type": "\"\"",
+              "default": "",
+              "description": "Data attribute when checked."
+            },
+            {
+              "name": "data-unchecked",
+              "type": "\"\"",
+              "default": "",
+              "description": "Data attribute when unchecked."
+            },
+            {
+              "name": "data-disabled",
+              "type": "\"\"",
+              "default": "",
+              "description": "Data attribute when disabled."
+            },
+            {
+              "name": "data-invalid",
+              "type": "\"\"",
+              "default": "",
+              "description": "Data attribute when invalid."
+            }
+          ],
+          "methods": []
+        },
+        "UseToggleSwitchHandleProps": {
+          "description": "Pre-built props for the toggle switch handle element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "data-checked",
+              "type": "\"\"",
+              "default": "",
+              "description": "Data attribute when checked."
+            },
+            {
+              "name": "data-unchecked",
+              "type": "\"\"",
+              "default": "",
+              "description": "Data attribute when unchecked."
+            },
+            {
+              "name": "data-disabled",
+              "type": "\"\"",
+              "default": "",
+              "description": "Data attribute when disabled."
+            },
+            {
+              "name": "data-invalid",
+              "type": "\"\"",
+              "default": "",
+              "description": "Data attribute when invalid."
+            }
+          ],
+          "methods": []
+        },
+        "UseToggleSwitchExposes": {
+          "description": "Defines the methods and properties exposed by useToggleSwitch.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "state",
+              "type": "UseToggleSwitchState",
+              "default": "",
+              "description": "The state of the useToggleSwitch."
+            },
+            {
+              "name": "onChange",
+              "type": "(event: UseToggleSwitchChangeEvent) => void",
+              "default": "",
+              "description": "Callback fired when the useToggleSwitch's checked state changes."
+            },
+            {
+              "name": "rootProps",
+              "type": "UseToggleSwitchRootProps",
+              "default": "",
+              "description": "Pre-built props for the root element."
+            },
+            {
+              "name": "inputProps",
+              "type": "UseToggleSwitchInputProps",
+              "default": "",
+              "description": "Pre-built props for the input element."
+            },
+            {
+              "name": "controlProps",
+              "type": "UseToggleSwitchControlProps",
+              "default": "",
+              "description": "Pre-built props for the control element."
+            },
+            {
+              "name": "handleProps",
+              "type": "UseToggleSwitchHandleProps",
+              "default": "",
+              "description": "Pre-built props for the handle element."
+            }
+          ],
+          "methods": []
+        }
+      },
+      "types": {
+        "UseToggleSwitchInstance": {
+          "description": "Instance of useToggleSwitch headless.",
+          "values": "HeadlessInstance<UseToggleSwitchProps, UseToggleSwitchState, UseToggleSwitchExposes>"
+        }
+      },
+      "variables": {}
+    }
+  }
+]

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

@@ -0,0 +1,164 @@
+# useToggleSwitch
+
+Hook that manages toggle switch state, checked/unchecked logic, and ARIA attributes.
+
+```tsx
+'use client';
+import * as React from 'react';
+import { useToggleSwitch } from '@primereact/headless/toggleswitch';
+
+export default function BasicDemo() {
+    const { rootProps, inputProps, controlProps, handleProps } = useToggleSwitch({ defaultChecked: false });
+
+    return (
+        <div className="flex justify-center">
+            <div 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 as unknown as React.InputHTMLAttributes<HTMLInputElement>)}
+                        id="basic-switch"
+                        className="absolute z-2 inset-0 w-full h-full opacity-0 cursor-pointer appearance-none m-0 p-0 border border-transparent rounded-full"
+                    />
+                    <div
+                        {...controlProps}
+                        className="relative w-10 h-6 rounded-full transition-colors duration-200 bg-surface-300 dark:bg-surface-600 data-[checked]:bg-primary"
+                    >
+                        <span
+                            {...handleProps}
+                            className="absolute top-1 block w-4 h-4 rounded-full bg-white shadow transition-transform duration-200 translate-x-1 data-[checked]:translate-x-5"
+                        />
+                    </div>
+                </div>
+                <label htmlFor="basic-switch" className="cursor-pointer select-none text-sm">
+                    Notifications
+                </label>
+            </div>
+        </div>
+    );
+}
+```
+
+## Usage
+
+```tsx
+import { useToggleSwitch } from '@primereact/headless/toggleswitch';
+```
+
+```tsx
+const { rootProps, inputProps, controlProps, handleProps } = useToggleSwitch({
+    defaultChecked: false
+});
+
+<div {...rootProps}>
+    <input {...inputProps} />
+    <div {...controlProps}>
+        <span {...handleProps} />
+    </div>
+</div>;
+```
+
+`useToggleSwitch` manages boolean toggle state with a hidden native checkbox using `role="switch"`. See [Primitive](/docs/primitive/components/toggleswitch) for a component-based API.
+
+## Features
+
+- **Composable parts**, spreads props onto `root`, `input`, `control`, and `handle` elements so the visual track and handle are fully yours
+- **Switch semantics**, hidden native checkbox with `role="switch"` preserves screen reader and keyboard behavior
+- **Controlled or uncontrolled**, drive via `checked`/`onCheckedChange` or let the hook manage state from `defaultChecked`
+- **Validation flags**, `invalid` and `disabled` emit `aria-invalid`, `data-invalid`, and `data-disabled` across the parts
+- **Animation-ready**, `data-checked` on `control` and `handle` lets you transition the track color and handle position via CSS
+
+## Working with callbacks
+
+### Controlled toggle switch
+
+Pass `checked` and `onCheckedChange` to own the state externally, needed for settings pages, async toggles, or validation flows.
+
+```tsx
+const [checked, setChecked] = React.useState(false);
+
+useToggleSwitch({
+    checked,
+    onCheckedChange: (e) => setChecked(e.checked)
+});
+```
+
+The callback receives `{ originalEvent, checked }` where `checked` is the new boolean.
+
+### Async confirmation before commit
+
+Intercept `onCheckedChange` to run a confirmation or network call before applying the new state.
+
+```tsx
+const [checked, setChecked] = React.useState(false);
+
+useToggleSwitch({
+    checked,
+    onCheckedChange: async (e) => {
+        if (await confirmChange(e.checked)) setChecked(e.checked);
+    }
+});
+```
+
+### Invalid state tied to form validation
+
+Flip `invalid` from your form state so CSS can react via `data-invalid`.
+
+```tsx
+useToggleSwitch({
+    invalid: formState.errors.notifications != null
+});
+```
+
+## Styling with data attributes
+
+Every prop object includes `data-scope="toggleswitch"` and a `data-part` attribute. State-dependent attributes are added automatically.
+
+| Scope          | Part      | States                                          |
+| -------------- | --------- | ----------------------------------------------- |
+| `toggleswitch` | `root`    | `data-checked`, `data-disabled`, `data-invalid` |
+| `toggleswitch` | `control` | `data-checked`, `data-disabled`, `data-invalid` |
+| `toggleswitch` | `handle`  | `data-checked`, `data-disabled`, `data-invalid` |
+
+```css
+[data-scope='toggleswitch'][data-part='control'] {
+    width: 2.5rem;
+    height: 1.5rem;
+    border-radius: 9999px;
+    background: #ccc;
+    transition: background 200ms;
+}
+
+[data-scope='toggleswitch'][data-part='control'][data-checked] {
+    background: var(--p-primary-color);
+}
+
+[data-scope='toggleswitch'][data-part='handle'] {
+    width: 1rem;
+    height: 1rem;
+    border-radius: 9999px;
+    background: white;
+    transition: transform 200ms;
+}
+
+[data-scope='toggleswitch'][data-part='handle'][data-checked] {
+    transform: translateX(1rem);
+}
+
+[data-scope='toggleswitch'][data-part='root'][data-disabled] {
+    opacity: 0.5;
+    cursor: not-allowed;
+}
+```
+
+## API
+
+### useToggleSwitch
+
+<DocTable name="useToggleSwitch" category="api" />
+
+## Accessibility
+
+Space toggles the on/off state while focused, matching native checkbox keyboard behavior. See [Primitive](/docs/primitive/components/toggleswitch#accessibility) for full WAI-ARIA compliance details.