@dxos/react-ui-form 0.8.4-main.d05673bc65 → 0.8.4-main.d9fc60f731

package/src/components/Form/fields/TupleField.tsx

@@ -17,6 +17,7 @@ export const TupleField = ({
   type,
   readonly,
   label,
+  jsonPath,
   getStatus,
   getValue,
   onValueChange,
@@ -31,8 +32,8 @@ export const TupleField = ({
 
   return (
     <Input.Root validationValence={status}>
-      <FormFieldLabel error={error} readonly={readonly} label={label} />
-      <div className={mx('grid gap-2', gridCols[binding.length - 1])}>
+      <FormFieldLabel error={error} readonly={readonly} label={label} path={jsonPath} />
+      <div className={mx('grid gap-form-gap', gridCols[binding.length - 1])}>
         {binding.map((prop) => (
           <Input.TextInput
             key={prop}

package/src/components/Form/fields/index.ts

@@ -4,7 +4,9 @@
 
 export * from './ArrayField';
 export * from './BooleanField';
+export * from './DateField';
 export * from './GeoPointField';
+export * from './InlineRefField';
 export * from './MarkdownField';
 export * from './NumberField';
 export * from './RefField';

package/src/components/Form/index.ts

@@ -6,3 +6,6 @@ export * from './fields';
 
 export * from './Form';
 export * from './FormFieldComponent';
+export * from './FormTooltipsContext';
+export * from './meta-tags';
+export * from './Layout';

package/src/components/Form/meta-tags.test.ts

@@ -0,0 +1,47 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+import { describe, test } from 'vitest';
+
+import { Obj, Ref, Tag } from '@dxos/echo';
+
+import { META_TAGS_KEY, withMetaTags } from './meta-tags';
+
+// A feed-host schema whose own `tags` field is a `TagIndex` record (tagId -> objectId[]), not an
+// array — mirrors plugin-commerce `Search`, plugin-inbox `Mailbox`, plugin-feed `Subscription`.
+const TagIndexHost = Schema.Struct({
+  name: Schema.String.pipe(Schema.optional),
+  tags: Schema.Record({ key: Schema.String, value: Schema.Array(Obj.ID) }).pipe(Schema.optional),
+});
+
+const propertyNames = (schema: Schema.Schema.AnyNoContext): string[] =>
+  SchemaAST.getPropertySignatures(schema.ast).map((property) => property.name.toString());
+
+describe('withMetaTags', () => {
+  test('keying meta-tags as `tags` collides with a schema-declared `tags` record (regression)', ({ expect }) => {
+    // The pre-fix shape: splice a `tags: Array<Ref<Tag>>` onto a schema that already declares `tags`.
+    // `Schema.extend` cannot merge an array with a record at the same key, hence the companion crash:
+    // "overlapping types at path: [\"tags\"]".
+    expect(() =>
+      Schema.Struct({ tags: Schema.Array(Ref.Ref(Tag.Tag)).pipe(Schema.optional) }).pipe(Schema.extend(TagIndexHost)),
+    ).toThrow(/tags/i);
+  });
+
+  test('splices meta-tags under `_tags` without colliding with a schema-declared `tags`', ({ expect }) => {
+    const schema = withMetaTags(TagIndexHost);
+    const names = propertyNames(schema);
+    expect(names).toContain(META_TAGS_KEY);
+    expect(names).toContain('tags');
+    expect(names).not.toContain('id');
+  });
+
+  test('still splices meta-tags onto a schema with no `tags` field', ({ expect }) => {
+    const Plain = Schema.Struct({ name: Schema.String });
+    const names = propertyNames(withMetaTags(Plain));
+    expect(names).toContain(META_TAGS_KEY);
+    expect(names).toContain('name');
+  });
+});

package/src/components/Form/meta-tags.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Ref, Tag } from '@dxos/echo';
+
+import { omitId } from './Form';
+
+/**
+ * Form-field key for the synthetic meta-tags array spliced into property/create forms.
+ *
+ * An object's tags live in `Obj.getMeta(obj).tags` (off-schema), so the form surfaces them as an
+ * extra field rather than reading the schema. The key is underscore-prefixed so it never collides
+ * with a `tags` field an object schema declares itself — e.g. a `TagIndex` record on a feed host,
+ * whose `tags` is `Record<tagId, objectId[]>`, not an array. Extending such a schema with a `tags`
+ * array threw "overlapping types at path: [\"tags\"]"; the disjoint `_tags` key avoids it. The
+ * human-facing label is restored via the `title` annotation on {@link withMetaTags}.
+ */
+export const META_TAGS_KEY = '_tags';
+
+/**
+ * Splices the synthetic meta-tags array (an object's `meta.tags`, surfaced as {@link Tag} refs) onto
+ * a schema for editing and drops `id`. Keyed by {@link META_TAGS_KEY} so it never collides with a
+ * `tags` field the schema declares itself.
+ */
+export const withMetaTags = (schema: Schema.Schema.AnyNoContext) =>
+  omitId(
+    Schema.Struct({
+      [META_TAGS_KEY]: Schema.Array(Ref.Ref(Tag.Tag)).pipe(Schema.annotations({ title: 'Tags' }), Schema.optional),
+    }).pipe(Schema.extend(schema)),
+  );

package/src/components/ObjectForm/ObjectForm.tsx

@@ -0,0 +1,109 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useCallback, useMemo } from 'react';
+
+import { Obj, Ref, Tag, Type } from '@dxos/echo';
+import { type JsonPath, splitJsonPath } from '@dxos/echo/internal';
+import { invariant } from '@dxos/invariant';
+import { HuePicker } from '@dxos/react-ui-pickers';
+
+import { translationKey } from '#translations';
+
+import { Form, type FormFieldMap, META_TAGS_KEY, withMetaTags } from '../Form';
+
+export type ObjectFormProps = {
+  type: Type.AnyEntity;
+  object: Obj.Unknown;
+};
+
+const createFieldMap: FormFieldMap = {
+  hue: ({ type, label, layout, getValue, onValueChange }) => {
+    const handleChange = useCallback((nextHue: string) => onValueChange(type, nextHue), [onValueChange, type]);
+    const handleReset = useCallback(() => onValueChange(type, undefined), [onValueChange, type]);
+    return (
+      <>
+        {layout !== 'inline' && <Form.Label label={label} />}
+        <HuePicker value={getValue()} onChange={handleChange} onReset={handleReset} />
+      </>
+    );
+  },
+};
+
+export const ObjectForm = ({ object, type }: ObjectFormProps) => {
+  const db = Obj.getDatabase(object);
+  const meta = Obj.getMeta(object);
+  // `meta.tags` already holds `Ref<Tag>`s (materialized by the database handler).
+  const tags = [...meta.tags];
+  const values = useMemo(() => ({ [META_TAGS_KEY]: tags, ...object }), [object, tags]);
+  const formSchema = useMemo(() => withMetaTags(Type.getSchema(type)), [type]);
+
+  const handleCreate = useCallback((type: Type.AnyEntity, values: any) => {
+    invariant(db);
+    invariant(Type.isObject(type));
+    const newObject = db.add(Obj.make(type, values));
+    if (Obj.instanceOf(Tag.Tag, newObject)) {
+      Obj.update(object, (object) => {
+        Obj.getMeta(object).tags = [...Obj.getMeta(object).tags, Ref.make(newObject)];
+      });
+    }
+  }, []);
+
+  // TODO(wittjosiah): Use FormRootProps type.
+  const handleChange = useCallback(
+    (
+      { [META_TAGS_KEY]: metaTags, ...values }: any,
+      { isValid, changed }: { isValid: boolean; changed: Record<JsonPath, boolean> },
+    ) => {
+      if (!isValid) {
+        return;
+      }
+
+      const changedPaths = Object.keys(changed).filter((path) => changed[path as JsonPath]) as JsonPath[];
+
+      // Handle meta-tags separately using Obj.update.
+      const hasTagsChange = changedPaths.some((path) => splitJsonPath(path)[0] === META_TAGS_KEY);
+      if (hasTagsChange) {
+        Obj.update(object, (object) => {
+          // Copy so later in-place form mutations don't bypass the `Obj.update` boundary.
+          Obj.getMeta(object).tags = Array.isArray(metaTags) ? [...(metaTags as Ref.Ref<Tag.Tag>[])] : [];
+        });
+      }
+
+      // Handle other property changes.
+      const nonTagPaths = changedPaths.filter((path) => splitJsonPath(path)[0] !== META_TAGS_KEY);
+      if (nonTagPaths.length > 0) {
+        Obj.update(object, () => {
+          for (const path of nonTagPaths) {
+            const parts = splitJsonPath(path);
+            const value = Obj.getValue(values, parts);
+            Obj.setValue(object, parts, value);
+          }
+        });
+      }
+    },
+    [object],
+  );
+
+  return (
+    <Form.Root
+      schema={formSchema}
+      defaultValues={values}
+      createTypename={Type.getTypename(Tag.Tag)}
+      createOptionIcon='ph--plus--regular'
+      createOptionLabel={['add-tag.label', { ns: translationKey }]}
+      createInitialValuePath='label'
+      createFieldMap={createFieldMap}
+      db={db}
+      onValuesChanged={handleChange}
+      onCreate={handleCreate}
+    >
+      <Form.Viewport>
+        <Form.Content>
+          <Form.FieldSet />
+        </Form.Content>
+      </Form.Viewport>
+    </Form.Root>
+  );
+};

package/src/components/ObjectForm/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './ObjectForm';

package/src/components/ObjectPicker/ObjectPicker.stories.tsx

@@ -7,28 +7,28 @@ import * as Schema from 'effect/Schema';
 import React, { useCallback, useEffect, useMemo, useState } from 'react';
 import { expect, fn, userEvent, within } from 'storybook/test';
 
-import { Obj } from '@dxos/echo';
-import { faker } from '@dxos/random';
-import { Filter, useQuery } from '@dxos/react-client/echo';
+import { Filter, Obj, Type } from '@dxos/echo';
+import { random } from '@dxos/random';
+import { useQuery } from '@dxos/react-client/echo';
 import { useClientStory, withClientProvider } from '@dxos/react-client/testing';
 import { Button } from '@dxos/react-ui';
 import { withTheme } from '@dxos/react-ui/testing';
 import { Person } from '@dxos/types';
 import { osTranslations } from '@dxos/ui-theme';
 
-import { translations } from '../../translations';
+import { translations } from '#translations';
 
 import { ObjectPicker } from './ObjectPicker';
 
-faker.seed(1);
+random.seed(1);
 
 const createPerson = () =>
   Obj.make(Person.Person, {
-    fullName: faker.person.fullName(),
+    fullName: random.person.fullName(),
   });
 
 const omitId = Schema.omit<any, any, ['id']>('id');
-const personSchema = omitId(Person.Person);
+const personSchema = omitId(Type.getSchema(Person.Person));
 
 // Mock functions for testing
 const mockHandleSelect = fn();
@@ -48,7 +48,7 @@ const DefaultStory = () => {
     }
   }, [space]);
 
-  // Get all objects in the space (similar to BoardContainer)
+  // Get all objects in the space (similar to BoardArticle)
   const allObjects = useQuery(space?.db, Filter.everything());
 
   // Map objects to options format expected by ObjectPicker
@@ -65,7 +65,9 @@ const DefaultStory = () => {
   const handleCreateCallback = useCallback(
     (values: any) => {
       console.log('[on create]', values);
-      if (!space) return;
+      if (!space) {
+        return;
+      }
       const newPerson = space.db.add(Obj.make(Person.Person, values));
       mockHandleCreate(values);
       return newPerson;
@@ -74,7 +76,7 @@ const DefaultStory = () => {
   );
 
   return (
-    <div role='none' className='flex w-96'>
+    <div className='w-96'>
       <ObjectPicker.Root open={isOpen} onOpenChange={setIsOpen}>
         <ObjectPicker.Trigger asChild>
           <Button variant='primary' data-testid='trigger' classNames='w-full'>
@@ -85,7 +87,7 @@ const DefaultStory = () => {
           classNames='dx-card-popover-width'
           options={options}
           createSchema={personSchema}
-          createOptionLabel={['create new person label', { ns: osTranslations }]}
+          createOptionLabel={['create-new-person.label', { ns: osTranslations }]}
           createOptionIcon='ph--user-plus--regular'
           createInitialValuePath='fullName'
           onCreate={handleCreateCallback}

package/src/components/ObjectPicker/ObjectPicker.tsx

@@ -6,10 +6,13 @@ import type * as Schema from 'effect/Schema';
 import React, { type KeyboardEvent, forwardRef, useCallback, useState } from 'react';
 
 import { type Palette, Popover, type ThemedClassName, useTranslation } from '@dxos/react-ui';
-import { Combobox, useSearchListInput, useSearchListResults } from '@dxos/react-ui-searchlist';
+import { Combobox } from '@dxos/react-ui-list';
+import { useSearchListResults } from '@dxos/react-ui-search';
+
+import { translationKey } from '#translations';
 
-import { translationKey } from '../../translations';
 import { Form } from '../Form';
+import { type FormFieldMap } from '../Form/FormFieldComponent';
 
 export type RefOption = {
   id: string;
@@ -20,40 +23,22 @@ export type RefOption = {
 export type ObjectPickerContentProps = ThemedClassName<{
   options: RefOption[];
   selectedIds?: string[];
-  createOptionLabel?: [string, { ns: string }];
+  createOptionLabel?: [string, { ns: string | readonly string[] }];
   createOptionIcon?: string;
   createSchema?: Schema.Schema.AnyNoContext;
   createInitialValuePath?: string;
-  onCreate?: (values: any) => void;
+  createFieldMap?: FormFieldMap;
+  /**
+   * Persist a newly-created object given the form values. May be async (e.g.
+   * to write to a database). The Promise is awaited before the inline create
+   * form is collapsed back to the picker list, so consumers can complete
+   * follow-up work (assign the new ref to a parent slot, close the popover)
+   * before the picker UI re-renders.
+   */
+  onCreate?: (values: any) => unknown | Promise<unknown>;
   onSelect: (id: string) => void;
 }>;
 
-const CreateItem = ({
-  createOptionLabel,
-  createOptionIcon,
-  onCreateItemSelect,
-}: {
-  createOptionLabel: [string, { ns: string }];
-  createOptionIcon: string;
-  onCreateItemSelect: (query: string) => void;
-}) => {
-  const { t } = useTranslation(translationKey);
-  const { query } = useSearchListInput();
-
-  return (
-    <Combobox.Item
-      value='__create__'
-      label={t(createOptionLabel[0], { ns: createOptionLabel[1].ns, text: query })}
-      icon={createOptionIcon}
-      classNames='flex items-center gap-2'
-      closeOnSelect={false}
-      onSelect={() => {
-        onCreateItemSelect(query);
-      }}
-    />
-  );
-};
-
 const ObjectPickerContent = forwardRef<HTMLDivElement, ObjectPickerContentProps>(
   (
     {
@@ -63,23 +48,24 @@ const ObjectPickerContent = forwardRef<HTMLDivElement, ObjectPickerContentProps>
       createOptionLabel,
       createOptionIcon,
       createInitialValuePath,
+      createFieldMap,
       onSelect,
       onCreate,
       ...props
     },
-    ref,
+    forwardedRef,
   ) => {
     const { t } = useTranslation(translationKey);
     const [showForm, setShowForm] = useState(false);
     const [formInitialValue, setFormInitialValue] = useState<string>('');
 
-    const { results, handleSearch } = useSearchListResults({
+    const { results, query, handleSearch } = useSearchListResults({
       items: options,
     });
 
     const handleFormSave = useCallback(
-      (values: any) => {
-        onCreate?.(values);
+      async (values: any) => {
+        await onCreate?.(values);
         setShowForm(false);
         setFormInitialValue('');
       },
@@ -112,14 +98,15 @@ const ObjectPickerContent = forwardRef<HTMLDivElement, ObjectPickerContentProps>
       [createSchema],
     );
 
-    return (
-      <Combobox.Content {...props} ref={ref} onSearch={handleSearch} onKeyDownCapture={handleKeyDown}>
-        {showForm && createSchema ? (
+    if (showForm && createSchema) {
+      return (
+        <Combobox.Content {...props} onKeyDownCapture={handleKeyDown} ref={forwardedRef}>
           <Popover.Viewport>
             <Form.Root
               testId='create-referenced-object-form'
               schema={createSchema}
-              values={createInitialValuePath ? { [createInitialValuePath]: formInitialValue } : {}}
+              defaultValues={createInitialValuePath ? { [createInitialValuePath]: formInitialValue } : {}}
+              fieldMap={createFieldMap}
               onSave={handleFormSave}
               onCancel={handleFormCancel}
             >
@@ -131,40 +118,80 @@ const ObjectPickerContent = forwardRef<HTMLDivElement, ObjectPickerContentProps>
               </Form.Viewport>
             </Form.Root>
           </Popover.Viewport>
-        ) : (
-          <>
-            <Combobox.Input placeholder={t('ref field combobox input placeholder')} autoFocus />
-            <Combobox.List>
-              {results.map((option) => (
-                <Combobox.Item
-                  key={option.id}
-                  value={option.id}
-                  label={option.label}
-                  checked={selectedIds?.includes(option.id)}
-                  onSelect={() => onSelect(option.id)}
-                  classNames='flex items-center gap-2'
-                />
-              ))}
-              {createOptionLabel && createOptionIcon && createSchema && onCreate && (
-                <CreateItem
-                  createOptionLabel={createOptionLabel}
-                  createOptionIcon={createOptionIcon}
-                  onCreateItemSelect={(query: string) => {
-                    setFormInitialValue(query);
-                    setShowForm(true);
-                  }}
-                />
-              )}
-            </Combobox.List>
-          </>
-        )}
+          <Combobox.Arrow />
+        </Combobox.Content>
+      );
+    }
+
+    return (
+      <Combobox.Content {...props} onKeyDownCapture={handleKeyDown} ref={forwardedRef}>
+        <Combobox.Input
+          placeholder={t('ref-field-combobox-input.placeholder')}
+          autoFocus
+          value={query}
+          onValueChange={handleSearch}
+        />
+        <Combobox.List>
+          {results.map((option) => (
+            <Combobox.Item
+              key={option.id}
+              value={option.id}
+              label={option.label}
+              checked={selectedIds?.includes(option.id)}
+              onSelect={() => onSelect(option.id)}
+              classNames='flex items-center gap-2'
+            />
+          ))}
+          {createSchema && onCreate && (
+            <CreateItem
+              query={query}
+              createOptionLabel={createOptionLabel}
+              createOptionIcon={createOptionIcon ?? 'ph--plus--regular'}
+              onCreateItemSelect={(currentQuery: string) => {
+                setFormInitialValue(currentQuery);
+                setShowForm(true);
+              }}
+            />
+          )}
+        </Combobox.List>
         <Combobox.Arrow />
       </Combobox.Content>
     );
   },
 );
 
-ObjectPickerContent.displayName = 'ObjectPickerContent';
+const CreateItem = ({
+  query,
+  createOptionLabel,
+  createOptionIcon,
+  onCreateItemSelect,
+}: {
+  query: string;
+  createOptionLabel?: [string, { ns: string | readonly string[] }];
+  createOptionIcon: string;
+  onCreateItemSelect: (query: string) => void;
+}) => {
+  const { t } = useTranslation(translationKey);
+
+  const label = createOptionLabel
+    ? t(createOptionLabel[0], { ns: createOptionLabel[1].ns, text: query })
+    : t('create-option.label');
+
+  return (
+    <Combobox.Item
+      value='__create__'
+      label={label}
+      icon={createOptionIcon}
+      classNames='flex items-center gap-2'
+      closeOnSelect={false}
+      onSelect={() => {
+        onCreateItemSelect(query);
+      }}
+    />
+  );
+};
+
+ObjectPickerContent.displayName = 'ObjectPicker.Content';
 
 export const ObjectPicker = {
   Root: Combobox.Root,