@dxos/react-ui-form 0.8.4-main.bc674ce → 0.8.4-main.bcb3aa67d6

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

@@ -6,14 +6,15 @@ import { type Meta, type StoryObj } from '@storybook/react-vite';
 import * as Schema from 'effect/Schema';
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
-import { DXN, Filter, Obj, Query, type QueryAST, Tag, Type } from '@dxos/echo';
+import { DXN, Filter, JsonSchema, Obj, Query, type QueryAST, Tag, Type } from '@dxos/echo';
+import { type View } from '@dxos/echo';
 import { type EchoSchema, Format, type Mutable } from '@dxos/echo/internal';
 import { useQuery } from '@dxos/react-client/echo';
 import { useClientStory, withClientProvider } from '@dxos/react-client/testing';
 import { useAsyncEffect } from '@dxos/react-ui';
-import { withTheme } from '@dxos/react-ui/testing';
-import { type ProjectionModel, View, getTypenameFromQuery } from '@dxos/schema';
-import { Employer, Organization, Person, Project } from '@dxos/types';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { type ProjectionModel, ViewModel, getTypenameFromQuery } from '@dxos/schema';
+import { Employer, Organization, Person, Pipeline } from '@dxos/types';
 
 import { translations } from '../../translations';
 import { TestLayout, VIEW_EDITOR_DEBUG_SYMBOL } from '../testing';
@@ -24,7 +25,7 @@ const types = [
   // TODO(burdon): Get label from annotation.
   { value: Organization.Organization.typename, label: 'Organization' },
   { value: Person.Person.typename, label: 'Person' },
-  { value: Project.Project.typename, label: 'Project' },
+  { value: Pipeline.Pipeline.typename, label: 'Project' },
   { value: Employer.Employer.typename, label: 'Employer' },
 ];
 
@@ -35,9 +36,9 @@ export type ViewEditorDebugObjects = {
   projection: ProjectionModel;
 };
 
-type StoryProps = Pick<ViewEditorProps, 'readonly' | 'mode'>;
+type DefaultStoryProps = Pick<ViewEditorProps, 'readonly' | 'mode'>;
 
-const DefaultStory = (props: StoryProps) => {
+const DefaultStory = (props: DefaultStoryProps) => {
   const { space } = useClientStory();
   const [schema, setSchema] = useState<EchoSchema>();
   const [view, setView] = useState<View.View>();
@@ -53,7 +54,7 @@ const DefaultStory = (props: StoryProps) => {
         salary: Format.Currency(),
       }).pipe(
         Type.object({
-          typename: 'example.com/type/Test',
+          typename: 'com.example.type.test',
           version: '0.1.0',
         }),
       );
@@ -64,16 +65,16 @@ const DefaultStory = (props: StoryProps) => {
         completed: Schema.Boolean,
       }).pipe(
         Type.object({
-          typename: 'example.com/type/Alternate',
+          typename: 'com.example.type.alternate',
           version: '0.1.0',
         }),
       );
 
       const [testSchema] = await space.db.schemaRegistry.register([TestSchema, AlternateSchema]);
-      const view = View.make({
+      const view = ViewModel.make({
         name: 'Test',
         query: Query.select(Filter.type(TestSchema)),
-        jsonSchema: Type.toJsonSchema(TestSchema),
+        jsonSchema: JsonSchema.toJsonSchema(TestSchema),
       });
 
       setSchema(testSchema);
@@ -89,9 +90,9 @@ const DefaultStory = (props: StoryProps) => {
 
       if (props.mode === 'tag') {
         const queue = target && DXN.tryParse(target) ? target : undefined;
-        const query = queue ? Query.fromAst(newQuery).options({ queues: [queue] }) : Query.fromAst(newQuery);
-        Obj.change(view, (v) => {
-          v.query.ast = query.ast as Mutable<typeof query.ast>;
+        const query = queue ? Query.fromAst(newQuery).from({ queues: [queue] }) : Query.fromAst(newQuery);
+        Obj.change(view, (obj) => {
+          obj.query.ast = query.ast as Mutable<typeof query.ast>;
         });
 
         const typename = getTypenameFromQuery(query.ast);
@@ -100,17 +101,17 @@ const DefaultStory = (props: StoryProps) => {
           return;
         }
 
-        const newView = View.make({
+        const newView = ViewModel.make({
           query,
           jsonSchema: newSchema.jsonSchema,
         });
-        Obj.change(view, (v) => {
-          v.projection = Obj.getSnapshot(newView).projection as Mutable<typeof v.projection>;
+        Obj.change(view, (obj) => {
+          obj.projection = Obj.getSnapshot(newView).projection as Mutable<typeof obj.projection>;
         });
         setSchema(() => newSchema);
       } else {
-        Obj.change(view, (v) => {
-          v.query.ast = newQuery as Mutable<typeof newQuery>;
+        Obj.change(view, (obj) => {
+          obj.query.ast = newQuery as Mutable<typeof newQuery>;
         });
         schema.updateTypename(getTypenameFromQuery(newQuery));
       }
@@ -175,7 +176,8 @@ const meta = {
         space.db.add(Tag.make({ label: 'New' }));
       },
     }),
-    withTheme,
+    withTheme(),
+    withLayout({ layout: 'fullscreen' }),
   ],
   parameters: {
     layout: 'fullscreen',

package/src/components/ViewEditor/ViewEditor.test.tsx

@@ -6,8 +6,9 @@ import { composeStories } from '@storybook/react';
 import { cleanup, fireEvent, screen, waitFor } from '@testing-library/react';
 import { afterEach, describe, expect, test } from 'vitest';
 
+import { View } from '@dxos/echo';
 import { EchoSchema, isInstanceOf } from '@dxos/echo/internal';
-import { ProjectionModel, View } from '@dxos/schema';
+import { ProjectionModel } from '@dxos/schema';
 
 import { VIEW_EDITOR_DEBUG_SYMBOL } from '../testing';
 
@@ -89,14 +90,10 @@ describe('ViewEditor', () => {
     await Default.run();
     await waitForViewEditor();
 
-    // Click the add property button.
+    // Click the add property button. The new field is auto-expanded by handleAdd.
     const addButton = screen.getByText('Add property');
     fireEvent.click(addButton);
 
-    // Open the last field.
-    const buttons = screen.getAllByTestId('field.toggle');
-    fireEvent.click(buttons.at(-1)!);
-
     // Fill out the property field.
     const fieldInput = screen.getByPlaceholderText('Property name');
     fireEvent.change(fieldInput, { target: { value: 'added_property' } });

package/src/components/ViewEditor/ViewEditor.tsx

@@ -9,19 +9,18 @@ import * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
 import React, { forwardRef, useCallback, useContext, useImperativeHandle, useMemo, useState } from 'react';
 
-import { Filter, Format, Obj, Query, QueryAST, type SchemaRegistry } from '@dxos/echo';
+import { Entity, Feed, Filter, Format, Obj, Query, QueryAST, Ref, type SchemaRegistry } from '@dxos/echo';
+import { View } from '@dxos/echo';
 import { EchoSchema, type JsonProp, isMutable, toJsonSchema } from '@dxos/echo/internal';
 import { invariant } from '@dxos/invariant';
-import { useObject } from '@dxos/react-client/echo';
-import { Callout, IconButton, Input, type ThemedClassName, useTranslation } from '@dxos/react-ui';
+import { useObject, useQuery } from '@dxos/react-client/echo';
+import { IconButton, Input, Message, type ThemedClassName, useTranslation } from '@dxos/react-ui';
 import { QueryForm, type QueryFormProps } from '@dxos/react-ui-components';
 import { List } from '@dxos/react-ui-list';
 import {
-  FieldSchema,
-  type FieldType,
+  ParentLabelAnnotation,
   ProjectionModel,
   VIEW_FIELD_LIMIT,
-  type View,
   createEchoChangeCallback,
   getTypenameFromQuery,
 } from '@dxos/schema';
@@ -35,22 +34,20 @@ import {
   type FormFieldComponentProps,
   FormFieldLabel,
   type FormFieldMap,
+  type FormRootProps,
 } from '../Form';
 
-const listGrid = 'grid grid-cols-[min-content_1fr_min-content_min-content_min-content]';
-const listItemGrid = 'grid grid-cols-subgrid col-span-5';
-
 export type ViewEditorProps = ThemedClassName<
   {
     schema: Schema.Schema.AnyNoContext;
     view: View.View;
     mode?: 'schema' | 'tag';
     registry?: SchemaRegistry.SchemaRegistry;
-    readonly?: boolean;
     showHeading?: boolean;
     onQueryChanged?: (query: QueryAST.Query, target?: string) => void;
     onDelete?: (fieldId: string) => void;
-  } & Pick<QueryFormProps, 'types' | 'tags'>
+  } & Pick<QueryFormProps, 'types' | 'tags'> &
+    Pick<FormRootProps<any>, 'readonly' | 'db'>
 >;
 
 /**
@@ -64,6 +61,7 @@ export const ViewEditor = forwardRef<ProjectionModel, ViewEditorProps>(
       view,
       mode = 'schema',
       registry,
+      db,
       readonly,
       showHeading = false,
       types,
@@ -96,18 +94,31 @@ export const ViewEditor = forwardRef<ProjectionModel, ViewEditorProps>(
     }, [atomRegistry, schema, view]);
 
     useImperativeHandle(forwardedRef, () => projectionModel, [projectionModel]);
-    const [expandedField, setExpandedField] = useState<FieldType['id']>();
 
     const queueTarget = Match.value(view.query.ast).pipe(
-      Match.when({ type: 'options' }, ({ options }) => {
-        return Option.fromNullable(options.queues).pipe(
+      Match.when({ type: 'from' }, ({ from }) => {
+        if (from._tag !== 'scope') {
+          return undefined;
+        }
+        return Option.fromNullable(from.scope.queues).pipe(
           Option.flatMap((queues) => Array.head(queues)),
+          Option.map(String),
           Option.getOrUndefined,
         );
       }),
       Match.orElse(() => undefined),
     );
 
+    const feeds = useQuery(db, Filter.type(Feed.Feed));
+
+    const targetRef = useMemo(() => {
+      if (!queueTarget) {
+        return undefined;
+      }
+      const feed = feeds.find((feed) => Feed.getQueueDxn(feed)?.toString() === queueTarget);
+      return feed ? Ref.fromDXN(Entity.getDXN(feed)) : undefined;
+    }, [queueTarget, feeds]);
+
     const viewSchema = useMemo(() => {
       const base = Schema.Struct({
         query:
@@ -119,7 +130,12 @@ export const ViewEditor = forwardRef<ProjectionModel, ViewEditorProps>(
       if (mode === 'tag') {
         return Schema.Struct({
           ...base.fields,
-          target: Schema.optional(Schema.String.annotations({ title: 'Target Queue' })),
+          // TODO(wittjosiah): Replace Type.Feed with Dataset.Dataset when Ref.Ref supports unions.
+          target: Ref.Ref(Feed.Feed).pipe(
+            Schema.annotations({ title: 'Target Feed' }),
+            ParentLabelAnnotation.set(true),
+            Schema.optional,
+          ),
         }).pipe(Schema.mutable);
       }
 
@@ -131,9 +147,9 @@ export const ViewEditor = forwardRef<ProjectionModel, ViewEditorProps>(
     const viewValues = useMemo(
       () => ({
         query: mode === 'schema' ? getTypenameFromQuery(view.query.ast) : view.query.ast,
-        target: queueTarget,
+        target: targetRef,
       }),
-      [mode, view.query.ast, queueTarget],
+      [mode, view.query.ast, targetRef],
     );
 
     const fieldMap = useMemo<FormFieldMap | undefined>(
@@ -141,49 +157,51 @@ export const ViewEditor = forwardRef<ProjectionModel, ViewEditorProps>(
       [mode, types, tags],
     );
 
-    // TODO(burdon): Check if mutable.
-    const handleAdd = useCallback(() => {
-      invariant(!readonly);
-      const field = projectionModel.createFieldProjection();
-      setExpandedField(field.id);
-    }, [projectionModel, readonly]);
-
     const handleUpdate = useCallback(
       (values: any) => {
-        requestAnimationFrame(() => {
-          const query = mode === 'schema' ? Query.select(Filter.typename(values.query)).ast : values.query;
-          onQueryChanged?.(query, values.target);
-        });
+        const targetValue = values.target;
+        let queueDxn: string | undefined;
+
+        if (Ref.isRef(targetValue)) {
+          const feedDxn = targetValue.dxn.toString();
+          const feed = feeds.find((feed) => Obj.getDXN(feed).toString() === feedDxn);
+          if (feed) {
+            queueDxn = Feed.getQueueDxn(feed)?.toString();
+          }
+        }
+
+        // TODO(wittjosiah): Deep-clone the AST to plain JS or ECHO proxy arrays become objects with numeric keys.
+        const query =
+          mode === 'schema'
+            ? Query.select(Filter.typename(values.query)).ast
+            : JSON.parse(JSON.stringify(values.query));
+        onQueryChanged?.(query, queueDxn);
       },
-      [onQueryChanged, view, queueTarget, mode],
+      [onQueryChanged, mode, feeds],
     );
 
     const handleDelete = useCallback(
       (fieldId: string) => {
         invariant(!readonly);
-        if (fieldId === expandedField) {
-          setExpandedField(undefined);
-        }
-
         onDelete?.(fieldId);
       },
-      [expandedField, onDelete, readonly],
+      [onDelete, readonly],
     );
 
     return (
       <div role='none' className={mx(classNames)}>
         {/* If readonly is set, then the callout is not needed. */}
         {schemaReadonly && !readonly && (
-          <Callout.Root valence='info' classNames='mlb-cardSpacingBlock'>
-            <Callout.Title>{t('system schema description')}</Callout.Title>
-          </Callout.Root>
+          <Message.Root valence='info' classNames='my-form-padding'>
+            <Message.Title>{t('system-schema.description')}</Message.Title>
+          </Message.Root>
         )}
 
         {/* TODO(burdon): Is the form read-only or just the schema? */}
-        <Form.Root schema={viewSchema} values={viewValues} fieldMap={fieldMap} autoSave onSave={handleUpdate}>
+        <Form.Root schema={viewSchema} values={viewValues} fieldMap={fieldMap} db={db} onValuesChanged={handleUpdate}>
           <Form.FieldSet />
 
-          <FormFieldLabel label={t('fields label')} asChild />
+          <FormFieldLabel label={t('fields.label')} asChild />
           <FieldList
             schema={schema}
             view={view}
@@ -193,19 +211,6 @@ export const ViewEditor = forwardRef<ProjectionModel, ViewEditorProps>(
             onDelete={handleDelete}
           />
         </Form.Root>
-
-        {!readonly && !expandedField && (
-          <div role='none' className='mlb-cardSpacingBlock'>
-            <IconButton
-              icon='ph--plus--regular'
-              label={t('add property button label')}
-              onClick={readonly ? undefined : handleAdd}
-              // TODO(burdon): Show field limit in ux (not tooltip).
-              disabled={view.projection.fields.length >= VIEW_FIELD_LIMIT}
-              classNames='is-full'
-            />
-          </div>
-        )}
       </div>
     );
   },
@@ -239,10 +244,16 @@ const FieldList = ({ schema, view, registry, readonly, showHeading = false, onDe
     return model;
   }, [atomRegistry, schema, view]);
 
-  const [expandedField, setExpandedField] = useState<FieldType['id']>();
+  const [expandedField, setExpandedField] = useState<View.FieldType['id']>();
+
+  const handleAdd = useCallback(() => {
+    invariant(!readonly);
+    const field = projectionModel.createFieldProjection();
+    setExpandedField(field.id);
+  }, [projectionModel, readonly]);
 
   const handleToggleField = useCallback(
-    (field: FieldType) => {
+    (field: View.FieldType) => {
       setExpandedField((prevExpandedFieldId) => (prevExpandedFieldId === field.id ? undefined : field.id));
     },
     [readonly],
@@ -263,12 +274,12 @@ const FieldList = ({ schema, view, registry, readonly, showHeading = false, onDe
   const handleMove = useCallback(
     (fromIndex: number, toIndex: number) => {
       invariant(!readonly);
-      Obj.change(view, (v) => {
+      Obj.change(view, (obj) => {
         // NOTE(ZaymonFC): Using arrayMove here causes a race condition with the kanban model.
-        const fields = [...v.projection.fields];
+        const fields = [...obj.projection.fields];
         const [moved] = fields.splice(fromIndex, 1);
         fields.splice(toIndex, 0, moved);
-        v.projection.fields = fields;
+        obj.projection.fields = fields;
       });
     },
     [view, readonly],
@@ -297,32 +308,39 @@ const FieldList = ({ schema, view, registry, readonly, showHeading = false, onDe
   }
 
   return (
-    <List.Root<FieldType>
-      items={viewSnapshot.projection.fields as FieldType[]}
-      isItem={Schema.is(FieldSchema)}
+    <List.Root<View.FieldType>
+      items={viewSnapshot.projection.fields as View.FieldType[]}
+      isItem={Schema.is(View.FieldSchema)}
       getId={(field) => field.id}
       onMove={readonly ? undefined : handleMove}
       readonly={readonly}
     >
       {({ items: fields }) => (
         <>
-          {showHeading && <h3 className='text-sm'>{t('field path label')}</h3>}
-          <div role='list' className={listGrid}>
+          {showHeading && <h3 className='text-sm'>{t('field-path.label')}</h3>}
+          <div role='list' className='grid grid-cols-[min-content_1fr_min-content_min-content_min-content]'>
             {fields?.map((field) => {
               const hidden = field.visible === false;
               return (
-                <List.Item<FieldType>
+                <List.Item<View.FieldType>
                   key={field.id}
                   item={field}
-                  classNames={listItemGrid}
+                  classNames={'grid grid-cols-subgrid col-span-5'}
                   aria-expanded={expandedField === field.id}
                 >
-                  <div role='none' className={mx(subtleHover, listItemGrid, 'rounded-sm cursor-pointer min-bs-10')}>
+                  <div
+                    role='none'
+                    className={mx(
+                      subtleHover,
+                      'grid grid-cols-subgrid col-span-5',
+                      'rounded-xs cursor-pointer min-h-10',
+                    )}
+                  >
                     <List.ItemDragHandle disabled={readonly || schemaReadonly} />
                     <List.ItemTitle classNames={hidden && 'text-subdued'} onClick={() => handleToggleField(field)}>
                       {field.path}
                     </List.ItemTitle>
-                    <List.ItemButton
+                    <List.ItemIconButton
                       label={t(hidden ? 'show field label' : 'hide field label')}
                       data-testid={hidden ? 'show-field-button' : 'hide-field-button'}
                       icon={hidden ? 'ph--eye-closed--regular' : 'ph--eye--regular'}
@@ -333,16 +351,16 @@ const FieldList = ({ schema, view, registry, readonly, showHeading = false, onDe
                     {!readonly && (
                       <>
                         <List.ItemDeleteButton
-                          label={t('delete field label')}
+                          label={t('delete-field.label')}
                           autoHide={false}
                           disabled={readonly || schemaReadonly || viewSnapshot.projection.fields.length <= 1}
                           onClick={() => handleDelete(field.id)}
                           data-testid='field.delete'
                         />
-                        <IconButton
+                        <List.ItemIconButton
                           iconOnly
                           variant='ghost'
-                          label={t('toggle expand label', { ns: osTranslations })}
+                          label={t('toggle-expand.label', { ns: osTranslations })}
                           icon={expandedField === field.id ? 'ph--caret-down--regular' : 'ph--caret-right--regular'}
                           onClick={() => handleToggleField(field)}
                           data-testid='field.toggle'
@@ -351,7 +369,7 @@ const FieldList = ({ schema, view, registry, readonly, showHeading = false, onDe
                     )}
                   </div>
                   {expandedField === field.id && !readonly && (
-                    <div role='none' className='col-span-5 mbs-1 mbe-1 border border-separator rounded-md'>
+                    <div role='none' className='col-span-5 mt-1 mb-1 border border-separator rounded-md'>
                       <FieldEditor
                         readonly={readonly || schemaReadonly}
                         registry={registry}
@@ -365,6 +383,17 @@ const FieldList = ({ schema, view, registry, readonly, showHeading = false, onDe
               );
             })}
           </div>
+          {!readonly && !expandedField && (
+            <div role='none' className='my-form-padding'>
+              <IconButton
+                icon='ph--plus--regular'
+                label={t('add-property-button.label')}
+                onClick={handleAdd}
+                disabled={viewSnapshot.projection.fields.length >= VIEW_FIELD_LIMIT}
+                classNames='w-full'
+              />
+            </div>
+          )}
         </>
       )}
     </List.Root>

package/src/components/index.ts

@@ -2,8 +2,8 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './ControlSection';
 export * from './FieldEditor';
 export * from './Form';
 export * from './ObjectPicker';
+export * from './Settings';
 export * from './ViewEditor';

package/src/components/testing.tsx

@@ -4,19 +4,27 @@
 
 import React, { type PropsWithChildren } from 'react';
 
-import { type ThemedClassName } from '@dxos/react-ui';
-import { Card } from '@dxos/react-ui-mosaic';
-import { JsonFilter } from '@dxos/react-ui-syntax-highlighter';
-import { textBlockWidth } from '@dxos/ui-theme';
+import { Column, type ThemedClassName } from '@dxos/react-ui';
+import { Json } from '@dxos/react-ui-syntax-highlighter';
+import { mx } from '@dxos/ui-theme';
 
 type TestLayoutProps = ThemedClassName<PropsWithChildren<{ json?: any }>>;
 
 export const TestLayout = ({ classNames, children, json }: TestLayoutProps) => {
   return (
-    <div className='is-full bs-full grid grid-cols-[1fr_1fr] p-4 gap-4 overflow-hidden'>
-      <TestPanel classNames={['flex flex-col bs-full overflow-y-auto', classNames]}>{children}</TestPanel>
+    <div className='h-full w-full grid grid-cols-[1fr_1fr] p-4 gap-4 overflow-hidden'>
+      <TestPanel classNames={['dx-container', classNames]}>
+        <Column.Root classNames='dx-container' gutter='sm'>
+          {children}
+        </Column.Root>
+      </TestPanel>
       <TestPanel classNames={'overflow-hidden'}>
-        <JsonFilter testId='debug' data={json} classNames='bs-full text-xs' />
+        <Json.Root data={json}>
+          <Json.Content classNames='h-full'>
+            <Json.Filter />
+            <Json.Data testId='debug' classNames='text-xs' />
+          </Json.Content>
+        </Json.Root>
       </TestPanel>
     </div>
   );
@@ -25,7 +33,11 @@ export const TestLayout = ({ classNames, children, json }: TestLayoutProps) => {
 type TestPanelProps = ThemedClassName<PropsWithChildren>;
 
 const TestPanel = ({ classNames, children }: TestPanelProps) => {
-  return <Card.Root classNames={['bs-full overflow-y-auto', textBlockWidth, classNames]}>{children}</Card.Root>;
+  return (
+    <div role='none' className={mx(['dx-document h-full bg-modal-surface rounded-md', classNames])}>
+      {children}
+    </div>
+  );
 };
 
 // Symbol for accessing debug objects in tests.

package/src/hooks/useFormHandler.ts

@@ -7,22 +7,13 @@ import type * as Schema from 'effect/Schema';
 import type * as SchemaAST from 'effect/SchemaAST';
 import { useCallback, useEffect, useMemo, useState } from 'react';
 
-import { Obj } from '@dxos/echo';
 import { type AnyProperties } from '@dxos/echo/internal';
-import {
-  type JsonPath,
-  createJsonPath,
-  fromEffectValidationPath,
-  getValue as getValue$,
-  setValue as setValue$,
-} from '@dxos/effect';
+import { type JsonPath, createJsonPath, fromEffectValidationPath, getValue as getValue$ } from '@dxos/effect';
 import { log } from '@dxos/log';
 import { useDefaultValue } from '@dxos/react-ui';
 import { type ValidationError, validateSchema } from '@dxos/schema';
 import { type MaybePromise } from '@dxos/util';
 
-import { setValueEchoAware } from '../util';
-
 export type FormFieldStatus = {
   status?: 'error';
   error?: string;
@@ -139,11 +130,15 @@ export const useFormHandler = <T extends AnyProperties>({
     prop: valuesProp,
     defaultProp: defaultValues,
     onChange: () => {
-      setValues(valuesProp ?? defaultValues);
-      setChanged({});
-      setTouched({});
-      setErrors({});
-      setSaving(false);
+      // Only reset when controlled: parent passed new values.
+      // Uncontrolled updates come from setValues in onValueChange.
+      if (valuesProp !== undefined) {
+        setValues(valuesProp ?? defaultValues);
+        setChanged({});
+        setTouched({});
+        setErrors({});
+        setSaving(false);
+      }
     },
   });
   // TODO(wittjosiah): Upgrade @radix-ui/react-use-controllable-state.
@@ -259,6 +254,7 @@ export const useFormHandler = <T extends AnyProperties>({
       log('onValueChange', { path, value });
 
       const jsonPath = createJsonPath(path);
+      const pathArray = path;
       let parsedValue = value as any;
       try {
         if (type._tag === 'NumberKeyword') {
@@ -269,24 +265,25 @@ export const useFormHandler = <T extends AnyProperties>({
         parsedValue = undefined;
       }
 
-      // Update.
-      // For ECHO objects, mutate in place via Obj.change(); for plain objects, spread to create new reference.
-      const newValues = Obj.isObject(values)
-        ? (setValueEchoAware(values, jsonPath, parsedValue), values)
-        : { ...setValue$(values, jsonPath, parsedValue) };
-      setValues(newValues);
+      // Create merged values for validation and callback. Form never mutates; parent applies via onValuesChanged.
+      const newValues = mergeAtPath(values, pathArray as (string | number)[], parsedValue) as Partial<T>;
 
       // TODO(burdon): Check value has changed from original.
       const newChanged = { [jsonPath]: true };
-      setChanged({ ...changed, ...newChanged });
+      setChanged((prev) => ({ ...prev, ...newChanged }));
 
       // Validate.
       const isValid = validate(newValues);
 
-      // Callback.
+      // Notify parent; parent is responsible for applying the change.
       onValuesChanged?.(newValues, { isValid, changed: newChanged });
+
+      // For uncontrolled mode, update internal state. Controlled mode relies on parent to pass new values.
+      if (valuesProp === undefined) {
+        setValues(newValues);
+      }
     },
-    [values, changed, validate, onValuesChanged],
+    [values, validate, onValuesChanged, valuesProp],
   );
 
   const onBlur = useCallback(
@@ -347,6 +344,27 @@ export const useFormHandler = <T extends AnyProperties>({
   );
 };
 
+/**
+ * Creates a new object with value at path. Does not mutate source.
+ * Preserves arrays when path segments are numeric indices.
+ */
+const mergeAtPath = (obj: any, path: readonly (string | number)[], value: any): any => {
+  if (path.length === 0) {
+    return value;
+  }
+
+  const [head, ...rest] = path;
+  const child = rest.length === 0 ? value : mergeAtPath(obj?.[head], rest, value);
+
+  if (Array.isArray(obj)) {
+    const copy = [...obj];
+    copy[head as number] = child;
+    return copy;
+  }
+
+  return { ...obj, [head]: child };
+};
+
 const flatMap = (errors: ValidationError[]) => {
   return errors.reduce(
     (result, { path, message }) => {