@dynostack/react-grid 0.1.0 → 0.2.0

package/README.md

@@ -26,7 +26,7 @@ A single `<DataTable />` component that gives you ag-grid–level functionality
 - **Selection + bulk actions** — pinned `__select` column with select-all, clear, bulk delete
 - **Expandable rows** — provide a `renderSubRow` panel or use TanStack's nested `getSubRows`
 - **CSV / Excel export** — selection-aware (export selected vs. all)
-- **Theming** — built on shadcn/ui CSS variables; per-instance overrides with a `theme` prop and ready-made presets
+- **Theming that just works** — shadcn-compatible CSS variables, automatic OS dark-mode follow, cascade-layered defaults that never overwrite your app theme, full-repaint moded presets (`violet`, `emerald`, `amber`, `rose`, `sky`, `slate`, …), `buildPreset(hue)` for custom hues, and `isolate` to opt out of inheriting the app theme
 - **Density** — `compact` · `default` · `comfortable`
 - **i18n / labels** — every visible string is overridable
 - **Feature flags** — turn off any toolbar control or table capability with a single boolean
@@ -40,6 +40,7 @@ A single `<DataTable />` component that gives you ag-grid–level functionality
 - [Tailwind setup](#tailwind-setup)
 - [Theme tokens](#theme-tokens)
 - [Quick start](#quick-start)
+- [Data fetching](#data-fetching)
 - [Theming](#theming)
 - [Density](#density)
 - [Feature flags](#feature-flags)
@@ -90,14 +91,44 @@ export default {
 
 ## Theme tokens
 
-If your app already has [shadcn/ui](https://ui.shadcn.com/docs/theming) tokens defined on `:root`, you're done — the table inherits them automatically.
+The grid is built on **shadcn/ui CSS variables**. It auto-adjusts to whatever theme your app already has:
 
-If not, import the default-tokens stylesheet once:
+| Your app has… | What you do | What you get |
+|---|---|---|
+| Nothing (bare React) | `import "@dynostack/react-grid/styles.css"` | Clean light theme, auto-switches to dark on OS preference. |
+| shadcn/ui (default theme) | Nothing | Grid inherits your `:root` tokens automatically. |
+| shadcn/ui with a custom theme (Stone / Zinc / your own hue) | Nothing | Grid picks up your custom tokens automatically. |
+| Custom theme using shadcn token names | Nothing | Same as above. |
+| 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.
+
+### Minimal install
+
+```ts
+// main.tsx — once per app
+import "@dynostack/react-grid/styles.css"
+```
+
+### 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:
 
 ```ts
 import "@dynostack/react-grid/styles.css"
+import "@dynostack/react-grid/page.css"   // optional
 ```
 
+### Dark mode
+
+| Mode | How to enable | Behavior |
+|---|---|---|
+| Follow OS | Default — no action required | Light by day, dark by night via `prefers-color-scheme`. |
+| Force light | Add `class="light"` to `<html>` | Stays light regardless of OS. |
+| Force dark | Add `class="dark"` to `<html>` | Stays dark regardless of OS. |
+| Per-instance | `<DataTable theme={themePresets.violet}>` | Grid auto-flips light/dark inside the moded preset. |
+
 Either way you can still override any token per-instance via the [`theme`](#theming) prop.
 
 ---
@@ -167,26 +198,92 @@ That's it. You now have sort + filter + edit + add + delete + export + pin + res
 
 ---
 
-## Theming
+## Data fetching
 
-All shadcn tokens are supported plus `radius` and `fontFamily`. Anything you omit falls through to the consumer's `:root`.
+`DataTable` supports two data ownership models.
 
-### Use a preset
+### 1. Controlled data from your page
+
+Use this when your app already owns fetching with TanStack Query, SWR, Redux,
+loader functions, or custom hooks. The table receives rows and loading flags as
+props, and your app owns error/toast behavior.
 
 ```tsx
-import { DataTable, themePresets } from "@dynostack/react-grid"
+const usersQuery = useQuery({
+  queryKey: ["users"],
+  queryFn: fetchUsers,
+})
 
-<DataTable data={data} columns={columns} theme={themePresets.violet} />
+<DataTable<User>
+  data={usersQuery.data ?? []}
+  columns={columns}
+  isLoading={usersQuery.isLoading}
+  isFetching={usersQuery.isFetching}
+  onRefresh={() => usersQuery.refetch()}
+  totalRecords={usersQuery.data?.length ?? 0}
+/>
 ```
 
-Available presets: `light` · `dark` · `emerald` · `violet` · `amber`.
+For blocking load errors, render your own page-level error state or pass an empty
+array. For background errors, show a toast from your query/mutation callbacks.
+
+### 2. Internal fetching with `dataSource`
 
-### Custom tokens
+Use this when you want the table to own fetch/loading/error/refresh state.
+`fetchRows` receives the current table state and can return either an array or
+`{ rows, totalRecords }`.
 
 ```tsx
-<DataTable
-  data={data}
+<DataTable<User>
   columns={columns}
+  dataSource={{
+    fetchRows: async ({ pageIndex, pageSize, sorting, columnFilters, globalFilter }) => {
+      const res = await fetch("/api/users", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          pageIndex,
+          pageSize,
+          sorting,
+          columnFilters,
+          q: globalFilter,
+        }),
+      })
+
+      if (!res.ok) throw new Error("Failed to load users")
+      return res.json() as Promise<{ rows: User[]; totalRecords: number }>
+    },
+    mode: "server",
+    onError: (error, context) => {
+      toast.error(context.message)
+      console.error(error)
+    },
+  }}
+/>
+```
+
+Internal mode behavior:
+
+- Initial load shows the table skeleton.
+- Initial load failure shows an inline `Could not load rows` state with `Retry`.
+- Refresh failure keeps the last successful rows visible and calls `onError`.
+- `mode: "client"` expects the full row array and lets the table sort/filter/page in memory.
+- `mode: "server"` expects the current page and uses `totalRecords` for pagination.
+
+Keep using `onCellEdit`, `onRowSave`, `onAddRow`, and `onBulkDelete` for mutations.
+The table does not assume your write API; this lets you choose optimistic updates,
+rollback, toast notifications, and validation.
+
+---
+
+## Theming
+
+The `theme` prop accepts **two shapes**. Pick whichever fits your use case.
+
+### Shape 1 — Flat tokens
+
+```tsx
+<DataTable
   theme={{
     primary: "oklch(0.6 0.2 200)",
     primaryForeground: "oklch(1 0 0)",
@@ -197,16 +294,102 @@ Available presets: `light` · `dark` · `emerald` · `violet` · `amber`.
 />
 ```
 
-CSS variables are emitted on the table root, so multiple instances on the same page can wear different themes.
+All shadcn tokens are supported plus `radius` and `fontFamily`. Anything you omit falls through to whatever your app's `:root` provides.
+
+### Shape 2 — Moded `{ light, dark }`
+
+A moded theme repaints the whole table **and** auto-flips on dark mode (OS preference *or* a `.dark` ancestor):
+
+```tsx
+<DataTable
+  theme={{
+    light: { background: "oklch(0.99 0.005 285)", primary: "oklch(0.55 0.22 285)", /* … */ },
+    dark:  { background: "oklch(0.16 0.012 285)", primary: "oklch(0.7  0.18 285)", /* … */ },
+  }}
+/>
+```
+
+The grid emits a tiny scoped `<style>` block that targets only this instance — multiple grids on the same page can wear different moded themes without interfering.
+
+### Use a preset
+
+Presets ship in **moded shape** — passing one repaints the entire table and follows dark mode automatically:
+
+```tsx
+import { DataTable, themePresets } from "@dynostack/react-grid"
+
+<DataTable theme={themePresets.violet} />
+```
+
+Available presets:
+
+| Preset | Hue |
+|---|---|
+| `neutral` | Grayscale (default appearance) |
+| `light` | Force light, no dark variant |
+| `dark` | Force dark, no light variant |
+| `violet` | 285° |
+| `emerald` | 162° |
+| `amber` | 65° |
+| `rose` | 15° |
+| `sky` | 235° |
+| `slate` | 240° (low chroma) |
+
+### Build a custom preset from a single hue
+
+```tsx
+import { DataTable, buildPreset } from "@dynostack/react-grid"
+
+const teal = buildPreset(180)        // hue only
+const subtleTeal = buildPreset(180, 0.015)  // hue + custom chroma
+
+<DataTable theme={teal} />
+```
+
+`buildPreset(hue, chroma?)` returns a full `{ light, dark }` token set tinted around the given OKLCH hue.
 
 ### Compose with a preset
 
 ```tsx
 <DataTable
-  theme={{ ...themePresets.dark, primary: "oklch(0.7 0.18 250)" }}
+  theme={{
+    ...themePresets.violet,
+    light: { ...themePresets.violet.light, primary: "oklch(0.7 0.18 250)" },
+  }}
 />
 ```
 
+### Isolate a grid from the app theme
+
+When embedding inside a heavily-themed shell where you want the table to keep its own look:
+
+```tsx
+<DataTable isolate /* uses bundled neutral tokens, ignores app :root */ />
+<DataTable isolate theme={themePresets.violet} /* isolated AND violet */ />
+```
+
+### Multiple grids, different themes
+
+CSS variables are emitted on each table root, so this works:
+
+```tsx
+<DataTable theme={themePresets.violet} />
+<DataTable theme={themePresets.emerald} />
+<DataTable theme={{ primary: "oklch(0.6 0.2 200)" }} />
+```
+
+### Precedence summary
+
+```
+┌──────────────────────────────────────────────────────────┐
+│ Inline style on the grid root  (per-instance `theme`)    │  ← highest
+├──────────────────────────────────────────────────────────┤
+│ Consumer's :root rules         (shadcn, custom app CSS)  │
+├──────────────────────────────────────────────────────────┤
+│ @layer dynostack-grid-defaults (bundled styles.css)      │  ← lowest
+└──────────────────────────────────────────────────────────┘
+```
+
 ---
 
 ## Density
@@ -454,7 +637,11 @@ Mark a column non-exportable via `meta.exportable: false`.
 
 ## Server-side data
 
-Provide a controlled global filter and refetch on change:
+You can do server-side data in either mode.
+
+### Controlled server-side data
+
+Own the API call in your page and pass the result into the table:
 
 ```tsx
 const [q, setQ] = useState("")
@@ -474,7 +661,38 @@ const usersQuery = useQuery({
 />
 ```
 
-Pair with TanStack Query's pagination/cursor utilities for cursor-based grids.
+Pair this with TanStack Query's pagination/cursor utilities when you want query
+caching and mutation orchestration outside the grid.
+
+### Built-in server-side data
+
+Let the grid call your API by setting `dataSource.mode` to `"server"`:
+
+```tsx
+<DataTable<User>
+  columns={columns}
+  dataSource={{
+    mode: "server",
+    fetchRows: async (state) => {
+      const res = await fetch("/api/users/grid", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(state),
+      })
+
+      if (!res.ok) throw new Error("Users request failed")
+      return res.json() as Promise<{ rows: User[]; totalRecords: number }>
+    },
+    onError: (_error, context) => {
+      toast.error(context.message)
+    },
+  }}
+/>
+```
+
+`state` contains `pageIndex`, `pageSize`, `sorting`, `columnFilters`, and
+`globalFilter`. In server mode the table assumes the API already applied those
+operations and only renders the returned page.
 
 ---
 
@@ -482,8 +700,9 @@ Pair with TanStack Query's pagination/cursor utilities for cursor-based grids.
 
 | Prop                      | Type                                                       | Default                | Description                                            |
 | ------------------------- | ---------------------------------------------------------- | ---------------------- | ------------------------------------------------------ |
-| `data`                    | `TData[]`                                                  | —                      | Row data.                                              |
+| `data`                    | `TData[]`                                                  | `[]`                   | Controlled row data. Use this when fetching outside the table. |
 | `columns`                 | `ColumnDef<TData>[]`                                       | —                      | TanStack column definitions.                           |
+| `dataSource`              | `DataTableDataSource<TData>`                               | —                      | Optional internal fetcher for client/server data loading. |
 | `isLoading`               | `boolean`                                                  | `false`                | Initial skeleton state.                                |
 | `isFetching`              | `boolean`                                                  | `false`                | Background-refresh indicator.                          |
 | `onRefresh`               | `() => void`                                               | —                      | Refresh button handler.                                |
@@ -510,10 +729,78 @@ Pair with TanStack Query's pagination/cursor utilities for cursor-based grids.
 | `features`                | `DataTableFeatures`                                        | all on                 | Feature flags.                                         |
 | `labels`                  | `DataTableLabels`                                          | English defaults       | i18n labels.                                           |
 | `density`                 | `"compact" \| "default" \| "comfortable"`                  | `"default"`            | Row density.                                           |
-| `theme`                   | `DataTableTheme`                                           | inherits `:root`       | Per-instance CSS-variable overrides.                   |
+| `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. |
 
 `TData` must extend `{ id: string \| number }`.
 
+```ts
+type DataTableDataSource<TData> = {
+  fetchRows: (params: {
+    pageIndex: number
+    pageSize: number
+    sorting: SortingState
+    columnFilters: ColumnFiltersState
+    globalFilter: string
+  }) => Promise<TData[] | { rows: TData[]; totalRecords?: number }>
+  mode?: "client" | "server"
+  enabled?: boolean
+  initialData?: TData[]
+  deps?: readonly unknown[]
+  onError?: (
+    error: unknown,
+    context: { type: "load" | "refresh"; message: string }
+  ) => void
+}
+```
+
+```ts
+// Theme types
+type DataTableTokens = {
+  background?: string
+  foreground?: string
+  card?: string
+  cardForeground?: string
+  popover?: string
+  popoverForeground?: string
+  primary?: string
+  primaryForeground?: string
+  secondary?: string
+  secondaryForeground?: string
+  muted?: string
+  mutedForeground?: string
+  accent?: string
+  accentForeground?: string
+  destructive?: string
+  destructiveForeground?: string
+  border?: string
+  input?: string
+  ring?: string
+  radius?: string
+  fontFamily?: string
+}
+
+type DataTableModedTheme = {
+  light?: DataTableTokens
+  dark?: DataTableTokens
+}
+
+type DataTableTheme = DataTableTokens | DataTableModedTheme
+```
+
+```ts
+// Theme exports
+import {
+  themePresets,        // ready-made moded presets
+  buildPreset,         // (hue, chroma?) => DataTableModedTheme
+  splitTheme,          // (theme) => { light, dark }
+  tokensToStyle,       // (tokens) => React.CSSProperties
+  tokensToCssBlock,    // (tokens) => "var:val;var:val" string
+  ISOLATE_LIGHT_TOKENS,
+  ISOLATE_DARK_TOKENS,
+} from "@dynostack/react-grid"
+```
+
 ---
 
 ## Compatibility