@g4rcez/components 4.0.1 → 4.1.1

package/dist/ai/docs/Tag.md

@@ -1,224 +0,0 @@
----
-title: Tag
-description: A label/badge component for displaying metadata, status, or categorization information.
-package: "@g4rcez/components"
-export: "{ Tag }"
-import: "import { Tag } from '@g4rcez/components/tag'"
-category: core
----
-
-# Tag
-
-A versatile label/badge component for displaying metadata, status, or categorization information. Built with polymorphic capabilities and multiple visual variants.
-
-## Import
-
-```tsx
-import { Tag } from "@g4rcez/components/tag";
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `theme` | `"primary" \| "secondary" \| "info" \| "warn" \| "danger" \| "success" \| "muted" \| "neutral" \| "custom" \| "disabled" \| "loading"` | `"primary"` | Visual theme/variant of the tag |
-| `size` | `"icon" \| "small" \| "default" \| "big" \| "tiny"` | `"default"` | Size of the tag |
-| `icon` | `React.ReactNode` | - | Icon to display inside the tag |
-| `indicator` | `"primary" \| "secondary" \| "info" \| "warn" \| "danger" \| "success" \| "muted" \| "neutral"` | - | Shows a small colored dot before the label |
-| `loading` | `boolean` | `false` | Overrides theme with pulse animation |
-| `as` | `React.ElementType` | `"span"` | HTML element to render as |
-| `className` | `string` | - | Additional CSS classes |
-| `children` | `React.ReactNode` | - | Tag content |
-
-## Design Tokens
-
-Tokens this component reads. Customize by overriding these CSS variables in your theme.
-
-| Token | CSS Variable | Purpose |
-|-------|-------------|---------|
-| `bg-tag-primary-bg` | `--tag-primary-bg` | Background for primary theme |
-| `text-tag-primary-text` | `--tag-primary-text` | Text color for primary theme |
-| `bg-tag-secondary-bg` | `--tag-secondary-bg` | Background for secondary theme |
-| `text-tag-secondary-text` | `--tag-secondary-text` | Text color for secondary theme |
-| `bg-tag-info-bg` | `--tag-info-bg` | Background for info theme |
-| `text-tag-info-text` | `--tag-info-text` | Text color for info theme |
-| `bg-tag-warn-bg` | `--tag-warn-bg` | Background for warn theme |
-| `text-tag-warn-text` | `--tag-warn-text` | Text color for warn theme |
-| `bg-tag-danger-bg` | `--tag-danger-bg` | Background for danger theme |
-| `text-tag-danger-text` | `--tag-danger-text` | Text color for danger theme |
-| `bg-tag-success-bg` | `--tag-success-bg` | Background for success theme |
-| `text-tag-success-text` | `--tag-success-text` | Text color for success theme |
-| `bg-tag-muted-bg` | `--tag-muted-bg` | Background for muted theme |
-| `text-tag-muted-text` | `--tag-muted-text` | Text color for muted theme |
-| `bg-disabled` | `--disabled` | Background for disabled/loading states |
-| `border-card-border` | `--card-border` | Border color for neutral theme |
-| `rounded-pill` | `--radius-pill` | Pill border radius applied to all tags |
-| `bg-primary` | `--primary` | Dot color for primary indicator |
-| `bg-secondary` | `--secondary` | Dot color for secondary indicator |
-| `bg-info` | `--info` | Dot color for info indicator |
-| `bg-warn` | `--warn` | Dot color for warn indicator |
-| `bg-danger` | `--danger` | Dot color for danger indicator |
-| `bg-success` | `--success` | Dot color for success indicator |
-| `bg-muted` | `--muted` | Dot color for muted indicator |
-
-## Theme Variants
-
-- `primary`: Primary brand color
-- `secondary`: Secondary color scheme
-- `info`: Informational styling
-- `warn`: Warning/caution styling
-- `danger`: Error/destructive styling
-- `success`: Success/positive styling
-- `muted`: Subtle/subdued styling
-- `neutral`: Transparent with card border
-- `custom`: No default styling — supply all classes via `className`
-- `disabled`: Disabled appearance with reduced opacity
-- `loading`: Pulse animation (also triggered by the `loading` boolean prop)
-
-## Examples
-
-### Basic Variants
-
-```tsx
-<Tag theme="primary">Primary</Tag>
-<Tag theme="secondary">Secondary</Tag>
-<Tag theme="info">Info</Tag>
-<Tag theme="warn">Warning</Tag>
-<Tag theme="danger">Error</Tag>
-<Tag theme="success">Success</Tag>
-<Tag theme="muted">Muted</Tag>
-<Tag theme="neutral">Neutral</Tag>
-```
-
-### Sizes
-
-```tsx
-<Tag size="small">Small</Tag>
-<Tag size="default">Default</Tag>
-<Tag size="big">Big</Tag>
-```
-
-### With Icons
-
-```tsx
-import { StarIcon, CheckIcon } from "@phosphor-icons/react";
-
-<Tag icon={<StarIcon size={14} />} theme="warn">Featured</Tag>
-<Tag icon={<CheckIcon size={14} />} theme="success">Completed</Tag>
-```
-
-### With Indicators
-
-```tsx
-<Tag indicator="success">Online</Tag>
-<Tag indicator="danger">Offline</Tag>
-<Tag indicator="warn">Pending</Tag>
-```
-
-### Status Tags
-
-```tsx
-const statusMap: Record<string, { theme: "success" | "warn" | "muted" | "danger" }> = {
-  active:   { theme: "success" },
-  pending:  { theme: "warn" },
-  inactive: { theme: "muted" },
-  error:    { theme: "danger" },
-};
-
-const StatusTag = ({ status }: { status: string }) => {
-  const config = statusMap[status] ?? statusMap.inactive;
-  return (
-    <Tag theme={config.theme} indicator={config.theme}>
-      {status.charAt(0).toUpperCase() + status.slice(1)}
-    </Tag>
-  );
-};
-```
-
-### Loading State
-
-```tsx
-<Tag loading theme="primary">Processing...</Tag>
-```
-
-### Polymorphic Usage
-
-```tsx
-<Tag as="button" onClick={() => void 0} theme="primary">
-  Clickable Tag
-</Tag>
-
-<Tag as="a" href="/category/react" theme="info">
-  React
-</Tag>
-```
-
-### Content Categorization
-
-```tsx
-const categories = [
-  { name: "React",      theme: "info"    },
-  { name: "TypeScript", theme: "primary" },
-  { name: "CSS",        theme: "success" },
-];
-
-<div className="flex gap-2 flex-wrap">
-  {categories.map((cat) => (
-    <Tag key={cat.name} theme={cat.theme as any}>
-      {cat.name}
-    </Tag>
-  ))}
-</div>
-```
-
-### Notification Badge
-
-```tsx
-import { BellIcon } from "@phosphor-icons/react";
-
-<div className="relative">
-  <BellIcon size={24} />
-  <Tag
-    size="small"
-    theme="danger"
-    className="absolute -top-2 -right-2 min-w-[20px] h-5 text-xs"
-  >
-    3
-  </Tag>
-</div>
-```
-
-## Do
-
-- Use `theme="success"` for positive states and `theme="danger"` for errors — keep it consistent
-- Keep tag labels short and scannable
-- Use `indicator` to add extra color meaning without extra text
-- Use `as="button"` when the tag performs an action (e.g., removing a filter)
-- Use design-token classes for wrapper elements (`bg-muted`, `border-border`)
-
-## Don't
-
-- Don't pass raw Tailwind color classes (`bg-blue-500`, `text-white`) — use `theme` prop instead
-- Don't use arbitrary Tailwind values (`bg-[#abc]`, `bg-[--my-var]`) — override CSS variables in your `@theme` block
-- Don't use too many different themes on one screen — excessive color variety is distracting
-- Don't use `Tag` as a replacement for `Button` on primary actions
-- Don't combine `icon` and `indicator` on a small tag — it becomes too visually busy
-
-## Accessibility
-
-- Uses semantic HTML via the `as` prop (defaults to `<span>`)
-- The indicator dot is `aria-hidden="true"` — it is purely decorative
-- When used as a `button` or `a`, standard keyboard navigation applies
-- Ensure color meaning is supplemented by text — do not rely on color alone
-
-## Data Attributes
-
-- `data-component="tag"`: Identifies the component for styling/testing
-- `data-theme`: Current theme variant value
-
-## Notes
-
-- The `loading` prop overrides the `theme` value and applies the loading animation
-- Once `loading` becomes `false`, the original `theme` is restored
-- The component forwards refs to the underlying element
-- All standard HTML attributes for the target element are forwarded

package/dist/ai/docs/Textarea.md

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

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