xertica-ui 2.2.1 → 2.4.0

package/docs/components/sonner.md

@@ -1,115 +1,115 @@
-# Sonner (Toast Notifications)
-
-## Overview
-
-Sonner is the toast notification system. It displays ephemeral feedback messages that appear at a fixed position on screen (top-right by default), auto-dismiss after a few seconds, and can be dismissed manually. `<Toaster>` is auto-injected by `<XerticaProvider>` — you never need to render it manually.
-
----
-
-## When to Use
-
-- Confirming user actions: "Saved successfully", "Member added"
-- Showing errors from API calls: "Failed to save changes"
-- Providing undo affordance after non-destructive actions
-
-## When NOT to Use
-
-- Critical, persistent warnings — use inline `<Alert>` instead.
-- Destructive confirmations — use `<AlertDialog>` instead.
-- Validation errors in forms — use `<FormMessage>` inside `<FormField>`.
-
----
-
-## Usage
-
-Import the `toast` function from `sonner` directly — it is re-exported alongside the library:
-
-```tsx
-import { toast } from 'sonner';
-```
-
----
-
-## Methods
-
-| Method                                                | Description                                |
-| ----------------------------------------------------- | ------------------------------------------ |
-| `toast(message)`                                      | Default neutral toast                      |
-| `toast.success(message)`                              | Green success toast                        |
-| `toast.error(message)`                                | Red error toast                            |
-| `toast.warning(message)`                              | Amber warning toast                        |
-| `toast.info(message)`                                 | Blue info toast                            |
-| `toast.loading(message)`                              | Spinner toast (persistent until dismissed) |
-| `toast.promise(promise, { loading, success, error })` | Auto-updates toast based on promise state  |
-
----
-
-## Examples
-
-### Basic Feedback
-
-```tsx
-import { toast } from 'sonner';
-
-// In an event handler
-toast.success('Member saved successfully');
-toast.error('Failed to connect to server');
-toast.warning('Your session expires in 5 minutes');
-```
-
-### With Description
-
-```tsx
-toast.error('Save failed', {
-  description: 'Please check your connection and try again.',
-});
-```
-
-### Promise Toast (API calls)
-
-```tsx
-toast.promise(fetch('/api/save', { method: 'POST', body: JSON.stringify(data) }), {
-  loading: 'Saving...',
-  success: 'Saved successfully!',
-  error: 'Failed to save. Please try again.',
-});
-```
-
-### With Undo Action
-
-```tsx
-toast('Member deactivated', {
-  action: {
-    label: 'Undo',
-    onClick: () => handleReactivate(memberId),
-  },
-});
-```
-
----
-
-## Configuration
-
-The `<Toaster>` is rendered inside `<XerticaProvider>` with `position="top-right" richColors`. You do not need to customize it unless you need a different position or theme:
-
-```tsx
-// Inside XerticaProvider — already set up
-<Toaster position="top-right" richColors />
-```
-
----
-
-## AI Rules
-
-- **Never add `<Toaster>` manually** — it is injected by `<XerticaProvider>`.
-- Always use `toast.error()` for errors — never `toast()` with a modified className.
-- For actions that modify data (save, delete, add), **always provide user feedback** via a toast.
-- For API operations, use `toast.promise()` — it provides loading + success + error states automatically.
-- Do not use toasts for form validation errors — those go in `<FormMessage>`.
-
----
-
-## Related Components
-
-- [`Alert`](./alert.md) — Persistent inline messages
-- [`AlertDialog`](./alert-dialog.md) — Confirmation modals
+# Sonner (Toast Notifications)
+
+## Overview
+
+Sonner is the toast notification system. It displays ephemeral feedback messages that appear at a fixed position on screen (top-right by default), auto-dismiss after a few seconds, and can be dismissed manually. `<Toaster>` is auto-injected by `<XerticaProvider>` — you never need to render it manually.
+
+---
+
+## When to Use
+
+- Confirming user actions: "Saved successfully", "Member added"
+- Showing errors from API calls: "Failed to save changes"
+- Providing undo affordance after non-destructive actions
+
+## When NOT to Use
+
+- Critical, persistent warnings — use inline `<Alert>` instead.
+- Destructive confirmations — use `<AlertDialog>` instead.
+- Validation errors in forms — use `<FormMessage>` inside `<FormField>`.
+
+---
+
+## Usage
+
+Import the `toast` function from `sonner` directly — it is re-exported alongside the library:
+
+```tsx
+import { toast } from 'sonner';
+```
+
+---
+
+## Methods
+
+| Method                                                | Description                                |
+| ----------------------------------------------------- | ------------------------------------------ |
+| `toast(message)`                                      | Default neutral toast                      |
+| `toast.success(message)`                              | Green success toast                        |
+| `toast.error(message)`                                | Red error toast                            |
+| `toast.warning(message)`                              | Amber warning toast                        |
+| `toast.info(message)`                                 | Blue info toast                            |
+| `toast.loading(message)`                              | Spinner toast (persistent until dismissed) |
+| `toast.promise(promise, { loading, success, error })` | Auto-updates toast based on promise state  |
+
+---
+
+## Examples
+
+### Basic Feedback
+
+```tsx
+import { toast } from 'sonner';
+
+// In an event handler
+toast.success('Member saved successfully');
+toast.error('Failed to connect to server');
+toast.warning('Your session expires in 5 minutes');
+```
+
+### With Description
+
+```tsx
+toast.error('Save failed', {
+  description: 'Please check your connection and try again.',
+});
+```
+
+### Promise Toast (API calls)
+
+```tsx
+toast.promise(fetch('/api/save', { method: 'POST', body: JSON.stringify(data) }), {
+  loading: 'Saving...',
+  success: 'Saved successfully!',
+  error: 'Failed to save. Please try again.',
+});
+```
+
+### With Undo Action
+
+```tsx
+toast('Member deactivated', {
+  action: {
+    label: 'Undo',
+    onClick: () => handleReactivate(memberId),
+  },
+});
+```
+
+---
+
+## Configuration
+
+The `<Toaster>` is rendered inside `<XerticaProvider>` with `position="top-right" richColors`. You do not need to customize it unless you need a different position or theme:
+
+```tsx
+// Inside XerticaProvider — already set up
+<Toaster position="top-right" richColors />
+```
+
+---
+
+## AI Rules
+
+- **Never add `<Toaster>` manually** — it is injected by `<XerticaProvider>`.
+- Always use `toast.error()` for errors — never `toast()` with a modified className.
+- For actions that modify data (save, delete, add), **always provide user feedback** via a toast.
+- For API operations, use `toast.promise()` — it provides loading + success + error states automatically.
+- Do not use toasts for form validation errors — those go in `<FormMessage>`.
+
+---
+
+## Related Components
+
+- [`Alert`](./alert.md) — Persistent inline messages
+- [`AlertDialog`](./alert-dialog.md) — Confirmation modals

package/docs/components/stats-card.md

@@ -1,120 +1,120 @@
-# StatsCard
-
-## Overview
-
-A pre-built KPI (Key Performance Indicator) card for dashboard overview pages. Renders a metric title, a large value, an optional trend indicator with automatic up/down/neutral icon, and an optional icon.
-
-Built on top of `<Card>`. Use it for dashboard stat widgets where a consistent metric display is needed.
-
----
-
-## When to Use
-
-- Dashboard overview pages to show summary metrics (revenue, users, conversion)
-- KPI widgets that need to show value + trend direction
-
-## When NOT to Use
-
-- For arbitrary content — use `<Card>` directly.
-- When you need to heavily customize layout — compose from `<Card>` primitives instead.
-
----
-
-## Props
-
-| Prop          | Type                                | Required | Description                                                                                               |
-| ------------- | ----------------------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
-| `title`       | `string`                            | **Yes**  | Metric label (short)                                                                                      |
-| `value`       | `string \| number`                  | **Yes**  | The displayed metric value                                                                                |
-| `description` | `string`                            | No       | Additional supplementary text below the value                                                             |
-| `trend`       | `{ value: number; label?: string }` | No       | Trend object. `value` is a number (positive = up, negative = down). `label` overrides `description` text. |
-| `icon`        | `ReactNode`                         | No       | Icon from `lucide-react`                                                                                  |
-| `className`   | `string`                            | No       | Additional CSS classes                                                                                    |
-
-### trend
-
-The `trend` prop controls the automatic trend icon and color:
-
-- `trend.value > 0` → shows `TrendingUp` icon in green
-- `trend.value < 0` → shows `TrendingDown` icon in red (destructive)
-- `trend.value === 0` → shows `Minus` icon in muted
-
-The numeric value is displayed as an absolute percentage: `Math.abs(trend.value)%`.
-
----
-
-## Examples
-
-### Basic KPI Card
-
-```tsx
-import { StatsCard } from 'xertica-ui/ui';
-import { DollarSign } from 'lucide-react';
-
-<StatsCard
-  title="Total Revenue"
-  value="$45,231.89"
-  trend={{ value: 20.1, label: 'from last month' }}
-  icon={<DollarSign className="size-5" />}
-/>;
-```
-
-### Negative Trend
-
-```tsx
-<StatsCard
-  title="Churn Rate"
-  value="3.2%"
-  trend={{ value: -0.8, label: 'vs last quarter' }}
-  icon={<TrendingDown className="size-5" />}
-/>
-```
-
-### Stats Grid (4 columns)
-
-```tsx
-<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
-  <StatsCard
-    title="Revenue"
-    value="$45,231"
-    trend={{ value: 20.1, label: 'from last month' }}
-    icon={<DollarSign className="size-5" />}
-  />
-  <StatsCard
-    title="Active Users"
-    value="2,350"
-    trend={{ value: 8.2, label: 'new this week' }}
-    icon={<Users className="size-5" />}
-  />
-  <StatsCard
-    title="Conversion"
-    value="3.6%"
-    trend={{ value: -0.4, label: 'vs last month' }}
-    icon={<Activity className="size-5" />}
-  />
-  <StatsCard
-    title="Avg. Ticket"
-    value="$89.40"
-    description="All time average"
-    icon={<ShoppingCart className="size-5" />}
-  />
-</div>
-```
-
----
-
-## AI Rules
-
-- `trend.value` is a **numeric percentage** (e.g., `20.1` for +20.1%) — the component displays `Math.abs(value)%` automatically.
-- Do NOT pre-format the trend value as a string — pass the raw number.
-- `value` IS pre-formatted as a display string: `"$45,231"`, `"3.6%"`, `"2,350"`.
-- Icons render inside a muted rounded background — use `size-5` for the icon.
-- Always use in a 4-column responsive grid for dashboard overviews.
-- `trend.label` takes precedence over `description` for below-value text.
-
----
-
-## Related Components
-
-- [`Card`](./card.md) — The underlying primitive
-- [Dashboard Pattern](../patterns/dashboard.md) — Standard usage context
+# StatsCard
+
+## Overview
+
+A pre-built KPI (Key Performance Indicator) card for dashboard overview pages. Renders a metric title, a large value, an optional trend indicator with automatic up/down/neutral icon, and an optional icon.
+
+Built on top of `<Card>`. Use it for dashboard stat widgets where a consistent metric display is needed.
+
+---
+
+## When to Use
+
+- Dashboard overview pages to show summary metrics (revenue, users, conversion)
+- KPI widgets that need to show value + trend direction
+
+## When NOT to Use
+
+- For arbitrary content — use `<Card>` directly.
+- When you need to heavily customize layout — compose from `<Card>` primitives instead.
+
+---
+
+## Props
+
+| Prop          | Type                                | Required | Description                                                                                               |
+| ------------- | ----------------------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
+| `title`       | `string`                            | **Yes**  | Metric label (short)                                                                                      |
+| `value`       | `string \| number`                  | **Yes**  | The displayed metric value                                                                                |
+| `description` | `string`                            | No       | Additional supplementary text below the value                                                             |
+| `trend`       | `{ value: number; label?: string }` | No       | Trend object. `value` is a number (positive = up, negative = down). `label` overrides `description` text. |
+| `icon`        | `ReactNode`                         | No       | Icon from `lucide-react`                                                                                  |
+| `className`   | `string`                            | No       | Additional CSS classes                                                                                    |
+
+### trend
+
+The `trend` prop controls the automatic trend icon and color:
+
+- `trend.value > 0` → shows `TrendingUp` icon in green
+- `trend.value < 0` → shows `TrendingDown` icon in red (destructive)
+- `trend.value === 0` → shows `Minus` icon in muted
+
+The numeric value is displayed as an absolute percentage: `Math.abs(trend.value)%`.
+
+---
+
+## Examples
+
+### Basic KPI Card
+
+```tsx
+import { StatsCard } from 'xertica-ui/ui';
+import { DollarSign } from 'lucide-react';
+
+<StatsCard
+  title="Total Revenue"
+  value="$45,231.89"
+  trend={{ value: 20.1, label: 'from last month' }}
+  icon={<DollarSign className="size-5" />}
+/>;
+```
+
+### Negative Trend
+
+```tsx
+<StatsCard
+  title="Churn Rate"
+  value="3.2%"
+  trend={{ value: -0.8, label: 'vs last quarter' }}
+  icon={<TrendingDown className="size-5" />}
+/>
+```
+
+### Stats Grid (4 columns)
+
+```tsx
+<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
+  <StatsCard
+    title="Revenue"
+    value="$45,231"
+    trend={{ value: 20.1, label: 'from last month' }}
+    icon={<DollarSign className="size-5" />}
+  />
+  <StatsCard
+    title="Active Users"
+    value="2,350"
+    trend={{ value: 8.2, label: 'new this week' }}
+    icon={<Users className="size-5" />}
+  />
+  <StatsCard
+    title="Conversion"
+    value="3.6%"
+    trend={{ value: -0.4, label: 'vs last month' }}
+    icon={<Activity className="size-5" />}
+  />
+  <StatsCard
+    title="Avg. Ticket"
+    value="$89.40"
+    description="All time average"
+    icon={<ShoppingCart className="size-5" />}
+  />
+</div>
+```
+
+---
+
+## AI Rules
+
+- `trend.value` is a **numeric percentage** (e.g., `20.1` for +20.1%) — the component displays `Math.abs(value)%` automatically.
+- Do NOT pre-format the trend value as a string — pass the raw number.
+- `value` IS pre-formatted as a display string: `"$45,231"`, `"3.6%"`, `"2,350"`.
+- Icons render inside a muted rounded background — use `size-5` for the icon.
+- Always use in a 4-column responsive grid for dashboard overviews.
+- `trend.label` takes precedence over `description` for below-value text.
+
+---
+
+## Related Components
+
+- [`Card`](./card.md) — The underlying primitive
+- [Dashboard Pattern](../patterns/dashboard.md) — Standard usage context