release: @datasketch/monkeytab@0.6.0

Author: jpmarindiaz

.gitignore

@@ -12,3 +12,7 @@ deno.lock
 .local/
 CLAUDE.md
 .claude/
+# Sync-owner-only config, regenerated on every sync. Public
+# contributors don't have .local/, so committing it would give
+# them broken references. See CLAUDE.md for context.
+deno.json

BROWSER.md

@@ -174,9 +174,82 @@ interface MonkeyTableColumn {
   maxWidth?: number;                       // maximum width (default: 600)
   sortable?: boolean;                      // can this column be sorted (default: true)
   align?: 'left' | 'center' | 'right';     // cell text alignment
+  color?: string | CellColorFn;            // column color — static string or per-cell fn
 }
+
+type CellColorFn = (
+  row: Record<string, Value>,
+  value: Value,
+  fieldId: string,
+) => string | undefined;
 ```
 
+### Column coloring (`column.color`)
+
+Three shapes, from simplest to most flexible:
+
+- **Static** (`string`) — any CSS color. Every cell in the column plus the header gets a soft tint of that color. Good for marking a non-editable column, flagging a column that needs attention, or grouping related columns visually.
+- **Rule array** (`ColorRule[]`) — JSON-serializable conditional formatting. Each rule is `{ when: ColorCondition, color: string }`. Rules evaluate top-down; first match wins. Header stays default in this mode. Works in the JSON config form.
+- **Function** (`CellColorFn`) — `(row, value, fieldId) => string | undefined`. For anything the rule array can't express: palettes, numeric interpolation, cross-field math. Header stays default. Prop-API only (functions aren't JSON-serializable).
+
+Tints always blend with `color-mix(… 30%, white)` so dark colors stay readable, and compose cleanly with the row-level `colorBy` tint and the in-search yellow highlight.
+
+```tsx
+<MonkeyTable
+  columns={[
+    { id: 'Name' },
+    // Static: the whole "CreatedAt" column + header reads as a read-only band.
+    { id: 'CreatedAt', type: 'Date', editable: false, color: '#f1f5f9' },
+    // Rule array: red < 50, green ≥ 90, else untouched. Also works in JSON config.
+    {
+      id: 'Score',
+      type: 'Number',
+      color: [
+        { when: { op: 'lt', value: 50 }, color: '#fee2e2' },
+        { when: { op: 'gte', value: 90 }, color: '#dcfce7' },
+      ],
+    },
+    // Function: same effect but with a mid-range yellow band, and arbitrary logic.
+    {
+      id: 'Priority',
+      color: (_row, value) => {
+        if (value === 'P0') return '#fecaca';
+        if (value === 'P1') return '#fed7aa';
+        return undefined;
+      },
+    },
+  ]}
+  rows={rows}
+/>
+```
+
+**Rule operators.** `ColorCondition` is a tagged union keyed by `op`:
+
+| op | value(s) | Matches when |
+|---|---|---|
+| `equals` / `notEquals` | `value: unknown` | strict `===` / `!==` |
+| `lt` / `lte` / `gt` / `gte` | `value: number` | numeric comparison (non-numeric cells never match) |
+| `contains` / `notContains` | `value: string` | case-insensitive substring on string cells |
+| `empty` / `notEmpty` | — | `null`, `undefined`, `""`, or `[]` |
+| `in` / `notIn` | `values: unknown[]` | value is / isn't one of the list |
+
+Every operator accepts an optional `field: string` to compare against a **different** column's value instead of the cell's own — useful for "tint the `Status` cell when `Owner` is empty":
+
+```ts
+color: [
+  { when: { op: 'empty', field: 'Owner' }, color: '#fef3c7' },
+]
+```
+
+For callers who want to reuse the same evaluator outside the grid (e.g., in a summary widget), `evaluateColorRules(rules, row, value)` is exported too:
+
+```ts
+import { evaluateColorRules } from '@datasketch/monkeytab';
+const tint = evaluateColorRules(col.color as ColorRule[], row, row.Score);
+```
+
+In the JSON config form (`<MonkeyTableFromConfig>`), `string` and `ColorRule[]` are both accepted. The function form stays prop-API-only.
+
 ---
 
 ## Field Types
@@ -243,6 +316,7 @@ const config: MonkeyTableConfig = {
 interface MonkeyTableConfig {
   schemaVersion?: number;              // reserved for future migrators
   columns: MonkeyTableConfigColumn[];  // same as MonkeyTableColumn, minus render/icon
+                                        //   and with color narrowed to string
   rows: Array<Record<string, Value>>;
   settings?: MonkeyTableConfigSettings;
 }
@@ -252,7 +326,9 @@ interface MonkeyTableConfig {
 above — `editable`, `height`, `pageSize`, `locale`, `groupBy`, `sortBy`,
 `dateDisplayFormat`, etc. Anything not serializable (React handlers, custom
 renderers/editors, `render`/`icon` on a column, `functions`/`constraints`,
-`presence`) stays as ordinary component props on `<MonkeyTableFromConfig>`.
+`presence`, conditional-coloring functions) stays as ordinary component props
+on `<MonkeyTableFromConfig>`. Static `column.color` (CSS string) is allowed
+in the config; the function form is prop-API-only.
 
 ### resolveConfig
 

CHANGELOG.md

@@ -6,6 +6,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.6.0] — 2026-04-19
+
+### New
+- **Column coloring (`column.color`)** — three shapes, same prop. Pass a CSS color string to tint a whole column (every cell + the header) with a soft blend — good for flagging a non-editable column or grouping related columns visually. Pass a `ColorRule[]` (`{ when: { op, value/values, field? }, color }`) for JSON-serializable Google-Sheets-style conditional formatting; rules evaluate top-down and the first match wins. Operators include `equals`/`notEquals`, `lt`/`lte`/`gt`/`gte`, `contains`/`notContains`, `empty`/`notEmpty`, and `in`/`notIn`; each can optionally compare a different field. For anything the rule array can't express (palettes, numeric interpolation, cross-field math), pass a `(row, value, fieldId) => string | undefined` function instead — prop-API only. The evaluator is exported as `evaluateColorRules(rules, row, value)` so the same rules can be reused outside the grid. See [BROWSER.md → Column coloring](./BROWSER.md#column-coloring-columncolor).
+
+### Fixed
+- **Header overflow fade now tints with the column** — when a column uses `color` to tint its header, the right-edge fade gradient blends into the tinted background instead of showing a strip of default gray. Symmetric with the row-background fade that already respected `colorBy`.
+
 ## [0.5.0] — 2026-04-19
 
 ### New
@@ -118,7 +126,8 @@ First public release.
 - `onUpload` prop — bring your own file upload (S3, Cloudinary, etc.)
 - Drag-and-drop and paste support for Image cells
 
-[Unreleased]: https://github.com/datasketch/monkeytab/compare/v0.5.0...HEAD
+[Unreleased]: https://github.com/datasketch/monkeytab/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/datasketch/monkeytab/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/datasketch/monkeytab/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/datasketch/monkeytab/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/datasketch/monkeytab/compare/v0.2.1...v0.3.0

examples/browser-standalone/main.tsx

@@ -47,15 +47,36 @@ const COLUMNS = [
 
 const COLUMN_OPTIONS_COLUMNS = [
   { id: 'Product', width: 200, minWidth: 150, maxWidth: 300 },
-  { id: 'SKU', width: 120, editable: false, sortable: false },
+  // Static `color`: the whole SKU column (including its header) reads as a soft
+  // read-only band. Good for flagging columns the user shouldn't touch.
+  { id: 'SKU', width: 120, editable: false, sortable: false, color: '#f1f5f9' },
   { id: 'Category', type: 'SingleSelect' as const, width: 140, options: { options: [
     { value: 'Electronics', label: 'Electronics', color: '#dbeafe' },
     { value: 'Clothing', label: 'Clothing', color: '#fce7f3' },
     { value: 'Food', label: 'Food', color: '#dcfce7' },
     { value: 'Books', label: 'Books', color: '#fef3c7' },
   ]}},
-  { id: 'Price', type: 'Number' as const, width: 110, align: 'right' as const, options: { precision: 2 } },
-  { id: 'Stock', type: 'Number' as const, width: 90, align: 'center' as const, editable: false },
+  // Rule-array `color`: JSON-serializable conditional formatting. Rules evaluate
+  // top-down — the first match wins. Red for high-ticket items, pale yellow for
+  // cheap ones. Works in `<MonkeyTableFromConfig>` too (same JSON shape).
+  { id: 'Price', type: 'Number' as const, width: 110, align: 'right' as const, options: { precision: 2 },
+    color: [
+      { when: { op: 'gte' as const, value: 100 }, color: '#fee2e2' },
+      { when: { op: 'lt' as const, value: 25 }, color: '#fef9c3' },
+    ],
+  },
+  // Function `color`: escape hatch for logic the rule array can't express —
+  // here, a three-tier band built from the numeric value. Header stays default
+  // (no row to evaluate against). Prop-API only (not JSON-serializable).
+  { id: 'Stock', type: 'Number' as const, width: 90, align: 'center' as const, editable: false,
+    color: (_row: Record<string, unknown>, value: unknown) => {
+      if (typeof value !== 'number') return undefined;
+      if (value === 0) return '#fecaca';      // out of stock
+      if (value < 100) return '#fed7aa';      // low
+      if (value > 500) return '#bbf7d0';      // overstocked
+      return undefined;
+    },
+  },
   { id: 'Available', type: 'Boolean' as const, width: 100, align: 'center' as const },
   { id: 'Notes', width: 250, minWidth: 150, maxWidth: 500 },
 ];
@@ -980,9 +1001,49 @@ function App() {
   const [ghostGrid, setGhostGrid] = useState(true);
   const [groupBy, setGroupBy] = useState<string | null>(null);
   const [colorBy, setColorBy] = useState<string | null>(null);
+  // Runtime column-coloring: pick a column id + a CSS color and it's applied
+  // as a static `column.color` string on the active tab's table. Demonstrates
+  // that the prop works live; same shape you'd put in a JSON config.
+  const [userColumnId, setUserColumnId] = useState<string | null>(null);
+  const [userColumnColor, setUserColumnColor] = useState<string>('#fde68a');
 
   const locale = language === 'es' ? 'es-CO' : 'en-US';
 
+  // Which column set the toolbar controls (Row color + Column color) should
+  // address for the currently-active tab. Tabs not listed here are wired
+  // inside sub-components — the toolbar dropdowns will show "None" only and
+  // clear when the user switches to them.
+  const TAB_COLUMNS: Record<string, ReadonlyArray<{ id: string; type?: string }>> = useMemo(() => ({
+    editable: COLUMNS,
+    columns: COLUMN_OPTIONS_COLUMNS,
+    readonly: METRICS_COLUMNS,
+  }), []);
+  const activeColumnSet = TAB_COLUMNS[tab] ?? [];
+
+  // If the selected column / colorBy field doesn't exist on the new tab,
+  // silently clear — the control shouldn't dangle a stale selection.
+  useEffect(() => {
+    if (userColumnId && !activeColumnSet.some((c) => c.id === userColumnId)) {
+      setUserColumnId(null);
+    }
+    if (colorBy && !activeColumnSet.some((c) => c.id === colorBy)) {
+      setColorBy(null);
+    }
+  }, [tab, activeColumnSet, userColumnId, colorBy]);
+
+  // Overlay the user's color onto the active tab's columns. Leaves everything
+  // else alone (including per-column `color` that was already set in source —
+  // the user's pick only wins for the column they picked).
+  const overlayUserColor = <T extends { id: string }>(cols: ReadonlyArray<T>): T[] => {
+    if (!userColumnId) return cols as T[];
+    return cols.map((c) =>
+      c.id === userColumnId ? ({ ...c, color: userColumnColor } as T) : c,
+    );
+  };
+  const editableColumns = useMemo(() => overlayUserColor(COLUMNS), [userColumnId, userColumnColor]);
+  const columnsTabColumns = useMemo(() => overlayUserColor(COLUMN_OPTIONS_COLUMNS), [userColumnId, userColumnColor]);
+  const readonlyTabColumns = useMemo(() => overlayUserColor(METRICS_COLUMNS), [userColumnId, userColumnColor]);
+
   const handleSortChange = (fieldId: string | null, direction: 'asc' | 'desc' | null) => {
     setSortBy(fieldId);
     setSortDirection(direction);
@@ -1042,20 +1103,58 @@ function App() {
             </select>
           </label>
           <label style={{ fontSize: '14px', display: 'inline-flex', alignItems: 'center', gap: '6px' }}>
-            Color:
+            Row color:
             <select
               value={colorBy ?? ''}
               onChange={(e) => setColorBy(e.target.value || null)}
               style={{ padding: '2px 6px', fontSize: '13px', borderRadius: '4px', border: '1px solid #d1d5db' }}
+              disabled={activeColumnSet.length === 0}
+              title={activeColumnSet.length === 0
+                ? 'This tab runs inside a sub-component — row coloring is wired there, not at the toolbar'
+                : 'Row background tint from a SingleSelect / MultiSelect / Boolean field'}
             >
               <option value="">None</option>
-              {COLUMNS
+              {activeColumnSet
                 .filter((c) => (['SingleSelect', 'MultiSelect', 'Boolean'] as string[]).includes(c.type as string))
                 .map((c) => (
                   <option key={c.id} value={c.id}>{c.id}</option>
                 ))}
             </select>
           </label>
+          <label style={{ fontSize: '14px', display: 'inline-flex', alignItems: 'center', gap: '6px' }}>
+            Column color:
+            <select
+              value={userColumnId ?? ''}
+              onChange={(e) => setUserColumnId(e.target.value || null)}
+              style={{ padding: '2px 6px', fontSize: '13px', borderRadius: '4px', border: '1px solid #d1d5db' }}
+              disabled={activeColumnSet.length === 0}
+              title={activeColumnSet.length === 0
+                ? 'This tab runs inside a sub-component — column coloring is wired there, not at the toolbar'
+                : 'Pick a column to tint (header + all cells) with the color next to this dropdown'}
+            >
+              <option value="">None</option>
+              {activeColumnSet.map((c) => (
+                <option key={c.id} value={c.id}>{c.id}</option>
+              ))}
+            </select>
+            <input
+              type="color"
+              value={userColumnColor}
+              onChange={(e) => setUserColumnColor(e.target.value)}
+              disabled={!userColumnId}
+              style={{
+                width: '28px',
+                height: '24px',
+                padding: 0,
+                border: '1px solid #d1d5db',
+                borderRadius: '4px',
+                cursor: userColumnId ? 'pointer' : 'not-allowed',
+                opacity: userColumnId ? 1 : 0.4,
+                background: 'none',
+              }}
+              title={userColumnId ? `Tint the "${userColumnId}" column with this color` : 'Pick a column first'}
+            />
+          </label>
           {tab === 'editable' && (
             <>
               <span style={{ fontSize: '14px', color: '#6b7280' }}>
@@ -1082,7 +1181,7 @@ function App() {
             <div className="desc">Click cells to edit. Add/delete rows. Drag columns to reorder. Try the filter and search.</div>
             <div className="table-container">
               <MonkeyTable
-                columns={COLUMNS}
+                columns={editableColumns}
                 rows={INITIAL_ROWS}
                 onChange={handleChange}
                 sortBy={sortBy}
@@ -1146,12 +1245,22 @@ function App() {
           <div className="example" style={{ display: 'flex', flexDirection: 'column', minHeight: 'calc(100vh - 200px)' }}>
             <h2>Column Options</h2>
             <div className="desc">
-              Per-column <code>width</code>, <code>minWidth</code>, <code>maxWidth</code>, <code>align</code>, <code>editable</code>, and <code>sortable</code>.
-              SKU and Stock are read-only. SKU is not sortable. Price and Stock are right/center-aligned.
+              Per-column <code>width</code>, <code>minWidth</code>, <code>maxWidth</code>, <code>align</code>, <code>editable</code>, <code>sortable</code>, and
+              {' '}<strong><code>color</code></strong>.
+              SKU and Stock are read-only; SKU is not sortable; Price and Stock are right/center-aligned.
+              <br />
+              <br />
+              <strong>Column coloring demo</strong> — three shapes, one prop:
+              <ul style={{ margin: '6px 0 0 1.2em', padding: 0 }}>
+                <li><strong>Static</strong>: <code>SKU</code> uses <code>color: '#f1f5f9'</code> — whole column + header get a soft read-only band.</li>
+                <li><strong>Rule array</strong>: <code>Price</code> uses <code>color: [&#123; when: &#123; op: 'gte', value: 100 &#125;, color: '#fee2e2' &#125;, &#123; when: &#123; op: 'lt', value: 25 &#125;, color: '#fef9c3' &#125;]</code>. Top-down, first match wins. JSON-serializable, so this works verbatim in <code>&lt;MonkeyTableFromConfig&gt;</code>.</li>
+                <li><strong>Function</strong>: <code>Stock</code> uses <code>color: (row, value) =&gt; …</code> with a three-tier band (red at 0, orange &lt; 100, green &gt; 500). Escape hatch for anything rule data can't express.</li>
+              </ul>
+              Tints compose with row-level coloring (the <em>Row color</em> dropdown on the Editable Table tab) and the search yellow highlight. Higher-priority states — selection, range, drag, Computed fields — still override.
             </div>
             <div className="table-container" style={{ flex: 1, height: 'auto' }}>
               <MonkeyTable
-                columns={COLUMN_OPTIONS_COLUMNS}
+                columns={columnsTabColumns}
                 rows={COLUMN_OPTIONS_ROWS}
                 ghostGrid={ghostGrid}
                 height="100%"
@@ -1175,7 +1284,7 @@ function App() {
             <div className="desc">Set <code>editable=false</code> to display data without mutation controls.</div>
             <div className="table-container">
               <MonkeyTable
-                columns={METRICS_COLUMNS}
+                columns={readonlyTabColumns}
                 rows={METRICS_ROWS}
                 editable={false}
                 height="100%"

examples/browser-standalone/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-standalone",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "private": true,
   "type": "module",
   "scripts": {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datasketch/monkeytab",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Embeddable, editable React table component",
   "keywords": [
     "react",