@djangocfg/ui-core 2.1.422 → 2.1.423

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.422",
+  "version": "2.1.423",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -106,7 +106,7 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.422",
+    "@djangocfg/i18n": "^2.1.423",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -180,8 +180,8 @@
     "@chenglou/pretext": "*"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.422",
-    "@djangocfg/typescript-config": "^2.1.422",
+    "@djangocfg/i18n": "^2.1.423",
+    "@djangocfg/typescript-config": "^2.1.423",
     "@types/node": "^25.2.3",
     "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",

package/src/components/data/table/README.md

@@ -0,0 +1,81 @@
+# Table
+
+Composable, headless data table built from semantic primitives. The root `Table`
+renders a bordered, rounded **`--card`** surface (a contained data panel that reads
+correctly in both light and dark), and you assemble the structure from the
+sub-components — there is no monolithic `columns`/`data` prop.
+
+All colors come from theme tokens (`--card`, `--border`, `--muted`, `--accent`),
+so light/dark is automatic. Don't reach for raw `bg-gray-*` / `border-zinc-*`.
+
+```tsx
+import {
+  Table, TableHeader, TableBody, TableFooter,
+  TableRow, TableHead, TableCell, TableCaption,
+} from '@djangocfg/ui-core';
+
+<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Invoice</TableHead>
+      <TableHead className="text-right">Amount</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell className="font-medium">INV001</TableCell>
+      <TableCell className="text-right">$250.00</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+## Components
+
+| Component | Element | Notes |
+|---|---|---|
+| `Table` | `<table>` (wrapped) | Card frame + scroll container. `className` → `<table>`; see `containerClassName` below. |
+| `TableHeader` | `<thead>` | Tinted header band. Supports `sticky`. |
+| `TableBody` | `<tbody>` | Supports `striped`. |
+| `TableFooter` | `<tfoot>` | Tinted band + `font-medium` for totals/summary rows. |
+| `TableRow` | `<tr>` | Hover highlight; `data-state="selected"` → accent fill. |
+| `TableHead` | `<th>` | Muted, medium-weight column label. |
+| `TableCell` | `<td>` | Body cell. |
+| `TableCaption` | `<caption>` | Bottom footer strip inside the card frame. |
+
+All forward their ref and spread native attributes. Per-element `className` always wins.
+
+## Custom props
+
+These are the only props beyond native HTML attributes:
+
+| Component | Prop | Type | Default | Description |
+|---|---|---|---|---|
+| `Table` | `containerClassName` | `string` | — | Class for the **inner scroll `<div>`** (`overflow-auto`), not the `<table>`. Cap its height (e.g. `"max-h-80"`) to get a scrollable body — required for a sticky header to have something to stick within. |
+| `TableHeader` | `sticky` | `boolean` | `false` | Pins the header (`sticky top-0 z-10`) and makes the band **fully opaque** (solid `bg-muted` instead of the `/50` tint) so scrolled rows don't bleed through. |
+| `TableBody` | `striped` | `boolean` | `false` | Zebra rows via `nth-child(even)` on the body — no need to compute `i % 2` per row. Per-row `className` still overrides. |
+
+## Selected rows
+
+`TableRow` reacts to `data-state="selected"` with an accent fill — drive it from your
+own selection state:
+
+```tsx
+<TableRow data-state={isSelected ? 'selected' : undefined}>…</TableRow>
+```
+
+## Scrollable table with a sticky header
+
+```tsx
+<Table containerClassName="max-h-[320px]">
+  <TableHeader sticky>…</TableHeader>
+  <TableBody>{/* many rows */}</TableBody>
+</Table>
+```
+
+The height cap goes on the **scroll container** (`containerClassName`), and `sticky`
+goes on the header — both are needed together.
+
+Storybook: `apps/storybook/stories/ui-core/data/Table.stories.tsx`
+(`Default`, `WithBadges`, `Striped`, `Compact`, `Sortable`, `Selectable`,
+`WithFooter`, `StickyHeader`, `Loading`, `Empty`).

package/src/components/data/table/index.tsx

@@ -4,33 +4,60 @@ import { cn } from '../../../lib/utils';
 
 const Table = React.forwardRef<
   HTMLTableElement,
-  React.HTMLAttributes<HTMLTableElement>
->(({ className, ...props }, ref) => (
-  <div className="relative w-full overflow-auto">
-    <table
-      ref={ref}
-      className={cn("w-full caption-bottom text-sm", className)}
-      {...props}
-    />
+  React.HTMLAttributes<HTMLTableElement> & { containerClassName?: string }
+>(({ className, containerClassName, ...props }, ref) => (
+  // Card-style frame: a bordered, rounded `--card` surface so the table
+  // reads as a contained data panel in both themes (the page `--background`
+  // alone gives no separation). `overflow-hidden` clips the header band and
+  // row borders to the rounded corners.
+  <div className="relative w-full overflow-hidden rounded-[var(--radius)] border border-border bg-card text-card-foreground">
+    {/* Scroll container. Cap its height via `containerClassName`
+      * (e.g. "max-h-80") to get a scrollable body with a sticky header. */}
+    <div className={cn("w-full overflow-auto", containerClassName)}>
+      <table
+        ref={ref}
+        className={cn("w-full caption-bottom text-sm", className)}
+        {...props}
+      />
+    </div>
   </div>
 ))
 Table.displayName = "Table"
 
 const TableHeader = React.forwardRef<
   HTMLTableSectionElement,
-  React.HTMLAttributes<HTMLTableSectionElement>
->(({ className, ...props }, ref) => (
-  <thead ref={ref} className={cn("[&_tr]:border-b", className)} {...props} />
+  React.HTMLAttributes<HTMLTableSectionElement> & { sticky?: boolean }
+>(({ className, sticky = false, ...props }, ref) => (
+  // Tinted header band with a solid bottom border so the column labels
+  // separate clearly from the body in both light and dark.
+  // When `sticky`, the band must be fully opaque (solid `bg-muted`, not the
+  // /50 tint) so scrolled body rows don't bleed through it.
+  <thead
+    ref={ref}
+    className={cn(
+      "[&_tr]:border-b [&_tr]:border-border",
+      sticky ? "sticky top-0 z-10 bg-muted" : "bg-muted/50",
+      className
+    )}
+    {...props}
+  />
 ))
 TableHeader.displayName = "TableHeader"
 
 const TableBody = React.forwardRef<
   HTMLTableSectionElement,
-  React.HTMLAttributes<HTMLTableSectionElement>
->(({ className, ...props }, ref) => (
+  React.HTMLAttributes<HTMLTableSectionElement> & { striped?: boolean }
+>(({ className, striped = false, ...props }, ref) => (
+  // `striped` opts into zebra rows via a structural selector on the body, so
+  // callers don't have to compute `i % 2` per row. Keeps the headless API:
+  // per-row className still wins and the default (false) is unchanged.
   <tbody
     ref={ref}
-    className={cn("[&_tr:last-child]:border-0", className)}
+    className={cn(
+      "[&_tr:last-child]:border-0",
+      striped && "[&_tr:nth-child(even)]:bg-muted/50",
+      className
+    )}
     {...props}
   />
 ))
@@ -58,7 +85,7 @@ const TableRow = React.forwardRef<
   <tr
     ref={ref}
     className={cn(
-      "border-b transition-colors hover:bg-muted/50 data-[state=selected]:bg-muted",
+      "border-b border-border transition-colors hover:bg-muted/50 data-[state=selected]:bg-accent",
       className
     )}
     {...props}
@@ -100,9 +127,14 @@ const TableCaption = React.forwardRef<
   HTMLTableCaptionElement,
   React.HTMLAttributes<HTMLTableCaptionElement>
 >(({ className, ...props }, ref) => (
+  // Caption sits at the bottom inside the card frame; a top border + padding
+  // make it read as a footer strip rather than floating text.
   <caption
     ref={ref}
-    className={cn("mt-4 text-sm text-muted-foreground", className)}
+    className={cn(
+      "border-t border-border px-3 py-2.5 text-left text-sm text-muted-foreground",
+      className
+    )}
     {...props}
   />
 ))