@dynostack/react-grid 0.2.0 → 0.3.1

package/README.md

@@ -51,6 +51,8 @@ A single `<DataTable />` component that gives you ag-grid–level functionality
 - [Selection & bulk actions](#selection--bulk-actions)
 - [Expandable rows](#expandable-rows)
 - [Export](#export)
+- [View sheet](#view-sheet)
+- [Delete confirmation](#delete-confirmation)
 - [Custom row actions](#custom-row-actions)
 - [Server-side data](#server-side-data)
 - [API reference](#api-reference)
@@ -75,7 +77,28 @@ yarn add @dynostack/react-grid
 
 ## Tailwind setup
 
-The component ships Tailwind class names verbatim. Tell your Tailwind config to scan the package files:
+The component ships Tailwind class names verbatim, so your Tailwind build needs to know two things:
+
+1. **Where to scan** for the class strings inside the bundle.
+2. **Which semantic color tokens** (`bg-popover`, `bg-card`, `text-foreground`, …) exist.
+
+The package's `styles.css` registers the tokens for you via Tailwind v4's `@theme inline`. You only need to wire scanning.
+
+### Tailwind v4 — zero config
+
+```css
+/* your global stylesheet (e.g. src/index.css) */
+@import "tailwindcss";
+@source "../node_modules/@dynostack/react-grid/dist";
+@import "@dynostack/react-grid/styles.css";
+@import "@dynostack/react-grid/page.css";   /* optional: extend tokens to <body> */
+```
+
+That's the whole setup. No `tailwind.config.js`, no `@theme` block to copy-paste, no shadcn install required. Overlay surfaces (popovers, dropdowns, sheets, the row-actions menu) all render correctly out of the box.
+
+### Tailwind v3
+
+v3 doesn't read CSS `@theme` directives, so the semantic-color mapping has to live in your `tailwind.config.js`. The shadcn install guide for v3 covers the exact `theme.extend.colors` block you need — copy that, plus add the package's `dist` to your `content` array:
 
 ```js
 // tailwind.config.{js,ts}
@@ -84,10 +107,28 @@ export default {
     "./src/**/*.{ts,tsx}",
     "./node_modules/@dynostack/react-grid/dist/**/*.{js,mjs,cjs}",
   ],
+  theme: {
+    extend: {
+      colors: {
+        // copy the shadcn v3 color mapping here
+        // (background, foreground, card, popover, primary, secondary,
+        //  muted, accent, destructive, border, input, ring)
+        background: "hsl(var(--background))",
+        foreground: "hsl(var(--foreground))",
+        // … etc
+      },
+    },
+  },
 }
 ```
 
-> Tailwind v4? Add the same path to your `@source` directive instead.
+Then import `styles.css` as usual:
+
+```ts
+import "@dynostack/react-grid/styles.css"
+```
+
+> Starting a new project? **Use Tailwind v4.** The v4 path above is meaningfully simpler — the package handles token registration for you.
 
 ## Theme tokens
 
@@ -102,15 +143,22 @@ The grid is built on **shadcn/ui CSS variables**. It auto-adjusts to whatever th
 | Custom theme with non-shadcn names | Pass [`theme` prop](#theming) | Per-instance override mapped to shadcn vars. |
 | Want one grid to ignore the app theme | Pass `isolate` | Grid uses bundled defaults regardless of `:root`. |
 
-**Why this just works.** The bundled `styles.css` declares its defaults inside the `dynostack-grid-defaults` cascade layer. Any unlayered consumer rule (which is where shadcn and most app CSS lives) automatically wins — import order doesn't matter, and you can't accidentally overwrite your app's theme by importing the grid's stylesheet.
+**Why this just works.** The bundled `styles.css`:
 
-### Minimal install
+1. **Registers Tailwind v4 utility tokens** via a top-level `@theme inline` block — so `bg-popover`, `text-foreground`, `border-border`, etc. resolve to your tokens without any consumer-side `@theme` block.
+2. **Declares variable values inside the `dynostack-grid-defaults` cascade layer** — any unlayered consumer rule (which is where shadcn and most app CSS lives) automatically wins, regardless of import order. You can't accidentally overwrite your app's theme by importing the grid's stylesheet.
 
-```ts
-// main.tsx — once per app
-import "@dynostack/react-grid/styles.css"
+### Minimal install (Tailwind v4)
+
+```css
+/* your global stylesheet */
+@import "tailwindcss";
+@source "../node_modules/@dynostack/react-grid/dist";
+@import "@dynostack/react-grid/styles.css";
 ```
 
+See the [Tailwind setup](#tailwind-setup) section for v3.
+
 ### Optional: extend the theme to the page
 
 By default the grid only styles itself, not the surrounding page. If you want `<body>` to use the same background/foreground as the grid:
@@ -610,6 +658,72 @@ Mark a column non-exportable via `meta.exportable: false`.
 
 ---
 
+## View sheet
+
+Click the row action "View" → a right-side `Sheet` slides in showing every visible column as a `{Label}: {value}` card. The user can switch layout density inline (Compact 1 col / Relaxed 2 col / Comfy 3 col).
+
+Works out of the box with no props. Customize via `viewSheet`:
+
+```tsx
+<DataTable
+  viewSheet={{
+    side: "right",                              // or "left"
+    defaultDensity: "relaxed",                  // initial column count
+    hideDensityTabs: true,                      // hide the layout picker
+    fields: ["name", "email", "role"],          // limit / reorder shown columns
+    renderField: ({ column, value, row }) =>    // override how a value renders
+      column.id === "phone" ? <a href={`tel:${value}`}>{String(value)}</a> : null,
+    renderHeader: (row) => <YourCustomHeader row={row} />,
+    labels: {
+      title: (row) => `${row.name} (${row.role})`,
+      description: (row) => `Joined ${row.joinedAt}`,
+      emptyValue: "—",
+      density: { compact: "1 col", relaxed: "2 cols", comfy: "3 cols" },
+    },
+  }}
+  onView={(row) => track("user.view", row)}   // optional side-effect
+/>
+```
+
+Disable the built-in sheet entirely:
+
+```tsx
+<DataTable viewSheet={false} onView={(row) => router.push(`/users/${row.id}`)} />
+```
+
+`onView` fires before the sheet opens, so you can navigate / log / fetch alongside it.
+
+---
+
+## Delete confirmation
+
+Both the row-action "Delete" and the toolbar "Bulk delete" open a confirmation `AlertDialog` by default. The user must confirm before `onDelete` or `onBulkDelete` fires.
+
+```tsx
+<DataTable
+  onDelete={(row) => api.deleteUser(row.id)}
+  onBulkDelete={(rows) => api.bulkDelete(rows.map(r => r.id))}
+  confirmDelete={{
+    title: ({ rows, source }) =>
+      source === "bulk"
+        ? `Delete ${rows.length} users?`
+        : `Delete ${rows[0].name}?`,
+    description: ({ rows }) =>
+      `${rows.length === 1 ? "This user" : "These users"} will be permanently removed. This cannot be undone.`,
+    confirmLabel: "Yes, delete",
+    cancelLabel: "Keep",
+  }}
+/>
+```
+
+Skip the dialog (fire immediately):
+
+```tsx
+<DataTable confirmDelete={false} onDelete={(row) => softDelete(row)} />
+```
+
+---
+
 ## Custom row actions
 
 ```tsx
@@ -731,6 +845,10 @@ operations and only renders the returned page.
 | `density`                 | `"compact" \| "default" \| "comfortable"`                  | `"default"`            | Row density.                                           |
 | `theme`                   | `DataTableTheme`                                           | inherits `:root`       | Per-instance CSS-variable overrides. Accepts flat tokens **or** `{ light, dark }`. |
 | `isolate`                 | `boolean`                                                  | `false`                | Ignore the app's `:root` and render with bundled defaults. |
+| `onView`                  | `(row: TData) => void`                                     | —                      | Side-effect when "View" is clicked. Fires *before* the sheet opens. |
+| `onDelete`                | `(row: TData) => void`                                     | —                      | Single-row delete handler. Fires *after* the confirm modal (or immediately if `confirmDelete={false}`). |
+| `viewSheet`               | `ViewSheetConfig<TData> \| false`                          | enabled                | Configure or disable the built-in View sheet. |
+| `confirmDelete`           | `ConfirmDeleteConfig<TData> \| boolean`                    | `true`                 | Configure or disable the delete confirmation modal (applies to single + bulk). |
 
 `TData` must extend `{ id: string \| number }`.
 
@@ -801,6 +919,43 @@ import {
 } from "@dynostack/react-grid"
 ```
 
+```ts
+// View sheet types
+type ViewSheetDensity = "compact" | "relaxed" | "comfy"
+
+type ViewSheetConfig<TData> = {
+  side?: "right" | "left" | "top" | "bottom"
+  defaultDensity?: ViewSheetDensity
+  hideDensityTabs?: boolean
+  fields?: string[]
+  renderField?: (args: {
+    column: Column<TData, unknown>
+    value: unknown
+    row: TData
+  }) => React.ReactNode
+  renderHeader?: (row: TData) => React.ReactNode
+  labels?: {
+    title?: (row: TData) => React.ReactNode
+    description?: (row: TData) => React.ReactNode
+    emptyValue?: string
+    density?: { compact?: string; relaxed?: string; comfy?: string }
+  }
+}
+
+// Confirm-delete types
+type ConfirmDeleteContext<TData> = {
+  rows: TData[]
+  source: "single" | "bulk"
+}
+
+type ConfirmDeleteConfig<TData> = {
+  title?: (ctx: ConfirmDeleteContext<TData>) => React.ReactNode
+  description?: (ctx: ConfirmDeleteContext<TData>) => React.ReactNode
+  confirmLabel?: string
+  cancelLabel?: string
+}
+```
+
 ---
 
 ## Compatibility