@g4rcez/components 3.0.0 → 3.0.1

package/dist/ai/docs/Timeline.md

@@ -0,0 +1,210 @@
+---
+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 "lucide-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, EditIcon, TrashIcon } from "lucide-react";
+
+function ActivityFeed({ events }: { events: ActivityEvent[] }) {
+  const iconMap = {
+    create: UserIcon,
+    update: EditIcon,
+    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 { AlertCircleIcon } from "lucide-react";
+
+<TimelineItem>
+  <TimelineItem.Icon className="bg-danger text-danger-foreground">
+    <AlertCircleIcon 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/docs/Toolbar.md

@@ -0,0 +1,132 @@
+---
+title: Toolbar
+description: Sticky floating toolbar for surfacing persistent actions at the bottom of a scrollable area.
+package: "@g4rcez/components"
+export: "{ Toolbar }"
+import: "import { Toolbar } from '@g4rcez/components'"
+category: floating
+---
+
+# Toolbar
+
+Sticky floating toolbar for surfacing persistent actions at the bottom of a scrollable area.
+
+## Import
+
+```tsx
+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 |
+
+## 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 |
+
+## Examples
+
+### Form Actions Toolbar
+
+```tsx
+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>
+```
+
+### Rich Text Editor Toolbar
+
+```tsx
+import { BoldIcon, ItalicIcon, UnderlineIcon } from "lucide-react";
+import { Toolbar } from "@g4rcez/components";
+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} />
+    </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>
+```
+
+### Batch Action Toolbar
+
+```tsx
+import { TrashIcon, DownloadIcon } from "lucide-react";
+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>
+  );
+}
+```
+
+## Do
+
+- Keep the toolbar small — it overlays content and should not obscure more than a thin strip at the bottom.
+- Reserve the toolbar for primary actions users may need at any scroll position.
+- Provide sufficient spacing between touch targets for mobile usability.
+- Use design-token classes for any custom styling inside the toolbar (`bg-background`, `border-card-border`, `text-foreground`).
+
+## Don't
+
+- Don't use `Toolbar` for secondary or rarely used actions — keep the surface focused.
+- Don't cram too many items into the toolbar; it will wrap awkwardly on narrow viewports.
+- Don't pass raw Tailwind color classes (`bg-gray-100`, `border-gray-300`) — use design-token classes.
+- Don't use arbitrary Tailwind values (`bg-[#abc]`) — override CSS variables in your `@theme` block.
+
+## Accessibility
+
+- Wrap the toolbar in a `<div role="toolbar" aria-label="Page actions">` when it contains only icon buttons, so assistive technologies can announce the region.
+- Ensure each icon-only button inside the toolbar has an accessible name via `aria-label` or a `Tooltip` with `focus={true}`.
+- Tab key navigates through items in the toolbar naturally.
+
+## Notes
+
+- The component is a thin wrapper around `motion.div` from `motion/react` with `sticky bottom-4` positioning.
+- The `root` prop is accepted but not yet used in the current implementation — it is reserved for future scrolling context support.
+- Because the toolbar is `sticky` (not `fixed`), it flows with the document and sticks at the bottom of its scrolling container, not the viewport.

package/dist/ai/docs/Tooltip.md

@@ -0,0 +1,231 @@
+---
+title: Tooltip
+description: Polymorphic tooltip with hover, focus, and click triggers; supports cursor-following and rich content.
+package: "@g4rcez/components"
+export: "{ Tooltip }"
+import: "import { Tooltip } from '@g4rcez/components/tooltip'"
+category: floating
+---
+
+# Tooltip
+
+Polymorphic tooltip with hover, focus, and click triggers; supports cursor-following and rich content.
+
+## Import
+
+```tsx
+import { Tooltip } from "@g4rcez/components/tooltip";
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `Label` | — | Tooltip trigger element — the element the user interacts with |
+| `children` | `React.ReactNode` | — | Tooltip popup content |
+| `open` | `boolean` | — | Controlled open state |
+| `enabled` | `boolean` | `true` | Enable or disable the tooltip entirely |
+| `hover` | `boolean` | `true` | Show tooltip on hover |
+| `focus` | `boolean` | `true` | Show tooltip on focus |
+| `popover` | `boolean` | `true` | Show tooltip on click |
+| `placement` | `Placement` | auto | Preferred placement; falls back via `autoPlacement` |
+| `followCursor` | `boolean` | `false` | Tooltip follows the mouse cursor position |
+| `onChange` | `(open: boolean) => void` | — | Open state change handler |
+| `as` | `React.ElementType` | `"span"` | HTML element to render the trigger wrapper as |
+
+> Note: `title` is the **trigger** and `children` is the **popup content**. This is the inverse of the HTML `title` attribute convention — the prop name matches how the component API evolved.
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token | CSS Variable | Purpose |
+|-------|-------------|---------|
+| `bg-tooltip-background` | `--tooltip-background` | Tooltip popup background |
+| `text-tooltip-foreground` | `--tooltip-foreground` | Tooltip popup text color |
+| `border-tooltip-border` | `--tooltip-border` | Tooltip popup border and arrow stroke |
+| `fill-tooltip-background` | `--tooltip-background` | Arrow fill color |
+| `z-tooltip` | `--z-tooltip` | Z-index of the tooltip popup |
+| `shadow-shadow-floating` | `--shadow-floating` | Tooltip drop shadow |
+
+## Placement Options
+
+Supports all Floating UI placements: `"top"`, `"top-start"`, `"top-end"`, `"bottom"`, `"bottom-start"`, `"bottom-end"`, `"left"`, `"left-start"`, `"left-end"`, `"right"`, `"right-start"`, `"right-end"`. When `placement` is omitted, `autoPlacement` picks the best available side.
+
+## Examples
+
+### Basic Hover Tooltip
+
+```tsx
+import { Tooltip } from "@g4rcez/components/tooltip";
+
+<Tooltip title={<button className="px-4 py-2 bg-primary text-primary-foreground rounded-button">Hover me</button>}>
+  This is a helpful tooltip
+</Tooltip>
+```
+
+### Icon Button with Label
+
+```tsx
+import { SaveIcon } from "lucide-react";
+import { Tooltip } from "@g4rcez/components/tooltip";
+import { Button } from "@g4rcez/components/button";
+
+<Tooltip title={<Button size="icon" theme="ghost-neutral"><SaveIcon size={16} /></Button>}>
+  Save (Ctrl+S)
+</Tooltip>
+```
+
+### Interaction Modes
+
+```tsx
+import { Tooltip } from "@g4rcez/components/tooltip";
+
+{/* Hover only */}
+<Tooltip
+  title={<button className="px-4 py-2 rounded-button border border-border text-foreground">Hover Only</button>}
+  focus={false}
+  popover={false}
+>
+  Shown on hover
+</Tooltip>
+
+{/* Focus only — keyboard accessible */}
+<Tooltip
+  title={<input placeholder="Focus me with tab" className="px-3 py-2 rounded-button border border-border bg-background text-foreground" />}
+  hover={false}
+  popover={false}
+>
+  Shown on focus
+</Tooltip>
+
+{/* Click only — acts like a popover */}
+<Tooltip
+  title={<button className="px-4 py-2 bg-primary text-primary-foreground rounded-button">Click me</button>}
+  hover={false}
+  focus={false}
+>
+  Shown on click
+</Tooltip>
+```
+
+### Cursor-Following Tooltip
+
+```tsx
+import { Tooltip } from "@g4rcez/components/tooltip";
+
+<Tooltip
+  followCursor
+  placement="top-start"
+  title={
+    <div className="w-full h-32 rounded-card border border-border bg-muted flex items-center justify-center">
+      <span className="text-muted-foreground">Move your mouse over this area</span>
+    </div>
+  }
+>
+  Follows your cursor
+</Tooltip>
+```
+
+### Controlled Tooltip
+
+```tsx
+import { useState } from "react";
+import { Tooltip } from "@g4rcez/components/tooltip";
+
+function ControlledTooltip() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <Tooltip
+        title={<button className="px-4 py-2 rounded-button border border-border text-foreground">Target</button>}
+        open={isOpen}
+        onChange={setIsOpen}
+        hover={false}
+        focus={false}
+        popover={false}
+      >
+        Externally controlled
+      </Tooltip>
+
+      <div className="mt-4 flex gap-2">
+        <button onClick={() => setIsOpen(true)} className="px-3 py-1 bg-primary text-primary-foreground rounded-button text-sm">
+          Show
+        </button>
+        <button onClick={() => setIsOpen(false)} className="px-3 py-1 bg-muted text-foreground rounded-button text-sm">
+          Hide
+        </button>
+      </div>
+    </>
+  );
+}
+```
+
+### Polymorphic — Render as Different Elements
+
+```tsx
+import { Tooltip } from "@g4rcez/components/tooltip";
+
+{/* Render as <div> */}
+<Tooltip
+  as="div"
+  title={<span className="p-3 bg-muted rounded-button inline-block text-foreground">Div with tooltip</span>}
+>
+  Tooltip on a div
+</Tooltip>
+
+{/* Wrap a paragraph */}
+<Tooltip
+  as="p"
+  title={<span className="text-primary cursor-pointer">Hover this paragraph</span>}
+>
+  Paragraph tooltip
+</Tooltip>
+```
+
+### Form Field Help Tooltip
+
+```tsx
+import { InfoIcon } from "lucide-react";
+import { Tooltip } from "@g4rcez/components/tooltip";
+
+<label className="block text-sm font-medium text-foreground mb-1">
+  Username
+  <Tooltip
+    title={<InfoIcon className="inline ml-1 text-muted-foreground cursor-help" size={14} />}
+  >
+    3–20 characters; letters, numbers, and underscores only
+  </Tooltip>
+</label>
+```
+
+## Do
+
+- Always keep `focus={true}` (default) so keyboard users can access tooltips via Tab navigation.
+- Keep tooltip content short — one or two sentences at most.
+- Use `followCursor` for large interactive areas (charts, canvases) to keep the tip near the pointer.
+- Use design-token classes for any custom elements inside the tooltip popup (`text-tooltip-foreground`, `bg-muted`, etc.).
+
+## Don't
+
+- Don't put essential information only in a tooltip — users on touch devices may never see it.
+- Don't use tooltips for long text or complex layouts — use `Modal` or `Dropdown` instead.
+- Don't pass raw Tailwind color classes (`bg-gray-900`, `text-white`) inside tooltip content — use design-token classes.
+- Don't use arbitrary Tailwind values (`bg-[#abc]`, `z-[9999]`) — override CSS variables in your `@theme` block.
+- Don't use tooltips on elements that are already self-explanatory.
+
+## Accessibility
+
+- By default all three triggers are active (`hover`, `focus`, `popover`); disable `focus` only when the trigger itself provides equivalent keyboard affordance.
+- The tooltip popup receives `role="tooltip"` via Floating UI's `useRole`.
+- `useDismiss` closes the tooltip when focus moves away or `Escape` is pressed.
+- Safe-polygon hover handling keeps the tooltip open while the pointer moves toward interactive content (`popover={true}` enables this).
+- The `as` prop lets you place the reference on a semantically correct element without extra wrapper divs.
+
+## Notes
+
+- The `open` prop syncs to internal state via `useEffect`; when provided, external changes override internal toggle state.
+- `autoPlacement` middleware runs alongside `flip` — placement is fully automatic when `placement` is omitted.
+- Hover delay is controlled by the shared `FLOATING_DELAY` constant; there is no per-instance delay prop.
+- The component is polymorphic via the `Polymorph` core component for the popup and `as` for the trigger wrapper.