Expand styling and customization docs

Author: nstepien

README.md

@@ -120,9 +120,299 @@ function App() {
 }
 ```
 
-## Theming
+## Styling and Customization
 
-Set `--rdg-color-scheme: light/dark` at the `:root` to control the color theme. The light or dark themes can be enforced using the `rdg-light` or `rdg-dark` classes.
+The DataGrid provides multiple ways to customize its appearance and behavior.
+
+### Light/Dark Themes
+
+The DataGrid supports both light and dark color schemes out of the box using CSS's `light-dark()` function. The theme automatically adapts based on the user's system preference when `color-scheme: light dark;` is set.
+
+To enforce a specific theme, we recommend setting the standard `color-scheme` CSS property on the `:root`:
+
+```css
+:root {
+  color-scheme: light; /* or 'dark', or 'light dark' for auto */
+}
+```
+
+Alternatively, you can add the `rdg-light` or `rdg-dark` class to individual grids:
+
+```tsx
+// Force light theme
+<DataGrid className="rdg-light" columns={columns} rows={rows} />
+
+// Force dark theme
+<DataGrid className="rdg-dark" columns={columns} rows={rows} />
+```
+
+### CSS Variables
+
+The DataGrid supports the following CSS variables for customization:
+
+```css
+.rdg {
+  /* Selection */
+  --rdg-selection-width: 2px;
+  --rdg-selection-color: hsl(207, 75%, 66%);
+
+  /* Typography */
+  --rdg-font-size: 14px;
+
+  /* Colors (using light-dark() for automatic theme switching) */
+  --rdg-color: light-dark(#000, #ddd);
+  --rdg-background-color: light-dark(hsl(0deg 0% 100%), hsl(0deg 0% 13%));
+
+  /* Header */
+  --rdg-header-background-color: light-dark(hsl(0deg 0% 97.5%), hsl(0deg 0% 10.5%));
+  --rdg-header-draggable-background-color: light-dark(hsl(0deg 0% 90.5%), hsl(0deg 0% 17.5%));
+
+  /* Rows */
+  --rdg-row-hover-background-color: light-dark(hsl(0deg 0% 96%), hsl(0deg 0% 9%));
+  --rdg-row-selected-background-color: light-dark(hsl(207deg 76% 92%), hsl(207deg 76% 42%));
+  --rdg-row-selected-hover-background-color: light-dark(hsl(207deg 76% 88%), hsl(207deg 76% 38%));
+
+  /* Borders */
+  --rdg-border-width: 1px;
+  --rdg-border-color: light-dark(#ddd, #444);
+  --rdg-summary-border-width: calc(var(--rdg-border-width) * 2);
+  --rdg-summary-border-color: light-dark(#aaa, #555);
+
+  /* Frozen columns */
+  --rdg-cell-frozen-box-shadow: 2px 0 5px -2px rgba(136, 136, 136, 0.3);
+
+  /* Checkboxes */
+  --rdg-checkbox-focus-color: hsl(207deg 100% 69%);
+}
+```
+
+Example of customizing colors:
+
+```css
+.my-custom-grid {
+  --rdg-background-color: #f0f0f0;
+  --rdg-selection-color: #ff6b6b;
+  --rdg-font-size: 16px;
+}
+```
+
+```tsx
+<DataGrid className="my-custom-grid" columns={columns} rows={rows} />
+```
+
+### Standard Props
+
+The DataGrid accepts standard `className` and `style` props:
+
+```tsx
+<DataGrid
+  columns={columns}
+  rows={rows}
+  className="my-grid custom-theme"
+  style={{ height: '600px', border: '2px solid navy' }}
+/>
+```
+
+### Row and Cell Styling
+
+#### Row Heights
+
+Control row heights using the [`rowHeight`](#rowheight-maybenumber--row-r--number) prop:
+
+```tsx
+// Fixed height for all rows
+<DataGrid columns={columns} rows={rows} rowHeight={50} />
+
+// Dynamic height per row
+<DataGrid
+  columns={columns}
+  rows={rows}
+  rowHeight={(row) => row.isExpanded ? 100 : 35}
+/>
+```
+
+You can also customize header and summary row heights:
+
+```tsx
+<DataGrid
+  columns={columns}
+  rows={rows}
+  rowHeight={35}
+  headerRowHeight={45}
+  summaryRowHeight={40}
+  topSummaryRows={topSummaryRows}
+/>
+```
+
+#### Row Classes
+
+Apply custom CSS classes to rows using the [`rowClass`](#rowclass-mayberow-r-rowidx-number--maybestring) prop:
+
+```tsx
+<DataGrid
+  columns={columns}
+  rows={rows}
+  rowClass={(row, rowIdx) => {
+    if (row.status === 'error') return 'row-error';
+    if (rowIdx % 2 === 0) return 'row-even';
+    return 'row-odd';
+  }}
+/>
+```
+
+```css
+.row-error {
+  background-color: #fee;
+  color: #c00;
+}
+
+.row-even {
+  background-color: #f9f9f9;
+}
+```
+
+For header rows, use the [`headerRowClass`](#headerrowclass-maybestring) prop:
+
+```tsx
+<DataGrid columns={columns} rows={rows} headerRowClass="sticky-header" />
+```
+
+#### Cell Classes
+
+Apply custom CSS classes to cells using the `cellClass` property in column definitions:
+
+```tsx
+const columns: Column<Row>[] = [
+  {
+    key: 'status',
+    name: 'Status',
+    cellClass: (row) => `status-${row.status.toLowerCase()}`
+  },
+  {
+    key: 'price',
+    name: 'Price',
+    cellClass: 'text-right' // Static class
+  }
+];
+```
+
+```css
+.status-active {
+  color: green;
+  font-weight: bold;
+}
+
+.status-inactive {
+  color: gray;
+}
+
+.text-right {
+  text-align: right;
+}
+```
+
+You can also use `headerCellClass` and `summaryCellClass` for header and summary cells respectively.
+
+#### Column Widths
+
+Control column widths using the `width`, `minWidth`, and `maxWidth` properties:
+
+```tsx
+const columns: Column<Row>[] = [
+  {
+    key: 'id',
+    name: 'ID',
+    width: 80, // Fixed width
+    resizable: false
+  },
+  {
+    key: 'name',
+    name: 'Name',
+    width: '30%', // Percentage width
+    minWidth: 100,
+    maxWidth: 400
+  },
+  {
+    key: 'description',
+    name: 'Description'
+    // No width specified - automatically sized
+  }
+];
+```
+
+Enable column resizing by setting `resizable: true` on individual columns or use [`defaultColumnOptions`](#defaultcolumnoptions-maybedefaultcolumnoptionsr-sr) to apply it to all columns:
+
+```tsx
+<DataGrid
+  columns={columns}
+  rows={rows}
+  defaultColumnOptions={{
+    resizable: true,
+    sortable: true
+  }}
+/>
+```
+
+### Custom Renderers
+
+Replace default components with custom implementations using the [`renderers`](#renderers-mayberendererstrow-tsummaryrow) prop:
+
+```tsx
+const customRenderers = {
+  // Custom row component
+  renderRow(key, props) {
+    return <CustomRow key={key} {...props} />;
+  },
+
+  // Custom cell component
+  renderCell(key, props) {
+    return <CustomCell key={key} {...props} />;
+  },
+
+  // Custom checkbox component
+  renderCheckbox(props) {
+    return <CustomCheckbox {...props} />;
+  },
+
+  // Custom sort status indicator
+  renderSortStatus(props) {
+    return <CustomSortIcon {...props} />;
+  },
+
+  // Custom empty state
+  noRowsFallback: <div>No data available</div>
+};
+
+<DataGrid columns={columns} rows={rows} renderers={customRenderers} />;
+```
+
+Columns can also have custom renderers:
+
+```tsx
+const columns: Column<Row>[] = [
+  {
+    key: 'avatar',
+    name: 'Avatar',
+    renderCell(props) {
+      return <img src={props.row.avatarUrl} alt={props.row.name} />;
+    }
+  },
+  {
+    key: 'status',
+    name: 'Status',
+    renderHeaderCell(props) {
+      return (
+        <div>
+          <strong>{props.column.name}</strong>
+          <InfoIcon />
+        </div>
+      );
+    }
+  }
+];
+```
+
+See the [Renderers section](#renderers-mayberendererstrow-tsummaryrow) for full type definitions and examples.
 
 ## API Reference
 

package.json

@@ -50,7 +50,7 @@
     "typecheck": "tsc --build"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.3.8",
+    "@biomejs/biome": "2.3.10",
     "@eslint-react/eslint-plugin": "^2.3.12",
     "@eslint/markdown": "^7.5.1",
     "@faker-js/faker": "^10.0.0",
@@ -82,7 +82,7 @@
     "react": "^19.2.1",
     "react-dom": "^19.2.1",
     "rolldown": "^1.0.0-beta.51",
-    "rolldown-plugin-dts": "^0.18.0",
+    "rolldown-plugin-dts": "^0.19.1",
     "typescript": "~5.9.2",
     "vite": "npm:rolldown-vite@^7.2.5",
     "vitest": "^4.0.15",

src/style/core.ts

@@ -31,15 +31,13 @@ const root = css`
     --rdg-checkbox-focus-color: hsl(207deg 100% 69%);
 
     &.rdg-dark {
-      --rdg-color-scheme: dark;
+      color-scheme: dark;
     }
 
     &.rdg-light {
-      --rdg-color-scheme: light;
+      color-scheme: light;
     }
 
-    color-scheme: var(--rdg-color-scheme, light dark);
-
     &:dir(rtl) {
       --rdg-cell-frozen-box-shadow: -2px 0 5px -2px rgba(136, 136, 136, 0.3);
     }

website/root.css

@@ -6,17 +6,18 @@ body {
 }
 
 :root {
+  color-scheme: light dark;
+
   &:has([value='light']:checked) {
-    --rdg-color-scheme: light;
+    color-scheme: light;
   }
 
   &:has([value='dark']:checked) {
-    --rdg-color-scheme: dark;
+    color-scheme: dark;
   }
 }
 
 body {
-  color-scheme: var(--rdg-color-scheme, light dark);
   background-color: light-dark(#fff, hsl(0deg 0% 10%));
   color: light-dark(#111, #fff);
 }