@g4rcez/components 4.0.1 → 4.1.1

package/ai/docs/Card.md

@@ -0,0 +1,178 @@
+---
+title: Card
+description: Polymorphic container for grouping related content with optional title header, loading state, and composable sub-components.
+package: "@g4rcez/components"
+export: "{ Card }"
+import: "import { Card } from '@g4rcez/components/card'"
+category: display
+---
+
+# Card
+
+Polymorphic container for grouping related content with optional title header, loading state, and composable sub-components.
+
+## Import
+
+```tsx
+import { Card } from "@g4rcez/components/card";
+```
+
+## Props
+
+### Card
+
+| Prop             | Type                         | Default | Description                                       |
+| ---------------- | ---------------------------- | ------- | ------------------------------------------------- |
+| `title`          | `React.ReactNode`            | —       | Renders an automatic header with border separator |
+| `loading`        | `boolean`                    | —       | Replaces content with animated skeleton lines     |
+| `titleClassName` | `string`                     | `""`    | Additional classes for the title header element   |
+| `header`         | `React.ReactElement \| null` | `null`  | Custom header element; overrides `title`          |
+| `container`      | `string`                     | `""`    | Additional classes for the outer card element     |
+| `as`             | `React.ElementType`          | `"div"` | Polymorphic root element                          |
+| `className`      | `string`                     | `""`    | Additional classes for the card body element      |
+| `children`       | `React.ReactNode`            | —       | Card body content                                 |
+
+### Card.Title
+
+A composable header with a title and an optional navigation/action area.
+
+| Prop       | Type                           | Default | Description                                     |
+| ---------- | ------------------------------ | ------- | ----------------------------------------------- |
+| `title`    | `React.ReactElement \| string` | —       | Title content                                   |
+| `titleTag` | `React.ElementType`            | `"h2"`  | Element type for the title                      |
+| `navTag`   | `React.ElementType`            | `"nav"` | Element type for the actions wrapper            |
+| `as`       | `React.ElementType`            | `"div"` | Element type for the container                  |
+| `children` | `React.ReactNode`              | —       | Action elements rendered in the navigation area |
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token                | CSS Variable        | Purpose                         |
+| -------------------- | ------------------- | ------------------------------- |
+| `bg-card-background` | `--card-background` | Card surface color              |
+| `border-card-border` | `--card-border`     | Card border and title separator |
+| `rounded-card`       | `--radius-card`     | Corner radius                   |
+| `shadow-shadow-card` | `--shadow-card`     | Card drop shadow                |
+| `bg-muted`           | `--muted`           | Skeleton loading lines          |
+
+## Examples
+
+### Basic Card
+
+```tsx
+<Card>
+    <p>Card content goes here.</p>
+</Card>
+```
+
+### Card with Title
+
+```tsx
+<Card title="User Profile">
+    <div className="space-y-4">
+        <p>Name: John Doe</p>
+        <p>Email: john@example.com</p>
+    </div>
+</Card>
+```
+
+### Card with Loading State
+
+```tsx
+<Card title="Analytics" loading={isLoading}>
+    <p>Loaded content rendered here when not loading.</p>
+</Card>
+```
+
+### Card.Title with Actions
+
+```tsx
+import { Button } from "@g4rcez/components/button";
+
+<Card>
+    <Card.Title title="Project Overview">
+        <Button theme="primary" size="small">
+            Edit
+        </Button>
+        <Button theme="neutral" size="small">
+            Share
+        </Button>
+    </Card.Title>
+
+    <p>Project description and details.</p>
+</Card>;
+```
+
+### Custom Header
+
+```tsx
+<Card
+    header={
+        <header className="flex justify-between items-center p-4 border-b border-card-border">
+            <h2 className="text-foreground font-semibold">Custom Header</h2>
+        </header>
+    }
+>
+    <p>Content with a completely custom header.</p>
+</Card>
+```
+
+### Nested Cards
+
+```tsx
+<Card title="Dashboard">
+    <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+        <Card title="Statistics">
+            <p>Chart content here</p>
+        </Card>
+        <Card title="Recent Activity">
+            <ul>
+                <li>User logged in</li>
+                <li>New order received</li>
+            </ul>
+        </Card>
+    </div>
+</Card>
+```
+
+### Semantic Element
+
+```tsx
+<Card as="article" title="Blog Post">
+    <p>Blog post content.</p>
+</Card>
+```
+
+## Do
+
+- Use `title` or `Card.Title` to give cards a clear, descriptive heading.
+- Use `as="article"` or `as="section"` when semantics matter.
+- Use `loading={true}` while data is fetching to prevent layout shift.
+- Maintain consistent spacing between multiple cards in a grid using gap utilities.
+- Use design-token classes for wrapper elements (`bg-background`, `border-border`).
+
+## Don't
+
+- Don't pass raw Tailwind color classes (`bg-blue-500`, `text-white`, `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 instead.
+- Don't over-nest cards; multiple borders and shadows create visual clutter.
+- Don't put more than one primary action in a single `Card.Title` — keep actions focused.
+
+## Accessibility
+
+- Uses semantic HTML; `Card.Title` renders an `h2` by default (configurable via `titleTag`).
+- Polymorphic `as` prop allows correct element type for document structure.
+- Interactive elements within cards remain keyboard accessible.
+
+## Data Attributes
+
+- `data-component="card"` — outer card element.
+- `data-component="card-title"` — automatic title header.
+- `data-component="card-body"` — card body wrapper.
+
+## Notes
+
+- When both `title` and `header` are provided, `title` takes precedence and `header` is ignored.
+- The `loading` prop replaces children with four `Skeleton` lines of varying widths.
+- `Card.Title` lays out title and actions responsively: stacked on mobile, inline on `sm+`.

package/ai/docs/Checkbox.md

@@ -0,0 +1,194 @@
+---
+title: Checkbox
+description: Styled checkbox with label support, task mode, error display, loading state, and size variants.
+package: "@g4rcez/components"
+export: "{ Checkbox }"
+import: "import { Checkbox } from '@g4rcez/components/checkbox'"
+category: form
+---
+
+# Checkbox
+
+Styled checkbox with label support, task mode, error display, loading state, and size variants.
+
+## Import
+
+```tsx
+import { Checkbox } from "@g4rcez/components/checkbox";
+```
+
+## Props
+
+| Prop             | Type                                               | Default    | Description                                                |
+| ---------------- | -------------------------------------------------- | ---------- | ---------------------------------------------------------- |
+| `checked`        | `boolean`                                          | -          | Controlled checked state                                   |
+| `onChange`       | `(e: React.ChangeEvent<HTMLInputElement>) => void` | -          | Change handler                                             |
+| `disabled`       | `boolean`                                          | `false`    | Disabled state                                             |
+| `loading`        | `boolean`                                          | `false`    | Loading state — disables the checkbox while loading        |
+| `error`          | `string`                                           | -          | Error message rendered below the label                     |
+| `asTask`         | `boolean`                                          | `false`    | Task mode: applies strikethrough to the label when checked |
+| `size`           | `"medium" \| "large"`                              | `"medium"` | Checkbox size                                              |
+| `container`      | `string`                                           | -          | Extra CSS classes for the outer `<label>` wrapper          |
+| `labelClassName` | `string`                                           | -          | Extra CSS classes for the error text element               |
+| `className`      | `string`                                           | -          | Extra CSS classes for the `<input>` element                |
+| `children`       | `React.ReactNode`                                  | -          | Label content                                              |
+| `...props`       | `React.InputHTMLAttributes<HTMLInputElement>`      | -          | All standard input attributes                              |
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token                | CSS Variable    | Purpose                              |
+| -------------------- | --------------- | ------------------------------------ |
+| `text-primary`       | `--primary`     | Checkbox accent / checked color      |
+| `border-card-border` | `--card-border` | Unchecked border color               |
+| `text-danger`        | `--danger`      | Error message text color             |
+| `text-disabled`      | `--disabled`    | Opacity and cursor on disabled state |
+| `focus:ring-primary` | `--primary`     | Focus ring color                     |
+
+## Variants
+
+### Size
+
+| Value      | Description                           |
+| ---------- | ------------------------------------- |
+| `"medium"` | Default size — 1rem × 1rem (`size-4`) |
+| `"large"`  | Larger touch target                   |
+
+### Task mode
+
+When `asTask={true}`, the label text receives a strikethrough style when the checkbox is checked. This is intended for to-do lists and task management UIs.
+
+## Examples
+
+### Basic checkbox
+
+```tsx
+const [accepted, setAccepted] = useState(false);
+
+<Checkbox checked={accepted} onChange={(e) => setAccepted(e.target.checked)}>
+    I accept the terms and conditions
+</Checkbox>;
+```
+
+### Checkbox with error
+
+```tsx
+const [agreed, setAgreed] = useState(false);
+const [error, setError] = useState("");
+
+<Checkbox
+    checked={agreed}
+    onChange={(e) => {
+        setAgreed(e.target.checked);
+        if (e.target.checked) setError("");
+    }}
+    error={error}
+>
+    I agree to the privacy policy
+</Checkbox>;
+```
+
+### Task list
+
+```tsx
+const [tasks, setTasks] = useState([
+    { id: 1, text: "Write release notes", done: false },
+    { id: 2, text: "Merge pull request", done: true },
+]);
+
+<div className="flex flex-col gap-sm">
+    {tasks.map((task) => (
+        <Checkbox
+            key={task.id}
+            checked={task.done}
+            onChange={() => setTasks((prev) => prev.map((t) => (t.id === task.id ? { ...t, done: !t.done } : t)))}
+            asTask
+        >
+            {task.text}
+        </Checkbox>
+    ))}
+</div>;
+```
+
+### Loading state
+
+```tsx
+const [loading, setLoading] = useState(false);
+const [subscribed, setSubscribed] = useState(false);
+
+const handleChange = async (checked: boolean) => {
+    setLoading(true);
+    await updateSubscription(checked);
+    setSubscribed(checked);
+    setLoading(false);
+};
+
+<Checkbox checked={subscribed} onChange={(e) => handleChange(e.target.checked)} loading={loading}>
+    Subscribe to newsletter
+</Checkbox>;
+```
+
+### Notification preferences form
+
+```tsx
+function PreferencesForm() {
+    const [prefs, setPrefs] = useState({
+        email: false,
+        push: true,
+        sms: false,
+    });
+
+    const toggle = (key: keyof typeof prefs) => (e: React.ChangeEvent<HTMLInputElement>) =>
+        setPrefs((prev) => ({ ...prev, [key]: e.target.checked }));
+
+    return (
+        <form className="flex flex-col gap-sm">
+            <Checkbox checked={prefs.email} onChange={toggle("email")}>
+                Email notifications
+            </Checkbox>
+            <Checkbox checked={prefs.push} onChange={toggle("push")}>
+                Push notifications
+            </Checkbox>
+            <Checkbox checked={prefs.sms} onChange={toggle("sms")}>
+                SMS notifications
+            </Checkbox>
+        </form>
+    );
+}
+```
+
+## Do
+
+- Use descriptive, actionable labels so users know exactly what they are agreeing to or enabling.
+- Group related checkboxes visually to signal they form a set.
+- Use `asTask` for items in a to-do list or task-tracking UI.
+- Provide an `error` message when the checkbox is part of required validation (e.g., accepting terms).
+
+## Don't
+
+- Don't pass raw Tailwind color classes (`bg-blue-500`, `text-white`, `border-gray-300`) — use theme props or design tokens instead.
+- Don't use arbitrary Tailwind values (`bg-[#abc]`, `bg-[--my-var]`) — override CSS variables in your `@theme` block instead.
+- Don't use `Checkbox` to trigger an immediate action — use a `Button` or `Switch` instead.
+- Don't use checkboxes for mutually exclusive choices — use `Radiobox` instead.
+
+## Accessibility
+
+- Renders a native `<input type="checkbox">` for full browser and screen reader support.
+- The outer `<label>` wraps both the input and the label text, so clicking anywhere on the label toggles the checkbox.
+- `aria-disabled` and `data-disabled` are applied when `disabled` or `loading` is true.
+- Error messages are rendered as visible text below the label and are discoverable by screen readers.
+- Focus ring is visible for keyboard navigation.
+
+## Data Attributes
+
+- `data-component="checkbox"` — on the outer `<label>`.
+- `data-task` — reflects the `asTask` prop value.
+- `data-disabled` — reflects the effective disabled state (`disabled || loading`).
+- `data-name="checkbox-label"` — on the error text `<span>`.
+
+## Notes
+
+- `loading` sets `disabled` on the underlying input. The two states share the same visual treatment.
+- The component forwards its ref to the `<input>` element.
+- All standard `HTMLInputElement` attributes are forwarded to the native input, so you can use `name`, `value`, `required`, `defaultChecked`, and so on.

package/ai/docs/CommandPalette.md

@@ -0,0 +1,275 @@
+---
+title: CommandPalette
+description: Searchable command palette with fuzzy search, keyboard shortcuts, and grouped commands.
+package: "@g4rcez/components"
+export: "{ CommandPalette }"
+import: "import { CommandPalette } from '@g4rcez/components'"
+category: floating
+---
+
+# CommandPalette
+
+Searchable command palette with fuzzy search, keyboard shortcuts, and grouped commands.
+
+## Import
+
+```tsx
+import { CommandPalette } from "@g4rcez/components";
+```
+
+## Props
+
+| Prop                 | Type                                                                   | Default     | Description                                    |
+| -------------------- | ---------------------------------------------------------------------- | ----------- | ---------------------------------------------- |
+| `open`               | `boolean`                                                              | —           | Controlled open state                          |
+| `commands`           | `CommandItemTypes[]`                                                   | —           | Array of commands to display                   |
+| `onChangeVisibility` | `(next: boolean) => void`                                              | —           | Open/close handler                             |
+| `bind`               | `string`                                                               | `"Mod + k"` | Global keyboard shortcut to open the palette   |
+| `loading`            | `boolean`                                                              | `false`     | Show loading skeleton while commands load      |
+| `emptyMessage`       | `Label`                                                                | —           | Message shown when no results match            |
+| `footer`             | `React.ReactElement`                                                   | —           | Custom footer content                          |
+| `onChangeText`       | `(text: string) => void`                                               | —           | Search text change handler                     |
+| `Preview`            | `React.FC<{ command: CommandItemTypes; text: string }>`                | —           | Preview panel component for the active command |
+| `Icon`               | `React.FC<IconProps & { text: string; Default: React.FC<IconProps> }>` | —           | Custom search icon                             |
+
+## Command Types
+
+### CommandShortcutItem
+
+```tsx
+type CommandShortcutItem = {
+    type: "shortcut";
+    title: string | ((props: { text: string }) => string);
+    hint?: string | string[];
+    shortcut?: string;
+    Icon?: React.ReactElement;
+    enabled?: boolean | ((props: { text: string }) => boolean);
+    action: (args: {
+        text: string;
+        setText: (state: string) => void;
+        setOpen: (state: boolean) => void;
+        event: KeyboardEvent | React.MouseEvent | React.KeyboardEvent;
+    }) => void | Promise<void>;
+};
+```
+
+### CommandGroupItem
+
+```tsx
+type CommandGroupItem = {
+    type: "group";
+    title: string | ((props: { text: string }) => string);
+    items: CommandItemTypes[];
+};
+```
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token                    | CSS Variable            | Purpose                                |
+| ------------------------ | ----------------------- | -------------------------------------- |
+| `bg-floating-background` | `--floating-background` | Palette surface background             |
+| `border-floating-border` | `--floating-border`     | Palette surface border                 |
+| `bg-floating-hover`      | `--floating-hover`      | Hovered/active command item background |
+| `z-floating`             | `--z-floating`          | Z-index for the search header          |
+| `text-secondary`         | `--secondary`           | Group label and empty state text color |
+
+## Examples
+
+### Basic Command Palette
+
+```tsx
+import { useState } from "react";
+import { FileTextIcon, FloppyDiskIcon, FolderOpenIcon } from "@phosphor-icons/react";
+import { CommandPalette } from "@g4rcez/components";
+
+function BasicCommandPalette() {
+    const [open, setOpen] = useState(false);
+
+    const commands = [
+        {
+            type: "shortcut" as const,
+            title: "New Document",
+            shortcut: "Ctrl+N",
+            Icon: <FileTextIcon size={16} />,
+            action: ({ setOpen }) => {
+                console.log("Creating new document");
+                setOpen(false);
+            },
+        },
+        {
+            type: "shortcut" as const,
+            title: "Save Document",
+            shortcut: "Ctrl+S",
+            Icon: <FloppyDiskIcon size={16} />,
+            action: ({ setOpen }) => {
+                console.log("Saving document");
+                setOpen(false);
+            },
+        },
+        {
+            type: "shortcut" as const,
+            title: "Open File",
+            shortcut: "Ctrl+O",
+            Icon: <FolderOpenIcon size={16} />,
+            action: ({ setOpen }) => {
+                console.log("Opening file");
+                setOpen(false);
+            },
+        },
+    ];
+
+    return <CommandPalette open={open} commands={commands} onChangeVisibility={setOpen} />;
+}
+```
+
+### Grouped Commands
+
+```tsx
+import { FileIcon, FolderOpenIcon, HouseIcon, GearIcon, MoonIcon } from "@phosphor-icons/react";
+import { CommandPalette } from "@g4rcez/components";
+
+function GroupedCommandPalette() {
+    const [open, setOpen] = useState(false);
+
+    const commands = [
+        {
+            type: "group" as const,
+            title: "File Operations",
+            items: [
+                {
+                    type: "shortcut" as const,
+                    title: "New File",
+                    hint: ["create", "new", "file"],
+                    shortcut: "Ctrl+N",
+                    Icon: <FileIcon size={16} />,
+                    action: ({ setOpen }) => setOpen(false),
+                },
+                {
+                    type: "shortcut" as const,
+                    title: "Open File",
+                    hint: ["open", "load"],
+                    shortcut: "Ctrl+O",
+                    Icon: <FolderOpenIcon size={16} />,
+                    action: ({ setOpen }) => setOpen(false),
+                },
+            ],
+        },
+        {
+            type: "group" as const,
+            title: "Navigation",
+            items: [
+                {
+                    type: "shortcut" as const,
+                    title: "Go to Dashboard",
+                    hint: ["dashboard", "home", "main"],
+                    Icon: <HouseIcon size={16} />,
+                    action: ({ setOpen }) => {
+                        window.location.href = "/dashboard";
+                        setOpen(false);
+                    },
+                },
+                {
+                    type: "shortcut" as const,
+                    title: "Go to Settings",
+                    hint: ["settings", "preferences", "config"],
+                    Icon: <GearIcon size={16} />,
+                    action: ({ setOpen }) => {
+                        window.location.href = "/settings";
+                        setOpen(false);
+                    },
+                },
+            ],
+        },
+        {
+            type: "group" as const,
+            title: "Theme",
+            items: [
+                {
+                    type: "shortcut" as const,
+                    title: "Toggle Dark Mode",
+                    hint: ["dark", "theme", "mode"],
+                    Icon: <MoonIcon size={16} />,
+                    action: ({ setOpen }) => {
+                        document.documentElement.classList.toggle("dark");
+                        setOpen(false);
+                    },
+                },
+            ],
+        },
+    ];
+
+    return <CommandPalette open={open} commands={commands} onChangeVisibility={setOpen} emptyMessage="No commands found" />;
+}
+```
+
+### Custom Keyboard Shortcut
+
+```tsx
+<CommandPalette open={open} commands={commands} onChangeVisibility={setOpen} bind="Mod + /" />
+```
+
+### Conditional Commands
+
+```tsx
+import { UserIcon, ShieldIcon } from "@phosphor-icons/react";
+
+const commands = [
+    {
+        type: "shortcut" as const,
+        title: "User Dashboard",
+        Icon: <UserIcon size={16} />,
+        action: ({ setOpen }) => setOpen(false),
+    },
+    {
+        type: "shortcut" as const,
+        title: "Admin Panel",
+        enabled: user.isAdmin,
+        Icon: <ShieldIcon size={16} />,
+        action: ({ setOpen }) => {
+            console.log("Opening admin panel");
+            setOpen(false);
+        },
+    },
+];
+```
+
+## Do
+
+- Use `hint` arrays to add synonyms so commands match varied search terms (e.g., `["preferences", "config"]` for a "Settings" command).
+- Group related commands with `type: "group"` so users can scan results quickly.
+- Provide a clear `emptyMessage` so users know when nothing matches.
+- Keep command titles short; let `hint` carry the synonym load.
+
+## Don't
+
+- Don't put every action in the palette — focus on the most useful commands.
+- Don't use raw Tailwind color classes (`bg-blue-500`, `text-white`) in custom `Icon` or `Preview` components — use design-token classes instead.
+- Don't pass arbitrary Tailwind values (`bg-[#abc]`, `z-[9999]`) — override CSS variables in your `@theme` block.
+- Don't omit the global shortcut — the default `Mod+K` is a strong convention users expect.
+
+## Accessibility
+
+- Full arrow-key navigation within the list with loop support.
+- `Enter` executes the active command; `Escape` closes the palette.
+- Each item renders with `role="option"` and `aria-selected` reflecting the active state.
+- The palette is wrapped in a `Modal` with `ariaTitle="Command palette"` for screen readers.
+- The search input receives `autoFocus` when the palette opens.
+
+## Data Attributes
+
+| Attribute                                    | Applied to           | Description                           |
+| -------------------------------------------- | -------------------- | ------------------------------------- |
+| `data-component="command-palette"`           | Root modal container | Identifies the palette root           |
+| `data-component="command-palette-list"`      | `<ul>`               | Identifies the command list           |
+| `data-component="command-palette-item"`      | Each `<button>` item | Identifies individual command buttons |
+| `data-component="command-palette-container"` | List/preview wrapper | Identifies the content area           |
+
+## Notes
+
+- The component registers global keyboard listeners via `CombiKeys`. All `shortcut` commands are also registered as global hotkeys — they fire even when the palette is closed.
+- Fuzzy search runs over `title`, `shortcut`, and `hint` fields. When `title` is a function, it is called with the current search text to produce a string for matching.
+- Commands with `enabled: false` (or a function returning `false`) are filtered out of results.
+- The `Preview` panel is shown only when `activeIndex` is set and a `Preview` component is provided.
+- The palette is built on top of `Modal`, so it inherits modal accessibility and portal rendering.