@g4rcez/components 4.0.1 → 4.1.1

package/dist/ai/docs/Modal.md

@@ -1,280 +0,0 @@
----
-title: Modal
-description: Animated modal with dialog, drawer, and sheet variants; includes drag-to-resize and a programmatic confirm utility.
-package: "@g4rcez/components"
-export: "{ Modal, ModalConfirmProvider, useConfirm }"
-import: "import { Modal } from '@g4rcez/components/modal'"
-category: floating
----
-
-# Modal
-
-Animated modal with dialog, drawer, and sheet variants; includes drag-to-resize and a programmatic confirm utility.
-
-## Import
-
-```tsx
-import { Modal, ModalConfirmProvider, useConfirm } from "@g4rcez/components/modal";
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `open` | `boolean` | — | Controls modal visibility |
-| `onChange` | `(nextState: boolean) => void` | — | Callback when modal state changes |
-| `title` | `React.ReactNode` | — | Modal title; creates a `<h2>` header |
-| `ariaTitle` | `string` | — | ARIA label used when no visible `title` is provided |
-| `footer` | `React.ReactNode` | — | Footer content |
-| `type` | `"dialog" \| "drawer" \| "sheet"` | `"dialog"` | Modal display variant |
-| `position` | `"left" \| "right"` | `"right"` | Drawer slide-in side (drawer type only) |
-| `animated` | `boolean` | `true` | Enable enter/exit animations |
-| `closable` | `boolean` | `true` | Show the close button |
-| `resizer` | `boolean` | `true` | Show the drag-to-resize handle (drawer and sheet) |
-| `forceType` | `boolean` | `false` | Disable responsive behavior — keep `type` on all screen sizes |
-| `overlayClickClose` | `boolean` | `false` | Close when clicking the backdrop |
-| `trigger` | `React.ReactNode \| React.FC` | — | Element that toggles the modal when clicked |
-| `asChild` | `boolean` | `false` | Merge trigger props onto the child element via `Slot` |
-| `className` | `string` | — | Additional classes for the modal surface |
-| `bodyClassName` | `string` | — | Additional classes for the scrollable body |
-| `overlayClassName` | `string` | — | Additional classes for the backdrop overlay |
-| `layoutId` | `string` | — | Framer Motion layout ID for shared-element transitions |
-| `role` | `"dialog"` | `"dialog"` | ARIA role |
-| `interactions` | `ElementProps[]` | `[]` | Extra Floating UI interaction hooks |
-
-## Modal Types
-
-| Type | Behavior | Best for |
-|------|----------|---------|
-| `dialog` | Centered overlay with backdrop | Confirmations, forms |
-| `drawer` | Slides in from left or right; full height | Navigation, detail panels |
-| `sheet` | Slides up from bottom; full width | Mobile action sheets |
-
-On mobile (`< 64 rem`) drawers automatically become sheets unless `forceType` is set.
-
-## Design Tokens
-
-Tokens this component reads. Customize by overriding these CSS variables in your theme.
-
-| Token | CSS Variable | Purpose |
-|-------|-------------|---------|
-| `bg-floating-background` | `--floating-background` | Modal surface background |
-| `border-floating-border` | `--floating-border` | Modal border, header/footer dividers, resizer |
-| `bg-floating-overlay` | `--floating-overlay` | Backdrop color (with `/70` opacity) |
-| `z-overlay` | `--z-overlay` | Z-index of the backdrop |
-| `z-floating` | `--z-floating` | Z-index of the modal surface and close button |
-| `w-dialog` | `--dialog` | Default max-width for dialog type (`max-w-dialog`) |
-| `text-foreground` | `--foreground` | Body text color |
-| `text-danger` | `--danger` | Close button hover color |
-
-## Examples
-
-### Basic Dialog
-
-```tsx
-import { useState } from "react";
-import { Modal } from "@g4rcez/components/modal";
-import { Button } from "@g4rcez/components/button";
-
-function BasicDialog() {
-  const [open, setOpen] = useState(false);
-
-  return (
-    <>
-      <Button onClick={() => setOpen(true)}>Open Dialog</Button>
-
-      <Modal open={open} onChange={setOpen} title="Confirm Action">
-        <p className="text-foreground">Are you sure you want to proceed?</p>
-        <div className="flex gap-2 mt-4">
-          <Button theme="ghost-muted" onClick={() => setOpen(false)}>
-            Cancel
-          </Button>
-          <Button theme="danger" onClick={() => setOpen(false)}>
-            Confirm
-          </Button>
-        </div>
-      </Modal>
-    </>
-  );
-}
-```
-
-### Modal with Footer
-
-```tsx
-<Modal
-  open={open}
-  onChange={setOpen}
-  title="User Profile"
-  footer={
-    <div className="flex justify-end gap-2">
-      <Button theme="ghost-muted" onClick={() => setOpen(false)}>
-        Cancel
-      </Button>
-      <Button theme="primary">Save Changes</Button>
-    </div>
-  }
->
-  <form className="space-y-4">
-    <div>
-      <label className="text-sm font-medium text-foreground">Name</label>
-      <input type="text" className="w-full p-2 rounded-button border border-border bg-background text-foreground" />
-    </div>
-  </form>
-</Modal>
-```
-
-### Drawer
-
-```tsx
-<Modal
-  open={open}
-  onChange={setOpen}
-  type="drawer"
-  position="right"
-  title="Navigation"
->
-  <nav className="space-y-2">
-    <a href="/dashboard" className="block rounded-button p-2 text-foreground hover:bg-muted">
-      Dashboard
-    </a>
-    <a href="/profile" className="block rounded-button p-2 text-foreground hover:bg-muted">
-      Profile
-    </a>
-    <a href="/settings" className="block rounded-button p-2 text-foreground hover:bg-muted">
-      Settings
-    </a>
-  </nav>
-</Modal>
-```
-
-### Sheet
-
-```tsx
-<Modal open={open} onChange={setOpen} type="sheet" title="Quick Actions">
-  <div className="grid grid-cols-2 gap-4">
-    <Button theme="ghost-neutral" className="flex-col h-24">
-      Analytics
-    </Button>
-    <Button theme="ghost-neutral" className="flex-col h-24">
-      Revenue
-    </Button>
-  </div>
-</Modal>
-```
-
-### Modal with Built-in Trigger
-
-```tsx
-<Modal
-  open={open}
-  onChange={setOpen}
-  title="Settings"
-  trigger={<Button theme="primary">Open Settings</Button>}
->
-  <p className="text-foreground">Settings content here.</p>
-</Modal>
-```
-
-### Non-closable Processing Modal
-
-```tsx
-<Modal open={open} onChange={setOpen} title="Processing..." closable={false}>
-  <div className="text-center text-foreground">
-    <div className="animate-spin w-8 h-8 border-4 border-primary border-t-transparent rounded-full mx-auto mb-4" />
-    <p>Please wait while we process your request.</p>
-  </div>
-</Modal>
-```
-
-### Programmatic Confirm Dialog
-
-Wrap your app with `ModalConfirmProvider` once:
-
-```tsx
-import { ModalConfirmProvider } from "@g4rcez/components/modal";
-
-export default function App({ children }) {
-  return <ModalConfirmProvider>{children}</ModalConfirmProvider>;
-}
-```
-
-Then call `Modal.confirm` anywhere:
-
-```tsx
-import { Modal } from "@g4rcez/components/modal";
-
-async function handleDelete() {
-  const confirmed = await Modal.confirm({
-    title: "Delete item",
-    description: "This action cannot be undone.",
-    confirm: { text: "Delete", theme: "danger" },
-    cancel: { text: "Cancel" },
-  });
-
-  if (confirmed) {
-    // proceed with deletion
-  }
-}
-```
-
-Or use the `useConfirm` hook inside a `ModalConfirmProvider` subtree:
-
-```tsx
-import { useConfirm } from "@g4rcez/components/modal";
-
-function DeleteButton() {
-  const confirm = useConfirm();
-
-  const handleClick = async () => {
-    const ok = await confirm({
-      title: "Delete item",
-      description: "Are you sure?",
-    });
-    if (ok) {
-      // delete
-    }
-  };
-
-  return <Button theme="danger" onClick={handleClick}>Delete</Button>;
-}
-```
-
-## Do
-
-- Choose the correct `type` (`dialog`, `drawer`, `sheet`) for the content and context.
-- Use `<Modal type="dialog" />` as the default — only switch to `drawer` or `sheet` when layout demands it.
-- Always provide either `title` or `ariaTitle` so screen readers can announce the modal.
-- Use `footer` for action buttons to keep them separated from body content.
-
-## Don't
-
-- Don't pass custom `z-*`, `rounded-*`, or `p-*` overrides directly — use `type` to control layout variants.
-- Don't use raw Tailwind color classes (`bg-blue-500`, `text-white`, `bg-gray-100`) — use design-token classes.
-- Don't use arbitrary Tailwind values (`bg-[#abc]`, `z-[9999]`) — override CSS variables in your `@theme` block.
-- Don't use `color-mix()` in `className` or `style` props.
-- Don't nest modals inside each other — it creates broken focus and z-index behavior.
-- Don't hide a modal's only close affordance (`closable={false}`) without providing another way to close.
-
-## Accessibility
-
-- Focus is automatically trapped inside the modal via `FloatingFocusManager` with `guards` and `modal`.
-- `Escape` closes the modal (via `useDismiss` with `escapeKey: true`).
-- The modal surface receives `aria-labelledby` (when `title` is set) or `aria-label` (when `ariaTitle` is set).
-- `aria-modal="true"` is applied to the floating surface.
-- Scroll is locked on the body while the modal is open.
-
-## Data Attributes
-
-| Attribute | Applied to | Description |
-|-----------|-----------|-------------|
-| `data-component="modal"` | Modal surface `<div>` | Identifies the modal root |
-| `data-component="modal-body"` | Scrollable body `<section>` | Identifies the content area |
-
-## Notes
-
-- Drawers auto-switch to sheets on viewports narrower than `64rem` unless `forceType={true}`.
-- `resizer` adds a draggable handle: horizontal for drawers, vertical for sheets. Dragging a sheet past 60 % of screen height closes it.
-- `layoutId` enables Framer Motion shared-element transitions between a trigger and the modal surface.
-- `ModalConfirmProvider` sets a module-level `confirmGlobal` function so `Modal.confirm` works outside React trees (e.g., in event handlers).
-- The confirm dialog uses `max-w-dialog` (`w-dialog` token, default `20rem`) and cannot be closed by clicking the overlay.

package/dist/ai/docs/MultiSelect.md

@@ -1,196 +0,0 @@
----
-title: MultiSelect
-description: Dropdown that lets users select multiple options with fuzzy search and tag display.
-package: "@g4rcez/components"
-export: "{ MultiSelect }"
-import: "import { MultiSelect } from '@g4rcez/components'"
-category: form
----
-
-# MultiSelect
-
-Dropdown that lets users select multiple options with fuzzy search and tag display.
-
-## Import
-
-```tsx
-import { MultiSelect } from "@g4rcez/components";
-```
-
-## Props
-
-The `MultiSelect` component inherits all props from `InputField`, plus:
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `options` | `MultiSelectItemProps[]` | — | Array of `{ value, label, Render? }` option objects. |
-| `value` | `string[]` | — | Controlled selected values. |
-| `defaultValue` | `string[]` | `[]` | Initial selected values for uncontrolled usage. |
-| `onChangeOptions` | `(options: string[]) => void` | — | Called when the selection changes. |
-| `dynamicOption` | `boolean` | `false` | Allows users to select their search query as a new option. |
-| `emptyMessage` | `Label` | — | Message shown when no options match the search. |
-| `selectedLabel` | `string` | — | Text shown in the overflow counter (e.g., "selected"). |
-
-### MultiSelectItemProps
-
-Extends `OptionProps` with an optional custom renderer:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `value` | `string` | Option value. |
-| `label` | `string` | Option display text. |
-| `Render` | `React.FC<OptionProps>` | Custom render component for the dropdown row. |
-| `hidden` | `boolean` | Hides the option from the list. |
-
-## Design Tokens
-
-Tokens this component reads. Customize by overriding these CSS variables in your theme.
-
-| Token | CSS Variable | Purpose |
-|-------|-------------|---------|
-| `placeholder-input-mask` | `--input-mask` | Placeholder text color |
-| `placeholder-input-mask-error` | `--input-mask-error` | Placeholder color in error state |
-| `border-input-border` | `--input-border` | Search input bottom border in dropdown |
-| `bg-floating-background` | `--floating-background` | Dropdown panel background |
-| `border-floating-border` | `--floating-border` | Dropdown panel border |
-| `bg-floating-hover` | `--floating-hover` | Option row hover/active background |
-| `text-foreground` | `--foreground` | Option text color |
-| `text-input-placeholder` | `--input-placeholder` | Placeholder li color |
-| `text-disabled` | `--disabled` | Empty-state text color |
-| `focus:ring-primary` | `--primary` | Keyboard focus ring |
-| `h-input-height` | `--input-height` | Trigger element height (2.5 rem) |
-| `px-input-x` | `--input-x` | Horizontal padding |
-| `py-input-y` | `--input-y` | Vertical padding |
-
-## Examples
-
-### Basic usage
-
-```tsx
-import { MultiSelect } from "@g4rcez/components";
-
-const options = [
-  { value: "react", label: "React" },
-  { value: "vue", label: "Vue" },
-  { value: "angular", label: "Angular" },
-];
-
-export default function FrameworkPicker() {
-  return (
-    <MultiSelect
-      title="Frameworks"
-      options={options}
-      onChangeOptions={(values) => console.log(values)}
-    />
-  );
-}
-```
-
-### Controlled selection
-
-```tsx
-import { useState } from "react";
-import { MultiSelect } from "@g4rcez/components";
-
-export default function ControlledMultiSelect() {
-  const [selected, setSelected] = useState<string[]>(["react"]);
-
-  return (
-    <MultiSelect
-      title="Frameworks"
-      options={[
-        { value: "react", label: "React" },
-        { value: "vue", label: "Vue" },
-        { value: "angular", label: "Angular" },
-      ]}
-      value={selected}
-      onChangeOptions={setSelected}
-    />
-  );
-}
-```
-
-### Custom option rendering
-
-```tsx
-import { ShieldIcon } from "@phosphor-icons/react";
-import { MultiSelect } from "@g4rcez/components";
-
-const roleOptions = roles.map((r) => ({
-  value: r.id,
-  label: r.name,
-  Render: () => (
-    <span className="flex items-center gap-base">
-      <ShieldIcon size={14} className="text-primary" />
-      {r.name}
-    </span>
-  ),
-}));
-
-export default function RolePicker() {
-  return (
-    <MultiSelect
-      title="Roles"
-      options={roleOptions}
-      onChangeOptions={(ids) => console.log(ids)}
-    />
-  );
-}
-```
-
-### Dynamic option creation
-
-```tsx
-import { MultiSelect } from "@g4rcez/components";
-
-export default function TagInput() {
-  return (
-    <MultiSelect
-      title="Tags"
-      dynamicOption
-      options={existingTags}
-      onChangeOptions={(tags) => console.log(tags)}
-    />
-  );
-}
-```
-
-## Do
-
-- Provide a descriptive `title` to label the trigger.
-- Use `dynamicOption` when users may need to add items not in the predefined list.
-- Use design-token classes for any wrapper elements (`bg-background`, `border-border`, `text-foreground`).
-- Use `theme="<value>"` on nested elements — never hardcode colors in `className`.
-
-## Don't
-
-- Don't use `MultiSelect` when only a single selection is needed — use `Select` or `Autocomplete` instead.
-- Don't pass raw Tailwind color classes (`bg-blue-500`, `text-white`) — use theme props or design tokens instead.
-- Don't use arbitrary Tailwind values (`bg-[#abc]`, `bg-[--my-var]`) — override CSS variables in your `@theme` block instead.
-- Don't use `color-mix()` in className or style props for theming.
-
-## Accessibility
-
-- The trigger uses `aria-autocomplete="list"` and `role="button"`.
-- The dropdown list uses `role="listbox"` with individual items carrying `role="option"`, `aria-selected`, `aria-checked`, and `aria-current`.
-- `FloatingFocusManager` traps focus inside the open dropdown.
-- Arrow keys navigate the virtual list; Escape closes it; Enter selects the focused item.
-
-## Data Attributes
-
-| Attribute | Element | Value | Description |
-|-----------|---------|-------|-------------|
-| `data-component` | trigger `ul` | `"autocomplete"` | Identifies the component type. |
-| `data-shadow` | trigger `ul` | `"true"` | Marks the visual shadow trigger. |
-| `data-value` | trigger `ul` | JSON string | Currently selected values as a JSON array. |
-| `data-floating` | dropdown root | `"true"` | Marks the floating panel. |
-| `data-dynamic` | option button | `"true"` | Marks options injected via `dynamicOption`. |
-| `data-error` | trigger `ul` | boolean string | Reflects the error state. |
-
-## Notes
-
-- Uses `react-virtuoso` for virtualized rendering — large option lists perform well.
-- The overflow control collapses selected tags into a counter badge when they exceed the trigger width.
-- The hidden `<input type="hidden">` stores the comma-separated selected values for native form submission.
-- Floating position is computed with `@floating-ui/react` and updates automatically while open (`autoUpdate`).
-- The dropdown search uses `fzf` (fuzzy matching) across both `value` and `label` fields.

package/dist/ai/docs/Notifications.md

@@ -1,231 +0,0 @@
----
-title: Notifications
-description: Toast notification system with themes, stacking, swipe-to-dismiss, and programmatic control.
-package: "@g4rcez/components"
-export: "{ Notifications }"
-import: "import { Notifications, useNotification } from '@g4rcez/components/notifications'"
-category: display
----
-
-# Notifications
-
-Toast notification system with themes, stacking, swipe-to-dismiss, and programmatic control.
-
-## Import
-
-```tsx
-import { Notifications, useNotification } from "@g4rcez/components/notifications";
-```
-
-## Setup
-
-Wrap your app (or the subtree that needs toasts) with `Notifications`:
-
-```tsx
-import { Notifications } from "@g4rcez/components/notifications";
-
-function App() {
-  return (
-    <Notifications max={5} timeout={5000}>
-      <YourApp />
-    </Notifications>
-  );
-}
-```
-
-## Props
-
-### Notifications (Provider)
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `max` | `number` | `5` | Maximum notifications displayed at once |
-| `timeout` | `number` | `5000` | Default auto-dismiss duration in milliseconds |
-| `children` | `React.ReactNode` | — | Subtree that can use `useNotification` |
-
-### useNotification — notify function
-
-```tsx
-const notify = useNotification();
-const subscription = notify(message, options);
-```
-
-**Parameters**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `message` | `Label` | Notification body text (string or React node) |
-| `options` | `NotificationOptions` | Optional configuration (see below) |
-
-**NotificationOptions**
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `id` | `string` | — | Stable ID; if provided and a toast with this ID exists, it will be updated instead of duplicated |
-| `title` | `Label` | — | Optional notification title |
-| `theme` | `NotificationTheme` | `"default"` | Visual theme variant |
-| `timeout` | `number` | Provider default | Override auto-dismiss duration in ms |
-| `closable` | `boolean` | `true` | Show close button |
-| `loading` | `boolean` | `false` | Replaces icon with spinning `Loader2Icon` |
-
-**Return value — NotificationSubscriber**
-
-| Method | Description |
-|--------|-------------|
-| `close()` | Dismiss this specific notification |
-| `clear()` | Dismiss all visible notifications |
-
-## Themes
-
-| Value | Appearance |
-|-------|-----------|
-| `"default"` | Card background with foreground text |
-| `"info"` | `bg-alert-info-bg` / `text-alert-info-text` / `border-alert-info-border` |
-| `"success"` | `bg-alert-success-bg` / `text-alert-success-text` / `border-alert-success-border` |
-| `"warn"` | `bg-alert-warn-bg` / `text-alert-warn-text` / `border-alert-warn-border` |
-| `"danger"` | `bg-alert-danger-bg` / `text-alert-danger-text` / `border-alert-danger-border` |
-| `"secondary"` | `bg-alert-secondary-bg` / `text-alert-secondary-text` / `border-alert-secondary-border` |
-| `"muted"` | `bg-alert-muted-bg` / `text-alert-muted-text` / `border-alert-muted-border` |
-
-## Design Tokens
-
-Tokens this component reads. Customize by overriding these CSS variables in your theme.
-
-| Token | CSS Variable | Purpose |
-|-------|-------------|---------|
-| `bg-card-background` | `--card-background` | Default notification background |
-| `border-card-border` | `--card-border` | Default notification border |
-| `text-foreground` | `--foreground` | Default notification text |
-| `bg-alert-{theme}-bg` | `--alert-{theme}-bg` | Themed background |
-| `text-alert-{theme}-text` | `--alert-{theme}-text` | Themed text |
-| `border-alert-{theme}-border` | `--alert-{theme}-border` | Themed border |
-
-## Examples
-
-### Basic Notifications
-
-```tsx
-function NotificationExamples() {
-  const notify = useNotification();
-
-  return (
-    <div className="space-y-2">
-      <button onClick={() => notify("Default notification")}>Default</button>
-      <button onClick={() => notify("Info message", { theme: "info" })}>Info</button>
-      <button onClick={() => notify("Success!", { theme: "success" })}>Success</button>
-      <button onClick={() => notify("Warning", { theme: "warn" })}>Warning</button>
-      <button onClick={() => notify("Error occurred", { theme: "danger" })}>Error</button>
-    </div>
-  );
-}
-```
-
-### With Title
-
-```tsx
-function SaveButton() {
-  const notify = useNotification();
-
-  const handleSave = () => {
-    notify("Your changes have been saved to the server.", {
-      title: "Changes Saved",
-      theme: "success",
-      timeout: 3000,
-    });
-  };
-
-  return <button onClick={handleSave}>Save</button>;
-}
-```
-
-### Persistent Notification with Manual Close
-
-```tsx
-function ProcessButton() {
-  const notify = useNotification();
-
-  const startProcess = () => {
-    const subscription = notify("Processing your request…", {
-      title: "In Progress",
-      theme: "info",
-      timeout: Infinity,
-      closable: false,
-      loading: true,
-    });
-
-    doWork().then(() => {
-      subscription.close();
-      notify("Process completed successfully!", { theme: "success" });
-    });
-  };
-
-  return <button onClick={startProcess}>Start</button>;
-}
-```
-
-### Form Submission Feedback
-
-```tsx
-function ContactForm() {
-  const notify = useNotification();
-
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault();
-    try {
-      await submitForm();
-      notify("Message sent successfully.", { title: "Done", theme: "success" });
-    } catch {
-      notify("Failed to send. Please try again.", {
-        title: "Error",
-        theme: "danger",
-        timeout: 7000,
-      });
-    }
-  };
-
-  return <form onSubmit={handleSubmit}>{/* fields */}</form>;
-}
-```
-
-### Updating an Existing Toast
-
-```tsx
-const SYNC_ID = "data-sync";
-const notify = useNotification();
-
-// Show initial state
-notify("Syncing data…", { id: SYNC_ID, theme: "info", timeout: Infinity });
-
-// Update in-place when done
-notify("Sync complete.", { id: SYNC_ID, theme: "success", timeout: 3000 });
-```
-
-## Do
-
-- Use the correct `theme` to convey message severity (`success`, `danger`, `warn`).
-- Keep messages short — toasts are glanced at, not read.
-- Use `title` for important notifications that need extra prominence.
-- Set a longer `timeout` (or `Infinity`) for critical errors that need user attention.
-- Use `loading: true` for in-progress operations to signal activity.
-
-## Don't
-
-- Don't pass raw Tailwind color classes (`bg-blue-500`, `text-white`) — use `theme` instead.
-- Don't use arbitrary Tailwind values (`bg-[#abc]`) — override CSS variables in your `@theme` block.
-- Don't use notifications for information that must be acknowledged before proceeding — use a `Modal` instead.
-- Don't show more than 3–5 notifications at a time; configure `max` accordingly.
-- Don't use notifications for persistent status indicators — use `Alert` or a status bar.
-
-## Accessibility
-
-- Built on Base UI Toast which manages ARIA live regions for screen reader announcements.
-- Close buttons are keyboard accessible with visible focus states.
-- Swipe-to-dismiss works on touch devices via the Base UI primitive.
-- The viewport is positioned with `role` semantics handled by the underlying primitive.
-
-## Notes
-
-- Up to 3 notifications are visible by default; hovering the stack reveals all (up to `max`).
-- Animations use Framer Motion (`motion/react`) with spring physics for enter/exit.
-- The viewport is centered horizontally at the top of the viewport (`top-6`, `z-[100]`).
-- When `max` is exceeded, a pill showing `+N more` appears below the visible toasts.