xertica-ui 2.2.1 → 2.4.0

package/docs/patterns/crud.md

@@ -1,149 +1,149 @@
-# Pattern: CRUD List
-
-## Intent
-
-The standard data list page for any entity in the system. Combines a filterable table with row-level actions. Editing and creation are handled by modals (`Dialog`) or side panels (`Sheet`), not by navigating to a separate route.
-
----
-
-## When to Use
-
-- Team management, user lists, product catalogs, record management
-- Any page where the primary task is viewing, filtering, and acting on a list of records
-- When create/edit flows are short enough to fit in a modal or side sheet
-
----
-
-## Anatomy
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  Page Header: Entity Title + Description + [New Entity] Btn  │
-├─────────────────────────────────────────────────────────────┤
-│  Card Container:                                             │
-│  ┌──────────┬───────────────────────────────────────────┐  │
-│  │ [Search] │ [Filter Dropdown] [Status Filter] ...     │  │
-│  ├──────────┴───────────────────────────────────────────┤  │
-│  │ Table: thead > th columns                            │  │
-│  │   tbody > tr per record, last col = action menu      │  │
-│  └──────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Full Pattern Code
-
-```tsx
-import {
-  Button,
-  Input,
-  Table,
-  TableHeader,
-  TableRow,
-  TableHead,
-  TableBody,
-  TableCell,
-  DropdownMenu,
-  DropdownMenuTrigger,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  Badge,
-  Card,
-} from 'xertica-ui/ui';
-import { Search, Plus, MoreHorizontal } from 'lucide-react';
-
-export function TeamMembersCRUD() {
-  return (
-    <div className="flex flex-col gap-6 p-6 w-full max-w-[1400px] mx-auto">
-      {/* 1. Page Header */}
-      <div className="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
-        <div>
-          <h1 className="text-2xl font-bold tracking-tight">Team Members</h1>
-          <p className="text-muted-foreground">Manage member access to the system.</p>
-        </div>
-        <Button className="gap-2">
-          <Plus className="size-4" />
-          New Member
-        </Button>
-      </div>
-
-      {/* 2. Table Card */}
-      <Card>
-        {/* Filter Row */}
-        <div className="flex p-4 border-b gap-2 flex-wrap">
-          <div className="relative w-full max-w-sm">
-            <Search className="absolute left-2.5 top-2.5 size-4 text-muted-foreground" />
-            <Input placeholder="Search by email..." className="w-full h-9 pl-8" />
-          </div>
-          {/* Add more filter dropdowns here if needed */}
-        </div>
-
-        {/* Data Table */}
-        <Table>
-          <TableHeader>
-            <TableRow>
-              <TableHead>Name</TableHead>
-              <TableHead>Email</TableHead>
-              <TableHead className="hidden md:table-cell">Role</TableHead>
-              <TableHead>Status</TableHead>
-              <TableHead className="text-right">Actions</TableHead>
-            </TableRow>
-          </TableHeader>
-          <TableBody>
-            <TableRow>
-              <TableCell className="font-medium">Admin Dev</TableCell>
-              <TableCell>dev@example.com</TableCell>
-              <TableCell className="hidden md:table-cell">Administrator</TableCell>
-              <TableCell>
-                <Badge variant="outline">Active</Badge>
-              </TableCell>
-              <TableCell className="text-right">
-                <DropdownMenu>
-                  <DropdownMenuTrigger asChild>
-                    <Button variant="ghost" size="icon" className="size-8">
-                      <MoreHorizontal className="size-4" />
-                    </Button>
-                  </DropdownMenuTrigger>
-                  <DropdownMenuContent align="end">
-                    <DropdownMenuItem>Edit Profile</DropdownMenuItem>
-                    <DropdownMenuItem className="text-destructive">Revoke Access</DropdownMenuItem>
-                  </DropdownMenuContent>
-                </DropdownMenu>
-              </TableCell>
-            </TableRow>
-          </TableBody>
-        </Table>
-      </Card>
-    </div>
-  );
-}
-```
-
----
-
-## Composition Rules
-
-1. **Filter search input** always uses the `relative` + `absolute icon` + `pl-8` pattern — never put the icon outside the input.
-2. **Row action menus** always use `<DropdownMenu>` with `<DropdownMenuTrigger asChild>` wrapping a ghost icon button.
-3. **Status cells** always use `<Badge>` — never plain text.
-4. **Destructive row actions** (delete, revoke) use `className="text-destructive"` on the `<DropdownMenuItem>`.
-5. **The create button** is always in the top-right of the page header, uses `<Plus className="size-4" />` icon.
-6. **Never open a new route for create/edit** — use a `<Dialog>` or `<Sheet>` instead.
-7. Wrap the entire table (filter row + `<Table>`) inside a **single `<Card>`** — do not create separate cards for the filter and the table.
-
----
-
-## Related Patterns
-
-- [Dashboard Pattern](./dashboard.md) — Overview page that links to CRUD pages
-- [Form Pattern](./form.md) — The create/edit form used inside the Dialog or Sheet
-
-## Related Components
-
-- [`Table`](../components/table.md)
-- [`DropdownMenu`](../components/dropdown-menu.md)
-- [`Badge`](../components/badge.md)
-- [`Input`](../components/input.md)
-- [`Dialog`](../components/dialog.md) — For create/edit modals
-- [`Sheet`](../components/sheet.md) — For create/edit side panels
+# Pattern: CRUD List
+
+## Intent
+
+The standard data list page for any entity in the system. Combines a filterable table with row-level actions. Editing and creation are handled by modals (`Dialog`) or side panels (`Sheet`), not by navigating to a separate route.
+
+---
+
+## When to Use
+
+- Team management, user lists, product catalogs, record management
+- Any page where the primary task is viewing, filtering, and acting on a list of records
+- When create/edit flows are short enough to fit in a modal or side sheet
+
+---
+
+## Anatomy
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Page Header: Entity Title + Description + [New Entity] Btn  │
+├─────────────────────────────────────────────────────────────┤
+│  Card Container:                                             │
+│  ┌──────────┬───────────────────────────────────────────┐  │
+│  │ [Search] │ [Filter Dropdown] [Status Filter] ...     │  │
+│  ├──────────┴───────────────────────────────────────────┤  │
+│  │ Table: thead > th columns                            │  │
+│  │   tbody > tr per record, last col = action menu      │  │
+│  └──────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Full Pattern Code
+
+```tsx
+import {
+  Button,
+  Input,
+  Table,
+  TableHeader,
+  TableRow,
+  TableHead,
+  TableBody,
+  TableCell,
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  Badge,
+  Card,
+} from 'xertica-ui/ui';
+import { Search, Plus, MoreHorizontal } from 'lucide-react';
+
+export function TeamMembersCRUD() {
+  return (
+    <div className="flex flex-col gap-6 p-6 w-full max-w-[1400px] mx-auto">
+      {/* 1. Page Header */}
+      <div className="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
+        <div>
+          <h1 className="text-2xl font-bold tracking-tight">Team Members</h1>
+          <p className="text-muted-foreground">Manage member access to the system.</p>
+        </div>
+        <Button className="gap-2">
+          <Plus className="size-4" />
+          New Member
+        </Button>
+      </div>
+
+      {/* 2. Table Card */}
+      <Card>
+        {/* Filter Row */}
+        <div className="flex p-4 border-b gap-2 flex-wrap">
+          <div className="relative w-full max-w-sm">
+            <Search className="absolute left-2.5 top-2.5 size-4 text-muted-foreground" />
+            <Input placeholder="Search by email..." className="w-full h-9 pl-8" />
+          </div>
+          {/* Add more filter dropdowns here if needed */}
+        </div>
+
+        {/* Data Table */}
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead>Name</TableHead>
+              <TableHead>Email</TableHead>
+              <TableHead className="hidden md:table-cell">Role</TableHead>
+              <TableHead>Status</TableHead>
+              <TableHead className="text-right">Actions</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            <TableRow>
+              <TableCell className="font-medium">Admin Dev</TableCell>
+              <TableCell>dev@example.com</TableCell>
+              <TableCell className="hidden md:table-cell">Administrator</TableCell>
+              <TableCell>
+                <Badge variant="outline">Active</Badge>
+              </TableCell>
+              <TableCell className="text-right">
+                <DropdownMenu>
+                  <DropdownMenuTrigger asChild>
+                    <Button variant="ghost" size="icon" className="size-8">
+                      <MoreHorizontal className="size-4" />
+                    </Button>
+                  </DropdownMenuTrigger>
+                  <DropdownMenuContent align="end">
+                    <DropdownMenuItem>Edit Profile</DropdownMenuItem>
+                    <DropdownMenuItem className="text-destructive">Revoke Access</DropdownMenuItem>
+                  </DropdownMenuContent>
+                </DropdownMenu>
+              </TableCell>
+            </TableRow>
+          </TableBody>
+        </Table>
+      </Card>
+    </div>
+  );
+}
+```
+
+---
+
+## Composition Rules
+
+1. **Filter search input** always uses the `relative` + `absolute icon` + `pl-8` pattern — never put the icon outside the input.
+2. **Row action menus** always use `<DropdownMenu>` with `<DropdownMenuTrigger asChild>` wrapping a ghost icon button.
+3. **Status cells** always use `<Badge>` — never plain text.
+4. **Destructive row actions** (delete, revoke) use `className="text-destructive"` on the `<DropdownMenuItem>`.
+5. **The create button** is always in the top-right of the page header, uses `<Plus className="size-4" />` icon.
+6. **Never open a new route for create/edit** — use a `<Dialog>` or `<Sheet>` instead.
+7. Wrap the entire table (filter row + `<Table>`) inside a **single `<Card>`** — do not create separate cards for the filter and the table.
+
+---
+
+## Related Patterns
+
+- [Dashboard Pattern](./dashboard.md) — Overview page that links to CRUD pages
+- [Form Pattern](./form.md) — The create/edit form used inside the Dialog or Sheet
+
+## Related Components
+
+- [`Table`](../components/table.md)
+- [`DropdownMenu`](../components/dropdown-menu.md)
+- [`Badge`](../components/badge.md)
+- [`Input`](../components/input.md)
+- [`Dialog`](../components/dialog.md) — For create/edit modals
+- [`Sheet`](../components/sheet.md) — For create/edit side panels

package/docs/patterns/dashboard.md

@@ -1,138 +1,138 @@
-# Pattern: Dashboard
-
-## Intent
-
-A Dashboard provides an at-a-glance overview of key system metrics. Use it as the home or overview page of any management application. The pattern combines KPI stat cards, charts, and activity feeds in a structured grid layout.
-
----
-
-## When to Use
-
-- As the first page after login in management applications
-- When the user needs to monitor multiple metrics simultaneously
-- For executive or operational overview screens
-
----
-
-## Anatomy
-
-```
-┌────────────────────────────────────────────────────────┐
-│  Page Header: Title + CTA Button (e.g., "Download Report")
-├────────────────────────────────────────────────────────┤
-│  Stats Row: 4 KPI Cards (grid-cols-4 lg)               │
-├───────────────────────────────┬────────────────────────┤
-│  Chart Panel (col-span-4)     │ Activity Feed (col-3)  │
-└───────────────────────────────┴────────────────────────┘
-```
-
----
-
-## Full Pattern Code
-
-```tsx
-import { Card, CardContent, CardHeader, CardTitle, Badge, Button, StatsCard } from 'xertica-ui/ui';
-import { Users, DollarSign, Activity, TrendingUp } from 'lucide-react';
-
-export function DashboardPage() {
-  return (
-    <div className="flex flex-col gap-6 p-6 w-full max-w-[1400px] mx-auto">
-      {/* 1. Page Header */}
-      <div className="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
-        <div>
-          <h1 className="text-2xl font-bold tracking-tight">Dashboard</h1>
-          <p className="text-muted-foreground">System overview</p>
-        </div>
-        <Button>Download Report</Button>
-      </div>
-
-      {/* 2. KPI Stats Row */}
-      <div className="grid gap-4 grid-cols-1 sm:grid-cols-2 lg:grid-cols-4">
-        <StatsCard
-          title="Total Revenue"
-          value="$45,231.89"
-          trend="+20.1%"
-          icon={<DollarSign className="size-4 text-muted-foreground" />}
-        />
-        <StatsCard
-          title="Active Users"
-          value="+2,350"
-          trend="+180 this month"
-          icon={<Users className="size-4 text-muted-foreground" />}
-        />
-        <StatsCard
-          title="Sales"
-          value="+12,234"
-          trend="+19% vs last month"
-          icon={<Activity className="size-4 text-muted-foreground" />}
-        />
-        <StatsCard
-          title="Retention Rate"
-          value="89.3%"
-          trend="+1.2%"
-          icon={<TrendingUp className="size-4 text-muted-foreground" />}
-        />
-      </div>
-
-      {/* 3. Chart + Feed Panel */}
-      <div className="grid gap-4 grid-cols-1 lg:grid-cols-7">
-        {/* Chart — takes 4 of 7 columns */}
-        <Card className="col-span-1 lg:col-span-4">
-          <CardHeader>
-            <CardTitle>Overview</CardTitle>
-          </CardHeader>
-          <CardContent className="h-[350px]">
-            {/* Mount a Recharts BarChart / LineChart here */}
-            <div className="flex h-full w-full items-center justify-center rounded-md border border-dashed bg-muted/20 text-muted-foreground">
-              Chart Area
-            </div>
-          </CardContent>
-        </Card>
-
-        {/* Activity Feed — takes 3 of 7 columns */}
-        <Card className="col-span-1 lg:col-span-3">
-          <CardHeader>
-            <CardTitle>Recent Events</CardTitle>
-          </CardHeader>
-          <CardContent>
-            <div className="space-y-4 text-sm">
-              <div className="flex items-center gap-4">
-                <Badge variant="outline">09:00</Badge>
-                <span>John Smith logged in</span>
-              </div>
-              <div className="flex items-center gap-4">
-                <Badge variant="outline">10:45</Badge>
-                <span>Invoice #INV004 paid</span>
-              </div>
-            </div>
-          </CardContent>
-        </Card>
-      </div>
-    </div>
-  );
-}
-```
-
----
-
-## Composition Rules
-
-1. **KPI cards always use the `StatsCard` pattern**: small title (`text-sm font-medium`), large value (`text-2xl font-bold`), supplementary trend text.
-2. **Chart cards always occupy more grid space than feed cards** — use `col-span-4` vs `col-span-3` in a 7-column grid.
-3. **Never hardcode pixel widths in grids** — use `lg:grid-cols-4`, `lg:grid-cols-7` with responsive overrides.
-4. **Chart placeholder areas** use `border-dashed bg-muted/20` — never leave them blank.
-5. **The max-width `max-w-[1400px]`** prevents the content from becoming too wide on large monitors.
-
----
-
-## Related Patterns
-
-- [Analytics Pattern](./analytics.md) — When you need time-series filtering and comparative views
-- [CRUD Pattern](./crud.md) — When the dashboard links to data management pages
-
-## Related Components
-
-- [`Card`](../components/card.md) — Primary container for all dashboard sections
-- [`Badge`](../components/badge.md) — Status and timestamp labels
-- [`Chart`](../components/chart.md) — Recharts integration for graph areas
-- [`StatsCard`](../components/stats-card.md) — Pre-built KPI card component
+# Pattern: Dashboard
+
+## Intent
+
+A Dashboard provides an at-a-glance overview of key system metrics. Use it as the home or overview page of any management application. The pattern combines KPI stat cards, charts, and activity feeds in a structured grid layout.
+
+---
+
+## When to Use
+
+- As the first page after login in management applications
+- When the user needs to monitor multiple metrics simultaneously
+- For executive or operational overview screens
+
+---
+
+## Anatomy
+
+```
+┌────────────────────────────────────────────────────────┐
+│  Page Header: Title + CTA Button (e.g., "Download Report")
+├────────────────────────────────────────────────────────┤
+│  Stats Row: 4 KPI Cards (grid-cols-4 lg)               │
+├───────────────────────────────┬────────────────────────┤
+│  Chart Panel (col-span-4)     │ Activity Feed (col-3)  │
+└───────────────────────────────┴────────────────────────┘
+```
+
+---
+
+## Full Pattern Code
+
+```tsx
+import { Card, CardContent, CardHeader, CardTitle, Badge, Button, StatsCard } from 'xertica-ui/ui';
+import { Users, DollarSign, Activity, TrendingUp } from 'lucide-react';
+
+export function DashboardPage() {
+  return (
+    <div className="flex flex-col gap-6 p-6 w-full max-w-[1400px] mx-auto">
+      {/* 1. Page Header */}
+      <div className="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
+        <div>
+          <h1 className="text-2xl font-bold tracking-tight">Dashboard</h1>
+          <p className="text-muted-foreground">System overview</p>
+        </div>
+        <Button>Download Report</Button>
+      </div>
+
+      {/* 2. KPI Stats Row */}
+      <div className="grid gap-4 grid-cols-1 sm:grid-cols-2 lg:grid-cols-4">
+        <StatsCard
+          title="Total Revenue"
+          value="$45,231.89"
+          trend="+20.1%"
+          icon={<DollarSign className="size-4 text-muted-foreground" />}
+        />
+        <StatsCard
+          title="Active Users"
+          value="+2,350"
+          trend="+180 this month"
+          icon={<Users className="size-4 text-muted-foreground" />}
+        />
+        <StatsCard
+          title="Sales"
+          value="+12,234"
+          trend="+19% vs last month"
+          icon={<Activity className="size-4 text-muted-foreground" />}
+        />
+        <StatsCard
+          title="Retention Rate"
+          value="89.3%"
+          trend="+1.2%"
+          icon={<TrendingUp className="size-4 text-muted-foreground" />}
+        />
+      </div>
+
+      {/* 3. Chart + Feed Panel */}
+      <div className="grid gap-4 grid-cols-1 lg:grid-cols-7">
+        {/* Chart — takes 4 of 7 columns */}
+        <Card className="col-span-1 lg:col-span-4">
+          <CardHeader>
+            <CardTitle>Overview</CardTitle>
+          </CardHeader>
+          <CardContent className="h-[350px]">
+            {/* Mount a Recharts BarChart / LineChart here */}
+            <div className="flex h-full w-full items-center justify-center rounded-md border border-dashed bg-muted/20 text-muted-foreground">
+              Chart Area
+            </div>
+          </CardContent>
+        </Card>
+
+        {/* Activity Feed — takes 3 of 7 columns */}
+        <Card className="col-span-1 lg:col-span-3">
+          <CardHeader>
+            <CardTitle>Recent Events</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <div className="space-y-4 text-sm">
+              <div className="flex items-center gap-4">
+                <Badge variant="outline">09:00</Badge>
+                <span>John Smith logged in</span>
+              </div>
+              <div className="flex items-center gap-4">
+                <Badge variant="outline">10:45</Badge>
+                <span>Invoice #INV004 paid</span>
+              </div>
+            </div>
+          </CardContent>
+        </Card>
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## Composition Rules
+
+1. **KPI cards always use the `StatsCard` pattern**: small title (`text-sm font-medium`), large value (`text-2xl font-bold`), supplementary trend text.
+2. **Chart cards always occupy more grid space than feed cards** — use `col-span-4` vs `col-span-3` in a 7-column grid.
+3. **Never hardcode pixel widths in grids** — use `lg:grid-cols-4`, `lg:grid-cols-7` with responsive overrides.
+4. **Chart placeholder areas** use `border-dashed bg-muted/20` — never leave them blank.
+5. **The max-width `max-w-[1400px]`** prevents the content from becoming too wide on large monitors.
+
+---
+
+## Related Patterns
+
+- [Analytics Pattern](./analytics.md) — When you need time-series filtering and comparative views
+- [CRUD Pattern](./crud.md) — When the dashboard links to data management pages
+
+## Related Components
+
+- [`Card`](../components/card.md) — Primary container for all dashboard sections
+- [`Badge`](../components/badge.md) — Status and timestamp labels
+- [`Chart`](../components/chart.md) — Recharts integration for graph areas
+- [`StatsCard`](../components/stats-card.md) — Pre-built KPI card component