@g4rcez/components 4.0.1 → 4.1.1

package/dist/ai/docs/InputField.md

@@ -1,170 +0,0 @@
----
-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/dist/ai/docs/List.md

@@ -1,205 +0,0 @@
----
-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/dist/ai/docs/Menu.md

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