@dynostack/react-grid 0.1.3 → 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
@@ -91,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.
 
 ---
@@ -248,24 +278,12 @@ rollback, toast notifications, and validation.
 
 ## Theming
 
-All shadcn tokens are supported plus `radius` and `fontFamily`. Anything you omit falls through to the consumer's `:root`.
+The `theme` prop accepts **two shapes**. Pick whichever fits your use case.
 
-### Use a preset
-
-```tsx
-import { DataTable, themePresets } from "@dynostack/react-grid"
-
-<DataTable data={data} columns={columns} theme={themePresets.violet} />
-```
-
-Available presets: `light` · `dark` · `emerald` · `violet` · `amber`.
-
-### Custom tokens
+### Shape 1 — Flat tokens
 
 ```tsx
 <DataTable
-  data={data}
-  columns={columns}
   theme={{
     primary: "oklch(0.6 0.2 200)",
     primaryForeground: "oklch(1 0 0)",
@@ -276,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
@@ -625,7 +729,8 @@ operations and only renders the returned page.
 | `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 }`.
 
@@ -649,6 +754,53 @@ type DataTableDataSource<TData> = {
 }
 ```
 
+```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

package/dist/index.cjs

@@ -2026,57 +2026,148 @@ var TOKEN_TO_VAR = {
   radius: "--radius",
   fontFamily: "--font-family"
 };
-function themeToStyle(theme) {
-  if (!theme) return {};
+function isModed(theme) {
+  if (!theme) return false;
+  return "light" in theme || "dark" in theme;
+}
+function tokensToStyle(tokens) {
+  if (!tokens) return {};
   const out = {};
-  for (const [k, v] of Object.entries(theme)) {
+  for (const [k, v] of Object.entries(tokens)) {
     if (v == null) continue;
     const cssVar = TOKEN_TO_VAR[k];
     if (cssVar) out[cssVar] = v;
   }
   return out;
 }
-var themePresets = {
+function themeToStyle(theme) {
+  if (!theme) return {};
+  if (isModed(theme)) return tokensToStyle(theme.light);
+  return tokensToStyle(theme);
+}
+function splitTheme(theme) {
+  if (!theme) return { light: void 0, dark: void 0 };
+  if (isModed(theme)) return { light: theme.light, dark: theme.dark };
+  return { light: theme, dark: void 0 };
+}
+function buildPreset(hue, chroma = 0.03) {
+  const c = chroma;
+  return {
+    light: {
+      background: `oklch(0.99 ${c * 0.2} ${hue})`,
+      foreground: `oklch(0.18 ${c * 1.2} ${hue})`,
+      card: `oklch(1 0 0)`,
+      cardForeground: `oklch(0.18 ${c * 1.2} ${hue})`,
+      popover: `oklch(1 0 0)`,
+      popoverForeground: `oklch(0.18 ${c * 1.2} ${hue})`,
+      primary: `oklch(0.55 0.2 ${hue})`,
+      primaryForeground: `oklch(0.99 0 0)`,
+      secondary: `oklch(0.96 ${c} ${hue})`,
+      secondaryForeground: `oklch(0.25 ${c * 2} ${hue})`,
+      muted: `oklch(0.96 ${c} ${hue})`,
+      mutedForeground: `oklch(0.5 ${c * 1.5} ${hue})`,
+      accent: `oklch(0.94 ${c * 1.2} ${hue})`,
+      accentForeground: `oklch(0.3 ${c * 3} ${hue})`,
+      destructive: `oklch(0.577 0.245 27.325)`,
+      destructiveForeground: `oklch(0.985 0 0)`,
+      border: `oklch(0.9 ${c * 0.8} ${hue})`,
+      input: `oklch(0.9 ${c * 0.8} ${hue})`,
+      ring: `oklch(0.55 0.2 ${hue} / 0.5)`,
+      radius: "0.625rem"
+    },
+    dark: {
+      background: `oklch(0.16 ${c * 0.6} ${hue})`,
+      foreground: `oklch(0.97 ${c * 0.2} ${hue})`,
+      card: `oklch(0.21 ${c * 0.8} ${hue})`,
+      cardForeground: `oklch(0.97 ${c * 0.2} ${hue})`,
+      popover: `oklch(0.21 ${c * 0.8} ${hue})`,
+      popoverForeground: `oklch(0.97 ${c * 0.2} ${hue})`,
+      primary: `oklch(0.7 0.18 ${hue})`,
+      primaryForeground: `oklch(0.16 ${c * 0.6} ${hue})`,
+      secondary: `oklch(0.27 ${c * 0.8} ${hue})`,
+      secondaryForeground: `oklch(0.97 ${c * 0.2} ${hue})`,
+      muted: `oklch(0.27 ${c * 0.8} ${hue})`,
+      mutedForeground: `oklch(0.7 ${c * 0.5} ${hue})`,
+      accent: `oklch(0.3 ${c * 1.5} ${hue})`,
+      accentForeground: `oklch(0.97 ${c * 0.2} ${hue})`,
+      destructive: `oklch(0.577 0.245 27.325 / 0.6)`,
+      destructiveForeground: `oklch(0.985 0 0)`,
+      border: `oklch(0.27 ${c * 0.8} ${hue})`,
+      input: `oklch(0.27 ${c * 0.8} ${hue})`,
+      ring: `oklch(0.7 0.18 ${hue} / 0.5)`,
+      radius: "0.625rem"
+    }
+  };
+}
+function tokensToCssBlock(tokens) {
+  if (!tokens) return "";
+  const parts = [];
+  for (const [k, v] of Object.entries(tokens)) {
+    if (v == null) continue;
+    const cssVar = TOKEN_TO_VAR[k];
+    if (cssVar) parts.push(`${cssVar}:${v}`);
+  }
+  return parts.join(";");
+}
+var neutral = {
   light: {
     background: "oklch(1 0 0)",
     foreground: "oklch(0.145 0 0)",
     card: "oklch(1 0 0)",
     cardForeground: "oklch(0.145 0 0)",
+    popover: "oklch(1 0 0)",
+    popoverForeground: "oklch(0.145 0 0)",
     primary: "oklch(0.205 0 0)",
     primaryForeground: "oklch(0.985 0 0)",
-    border: "oklch(0.922 0 0)"
+    secondary: "oklch(0.97 0 0)",
+    secondaryForeground: "oklch(0.205 0 0)",
+    muted: "oklch(0.97 0 0)",
+    mutedForeground: "oklch(0.556 0 0)",
+    accent: "oklch(0.97 0 0)",
+    accentForeground: "oklch(0.205 0 0)",
+    destructive: "oklch(0.577 0.245 27.325)",
+    destructiveForeground: "oklch(0.985 0 0)",
+    border: "oklch(0.922 0 0)",
+    input: "oklch(0.922 0 0)",
+    ring: "oklch(0.708 0 0)",
+    radius: "0.625rem"
   },
   dark: {
     background: "oklch(0.145 0 0)",
     foreground: "oklch(0.985 0 0)",
     card: "oklch(0.205 0 0)",
     cardForeground: "oklch(0.985 0 0)",
+    popover: "oklch(0.205 0 0)",
+    popoverForeground: "oklch(0.985 0 0)",
     primary: "oklch(0.985 0 0)",
     primaryForeground: "oklch(0.205 0 0)",
-    border: "oklch(0.269 0 0)"
-  },
-  emerald: {
-    primary: "oklch(0.66 0.15 162)",
-    primaryForeground: "oklch(1 0 0)",
-    accent: "oklch(0.94 0.04 162)",
-    accentForeground: "oklch(0.3 0.1 162)",
-    ring: "oklch(0.66 0.15 162 / 0.5)"
-  },
-  violet: {
-    primary: "oklch(0.55 0.22 285)",
-    primaryForeground: "oklch(1 0 0)",
-    accent: "oklch(0.94 0.04 285)",
-    accentForeground: "oklch(0.3 0.12 285)",
-    ring: "oklch(0.55 0.22 285 / 0.5)"
-  },
-  amber: {
-    primary: "oklch(0.7 0.18 65)",
-    primaryForeground: "oklch(0.2 0 0)",
-    accent: "oklch(0.94 0.05 65)",
-    accentForeground: "oklch(0.3 0.12 65)",
-    ring: "oklch(0.7 0.18 65 / 0.5)"
+    secondary: "oklch(0.269 0 0)",
+    secondaryForeground: "oklch(0.985 0 0)",
+    muted: "oklch(0.269 0 0)",
+    mutedForeground: "oklch(0.708 0 0)",
+    accent: "oklch(0.269 0 0)",
+    accentForeground: "oklch(0.985 0 0)",
+    destructive: "oklch(0.577 0.245 27.325 / 0.6)",
+    destructiveForeground: "oklch(0.985 0 0)",
+    border: "oklch(0.269 0 0)",
+    input: "oklch(0.269 0 0)",
+    ring: "oklch(0.439 0 0)",
+    radius: "0.625rem"
   }
 };
+var themePresets = {
+  neutral,
+  light: { light: neutral.light },
+  dark: { light: neutral.dark },
+  violet: buildPreset(285),
+  emerald: buildPreset(162),
+  amber: buildPreset(65),
+  rose: buildPreset(15),
+  sky: buildPreset(235),
+  slate: buildPreset(240, 0.015)
+};
+var ISOLATE_LIGHT_TOKENS = neutral.light;
+var ISOLATE_DARK_TOKENS = neutral.dark;
 function getPinningStyles(column) {
   const isPinned = column.getIsPinned();
   if (!isPinned) return {};
@@ -2241,7 +2332,8 @@ function DataTable({
   features,
   labels: labelsProp,
   density = "default",
-  theme
+  theme,
+  isolate = false
 }) {
   const labels = { ...DEFAULT_LABELS, ...labelsProp };
   const f = {
@@ -2257,7 +2349,20 @@ function DataTable({
     reordering: features?.reordering ?? true,
     pinning: features?.pinning ?? true
   };
-  const themeStyle = themeToStyle(theme);
+  const rawInstanceId = react.useId();
+  const instanceId = react.useMemo(
+    () => `dyno-grid-${rawInstanceId.replace(/[^a-zA-Z0-9]/g, "")}`,
+    [rawInstanceId]
+  );
+  const { lightStyle, darkCss } = react.useMemo(() => {
+    const { light, dark } = splitTheme(theme);
+    const lightTokens = isolate ? { ...ISOLATE_LIGHT_TOKENS, ...light ?? {} } : light;
+    const darkTokens = isolate ? { ...ISOLATE_DARK_TOKENS, ...dark ?? light ?? {} } : dark;
+    return {
+      lightStyle: tokensToStyle(lightTokens),
+      darkCss: darkTokens ? tokensToCssBlock(darkTokens) : null
+    };
+  }, [theme, isolate]);
   const [sorting, setSorting] = react.useState([]);
   const [columnFilters, setColumnFilters] = react.useState([]);
   const [internalGlobalFilter, setInternalGlobalFilter] = react.useState("");
@@ -2636,13 +2741,19 @@ function DataTable({
       children: /* @__PURE__ */ jsxRuntime.jsxs(
         "div",
         {
+          "data-dyno-grid": instanceId,
           className: cn(
             "flex flex-col rounded-lg border bg-card text-card-foreground shadow-sm",
             DENSITY_CLASS[density],
             className
           ),
-          style: themeStyle,
+          style: lightStyle,
           children: [
+            darkCss && /* @__PURE__ */ jsxRuntime.jsxs("style", { children: [
+              `@media (prefers-color-scheme: dark){[data-dyno-grid="${instanceId}"]{${darkCss}}}`,
+              `.dark [data-dyno-grid="${instanceId}"]{${darkCss}}`,
+              `[data-dyno-grid="${instanceId}"].dark{${darkCss}}`
+            ] }),
             /* @__PURE__ */ jsxRuntime.jsx(
               DataTableToolbar,
               {
@@ -2836,15 +2947,21 @@ exports.DataTablePagination = DataTablePagination;
 exports.DataTableRowActions = DataTableRowActions;
 exports.DataTableToolbar = DataTableToolbar;
 exports.EditableCell = EditableCell;
+exports.ISOLATE_DARK_TOKENS = ISOLATE_DARK_TOKENS;
+exports.ISOLATE_LIGHT_TOKENS = ISOLATE_LIGHT_TOKENS;
 exports.booleanFilterFn = booleanFilterFn;
+exports.buildPreset = buildPreset;
 exports.dateFilterFn = dateFilterFn;
 exports.exportToCsv = exportToCsv;
 exports.exportToExcel = exportToExcel;
 exports.isFilterActive = isFilterActive;
 exports.numberFilterFn = numberFilterFn;
 exports.setFilterFn = setFilterFn;
+exports.splitTheme = splitTheme;
 exports.textFilterFn = textFilterFn;
 exports.themePresets = themePresets;
 exports.themeToStyle = themeToStyle;
+exports.tokensToCssBlock = tokensToCssBlock;
+exports.tokensToStyle = tokensToStyle;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map