@g4rcez/components 4.0.1 → 4.1.1

package/ai/docs/Textarea.md

@@ -0,0 +1,144 @@
+---
+title: Textarea
+description: Auto-growing multi-line text input built on the InputField foundation.
+package: "@g4rcez/components"
+export: "{ Textarea }"
+import: "import { Textarea } from '@g4rcez/components'"
+category: form
+---
+
+# Textarea
+
+Auto-growing multi-line text input built on the InputField foundation.
+
+## Import
+
+```tsx
+import { Textarea } from "@g4rcez/components";
+```
+
+## Props
+
+Inherits all `InputField` props and standard HTML `<textarea>` attributes, plus:
+
+| Prop          | Type      | Default | Description                                                                             |
+| ------------- | --------- | ------- | --------------------------------------------------------------------------------------- |
+| `title`       | `Label`   | —       | Label for the textarea.                                                                 |
+| `error`       | `string`  | —       | Error message displayed below the field.                                                |
+| `loading`     | `boolean` | `false` | Disables the field and signals a pending state.                                         |
+| `rows`        | `number`  | `2`     | Initial number of visible text rows.                                                    |
+| `next`        | `string`  | —       | ID of the next element to focus when Enter is pressed (requires `enterKeyHint="next"`). |
+| `placeholder` | `string`  | —       | Placeholder text.                                                                       |
+| `required`    | `boolean` | —       | Marks the field as required.                                                            |
+| `className`   | `string`  | —       | Additional CSS classes for the `<textarea>` element.                                    |
+
+## 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` (via `group-error`) | `--input-mask-error` | Placeholder tint in error state                      |
+| `text-foreground`                                  | `--foreground`       | Input text color                                     |
+| `text-danger` (via `group-error`)                  | `--danger`           | Text color in error state                            |
+| `bg-transparent`                                   | —                    | Input background (inherits from field wrapper)       |
+| `focus:ring-primary`                               | `--primary`          | Focus ring                                           |
+| `group-focus-within:border-primary`                | `--primary`          | Border highlight on focus                            |
+| `group-hover:border-primary`                       | `--primary`          | Border highlight on hover                            |
+| `h-input-height`                                   | `--input-height`     | Base height token (overridden by `rows` in practice) |
+| `px-input-x`                                       | `--input-x`          | Horizontal padding                                   |
+| `py-input-y`                                       | `--input-y`          | Vertical padding                                     |
+
+## Examples
+
+### Basic usage
+
+```tsx
+import { Textarea } from "@g4rcez/components";
+
+export default function BioField() {
+    return <Textarea title="Bio" name="bio" placeholder="Tell us about yourself…" rows={4} onChange={(e) => console.log(e.target.value)} />;
+}
+```
+
+### With validation error
+
+```tsx
+import { Textarea } from "@g4rcez/components";
+
+export default function MessageField() {
+    return (
+        <Textarea
+            title="Message"
+            name="message"
+            required
+            error="Message is required and must be at least 10 characters."
+            placeholder="Enter your message…"
+        />
+    );
+}
+```
+
+### Monospace styling for code
+
+```tsx
+import { Textarea } from "@g4rcez/components";
+
+export default function CssSnippetField() {
+    return <Textarea title="CSS Snippet" name="css" className="font-mono text-sm" rows={6} placeholder="body { margin: 0; }" />;
+}
+```
+
+### Focus-next navigation
+
+```tsx
+import { Textarea } from "@g4rcez/components";
+import { Input } from "@g4rcez/components";
+
+export default function MultiFieldForm() {
+    return (
+        <div className="flex flex-col gap-base">
+            <Textarea title="Description" name="description" enterKeyHint="next" next="submit-btn" rows={3} placeholder="Describe the issue…" />
+            <button id="submit-btn" type="submit" className="btn">
+                Submit
+            </button>
+        </div>
+    );
+}
+```
+
+## Do
+
+- Provide a descriptive `title` to label the field.
+- Set a sensible initial `rows` value based on the expected content length.
+- Use `Textarea` whenever the user is expected to provide more than a single line of text.
+- Use design-token classes on wrapper elements (`bg-background`, `text-foreground`, `border-border`).
+
+## Don't
+
+- Don't use `Textarea` for single-line inputs like names or emails — use `Input` instead.
+- Don't fix the height with a `className` like `h-32` if you want the auto-resize behavior to work.
+- Don't pass raw Tailwind color classes (`bg-gray-50`, `border-gray-300`) — use design tokens instead.
+- Don't use arbitrary Tailwind values (`bg-[#abc]`) — override CSS variables in your `@theme` block instead.
+
+## Accessibility
+
+- Rendered inside an `InputField` which wraps the element with `<fieldset>` and a `<label>` linked via `id`/`for`.
+- Supports `aria-required`, `aria-invalid`, `aria-disabled`, and `aria-readonly` via prop spread.
+- Keyboard navigation follows standard `<textarea>` behavior (Tab to focus, Shift+Tab to leave).
+- When `enterKeyHint="next"` and a `next` id is provided, pressing Enter moves focus to the target element.
+
+## Data Attributes
+
+| Attribute        | Element           | Value         | Description                                       |
+| ---------------- | ----------------- | ------------- | ------------------------------------------------- |
+| `data-component` | `InputField` root | `"textarea"`  | Identifies the component.                         |
+| `data-error`     | `InputField` root | truthy string | Present when an error message is supplied.        |
+| `data-next`      | `<textarea>`      | element id    | Target element id for Enter-key focus forwarding. |
+
+## Notes
+
+- Auto-resize is driven by a native `input` event listener that sets `style.height = "auto"` then `style.height = scrollHeight + "px"` — no JavaScript polling or ResizeObserver involved.
+- The resize handle is set to `resize-y` by default; add `className="resize-none"` to disable it.
+- Built via the shared `createFreeText` factory, which also powers the `Input` component — all `InputField` layout features (left/right slots, optional text, feedback, etc.) are available.

package/ai/docs/Timeline.md

@@ -0,0 +1,212 @@
+---
+title: Timeline
+description: Vertical chronological event list with icon markers, body content, and optional right-side metadata.
+package: "@g4rcez/components"
+export: "{ Timeline }"
+import: "import { Timeline, TimelineItem } from '@g4rcez/components/timeline'"
+category: display
+---
+
+# Timeline
+
+Vertical chronological event list with icon markers, body content, and optional right-side metadata.
+
+## Import
+
+```tsx
+import { Timeline, TimelineItem } from "@g4rcez/components/timeline";
+```
+
+## Components
+
+### Timeline
+
+The root container. Renders as a `<ul>` with `role="list"`. The vertical connector line on the last item is hidden automatically.
+
+### TimelineItem
+
+A single event entry. Renders as a `<li>` with `role="listitem"` and `pb-12` vertical spacing for the connector line.
+
+### TimelineItem.Icon
+
+The visual marker — a rounded circle, typically containing an icon. Renders as a `<header>`.
+
+| Prop        | Type              | Default | Description                        |
+| ----------- | ----------------- | ------- | ---------------------------------- |
+| `className` | `string`          | —       | Override icon container appearance |
+| `children`  | `React.ReactNode` | —       | Icon element                       |
+
+### TimelineItem.Body
+
+The main content area. Polymorphic — defaults to `<section>`.
+
+| Prop        | Type                | Default     | Description               |
+| ----------- | ------------------- | ----------- | ------------------------- |
+| `as`        | `React.ElementType` | `"section"` | HTML element to render as |
+| `className` | `string`            | —           | Additional classes        |
+| `children`  | `React.ReactNode`   | —           | Event body content        |
+
+### TimelineItem.Right
+
+Optional right-side slot for timestamps or auxiliary actions. Renders inside a `<footer>` wrapper. Polymorphic — defaults to `<button>`.
+
+| Prop       | Type                | Default    | Description               |
+| ---------- | ------------------- | ---------- | ------------------------- |
+| `as`       | `React.ElementType` | `"button"` | HTML element to render as |
+| `children` | `React.ReactNode`   | —          | Right-side content        |
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token                     | CSS Variable           | Purpose                           |
+| ------------------------- | ---------------------- | --------------------------------- |
+| `bg-card-border`          | `--card-border`        | Vertical connector line color     |
+| `bg-primary`              | `--primary`            | Icon container default background |
+| `text-primary-foreground` | `--primary-foreground` | Icon default text/icon color      |
+
+## Examples
+
+### Order Tracking Timeline
+
+```tsx
+import { CheckIcon, PackageIcon, TruckIcon } from "@phosphor-icons/react";
+
+<Timeline>
+    <TimelineItem>
+        <TimelineItem.Icon>
+            <CheckIcon size={20} />
+        </TimelineItem.Icon>
+        <TimelineItem.Body>
+            <h4 className="font-bold">Order Placed</h4>
+            <p className="text-muted-foreground">Your order has been received and is being processed.</p>
+        </TimelineItem.Body>
+        <TimelineItem.Right as="time">10:00 AM</TimelineItem.Right>
+    </TimelineItem>
+
+    <TimelineItem>
+        <TimelineItem.Icon>
+            <PackageIcon size={20} />
+        </TimelineItem.Icon>
+        <TimelineItem.Body>
+            <h4 className="font-bold">Packed</h4>
+            <p className="text-muted-foreground">Your order has been packed and is ready for shipment.</p>
+        </TimelineItem.Body>
+        <TimelineItem.Right as="time">1:00 PM</TimelineItem.Right>
+    </TimelineItem>
+
+    <TimelineItem>
+        <TimelineItem.Icon>
+            <TruckIcon size={20} />
+        </TimelineItem.Icon>
+        <TimelineItem.Body>
+            <h4 className="font-bold">Shipped</h4>
+            <p className="text-muted-foreground">Your package is on its way.</p>
+        </TimelineItem.Body>
+        <TimelineItem.Right as="time">2:30 PM</TimelineItem.Right>
+    </TimelineItem>
+</Timeline>;
+```
+
+### Simple Text Timeline
+
+```tsx
+<Timeline>
+    <TimelineItem>
+        <TimelineItem.Body>
+            <strong>Step 1:</strong> Initial setup completed.
+        </TimelineItem.Body>
+    </TimelineItem>
+    <TimelineItem>
+        <TimelineItem.Body>
+            <strong>Step 2:</strong> Data migration started.
+        </TimelineItem.Body>
+    </TimelineItem>
+</Timeline>
+```
+
+### Activity Feed
+
+```tsx
+import { UserIcon, PencilSimpleIcon, TrashIcon } from "@phosphor-icons/react";
+
+function ActivityFeed({ events }: { events: ActivityEvent[] }) {
+    const iconMap = {
+        create: UserIcon,
+        update: PencilSimpleIcon,
+        delete: TrashIcon,
+    };
+
+    return (
+        <Timeline>
+            {events.map((event) => {
+                const Icon = iconMap[event.type];
+                return (
+                    <TimelineItem key={event.id}>
+                        <TimelineItem.Icon>
+                            <Icon size={18} />
+                        </TimelineItem.Icon>
+                        <TimelineItem.Body>
+                            <p className="font-medium">
+                                {event.user} {event.action}
+                            </p>
+                            <p className="text-sm text-muted-foreground">{event.description}</p>
+                        </TimelineItem.Body>
+                        <TimelineItem.Right as="time" dateTime={event.iso}>
+                            {event.relativeTime}
+                        </TimelineItem.Right>
+                    </TimelineItem>
+                );
+            })}
+        </Timeline>
+    );
+}
+```
+
+### Custom Icon Background
+
+```tsx
+import { WarningCircleIcon } from "@phosphor-icons/react";
+
+<TimelineItem>
+    <TimelineItem.Icon className="bg-danger text-danger-foreground">
+        <WarningCircleIcon size={20} />
+    </TimelineItem.Icon>
+    <TimelineItem.Body>
+        <h4 className="font-bold text-danger-foreground">Deployment Failed</h4>
+        <p className="text-muted-foreground">Build step exited with code 1.</p>
+    </TimelineItem.Body>
+</TimelineItem>;
+```
+
+## Do
+
+- Use icons that clearly represent the status or type of event.
+- Keep body content concise; link to a detail view for lengthy information.
+- Maintain consistent chronological order (ascending or descending) throughout the list.
+- Use semantic elements for timestamps — `as="time"` with a `dateTime` attribute.
+- Use design-token classes for icon background overrides (`bg-success`, `bg-danger`).
+
+## Don't
+
+- Don't pass raw Tailwind color classes (`bg-green-500`, `text-red-600`) for icon backgrounds — use design tokens instead.
+- Don't use arbitrary Tailwind values (`bg-[#abc]`) — override CSS variables in your `@theme` block.
+- Don't cram too much information into a single `TimelineItem`; link to detail pages.
+- Don't use `Timeline` for non-sequential data — use `List` or `Table` for unordered collections.
+
+## Accessibility
+
+- `Timeline` uses `<ul role="list">` and each `TimelineItem` uses `<li role="listitem">` for semantic list structure.
+- The vertical connector `<span>` between items carries `aria-hidden="true"` since it is purely decorative.
+- The last item's connector line is hidden via a CSS selector (`[&>li:last-child>span[aria-hidden=true]]:hidden`), removing it from layout without JS.
+
+## Data Attributes
+
+- `data-component="timeline"` — applied to the `<ul>` container.
+- `data-component="timeline-item"` — applied to each `<li>` entry.
+
+## Notes
+
+- `TimelineItem.Right` defaults to `as="button"` — change to `as="time"` or `as="span"` if the right slot is non-interactive.
+- Vertical spacing between entries is controlled by `pb-12` on `TimelineItem`; the connector line fills this gap.
+- `TimelineItem` can be used without `TimelineItem.Icon` — the connector line still renders from the left edge.

package/{dist/ai → ai}/docs/Toolbar.md

@@ -19,20 +19,20 @@ import { Toolbar } from "@g4rcez/components";
 
 ## Props
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `children` | `React.ReactNode` | — | Items displayed inside the toolbar |
-| `root` | `HTMLElement` | — | Optional root element reference for scrolling context |
+| Prop       | Type              | Default | Description                                           |
+| ---------- | ----------------- | ------- | ----------------------------------------------------- |
+| `children` | `React.ReactNode` | —       | Items displayed inside the toolbar                    |
+| `root`     | `HTMLElement`     | —       | Optional root element reference for scrolling context |
 
 ## Design Tokens
 
 Tokens this component reads. Customize by overriding these CSS variables in your theme.
 
-| Token | CSS Variable | Purpose |
-|-------|-------------|---------|
-| `bg-background` | `--background` | Toolbar surface background |
-| `border-card-border` | `--card-border` | Toolbar border |
-| `rounded-lg` | — | Toolbar corner radius |
+| Token                | CSS Variable    | Purpose                    |
+| -------------------- | --------------- | -------------------------- |
+| `bg-background`      | `--background`  | Toolbar surface background |
+| `border-card-border` | `--card-border` | Toolbar border             |
+| `rounded-lg`         | —               | Toolbar corner radius      |
 
 ## Examples
 
@@ -43,9 +43,9 @@ import { Toolbar } from "@g4rcez/components";
 import { Button } from "@g4rcez/components/button";
 
 <Toolbar>
-  <Button theme="ghost-muted">Cancel</Button>
-  <Button theme="primary">Save Changes</Button>
-</Toolbar>
+    <Button theme="ghost-muted">Cancel</Button>
+    <Button theme="primary">Save Changes</Button>
+</Toolbar>;
 ```
 
 ### Rich Text Editor Toolbar
@@ -57,24 +57,26 @@ import { Button } from "@g4rcez/components/button";
 import { Tooltip } from "@g4rcez/components/tooltip";
 
 <Toolbar>
-  <Tooltip title="Bold">
-    <Button size="icon" theme="ghost-neutral">
-      <BoldIcon size={16} />
+    <Tooltip title="Bold">
+        <Button size="icon" theme="ghost-neutral">
+            <BoldIcon size={16} />
+        </Button>
+    </Tooltip>
+    <Tooltip title="Italic">
+        <Button size="icon" theme="ghost-neutral">
+            <ItalicIcon size={16} />
+        </Button>
+    </Tooltip>
+    <Tooltip title="Underline">
+        <Button size="icon" theme="ghost-neutral">
+            <UnderlineIcon size={16} />
+        </Button>
+    </Tooltip>
+    <div className="mx-2 h-6 w-px bg-card-border" />
+    <Button theme="primary" size="small">
+        Publish
     </Button>
-  </Tooltip>
-  <Tooltip title="Italic">
-    <Button size="icon" theme="ghost-neutral">
-      <ItalicIcon size={16} />
-    </Button>
-  </Tooltip>
-  <Tooltip title="Underline">
-    <Button size="icon" theme="ghost-neutral">
-      <UnderlineIcon size={16} />
-    </Button>
-  </Tooltip>
-  <div className="mx-2 h-6 w-px bg-card-border" />
-  <Button theme="primary" size="small">Publish</Button>
-</Toolbar>
+</Toolbar>;
 ```
 
 ### Batch Action Toolbar
@@ -85,23 +87,21 @@ import { Toolbar } from "@g4rcez/components";
 import { Button } from "@g4rcez/components/button";
 
 function BatchToolbar({ selectedCount }: { selectedCount: number }) {
-  if (selectedCount === 0) return null;
-
-  return (
-    <Toolbar>
-      <span className="text-sm text-muted-foreground">
-        {selectedCount} selected
-      </span>
-      <Button theme="ghost-neutral" size="small">
-        <DownloadIcon size={16} />
-        Export
-      </Button>
-      <Button theme="danger" size="small">
-        <TrashIcon size={16} />
-        Delete
-      </Button>
-    </Toolbar>
-  );
+    if (selectedCount === 0) return null;
+
+    return (
+        <Toolbar>
+            <span className="text-sm text-muted-foreground">{selectedCount} selected</span>
+            <Button theme="ghost-neutral" size="small">
+                <DownloadIcon size={16} />
+                Export
+            </Button>
+            <Button theme="danger" size="small">
+                <TrashIcon size={16} />
+                Delete
+            </Button>
+        </Toolbar>
+    );
 }
 ```