@g4rcez/components 3.0.0 → 3.0.1

package/dist/ai/docs/Card.md

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

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

@@ -0,0 +1,293 @@
+---
+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<LucideProps & { text: string; Default: React.FC<LucideProps> }>` | — | 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, SaveIcon, FolderOpenIcon } from "lucide-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: <SaveIcon 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, HomeIcon, SettingsIcon, MoonIcon } from "lucide-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: <HomeIcon size={16} />,
+          action: ({ setOpen }) => {
+            window.location.href = "/dashboard";
+            setOpen(false);
+          },
+        },
+        {
+          type: "shortcut" as const,
+          title: "Go to Settings",
+          hint: ["settings", "preferences", "config"],
+          Icon: <SettingsIcon 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 "lucide-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.