@g4rcez/components 3.0.0 → 3.0.1

package/dist/ai/docs/Tag.md

@@ -0,0 +1,224 @@
+---
+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 "lucide-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 "lucide-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/TaskList.md

@@ -0,0 +1,144 @@
+---
+title: TaskList
+description: Fieldset container that triggers a celebratory animation when all child tasks are checked.
+package: "@g4rcez/components"
+export: "{ TaskList }"
+import: "import { TaskList } from '@g4rcez/components/task-list'"
+category: form
+---
+
+# TaskList
+
+Fieldset container that triggers a celebratory animation when all child tasks are checked.
+
+## Import
+
+```tsx
+import { TaskList } from "@g4rcez/components/task-list";
+import { Checkbox } from "@g4rcez/components/checkbox";
+```
+
+## Props
+
+Accepts all standard HTML `<fieldset>` attributes.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | — | `Checkbox` components with the `asTask` prop. |
+| `className` | `string` | — | Additional CSS classes for the `<fieldset>`. |
+
+## Design Tokens
+
+`TaskList` itself is a plain `<fieldset>` and inherits ambient tokens from its children. No component-scoped tokens are consumed directly. Style the container using semantic tokens:
+
+| Token | CSS Variable | Purpose |
+|-------|-------------|---------|
+| `border-border` | `--border` | Optional border around the task group |
+| `bg-background` | `--background` | Container background |
+| `text-foreground` | `--foreground` | Task label text |
+
+## Examples
+
+### Basic task list
+
+```tsx
+import { TaskList } from "@g4rcez/components/task-list";
+import { Checkbox } from "@g4rcez/components/checkbox";
+
+export default function OnboardingChecklist() {
+  return (
+    <TaskList className="flex flex-col gap-sm border border-border rounded-card p-4">
+      <Checkbox asTask>Complete initial setup</Checkbox>
+      <Checkbox asTask>Upload profile picture</Checkbox>
+      <Checkbox asTask>Verify email address</Checkbox>
+    </TaskList>
+  );
+}
+```
+
+### Dynamic tasks from state
+
+```tsx
+import { useState } from "react";
+import { TaskList } from "@g4rcez/components/task-list";
+import { Checkbox } from "@g4rcez/components/checkbox";
+
+type Task = { id: string; text: string; done: boolean };
+
+export default function DynamicTaskList({ tasks }: { tasks: Task[] }) {
+  const [items, setItems] = useState(tasks);
+
+  const toggle = (id: string) =>
+    setItems((prev) =>
+      prev.map((t) => (t.id === id ? { ...t, done: !t.done } : t))
+    );
+
+  return (
+    <TaskList className="flex flex-col gap-sm">
+      {items.map((task) => (
+        <Checkbox
+          key={task.id}
+          asTask
+          checked={task.done}
+          onChange={() => toggle(task.id)}
+        >
+          {task.text}
+        </Checkbox>
+      ))}
+    </TaskList>
+  );
+}
+```
+
+### Grouped tasks with a legend
+
+```tsx
+import { TaskList } from "@g4rcez/components/task-list";
+import { Checkbox } from "@g4rcez/components/checkbox";
+
+export default function ProjectSubtasks() {
+  return (
+    <TaskList className="flex flex-col gap-sm rounded-card border border-border p-4">
+      <legend className="px-1 text-sm font-medium text-foreground">
+        Phase 1 — Design
+      </legend>
+      <Checkbox asTask>Create wireframes</Checkbox>
+      <Checkbox asTask>Review with stakeholders</Checkbox>
+      <Checkbox asTask>Export design tokens</Checkbox>
+    </TaskList>
+  );
+}
+```
+
+## Do
+
+- Use `asTask` on every `Checkbox` inside `TaskList` so they are counted for the completion animation.
+- Group closely related tasks — the animation is most meaningful when all items belong to one milestone.
+- Provide adequate vertical spacing between items (`gap-sm`, `gap-base`) for readability.
+- Use design-token classes for wrappers (`bg-background`, `border-border`, `rounded-card`).
+
+## Don't
+
+- Don't use `TaskList` for checkboxes that are not tasks (e.g., bulk-selection rows in a table).
+- Don't pack too many unrelated tasks into a single list; split them into smaller groups.
+- Don't pass raw Tailwind color classes (`bg-gray-100`, `border-gray-300`) — use design tokens instead.
+- Don't use arbitrary Tailwind values (`bg-[#abc]`) — override CSS variables in your `@theme` block instead.
+
+## Accessibility
+
+- Renders a semantic `<fieldset>` to group related inputs — pair with a `<legend>` for a fully accessible group label.
+- Inherits all accessibility features of the underlying `Checkbox` component.
+- The completion animation (scale + rotate) is visual-only and does not alter keyboard or screen-reader behavior.
+
+## Data Attributes
+
+| Attribute | Element | Value | Description |
+|-----------|---------|-------|-------------|
+| `data-component` | `fieldset` | `"task-list"` | Identifies the component. |
+| `data-task` | child `input` | `"true"` | Must be present on child checkbox inputs for them to be counted in the completion check. Set automatically via `asTask`. |
+
+## Notes
+
+- The animation is powered by `motion/react`. When all `input[data-task=true]` elements inside the fieldset are checked, a staggered scale + rotate animation fires starting from the last-checked item's index.
+- `TaskList` attaches a single `change` event listener on the `<fieldset>` (event delegation) — no per-item wiring is required.
+- The animation runs once per "all complete" event; unchecking an item and re-checking to completion will replay it.

package/dist/ai/docs/Textarea.md

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