@g4rcez/components 4.0.1 → 4.1.1

package/ai/docs/InputField.md

@@ -0,0 +1,170 @@
+---
+title: InputField
+description: Low-level field wrapper that provides a label, tooltip, error message, feedback text, and left/right slots for any form control.
+package: "@g4rcez/components"
+export: "{ InputField }"
+import: "import { InputField } from '@g4rcez/components'"
+category: form
+---
+
+# InputField
+
+Low-level field wrapper that provides a label, tooltip, error message, feedback text, and left/right slots for any form control. Most higher-level components (`Input`, `Select`, `Autocomplete`, `DatePicker`, `Textarea`) use `InputField` internally and forward its props automatically.
+
+## Import
+
+```tsx
+import { InputField } from "@g4rcez/components";
+```
+
+## Props
+
+| Prop             | Type              | Default      | Description                                                              |
+| ---------------- | ----------------- | ------------ | ------------------------------------------------------------------------ |
+| `title`          | `Label`           | -            | Main label text for the field                                            |
+| `info`           | `Label`           | -            | Informational text shown in a `Tooltip` icon next to the label           |
+| `error`          | `string`          | -            | Error message rendered below the field border                            |
+| `feedback`       | `Label`           | -            | Success or neutral feedback message (hidden when `error` is present)     |
+| `left`           | `Label`           | -            | Content rendered to the left inside the field border                     |
+| `right`          | `Label`           | -            | Content rendered to the right inside the field border                    |
+| `rightLabel`     | `Label`           | -            | Content rendered to the right of the label text                          |
+| `required`       | `boolean`         | `false`      | If `true`, hides the "Optional" badge                                    |
+| `optionalText`   | `string`          | `"Optional"` | Text shown for optional fields (translatable)                            |
+| `disabled`       | `boolean`         | `false`      | Applies disabled styling to the wrapper and label                        |
+| `interactive`    | `boolean`         | `false`      | Sets `data-interactive` on the fieldset                                  |
+| `container`      | `string`          | -            | Extra CSS classes for the outer `<fieldset>`                             |
+| `labelClassName` | `string`          | -            | Extra CSS classes for the inner label/border wrapper `<div>`             |
+| `hiddenLabel`    | `boolean`         | `false`      | Visually hides the label row while keeping it accessible                 |
+| `reportStatus`   | `boolean`         | -            | Show `CheckCircle`/`XCircle` icons alongside the label based on validity |
+| `componentName`  | `string`          | -            | Sets `data-component` on the fieldset (e.g., `"input"`, `"select"`)      |
+| `id`             | `string`          | -            | `id` linked to the inner control via `htmlFor` on the label              |
+| `name`           | `string`          | -            | Fallback for `id` when `id` is not provided                              |
+| `children`       | `React.ReactNode` | -            | The actual form control (input, select, etc.)                            |
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token                 | CSS Variable     | Purpose                                            |
+| --------------------- | ---------------- | -------------------------------------------------- |
+| `border-input-border` | `--input-border` | Default field border color                         |
+| `text-field-label`    | `--field-label`  | Label text color                                   |
+| `text-primary`        | `--primary`      | Label and border color on focus/hover              |
+| `text-danger`         | `--danger`       | Label, border, and error text color in error state |
+| `text-disabled`       | `--disabled`     | Label and border color when disabled               |
+| `mt-input-gap`        | `--input-gap`    | Gap between border and error/feedback text         |
+
+## Examples
+
+### Wrapping a native input
+
+```tsx
+import { InputField } from "@g4rcez/components";
+
+<InputField title="Username" name="username" required>
+    <input id="username" name="username" className="h-input-height w-full flex-1 bg-transparent px-input-x text-foreground outline-none" />
+</InputField>;
+```
+
+### With info tooltip and error
+
+```tsx
+import { MagnifyingGlassIcon, CheckIcon } from "@phosphor-icons/react";
+
+<InputField
+    title="API Key"
+    name="api_key"
+    info="Your secret API key from the developer portal."
+    error={apiKeyError}
+    left={<MagnifyingGlassIcon size={16} className="text-muted-foreground" />}
+    right={isValid ? <CheckIcon size={16} className="text-success" /> : null}
+    required
+>
+    <input
+        id="api_key"
+        name="api_key"
+        type="password"
+        className="h-input-height w-full flex-1 bg-transparent px-input-x text-foreground outline-none"
+    />
+</InputField>;
+```
+
+### Optional vs required
+
+```tsx
+{
+    /* Required — "Optional" badge is hidden */
+}
+<InputField title="Email" name="email" required>
+    <input id="email" name="email" type="email" className="h-input-height w-full flex-1 bg-transparent px-input-x text-foreground outline-none" />
+</InputField>;
+
+{
+    /* Optional — shows "Optional" badge */
+}
+<InputField title="Website" name="website">
+    <input id="website" name="website" type="url" className="h-input-height w-full flex-1 bg-transparent px-input-x text-foreground outline-none" />
+</InputField>;
+```
+
+### Hidden label (accessible)
+
+```tsx
+<InputField title="Search" name="search" hiddenLabel>
+    <input
+        id="search"
+        name="search"
+        placeholder="Search..."
+        className="h-input-height w-full flex-1 bg-transparent px-input-x text-foreground outline-none"
+    />
+</InputField>
+```
+
+### Feedback after validation
+
+```tsx
+<InputField
+    title="Slug"
+    name="slug"
+    feedback={isAvailable ? "This slug is available." : undefined}
+    error={!isAvailable ? "Slug is already taken." : undefined}
+    required
+>
+    <input id="slug" name="slug" className="h-input-height w-full flex-1 bg-transparent px-input-x text-foreground outline-none" />
+</InputField>
+```
+
+## Do
+
+- Use `InputField` when building new form controls to ensure consistent label, error, and feedback layout across the application.
+- Always provide a `title` for every field so screen readers can identify the control.
+- Use the `info` prop for fields that need supplemental explanation without cluttering the label.
+- Match the `id` on the inner control to the `name` (or `id`) on `InputField` so the `<label htmlFor>` association works correctly.
+
+## Don't
+
+- Don't pass raw Tailwind color classes (`bg-blue-500`, `text-white`, `border-gray-300`) to `InputField` wrappers — 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 `InputField` for non-form content; it is specifically designed for labeled input controls.
+- Don't skip the `title` prop — omitting it hides the label but may break screen reader associations.
+
+## Accessibility
+
+- Renders a `<fieldset>` element as the outer wrapper, with `aria-disabled` when disabled.
+- The inner `<label>` uses `htmlFor` linked to `id` (or `name`) to associate with the control.
+- Error messages render as a `<p>` below the field; they are shown after the user interacts with the input (`data-initialized="true"`) or when `error` is set explicitly.
+- Feedback messages render as a separate `<p>` and are hidden when an error is present.
+- The `info` tooltip uses `Tooltip` with `aria-label` / `aria-describedby` for screen reader support.
+- `reportStatus` icons use `aria-hidden="true"` since they are supplemental visual indicators.
+
+## Data Attributes
+
+- `data-component` — reflects the `componentName` prop (e.g., `"input"`, `"select"`, `"autocomplete"`).
+- `data-error` — `"true"` when an `error` string is present; drives CSS group variants.
+- `data-interactive` — `"true"` when `interactive` is set; used for custom interactive state styling.
+
+## Notes
+
+- `InputField` uses Tailwind `group` classes to synchronize hover and focus states between the outer wrapper and inner elements. The `group-focus-within:border-primary` and `group-hover:border-primary` patterns rely on this.
+- The optional text label ("Optional") is sourced from the translation system via `useTranslations`, making it localizable.
+- `reportStatus` defaults to the value configured in `useTweaks().input.iconFeedback`, allowing a global default.

package/ai/docs/List.md

@@ -0,0 +1,208 @@
+---
+title: List
+description: Animated list that expands each item into a focused floating detail overlay when clicked.
+package: "@g4rcez/components"
+export: "{ AnimatedList, AnimatedListItem }"
+import: "import { AnimatedList, AnimatedListItem } from '@g4rcez/components/list'"
+category: display
+---
+
+# List
+
+Animated list that expands each item into a focused floating detail overlay when clicked.
+
+`AnimatedList` and `AnimatedListItem` are exported from the `@g4rcez/components/list` subpath. Each row in the list is clickable; selecting a row opens a `motion/react`-animated card overlay with the item's full content.
+
+## Import
+
+```tsx
+import { AnimatedList, AnimatedListItem } from "@g4rcez/components/list";
+```
+
+## Props
+
+### AnimatedList
+
+| Prop       | Type              | Default | Description                              |
+| ---------- | ----------------- | ------- | ---------------------------------------- |
+| `children` | `React.ReactNode` | —       | One or more `AnimatedListItem` elements. |
+
+### AnimatedListItem
+
+| Prop          | Type                             | Default | Description                                                                                                                      |
+| ------------- | -------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `title`       | `Label`                          | —       | Primary heading shown in the list row and in the overlay header.                                                                 |
+| `description` | `Label`                          | —       | Secondary text rendered below the title in both the row and the overlay.                                                         |
+| `children`    | `Label`                          | —       | Content rendered inside the expanded overlay below the header section.                                                           |
+| `avatar`      | `Label`                          | —       | Optional leading node (image, icon, or element) displayed before the title in the row.                                           |
+| `leading`     | `React.FC<{ open: () => void }>` | —       | Optional render-prop component at the trailing end of the row. Receives an `open` callback to open the overlay programmatically. |
+
+`Label` is `string | number | ReactNode`.
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token                 | CSS Variable         | Purpose                                                             |
+| --------------------- | -------------------- | ------------------------------------------------------------------- |
+| `border-card-border`  | `--card-border`      | Row separator and overlay card border                               |
+| `bg-card-background`  | `--card-background`  | Overlay card background color                                       |
+| `rounded-card`        | `--radius-card`      | Overlay card corner radius                                          |
+| `shadow-shadow-card`  | `--shadow-card`      | Overlay card drop shadow                                            |
+| `text-foreground`     | `--foreground`       | Default text color for row and overlay content                      |
+| `text-secondary`      | `--secondary`        | Description text color                                              |
+| `text-primary`        | `--primary`          | Row title hover color and avatar focus ring                         |
+| `text-danger`         | `--danger`           | Close button hover color in the overlay                             |
+| `bg-floating-overlay` | `--floating-overlay` | Semi-transparent backdrop behind the overlay (used at 70 % opacity) |
+| `z-floating`          | `--z-floating`       | `z-index` for the overlay card (value: 22)                          |
+| `z-overlay`           | `--z-overlay`        | `z-index` for the backdrop scrim                                    |
+
+## Examples
+
+### Basic usage
+
+```tsx
+import { AnimatedList, AnimatedListItem } from "@g4rcez/components/list";
+
+const members = [
+    { id: "1", name: "Alice Johnson", role: "Engineering" },
+    { id: "2", name: "Bob Smith", role: "Design" },
+];
+
+export function TeamList() {
+    return (
+        <AnimatedList>
+            {members.map((m) => (
+                <AnimatedListItem key={m.id} title={m.name} description={m.role}>
+                    <p className="text-foreground">Full profile for {m.name}.</p>
+                </AnimatedListItem>
+            ))}
+        </AnimatedList>
+    );
+}
+```
+
+### With avatar
+
+```tsx
+import { AnimatedList, AnimatedListItem } from "@g4rcez/components/list";
+import { UserCircleIcon } from "@phosphor-icons/react";
+
+export function UserDirectory() {
+    return (
+        <AnimatedList>
+            <AnimatedListItem
+                title="Carol White"
+                description="Product Manager"
+                avatar={<UserCircleIcon size={40} className="text-muted-foreground" />}
+            >
+                <div className="flex flex-col gap-2 text-foreground">
+                    <span>Department: Product</span>
+                    <span>Location: San Francisco</span>
+                </div>
+            </AnimatedListItem>
+        </AnimatedList>
+    );
+}
+```
+
+### With trailing action using `leading`
+
+```tsx
+import { AnimatedList, AnimatedListItem } from "@g4rcez/components/list";
+import { Button } from "@g4rcez/components/button";
+
+export function OrderList({ orders }: { orders: Order[] }) {
+    return (
+        <AnimatedList>
+            {orders.map((order) => (
+                <AnimatedListItem
+                    key={order.id}
+                    title={`Order #${order.id}`}
+                    description={`Total: ${order.total}`}
+                    leading={({ open }) => (
+                        <Button size="small" theme="ghost-muted" onClick={open}>
+                            View details
+                        </Button>
+                    )}
+                >
+                    <OrderDetailContent order={order} />
+                </AnimatedListItem>
+            ))}
+        </AnimatedList>
+    );
+}
+```
+
+### Notification / activity feed
+
+```tsx
+import { AnimatedList, AnimatedListItem } from "@g4rcez/components/list";
+import { CheckCircleIcon, WarningIcon } from "@phosphor-icons/react";
+
+const feed = [
+    {
+        id: "n1",
+        icon: <CheckCircleIcon size={20} className="text-success" />,
+        title: "Deployment succeeded",
+        time: "2 min ago",
+        detail: "All 3 services are healthy.",
+    },
+    {
+        id: "n2",
+        icon: <WarningIcon size={20} className="text-warn" />,
+        title: "High CPU usage",
+        time: "10 min ago",
+        detail: "Instance i-0ab2 is at 94 %.",
+    },
+];
+
+export function NotificationFeed() {
+    return (
+        <AnimatedList>
+            {feed.map((n) => (
+                <AnimatedListItem key={n.id} title={n.title} description={n.time} avatar={n.icon}>
+                    <p className="text-sm text-muted-foreground">{n.detail}</p>
+                </AnimatedListItem>
+            ))}
+        </AnimatedList>
+    );
+}
+```
+
+## Do
+
+- Keep `title` and `description` short — they share a single row and are not truncated automatically.
+- Provide meaningful `children` content in the overlay to justify clicking the row.
+- Use `leading` to expose a primary call-to-action alongside the title without forcing the user to open the overlay.
+- Use design-token classes inside the overlay content (`bg-card-background`, `text-foreground`, `border-card-border`).
+
+## Don't
+
+- Don't pass raw Tailwind color classes (`bg-blue-500`, `text-white`, `border-gray-300`) — use 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 this component for purely informational lists where no detail overlay is needed — use a plain `<ul>` instead.
+- Don't embed full applications or heavy forms inside the overlay `children`; use a `Modal` for complex workflows.
+- Don't render `AnimatedListItem` outside of `AnimatedList` — the item component returns a `Fragment` and relies entirely on the parent list for rendering.
+
+## Accessibility
+
+- The list renders as `<ul role="list">`.
+- Each row title/description area is a `<button>`, making it keyboard focusable and activatable with `Enter` or `Space`.
+- The overlay uses `FloatingFocusManager` to trap focus and `FloatingOverlay` with `lockScroll` to block background interaction.
+- Pressing `Escape`, clicking outside, or clicking the close button dismisses the overlay.
+- The close button inside the overlay is a focusable `<button>` with an `XIcon`.
+- `MotionConfig reducedMotion="user"` honours the system-level reduced-motion preference, disabling animations when requested.
+
+## Data Attributes
+
+- `layoutId="item-{id}"` — shared between the list row `<li>` and the overlay card `<motion.div>` to drive the shared-element expand/collapse animation.
+- `layoutId="toast-{id}"` — inner content wrapper for coordinated layout transitions.
+
+## Notes
+
+- Only one item can be open at a time; selecting a new item dismisses the previous overlay automatically.
+- `AnimatedListItem` is a shell — it returns a `Fragment` directly and holds no state. All rendering logic lives inside `AnimatedList`, which reads child props via `React.Children.toArray`.
+- The overlay is rendered in a `FloatingPortal` (outside the DOM tree) to avoid stacking-context or overflow clipping issues.
+- Animations use `motion/react` shared-layout (`layoutId`) so the item card expands smoothly from its row position to the center of the viewport.
+- The animation transition is `tween` with a 0.3 s duration; `stiffness` is set low (25) for a relaxed feel.

package/ai/docs/Menu.md

@@ -0,0 +1,168 @@
+---
+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<IconProps>` | —       | 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 { PencilSimpleIcon, TrashIcon } from "@phosphor-icons/react";
+import { Menu, MenuItem } from "@g4rcez/components/menu";
+
+<Menu label="Settings">
+    <MenuItem title="Edit" Right={PencilSimpleIcon}>
+        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.