@g4rcez/components 3.0.0 → 3.0.1

package/dist/ai/docs/Autocomplete.md

@@ -0,0 +1,225 @@
+---
+title: Autocomplete
+description: Searchable select with fuzzy matching, virtualized options, keyboard navigation, and dynamic option creation.
+package: "@g4rcez/components"
+export: "{ Autocomplete }"
+import: "import { Autocomplete } from '@g4rcez/components/autocomplete'"
+category: form
+---
+
+# Autocomplete
+
+Searchable select with fuzzy matching, virtualized options, keyboard navigation, and dynamic option creation.
+
+## Import
+
+```tsx
+import { Autocomplete } from "@g4rcez/components/autocomplete";
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | - | Field label |
+| `value` | `string` | - | Controlled selected value |
+| `options` | `AutocompleteItemProps[]` | - | List of selectable options |
+| `emptyMessage` | `Label` | - | Message displayed when no options match |
+| `dynamicOption` | `boolean` | `false` | Allow creating new options from typed text |
+| `onChange` | `(e: React.ChangeEvent<HTMLInputElement>) => void` | - | Change handler |
+| `error` | `string` | - | Error message displayed below the field |
+| `feedback` | `Label` | - | Success/neutral feedback text below the field |
+| `left` | `Label` | - | Content rendered on the left inside the field border |
+| `right` | `Label` | - | Content rendered on the right inside the field border |
+| `required` | `boolean` | `false` | Marks field as required; hides "Optional" text |
+| `disabled` | `boolean` | `false` | Disables the field |
+| `loading` | `boolean` | `false` | Shows loading state |
+| `container` | `string` | - | Extra CSS classes for the outer `fieldset` |
+| `labelClassName` | `string` | - | Extra CSS classes for the label/border wrapper |
+
+### AutocompleteItemProps
+
+```tsx
+type AutocompleteItemProps = {
+  value: string;
+  label?: string;
+  hidden?: boolean;
+  disabled?: boolean;
+  "data-dynamic"?: string;
+  Render?: React.FC<OptionProps>;
+} & Record<`data-${string}`, string>;
+```
+
+## 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 field border color |
+| `placeholder-input-mask` | `--input-mask` | Placeholder text color |
+| `placeholder-input-mask-error` | `--input-mask-error` | Placeholder color in error state |
+| `text-foreground` | `--foreground` | Input text color |
+| `text-danger` | `--danger` | Text color in error state |
+| `text-primary` | `--primary` | Focus/hover border and ring color |
+| `bg-floating-background` | `--floating-background` | Dropdown background |
+| `border-floating-border` | `--floating-border` | Dropdown border color |
+| `bg-floating-hover` | `--floating-hover` | Option background on hover/keyboard focus |
+| `text-disabled` | `--disabled` | Empty message text color |
+| `border-tooltip-border` | `--tooltip-border` | Separator inside dropdown |
+| `z-floating` | `--z-floating` | Z-index for the floating panel |
+| `shadow-floating` | `--shadow-floating` | Drop shadow for the floating panel |
+
+## Examples
+
+### Basic usage
+
+```tsx
+import { Autocomplete } from "@g4rcez/components/autocomplete";
+
+const options = [
+  { value: "react", label: "React" },
+  { value: "vue", label: "Vue" },
+  { value: "svelte", label: "Svelte" },
+];
+
+function FrameworkPicker() {
+  const [value, setValue] = useState("");
+
+  return (
+    <Autocomplete
+      title="Framework"
+      placeholder="Search frameworks..."
+      options={options}
+      value={value}
+      onChange={(e) => setValue(e.target.value)}
+    />
+  );
+}
+```
+
+### Dynamic option creation
+
+```tsx
+function TagPicker() {
+  const [value, setValue] = useState("");
+  const [tags, setTags] = useState([
+    { value: "typescript", label: "TypeScript" },
+    { value: "javascript", label: "JavaScript" },
+  ]);
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const next = e.target.value;
+    setValue(next);
+    if (next && !tags.find((t) => t.value === next)) {
+      setTags((prev) => [...prev, { value: next, label: next }]);
+    }
+  };
+
+  return (
+    <Autocomplete
+      title="Tag"
+      placeholder="Search or create a tag..."
+      options={tags}
+      value={value}
+      onChange={handleChange}
+      dynamicOption
+      emptyMessage="Type to create a new tag"
+    />
+  );
+}
+```
+
+### Custom option renderer
+
+```tsx
+type UserOption = AutocompleteItemProps & { email: string; role: string };
+
+const UserRow = ({ value, label, ...props }: UserOption) => (
+  <div className="flex flex-col gap-0.5 py-1">
+    <span className="font-medium text-sm text-foreground">{label}</span>
+    <span className="text-xs text-muted-foreground">{props.email}</span>
+  </div>
+);
+
+const users: UserOption[] = [
+  { value: "alice", label: "Alice", email: "alice@example.com", role: "admin", Render: UserRow },
+  { value: "bob", label: "Bob", email: "bob@example.com", role: "member", Render: UserRow },
+];
+
+<Autocomplete title="Assign to" options={users} value="" onChange={() => {}} />;
+```
+
+### Form integration
+
+```tsx
+import { Form } from "@g4rcez/components/form";
+import { Button } from "@g4rcez/components/button";
+
+const countries = [
+  { value: "br", label: "Brazil" },
+  { value: "us", label: "United States" },
+  { value: "de", label: "Germany" },
+];
+
+function ContactForm() {
+  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    const data = new FormData(e.currentTarget);
+    console.log(Object.fromEntries(data));
+  };
+
+  return (
+    <Form onSubmit={handleSubmit} className="flex flex-col gap-base">
+      <Autocomplete
+        name="country"
+        title="Country"
+        options={countries}
+        required
+        emptyMessage="No countries found"
+      />
+      <Button theme="primary" type="submit">Submit</Button>
+    </Form>
+  );
+}
+```
+
+## Do
+
+- Provide a meaningful `emptyMessage` so users understand why no results appear.
+- Use `dynamicOption` when users should be able to add values not in the list.
+- Supply a custom `Render` component when each option needs to show more than its label (e.g., avatars, secondary text).
+- Prefer `Autocomplete` over `Select` for lists of more than ~15 items.
+
+## 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 `Autocomplete` for small lists where `Select` is simpler and faster.
+- Don't forget to handle the unselected case when `dynamicOption` is off and the user types but never picks an option.
+
+## Accessibility
+
+- Renders a `role="listbox"` dropdown managed by `@floating-ui/react`.
+- The visible input carries `aria-autocomplete="list"`.
+- Each option button has `aria-selected`, `aria-current`, and `aria-checked` set to reflect the active state.
+- Full keyboard navigation: Arrow Up/Down to move, Enter to select, Escape to close.
+- The caret button includes an `sr-only` label from the translation system.
+- Focus is returned to the trigger input when the dropdown closes.
+
+## Data Attributes
+
+- `data-value` — on the hidden `<input>`: the committed option value.
+- `data-shadow="true"` — on the visible text input to distinguish it from the real field.
+- `data-dynamic="true"` — on options injected by `dynamicOption`.
+- `data-initialized` — managed internally; used by `formReset` to track interaction state.
+- `data-floating="true"` — on the floating panel element.
+
+## Notes
+
+- The component renders two `<input>` elements: a visible shadow input for display/search and a hidden input with `name` that participates in form submission.
+- Option filtering uses a fuzzy-search (`fzf`) algorithm that matches partial text, abbreviations, and out-of-order characters against both `value` and `label`.
+- Large option lists are virtualized via `react-virtuoso` — rendering performance is maintained even with thousands of options.
+- The dropdown width always matches the width of the triggering fieldset.

package/dist/ai/docs/Button.md

@@ -0,0 +1,182 @@
+---
+title: Button
+description: A versatile button component with multiple variants, sizes, and states.
+package: "@g4rcez/components"
+export: "{ Button }"
+import: "import { Button } from '@g4rcez/components/button'"
+category: core
+---
+
+# Button
+
+A versatile button component with multiple variants, sizes, and states. Built with polymorphic capabilities to render as different HTML elements.
+
+## Import
+
+```tsx
+import { Button } from "@g4rcez/components/button";
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `theme` | `"main" \| "primary" \| "secondary" \| "info" \| "warn" \| "danger" \| "success" \| "muted" \| "neutral" \| "ghost-primary" \| "ghost-secondary" \| "ghost-info" \| "ghost-warn" \| "ghost-danger" \| "ghost-success" \| "ghost-muted" \| "ghost-neutral" \| "raw" \| "disabled" \| "loading"` | `"main"` | Visual theme/variant of the button |
+| `size` | `"icon" \| "min" \| "small" \| "default" \| "big" \| "tiny"` | `"default"` | Size of the button |
+| `rounded` | `"rough" \| "squared" \| "default" \| "circle"` | `"default"` | Border radius style |
+| `icon` | `React.ReactNode` | - | Icon to display before button content |
+| `loading` | `boolean` | `false` | Shows loading state with pulse animation and disables interaction |
+| `disabled` | `boolean` | `false` | Disables the button |
+| `as` | `React.ElementType` | `"button"` | HTML element to render as |
+| `type` | `string` | `"button"` | Button type attribute |
+| `className` | `string` | - | Additional CSS classes |
+| `children` | `React.ReactNode` | - | Button content |
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token | CSS Variable | Purpose |
+|-------|-------------|---------|
+| `bg-button-primary-bg` | `--button-primary-bg` | Background for primary/main theme |
+| `text-button-primary-text` | `--button-primary-text` | Text color for primary/main theme |
+| `bg-button-secondary-bg` | `--button-secondary-bg` | Background for secondary theme |
+| `text-button-secondary-text` | `--button-secondary-text` | Text color for secondary theme |
+| `bg-button-info-bg` | `--button-info-bg` | Background for info theme |
+| `text-button-info-text` | `--button-info-text` | Text color for info theme |
+| `bg-button-warn-bg` | `--button-warn-bg` | Background for warn theme |
+| `text-button-warn-text` | `--button-warn-text` | Text color for warn theme |
+| `bg-button-danger-bg` | `--button-danger-bg` | Background for danger theme |
+| `text-button-danger-text` | `--button-danger-text` | Text color for danger theme |
+| `bg-button-success-bg` | `--button-success-bg` | Background for success theme |
+| `text-button-success-text` | `--button-success-text` | Text color for success theme |
+| `bg-button-muted-bg` | `--button-muted-bg` | Background for muted theme |
+| `text-button-muted-text` | `--button-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-button` | `--radius-button` | Default border radius |
+| `focus-visible:ring-ring` | `--ring` | Focus ring color |
+
+## Theme Variants
+
+### Solid Variants
+
+- `main` / `primary`: Primary brand action
+- `secondary`: Secondary action
+- `info`: Informational action
+- `warn`: Warning action
+- `danger`: Destructive action
+- `success`: Confirmation/success action
+- `muted`: Subtle/subdued appearance
+- `neutral`: Transparent with card border
+
+### Ghost Variants
+
+Transparent background with colored text; shows a tinted background on hover.
+
+- `ghost-primary`, `ghost-secondary`, `ghost-info`, `ghost-warn`, `ghost-danger`, `ghost-success`, `ghost-muted`, `ghost-neutral`
+
+### Special Variants
+
+- `raw`: No default styling — supply all classes via `className`
+- `disabled`: Disabled visual appearance (use the `disabled` prop for full behavior)
+- `loading`: Pulse animation with muted background
+
+## Examples
+
+### Basic Variants
+
+```tsx
+<Button theme="primary">Primary</Button>
+<Button theme="secondary">Secondary</Button>
+<Button theme="danger">Delete</Button>
+<Button theme="success">Save</Button>
+```
+
+### Sizes
+
+```tsx
+<Button size="min">Mini</Button>
+<Button size="small">Small</Button>
+<Button size="default">Default</Button>
+<Button size="big">Big</Button>
+```
+
+### With Icons
+
+```tsx
+import { PlusIcon } from "lucide-react";
+
+<Button icon={<PlusIcon size={16} />}>Add Item</Button>
+
+<Button size="icon" theme="ghost-primary">
+  <PlusIcon size={16} />
+</Button>
+```
+
+### Loading State
+
+```tsx
+<Button loading>Saving...</Button>
+```
+
+### Ghost Variants
+
+```tsx
+<Button theme="ghost-primary">Ghost Primary</Button>
+<Button theme="ghost-danger">Ghost Danger</Button>
+```
+
+### Polymorphic Usage
+
+```tsx
+<Button as="a" href="/dashboard" theme="primary">
+  Go to Dashboard
+</Button>
+```
+
+### Rounded Variants
+
+```tsx
+<Button rounded="squared">Squared</Button>
+<Button rounded="circle" size="icon">
+  <PlusIcon size={16} />
+</Button>
+```
+
+## Do
+
+- Use `theme="primary"` for the single main action on a page
+- Use `theme="danger"` for destructive actions (delete, remove)
+- Use the `loading` prop to give immediate feedback for async operations
+- Use `as="a"` with `href` when the button navigates to a URL
+- Use design-token classes for any wrapper elements (`bg-primary`, `text-foreground`)
+
+## 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 place multiple `theme="primary"` buttons in the same view
+- Don't use `theme="primary"` for destructive actions — use `theme="danger"` instead
+
+## Accessibility
+
+- Renders as a semantic `<button>` element by default
+- Sets `aria-disabled` when `disabled` or `loading` is true
+- Sets `aria-busy` during loading state
+- Click handlers are automatically removed while loading or disabled
+- Supports visible focus rings via `focus-visible:ring-4 focus-visible:ring-ring`
+- Keyboard navigation is fully supported
+
+## Data Attributes
+
+- `data-component="button"`: Identifies the component for styling/testing
+- `data-theme`: Current theme variant value
+- `data-loading`: `"true"` when in loading state, `"false"` otherwise
+
+## Notes
+
+- When `loading` is `true`, `disabled` is also set to `true` automatically
+- The component forwards refs correctly to the underlying element
+- All standard HTML button (or target element) attributes are forwarded
+- The `as` prop enables rendering as any HTML element or React component while preserving full TypeScript type safety

package/dist/ai/docs/Calendar.md

@@ -0,0 +1,219 @@
+---
+title: Calendar
+description: Interactive month-view calendar with single-date and range selection, keyboard navigation, and locale support.
+package: "@g4rcez/components"
+export: "{ Calendar }"
+import: "import { Calendar } from '@g4rcez/components/calendar'"
+category: display
+---
+
+# Calendar
+
+Interactive month-view calendar with single-date and range selection, keyboard navigation, and locale support.
+
+## Import
+
+```tsx
+import { Calendar } from "@g4rcez/components/calendar";
+import type { Range, Locales } from "@g4rcez/components/calendar";
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `date` | `Date` | — | Selected date (single-date mode) |
+| `range` | `Range` | — | Selected range `{ from?: Date; to?: Date }` |
+| `rangeMode` | `boolean` | `false` | Enable range selection mode |
+| `markRange` | `boolean` | `true` | Visually highlight dates inside a range |
+| `markToday` | `boolean` | `true` | Emphasize today's date |
+| `type` | `"date" \| "datetime"` | `"date"` | Show an additional time input when `"datetime"` |
+| `datetimeTitle` | `string` | — | Label for the time input in `"datetime"` mode |
+| `onChange` | `OnChangeDate \| OnChangeRange` | — | Called when a date or range changes |
+| `changeOnlyOnClick` | `boolean` | `false` | Suppress onChange on keyboard navigation; fire only on explicit click |
+| `onChangeYear` | `(date: Date) => void` | — | Called when the year changes |
+| `onChangeMonth` | `(date: Date) => void` | — | Called when the month changes |
+| `disabledDate` | `(date: Date) => boolean` | — | Return `true` to disable a specific date |
+| `RenderOnDay` | `React.FC<{ date: Date }>` | — | Custom renderer overlaid on each day cell |
+| `locale` | `Locales` | — | BCP 47 locale string for month/weekday labels |
+| `labelRange` | `{ from: string; to: string }` | — | Labels shown on the selected range endpoints |
+| `styles` | `CalendarStyles` | — | Fine-grained class overrides per calendar section |
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token | CSS Variable | Purpose |
+|-------|-------------|---------|
+| `bg-primary` | `--primary` | Selected day background |
+| `text-primary-foreground` | `--primary-foreground` | Selected day text |
+| `hover:bg-primary` | `--primary` | Navigation button hover background |
+| `hover:text-primary-foreground` | `--primary-foreground` | Navigation button hover text |
+| `text-primary` | `--primary` | "Today" button and year/month hover color |
+| `text-disabled` | `--disabled` | Days outside the current month |
+| `border-card-border` | `--card-border` | Range highlight border |
+| `text-foreground` | `--foreground` | Range endpoint label |
+
+## Examples
+
+### Single Date Selection
+
+```tsx
+import { useState } from "react";
+
+function DatePicker() {
+  const [selectedDate, setSelectedDate] = useState<Date>(new Date());
+
+  return (
+    <Calendar
+      date={selectedDate}
+      onChange={setSelectedDate}
+      markToday
+    />
+  );
+}
+```
+
+### Date Range Selection
+
+```tsx
+import { useState } from "react";
+import { Calendar, type Range } from "@g4rcez/components/calendar";
+
+function DateRangePicker() {
+  const [range, setRange] = useState<Range>({ from: undefined, to: undefined });
+
+  return (
+    <Calendar
+      range={range}
+      rangeMode
+      markRange
+      onChange={setRange}
+      labelRange={{ from: "Start Date", to: "End Date" }}
+    />
+  );
+}
+```
+
+### Disabled Dates
+
+```tsx
+const isPastDate = (date: Date): boolean => {
+  const today = new Date();
+  today.setHours(0, 0, 0, 0);
+  return date < today;
+};
+
+<Calendar
+  date={selectedDate}
+  onChange={setSelectedDate}
+  disabledDate={isPastDate}
+/>
+```
+
+### Booking Calendar with Range Restrictions
+
+```tsx
+function BookingCalendar() {
+  const [bookingRange, setBookingRange] = useState<Range>({});
+
+  const isDateDisabled = (date: Date): boolean => {
+    const today = new Date();
+    const minDate = new Date(today);
+    minDate.setDate(today.getDate() + 2);
+    const maxDate = new Date(today);
+    maxDate.setDate(today.getDate() + 90);
+    return date < minDate || date > maxDate;
+  };
+
+  return (
+    <Calendar
+      range={bookingRange}
+      rangeMode
+      markRange
+      markToday
+      onChange={setBookingRange}
+      disabledDate={isDateDisabled}
+      labelRange={{ from: "Check-in", to: "Check-out" }}
+    />
+  );
+}
+```
+
+### Internationalized Calendar
+
+```tsx
+import { Calendar, type Locales } from "@g4rcez/components/calendar";
+
+function InternationalCalendar() {
+  const [selectedDate, setSelectedDate] = useState<Date>(new Date());
+  const [locale, setLocale] = useState<Locales>("en");
+
+  return (
+    <Calendar
+      date={selectedDate}
+      onChange={setSelectedDate}
+      locale={locale}
+      markToday
+    />
+  );
+}
+```
+
+### Custom Day Renderer
+
+```tsx
+function EventDot({ date }: { date: Date }) {
+  const hasEvent = myEvents.some(
+    (e) => e.date.toDateString() === date.toDateString()
+  );
+  return hasEvent ? (
+    <span className="absolute bottom-1 left-1/2 -translate-x-1/2 size-1 rounded-full bg-primary" />
+  ) : null;
+}
+
+<Calendar
+  date={selectedDate}
+  onChange={setSelectedDate}
+  RenderOnDay={EventDot}
+  markToday
+/>
+```
+
+## Do
+
+- Use `markToday` to help users orient themselves.
+- Use `disabledDate` to restrict selection to valid periods.
+- Provide `labelRange` labels when using `rangeMode` so users know which endpoint they are selecting.
+- Pass the correct `locale` to match user locale preferences.
+- Use design-token classes for any wrapper elements (`bg-background`, `border-border`).
+
+## Don't
+
+- Don't pass raw Tailwind color classes (`bg-blue-500`, `text-white`) in `styles` or `RenderOnDay` — use design tokens instead.
+- Don't use arbitrary Tailwind values (`bg-[#abc]`) — override CSS variables in your `@theme` block.
+- Don't use `Calendar` when only year selection is needed — a `Select` is more efficient.
+- Don't place too many visual markers on each day; keep day-level indicators minimal.
+
+## Accessibility
+
+- Full keyboard navigation: Arrow keys move days, Shift+Arrow moves months/years, Enter/Space selects.
+- Month and year controls are accessible `<select>` and masked text inputs with `aria-label`.
+- Navigation buttons include `title` attributes for screen reader description.
+- Disabled dates use the native `disabled` attribute on `<button>`.
+
+## Data Attributes
+
+- `data-component="calendar"` — root container.
+- `data-date` — ISO date string on each day button, used for focus management.
+- `data-samemonth` — `"true"` / `"false"` on each day button.
+- `data-range` — `"true"` / `"false"` on each day button.
+- `data-focustrap` — `"prev"` / `"next"` on navigation buttons.
+
+## Notes
+
+- Uses `date-fns` for date arithmetic and Framer Motion (`motion/react`) for slide animations.
+- Touch devices get swipe-left/right support for month navigation automatically.
+- When `changeOnlyOnClick` is `false` (default), `onChange` fires on every keyboard navigation move.
+- The calendar always renders 6 weeks (42 cells) to avoid layout shifts when switching months.
+- `type="datetime"` appends a masked time input below the calendar grid.