@primereact/mcp 11.0.0-rc.2

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

@@ -0,0 +1,277 @@
+# useToast
+
+Hooks that manage toast notification state, swipe dismissal, auto-timeout, and stacking behavior.
+
+```tsx
+'use client';
+import { Check } from '@primeicons/react/check';
+import { ExclamationTriangle } from '@primeicons/react/exclamation-triangle';
+import { InfoCircle } from '@primeicons/react/info-circle';
+import { Times } from '@primeicons/react/times';
+import { usePortal } from '@primereact/headless/portal';
+import { useToast } from '@primereact/headless/toast';
+import { toast, useToaster } from '@primereact/headless/toaster';
+import { ToastType } from 'primereact/toaster';
+import * as React from 'react';
+import { createPortal } from 'react-dom';
+
+const severityIcons: Record<string, React.ReactNode> = {
+    success: <Check />,
+    error: <Times />,
+    warn: <ExclamationTriangle />,
+    info: <InfoCircle />
+};
+
+function ToastItem({ toastData, toaster }: { toastData: ToastType; toaster: ReturnType<typeof useToaster> }) {
+    const { rootProps, messageProps, contentProps, closeProps } = useToast({ toast: toastData, toaster });
+
+    return (
+        <div
+            {...rootProps}
+            className={[
+                'w-full p-4 rounded-lg border border-surface-200 dark:border-surface-800 bg-surface-0 dark:bg-surface-900 text-surface-900 dark:text-surface-0',
+                'outline-none absolute touch-none shadow-sm z-[var(--px-toast-z-index)]',
+                'opacity-0 [transform:translateX(var(--offset-x))_translateY(calc(100%*var(--raise-factor)*-1))]',
+                '[transition:transform_0.3s,opacity_0.3s,height_0.3s]',
+                'focus-visible:outline-1 focus-visible:outline-primary focus-visible:outline-offset-2',
+                'data-[mounted]:opacity-100 data-[mounted]:[transform:translateY(0)]',
+                'not-data-[expanded]:not-data-[front]:overflow-hidden not-data-[expanded]:not-data-[front]:h-[var(--px-front-toast-height)] not-data-[expanded]:not-data-[front]:[transform:translateX(var(--offset-x))_translateY(calc(var(--raise-factor)*var(--px-toast-index)*var(--px-gap)))_scale(calc(var(--px-toast-index)*-0.05+1))]',
+                'data-[mounted]:data-[expanded]:h-[var(--px-initial-height)] data-[mounted]:data-[expanded]:[transform:translateX(var(--offset-x))_translateY(var(--offset-y))]',
+                'data-[expanded]:after:content-[""] data-[expanded]:after:absolute data-[expanded]:after:left-0 data-[expanded]:after:h-[calc(var(--px-gap)+1px)] data-[expanded]:after:w-full data-[expanded]:after:bottom-full',
+                'not-data-[visible]:!opacity-0 not-data-[visible]:!pointer-events-none not-data-[visible]:!select-none',
+                'data-[removed]:data-[front]:not-data-[swipe-out]:opacity-0 data-[removed]:data-[front]:not-data-[swipe-out]:[transform:translateX(var(--offset-x))_translateY(calc(var(--raise-factor)*-100%))]',
+                'data-[removed]:not-data-[front]:not-data-[swipe-out]:data-[expanded]:opacity-0 data-[removed]:not-data-[front]:not-data-[swipe-out]:data-[expanded]:[transform:translateX(var(--offset-x))_translateY(calc(var(--raise-factor)*var(--offset-y)*0.4))]',
+                'data-[removed]:not-data-[front]:not-data-[swipe-out]:not-data-[expanded]:opacity-0 data-[removed]:not-data-[front]:not-data-[swipe-out]:not-data-[expanded]:[transform:translateX(var(--offset-x))_translateY(calc(var(--raise-factor)*40%*-1))] data-[removed]:not-data-[front]:not-data-[swipe-out]:not-data-[expanded]:[transition:transform_500ms,opacity_200ms]',
+                'data-[swiping]:!transition-none data-[swiping]:![transform:translateX(var(--offset-x))_translateY(var(--offset-y))]',
+                'data-[swiped]:select-none',
+                'data-[swipe-out]:data-[swipe-direction=up]:opacity-0 data-[swipe-out]:data-[swipe-direction=up]:![transform:translateX(var(--offset-x))_translateY(calc(var(--offset-y)-100%))]',
+                'data-[swipe-out]:data-[swipe-direction=down]:opacity-0 data-[swipe-out]:data-[swipe-direction=down]:![transform:translateX(var(--offset-x))_translateY(calc(var(--offset-y)+100%))]',
+                'data-[swipe-out]:data-[swipe-direction=left]:opacity-0 data-[swipe-out]:data-[swipe-direction=left]:![transform:translateX(calc(var(--offset-x)-100%))_translateY(var(--offset-y))]',
+                'data-[swipe-out]:data-[swipe-direction=right]:opacity-0 data-[swipe-out]:data-[swipe-direction=right]:![transform:translateX(calc(var(--offset-x)+100%))_translateY(var(--offset-y))] data-[swipe-out]:data-[swipe-direction=right]:[transition:transform_500ms,opacity_200ms]'
+            ].join(' ')}
+            style={
+                {
+                    ...rootProps.style,
+                    '--offset-y': `calc(var(--px-swipe-amount-y) + (var(--px-toast-offset) + var(--px-toast-index) * var(--px-gap)) * var(--raise-factor))`,
+                    '--offset-x': 'var(--px-swipe-amount-x)',
+                    bottom: 0,
+                    right: 0,
+                    '--raise-factor': '-1'
+                } as React.CSSProperties
+            }
+        >
+            <div {...messageProps} className="grid grid-cols-[auto_1fr] items-start gap-3">
+                {severityIcons[toastData.severity as string] && (
+                    <span className="[&>svg]:size-3.5 mt-1 text-surface-800 dark:text-surface-100">
+                        {severityIcons[toastData.severity as string]}
+                    </span>
+                )}
+                <div {...contentProps}>
+                    {toastData.title && <div className="text-sm font-semibold text-surface-800 dark:text-surface-100">{toastData.title}</div>}
+                    {toastData.description && <div className="text-sm text-surface-500 dark:text-surface-400 mt-1">{toastData.description}</div>}
+                </div>
+            </div>
+            {toastData.dismissible !== false && !toastData.loading && (
+                <button
+                    {...closeProps}
+                    className="absolute top-2 right-2 p-1 rounded text-surface-400 hover:text-surface-600 dark:hover:text-surface-200 cursor-pointer focus-visible:outline-1 focus-visible:outline-primary"
+                >
+                    <Times className="size-3" />
+                </button>
+            )}
+        </div>
+    );
+}
+
+export default function BasicDemo() {
+    const toaster = useToaster({ position: 'bottom-right', group: 'headless-basic' });
+    const portal = usePortal();
+
+    return (
+        <div className="flex flex-wrap items-center justify-center gap-4">
+            <button
+                onClick={() =>
+                    toast({
+                        severity: 'success',
+                        title: 'Saved successfully',
+                        description: 'Your changes have been saved.',
+                        group: 'headless-basic'
+                    })
+                }
+                className="px-2.5 py-1.5 text-sm rounded-md border border-surface-200 dark:border-surface-700 text-surface-700 dark:text-surface-200 hover:bg-surface-50 dark:hover:bg-surface-800 cursor-pointer focus-visible:outline-1 focus-visible:outline-primary"
+            >
+                Create toast
+            </button>
+            {portal.state.mounted &&
+                createPortal(
+                    <div {...toaster.regionProps} className="fixed w-75 z-[2000] right-8 bottom-8" style={toaster.regionProps.style}>
+                        {toaster.toasts.map((t) => (
+                            <ToastItem key={t.id} toastData={t} toaster={toaster} />
+                        ))}
+                    </div>,
+
+                    document.body
+                )}
+        </div>
+    );
+}
+```
+
+## Usage
+
+```tsx
+import { toast, useToaster } from '@primereact/headless/toaster';
+import { useToast } from '@primereact/headless/toast';
+```
+
+```tsx
+const toaster = useToaster({ position: 'bottom-right' });
+const { rootProps, regionProps, toasts } = toaster;
+
+const { rootProps: toastRootProps, closeProps, state } = useToast({ toast: toastData, toaster });
+
+<div {...rootProps}>
+    <div {...regionProps}>
+        {toasts.map((t) => (
+            <div {...toastRootProps}>
+                <button {...closeProps}></button>
+            </div>
+```
+
+`useToaster` manages the toast container; `useToast` drives per-toast lifecycle. See [Primitive](/docs/primitive/components/toast) for a component-based API.
+
+## Features
+
+- **Two-hook architecture**, `useToaster` owns container/region state, `useToast` drives per-toast lifecycle
+- **Imperative API**, global `toast` function with severity shortcuts (`success`, `info`, `warn`, `error`, `secondary`, `contrast`) and `update`, `dismiss`, `promise` methods
+- **Swipe-to-dismiss**, directional gesture detection with `data-*` lifecycle attributes
+- **Auto-timeout with pause**, timers pause on hover, focus, and when the document is hidden; per-toast `duration` overrides the container `timeout`
+- **Stacking and expansion**, stacked layout with expand-on-hover, configurable visible `limit`, and positional placement
+- **Grouping**, route toasts to specific containers via matching `group` keys
+
+## Working with toasts
+
+### Creating toasts
+
+Pass `severity` directly or use the shortcut method. Each call returns an id you can use later to update or dismiss.
+
+```tsx
+import { toast } from '@primereact/headless/toaster';
+
+const id = toast({ title: 'Update available', description: 'A new version is ready.' });
+
+toast.success({ title: 'Saved' });
+toast.error({ title: 'Error', description: 'Something went wrong.' });
+```
+
+### Promise lifecycle
+
+`toast.promise` ties a single toast to a promise, loading state during the await, then success/error based on the outcome.
+
+```tsx
+toast.promise(fetchData(), {
+    loading: { title: 'Loading…' },
+    success: (data) => ({ title: 'Done', description: `Fetched ${data.length} items.` }),
+    error: (err) => ({ title: 'Failed', description: err.message })
+});
+```
+
+### Updating toasts
+
+`toast.update(id, options)` merges new options into an existing toast, typically used to turn a loading toast into a result.
+
+```tsx
+const id = toast({ loading: true, title: 'Uploading…' });
+
+await upload();
+
+toast.update(id, { loading: false, severity: 'success', title: 'Complete' });
+```
+
+### Custom JSX
+
+Pass a React element to `render` to override the default body. The root wrapper (positioning, animation, swipe) is preserved.
+
+```tsx
+const id = toast({
+    render: (
+        <div>
+            <span>Custom content</span>
+            <button onClick={() => toast.dismiss(id)}>Close</button>
+        </div>
+    )
+});
+```
+
+### Sticky and grouped toasts
+
+Pass `duration: Infinity` to keep a toast until dismissed manually. Use `group` on both the toaster and the call to route toasts to a specific container.
+
+```tsx
+const toaster = useToaster({ group: 'notifications' });
+
+toast({ title: 'Sticky', duration: Infinity, group: 'notifications' });
+```
+
+### Callbacks
+
+```tsx
+toast({
+    title: 'Notification',
+    onDismiss: (t) => console.log('dismissed', t.id),
+    onTimeout: (t) => console.log('timed out', t.id)
+});
+```
+
+### Per-toast state
+
+`useToast` exposes a `state` object useful for custom animations or conditional rendering.
+
+```tsx
+const { state } = useToast({ toast: toastData, toaster });
+// state.mounted, state.removed, state.swiping, state.swipeOut,
+// state.swipeOutDirection, state.isSwiped, state.initialHeight
+```
+
+## Styling with data attributes
+
+`rootProps` from both hooks expose state through `data-*` attributes.
+
+| Scope     | Element | Attributes                                                                                                             |
+| --------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `toaster` | region  | `data-position`, `data-expanded`                                                                                       |
+| `toast`   | root    | `data-mounted`, `data-removed`, `data-visible`, `data-front`, `data-swiping`, `data-swipe-out`, `data-swipe-direction` |
+
+```css
+[data-position='bottom-right'] {
+    right: 2rem;
+    bottom: 2rem;
+}
+
+[data-mounted] {
+    opacity: 1;
+}
+[data-removed] {
+    opacity: 0;
+}
+[data-swiping] {
+    transition: none;
+}
+[data-swipe-out][data-swipe-direction='left'] {
+    transform: translateX(-100%);
+}
+```
+
+## API
+
+### useToaster
+
+<DocTable name="useToaster" category="api" />
+
+### useToast
+
+<DocTable name="useToast" category="api" />
+
+## Accessibility
+
+Focus moves into the toast when it contains action buttons, and Escape dismisses when focused. See [Primitive](/docs/primitive/components/toast#accessibility) for full WAI-ARIA compliance details.

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

@@ -0,0 +1,357 @@
+[
+  {
+    "name": "useToggleButton",
+    "source": "apps/showcase/assets/apidoc/usetogglebutton.json",
+    "data": {
+      "description": "The useToggleButton manages the state and functionality of a ToggleButton component.",
+      "interfaces": {
+        "UseToggleButtonChangeEvent": {
+          "description": "Event fired when the ToggleButton's checked state changes.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "originalEvent",
+              "type": "E",
+              "default": "",
+              "description": "The original event that triggered the change."
+            },
+            {
+              "name": "pressed",
+              "type": "boolean",
+              "default": "",
+              "description": "The pressed state of the ToggleButton."
+            }
+          ],
+          "methods": []
+        },
+        "UseToggleButtonProps": {
+          "description": "Defines valid properties in useToggleButton.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "pressed",
+              "type": "boolean",
+              "default": "",
+              "description": "When present, it specifies that the ToggleButton should be pressed."
+            },
+            {
+              "name": "defaultPressed",
+              "type": "boolean",
+              "default": "",
+              "description": "The default pressed value when not controlled by  `pressed`  and  `onPressedChange` ."
+            },
+            {
+              "name": "disabled",
+              "type": "boolean",
+              "default": "false",
+              "description": "When present, it specifies that the element should be disabled."
+            },
+            {
+              "name": "invalid",
+              "type": "boolean",
+              "default": "false",
+              "description": "When present, it specifies that the component should have invalid state style."
+            },
+            {
+              "name": "onPressedChange",
+              "type": "(event: UseToggleButtonChangeEvent) => void",
+              "default": "",
+              "description": "Callback fired when the ToggleButton's pressed state changes."
+            }
+          ],
+          "methods": []
+        },
+        "UseToggleButtonState": {
+          "description": "Defines valid state in useToggleButton.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "pressed",
+              "type": "boolean",
+              "default": "",
+              "description": "The pressed state of the useToggleButton."
+            }
+          ],
+          "methods": []
+        },
+        "UseToggleButtonIndicatorProps": {
+          "description": "Pre-built props for the toggle button indicator element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "data-pressed",
+              "type": "\"\"",
+              "default": "",
+              "description": "Data attribute when pressed."
+            },
+            {
+              "name": "data-disabled",
+              "type": "\"\"",
+              "default": "",
+              "description": "Data attribute when disabled."
+            },
+            {
+              "name": "data-invalid",
+              "type": "\"\"",
+              "default": "",
+              "description": "Data attribute when invalid."
+            }
+          ],
+          "methods": []
+        },
+        "UseToggleButtonRootProps": {
+          "description": "Pre-built props for the toggle button root element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "disabled",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether the button is disabled."
+            },
+            {
+              "name": "aria-pressed",
+              "type": "boolean",
+              "default": "",
+              "description": "ARIA pressed state."
+            },
+            {
+              "name": "aria-disabled",
+              "type": "boolean",
+              "default": "",
+              "description": "ARIA disabled state."
+            },
+            {
+              "name": "data-pressed",
+              "type": "\"\"",
+              "default": "",
+              "description": "Data attribute when pressed."
+            },
+            {
+              "name": "data-disabled",
+              "type": "\"\"",
+              "default": "",
+              "description": "Data attribute when disabled."
+            },
+            {
+              "name": "data-invalid",
+              "type": "\"\"",
+              "default": "",
+              "description": "Data attribute when invalid."
+            },
+            {
+              "name": "onClick",
+              "type": "(event: SyntheticEvent) => void",
+              "default": "",
+              "description": "Click handler."
+            }
+          ],
+          "methods": []
+        },
+        "UseToggleButtonExposes": {
+          "description": "Defines the methods and properties exposed by useToggleButton.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "state",
+              "type": "UseToggleButtonState",
+              "default": "",
+              "description": "The state of the useToggleButton."
+            },
+            {
+              "name": "onChange",
+              "type": "(event: UseToggleButtonChangeEvent) => void",
+              "default": "",
+              "description": "Callback fired when the useToggleButton's pressed state changes."
+            },
+            {
+              "name": "getRootProps",
+              "type": "(disabled: boolean, invalid: boolean) => UseToggleButtonRootProps",
+              "default": "",
+              "description": "Returns pre-built props for the root element."
+            },
+            {
+              "name": "getIndicatorProps",
+              "type": "(disabled: boolean, invalid: boolean) => UseToggleButtonIndicatorProps",
+              "default": "",
+              "description": "Returns pre-built props for the indicator element."
+            }
+          ],
+          "methods": []
+        }
+      },
+      "types": {
+        "UseToggleButtonInstance": {
+          "description": "Instance of useToggleButton headless.",
+          "values": "HeadlessInstance<UseToggleButtonProps, UseToggleButtonState, UseToggleButtonExposes>"
+        }
+      },
+      "variables": {}
+    }
+  },
+  {
+    "name": "useToggleButtonGroup",
+    "source": "apps/showcase/assets/apidoc/usetogglebuttongroup.json",
+    "data": {
+      "description": "The useToggleButtonGroup manages the state and functionality of a ToggleButtonGroup component.",
+      "interfaces": {
+        "UseToggleButtonGroupChangeEvent": {
+          "description": "Event fired when the ToggleButtonGroup's checked state changes.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "originalEvent",
+              "type": "E",
+              "default": "",
+              "description": "The original event that triggered the change."
+            },
+            {
+              "name": "value",
+              "type": "unknown",
+              "default": "",
+              "description": "The value of the ToggleButtonGroup."
+            }
+          ],
+          "methods": []
+        },
+        "UseToggleButtonGroupProps": {
+          "description": "Defines valid properties in useToggleButton.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "value",
+              "type": "unknown",
+              "default": "",
+              "description": "Value of the ToggleButtonGroup."
+            },
+            {
+              "name": "defaultValue",
+              "type": "unknown",
+              "default": "",
+              "description": "The default value of the ToggleButtonGroup."
+            },
+            {
+              "name": "onValueChange",
+              "type": "(event: UseToggleButtonGroupChangeEvent) => void",
+              "default": "",
+              "description": "Callback fired when the ToggleButtonGroup's value state changes."
+            },
+            {
+              "name": "multiple",
+              "type": "boolean",
+              "default": "false",
+              "description": "When present, it specifies that the ToggleButton group allows multiple selections."
+            },
+            {
+              "name": "allowEmpty",
+              "type": "boolean",
+              "default": "true",
+              "description": "When present, it specifies that the ToggleButton group allows empty selection."
+            },
+            {
+              "name": "disabled",
+              "type": "boolean",
+              "default": "false",
+              "description": "When present, it specifies that the ToggleButton group is disabled."
+            },
+            {
+              "name": "invalid",
+              "type": "boolean",
+              "default": "false",
+              "description": "When present, it specifies that the ToggleButton group value is invalid."
+            }
+          ],
+          "methods": []
+        },
+        "UseToggleButtonGroupState": {
+          "description": "Defines valid state in useToggleButtonGroup.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "value",
+              "type": "unknown",
+              "default": "",
+              "description": "The value state of the useToggleButtonGroup."
+            }
+          ],
+          "methods": []
+        },
+        "UseToggleButtonGroupRootProps": {
+          "description": "Pre-built props for the toggle button group root element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "role",
+              "type": "\"group\"",
+              "default": "",
+              "description": "ARIA role."
+            },
+            {
+              "name": "data-disabled",
+              "type": "\"\"",
+              "default": "",
+              "description": "Data attribute when disabled."
+            },
+            {
+              "name": "data-invalid",
+              "type": "\"\"",
+              "default": "",
+              "description": "Data attribute when invalid."
+            },
+            {
+              "name": "data-multiple",
+              "type": "\"\"",
+              "default": "",
+              "description": "Data attribute when multiple selection is enabled."
+            },
+            {
+              "name": "data-allow-empty",
+              "type": "\"\"",
+              "default": "",
+              "description": "Data attribute when empty selection is allowed."
+            }
+          ],
+          "methods": []
+        },
+        "UseToggleButtonGroupExposes": {
+          "description": "Defines the methods and properties exposed by useToggleButton.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "state",
+              "type": "UseToggleButtonGroupState",
+              "default": "",
+              "description": "The state of the useToggleButtonGroup."
+            },
+            {
+              "name": "rootProps",
+              "type": "UseToggleButtonGroupRootProps",
+              "default": "",
+              "description": "Pre-built props for the root element."
+            },
+            {
+              "name": "updateChange",
+              "type": "(event: UseToggleButtonGroupChangeEvent<SyntheticEvent<Element, Event>> & { pressed: boolean }) => void",
+              "default": "",
+              "description": "Updates the value of the checkbox group."
+            },
+            {
+              "name": "isPressed",
+              "type": "(value: unknown, toggleButtonValue: unknown) => boolean",
+              "default": "",
+              "description": "Checks if a toggle button is pressed.\nReturns true if the toggle button is pressed, false if not pressed, or undefined if the value is undefined."
+            }
+          ],
+          "methods": []
+        }
+      },
+      "types": {
+        "UseToggleButtonGroupInstance": {
+          "description": "Instance of useToggleButtonGroup headless.",
+          "values": "HeadlessInstance<UseToggleButtonGroupProps, UseToggleButtonGroupState, UseToggleButtonGroupExposes>"
+        }
+      },
+      "variables": {}
+    }
+  }
+]