@g4rcez/components 4.0.1 → 4.1.1

package/dist/ai/docs/Button.md

@@ -1,182 +0,0 @@
----
-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 "@phosphor-icons/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

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

package/dist/ai/docs/Card.md

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