feat(spec): warn when a grid view's rowColor declares no colors map (#15101)

`RowColorConfigSchema` requires `field` and leaves `colors` optional, so
`rowColor: { field: 'status' }` parses, publishes and colours nothing: the
only renderer that reads the block bails unless both are present. Every key
involved is declared and live, so neither unknown-key rejection nor the
liveness ledger can see it — the ADR-0078 silent half.

`checkViewCompleteness` now emits `view/row-color-without-colors` (warning,
path `rowColor.colors`) when a grid list view binds a non-empty
`rowColor.field` and declares no usable `colors` map. Both spellings of "no
map" are flagged: `colors` absent (the resolver's own guard returns early)
and `colors: {}` (truthy, so it passes that guard, then matches no value).
The message names the view, the bound field and the runtime line; the fix
prescribes the map.

Scope is measured from the renderer, not inferred from the schema: the rule
fires only on the view type whose adapter forwards `rowColor` at all. On the
other list view types the block is inert for a different reason, and
prescribing a colours map would not fix it — recorded in the module as a
non-rule rather than enforced.

`RowColorConfigSchema.field`'s describe is rewritten so it no longer reads as
if a colour is derived without a map. The accept set does not move: `colors`
stays optional and no member is added, removed or narrowed.


Claude-Session: https://claude.ai/code/session_0174WZTU6XcFcS7g2kykC53i

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

.changeset/row-color-without-colors.md

@@ -0,0 +1,31 @@
+---
+"@objectstack/spec": patch
+---
+
+`view/row-color-without-colors` — a new author-time completeness warning for a `rowColor` block that colours nothing
+
+`RowColorConfigSchema` requires `field` and leaves `colors` optional, so a list view
+authored as `rowColor: { field: 'status' }` parses, publishes and colours no row: the
+only renderer that reads the block needs BOTH keys, and its row-className resolver
+returns before it reads a record when the map is missing. Every key involved is a
+declared, live one, so neither unknown-key rejection nor the liveness ledger could see
+it — the ADR-0078 silent half, in the family `validateFunctionalCompleteness` already
+gates (a `summary` with no `summaryOperations`, a `select` with no `options`).
+
+`checkViewCompleteness` now emits a `warning` finding at `rowColor.colors` when a grid
+list view binds a non-empty `rowColor.field` and declares no usable `colors` map. Both
+spellings of "no map" are flagged — `colors` absent, and `colors: {}`, which passes the
+renderer's own guard and then matches no value, so it is the same dead shape spelled
+out. The finding names the view, the bound field and the runtime line that makes it
+true, and prescribes the map.
+
+The accept set does not move: `colors` stays optional and nothing is added, removed or
+narrowed. Only the diagnostic is new, plus a rewritten `.describe()` on
+`RowColorConfigSchema.field` that no longer reads as if a colour is derived without a
+map.
+
+Scope is measured, not assumed: the rule fires only on the view type whose renderer
+actually reads `rowColor` (the grid branch of the list-view adapter's per-type props
+switch). On a kanban or gallery view the block is inert too, but for a different
+reason — the key is never forwarded there at all — so prescribing a `colors` map would
+be a false prescription. That is recorded in the module, not enforced.

content/docs/references/ui/view.mdx

@@ -1009,7 +1009,7 @@ View filter rule
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **field** | `string` | ✅ | Field to derive color from (typically a select/status field) |
+| **field** | `string` | ✅ | Field whose value is looked up in the `colors` map below to pick a row colour (typically a select/status field). The map is what does the colouring — with no `colors`, no row is ever coloured, whatever this field holds. Author-time diagnostic `view/row-color-without-colors` reports that combination. |
 | **colors** | `Record<string, string>` | optional | Map of field value to color (hex/token) |
 
 ### Nested Shape: `ListView.bulkActionDefs[number]`
@@ -1395,7 +1395,7 @@ View filter rule
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **field** | `string` | ✅ | Field to derive color from (typically a select/status field) |
+| **field** | `string` | ✅ | Field whose value is looked up in the `colors` map below to pick a row colour (typically a select/status field). The map is what does the colouring — with no `colors`, no row is ever coloured, whatever this field holds. Author-time diagnostic `view/row-color-without-colors` reports that combination. |
 | **colors** | `Record<string, string>` | optional | Map of field value to color (hex/token) |
 
 ### Nested Shape: `ObjectListView.bulkActionDefs[number]`
@@ -1553,7 +1553,7 @@ Row color configuration based on field values
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **field** | `string` | ✅ | Field to derive color from (typically a select/status field) |
+| **field** | `string` | ✅ | Field whose value is looked up in the `colors` map below to pick a row colour (typically a select/status field). The map is what does the colouring — with no `colors`, no row is ever coloured, whatever this field holds. Author-time diagnostic `view/row-color-without-colors` reports that combination. |
 | **colors** | `Record<string, string>` | optional | Map of field value to color (hex/token) |
 
 

packages/spec/api-surface/kernel.json

@@ -442,6 +442,7 @@
     "UpgradeSnapshotParsed (type)",
     "UpgradeSnapshotSchema (const)",
     "VIEW_LAYOUT_WITHOUT_BINDING (const)",
+    "VIEW_ROW_COLOR_WITHOUT_COLORS (const)",
     "VIEW_TREE_WITHOUT_PARENT_FIELD (const)",
     "ValidationError (type)",
     "ValidationErrorSchema (const)",

packages/spec/export-origins/kernel.json

@@ -442,6 +442,7 @@
     "UpgradeSnapshotParsed": "src/kernel/package-upgrade.zod.ts#UpgradeSnapshotParsed (type)",
     "UpgradeSnapshotSchema": "src/kernel/package-upgrade.zod.ts#UpgradeSnapshotSchema (const)",
     "VIEW_LAYOUT_WITHOUT_BINDING": "src/kernel/functional-completeness.ts#VIEW_LAYOUT_WITHOUT_BINDING (const)",
+    "VIEW_ROW_COLOR_WITHOUT_COLORS": "src/kernel/functional-completeness.ts#VIEW_ROW_COLOR_WITHOUT_COLORS (const)",
     "VIEW_TREE_WITHOUT_PARENT_FIELD": "src/kernel/functional-completeness.ts#VIEW_TREE_WITHOUT_PARENT_FIELD (const)",
     "ValidationError": "src/kernel/plugin-validator.zod.ts#ValidationError (type)",
     "ValidationErrorSchema": "src/kernel/plugin-validator.zod.ts#ValidationErrorSchema (const)",

packages/spec/src/kernel/functional-completeness.test.ts

@@ -28,6 +28,7 @@ import {
   FIELD_CHOICE_WITHOUT_OPTIONS,
   VIEW_LAYOUT_WITHOUT_BINDING,
   VIEW_TREE_WITHOUT_PARENT_FIELD,
+  VIEW_ROW_COLOR_WITHOUT_COLORS,
   WEBHOOK_WITHOUT_TRIGGERS,
 } from './functional-completeness';
 
@@ -277,6 +278,78 @@ describe('checkViewCompleteness — the tree parent pointer (the silent-flat hal
   });
 });
 
+describe('checkViewCompleteness — rowColor without a colour map (the parse-clean no-op)', () => {
+  // `RowColorConfigSchema` requires `field` and leaves `colors` optional, so
+  // `rowColor: { field }` parses, publishes, and colours nothing: objectui's
+  // `useRowColor.ts` returns `undefined` unless BOTH are present. Every key is
+  // one we know, which is why nothing else in the stack can see it.
+
+  it('flags `rowColor: { field }` with no `colors` as a WARNING', () => {
+    const f = only(checkViewCompleteness({ type: 'grid', rowColor: { field: 'status' } }) as never);
+    expect(f.rule).toBe(VIEW_ROW_COLOR_WITHOUT_COLORS);
+    expect(f.severity).toBe('warning');
+    expect(f.path).toBe('rowColor.colors');
+    // The first sentence, verbatim: it names the view, the bound field and the
+    // consequence — a prescription with no diagnosis is the shape ADR-0078 §6
+    // rejects.
+    expect(f.message).toContain(
+      'A `grid` view whose `rowColor` binds `status` and declares no `colors` map never colours a row',
+    );
+    // …and the runtime line that makes it true.
+    expect(f.message).toContain('if (!config?.field || !config.colors) return undefined');
+    // The prescription is machine-pastable and carries the authored field back.
+    expect(f.fix).toContain("field: 'status'");
+    expect(f.fix).toContain('colors');
+  });
+
+  it('is silent once a `colors` map is declared — the negative fixture', () => {
+    expect(checkViewCompleteness({
+      type: 'grid',
+      rowColor: { field: 'status', colors: { open: '#0f0' } },
+    })).toEqual([]);
+  });
+
+  it('flags `colors: {}` the same — an empty map passes the guard and then matches nothing', () => {
+    // The renderer's own test is `!config.colors`, which an empty object
+    // PASSES; the lookup one line down matches no value and the row keeps its
+    // default background anyway. Mirroring the guard expression alone would
+    // have blessed this shape; the rule mirrors the outcome.
+    const f = only(checkViewCompleteness({ type: 'grid', rowColor: { field: 'status', colors: {} } }) as never);
+    expect(f.rule).toBe(VIEW_ROW_COLOR_WITHOUT_COLORS);
+    expect(f.path).toBe('rowColor.colors');
+  });
+
+  it('does NOT flag the view types whose renderer never reads `rowColor` — the pinned NON-rule', () => {
+    // objectui's ListView adapter forwards `rowColor` in its `grid` branch
+    // only. On a kanban board the block is inert too, but declaring a `colors`
+    // map would not fix it — so warning here would be a false prescription,
+    // which is what this module refuses to ship. Recorded, not enforced.
+    for (const type of ['kanban', 'gallery', 'chart', 'timeline']) {
+      const findings = checkViewCompleteness({ type, rowColor: { field: 'status' } });
+      expect(findings.map((f) => f.rule)).not.toContain(VIEW_ROW_COLOR_WITHOUT_COLORS);
+    }
+  });
+
+  it('stays silent without a `field` to bind — that half is the schema\'s to refuse', () => {
+    // `field` is REQUIRED by `RowColorConfigSchema`, so a block without one is
+    // a parse error, not a completeness finding. Asserting it here would
+    // double-report the same defect in two different vocabularies.
+    expect(checkViewCompleteness({ type: 'grid', rowColor: {} })).toEqual([]);
+    expect(checkViewCompleteness({ type: 'grid', rowColor: { field: '' } })).toEqual([]);
+  });
+
+  it('leaves a non-record `colors` alone — only what was verified is asserted', () => {
+    // The schema refuses these at parse; this module is not a second parser.
+    expect(checkViewCompleteness({ type: 'grid', rowColor: { field: 'status', colors: 'red' } })).toEqual([]);
+    expect(checkViewCompleteness({ type: 'grid', rowColor: { field: 'status', colors: [] } })).toEqual([]);
+  });
+
+  it('never throws on junk', () => {
+    expect(checkViewCompleteness({ type: 'grid', rowColor: 'red' })).toEqual([]);
+    expect(checkViewCompleteness({ type: 'grid', rowColor: null })).toEqual([]);
+  });
+});
+
 describe('checkWebhookCompleteness — the rule the runtime comment argued against', () => {
   it('flags a webhook with no `triggers` as an ERROR', () => {
     const f = only(checkWebhookCompleteness({ name: 'notify_slack', url: 'https://x' }) as never);
@@ -329,6 +402,7 @@ describe('registry hygiene', () => {
       'field/relationship-without-reference',
       'field/summary-without-operations',
       'view/layout-without-binding',
+      'view/row-color-without-colors',
       'view/tree-without-parent-field',
       'webhook/without-triggers',
     ]);
@@ -343,9 +417,10 @@ describe('registry hygiene', () => {
       ...checkFieldCompleteness({ type: 'checkboxes' }),
       ...checkViewCompleteness({ type: 'kanban' }),
       ...checkViewCompleteness({ type: 'tree', tree: {} }, { name: 'unit', fields: {} }),
+      ...checkViewCompleteness({ type: 'grid', rowColor: { field: 'status' } }),
       ...checkWebhookCompleteness({ url: 'https://x' }),
     ];
-    expect(all).toHaveLength(8);
+    expect(all).toHaveLength(9);
     for (const f of all) {
       expect(f.fix.length).toBeGreaterThan(8);
       expect(f.message.length).toBeGreaterThan(60);

packages/spec/src/kernel/functional-completeness.ts

@@ -46,6 +46,10 @@
  * - `checkboxes` w/o `options` sits between the two: it shares the multi
  *   branch's free-form validator behaviour, but a checkbox group with zero
  *   boxes is almost certainly an omission — so it is a WARNING, not an error.
+ * - a grid view's `rowColor` w/o `colors` → objectui `plugin-grid`'s
+ *   `useRowColor.ts` `if (!config?.field || !config.colors) return undefined;`
+ *   — the row-className resolver bails before it reads a single row, so every
+ *   row keeps the default colour. See {@link VIEW_ROW_COLOR_WITHOUT_COLORS}.
  * - `webhook` w/o `triggers` → `auto-enqueuer.ts` `if (triggers.size === 0) …
  *   return null`. Note this one needed a SECOND source: that skip site's own
  *   comment blesses the empty case as "a manual-only webhook", which reads
@@ -78,6 +82,7 @@ export const FIELD_RELATIONSHIP_WITHOUT_REFERENCE = 'field/relationship-without-
 export const FIELD_CHOICE_WITHOUT_OPTIONS = 'field/choice-without-options';
 export const VIEW_LAYOUT_WITHOUT_BINDING = 'view/layout-without-binding';
 export const VIEW_TREE_WITHOUT_PARENT_FIELD = 'view/tree-without-parent-field';
+export const VIEW_ROW_COLOR_WITHOUT_COLORS = 'view/row-color-without-colors';
 export const WEBHOOK_WITHOUT_TRIGGERS = 'webhook/without-triggers';
 
 /** Every rule id this module can emit — pinned by tests so ids cannot drift. */
@@ -88,6 +93,7 @@ export const FUNCTIONAL_COMPLETENESS_RULES = [
   FIELD_CHOICE_WITHOUT_OPTIONS,
   VIEW_LAYOUT_WITHOUT_BINDING,
   VIEW_TREE_WITHOUT_PARENT_FIELD,
+  VIEW_ROW_COLOR_WITHOUT_COLORS,
   WEBHOOK_WITHOUT_TRIGGERS,
 ] as const;
 
@@ -315,6 +321,59 @@ function hasDetectableParentField(object: AnyRec): boolean {
     || ((def.type === 'lookup' || def.type === 'master_detail') && own !== undefined && def.reference === own));
 }
 
+/**
+ * The view types whose renderer actually READS `rowColor`, measured rather
+ * than inferred from the schema: `rowColor` is declared on every list view,
+ * but objectui's ListView adapter forwards it in exactly one branch of its
+ * per-type props switch — `case 'grid'` (`packages/plugin-list/src/
+ * ListView.tsx`, `...(rowColorConfig ? { rowColor: rowColorConfig } : {})`).
+ * `kanban` / `gallery` / `calendar` / `timeline` / `gantt` / `map` / `tree` /
+ * `chart` each build their own props and never carry the key; `page` mounts a
+ * published page through a different renderer entirely.
+ *
+ * ⛔ So this rule is NOT widened to every list view type, however tempting the
+ * schema's shape makes it. On a `kanban` view a `rowColor` block is inert too
+ * — but it is inert for a DIFFERENT reason, and this rule's prescription
+ * ("declare a `colors` map") would not fix it: the key is never read there
+ * with or without a map. Warning would be a false prescription, the failure
+ * mode the module doc and ADR-0078 §6 exist to prevent. That non-grid
+ * inertness is recorded here, not enforced — the `gallery` disposition in
+ * {@link VIEW_BINDING_BLOCKS} for the same reason.
+ *
+ * The `default:` arm of that switch shares the grid branch, so an unrecognised
+ * view type would carry `rowColor` too — unreachable from this predicate,
+ * which returns early on a view with no string `type` and never sees a
+ * defaulted one (it runs on the NORMALIZED, pre-parse stack).
+ */
+const ROW_COLOR_VIEW_TYPES: ReadonlySet<string> = new Set(['grid']);
+
+/**
+ * Whether a `rowColor` block declares no usable colour map.
+ *
+ * Both spellings of "no map" are flagged, and they reach the same dead end by
+ * two different routes in objectui's `useRowColor.ts` (`plugin-grid`):
+ *
+ * - `colors` ABSENT — the resolver's own guard,
+ *   `if (!config?.field || !config.colors) return undefined;`, returns before
+ *   it reads a row. Nothing is ever coloured.
+ * - `colors: {}` — an empty object is truthy, so it PASSES that guard; the
+ *   lookup one line down (`hasOwnProperty.call(config.colors, value)`) then
+ *   matches no value, `if (!color) return undefined`, and nothing is coloured
+ *   either. Mirroring the guard expression alone would have blessed this one;
+ *   the rule mirrors the OUTCOME the guard produces, which is the same.
+ *
+ * An empty map is not an "I meant it" marker the way an action's
+ * `locations: []` is — turning row colouring off has its own spellings (omit
+ * the `rowColor` block, or leave the toolbar toggle `userActions.rowColor`
+ * off), so `{}` is the same dead shape spelled out. Same reasoning as
+ * `triggers: []` in {@link checkWebhookCompleteness}.
+ *
+ * Any OTHER shape (a string, an array) is left alone: the schema refuses it at
+ * parse, and this module only asserts what it verified.
+ */
+const hasNoColorMap = (colors: unknown): boolean =>
+  colors === undefined || colors === null || (isRec(colors) && Object.keys(colors).length === 0);
+
 /**
  * Completeness of a single list-view definition (a container's `list` /
  * `listViews.*` entry).
@@ -343,6 +402,17 @@ function hasDetectableParentField(object: AnyRec): boolean {
  * rule fires only when BOTH halves fail — `parentField` undeclared AND nothing
  * on the bound object the renderer would detect — so a view that renders
  * correctly by auto-detection is never warned about.
+ *
+ * ## Why `rowColor` gets a rule of its own
+ *
+ * `RowColorConfigSchema` requires `field` and leaves `colors` optional, so
+ * `rowColor: { field: 'status' }` parses, publishes and colours nothing — the
+ * only renderer needs BOTH ({@link ROW_COLOR_VIEW_TYPES},
+ * {@link hasNoColorMap}). It is the same ADR-0078 silent half as a `summary`
+ * with no `summaryOperations`: every key is one we know, so the unknown-key
+ * rejection cannot see it and the liveness ledger cannot either — `rowColor`
+ * IS live, it is this instance that is dead. WARNING rather than error: only
+ * the colouring is lost, the rows still render (ADR-0078 §1).
  */
 export function checkViewCompleteness(view: unknown, boundObject?: unknown): CompletenessFinding[] {
   if (!isRec(view)) return [];
@@ -396,6 +466,25 @@ export function checkViewCompleteness(view: unknown, boundObject?: unknown): Com
     }
   }
 
+  if (ROW_COLOR_VIEW_TYPES.has(type) && isRec(view.rowColor)) {
+    const field = isNonEmptyString(view.rowColor.field) ? view.rowColor.field : undefined;
+    if (field !== undefined && hasNoColorMap(view.rowColor.colors)) {
+      out.push({
+        rule: VIEW_ROW_COLOR_WITHOUT_COLORS,
+        severity: 'warning',
+        path: 'rowColor.colors',
+        message:
+          `A \`${type}\` view whose \`rowColor\` binds \`${field}\` and declares no \`colors\` map never `
+          + 'colours a row: the grid\'s row-className resolver returns before it reads a record (objectui '
+          + '`useRowColor.ts` — `if (!config?.field || !config.colors) return undefined`), so every row keeps '
+          + 'the default background while parsing and publishing report success. An empty `colors: {}` is the '
+          + 'same dead shape spelled out — it passes that guard and then matches no value. The map is what '
+          + 'does the colouring; the field only says which value to look up.',
+        fix: `rowColor: { field: '${field}', colors: { '<field_value>': '<hex_or_token>' } }`,
+      });
+    }
+  }
+
   return out;
 }
 

packages/spec/src/ui/view.zod.ts

@@ -874,7 +874,7 @@ export const RowColorConfigSchema = lazySchema(() => strictObject({
   surface: 'this row color configuration',
   history: VIEW_HISTORY,
 }, {
-  field: z.string().describe('Field to derive color from (typically a select/status field)'),
+  field: z.string().describe('Field whose value is looked up in the `colors` map below to pick a row colour (typically a select/status field). The map is what does the colouring — with no `colors`, no row is ever coloured, whatever this field holds. Author-time diagnostic `view/row-color-without-colors` reports that combination.'),
   colors: z.record(z.string(), z.string()).optional().describe('Map of field value to color (hex/token)'),
 }).describe('Row color configuration based on field values'));