@dxos/react-ui-form 0.8.4-main.fd6878d → 0.8.4-staging.60fe92afc8

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

@@ -0,0 +1,55 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React from 'react';
+
+import { Input } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+import { safeParseFloat } from '@dxos/util';
+
+import { type FormFieldComponentProps, FormFieldLabel } from '../FormFieldComponent';
+
+const gridCols = ['grid-cols-1', 'grid-cols-2', 'grid-cols-3', 'grid-cols-4'];
+
+export const TupleField = ({
+  binding,
+  type,
+  readonly,
+  label,
+  jsonPath,
+  getStatus,
+  getValue,
+  onValueChange,
+  onBlur,
+}: FormFieldComponentProps<Record<string, number>> & {
+  binding: string[];
+}) => {
+  const { status, error } = getStatus();
+
+  // TODO(burdon): Generalize number/float/string, etc.
+  const values: Record<string, number> = getValue() ?? {};
+
+  return (
+    <Input.Root validationValence={status}>
+      <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}
+            type='number'
+            disabled={!!readonly}
+            value={values[prop]}
+            onChange={(event) => {
+              onValueChange(type, {
+                ...values,
+                [prop]: safeParseFloat(event.target.value, 0),
+              });
+            }}
+            onBlur={onBlur}
+          />
+        ))}
+      </div>
+    </Input.Root>
+  );
+};

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

@@ -0,0 +1,17 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './ArrayField';
+export * from './BooleanField';
+export * from './DateField';
+export * from './GeoPointField';
+export * from './InlineRefField';
+export * from './MarkdownField';
+export * from './NumberField';
+export * from './RefField';
+export * from './SelectField';
+export * from './SelectOptionField';
+export * from './TextField';
+export * from './TextAreaField';
+export * from './TupleField';

package/src/components/Form/index.ts

@@ -2,8 +2,10 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './custom';
-export * from './Defaults';
+export * from './fields';
+
 export * from './Form';
-export * from './FormContext';
-export * from './Input';
+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.stories.tsx

@@ -0,0 +1,62 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { Filter, Obj, Ref, Tag } from '@dxos/echo';
+import { useQuery } from '@dxos/react-client/echo';
+import { useClientStory, withClientProvider } from '@dxos/react-client/testing';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { Person } from '@dxos/types';
+
+import { translations } from '#translations';
+
+import { ObjectForm } from './ObjectForm';
+
+const DefaultStory = () => {
+  const { space } = useClientStory();
+  const [person] = useQuery(space?.db, Filter.type(Person.Person));
+  if (!person) {
+    return <></>;
+  }
+
+  return <ObjectForm object={person} type={Person.Person} />;
+};
+
+const meta = {
+  title: 'ui/react-ui-form/ObjectForm',
+  render: DefaultStory,
+  decorators: [
+    withTheme(),
+    withLayout({ layout: 'column', classNames: 'p-2', scroll: true }),
+    withClientProvider({
+      types: [Person.Person, Tag.Tag],
+      createIdentity: true,
+      createSpace: true,
+      onCreateSpace: async ({ space }) => {
+        const tag = space.db.add(Tag.make({ label: 'Friend', hue: 'emerald' }));
+        const person = space.db.add(
+          Obj.make(Person.Person, {
+            fullName: 'Alice Carroll',
+            jobTitle: 'Engineer',
+            emails: [{ value: 'alice@example.com' }],
+          }),
+        );
+        Obj.update(person, (person) => {
+          Obj.getMeta(person).tags = [Ref.make(tag)];
+        });
+      },
+    }),
+  ],
+  parameters: {
+    translations,
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/src/components/ObjectForm/ObjectForm.tsx

@@ -0,0 +1,111 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useCallback, useMemo } from 'react';
+
+import { Obj, Ref, Tag, Type } from '@dxos/echo';
+import { SchemaEx } from '@dxos/effect';
+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<SchemaEx.JsonPath, boolean> },
+    ) => {
+      if (!isValid) {
+        return;
+      }
+
+      const changedPaths = Object.keys(changed).filter(
+        (path) => changed[path as SchemaEx.JsonPath],
+      ) as SchemaEx.JsonPath[];
+
+      // Handle meta-tags separately using Obj.update.
+      const hasTagsChange = changedPaths.some((path) => SchemaEx.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) => SchemaEx.splitJsonPath(path)[0] !== META_TAGS_KEY);
+      if (nonTagPaths.length > 0) {
+        Obj.update(object, () => {
+          for (const path of nonTagPaths) {
+            const parts = SchemaEx.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/{ControlSection → ObjectForm}/index.ts

@@ -2,4 +2,4 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './ControlSection';
+export * from './ObjectForm';

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

@@ -0,0 +1,212 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Schema from 'effect/Schema';
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
+import { expect, fn, userEvent, within } from 'storybook/test';
+
+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 { ObjectPicker } from './ObjectPicker';
+
+random.seed(1);
+
+const createPerson = () =>
+  Obj.make(Person.Person, {
+    fullName: random.person.fullName(),
+  });
+
+const omitId = Schema.omit<any, any, ['id']>('id');
+const personSchema = omitId(Type.getSchema(Person.Person));
+
+// Mock functions for testing
+const mockHandleSelect = fn();
+const mockHandleCreate = fn();
+
+const DefaultStory = () => {
+  const { space } = useClientStory();
+  const [isOpen, setIsOpen] = useState(false);
+
+  // Create sample Person objects
+  useEffect(() => {
+    if (space) {
+      // Create some sample Person objects for testing
+      Array.from({ length: 10 }).forEach(() => {
+        space.db.add(createPerson());
+      });
+    }
+  }, [space]);
+
+  // Get all objects in the space (similar to BoardArticle)
+  const allObjects = useQuery(space?.db, Filter.everything());
+
+  // Map objects to options format expected by ObjectPicker
+  const options = useMemo(
+    () =>
+      allObjects.map((obj) => ({
+        id: obj.id,
+        label: obj.fullName || obj.name || obj.title || obj.id,
+        hue: 'neutral' as const,
+      })),
+    [allObjects],
+  );
+
+  const handleCreateCallback = useCallback(
+    (values: any) => {
+      console.log('[on create]', values);
+      if (!space) {
+        return;
+      }
+      const newPerson = space.db.add(Obj.make(Person.Person, values));
+      mockHandleCreate(values);
+      return newPerson;
+    },
+    [space],
+  );
+
+  return (
+    <div className='w-96'>
+      <ObjectPicker.Root open={isOpen} onOpenChange={setIsOpen}>
+        <ObjectPicker.Trigger asChild>
+          <Button variant='primary' data-testid='trigger' classNames='w-full'>
+            Select Person
+          </Button>
+        </ObjectPicker.Trigger>
+        <ObjectPicker.Content
+          classNames='dx-card-popover-width'
+          options={options}
+          createSchema={personSchema}
+          createOptionLabel={['create-new-person.label', { ns: osTranslations }]}
+          createOptionIcon='ph--user-plus--regular'
+          createInitialValuePath='fullName'
+          onCreate={handleCreateCallback}
+          onSelect={mockHandleSelect}
+        />
+      </ObjectPicker.Root>
+    </div>
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-form/ObjectPicker',
+  render: DefaultStory,
+  decorators: [
+    withTheme(),
+    withClientProvider({
+      types: [Person.Person],
+      createIdentity: true,
+      createSpace: true,
+    }),
+  ],
+  parameters: {
+    layout: 'centered',
+    controls: { disable: true },
+    translations,
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const WithTest: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const body = within(document.body);
+
+    // Find and click the trigger button.
+    const triggerButton = await canvas.findByTestId('trigger', undefined, { timeout: 5000 });
+    await expect(triggerButton).toBeVisible();
+    await userEvent.click(triggerButton);
+
+    // Check that the listbox renders when the trigger is clicked.
+    const listbox = await body.findByRole('listbox', undefined, { timeout: 5000 });
+    await expect(listbox).toBeVisible();
+
+    // Find the search input.
+    const searchInput = await body.findByPlaceholderText('Search…');
+    await expect(searchInput).toBeVisible();
+
+    // Test searching filters the results - get initial options count.
+    const initialOptions = await body.findAllByRole('option');
+    const initialCount = initialOptions.length;
+    await expect(initialCount).toBeGreaterThan(0);
+
+    // Type a search term that should filter results.
+    await userEvent.type(searchInput, 'John');
+
+    // Wait a moment for filtering.
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    // Check that results are filtered (should be fewer options)
+    const _filteredOptions = await body.findAllByRole('option');
+    // Note: We expect either fewer results or the same if no John exists
+
+    // Clear search and test selecting a result
+    await userEvent.clear(searchInput);
+
+    // Get the first option and click it
+    const updatedOptions = await body.findAllByRole('option');
+    const firstOption = updatedOptions[0];
+    await expect(firstOption).toBeVisible();
+
+    const _firstOptionText = firstOption.textContent;
+    await userEvent.click(firstOption);
+
+    // Check that clicking a result fires onSelect with that id
+    // The onSelect should have been called with the selected option's id
+    await expect(mockHandleSelect).toHaveBeenCalled();
+
+    // Re-open the picker to test create functionality.
+    await userEvent.click(triggerButton);
+
+    // Wait for listbox to appear again.
+    const newListbox = await body.findByRole('listbox', undefined, { timeout: 5000 });
+    await expect(newListbox).toBeVisible();
+
+    const newSearchInput = await body.findByPlaceholderText('Search…');
+
+    // Test searching an unrelated term provides the __create__ option.
+    const unrelatedTerm = 'ZxyUnrelatedName123';
+    await userEvent.type(newSearchInput, unrelatedTerm);
+
+    // Wait for the create option to appear.
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    // Look for the create option.
+    const createOption = await body.findByRole('option', undefined, { timeout: 3000 });
+    await expect(createOption).toBeVisible();
+
+    // Click the create option - this should change state to the form field.
+    await userEvent.click(createOption);
+
+    // Check that clicking that option changes state to the form field.
+    const form = await body.findByTestId('create-referenced-object-form', undefined, { timeout: 5000 });
+    await expect(form).toBeVisible();
+
+    // Find and click the save button.
+    const saveButton = await within(form).findByTestId('save-button');
+    await expect(saveButton).toBeVisible();
+    await userEvent.click(saveButton);
+
+    // Check that clicking the save button calls onCreate with expected values.
+    await expect(mockHandleCreate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        fullName: unrelatedTerm,
+      }),
+    );
+  },
+};