@everystack/admin 0.4.1 → 0.4.3

package/CHANGELOG.md

@@ -4,16 +4,88 @@ All notable changes to `@everystack/admin` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
-## [Unreleased]
+## [0.4.3] - 2026-10-14
+
+### Added
+
+- list query model: search, scope, sort and page as one URL state
+- adapter applies ListParams.search across searchFields
+- list search, sort and page live in the URL; search all fields after a pause
+- column headers sort ascending, descending, then off, with an arrow
+- scope tabs: named filters above the list, kept in the URL
+- opt-in scope tab counts; one grouped query for an enum's tabs
+- detect unsupported rich-text markup
+- preserve rich HTML in the stock editor schema
+- guard rich HTML against visual data loss
+- list page size from resource config, kept in the URL as size
+- fixed list column width
+- Save/Cancel also at the bottom of Edit and Create
+- tags field type with grouped pills, and form values on InputContext
+- resolveColumns and FieldColumns for screen layouts
+- Show, Edit and Create in columns, and scroll to the first error
+- listPriority and listHideBelow on fields; Actions is always kept
+- inline editable enum cell (inlineEdit on an enum field)
+
+### Fixed
+
+- adapter sends not.* and or/and filters instead of eq
+- list state updates the URL in place; the search box keeps focus
+- list URL names tab and dir; review-gate fixes
+- preserve search across RPC and custom adapters
+- detect HTML5 markup without silent misses
+- declare parse5 as a test dependency
+- keep links in inline code and code blocks
+- a resource perPage that is not a whole number above 0 falls back to 20
+- size the Actions column from its button labels
+- export ./package.json
+- render field.input as its own component
+- wrap a bare string or number from field.render in the cell Text
+- scroll to the topmost errored field on screen
+- size the Actions column from idle labels and let the buttons wrap
+- scroll to the first error after the errors render
+- inlineEdit follows actions.edit
+- the inline enum cell refuses a double save; pin the value after a save
+- refuse an update or delete by id that matches zero rows
+- refetch resolves after its fetch lands; add refreshing
+- keep the list table mounted through a refetch
+- refetch after unmount resolves; a newer pick wins over an older save's re-sync
+- refetch after a failed row action, keeping its error
+- the detail screen keeps a failed row action's error through the refetch
+- ResourceList keys table rows by the resource's primaryKey
+- ResourceShow keeps only the latest fetch's record, error and loading
+- a stale-id refetch cannot write under a newer id; row keys cannot collide with index fallbacks
+- ResourceShow sets the current id when it commits and drops the dead post-await id check
+- the inline enum cell stays busy until its refresh lands
+
+### Documentation
+
+- aggregate with fetchList, rowActions in the list, navigate, field.input as a component
+- column priority notes: never-dropping fields, hideBelow exception, identifying field, sort arrow
+- search, sort, scope tabs, tab counts and the list's URL params
+- FormActionBar, perPage limits, controlled setPerPage, label-based Actions width
+- document TagsFieldInput and its props
+
+## [0.4.2] - 2026-09-22
+
+### Fixed
+
+- refresh expired JWT instead of silently failing every request
+
+## [0.4.1] - 2026-09-22
 
 ### Added
 
 - auto-generated changelogs from conventional commits
 - automate the version-drift check — a manual note is not a gate
+- wire date/datetime field types to DateInput
 
 ### Fixed
 
 - the test suite compiled with type checking off
+- twitter preset field names must match the API's camelCase wire format
+- date fields no longer shift a day in UTC-negative timezones on List/Show
+- DateInput crash on malformed data; restore lost validation in date formatters
+- DateInput/admin date-value edge cases from final review pass
 
 ## [0.4.0] - 2026-07-19
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/admin",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Declarative admin dashboard framework for PostgREST APIs",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -41,7 +41,8 @@
       "source": "./src/editors/tiptap.tsx",
       "types": "./src/editors/tiptap.tsx",
       "default": "./src/editors/tiptap.tsx"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "dependencies": {
     "d3-scale": "4.0.2",
@@ -50,14 +51,38 @@
   "peerDependencies": {
     "drizzle-orm": "0.41.0",
     "@everystack/api": ">=0.2.4",
-    "@everystack/ui": ">=0.2.2",
-    "@tiptap/pm": ">=2.0.0",
-    "@tiptap/react": ">=2.0.0",
-    "@tiptap/starter-kit": ">=2.0.0",
+    "@everystack/ui": ">=0.4.2",
+    "@tiptap/extension-code": ">=3.0.0",
+    "@tiptap/extension-code-block": ">=3.0.0",
+    "@tiptap/extension-image": ">=3.0.0",
+    "@tiptap/extension-subscript": ">=3.0.0",
+    "@tiptap/extension-superscript": ">=3.0.0",
+    "@tiptap/extension-table": ">=3.0.0",
+    "@tiptap/pm": ">=3.0.0",
+    "@tiptap/react": ">=3.0.0",
+    "@tiptap/starter-kit": ">=3.0.0",
     "react": "19.2.0",
     "react-native": "0.83.6"
   },
   "peerDependenciesMeta": {
+    "@tiptap/extension-code": {
+      "optional": true
+    },
+    "@tiptap/extension-code-block": {
+      "optional": true
+    },
+    "@tiptap/extension-image": {
+      "optional": true
+    },
+    "@tiptap/extension-subscript": {
+      "optional": true
+    },
+    "@tiptap/extension-superscript": {
+      "optional": true
+    },
+    "@tiptap/extension-table": {
+      "optional": true
+    },
     "@tiptap/pm": {
       "optional": true
     },
@@ -69,22 +94,31 @@
     }
   },
   "devDependencies": {
-    "@tiptap/pm": "^2.0.0",
-    "@tiptap/react": "^2.0.0",
-    "@tiptap/starter-kit": "^2.0.0",
+    "@tiptap/extension-code": "^3.0.0",
+    "@tiptap/extension-code-block": "^3.0.0",
+    "@tiptap/extension-image": "^3.0.0",
+    "@tiptap/extension-subscript": "^3.0.0",
+    "@tiptap/extension-superscript": "^3.0.0",
+    "@tiptap/extension-table": "^3.0.0",
+    "@tiptap/pm": "^3.0.0",
+    "@tiptap/react": "^3.0.0",
+    "@tiptap/starter-kit": "^3.0.0",
     "@types/d3-scale": "4.0.9",
     "@types/d3-time-format": "4.0.3",
     "@types/jest": "29.5.14",
     "@types/node": "22.19.18",
     "@types/react": "19.2.14",
     "jest": "29.7.0",
+    "jest-environment-jsdom": "29.7.0",
+    "jsdom": "^20.0.3",
+    "parse5": "^7.3.0",
     "react": "19.2.0",
     "react-native": "0.83.6",
     "react-test-renderer": "19.2.0",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
-    "@everystack/api": "0.4.1",
-    "@everystack/ui": "0.4.1"
+    "@everystack/api": "0.4.3",
+    "@everystack/ui": "0.4.2"
   },
   "scripts": {
     "test": "jest",

package/src/adapters/EverystackAdapter.ts

@@ -7,6 +7,7 @@
 
 import { createClient, type Client, type ClientOptions, type QueryBuilder } from '@everystack/api/client';
 import { toCamelCaseKeys } from '../utils/naming';
+import { mergeFilters, normalizeSearchText } from '../utils/list-query';
 import type { DataAdapter } from './types';
 import type {
   ListParams,
@@ -23,6 +24,23 @@ const POSTGREST_OPERATORS = new Set([
   'sl', 'sr', 'nxl', 'nxr', 'adj', 'ov', 'fts',
 ]);
 
+/**
+ * The handler answers 200 [] when a write matches no row, whether the row is gone or a policy
+ * hides it. A write by one id that touched nothing failed, so update and delete refuse it with
+ * one message for both causes: naming the cause would tell a caller whether the row exists.
+ */
+const ZERO_ROW_UPDATE = 'No row was updated. It may not exist, or you may not have permission.';
+const ZERO_ROW_DELETE = 'No row was deleted. It may not exist, or you may not have permission.';
+
+/**
+ * `onTokenExpired` and `onAuthFailure` (inherited from `ClientOptions`) are how
+ * the admin survives a session longer than the access token's TTL. Without
+ * `onTokenExpired`, `getToken` keeps handing every request the same dead token
+ * forever — the user stays "logged in" while every screen 401s. `onAuthFailure`
+ * fires only once refresh itself is unrecoverable (refresh token also
+ * expired/revoked) — wire it to sign the user out for real. See
+ * `@everystack/auth/api`'s `refreshAuthToken` for a ready-made `onTokenExpired`.
+ */
 export interface EverystackAdapterOptions extends ClientOptions {
   /**
    * Resources whose list rows come from an RPC instead of the PostgREST table.
@@ -44,6 +62,7 @@ export interface EverystackAdapterOptions extends ClientOptions {
 }
 
 export class EverystackAdapter implements DataAdapter {
+  readonly supportsSearch = true;
   private client: Client;
   private listRpcs: Record<string, string>;
   private crudRpcs: Record<string, string>;
@@ -65,6 +84,12 @@ export class EverystackAdapter implements DataAdapter {
     // RPC-backed list (e.g. DB-free observability tables over the S3 archive).
     const listRpc = this.listRpcs[resource];
     if (listRpc) {
+      const text = normalizeSearchText(params.search);
+      const field = params.searchFields?.[0];
+      // RPC lists keep the first-field filter protocol; escape wildcard text for the S3 matcher.
+      const filter = text && field
+        ? mergeFilters(params.filter, { [field]: `ilike.*${text.replace(/[\\*%]/g, c => `\\${c}`)}*` })
+        : params.filter;
       // Accept either the S3 list shape ({ data, total }) or the dashboard eventList shape
       // ({ rows, total }) so a resource can be served by either kind of RPC.
       const result = await this.rpc<{ data?: T[]; rows?: T[]; total: number }>(listRpc, {
@@ -72,7 +97,7 @@ export class EverystackAdapter implements DataAdapter {
         offset,
         sort: params.sort,
         dir: params.order ?? 'asc',
-        filter: params.filter,
+        filter,
       });
       // Normalize row keys to camelCase so the list columns resolve regardless of whether
       // the RPC returns snake_case (e.g. jobsEventList over ops.runs) or camelCase (S3 lists,
@@ -88,8 +113,9 @@ export class EverystackAdapter implements DataAdapter {
 
     let builder = this.client.from(resource);
 
-    // Apply filters
+    // Apply filters, then the search group beside them
     builder = applyFilters(builder, params.filter);
+    builder = applySearch(builder, params);
 
     // Apply sort
     if (params.sort) {
@@ -173,7 +199,8 @@ export class EverystackAdapter implements DataAdapter {
       throw new Error(result.error.message);
     }
 
-    const rows = result.data as T[];
+    const rows = (result.data ?? []) as T[];
+    if (rows.length === 0) throw new Error(ZERO_ROW_UPDATE);
     return rows[0];
   }
 
@@ -189,6 +216,8 @@ export class EverystackAdapter implements DataAdapter {
     if (result.error) {
       throw new Error(result.error.message);
     }
+
+    if ((result.data ?? []).length === 0) throw new Error(ZERO_ROW_DELETE);
   }
 
   /** Unwrap an action RPC result, surfacing a `{ error }` payload as a throw. */
@@ -230,8 +259,9 @@ export class EverystackAdapter implements DataAdapter {
 
     let builder = this.client.from(resource).select(selectParts.join(','));
 
-    // Apply filters
+    // Apply filters, then the search group beside them (the same rules as a list)
     builder = applyFilters(builder, params.filter);
+    builder = applySearch(builder, params);
 
     const result = await builder.execute();
 
@@ -259,6 +289,15 @@ function applyFilters(builder: QueryBuilder, filter?: Record<string, unknown>):
 
   for (const [key, value] of Object.entries(filter)) {
     if (value == null) continue;
+    // `or` / `and` are PostgREST logical groups, not columns. The handler reads
+    // one of each, so a second expression would silently replace the first.
+    if (key === 'or' || key === 'and') {
+      if (typeof value !== 'string') {
+        throw new Error(`filter "${key}" takes one expression string, e.g. "(a.eq.1,b.eq.2)"`);
+      }
+      builder = builder[key](stripOuterParens(value));
+      continue;
+    }
     // An array applies several conditions to the same column (PostgREST ANDs
     // them) — e.g. a time range as ['gte.<from>', 'lte.<to>'].
     if (Array.isArray(value)) {
@@ -284,6 +323,8 @@ function applyOneFilter(builder: QueryBuilder, key: string, value: unknown): Que
   const op = strValue.substring(0, dotIndex);
   const val = strValue.substring(dotIndex + 1);
 
+  if (op === 'not') return applyNegatedFilter(builder, key, val, strValue);
+
   switch (op) {
     case 'eq': return builder.eq(key, val);
     case 'neq': return builder.neq(key, val);
@@ -303,6 +344,68 @@ function applyOneFilter(builder: QueryBuilder, key: string, value: unknown): Que
   }
 }
 
+/**
+ * Apply `not.<op>.<value>`. `rest` is everything after `not.`; `whole` is the
+ * full original value, used for the same eq fallback an unknown operator gets.
+ */
+function applyNegatedFilter(builder: QueryBuilder, key: string, rest: string, whole: string): QueryBuilder {
+  const dotIndex = rest.indexOf('.');
+  const op = dotIndex < 0 ? rest : rest.substring(0, dotIndex);
+  const val = dotIndex < 0 ? '' : rest.substring(dotIndex + 1);
+
+  switch (op) {
+    case 'eq': return builder.notEq(key, val);
+    case 'neq': return builder.notNeq(key, val);
+    case 'gt': return builder.notGt(key, val);
+    case 'gte': return builder.notGte(key, val);
+    case 'lt': return builder.notLt(key, val);
+    case 'lte': return builder.notLte(key, val);
+    case 'like': return builder.notLike(key, val);
+    case 'ilike': return builder.notIlike(key, val);
+    case 'is': return builder.notIs(key, val);
+    case 'in': return builder.notIn(key, val.replace(/^\(/, '').replace(/\)$/, '').split(','));
+    default:
+      return builder.eq(key, whole);
+  }
+}
+
+/** Plain column names only: a search field is spliced into an `or=(...)` expression. */
+const SEARCH_FIELD = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Match `params.search` in any of `params.searchFields`, as one `or()` group.
+ *
+ * The handler splits an `or` group on every comma and has no quoting, so user
+ * text must not carry `,` `(` `)`. `\` `%` `_` are escaped so they match
+ * literally; the structural characters and a typed `*` (the handler turns every
+ * `*` into `%`) become `_`, the one-character wildcard, so a stored value that
+ * contains them ("Alpha, Beta") still matches.
+ */
+function applySearch(builder: QueryBuilder, params: Pick<ListParams, 'filter' | 'search' | 'searchFields'>): QueryBuilder {
+  const fields = params.searchFields ?? [];
+  for (const field of fields) {
+    if (!SEARCH_FIELD.test(field)) throw new Error(`invalid search field "${field}": plain column names only`);
+  }
+
+  const text = normalizeSearchText(params.search);
+  if (!text) return builder;
+
+  if (fields.length === 0) {
+    throw new Error('ListParams.search needs ListParams.searchFields (the columns to look in)');
+  }
+  if (params.filter?.or != null) {
+    throw new Error('search cannot be combined with an "or" filter: the handler reads one or group');
+  }
+
+  const pattern = `*${text.replace(/[\\%_]/g, c => `\\${c}`).replace(/[,()*]/g, '_')}*`;
+  return builder.or(fields.map(field => `${field}.ilike.${pattern}`).join(','));
+}
+
+/** `(a.eq.1,b.eq.2)` → `a.eq.1,b.eq.2`; the client builder adds its own parentheses. */
+function stripOuterParens(expression: string): string {
+  return expression.startsWith('(') && expression.endsWith(')') ? expression.slice(1, -1) : expression;
+}
+
 /**
  * Check if a filter value is already in PostgREST format (operator.value).
  */

package/src/adapters/types.ts

@@ -18,6 +18,9 @@ import type {
 // =============================================================================
 
 export interface DataAdapter {
+  /** Handles search + searchFields in both list and aggregate params. Otherwise the UI uses a first-field filter. */
+  supportsSearch?: boolean;
+
   /**
    * Fetch a list of records with pagination, sorting, and filtering
    */
@@ -51,7 +54,10 @@ export interface DataAdapter {
   delete(resource: string, id: string | number): Promise<void>;
 
   /**
-   * Fetch aggregate data (count, sum, avg, min, max) with optional grouping
+   * Fetch aggregate data (count, sum, avg, min, max) with optional grouping.
+   * EverystackAdapter queries the table named after the resource; unlike its
+   * fetchList it has no listRpcs path. For a resource whose name is not a
+   * table, override aggregate() together with fetchList().
    */
   aggregate?(resource: string, params: AggregateParams): Promise<AggregateResult>;
 

package/src/components/CellText.tsx

@@ -0,0 +1,18 @@
+/**
+ * Wraps a bare string or number from a custom field.render in the default cell
+ * Text. react-native cannot render a text node outside <Text>, so a render
+ * that returns `42` or `'abc'` would otherwise crash on native. Elements,
+ * arrays, null, undefined and booleans pass through untouched.
+ */
+
+import React, { type ReactNode } from 'react';
+import { Text } from 'react-native';
+
+export function wrapBareText(node: ReactNode, numberOfLines?: number): ReactNode {
+  if (typeof node !== 'string' && typeof node !== 'number') return node;
+  return (
+    <Text className="text-sm text-gray-900" numberOfLines={numberOfLines}>
+      {node}
+    </Text>
+  );
+}

package/src/components/FieldColumns.tsx

@@ -0,0 +1,86 @@
+/**
+ * FieldColumns — the field columns of a Show/Edit/Create screen.
+ *
+ * Side by side on a wide container: a 'wide' column takes the space left
+ * over, a fixed column keeps its width. Below BREAKPOINT_STACK the columns
+ * stack, main first, each full width. It measures its own container (not the
+ * window) and renders stacked until the first measurement.
+ */
+
+import React, { useCallback, useRef } from 'react';
+import { View } from 'react-native';
+import type { LayoutChangeEvent } from 'react-native';
+import { useContainerWidth } from '@everystack/ui/dashboard';
+import type { FieldDefinition } from '../types';
+import type { ResolvedColumn } from '../utils/resolve-columns';
+
+/** Container width (px) below which the columns stack. */
+export const BREAKPOINT_STACK = 720;
+
+/** Space between columns that sit side by side, in px. */
+const COLUMN_GAP = 24;
+
+export interface FieldColumnsProps {
+  /** From resolveColumns. */
+  columns: ResolvedColumn[];
+  /** Draws one field; `index` is its place in its column. */
+  renderField: (field: FieldDefinition, index: number) => React.ReactNode;
+  /** A field's y within this component (its column's y + its own y), on every layout change. */
+  onFieldOffset?: (name: string, y: number) => void;
+}
+
+export function FieldColumns({ columns, renderField, onFieldOffset }: FieldColumnsProps): React.ReactElement {
+  // Fallback 0: stacked until the container is measured.
+  const { width, onLayout } = useContainerWidth(0);
+  const stacked = width < BREAKPOINT_STACK;
+
+  const columnY = useRef(new Map<number, number>());
+  const fieldY = useRef(new Map<string, { column: number; y: number }>());
+
+  const report = useCallback((name: string) => {
+    const field = fieldY.current.get(name);
+    if (!field || !onFieldOffset) return;
+    const top = columnY.current.get(field.column);
+    if (top === undefined) return;
+    onFieldOffset(name, top + field.y);
+  }, [onFieldOffset]);
+
+  const onColumnLayout = (column: number, fields: FieldDefinition[]) => (event: LayoutChangeEvent) => {
+    columnY.current.set(column, event.nativeEvent.layout.y);
+    for (const field of fields) report(field.name);
+  };
+
+  const onItemLayout = (column: number, name: string) => (event: LayoutChangeEvent) => {
+    fieldY.current.set(name, { column, y: event.nativeEvent.layout.y });
+    report(name);
+  };
+
+  return (
+    <View
+      testID="field-columns"
+      onLayout={onLayout}
+      style={stacked ? { flexDirection: 'column' } : { flexDirection: 'row', alignItems: 'flex-start', columnGap: COLUMN_GAP }}
+    >
+      {columns.map((column, ci) => (
+        <View
+          key={ci}
+          testID={`field-column-${ci}`}
+          onLayout={onColumnLayout(ci, column.fields)}
+          style={columnStyle(column, stacked)}
+        >
+          {column.fields.map((field, fi) => (
+            <View key={field.name} testID={`field-columns-item-${field.name}`} onLayout={onItemLayout(ci, field.name)}>
+              {renderField(field, fi)}
+            </View>
+          ))}
+        </View>
+      ))}
+    </View>
+  );
+}
+
+function columnStyle(column: ResolvedColumn, stacked: boolean) {
+  if (stacked) return { width: '100%' as const };
+  if (column.width === 'wide') return { flex: 1, minWidth: 0 };
+  return { width: column.width, flexShrink: 0 };
+}

package/src/components/FormActionBar.tsx

@@ -0,0 +1,45 @@
+/**
+ * FormActionBar — Save/Cancel at the bottom of the Edit and Create forms.
+ *
+ * The screens render it as a sibling under their ScrollView, so it stays in
+ * view on a long form without CSS positioning. The submit error lives here,
+ * above the buttons, so it is visible however far the form is scrolled.
+ */
+
+import React from 'react';
+import { View, Text } from 'react-native';
+import { Button } from '@everystack/ui';
+
+export interface FormActionBarProps {
+  onSubmit: () => void;
+  /** Cancel is shown only when this is given. */
+  onCancel?: () => void;
+  submitting: boolean;
+  /** Defaults to 'Save'. */
+  submitLabel?: string;
+  error?: string | null;
+}
+
+export function FormActionBar({
+  onSubmit,
+  onCancel,
+  submitting,
+  submitLabel = 'Save',
+  error,
+}: FormActionBarProps): React.ReactElement {
+  return (
+    <View testID="form-action-bar" className="border-t border-gray-200 bg-white px-4 py-3">
+      {error ? (
+        <View testID="form-action-bar-error" className="mb-3 bg-red-50 border border-red-200 rounded-lg px-4 py-3">
+          <Text className="text-sm text-red-700">{error}</Text>
+        </View>
+      ) : null}
+      <View className="flex-row justify-end gap-2">
+        {onCancel && (
+          <Button label="Cancel" variant="ghost" onPress={onCancel} />
+        )}
+        <Button label={submitLabel} onPress={onSubmit} loading={submitting} />
+      </View>
+    </View>
+  );
+}

package/src/components/InlineEnumCell.tsx

@@ -0,0 +1,98 @@
+/**
+ * InlineEnumCell — a list cell that edits an enum field (`inlineEdit: true`).
+ *
+ * A pick shows the new value at once and saves it with
+ * `adapter.update(resource, recordId, { [field]: value })`, the only write this
+ * cell makes. While it saves, the pill is disabled. A rejection restores the
+ * previous value and shows the server's message under the pill; the next
+ * change clears it. A success keeps the pill disabled through `onSaved` (the
+ * list refreshes), then shows the value the list holds, even when that value
+ * did not change.
+ *
+ * The cell claims the press, so a pick does not also fire the row's onRowPress.
+ */
+
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { View, Text } from 'react-native';
+import { OptionPicker } from '@everystack/ui';
+import type { DataAdapter } from '../adapters/types';
+
+export interface InlineEnumCellProps {
+  resource: string;
+  field: string;
+  recordId: string | number;
+  /** The stored value. */
+  value: unknown;
+  enumValues: string[];
+  adapter: DataAdapter;
+  /** Called after a successful save. The cell re-syncs from `value` once it settles. */
+  onSaved: () => void | Promise<void>;
+}
+
+export function InlineEnumCell({
+  resource,
+  field,
+  recordId,
+  value,
+  enumValues,
+  adapter,
+  onSaved,
+}: InlineEnumCellProps): React.ReactElement {
+  const stored = value == null ? '' : String(value);
+  const [shown, setShown] = useState(stored);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  // Set at once, so a second change in the same tick (before `saving` renders) is refused.
+  const inFlight = useRef(false);
+  const mounted = useRef(true);
+  useEffect(() => {
+    mounted.current = true;
+    return () => { mounted.current = false; };
+  }, []);
+  // Bumped after a save's refresh lands, so the cell re-syncs even when the stored value is unchanged.
+  const [synced, setSynced] = useState(0);
+
+  // The stored value (the list refetched) replaces what the cell shows.
+  useEffect(() => { setShown(stored); }, [stored, synced]);
+
+  const change = useCallback(async (next: string) => {
+    if (inFlight.current || next === shown) return;
+    inFlight.current = true;
+    const previous = shown;
+    setError(null);
+    setShown(next);
+    setSaving(true);
+    try {
+      try {
+        await adapter.update(resource, recordId, { [field]: next });
+      } catch (err) {
+        setShown(previous);
+        setError(err instanceof Error ? err.message : String(err));
+        return;
+      }
+      await onSaved();
+      if (mounted.current) setSynced(n => n + 1);
+    } catch {
+      // The save landed; a failed refresh is the list's to report.
+    } finally {
+      inFlight.current = false;
+      setSaving(false);
+    }
+  }, [shown, adapter, resource, recordId, field, onSaved]);
+
+  return (
+    <View onStartShouldSetResponder={() => true}>
+      <OptionPicker
+        value={shown}
+        options={enumValues.map(v => ({ label: v, value: v }))}
+        onChange={change}
+        disabled={saving}
+      />
+      {error ? (
+        <Text className="text-xs text-red-600 mt-1" numberOfLines={2}>
+          {error}
+        </Text>
+      ) : null}
+    </View>
+  );
+}