xertica-ui 2.2.1 → 2.3.0

package/docs/components/button.md

@@ -1,156 +1,156 @@
-# Button
-
-## Overview
-
-The primary interaction trigger. Use `Button` for any user-initiated action: form submission, navigation triggers, dialog openers, and destructive confirmations. It supports multiple visual variants, sizes, icon-only mode, and the `asChild` pattern for composing with router links.
-
----
-
-## When to Use
-
-- Submitting forms (primary action)
-- Opening dialogs, drawers, or sheets
-- Triggering secondary or ghost actions (cancel, go back)
-- Icon-only controls in toolbars and headers
-
-## When NOT to Use
-
-- **URL navigation without action intent** — use `<Button asChild><Link to="...">` or a navigation component instead of a plain `<Button>`.
-- **Destructive actions without confirmation** — always pair with an `<AlertDialog>` before executing irreversible actions.
-- **Never use native `<button>` HTML element** — always use `<Button>` from `xertica-ui`.
-
----
-
-## Variants
-
-| Variant       | Visual                         | Usage                            |
-| ------------- | ------------------------------ | -------------------------------- |
-| `default`     | Filled primary color           | Main CTA, form submit            |
-| `secondary`   | Filled muted color             | Secondary action                 |
-| `outline`     | Border, transparent background | Alternative secondary            |
-| `ghost`       | Transparent, hover accent      | Subtle controls, toolbar buttons |
-| `destructive` | Filled red/danger color        | Irreversible danger actions      |
-| `link`        | Text-only, underlined          | Inline text links                |
-| `success`     | Filled green                   | Positive confirmation actions    |
-| `info`        | Filled blue                    | Informational triggers           |
-| `warning`     | Filled amber                   | Cautionary actions               |
-
----
-
-## Sizes
-
-| Size      | Height    | Usage                        |
-| --------- | --------- | ---------------------------- |
-| `default` | `h-9`     | Standard                     |
-| `sm`      | `h-8`     | Compact areas, table rows    |
-| `lg`      | `h-10`    | Hero CTAs, prominent actions |
-| `icon`    | `h-9 w-9` | Icon-only buttons            |
-
----
-
-## Props
-
-| Prop        | Type                                                                                                              | Default     | Required | Description                                                |
-| ----------- | ----------------------------------------------------------------------------------------------------------------- | ----------- | -------- | ---------------------------------------------------------- |
-| `variant`   | `'default' \| 'secondary' \| 'outline' \| 'ghost' \| 'destructive' \| 'link' \| 'success' \| 'info' \| 'warning'` | `'default'` | No       | Visual style                                               |
-| `size`      | `'default' \| 'sm' \| 'lg' \| 'icon'`                                                                             | `'default'` | No       | Size preset                                                |
-| `loading`   | `boolean`                                                                                                         | `false`     | No       | Disables and shows a spinner while preserving button width |
-| `disabled`  | `boolean`                                                                                                         | `false`     | No       | Disables interaction                                       |
-| `asChild`   | `boolean`                                                                                                         | `false`     | No       | Renders as the child component (for Link composition)      |
-| `className` | `string`                                                                                                          | —           | No       | Additional CSS classes                                     |
-| `onClick`   | `() => void`                                                                                                      | —           | No       | Click handler                                              |
-| `type`      | `'button' \| 'submit' \| 'reset'`                                                                                 | `'button'`  | No       | HTML button type                                           |
-
-All other native `button` HTML attributes are forwarded.
-
----
-
-## Examples
-
-### Standard Variants
-
-```tsx
-import { Button } from 'xertica-ui/ui';
-
-<Button variant="default">Save</Button>
-<Button variant="secondary">Cancel</Button>
-<Button variant="outline">Export</Button>
-<Button variant="ghost">Learn More</Button>
-<Button variant="destructive">Delete Account</Button>
-<Button variant="success">Confirm</Button>
-<Button variant="info">Details</Button>
-<Button variant="warning">Review</Button>
-```
-
-### With Icon
-
-```tsx
-import { Plus, Trash2 } from 'lucide-react';
-
-<Button>
-  <Plus className="size-4" />
-  New Member
-</Button>
-
-<Button variant="destructive">
-  <Trash2 className="size-4" />
-  Delete
-</Button>
-```
-
-### Icon Only
-
-```tsx
-import { Settings } from 'lucide-react';
-
-<Button variant="ghost" size="icon" aria-label="Open settings">
-  <Settings className="size-4" />
-</Button>;
-```
-
-### Composed with Router Link
-
-```tsx
-import { Link } from 'react-router-dom';
-
-<Button asChild>
-  <Link to="/dashboard">Go to Dashboard</Link>
-</Button>;
-```
-
-### Action Pair
-
-```tsx
-<div className="flex justify-end gap-2">
-  <Button variant="ghost">Cancel</Button>
-  <Button type="submit">Save Changes</Button>
-</div>
-```
-
----
-
-## Accessibility
-
-- Has visible focus ring (`ring-ring`) via keyboard navigation.
-- Use `aria-label` for icon-only buttons to provide screen reader context.
-- When `disabled`, the button is non-interactive and visually muted.
-
----
-
-## AI Rules
-
-- **Never use `<button>`** — always use `<Button>` from `xertica-ui`.
-- **Never invent new variants** — use only the 9 documented variants.
-- **Never place two `variant="default"` buttons side by side** — one should be `ghost`, `outline`, or `secondary`.
-- For form submission, always set `type="submit"` on the submit button.
-- `size="icon"` requires the button to contain only a single icon element — adding text breaks the square aspect ratio.
-- When the button triggers a destructive action, use `variant="destructive"` and always confirm with `<AlertDialog>` first.
-
----
-
-## Related Components
-
-- [`AlertDialog`](./alert-dialog.md) — Required before destructive button actions
-- [`Dialog`](./dialog.md) — Common button target
-- [`Form`](./form.md) — Submit button context
-- [`DropdownMenu`](./dropdown-menu.md) — Often paired with ghost icon buttons
+# Button
+
+## Overview
+
+The primary interaction trigger. Use `Button` for any user-initiated action: form submission, navigation triggers, dialog openers, and destructive confirmations. It supports multiple visual variants, sizes, icon-only mode, and the `asChild` pattern for composing with router links.
+
+---
+
+## When to Use
+
+- Submitting forms (primary action)
+- Opening dialogs, drawers, or sheets
+- Triggering secondary or ghost actions (cancel, go back)
+- Icon-only controls in toolbars and headers
+
+## When NOT to Use
+
+- **URL navigation without action intent** — use `<Button asChild><Link to="...">` or a navigation component instead of a plain `<Button>`.
+- **Destructive actions without confirmation** — always pair with an `<AlertDialog>` before executing irreversible actions.
+- **Never use native `<button>` HTML element** — always use `<Button>` from `xertica-ui`.
+
+---
+
+## Variants
+
+| Variant       | Visual                         | Usage                            |
+| ------------- | ------------------------------ | -------------------------------- |
+| `default`     | Filled primary color           | Main CTA, form submit            |
+| `secondary`   | Filled muted color             | Secondary action                 |
+| `outline`     | Border, transparent background | Alternative secondary            |
+| `ghost`       | Transparent, hover accent      | Subtle controls, toolbar buttons |
+| `destructive` | Filled red/danger color        | Irreversible danger actions      |
+| `link`        | Text-only, underlined          | Inline text links                |
+| `success`     | Filled green                   | Positive confirmation actions    |
+| `info`        | Filled blue                    | Informational triggers           |
+| `warning`     | Filled amber                   | Cautionary actions               |
+
+---
+
+## Sizes
+
+| Size      | Height    | Usage                        |
+| --------- | --------- | ---------------------------- |
+| `default` | `h-9`     | Standard                     |
+| `sm`      | `h-8`     | Compact areas, table rows    |
+| `lg`      | `h-10`    | Hero CTAs, prominent actions |
+| `icon`    | `h-9 w-9` | Icon-only buttons            |
+
+---
+
+## Props
+
+| Prop        | Type                                                                                                              | Default     | Required | Description                                                |
+| ----------- | ----------------------------------------------------------------------------------------------------------------- | ----------- | -------- | ---------------------------------------------------------- |
+| `variant`   | `'default' \| 'secondary' \| 'outline' \| 'ghost' \| 'destructive' \| 'link' \| 'success' \| 'info' \| 'warning'` | `'default'` | No       | Visual style                                               |
+| `size`      | `'default' \| 'sm' \| 'lg' \| 'icon'`                                                                             | `'default'` | No       | Size preset                                                |
+| `loading`   | `boolean`                                                                                                         | `false`     | No       | Disables and shows a spinner while preserving button width |
+| `disabled`  | `boolean`                                                                                                         | `false`     | No       | Disables interaction                                       |
+| `asChild`   | `boolean`                                                                                                         | `false`     | No       | Renders as the child component (for Link composition)      |
+| `className` | `string`                                                                                                          | —           | No       | Additional CSS classes                                     |
+| `onClick`   | `() => void`                                                                                                      | —           | No       | Click handler                                              |
+| `type`      | `'button' \| 'submit' \| 'reset'`                                                                                 | `'button'`  | No       | HTML button type                                           |
+
+All other native `button` HTML attributes are forwarded.
+
+---
+
+## Examples
+
+### Standard Variants
+
+```tsx
+import { Button } from 'xertica-ui/ui';
+
+<Button variant="default">Save</Button>
+<Button variant="secondary">Cancel</Button>
+<Button variant="outline">Export</Button>
+<Button variant="ghost">Learn More</Button>
+<Button variant="destructive">Delete Account</Button>
+<Button variant="success">Confirm</Button>
+<Button variant="info">Details</Button>
+<Button variant="warning">Review</Button>
+```
+
+### With Icon
+
+```tsx
+import { Plus, Trash2 } from 'lucide-react';
+
+<Button>
+  <Plus className="size-4" />
+  New Member
+</Button>
+
+<Button variant="destructive">
+  <Trash2 className="size-4" />
+  Delete
+</Button>
+```
+
+### Icon Only
+
+```tsx
+import { Settings } from 'lucide-react';
+
+<Button variant="ghost" size="icon" aria-label="Open settings">
+  <Settings className="size-4" />
+</Button>;
+```
+
+### Composed with Router Link
+
+```tsx
+import { Link } from 'react-router-dom';
+
+<Button asChild>
+  <Link to="/dashboard">Go to Dashboard</Link>
+</Button>;
+```
+
+### Action Pair
+
+```tsx
+<div className="flex justify-end gap-2">
+  <Button variant="ghost">Cancel</Button>
+  <Button type="submit">Save Changes</Button>
+</div>
+```
+
+---
+
+## Accessibility
+
+- Has visible focus ring (`ring-ring`) via keyboard navigation.
+- Use `aria-label` for icon-only buttons to provide screen reader context.
+- When `disabled`, the button is non-interactive and visually muted.
+
+---
+
+## AI Rules
+
+- **Never use `<button>`** — always use `<Button>` from `xertica-ui`.
+- **Never invent new variants** — use only the 9 documented variants.
+- **Never place two `variant="default"` buttons side by side** — one should be `ghost`, `outline`, or `secondary`.
+- For form submission, always set `type="submit"` on the submit button.
+- `size="icon"` requires the button to contain only a single icon element — adding text breaks the square aspect ratio.
+- When the button triggers a destructive action, use `variant="destructive"` and always confirm with `<AlertDialog>` first.
+
+---
+
+## Related Components
+
+- [`AlertDialog`](./alert-dialog.md) — Required before destructive button actions
+- [`Dialog`](./dialog.md) — Common button target
+- [`Form`](./form.md) — Submit button context
+- [`DropdownMenu`](./dropdown-menu.md) — Often paired with ghost icon buttons

package/docs/components/calendar.md

@@ -1,141 +1,141 @@
-# Calendar
-
-## Overview
-
-A date picker calendar that renders a monthly grid of selectable days. Built on `react-day-picker`. Almost always used inside a `<Popover>` to provide an accessible date input. Supports single date selection, multiple dates, and date ranges. When `captionLayout="dropdown"` is used, the month/year header renders as interactive selectors with input-styled visuals.
-
----
-
-## When to Use
-
-- Date input fields (birth date, due date, deadline)
-- Date range selectors (start date / end date)
-- Any form field that requires calendar-based date selection
-
-## When NOT to Use
-
-- Datetime selection (date + time) — add a time input separately.
-- Period selection that doesn't need exact days — use a `<Select>` with "Last 30 days" options.
-
----
-
-## Props
-
-| Prop              | Type                                                             | Default    | Description                                                                                        |
-| ----------------- | ---------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------- |
-| `mode`            | `'single' \| 'multiple' \| 'range'`                              | `'single'` | Selection mode                                                                                     |
-| `selected`        | `Date \| Date[] \| DateRange`                                    | —          | Selected date(s)                                                                                   |
-| `onSelect`        | `(date) => void`                                                 | —          | Change handler                                                                                     |
-| `captionLayout`   | `'label' \| 'dropdown' \| 'dropdown-months' \| 'dropdown-years'` | `'label'`  | Controls how the month/year header is rendered. `'dropdown'` renders both as interactive selectors |
-| `buttonVariant`   | `ButtonVariant`                                                  | `'ghost'`  | Variant applied to the prev/next navigation buttons                                                |
-| `initialFocus`    | `boolean`                                                        | `false`    | Focuses the calendar on open (required when inside a Popover)                                      |
-| `disabled`        | `Matcher \| Matcher[]`                                           | —          | Disable specific dates                                                                             |
-| `fromDate`        | `Date`                                                           | —          | Minimum selectable date                                                                            |
-| `toDate`          | `Date`                                                           | —          | Maximum selectable date                                                                            |
-| `showOutsideDays` | `boolean`                                                        | `true`     | Show days from adjacent months                                                                     |
-| `className`       | `string`                                                         | —          | Additional CSS classes                                                                             |
-
-> All other `react-day-picker` props are forwarded as-is.
-
----
-
-## Examples
-
-### Single Date Picker (in Popover)
-
-```tsx
-import { Popover, PopoverContent, PopoverTrigger, Calendar, Button } from 'xertica-ui/ui';
-import { CalendarIcon } from 'lucide-react';
-import { format } from 'date-fns';
-import { useState } from 'react';
-
-const [date, setDate] = useState<Date>();
-
-<Popover>
-  <PopoverTrigger asChild>
-    <Button variant="outline" className="w-[240px] justify-start gap-2">
-      <CalendarIcon className="size-4" />
-      {date ? format(date, 'PPP') : 'Pick a date'}
-    </Button>
-  </PopoverTrigger>
-  <PopoverContent className="w-auto p-0" align="start">
-    <Calendar mode="single" selected={date} onSelect={setDate} initialFocus />
-  </PopoverContent>
-</Popover>;
-```
-
-### Dropdown Caption (month/year selectors)
-
-When `captionLayout="dropdown"`, the month and year header is replaced by interactive `<select>` elements styled to match inputs — with border, background, focus ring, and border-radius tokens. The trigger button size is controlled independently of the calendar.
-
-```tsx
-const triggerSizeClasses = {
-  sm: 'h-8 px-2 text-sm',
-  md: 'h-10 px-3 text-base',
-  lg: 'h-12 px-4 text-base',
-};
-
-<Popover>
-  <PopoverTrigger asChild>
-    <Button
-      variant="outline"
-      className={cn(
-        'w-[240px] justify-start gap-2 rounded-[var(--radius)]',
-        triggerSizeClasses['md']
-      )}
-    >
-      <CalendarIcon className="size-4" />
-      {date ? format(date, 'PPP') : 'Pick a date'}
-    </Button>
-  </PopoverTrigger>
-  <PopoverContent className="w-auto p-0" align="start">
-    <Calendar
-      captionLayout="dropdown"
-      mode="single"
-      selected={date}
-      onSelect={setDate}
-      initialFocus
-    />
-  </PopoverContent>
-</Popover>;
-```
-
-> **Note:** The `size` prop was intentionally kept off the `Calendar` component. Size and border-radius are concerns of the trigger element, not the calendar grid.
-
-### Disable Past Dates
-
-```tsx
-<Calendar
-  mode="single"
-  selected={date}
-  onSelect={setDate}
-  disabled={{ before: new Date() }}
-  initialFocus
-/>
-```
-
-### Date Range
-
-```tsx
-const [range, setRange] = useState<{ from: Date; to?: Date }>();
-
-<Calendar mode="range" selected={range} onSelect={setRange} className="rounded-md border" />;
-```
-
----
-
-## AI Rules
-
-- Always use Calendar inside a `<Popover>` with `<PopoverContent className="w-auto p-0">`.
-- Always pass `initialFocus` when inside a Popover — essential for keyboard/accessibility UX.
-- Use `date-fns` for date formatting (`format(date, 'PPP')`) — it is a standard peer dependency.
-- For form integration, use the `selected`/`onSelect` pattern, not `{...field}`.
-- To control trigger button size and border-radius, apply classes directly on the `<Button>` trigger — do not look for a `size` prop on `<Calendar>`.
-- Use `captionLayout="dropdown"` when the user needs to navigate to a distant month/year quickly (e.g., birth date fields).
-
----
-
-## Related Components
-
-- [`Popover`](./popover.md) — Always wraps Calendar for date input use cases
-- [`Select`](./select.md) — Alternative for period/range selection without exact dates
+# Calendar
+
+## Overview
+
+A date picker calendar that renders a monthly grid of selectable days. Built on `react-day-picker`. Almost always used inside a `<Popover>` to provide an accessible date input. Supports single date selection, multiple dates, and date ranges. When `captionLayout="dropdown"` is used, the month/year header renders as interactive selectors with input-styled visuals.
+
+---
+
+## When to Use
+
+- Date input fields (birth date, due date, deadline)
+- Date range selectors (start date / end date)
+- Any form field that requires calendar-based date selection
+
+## When NOT to Use
+
+- Datetime selection (date + time) — add a time input separately.
+- Period selection that doesn't need exact days — use a `<Select>` with "Last 30 days" options.
+
+---
+
+## Props
+
+| Prop              | Type                                                             | Default    | Description                                                                                        |
+| ----------------- | ---------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------- |
+| `mode`            | `'single' \| 'multiple' \| 'range'`                              | `'single'` | Selection mode                                                                                     |
+| `selected`        | `Date \| Date[] \| DateRange`                                    | —          | Selected date(s)                                                                                   |
+| `onSelect`        | `(date) => void`                                                 | —          | Change handler                                                                                     |
+| `captionLayout`   | `'label' \| 'dropdown' \| 'dropdown-months' \| 'dropdown-years'` | `'label'`  | Controls how the month/year header is rendered. `'dropdown'` renders both as interactive selectors |
+| `buttonVariant`   | `ButtonVariant`                                                  | `'ghost'`  | Variant applied to the prev/next navigation buttons                                                |
+| `initialFocus`    | `boolean`                                                        | `false`    | Focuses the calendar on open (required when inside a Popover)                                      |
+| `disabled`        | `Matcher \| Matcher[]`                                           | —          | Disable specific dates                                                                             |
+| `fromDate`        | `Date`                                                           | —          | Minimum selectable date                                                                            |
+| `toDate`          | `Date`                                                           | —          | Maximum selectable date                                                                            |
+| `showOutsideDays` | `boolean`                                                        | `true`     | Show days from adjacent months                                                                     |
+| `className`       | `string`                                                         | —          | Additional CSS classes                                                                             |
+
+> All other `react-day-picker` props are forwarded as-is.
+
+---
+
+## Examples
+
+### Single Date Picker (in Popover)
+
+```tsx
+import { Popover, PopoverContent, PopoverTrigger, Calendar, Button } from 'xertica-ui/ui';
+import { CalendarIcon } from 'lucide-react';
+import { format } from 'date-fns';
+import { useState } from 'react';
+
+const [date, setDate] = useState<Date>();
+
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="outline" className="w-[240px] justify-start gap-2">
+      <CalendarIcon className="size-4" />
+      {date ? format(date, 'PPP') : 'Pick a date'}
+    </Button>
+  </PopoverTrigger>
+  <PopoverContent className="w-auto p-0" align="start">
+    <Calendar mode="single" selected={date} onSelect={setDate} initialFocus />
+  </PopoverContent>
+</Popover>;
+```
+
+### Dropdown Caption (month/year selectors)
+
+When `captionLayout="dropdown"`, the month and year header is replaced by interactive `<select>` elements styled to match inputs — with border, background, focus ring, and border-radius tokens. The trigger button size is controlled independently of the calendar.
+
+```tsx
+const triggerSizeClasses = {
+  sm: 'h-8 px-2 text-sm',
+  md: 'h-10 px-3 text-base',
+  lg: 'h-12 px-4 text-base',
+};
+
+<Popover>
+  <PopoverTrigger asChild>
+    <Button
+      variant="outline"
+      className={cn(
+        'w-[240px] justify-start gap-2 rounded-[var(--radius)]',
+        triggerSizeClasses['md']
+      )}
+    >
+      <CalendarIcon className="size-4" />
+      {date ? format(date, 'PPP') : 'Pick a date'}
+    </Button>
+  </PopoverTrigger>
+  <PopoverContent className="w-auto p-0" align="start">
+    <Calendar
+      captionLayout="dropdown"
+      mode="single"
+      selected={date}
+      onSelect={setDate}
+      initialFocus
+    />
+  </PopoverContent>
+</Popover>;
+```
+
+> **Note:** The `size` prop was intentionally kept off the `Calendar` component. Size and border-radius are concerns of the trigger element, not the calendar grid.
+
+### Disable Past Dates
+
+```tsx
+<Calendar
+  mode="single"
+  selected={date}
+  onSelect={setDate}
+  disabled={{ before: new Date() }}
+  initialFocus
+/>
+```
+
+### Date Range
+
+```tsx
+const [range, setRange] = useState<{ from: Date; to?: Date }>();
+
+<Calendar mode="range" selected={range} onSelect={setRange} className="rounded-md border" />;
+```
+
+---
+
+## AI Rules
+
+- Always use Calendar inside a `<Popover>` with `<PopoverContent className="w-auto p-0">`.
+- Always pass `initialFocus` when inside a Popover — essential for keyboard/accessibility UX.
+- Use `date-fns` for date formatting (`format(date, 'PPP')`) — it is a standard peer dependency.
+- For form integration, use the `selected`/`onSelect` pattern, not `{...field}`.
+- To control trigger button size and border-radius, apply classes directly on the `<Button>` trigger — do not look for a `size` prop on `<Calendar>`.
+- Use `captionLayout="dropdown"` when the user needs to navigate to a distant month/year quickly (e.g., birth date fields).
+
+---
+
+## Related Components
+
+- [`Popover`](./popover.md) — Always wraps Calendar for date input use cases
+- [`Select`](./select.md) — Alternative for period/range selection without exact dates