@dxos/react-ui-form 0.10.0 → 0.11.0

package/src/components/RefEditor/RefEditor.tsx

@@ -7,7 +7,7 @@ import { type EditorView } from '@codemirror/view';
 import React, { forwardRef, useCallback, useEffect, useMemo, useRef } from 'react';
 
 import { type Database, Filter, Obj, type Type } from '@dxos/echo';
-import { useQuery } from '@dxos/react-client/echo';
+import { useQuery } from '@dxos/echo-react';
 import { type ThemedClassName, useThemeContext, useTranslation } from '@dxos/react-ui';
 import {
   Editor,
@@ -17,7 +17,7 @@ import {
   type UseEditorMenuProps,
 } from '@dxos/react-ui-editor';
 import { createBasicExtensions, createThemeExtensions, insertAtCursor, keymap } from '@dxos/ui-editor';
-import { getHashHue } from '@dxos/ui-theme';
+import { getHashHue, mx } from '@dxos/ui-theme';
 
 import { translationKey } from '#translations';
 
@@ -86,6 +86,7 @@ export const RefEditor = forwardRef<EditorController, RefEditorProps>(
       placeholder: placeholderProp,
       activateOnTyping,
       numItems = 8,
+      classNames,
       ...props
     },
     forwardedRef,
@@ -131,7 +132,13 @@ export const RefEditor = forwardRef<EditorController, RefEditorProps>(
 
     const getMenu = useCallback<NonNullable<UseEditorMenuProps['getMenu']>>(
       async ({ text }) => {
-        const query = (text ?? '').replace(/^@/, '').toLowerCase();
+        // With `activateOnTyping` (no `@` trigger) an empty query would otherwise match every object
+        // and anchor the popover at the viewport origin (no range to position against). Show nothing
+        // until the user types. An explicit `@` trigger still browses (its `text` is '@', not empty).
+        if (!text) {
+          return [];
+        }
+        const query = text.replace(/^@/, '').toLowerCase();
         const matchesQuery = (object: Obj.Unknown) =>
           !query ||
           getObjectLabel(object).toLowerCase().includes(query) ||
@@ -199,7 +206,17 @@ export const RefEditor = forwardRef<EditorController, RefEditorProps>(
     const extensions = useMemo<Extension[]>(
       () => [
         createBasicExtensions({ readOnly: readonly, lineWrapping: false }),
-        createThemeExtensions({ themeMode, slots: { scroller: { className: 'scrollbar-none' } } }),
+        createThemeExtensions({
+          themeMode,
+          slots: {
+            editor: {
+              className: 'w-full',
+            },
+            scroller: {
+              className: 'scrollbar-none',
+            },
+          },
+        }),
         refEditor({ mode, match, getRef: (id) => refsRef.current.get(id) }),
         Prec.highest(
           keymap.of([
@@ -225,6 +242,26 @@ export const RefEditor = forwardRef<EditorController, RefEditorProps>(
                 return true;
               },
             },
+            {
+              key: 'Space',
+              // In email mode, a space after a bare address commits it (a tag only forms once
+              // committed). A partial `Name <…` segment still needs spaces, so only commit — and
+              // consume the space — when the whole in-progress segment is an address.
+              run: (view) => {
+                if (mode !== 'email') {
+                  return false;
+                }
+                const { head } = view.state.selection.main;
+                const line = view.state.doc.lineAt(head);
+                const before = line.text.slice(0, head - line.from);
+                const segment = before.slice(before.lastIndexOf(',') + 1).trim();
+                if ((match ?? EMAIL_REGEX).test(segment)) {
+                  insertAtCursor(view, head, ', ');
+                  return true;
+                }
+                return false;
+              },
+            },
           ]),
         ),
       ],
@@ -245,9 +282,8 @@ export const RefEditor = forwardRef<EditorController, RefEditorProps>(
         ref={composedRef}
       >
         <Editor.View
-          // TOOD(burdon): Use same style as react-ui Input.
-          classNames='border border-input-separator rounded-xs px-2'
           {...props}
+          classNames={mx('flex items-center dx-input h-[2rem]', classNames)}
           initialValue={value}
           selectionEnd
         />

package/src/components/RefEditor/ref-editor-extension.ts

@@ -2,7 +2,14 @@
 // Copyright 2026 DXOS.org
 //
 
-import { type EditorState, type Extension, RangeSetBuilder, StateEffect, StateField } from '@codemirror/state';
+import {
+  EditorState,
+  type Extension,
+  RangeSetBuilder,
+  StateEffect,
+  StateField,
+  type TransactionSpec,
+} from '@codemirror/state';
 import { Decoration, type DecorationSet, EditorView, WidgetType } from '@codemirror/view';
 
 import { Domino } from '@dxos/ui';
@@ -25,14 +32,6 @@ export type RefInfo = {
  */
 export type RefEditorMode = 'ref' | 'email';
 
-export type RefEditorExtensionOptions = {
-  mode?: RefEditorMode;
-  /** Resolve an object id referenced as `@<id>` to display info. */
-  getRef?: (id: string) => RefInfo | undefined;
-  /** Pluggable raw-token matcher (e.g. {@link EMAIL_REGEX}); matching tokens render as neutral tags. */
-  match?: RegExp;
-};
-
 /** Matches an object reference token (`@<object id>`). */
 export const REF_REGEX = /^@([A-Za-z0-9]+)$/;
 
@@ -51,6 +50,15 @@ export const formatMailbox = (name: string | undefined, email: string): string =
  */
 export const refEditorRedecorate = StateEffect.define<null>();
 
+export type RefEditorExtensionOptions = {
+  mode?: RefEditorMode;
+  /** Resolve an object id referenced as `@<id>` to display info. */
+  getRef?: (id: string) => RefInfo | undefined;
+  /** Pluggable raw-token matcher (e.g. {@link EMAIL_REGEX}); matching tokens render as neutral tags. */
+  match?: RegExp;
+  colorize?: boolean;
+};
+
 /**
  * CodeMirror extension rendering reference-editor tokens as tags. Tags are atomic: the cursor
  * cannot enter them and deletion removes the whole token.
@@ -60,7 +68,44 @@ export const refEditorRedecorate = StateEffect.define<null>();
  * - `'email'` mode: RFC 5322 mailboxes render as tags labelled with the display name (falling
  *   back to the address); the trailing comma separator is hidden inside the tag's atomic range.
  */
-export const refEditor = ({ mode = 'ref', getRef, match }: RefEditorExtensionOptions = {}): Extension => {
+export const refEditor = ({ mode = 'ref', getRef, match, colorize }: RefEditorExtensionOptions = {}): Extension => {
+  // Forward declaration: the field is defined below but the widgets' delete affordance (built inside
+  // the field's `create`/`update`) needs to read it back at click time.
+  let decoField: StateField<DecorationSet>;
+
+  /** Delete the tag whose delete affordance (`node`) was clicked, keeping the delimited list well-formed. */
+  const removeToken = (view: EditorView, node: HTMLElement) => {
+    // Tags render in document order, so the button's index among all delete affordances selects the
+    // matching decoration. (A replace-widget's inner DOM has no reliable document position to query.)
+    const index = [...view.contentDOM.querySelectorAll('button[aria-label="Remove"]')].indexOf(node);
+    if (index < 0) {
+      return;
+    }
+    const cursor = view.state.field(decoField).iter();
+    let range: { from: number; to: number } | undefined;
+    for (let current = 0; cursor.value; current++, cursor.next()) {
+      if (current === index) {
+        range = { from: cursor.from, to: cursor.to };
+        break;
+      }
+    }
+    if (!range) {
+      return;
+    }
+
+    const doc = view.state.doc.toString();
+    let { from } = range;
+    const { to } = range;
+    if (mode === 'email' && !/,\s*$/.test(doc.slice(from, to))) {
+      // A last segment carries no trailing ", "; drop the one left dangling by the previous segment.
+      const dangling = doc.slice(0, from).match(/,\s*$/);
+      if (dangling) {
+        from -= dangling[0].length;
+      }
+    }
+    view.dispatch({ changes: { from, to }, selection: { anchor: from } });
+  };
+
   const buildRefDecorations = (state: EditorState) => {
     const deco = new RangeSetBuilder<Decoration>();
     const text = state.doc.toString();
@@ -78,9 +123,12 @@ export const refEditor = ({ mode = 'ref', getRef, match }: RefEditorExtensionOpt
           deco.add(
             from,
             to,
-            Decoration.widget({
-              widget: new RefWidget(ref.label, ref.hue ?? getHashHue(refMatch[1])),
-              atomic: true,
+            Decoration.replace({
+              widget: new RefWidget(
+                ref.label,
+                ref.hue ?? (colorize ? getHashHue(refMatch[1]) : undefined),
+                removeToken,
+              ),
             }),
           );
         }
@@ -91,9 +139,8 @@ export const refEditor = ({ mode = 'ref', getRef, match }: RefEditorExtensionOpt
         deco.add(
           from,
           to,
-          Decoration.widget({
-            widget: new TokenWidget(token),
-            atomic: true,
+          Decoration.replace({
+            widget: new RefWidget(token, undefined, removeToken),
           }),
         );
       }
@@ -117,6 +164,12 @@ export const refEditor = ({ mode = 'ref', getRef, match }: RefEditorExtensionOpt
       if (!content) {
         continue;
       }
+      // Only tag committed segments (those with a trailing comma). The final segment being typed has
+      // no comma yet, so a valid-looking address stays plain text until the user commits it (comma,
+      // space, or Enter) — otherwise the tag would pop in mid-typing.
+      if (commaIndex === -1) {
+        continue;
+      }
       const leading = segment.length - segment.trimStart().length;
       const from = segmentMatch.index + leading;
       const to = segmentMatch.index + segment.length;
@@ -126,18 +179,20 @@ export const refEditor = ({ mode = 'ref', getRef, match }: RefEditorExtensionOpt
         deco.add(
           from,
           to,
-          Decoration.widget({
-            widget: new RefWidget(nameAddr[1] || nameAddr[2], getHashHue(nameAddr[2])),
-            atomic: true,
+          Decoration.replace({
+            widget: new RefWidget(
+              nameAddr[1] || nameAddr[2],
+              colorize ? getHashHue(nameAddr[2]) : undefined,
+              removeToken,
+            ),
           }),
         );
       } else if (addrRegex.test(content)) {
         deco.add(
           from,
           to,
-          Decoration.widget({
-            widget: new TokenWidget(content),
-            atomic: true,
+          Decoration.replace({
+            widget: new RefWidget(content, undefined, removeToken),
           }),
         );
       }
@@ -148,55 +203,105 @@ export const refEditor = ({ mode = 'ref', getRef, match }: RefEditorExtensionOpt
 
   const buildDecorations = mode === 'email' ? buildEmailDecorations : buildRefDecorations;
 
-  return [
-    styles,
-    StateField.define<DecorationSet>({
-      create: (state) => buildDecorations(state),
-      update: (deco, tr) => {
-        if (tr.docChanged || tr.effects.some((effect) => effect.is(refEditorRedecorate))) {
-          return buildDecorations(tr.state);
+  decoField = StateField.define<DecorationSet>({
+    create: (state) => buildDecorations(state),
+    update: (deco, tr) => {
+      if (tr.docChanged || tr.effects.some((effect) => effect.is(refEditorRedecorate))) {
+        return buildDecorations(tr.state);
+      }
+
+      return deco;
+    },
+    provide: (field) => [
+      EditorView.decorations.from(field),
+      // Every tag is atomic: arrow motion skips the whole range and deletion removes the whole token.
+      EditorView.atomicRanges.of((view) => view.state.field(field)),
+    ],
+  });
+
+  const separator = mode === 'email' ? ', ' : ' ';
+
+  // Typing immediately before a tag would otherwise re-tokenize into it (e.g. `x` + `bob@e.com`
+  // parses as the single email `xbob@e.com`); inject the delimiter after the inserted text so the
+  // new characters begin their own token (and open a fresh completion) rather than joining the tag.
+  const separatorFilter = EditorState.transactionFilter.of((tr) => {
+    if (!tr.docChanged || !tr.isUserEvent('input')) {
+      return tr;
+    }
+    const tags = tr.startState.field(decoField, false);
+    if (!tags) {
+      return tr;
+    }
+
+    let extra: TransactionSpec | undefined;
+    tr.changes.iterChanges((fromA, toA, _fromB, toB, inserted) => {
+      if (extra || fromA !== toA) {
+        return;
+      }
+      const text = inserted.toString();
+      if (!text || /[\s,]$/.test(text)) {
+        return;
+      }
+      // A tag starting exactly at the insertion point means the new text abuts it.
+      let abutsTag = false;
+      for (const cursor = tags.iter(); cursor.value; cursor.next()) {
+        if (cursor.from === fromA) {
+          abutsTag = true;
+          break;
         }
+        if (cursor.from > fromA) {
+          break;
+        }
+      }
+      if (abutsTag) {
+        extra = { changes: { from: toB, insert: separator }, sequential: true, selection: { anchor: toB } };
+      }
+    });
+
+    return extra ? [tr, extra] : tr;
+  });
 
-        return deco;
-      },
-      provide: (field) => [
-        EditorView.decorations.from(field),
-        EditorView.atomicRanges.of((view) => {
-          const builder = new RangeSetBuilder<Decoration>();
-          const cursor = view.state.field(field).iter();
-          while (cursor.value) {
-            if (cursor.value.spec.atomic) {
-              builder.add(cursor.from, cursor.to, cursor.value);
-            }
-            cursor.next();
-          }
-
-          return builder.finish();
-        }),
-      ],
-    }),
-  ];
+  return [styles, decoField, separatorFilter];
 };
 
-const lineHeight = '30px';
+/** Delete an atomic tag given the DOM node of its widget. */
+type RemoveToken = (view: EditorView, node: HTMLElement) => void;
 
 /**
- * NOTE: The outer container vertically aligns the inner text with content in the outer div.
+ * The outer span vertically aligns the tag with the surrounding line and adds a trailing gap so
+ * adjacent tags don't touch. The inner span carries the border; `overflow-hidden` clips the child
+ * fills to its radius (a square-cornered fill otherwise peeks past the rounded border).
  */
 const container = (classNames: string, ...children: Domino<HTMLElement>[]) => {
   const inner = Domino.of('span')
-    .classNames(mx('inline-flex h-[26px] border rounded-xs', classNames))
+    .classNames(mx('inline-flex items-stretch border rounded-xs overflow-hidden', classNames))
     .append(...children);
-  return Domino.of('span').classNames('inline-flex h-[28px] align-middle').append(inner).root;
+  return Domino.of('span').classNames('inline-flex align-middle pe-1').append(inner).root;
+};
+
+/** Trailing `x` affordance that deletes the tag it belongs to. */
+const deleteButton = (view: EditorView, remove: RemoveToken) => {
+  const button = Domino.of('button')
+    .classNames('flex items-center px-1 text-description hover:text-error cursor-pointer')
+    .attributes({ 'type': 'button', 'aria-label': 'Remove' })
+    .append(Domino.svg('ph--x--bold').classNames('shrink-0 w-3.5 h-3.5'))
+    // `mousedown` + preventDefault so clicking the affordance does not move the editor selection.
+    .on('mousedown', (event) => {
+      event.preventDefault();
+      remove(view, button.root);
+    });
+  return button;
 };
 
 /**
- * Resolved reference (object reference or RFC 5322 mailbox), rendered as the object's label.
+ * Resolved reference (object reference or RFC 5322 mailbox), rendered as the object's label with a
+ * trailing delete affordance.
  */
 class RefWidget extends WidgetType {
   constructor(
     private readonly _label: string,
-    private readonly _hue: string,
+    private readonly _hue: string | undefined,
+    private readonly _remove: RemoveToken,
   ) {
     super();
   }
@@ -205,50 +310,22 @@ class RefWidget extends WidgetType {
     return this._label === other._label && this._hue === other._hue;
   }
 
-  override toDOM() {
-    const { bg: fill, border, surface } = getStyles(this._hue);
-    return container(
-      border,
-      Domino.of('span').classNames(mx('flex items-center px-1 text-black text-xs', fill)).text('@'),
-      Domino.of('span')
-        .classNames(mx('flex items-center px-1 text-subdued text-sm rounded-r-[3px]', surface))
-        .text(this._label),
-    );
-  }
-}
-
-/**
- * Raw token accepted by the pluggable matcher (e.g. an email address).
- */
-class TokenWidget extends WidgetType {
-  constructor(private readonly _token: string) {
-    super();
-  }
-
-  override eq(other: this) {
-    return this._token === other._token;
-  }
-
-  override toDOM() {
+  override toDOM(view: EditorView) {
+    const styles = this._hue ? getStyles(this._hue) : undefined;
     return container(
-      'border-separator',
-      Domino.of('span').classNames('flex items-center px-1 text-subdued text-sm').text(this._token),
+      mx('border-separator rounded-sm', styles?.border),
+      Domino.of('span').classNames('flex items-center ps-2 pe-1').text(this._label),
+      deleteButton(view, this._remove),
     );
   }
 }
 
 const styles = EditorView.theme({
+  // Single-line editor: lay the line out as a centered flex row so text runs and the atomic tag
+  // widgets share a vertical center (avoids `vertical-align` baseline guesswork between the two).
   '.cm-line': {
-    lineHeight,
-  },
-  // Match the standard Input block size (md density): 2.5rem, 2rem on pointer-fine devices.
-  '.cm-scroller': {
+    padding: '0',
+    display: 'flex',
     alignItems: 'center',
-    minHeight: '2.5rem',
-  },
-  '@media (pointer: fine)': {
-    '.cm-scroller': {
-      minHeight: '2rem',
-    },
   },
 });

package/src/components/ViewEditor/ViewEditor.stories.tsx

@@ -7,9 +7,9 @@ import * as Schema from 'effect/Schema';
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
 import { DXN, EID, Filter, JsonSchema, Obj, Query, type QueryAST, Scope, Tag, Type, type View } from '@dxos/echo';
+import { useQuery } from '@dxos/echo-react';
 import { Format } from '@dxos/echo/Format';
 import { type Mutable } from '@dxos/echo/Obj';
-import { useQuery } from '@dxos/react-client/echo';
 import { useClientStory, withClientProvider } from '@dxos/react-client/testing';
 import { useAsyncEffect } from '@dxos/react-ui';
 import { Loading, withLayout, withTheme } from '@dxos/react-ui/testing';

package/src/components/ViewEditor/ViewEditor.tsx

@@ -23,9 +23,9 @@ import {
   Type,
   View,
 } from '@dxos/echo';
+import { useObject, useQuery } from '@dxos/echo-react';
 import { SchemaEx } from '@dxos/effect';
 import { invariant } from '@dxos/invariant';
-import { useObject, useQuery } from '@dxos/react-client/echo';
 import { Input, Message, type ThemedClassName, ToggleIconButton, useTranslation } from '@dxos/react-ui';
 import { QueryForm, type QueryFormProps } from '@dxos/react-ui-components';
 import { OrderedList } from '@dxos/react-ui-list';
@@ -107,7 +107,7 @@ export const ViewEditor = forwardRef<ProjectionModel | null, ViewEditorProps>(
       projectionModel,
     ]);
 
-    const queueTarget = Match.value(view.query.ast).pipe(
+    const feedTarget = Match.value(view.query.ast).pipe(
       Match.when({ type: 'from' }, ({ from }) => {
         if (from._tag !== 'scope') {
           return undefined;
@@ -125,16 +125,16 @@ export const ViewEditor = forwardRef<ProjectionModel | null, ViewEditorProps>(
     const feeds = useQuery(db, Filter.type(Feed.Feed));
 
     const targetRef = useMemo(() => {
-      if (!queueTarget) {
+      if (!feedTarget) {
         return undefined;
       }
-      const targetEid = EID.tryParse(queueTarget);
+      const targetEid = EID.tryParse(feedTarget);
       const feed = feeds.find((feed) => {
-        const feedEid = Feed.getQueueUri(feed);
+        const feedEid = Feed.getFeedUri(feed);
         return feedEid != null && targetEid != null && EID.equals(feedEid, targetEid);
       });
       return feed ? Ref.fromURI(Entity.getURI(feed)) : undefined;
-    }, [queueTarget, feeds]);
+    }, [feedTarget, feeds]);
 
     const viewSchema = useMemo(() => {
       const base = Schema.Struct({
@@ -179,13 +179,13 @@ export const ViewEditor = forwardRef<ProjectionModel | null, ViewEditorProps>(
     const handleUpdate = useCallback(
       (values: any) => {
         const targetValue = values.target;
-        let queueDxn: EID.EID | undefined;
+        let feedDxn: EID.EID | undefined;
 
         if (Ref.isRef(targetValue)) {
           const feedUri = targetValue.uri;
           const feed = feeds.find((feed) => Obj.getURI(feed) === feedUri);
           if (feed) {
-            queueDxn = Feed.getQueueUri(feed);
+            feedDxn = Feed.getFeedUri(feed);
           }
         }
 
@@ -197,7 +197,7 @@ export const ViewEditor = forwardRef<ProjectionModel | null, ViewEditorProps>(
             ? Query.select(Filter.type(EID.isEID(values.query) ? (values.query as EID.EID) : DXN.make(values.query)))
                 .ast
             : JSON.parse(JSON.stringify(values.query));
-        onQueryChanged?.(query, queueDxn);
+        onQueryChanged?.(query, feedDxn);
       },
       [onQueryChanged, mode, feeds],
     );

package/src/hooks/useFormHandler.test.ts

@@ -0,0 +1,85 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { act, renderHook } from '@testing-library/react';
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import { useFormHandler } from './useFormHandler';
+
+const schema = Schema.mutable(
+  Schema.Struct({
+    name: Schema.NonEmptyString,
+    city: Schema.String,
+  }),
+);
+type Values = Schema.Schema.Type<typeof schema>;
+
+// Only the AST `_tag` matters to `onValueChange` (it special-cases numbers), so a plain string AST is enough here.
+const stringAst = Schema.String.ast;
+
+describe('useFormHandler reactive buffering', () => {
+  test('adopts external changes to fields the user is not editing', ({ expect }) => {
+    const { result, rerender } = renderHook(({ values }) => useFormHandler<Values>({ schema, values }), {
+      initialProps: { values: { name: 'Alice', city: 'NYC' } as Partial<Values> },
+    });
+    expect(result.current.getValue(['city'])).toBe('NYC');
+
+    act(() => rerender({ values: { name: 'Alice', city: 'LA' } }));
+    expect(result.current.getValue(['city'])).toBe('LA');
+  });
+
+  test('holds an invalid intermediate edit without snapping back while the source updates another field', ({
+    expect,
+  }) => {
+    const { result, rerender } = renderHook(({ values }) => useFormHandler<Values>({ schema, values }), {
+      initialProps: { values: { name: 'Alice', city: 'NYC' } as Partial<Values> },
+    });
+
+    // Type an invalid (empty) name. A parent that gates on validity would not persist it, so the source is unchanged.
+    act(() => result.current.onValueChange(['name'], stringAst, ''));
+    expect(result.current.getValue(['name'])).toBe('');
+    expect(result.current.isValid).toBe(false);
+
+    // The source updates a different field; the invalid draft must survive and the other field must update.
+    act(() => rerender({ values: { name: 'Alice', city: 'LA' } }));
+    expect(result.current.getValue(['name'])).toBe('');
+    expect(result.current.getValue(['city'])).toBe('LA');
+  });
+
+  test('reconciles an edited field once the source catches up to the committed value', ({ expect }) => {
+    const { result, rerender } = renderHook(({ values }) => useFormHandler<Values>({ schema, values }), {
+      initialProps: { values: { name: 'Alice', city: 'NYC' } as Partial<Values> },
+    });
+
+    // A valid edit is held locally until the source reflects it.
+    act(() => result.current.onValueChange(['name'], stringAst, 'Bob'));
+    expect(result.current.getValue(['name'])).toBe('Bob');
+
+    // Source now carries the committed value: the field reconciles and becomes valid again.
+    act(() => rerender({ values: { name: 'Bob', city: 'NYC' } }));
+    expect(result.current.getValue(['name'])).toBe('Bob');
+    expect(result.current.isValid).toBe(true);
+
+    // A subsequent external change to that same field is adopted (it is no longer treated as a pending edit).
+    act(() => rerender({ values: { name: 'Carol', city: 'NYC' } }));
+    expect(result.current.getValue(['name'])).toBe('Carol');
+  });
+
+  test('keeps an in-progress edit even when the source changes that same field (no snap-back)', ({ expect }) => {
+    const { result, rerender } = renderHook(({ values }) => useFormHandler<Values>({ schema, values }), {
+      initialProps: { values: { name: 'Alice', city: 'NYC' } as Partial<Values> },
+    });
+
+    // Start editing a field...
+    act(() => result.current.onValueChange(['name'], stringAst, 'Bob'));
+    expect(result.current.getValue(['name'])).toBe('Bob');
+
+    // ...the source changes that same field concurrently: the in-progress edit is kept (last-writer-wins on commit),
+    // while an un-edited field still adopts the source. Wholesale object swaps are handled by remounting the form.
+    act(() => rerender({ values: { name: 'Dave', city: 'SF' } }));
+    expect(result.current.getValue(['name'])).toBe('Bob');
+    expect(result.current.getValue(['city'])).toBe('SF');
+  });
+});