@g4rcez/components 3.0.0 → 3.0.1

package/dist/ai/docs/Input.md

@@ -0,0 +1,237 @@
+---
+title: Input
+description: Text input with optional masking for currencies, percentages, phone numbers, dates, and custom regex patterns.
+package: "@g4rcez/components"
+export: "{ Input }"
+import: "import { Input } from '@g4rcez/components/input'"
+category: form
+---
+
+# Input
+
+Text input with optional masking for currencies, percentages, phone numbers, dates, and custom regex patterns.
+
+## Import
+
+```tsx
+import { Input } from "@g4rcez/components/input";
+```
+
+## Props
+
+`Input` extends all standard HTML `<input>` attributes plus `InputField` layout props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `mask` | `AllMasks \| Array<string \| RegExp> \| ((value: string) => AllMasks)` | - | Input mask pattern |
+| `locale` | `Locales` | - | Locale for currency/number formatting |
+| `currency` | `CurrencyCode` | - | Currency code when using `mask="currency"` |
+| `error` | `string` | - | Error message shown below the field |
+| `title` | `string` | - | Field label |
+| `feedback` | `Label` | - | Success or neutral feedback text below the field |
+| `left` | `Label` | - | Content rendered on the left inside the field border |
+| `right` | `Label` | - | Content rendered on the right inside the field border |
+| `required` | `boolean` | `false` | Marks field as required; hides "Optional" label text |
+| `disabled` | `boolean` | `false` | Disabled state |
+| `loading` | `boolean` | `false` | Loading state |
+| `container` | `string` | - | Extra CSS classes for the outer `fieldset` |
+| `labelClassName` | `string` | - | Extra CSS classes for the label/border wrapper |
+| `next` | `string` | - | `id` of the next field to focus when Enter is pressed with `enterKeyHint="next"` |
+| `hiddenLabel` | `boolean` | `false` | Visually hides the label but keeps it for screen readers |
+| `...props` | `React.InputHTMLAttributes<HTMLInputElement>` | - | All standard input attributes |
+
+### Mask patterns
+
+| Pattern char | Matches |
+|---|---|
+| `9` | Digit (0–9) |
+| `A` | Letter (a–z, A–Z) |
+| `S` | Alphanumeric |
+| `*` | Any character |
+
+### Special mask strings
+
+| Value | Description |
+|---|---|
+| `"currency"` | Currency formatting (requires `locale` and `currency`) |
+| `"percentage"` | Percentage input with `%` symbol |
+| `"decimal"` | Decimal number formatting |
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token | CSS Variable | Purpose |
+|-------|-------------|---------|
+| `h-input-height` | `--input-height` | Input height |
+| `px-input-x` | `--input-x` | Horizontal padding |
+| `py-input-y` | `--input-y` | Vertical padding |
+| `mt-input-gap` | `--input-gap` | Gap between field border and error/feedback text |
+| `border-input-border` | `--input-border` | Default border color |
+| `text-field-label` | `--field-label` | Label text color |
+| `text-foreground` | `--foreground` | Input text color |
+| `text-primary` | `--primary` | Focus ring, focus/hover border color |
+| `text-danger` | `--danger` | Error state border, text, and label color |
+| `text-disabled` | `--disabled` | Disabled text and border color |
+| `placeholder-input-mask` | `--input-mask` | Placeholder text color |
+| `placeholder-input-mask-error` | `--input-mask-error` | Placeholder color in error state |
+
+## Examples
+
+### Basic text input
+
+```tsx
+import { Input } from "@g4rcez/components/input";
+
+<Input name="name" title="Full name" placeholder="Jane Smith" required />
+```
+
+### Phone number mask
+
+```tsx
+<Input
+  name="phone"
+  title="Phone"
+  mask="(99) 99999-9999"
+  placeholder="(00) 00000-0000"
+/>
+```
+
+### Currency input
+
+```tsx
+<Input
+  name="price"
+  title="Price"
+  mask="currency"
+  currency="USD"
+  locale="en-US"
+  placeholder="0.00"
+/>
+```
+
+### Dynamic mask (CPF / CNPJ)
+
+```tsx
+const docMask = (value: string) =>
+  value.replace(/\D/g, "").length <= 11
+    ? "999.999.999-99"
+    : "99.999.999/9999-99";
+
+<Input
+  name="document"
+  title="CPF or CNPJ"
+  mask={docMask}
+  placeholder="000.000.000-00"
+/>
+```
+
+### Input with inline left/right slots
+
+```tsx
+import { SearchIcon } from "lucide-react";
+
+<Input
+  name="search"
+  title="Search"
+  left={<SearchIcon size={16} className="text-muted-foreground" />}
+  placeholder="Type to search..."
+/>
+```
+
+### Input with error and feedback
+
+```tsx
+const [email, setEmail] = useState("");
+const error = email && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
+  ? "Enter a valid email address"
+  : undefined;
+
+<Input
+  name="email"
+  type="email"
+  title="Email"
+  value={email}
+  onChange={(e) => setEmail(e.target.value)}
+  error={error}
+  feedback={!error && email ? "Looks good!" : undefined}
+/>
+```
+
+### Enter-to-advance between fields
+
+```tsx
+<Input
+  name="first"
+  title="First name"
+  enterKeyHint="next"
+  next="last"
+/>
+<Input
+  name="last"
+  id="last"
+  title="Last name"
+  enterKeyHint="done"
+/>
+```
+
+### Inside a form
+
+```tsx
+import { Form } from "@g4rcez/components/form";
+import { Button } from "@g4rcez/components/button";
+
+function SignUpForm() {
+  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    const data = new FormData(e.currentTarget);
+    console.log(Object.fromEntries(data));
+  };
+
+  return (
+    <Form onSubmit={handleSubmit} className="flex flex-col gap-base max-w-md">
+      <Input name="name" title="Full name" required />
+      <Input name="email" type="email" title="Email" required />
+      <Input name="phone" title="Phone" mask="(99) 99999-9999" />
+      <Button theme="primary" type="submit">Sign up</Button>
+    </Form>
+  );
+}
+```
+
+## Do
+
+- Use `mask` patterns that match user expectations for the data type.
+- Provide a `placeholder` that shows the expected format (e.g., `"(00) 00000-0000"`).
+- Use the `error` prop to surface validation messages from your form library or manual validation.
+- Use the `next` prop with `enterKeyHint="next"` to create smooth keyboard flows on mobile.
+- Use design-token classes for wrapper elements (`bg-background`, `text-foreground`, `border-border`).
+
+## Don't
+
+- Don't pass raw Tailwind color classes (`bg-blue-500`, `text-white`, `border-gray-300`) — 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 a mask that blocks valid input variations — prefer dynamic masks for formats with variable length.
+- Don't forget that the mask formats the display value; if your backend expects raw data, strip formatting before sending.
+- Don't use `Input` for long-form text — use `Textarea` instead.
+
+## Accessibility
+
+- Renders a semantic `<input>` wrapped in a `<fieldset>` with an associated `<label>` (via `InputField`).
+- `aria-disabled`, `aria-readonly`, and `aria-busy` are set automatically from props.
+- Error messages appear as a visible `<p>` below the field after the user has interacted with it (`data-initialized="true"`).
+- Focus ring uses `focus:ring-primary` for consistent, visible keyboard indication.
+- The `hiddenLabel` prop keeps the label in the accessibility tree while hiding it visually.
+
+## Data Attributes
+
+- `data-initialized` — managed by `initializeInputDataset`; switches from `"false"` to `"true"` after first user interaction, enabling validation display.
+- `data-next` — set from the `next` prop; used to focus the next field on Enter.
+- `data-component="input"` — set on the outer `fieldset` by `InputField`.
+- `data-error` — on the `fieldset`: `"true"` when an `error` string is present.
+
+## Notes
+
+- Built on top of `the-mask-input`. All mask features from that library are available.
+- The component automatically manages cursor positioning during masked input.
+- Works with both controlled (`value` + `onChange`) and uncontrolled (`defaultValue`) patterns.
+- `Input` is created via the `createFreeText` factory, which also powers `Textarea`. Both share the same styling tokens.

package/dist/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 { SearchIcon, CheckIcon } from "lucide-react";
+
+<InputField
+  title="API Key"
+  name="api_key"
+  info="Your secret API key from the developer portal."
+  error={apiKeyError}
+  left={<SearchIcon 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

@@ -0,0 +1,205 @@
+---
+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 "lucide-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, AlertTriangleIcon } from "lucide-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: <AlertTriangleIcon 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.