@g4rcez/components 3.0.0 → 3.0.1

package/dist/ai/docs/Menu.md

@@ -0,0 +1,166 @@
+---
+title: Menu
+description: Accessible floating menu system with nested submenus, keyboard navigation, hover support, and typeahead.
+package: "@g4rcez/components"
+export: "{ Menu, MenuItem }"
+import: "import { Menu, MenuItem } from '@g4rcez/components/menu'"
+category: floating
+---
+
+# Menu
+
+Accessible floating menu system with nested submenus, keyboard navigation, hover support, and typeahead.
+
+## Import
+
+```tsx
+import { Menu, MenuItem } from "@g4rcez/components/menu";
+```
+
+## Props
+
+### Menu
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string \| React.ReactElement` | — | Trigger content |
+| `title` | `string` | — | Required for accessibility when `label` is an element; also used for typeahead |
+| `hover` | `boolean` | `true` | Open on hover in addition to click |
+| `open` | `boolean` | `false` | Initial open state |
+| `asChild` | `boolean` | `false` | Use the `Slot` pattern — merge props onto the child element instead of wrapping in a `<button>` |
+| `restoreFocus` | `boolean` | `false` | Restore focus to the trigger after the menu closes |
+| `floatingClassName` | `string` | — | Additional CSS classes for the floating list container |
+| `FloatingComponent` | `React.ElementType` | `"div"` | Element type for the floating container |
+
+### MenuItem
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | — | Item text; used for typeahead matching and the `title` attribute |
+| `children` | `React.ReactNode` | — | Visual content of the item |
+| `disabled` | `boolean` | `false` | Removes item from keyboard navigation and typeahead |
+| `Right` | `React.FC<LucideProps>` | — | Icon rendered on the right side |
+| `onClick` | `function` | — | Click handler |
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token | CSS Variable | Purpose |
+|-------|-------------|---------|
+| `bg-floating-background` | `--floating-background` | Menu list surface background |
+| `border-floating-border` | `--floating-border` | Menu list border |
+| `shadow-shadow-floating` | `--shadow-floating` | Menu list drop shadow |
+| `z-tooltip` | `--z-tooltip` | Z-index of the floating list |
+| `bg-primary` | `--primary` | Active/focused item background |
+| `text-primary-foreground` | `--primary-foreground` | Active/focused item text |
+
+## Examples
+
+### Basic Menu
+
+```tsx
+import { Menu, MenuItem } from "@g4rcez/components/menu";
+
+<Menu label="Actions">
+  <MenuItem title="Edit">Edit Profile</MenuItem>
+  <MenuItem title="Share">Share Profile</MenuItem>
+</Menu>
+```
+
+### With Icons and Shortcuts
+
+```tsx
+import { EditIcon, TrashIcon } from "lucide-react";
+import { Menu, MenuItem } from "@g4rcez/components/menu";
+
+<Menu label="Settings">
+  <MenuItem title="Edit" Right={EditIcon}>Edit</MenuItem>
+  <MenuItem title="Delete" Right={TrashIcon} className="text-danger">
+    Delete
+  </MenuItem>
+</Menu>
+```
+
+### Nested Submenus
+
+```tsx
+import { Menu, MenuItem } from "@g4rcez/components/menu";
+
+<Menu label="Actions">
+  <MenuItem title="Edit">Edit Profile</MenuItem>
+  <MenuItem title="Share">Share Profile</MenuItem>
+  <Menu label="More Options" title="More Options">
+    <MenuItem title="Archive">Archive Account</MenuItem>
+    <MenuItem title="Delete" className="text-danger">
+      Delete Account
+    </MenuItem>
+  </Menu>
+</Menu>
+```
+
+### Using asChild for Custom Triggers
+
+```tsx
+import { Menu, MenuItem } from "@g4rcez/components/menu";
+import { Button } from "@g4rcez/components/button";
+
+<Menu
+  label={<Button theme="primary">Main Action</Button>}
+  asChild
+  title="Main Action"
+>
+  <MenuItem title="Save">Save Version</MenuItem>
+  <MenuItem title="Publish">Publish Now</MenuItem>
+</Menu>
+```
+
+### Disabled Items
+
+```tsx
+import { Menu, MenuItem } from "@g4rcez/components/menu";
+
+<Menu label="Options">
+  <MenuItem title="Export">Export Data</MenuItem>
+  <MenuItem title="Import" disabled>Import (unavailable)</MenuItem>
+  <MenuItem title="Delete" className="text-danger">Delete</MenuItem>
+</Menu>
+```
+
+## Do
+
+- Provide a `title` string whenever `label` is a React element — it enables typeahead and improves accessibility.
+- Use nested `Menu` components (not just `MenuItem`) for logical groupings of secondary actions.
+- Use `disabled` for actions temporarily unavailable, so users know the option exists.
+- Use design-token classes (`text-danger`, `text-foreground`) for item text colors.
+
+## Don't
+
+- Don't make menus deeper than 2–3 levels — deeply nested submenus are hard to navigate.
+- Don't use raw Tailwind color classes (`text-red-600`, `hover:bg-gray-100`) on items — use design-token classes.
+- Don't use arbitrary Tailwind values (`bg-[#abc]`) — override CSS variables in your `@theme` block.
+- Don't use `Menu` for primary navigation that should be crawlable — use standard `<a>` links instead.
+
+## Accessibility
+
+- Full keyboard navigation: arrow keys navigate items, `Enter`/`Space` select, `Escape` closes.
+- Typeahead: typing the first characters of an item's `title` focuses it instantly (resets after inactivity).
+- Correct ARIA roles: `menu` on the container, `menuitem` on each item, `aria-expanded` on nested triggers.
+- `data-active` marks the currently focused item for CSS styling.
+- `FloatingFocusManager` handles focus trapping and restoration.
+
+## Data Attributes
+
+| Attribute | Applied to | Description |
+|-----------|-----------|-------------|
+| `data-open` | Menu trigger, MenuItem | Present when the menu/item is open |
+| `data-nested` | Nested menu trigger | Present on triggers that open a submenu |
+| `data-focus-inside` | Menu trigger | Present when focus is inside an open submenu |
+| `data-active` | MenuItem | Present on the currently focused item |
+
+## Notes
+
+- The root `Menu` wraps itself in a `FloatingTree`; nested `Menu` components detect this via `useFloatingParentNodeId` and behave as submenus.
+- Hover delay is controlled by the `FLOATING_DELAY` constant. The safe-polygon handler keeps the menu open while the pointer moves toward the submenu.
+- When `hover` is `false`, the menu opens only on click.
+- The floating container default `max-h-80` prevents the list from growing taller than the viewport.

package/dist/ai/docs/Modal.md

@@ -0,0 +1,280 @@
+---
+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

@@ -0,0 +1,196 @@
+---
+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 "lucide-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.