feat(grid): inline select editor only offers valid state-machine transitions (#2110)

The inline editor would happily offer a status change the server then rejects
(e.g. done → in_review), leaving the author to discover the failure on save.
Now, when a field is governed by a `state_machine` validation, the dropdown is
filtered to the values reachable from the current state — the current value
plus its declared transitions — so the invalid choice isn't offered at all.

- `stateMachineNextValues(objectSchema, field, value)` reads the object's
  `validations` (the same metadata the server enforces, already served on the
  schema and passed through by the adapter's getObjectSchema) and returns the
  reachable set, or null = "don't constrain" when there's no state machine or
  the current state is undeclared (mirrors the validation engine's lenient
  allow).
- ObjectGrid.renderCellEditor filters the field's `options` by that set before
  handing the field to FieldEditWidget; non-select / non-state-machine fields
  are untouched.
- 8 unit tests incl. the live bug case (from `done` → only [done, in_progress]).

Complements #2106 (surface save failures): prevent the invalid edit at the
source, and still report it if one slips through. Verified end-to-end that the
data path is live — the backend serves the transitions and getObjectSchema
passes them through unmodified.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: os-zhuang

.changeset/inline-edit-state-machine-options.md

@@ -0,0 +1,17 @@
+---
+"@object-ui/plugin-grid": patch
+---
+
+feat(grid): inline select editor only offers valid state-machine transitions
+
+When a field is governed by a `state_machine` validation, the inline cell
+editor now filters its dropdown to the values reachable from the current state
+(the current value plus its declared transitions) — so you can't stage an edit
+the server is bound to reject. Example: a task already `Done` only offers
+`Done` and `In Progress`, not `In Review`.
+
+This reads the same `validations` metadata the server enforces (already served
+on the object schema), and falls back to showing all options when the field has
+no state machine or its current state is undeclared (mirroring the validation
+engine's lenient allow). Complements the save-failure surfacing — prevent the
+invalid edit at the source, and still report it if one slips through.

packages/plugin-grid/src/ObjectGrid.tsx

@@ -27,6 +27,7 @@ import type { I18nLabel } from '@objectstack/spec/ui';
 import { SchemaRenderer, useDataScope, useNavigationOverlay, useAction, useObjectTranslation, useSafeFieldLabel } from '@object-ui/react';
 import { getCellRenderer, resolveCellRendererType, formatCurrency, formatCompactCurrency, formatDate, formatPercent, humanizeLabel, getBadgeColorClasses, FieldEditWidget, hasFieldEditWidget, DISCRETE_EDIT_TYPES } from '@object-ui/fields';
 import { useLocalization, resolveFieldCurrency } from '@object-ui/i18n';
+import { stateMachineNextValues } from './inline-edit-options';
 import {
   Badge, Button, NavigationOverlay, EmptyValue,
   Popover, PopoverContent, PopoverTrigger,
@@ -1704,9 +1705,20 @@ export const ObjectGrid: React.FC<ObjectGridProps> = ({
           const fieldDef = (objectSchema as any)?.fields?.[ctx.column?.accessorKey];
           if (!fieldDef || !hasFieldEditWidget(fieldDef.type)) return null;
           const discrete = DISCRETE_EDIT_TYPES.has(fieldDef.type);
+          let field: any = { name: ctx.column.accessorKey, ...fieldDef };
+          // State-machine-aware: a field bound to a `state_machine` validation
+          // only offers transitions valid from the current value, so the editor
+          // can't stage an edit the server would reject (e.g. done → in_review).
+          const reachable = stateMachineNextValues(objectSchema, ctx.column.accessorKey, ctx.value);
+          if (reachable && Array.isArray(field.options)) {
+            field = {
+              ...field,
+              options: field.options.filter((o: any) => reachable.has(String(o?.value ?? o))),
+            };
+          }
           return (
             <FieldEditWidget
-              field={{ name: ctx.column.accessorKey, ...fieldDef }}
+              field={field}
               value={ctx.value}
               onChange={(v: any) => (discrete ? ctx.commit(v) : ctx.stage(v))}
             />

packages/plugin-grid/src/inline-edit-options.test.ts

@@ -0,0 +1,80 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { stateMachineNextValues } from './inline-edit-options';
+
+// Mirrors examples/app-showcase task.object.ts — the state machine that rejected
+// done → in_review live (done only transitions to in_progress).
+const taskSchema = {
+  validations: [
+    {
+      type: 'state_machine',
+      field: 'status',
+      transitions: {
+        backlog: ['todo'],
+        todo: ['in_progress', 'backlog'],
+        in_progress: ['in_review', 'todo'],
+        in_review: ['done', 'in_progress'],
+        done: ['in_progress'],
+      },
+    },
+  ],
+};
+
+describe('stateMachineNextValues', () => {
+  it('returns the current value plus its allowed transitions', () => {
+    const r = stateMachineNextValues(taskSchema, 'status', 'in_review');
+    expect(r).not.toBeNull();
+    expect([...(r as Set<string>)].sort()).toEqual(['done', 'in_progress', 'in_review']);
+  });
+
+  it('constrains a near-terminal state to itself + its one valid move', () => {
+    // The exact live bug: from `done` the only valid move is `in_progress`,
+    // so `in_review` must NOT be offered.
+    const r = stateMachineNextValues(taskSchema, 'status', 'done');
+    expect([...(r as Set<string>)].sort()).toEqual(['done', 'in_progress']);
+    expect((r as Set<string>).has('in_review')).toBe(false);
+  });
+
+  it('always includes the current value so it stays selectable', () => {
+    const r = stateMachineNextValues(taskSchema, 'status', 'backlog');
+    expect((r as Set<string>).has('backlog')).toBe(true);
+    expect((r as Set<string>).has('todo')).toBe(true);
+  });
+
+  it('returns null (unconstrained) for a field with no state machine', () => {
+    expect(stateMachineNextValues(taskSchema, 'priority', 'medium')).toBeNull();
+  });
+
+  it('returns null when the current state is undeclared (lenient, mirrors the engine)', () => {
+    expect(stateMachineNextValues(taskSchema, 'status', 'archived')).toBeNull();
+  });
+
+  it('returns only the current value for a terminal state (no outgoing edges)', () => {
+    const terminal = {
+      validations: [{ type: 'state_machine', field: 'status', transitions: { done: [] } }],
+    };
+    const r = stateMachineNextValues(terminal, 'status', 'done');
+    expect([...(r as Set<string>)]).toEqual(['done']);
+  });
+
+  it('returns null for missing/empty schema or validations', () => {
+    expect(stateMachineNextValues(null, 'status', 'done')).toBeNull();
+    expect(stateMachineNextValues({}, 'status', 'done')).toBeNull();
+    expect(stateMachineNextValues({ validations: [] }, 'status', 'done')).toBeNull();
+  });
+
+  it('coerces non-string transition values to strings', () => {
+    const numeric = {
+      validations: [{ type: 'state_machine', field: 'level', transitions: { 1: [2, 3] } }],
+    };
+    const r = stateMachineNextValues(numeric, 'level', 1);
+    expect([...(r as Set<string>)].sort()).toEqual(['1', '2', '3']);
+  });
+});

packages/plugin-grid/src/inline-edit-options.ts

@@ -0,0 +1,48 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Helpers for constraining an inline cell editor's choices to what the data
+ * layer would actually accept — so the editor can't stage an edit the server
+ * is bound to reject.
+ */
+
+/**
+ * For a field governed by a `state_machine` validation, the set of values
+ * reachable from `currentValue` — the current value itself plus its declared
+ * allowed transitions.
+ *
+ * Returns `null` (= "don't constrain the options") when:
+ *  - the object has no `state_machine` validation for the field, or
+ *  - the current state isn't declared in the transition map.
+ *
+ * The second case mirrors the validation engine's lenient "allow" for
+ * undeclared from-states (an unconstrained state simply isn't policed), so the
+ * editor stays permissive exactly where the server would.
+ */
+export function stateMachineNextValues(
+  objectSchema: unknown,
+  fieldName: string,
+  currentValue: unknown,
+): Set<string> | null {
+  const rules = (objectSchema as { validations?: unknown })?.validations;
+  if (!Array.isArray(rules)) return null;
+  const sm = rules.find(
+    (r): r is { transitions: Record<string, string[]> } =>
+      !!r &&
+      typeof r === 'object' &&
+      (r as { type?: unknown }).type === 'state_machine' &&
+      (r as { field?: unknown }).field === fieldName &&
+      !!(r as { transitions?: unknown }).transitions,
+  );
+  if (!sm) return null;
+  const from = currentValue == null ? '' : String(currentValue);
+  const allowed = sm.transitions[from];
+  if (!Array.isArray(allowed)) return null; // undeclared from-state → unconstrained
+  return new Set<string>([from, ...allowed.map((s) => String(s))]);
+}