@g4rcez/components 4.0.1 → 4.1.1

package/ai/docs/Tabs.md

@@ -0,0 +1,191 @@
+---
+title: Tabs
+description: Keyboard-accessible tab container for organizing content into switchable panels.
+package: "@g4rcez/components"
+export: "{ Tabs }"
+import: "import { Tabs, Tab } from '@g4rcez/components/tabs'"
+category: display
+---
+
+# Tabs
+
+Keyboard-accessible tab container for organizing content into switchable panels.
+
+## Import
+
+```tsx
+import { Tabs, Tab } from "@g4rcez/components/tabs";
+```
+
+## Props
+
+### Tabs (Container)
+
+| Prop        | Type                   | Default | Description                                         |
+| ----------- | ---------------------- | ------- | --------------------------------------------------- |
+| `active`    | `string`               | —       | ID of the currently active tab                      |
+| `onChange`  | `(id: string) => void` | —       | Called when the active tab changes                  |
+| `container` | `string`               | —       | Additional classes for the outer card container     |
+| `className` | `string`               | —       | Additional classes for the card body (content area) |
+| `children`  | `Tab[]`                | —       | `Tab` panel components                              |
+
+### Tab (Panel)
+
+| Prop       | Type              | Default | Description                                                     |
+| ---------- | ----------------- | ------- | --------------------------------------------------------------- |
+| `id`       | `string`          | —       | Unique identifier; matched against `Tabs.active`                |
+| `title`    | `string`          | —       | Tab button label (use when label is a plain string)             |
+| `label`    | `string`          | —       | Accessible label when `title` is a non-string React element     |
+| `disabled` | `boolean`         | `false` | Disables the tab button and skips it during keyboard navigation |
+| `children` | `React.ReactNode` | —       | Panel content rendered when this tab is active                  |
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token                | CSS Variable        | Purpose                             |
+| -------------------- | ------------------- | ----------------------------------- |
+| `bg-card-background` | `--card-background` | Tab panel surface                   |
+| `border-card-border` | `--card-border`     | Tab bar bottom line and card border |
+| `border-primary`     | `--primary`         | Active tab bottom indicator         |
+| `text-primary`       | `--primary`         | Active tab text color               |
+| `text-disabled`      | `--disabled`        | Disabled tab text                   |
+
+## Examples
+
+### Basic Tabs
+
+```tsx
+const [active, setActive] = useState("overview");
+
+<Tabs active={active} onChange={setActive}>
+    <Tab id="overview" title="Overview">
+        <h3>Project Overview</h3>
+        <p>This is the overview of your project.</p>
+    </Tab>
+
+    <Tab id="details" title="Details">
+        <h3>Project Details</h3>
+        <p>Detailed information about your project.</p>
+    </Tab>
+
+    <Tab id="settings" title="Settings">
+        <h3>Project Settings</h3>
+        <p>Configure your project settings here.</p>
+    </Tab>
+</Tabs>;
+```
+
+### Tabs with Disabled State
+
+```tsx
+<Tabs active={activeTab} onChange={setActiveTab}>
+    <Tab id="available" title="Available">
+        <p>This tab is available.</p>
+    </Tab>
+
+    <Tab id="locked" title="Locked" disabled>
+        <p>This content is not accessible yet.</p>
+    </Tab>
+
+    <Tab id="also-available" title="Also Available">
+        <p>This tab is also available.</p>
+    </Tab>
+</Tabs>
+```
+
+### Settings Panel
+
+```tsx
+<Tabs active={activeTab} onChange={setActiveTab}>
+    <Tab id="general" title="General">
+        <GeneralSettings />
+    </Tab>
+    <Tab id="privacy" title="Privacy">
+        <PrivacySettings />
+    </Tab>
+    <Tab id="notifications" title="Notifications">
+        <NotificationSettings />
+    </Tab>
+</Tabs>
+```
+
+### Dynamic Tabs
+
+```tsx
+function DynamicTabs() {
+    const [tabs, setTabs] = useState([
+        { id: "tab1", title: "Tab 1", content: "Content 1" },
+        { id: "tab2", title: "Tab 2", content: "Content 2" },
+    ]);
+    const [activeTab, setActiveTab] = useState("tab1");
+
+    const addTab = () => {
+        const newId = `tab${tabs.length + 1}`;
+        setTabs([...tabs, { id: newId, title: `Tab ${tabs.length + 1}`, content: `Content ${tabs.length + 1}` }]);
+        setActiveTab(newId);
+    };
+
+    return (
+        <div className="space-y-4">
+            <button onClick={addTab} className="px-3 py-1 bg-primary text-primary-foreground rounded-button">
+                Add Tab
+            </button>
+
+            <Tabs active={activeTab} onChange={setActiveTab}>
+                {tabs.map((tab) => (
+                    <Tab key={tab.id} id={tab.id} title={tab.title}>
+                        <p>{tab.content}</p>
+                    </Tab>
+                ))}
+            </Tabs>
+        </div>
+    );
+}
+```
+
+### Form Wizard with Disabled Steps
+
+```tsx
+<Tabs active={currentStep} onChange={setCurrentStep}>
+    <Tab id="step1" title="Personal Info">
+        <PersonalInfoForm />
+    </Tab>
+    <Tab id="step2" title="Address" disabled={!step1Complete}>
+        <AddressForm />
+    </Tab>
+    <Tab id="step3" title="Payment" disabled={!step2Complete}>
+        <PaymentForm />
+    </Tab>
+</Tabs>
+```
+
+## Do
+
+- Always set a default `active` tab to prevent an empty initial state.
+- Use clear, concise tab titles (one to three words).
+- Arrange tabs in a logical order matching the user's workflow.
+- Use `disabled` for tabs not yet accessible (e.g. incomplete wizard steps).
+- Use design-token classes for any custom styling (`bg-background`, `border-border`).
+
+## Don't
+
+- Don't pass raw Tailwind color classes (`bg-blue-50`, `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.
+- Don't use more than 6–8 tabs; prefer sidebar navigation for larger sets.
+- Don't use tabs for content that needs to be compared side-by-side.
+- Don't use tabs for primary page-level navigation; use a nav bar instead.
+
+## Accessibility
+
+- Tab buttons use `aria-current="page"` and `aria-disabled` for screen reader state.
+- Keyboard navigation: `ArrowLeft` / `ArrowRight` moves between tabs; `Tab` key focuses the header row.
+- Disabled tabs are skipped during arrow-key navigation.
+- Tab panels are only rendered when active (unmounted otherwise) — use this for performance but be aware that form state inside inactive panels is lost.
+
+## Notes
+
+- Only the active panel's `children` are rendered — inactive panels are unmounted.
+- The tab header list is horizontally scrollable on small screens (`overflow-x-auto`).
+- `Tabs` is built on top of `Card`, so it inherits card design tokens and the `container` / `className` props map to the card's `container` and `className` respectively.
+- If `active` does not match any `Tab` `id`, the component selects the first available non-disabled tab automatically.

package/ai/docs/Tag.md

@@ -0,0 +1,222 @@
+---
+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 → ai}/docs/TaskList.md

@@ -22,20 +22,20 @@ import { Checkbox } from "@g4rcez/components/checkbox";
 
 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>`. |
+| 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 |
+| 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
 
@@ -46,13 +46,13 @@ 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>
-  );
+    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>
+    );
 }
 ```
 
@@ -66,27 +66,19 @@ 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))
+    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>
     );
-
-  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>
-  );
 }
 ```
 
@@ -97,16 +89,14 @@ 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>
-  );
+    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>
+    );
 }
 ```
 
@@ -132,10 +122,10 @@ export default function ProjectSubtasks() {
 
 ## 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`. |
+| 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