xertica-ui 2.2.1 → 2.3.0

package/docs/components/alert-dialog.md

@@ -1,127 +1,127 @@
-# AlertDialog
-
-## Overview
-
-A specialized modal for **irreversible destructive actions** — delete, revoke, reset, permanently disable. Unlike `Dialog`, `AlertDialog` enforces that the user must explicitly confirm or cancel; clicking outside does not dismiss it.
-
----
-
-## When to Use
-
-- Deleting a record
-- Revoking access or permissions
-- Permanently disabling or deactivating an entity
-- Any action that cannot be undone
-
-## When NOT to Use
-
-- Non-destructive confirmations — use `Dialog` instead.
-- Quick succinct confirmations that don't require explanation — use `toast` with an undo option instead.
-
----
-
-## Anatomy
-
-```
-<AlertDialog>
-  <AlertDialogTrigger />
-  <AlertDialogContent>
-    <AlertDialogHeader>
-      <AlertDialogTitle />
-      <AlertDialogDescription />
-    </AlertDialogHeader>
-    <AlertDialogFooter>
-      <AlertDialogCancel />   ← always first (left)
-      <AlertDialogAction />   ← destructive action (right)
-    </AlertDialogFooter>
-  </AlertDialogContent>
-</AlertDialog>
-```
-
----
-
-## Props
-
-### AlertDialog
-
-| Prop           | Type                      | Description           |
-| -------------- | ------------------------- | --------------------- |
-| `open`         | `boolean`                 | Controlled open state |
-| `onOpenChange` | `(open: boolean) => void` | State handler         |
-
-### AlertDialogTrigger
-
-| Prop      | Type      | Description              |
-| --------- | --------- | ------------------------ |
-| `asChild` | `boolean` | Renders as child element |
-
-### AlertDialogAction
-
-| Prop        | Type         | Description                                     |
-| ----------- | ------------ | ----------------------------------------------- |
-| `className` | `string`     | Style the action button (typically destructive) |
-| `onClick`   | `() => void` | Action to execute on confirm                    |
-
----
-
-## Examples
-
-### Delete Confirmation
-
-```tsx
-import {
-  AlertDialog,
-  AlertDialogAction,
-  AlertDialogCancel,
-  AlertDialogContent,
-  AlertDialogDescription,
-  AlertDialogFooter,
-  AlertDialogHeader,
-  AlertDialogTitle,
-  AlertDialogTrigger,
-  Button,
-} from 'xertica-ui/ui';
-
-<AlertDialog>
-  <AlertDialogTrigger asChild>
-    <Button variant="destructive">Delete Account</Button>
-  </AlertDialogTrigger>
-  <AlertDialogContent>
-    <AlertDialogHeader>
-      <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
-      <AlertDialogDescription>
-        This action cannot be undone. This will permanently delete your account and remove all
-        associated data.
-      </AlertDialogDescription>
-    </AlertDialogHeader>
-    <AlertDialogFooter>
-      <AlertDialogCancel>Cancel</AlertDialogCancel>
-      <AlertDialogAction
-        className="bg-destructive text-destructive-foreground hover:bg-destructive/90"
-        onClick={handleDelete}
-      >
-        Delete
-      </AlertDialogAction>
-    </AlertDialogFooter>
-  </AlertDialogContent>
-</AlertDialog>;
-```
-
----
-
-## AI Rules
-
-- `AlertDialogTitle` is **required** — omitting it will trigger an accessibility error.
-- `AlertDialogDescription` is **required** — it explains what will happen and cannot be undone.
-- `AlertDialogCancel` must appear **before** `AlertDialogAction` in the footer — left to right: Cancel → Confirm.
-- Style the `AlertDialogAction` with `className="bg-destructive text-destructive-foreground hover:bg-destructive/90"` for destructive actions.
-- Clicking outside the dialog does NOT dismiss it — this is intentional to prevent accidental dismissal during destructive operations.
-- Never omit the Cancel option — users must always have a safe exit.
-
----
-
-## Related Components
-
-- [`Dialog`](./dialog.md) — For non-destructive modals
-- [`Button`](./button.md) — The trigger button
-- [`Sonner`](./sonner.md) — For toast confirmations with undo
+# AlertDialog
+
+## Overview
+
+A specialized modal for **irreversible destructive actions** — delete, revoke, reset, permanently disable. Unlike `Dialog`, `AlertDialog` enforces that the user must explicitly confirm or cancel; clicking outside does not dismiss it.
+
+---
+
+## When to Use
+
+- Deleting a record
+- Revoking access or permissions
+- Permanently disabling or deactivating an entity
+- Any action that cannot be undone
+
+## When NOT to Use
+
+- Non-destructive confirmations — use `Dialog` instead.
+- Quick succinct confirmations that don't require explanation — use `toast` with an undo option instead.
+
+---
+
+## Anatomy
+
+```
+<AlertDialog>
+  <AlertDialogTrigger />
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle />
+      <AlertDialogDescription />
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel />   ← always first (left)
+      <AlertDialogAction />   ← destructive action (right)
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+---
+
+## Props
+
+### AlertDialog
+
+| Prop           | Type                      | Description           |
+| -------------- | ------------------------- | --------------------- |
+| `open`         | `boolean`                 | Controlled open state |
+| `onOpenChange` | `(open: boolean) => void` | State handler         |
+
+### AlertDialogTrigger
+
+| Prop      | Type      | Description              |
+| --------- | --------- | ------------------------ |
+| `asChild` | `boolean` | Renders as child element |
+
+### AlertDialogAction
+
+| Prop        | Type         | Description                                     |
+| ----------- | ------------ | ----------------------------------------------- |
+| `className` | `string`     | Style the action button (typically destructive) |
+| `onClick`   | `() => void` | Action to execute on confirm                    |
+
+---
+
+## Examples
+
+### Delete Confirmation
+
+```tsx
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+  Button,
+} from 'xertica-ui/ui';
+
+<AlertDialog>
+  <AlertDialogTrigger asChild>
+    <Button variant="destructive">Delete Account</Button>
+  </AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
+      <AlertDialogDescription>
+        This action cannot be undone. This will permanently delete your account and remove all
+        associated data.
+      </AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Cancel</AlertDialogCancel>
+      <AlertDialogAction
+        className="bg-destructive text-destructive-foreground hover:bg-destructive/90"
+        onClick={handleDelete}
+      >
+        Delete
+      </AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>;
+```
+
+---
+
+## AI Rules
+
+- `AlertDialogTitle` is **required** — omitting it will trigger an accessibility error.
+- `AlertDialogDescription` is **required** — it explains what will happen and cannot be undone.
+- `AlertDialogCancel` must appear **before** `AlertDialogAction` in the footer — left to right: Cancel → Confirm.
+- Style the `AlertDialogAction` with `className="bg-destructive text-destructive-foreground hover:bg-destructive/90"` for destructive actions.
+- Clicking outside the dialog does NOT dismiss it — this is intentional to prevent accidental dismissal during destructive operations.
+- Never omit the Cancel option — users must always have a safe exit.
+
+---
+
+## Related Components
+
+- [`Dialog`](./dialog.md) — For non-destructive modals
+- [`Button`](./button.md) — The trigger button
+- [`Sonner`](./sonner.md) — For toast confirmations with undo

package/docs/components/alert.md

@@ -1,106 +1,106 @@
-# Alert
-
-## Overview
-
-An inline message banner used to communicate status, feedback, or important contextual information directly within the page content — without interrupting the user flow. Unlike `Sonner` (toast notifications), alerts are persistent and visible at all times.
-
-**Optimization**: The Xertica UI `Alert` component automatically renders a semantic icon based on the chosen `variant`. You do not need to add icons manually unless you want to override the default.
-
----
-
-## When to Use
-
-- Inline warnings about data state ("This record is read-only")
-- Information banners about required actions ("Please verify your email")
-- Success confirmation areas within a form or page section
-- Error messages from API responses or forms
-
----
-
-## Variants
-
-| Variant       | Color        | Default Icon  | Usage                         |
-| ------------- | ------------ | ------------- | ----------------------------- |
-| `default`     | Neutral      | Info          | General information           |
-| `info`        | Blue accent  | Info          | Informational context         |
-| `success`     | Green accent | CheckCircle   | Confirmation or success state |
-| `warning`     | Amber accent | AlertTriangle | Cautionary information        |
-| `destructive` | Red          | XCircle       | Errors, critical warnings     |
-
----
-
-## Anatomy
-
-```tsx
-<Alert variant="info">
-  <AlertTitle>Title</AlertTitle>
-  <AlertDescription>Detailed message here.</AlertDescription>
-</Alert>
-```
-
----
-
-## Props
-
-### Alert
-
-| Prop        | Type                                                             | Default     | Description                                                               |
-| ----------- | ---------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------- |
-| `variant`   | `'default' \| 'info' \| 'success' \| 'warning' \| 'destructive'` | `'default'` | Visual style and automatic icon                                           |
-| `icon`      | `ReactNode`                                                      | —           | Overrides the default semantic icon. Set to `null` to hide the icon area. |
-| `className` | `string`                                                         | —           | Additional CSS classes                                                    |
-
----
-
-## Examples
-
-### Informational (Automatic Icon)
-
-```tsx
-import { Alert, AlertDescription, AlertTitle } from 'xertica-ui/ui';
-
-<Alert variant="info">
-  <AlertTitle>Note</AlertTitle>
-  <AlertDescription>
-    This data is refreshed every 24 hours. Last updated: today at 08:00.
-  </AlertDescription>
-</Alert>;
-```
-
-### Warning
-
-```tsx
-<Alert variant="warning">
-  <AlertTitle>Attention Required</AlertTitle>
-  <AlertDescription>
-    Your subscription expires in 3 days. Renew to avoid service interruption.
-  </AlertDescription>
-</Alert>
-```
-
-### Custom Icon
-
-```tsx
-import { Terminal } from 'lucide-react';
-
-<Alert icon={<Terminal className="size-4" />}>
-  <AlertTitle>System Prompt</AlertTitle>
-  <AlertDescription>Executing automated deployment script...</AlertDescription>
-</Alert>;
-```
-
----
-
-## AI Rules
-
-- **Do not manually add icons inside `<Alert>`** — let the component handle them via `variant` or `icon` prop.
-- Always include an `AlertTitle` for clear information hierarchy.
-- Use `destructive` for errors and critical failure states.
-- Place alerts close to the relevant content (e.g., top of a form or below a header).
-
----
-
-## Related Components
-
-- [`Sonner`](./sonner.md) — For transient toast notifications
-- [`AlertDialog`](./alert-dialog.md) — For destructive confirmation modals
+# Alert
+
+## Overview
+
+An inline message banner used to communicate status, feedback, or important contextual information directly within the page content — without interrupting the user flow. Unlike `Sonner` (toast notifications), alerts are persistent and visible at all times.
+
+**Optimization**: The Xertica UI `Alert` component automatically renders a semantic icon based on the chosen `variant`. You do not need to add icons manually unless you want to override the default.
+
+---
+
+## When to Use
+
+- Inline warnings about data state ("This record is read-only")
+- Information banners about required actions ("Please verify your email")
+- Success confirmation areas within a form or page section
+- Error messages from API responses or forms
+
+---
+
+## Variants
+
+| Variant       | Color        | Default Icon  | Usage                         |
+| ------------- | ------------ | ------------- | ----------------------------- |
+| `default`     | Neutral      | Info          | General information           |
+| `info`        | Blue accent  | Info          | Informational context         |
+| `success`     | Green accent | CheckCircle   | Confirmation or success state |
+| `warning`     | Amber accent | AlertTriangle | Cautionary information        |
+| `destructive` | Red          | XCircle       | Errors, critical warnings     |
+
+---
+
+## Anatomy
+
+```tsx
+<Alert variant="info">
+  <AlertTitle>Title</AlertTitle>
+  <AlertDescription>Detailed message here.</AlertDescription>
+</Alert>
+```
+
+---
+
+## Props
+
+### Alert
+
+| Prop        | Type                                                             | Default     | Description                                                               |
+| ----------- | ---------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------- |
+| `variant`   | `'default' \| 'info' \| 'success' \| 'warning' \| 'destructive'` | `'default'` | Visual style and automatic icon                                           |
+| `icon`      | `ReactNode`                                                      | —           | Overrides the default semantic icon. Set to `null` to hide the icon area. |
+| `className` | `string`                                                         | —           | Additional CSS classes                                                    |
+
+---
+
+## Examples
+
+### Informational (Automatic Icon)
+
+```tsx
+import { Alert, AlertDescription, AlertTitle } from 'xertica-ui/ui';
+
+<Alert variant="info">
+  <AlertTitle>Note</AlertTitle>
+  <AlertDescription>
+    This data is refreshed every 24 hours. Last updated: today at 08:00.
+  </AlertDescription>
+</Alert>;
+```
+
+### Warning
+
+```tsx
+<Alert variant="warning">
+  <AlertTitle>Attention Required</AlertTitle>
+  <AlertDescription>
+    Your subscription expires in 3 days. Renew to avoid service interruption.
+  </AlertDescription>
+</Alert>
+```
+
+### Custom Icon
+
+```tsx
+import { Terminal } from 'lucide-react';
+
+<Alert icon={<Terminal className="size-4" />}>
+  <AlertTitle>System Prompt</AlertTitle>
+  <AlertDescription>Executing automated deployment script...</AlertDescription>
+</Alert>;
+```
+
+---
+
+## AI Rules
+
+- **Do not manually add icons inside `<Alert>`** — let the component handle them via `variant` or `icon` prop.
+- Always include an `AlertTitle` for clear information hierarchy.
+- Use `destructive` for errors and critical failure states.
+- Place alerts close to the relevant content (e.g., top of a form or below a header).
+
+---
+
+## Related Components
+
+- [`Sonner`](./sonner.md) — For transient toast notifications
+- [`AlertDialog`](./alert-dialog.md) — For destructive confirmation modals

package/docs/components/aspect-ratio.md

@@ -1,58 +1,58 @@
-# AspectRatio
-
-## Overview
-
-A container that maintains a fixed width-to-height ratio regardless of the available space. Prevents layout shifts when loading images, videos, or charts. Use when content must always fill a specific shape.
-
----
-
-## When to Use
-
-- Image thumbnails or banners that must maintain 16:9, 4:3, or 1:1 ratios
-- Video embeds
-- Map or chart containers with fixed proportions
-
----
-
-## Props
-
-| Prop        | Type     | Default | Description                                      |
-| ----------- | -------- | ------- | ------------------------------------------------ |
-| `ratio`     | `number` | `1`     | Width/height ratio (e.g., `16/9` for widescreen) |
-| `className` | `string` | —       | Applied to the container                         |
-
----
-
-## Examples
-
-### Image with 16:9 Ratio
-
-```tsx
-import { AspectRatio } from 'xertica-ui/ui';
-
-<div className="w-full max-w-lg">
-  <AspectRatio ratio={16 / 9}>
-    <img
-      src="https://example.com/hero.jpg"
-      alt="Hero"
-      className="rounded-md object-cover w-full h-full"
-    />
-  </AspectRatio>
-</div>;
-```
-
-### Square Avatar Banner
-
-```tsx
-<AspectRatio ratio={1} className="w-24">
-  <img src={user.avatar} className="rounded-full object-cover w-full h-full" />
-</AspectRatio>
-```
-
----
-
-## AI Rules
-
-- The outer container must have a defined width — `AspectRatio` sets the height automatically based on `ratio`.
-- The child content must use `w-full h-full` to fill the ratio container.
-- Never use `<AspectRatio>` without an explicit outer width constraint.
+# AspectRatio
+
+## Overview
+
+A container that maintains a fixed width-to-height ratio regardless of the available space. Prevents layout shifts when loading images, videos, or charts. Use when content must always fill a specific shape.
+
+---
+
+## When to Use
+
+- Image thumbnails or banners that must maintain 16:9, 4:3, or 1:1 ratios
+- Video embeds
+- Map or chart containers with fixed proportions
+
+---
+
+## Props
+
+| Prop        | Type     | Default | Description                                      |
+| ----------- | -------- | ------- | ------------------------------------------------ |
+| `ratio`     | `number` | `1`     | Width/height ratio (e.g., `16/9` for widescreen) |
+| `className` | `string` | —       | Applied to the container                         |
+
+---
+
+## Examples
+
+### Image with 16:9 Ratio
+
+```tsx
+import { AspectRatio } from 'xertica-ui/ui';
+
+<div className="w-full max-w-lg">
+  <AspectRatio ratio={16 / 9}>
+    <img
+      src="https://example.com/hero.jpg"
+      alt="Hero"
+      className="rounded-md object-cover w-full h-full"
+    />
+  </AspectRatio>
+</div>;
+```
+
+### Square Avatar Banner
+
+```tsx
+<AspectRatio ratio={1} className="w-24">
+  <img src={user.avatar} className="rounded-full object-cover w-full h-full" />
+</AspectRatio>
+```
+
+---
+
+## AI Rules
+
+- The outer container must have a defined width — `AspectRatio` sets the height automatically based on `ratio`.
+- The child content must use `w-full h-full` to fill the ratio container.
+- Never use `<AspectRatio>` without an explicit outer width constraint.