@g4rcez/components 4.0.1 → 4.1.1

package/dist/ai/docs/Checkbox.md

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

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

package/dist/ai/docs/DatePicker.md

@@ -1,171 +0,0 @@
----
-title: DatePicker
-description: Date input with locale-aware masked entry and a floating calendar dropdown for visual selection.
-package: "@g4rcez/components"
-export: "{ DatePicker }"
-import: "import { DatePicker } from '@g4rcez/components/date-picker'"
-category: form
----
-
-# DatePicker
-
-Date input with locale-aware masked entry and a floating calendar dropdown for visual selection.
-
-## Import
-
-```tsx
-import { DatePicker } from "@g4rcez/components/date-picker";
-```
-
-## Props
-
-`DatePicker` inherits all `Input` and `Calendar` props. Notable additions:
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `date` | `Date` | - | Controlled selected date |
-| `type` | `"date" \| "datetime"` | `"date"` | Whether to include time (hour + minute) selection |
-| `floating` | `boolean` | `true` | Show the calendar in a floating `Dropdown`; set to `false` to embed it inline |
-| `clickToClose` | `boolean` | `false` | Close the calendar immediately after a date is picked |
-| `locale` | `Locales` | system locale | Locale for mask generation and calendar display |
-| `markToday` | `boolean` | `true` | Highlight today in the calendar |
-| `disabledDate` | `(date: Date) => boolean` | - | Callback that returns `true` for dates that should be unselectable |
-| `onChange` | `(date: Date \| undefined) => void` | - | Called with the new `Date` when input is valid, or `undefined` when cleared |
-| `title` | `string` | - | Field label |
-| `error` | `string` | - | Error message shown below the field |
-| `required` | `boolean` | `true` | Marks field as required (default is `true` for DatePicker) |
-| `name` | `string` | - | Form field name — also the `id` of the hidden `<input type="date">` |
-
-## Design Tokens
-
-Tokens this component reads. Customize by overriding these CSS variables in your theme.
-
-| Token | CSS Variable | Purpose |
-|-------|-------------|---------|
-| `h-input-height` | `--input-height` | Input height |
-| `px-input-x` | `--input-x` | Horizontal input padding |
-| `py-input-y` | `--input-y` | Vertical input padding |
-| `border-input-border` | `--input-border` | Default border color |
-| `text-foreground` | `--foreground` | Input text color |
-| `text-primary` | `--primary` | Focus ring and border on focus/hover |
-| `text-danger` | `--danger` | Error state text and border |
-| `placeholder-input-mask` | `--input-mask` | Placeholder text color |
-| `bg-floating-background` | `--floating-background` | Calendar dropdown background |
-| `border-floating-border` | `--floating-border` | Calendar dropdown border |
-
-## Examples
-
-### Basic date picker
-
-```tsx
-import { DatePicker } from "@g4rcez/components/date-picker";
-
-<DatePicker
-  name="birthdate"
-  title="Date of birth"
-/>
-```
-
-### Date and time
-
-```tsx
-<DatePicker
-  name="appointment"
-  title="Appointment time"
-  type="datetime"
-  clickToClose
-/>
-```
-
-### Disabling past dates
-
-```tsx
-import { isBefore, startOfDay } from "date-fns";
-
-<DatePicker
-  name="event_date"
-  title="Event date"
-  disabledDate={(date) => isBefore(date, startOfDay(new Date()))}
-/>
-```
-
-### Controlled value
-
-```tsx
-const [date, setDate] = useState<Date | undefined>();
-
-<DatePicker
-  name="due_date"
-  title="Due date"
-  date={date}
-  onChange={setDate}
-/>
-```
-
-### Inline calendar (no dropdown)
-
-```tsx
-<DatePicker
-  name="check_in"
-  title="Check-in"
-  floating={false}
-/>
-```
-
-### Inside a form
-
-```tsx
-import { Form } from "@g4rcez/components/form";
-import { Button } from "@g4rcez/components/button";
-
-function BookingForm() {
-  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
-    const data = new FormData(e.currentTarget);
-    console.log(data.get("check_in"), data.get("check_out"));
-  };
-
-  return (
-    <Form onSubmit={handleSubmit} className="flex flex-col gap-base">
-      <DatePicker name="check_in" title="Check-in" />
-      <DatePicker name="check_out" title="Check-out" />
-      <Button theme="primary" type="submit">Book</Button>
-    </Form>
-  );
-}
-```
-
-## Do
-
-- Use `disabledDate` to prevent invalid date selection (e.g., past dates for future bookings).
-- Use `type="datetime"` when both date and time are required for the use case.
-- Provide a clear `title` label.
-- Rely on `locale` for locale-aware mask and calendar generation rather than hardcoding a format.
-
-## 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 `DatePicker` when only a year or only a month is needed — a `Select` is more appropriate.
-- Don't assume users will always use the calendar; the masked text input must also be keyboard-friendly.
-
-## Accessibility
-
-- The calendar icon button includes an `aria-describedby` referencing a visually-hidden `<span>` with a translatable label.
-- The underlying `Input` component handles `aria-disabled`, `aria-readonly`, and `aria-busy`.
-- The calendar (`Calendar` component) is fully keyboard-navigable.
-- The input is masked to prevent invalid character entry, reducing validation friction.
-- Follows the standard `fieldset > label` structure from `InputField`.
-
-## Data Attributes
-
-- `data-component="date-picker"` — on the visible `Input`.
-- `data-value` — ISO string representation of the selected date (set on the visible input).
-- `data-target` — mirrors the `name` prop; used to link the shadow input to the hidden field.
-- `data-origin` — on the hidden `<input type="date">`: its `name` value, used by `formReset`.
-
-## Notes
-
-- The component renders two inputs: a visible masked `Input` for user interaction and a hidden `<input type="date">` (with `name`) for native form submission.
-- The input mask is generated dynamically from `Intl.DateTimeFormat.formatToParts`, so it automatically reflects the locale's date order (e.g., MM/DD/YYYY vs DD/MM/YYYY).
-- Date parsing uses `date-fns`. The `placeholder` is derived from the same locale format string.
-- When `floating={true}` (default), the calendar is rendered in a `Dropdown` using `@floating-ui/react` positioned to the right of the input.