@dxos/react-ui-form 0.8.4-main.8360d9e660 → 0.8.4-main.8baae0fced

package/src/components/ObjectProperties/ObjectProperties.test.tsx

@@ -0,0 +1,101 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { composeStories } from '@storybook/react';
+import { cleanup } from '@testing-library/react';
+import { afterEach, describe, expect, test } from 'vitest';
+
+import { Filter, Obj, Tag } from '@dxos/echo';
+
+import { OBJECT_PROPERTIES_DEBUG_SYMBOL } from '../testing';
+import * as stories from './ObjectProperties.stories';
+import { type ObjectPropertiesDebug } from './ObjectProperties.stories';
+
+const { CreateTagPlay, CreateRefArrayPlay, CreateHiddenFieldPlay } = composeStories(stories);
+
+const getDebug = (): ObjectPropertiesDebug => {
+  const debug = (window as any)[OBJECT_PROPERTIES_DEBUG_SYMBOL] as ObjectPropertiesDebug | undefined;
+  expect(debug).toBeDefined();
+  return debug!;
+};
+
+describe('ObjectProperties — inline create flow', () => {
+  afterEach(() => {
+    cleanup();
+    delete (window as any)[OBJECT_PROPERTIES_DEBUG_SYMBOL];
+  });
+
+  test('Tag.Tag: Create + Save persists tag and assigns it to the object', { timeout: 30_000 }, async () => {
+    await CreateTagPlay.run();
+    const { db, object } = getDebug();
+
+    // The new Tag should exist in the DB.
+    const tags = (await db.query(Filter.type(Tag.Tag)).run()) as Tag.Tag[];
+    const created = tags.find((tag) => tag.label === 'PinnedTag');
+    expect(created, 'new Tag.Tag with label "PinnedTag" should be in the database').toBeDefined();
+
+    // And `object.meta.tags` should contain a DXN that resolves to that tag.
+    // Compare by the DXN's object-id tail since refs may be stored as relative
+    // (`dxn:echo:@:<id>`) or absolute (`dxn:echo:<spaceId>:<id>`) forms.
+    const meta = Obj.getMeta(object);
+    const createdId = (created as any).id as string;
+    const matched = (meta.tags ?? []).some((dxn) => dxn.endsWith(`:${createdId}`));
+    expect(matched, "meta.tags should contain a DXN ending with the new tag's id").toBe(true);
+  });
+
+  test('non-Tag ref-array: Create + Save assigns the new ref to the array slot', { timeout: 30_000 }, async () => {
+    await CreateRefArrayPlay.run();
+    const { db, object } = getDebug();
+
+    // The new Author should exist in the DB.
+    const authors = (await db.query(Filter.typename('org.dxos.test.author' as any)).run()) as any[];
+    const created = authors.find((author: any) => author.name === 'Ada Lovelace');
+    expect(created, 'new Author with name "Ada Lovelace" should be in the database').toBeDefined();
+
+    // And the article's authors array should contain a Ref to it. This is the
+    // assertion that fails before the fix — handleCreate persists the object
+    // but never wires the new ref into the array slot.
+    const article = object as any;
+    expect(article.authors ?? [], 'article.authors should contain a single Ref').toHaveLength(1);
+    // Compare by DXN tail to be agnostic to relative vs absolute Ref form.
+    const createdId = (created as any).id as string;
+    expect(
+      article.authors[0]?.dxn?.toString().endsWith(`:${createdId}`),
+      'article.authors[0] should reference the newly-created Author',
+    ).toBe(true);
+  });
+
+  test(
+    'hidden required field via FactoryAnnotation: Create + Save closes form and assigns ref',
+    { timeout: 30_000 },
+    async () => {
+      await CreateHiddenFieldPlay.run();
+      const { db, object } = getDebug();
+
+      // The new Note should exist in the DB with the synthesised backing ref.
+      const notes = (await db.query(Filter.typename('org.dxos.test.note' as any)).run()) as any[];
+      const created = notes.find((note: any) => note.title === 'Ideas');
+      expect(created, 'new Note with title "Ideas" should be in the database').toBeDefined();
+      expect(
+        (created as any).backing,
+        'FactoryAnnotation should have populated the hidden `backing` ref',
+      ).toBeDefined();
+
+      // The notebook's notes array should reference the new Note.
+      const notebook = object as any;
+      expect(notebook.notes ?? [], 'notebook.notes should contain a single Ref').toHaveLength(1);
+      const createdId = (created as any).id as string;
+      expect(
+        notebook.notes[0]?.dxn?.toString().endsWith(`:${createdId}`),
+        'notebook.notes[0] should reference the newly-created Note',
+      ).toBe(true);
+
+      // The picker's create form should be gone.
+      expect(
+        document.querySelector('[data-testid="create-referenced-object-form"]'),
+        'create form should be dismissed after a successful save',
+      ).toBeNull();
+    },
+  );
+});

package/src/components/ObjectProperties/ObjectProperties.tsx

@@ -0,0 +1,148 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Function from 'effect/Function';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import React, { type PropsWithChildren, useCallback, useMemo } from 'react';
+
+import { DXN, Obj, Ref, Tag, Type } from '@dxos/echo';
+import { useSchema } from '@dxos/echo-react';
+import { type JsonPath, splitJsonPath } from '@dxos/echo/internal';
+import { invariant } from '@dxos/invariant';
+import { HuePicker } from '@dxos/react-ui-pickers';
+import { FactoryAnnotation } from '@dxos/schema';
+import { composable, composableProps } from '@dxos/ui-theme';
+import { isNonNullable } from '@dxos/util';
+
+import { translationKey } from '#translations';
+
+import { Form, type FormFieldMap, omitId } from '../Form';
+
+export type ObjectPropertiesProps = PropsWithChildren<{ object: Obj.Unknown }>;
+
+// TODO(wittjosiah): Reconcile w/ ObjectForm.
+export const ObjectProperties = composable<HTMLDivElement, ObjectPropertiesProps>(
+  ({ children, object, ...props }, forwardedRef) => {
+    const db = Obj.getDatabase(object);
+    const meta = Obj.getMeta(object);
+    const tags = (meta.tags ?? []).map((tag) => db?.makeRef(DXN.parse(tag))).filter(isNonNullable);
+    const values = useMemo(() => ({ tags, ...object }), [object, tags]);
+
+    // Obj.getSchema fails for database-registered (dynamic) schemas due to DXN mismatch;
+    // useSchema queries by typename which correctly resolves both static and dynamic schemas.
+    const typename = Obj.getTypename(object) ?? undefined;
+    const schemaFromRegistry = useSchema(db, typename);
+    const rawSchema = Obj.getSchema(object) ?? schemaFromRegistry;
+
+    const formSchema = useMemo(() => {
+      return Function.pipe(
+        rawSchema,
+        Option.fromNullable,
+        Option.map((schema) => omitId(BaseSchema.pipe(Schema.extend(schema)))),
+        Option.getOrUndefined,
+      );
+    }, [rawSchema]);
+
+    // Persist a newly-created object referenced by one of the form's ref
+    // fields and return it. The calling RefField wires the new Ref into its
+    // own slot's form value; for the BaseSchema `tags` array, the resulting
+    // form change is then synced back to `Obj.getMeta(object).tags` by
+    // `handleChange` below — so Tag.Tag follows the same generic path as any
+    // other ref-array field, no type-specific branching required here.
+    //
+    // Schemas whose required structure can't be produced by `Obj.make(schema,
+    // values)` alone (e.g. types with a required ref to a backing object) can
+    // declare a `FactoryAnnotation` to take over construction.
+    const handleCreate = useCallback(
+      (schema: Type.AnyEntity, values: any): Obj.Unknown => {
+        invariant(db);
+        invariant(Type.isObjectSchema(schema));
+        const factory = Option.getOrUndefined(FactoryAnnotation.get(schema));
+        const newObject = factory ? (factory(values) as Obj.Unknown) : Obj.make(schema, values);
+        return db.add(newObject) as Obj.Unknown;
+      },
+      [db],
+    );
+
+    // TODO(wittjosiah): Use FormRootProps type.
+    const handleChange = useCallback(
+      (
+        { tags, ...values }: Schema.Schema.Type<typeof formSchema>,
+        { 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 tags separately using Obj.update.
+        const hasTagsChange = changedPaths.some((path) => splitJsonPath(path)[0] === 'tags');
+        if (hasTagsChange) {
+          Obj.update(object, (object) => {
+            Obj.getMeta(object).tags = tags?.map((tag: Ref.Ref<Tag.Tag>) => tag.dxn.toString()) ?? [];
+          });
+        }
+
+        // Handle other property changes.
+        const nonTagPaths = changedPaths.filter((path) => splitJsonPath(path)[0] !== 'tags');
+        if (nonTagPaths.length > 0) {
+          Obj.update(object, () => {
+            for (const path of nonTagPaths) {
+              const parts = splitJsonPath(path);
+              const value = Obj.getValue(values as any, parts);
+              Obj.setValue(object, parts, value);
+            }
+          });
+        }
+      },
+      [object],
+    );
+
+    if (!formSchema) {
+      return null;
+    }
+
+    return (
+      <Form.Root
+        schema={formSchema}
+        defaultValues={values as any}
+        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 {...composableProps(props)} ref={forwardedRef}>
+          <Form.Content>
+            <Form.FieldSet />
+            {children}
+          </Form.Content>
+        </Form.Viewport>
+      </Form.Root>
+    );
+  },
+);
+
+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} />
+      </>
+    );
+  },
+};
+
+// TODO(wittjosiah): Would be nice to control order when extending so this isn't always first/last.
+const BaseSchema = Schema.Struct({
+  tags: Schema.Array(Ref.Ref(Tag.Tag)).pipe(Schema.optional),
+});

package/src/components/ObjectProperties/index.ts

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

package/src/components/Settings/AUDIT.md

@@ -0,0 +1,51 @@
+# Plugin Settings Audit
+
+Tracks which plugin settings panels use schema-driven `Settings.FieldSet` and which still hand-roll their controls.
+
+The target shape for a plugin settings panel is:
+
+```tsx
+<SettingsForm.Viewport>
+  <SettingsForm.Section title={t('settings.title', { ns: meta.id })}>
+    <SettingsForm.FieldSet
+      readonly={!onSettingsChange}
+      schema={Settings.Settings}
+      values={settings}
+      onValuesChanged={(values) => onSettingsChange?.(() => values)}
+    />
+  </SettingsForm.Section>
+</SettingsForm.Viewport>
+```
+
+Field labels and descriptions come from `.annotations({ title, description })` on each schema field. Use `fieldMap` for runtime-driven option lists (model pickers, etc.). Use the `visible` callback to gate fields on environment or sibling values.
+
+## FieldSet adopters
+
+| Plugin                 | Notes                                                                                                    |
+| ---------------------- | -------------------------------------------------------------------------------------------------------- |
+| `plugin-assistant`     | Nested `modelDefaults` struct; `fieldMap` provides per-provider model selectors via `createSelectField`. |
+| `plugin-crx`           | Two booleans.                                                                                            |
+| `plugin-deck`          | Five booleans; `enableNativeRedirect` hidden via `visible` when `isSocket`.                              |
+| `plugin-inbox`         | Single boolean.                                                                                          |
+| `plugin-markdown`      | Original reference adopter. `snippets` text field gated via `visible`/`fieldMap`.                        |
+| `plugin-meeting`       | Single boolean.                                                                                          |
+| `plugin-observability` | Boolean; info `Message.Root` banner kept above `FieldSet`.                                               |
+| `plugin-presenter`     | Single boolean.                                                                                          |
+| `plugin-sample`        | Single boolean.                                                                                          |
+| `plugin-script`        | Mixed: auth `Button` retained as a manual `SettingsForm.Item`; `editorInputMode` rendered by `FieldSet`. |
+| `plugin-sketch`        | Boolean + `gridType` literal union (rendered as a Select — was previously a Switch).                     |
+
+## Skipped
+
+| Plugin             | Reason                                                                                                                                                               |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `plugin-debug`     | Action buttons (download diagnostics, download logs, repair), `Toast`, and a storage-adapter selector wired to `client.config` rather than the plugin settings atom. |
+| `plugin-space`     | Renders a list of spaces with per-space "open settings" buttons — not bound to any schema field.                                                                     |
+| `plugin-spacetime` | Section is currently empty; nothing to render.                                                                                                                       |
+| `plugin-thread`    | Settings schema is `Schema.Struct({})` — nothing to render.                                                                                                          |
+
+## When to extend `SettingsFieldSet` vs. add a custom field
+
+- **Extend `SettingsFieldSet`** when the rendering rule applies generally to a schema construct (e.g. nested structs recursing into sibling fields, literal unions becoming Selects). Keep auto-detection in `detectFieldType`.
+- **Use `fieldMap`** when the schema can't fully describe the rendering — runtime-driven option lists, custom inputs, or override of the auto-rendered control. Use the typed form `SettingsFieldMap<T>` (or `satisfies SettingsFieldMap<Settings>`) so the entries are checked against the values shape.
+- **Drop back to manual `SettingsForm.Item`** when the panel needs UI that isn't bound to a settings field at all (action buttons, info banners, lists of external entities). These coexist as siblings of `FieldSet` inside the same `Section`.

package/src/components/Settings/Settings.stories.tsx

@@ -3,39 +3,40 @@
 //
 
 import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Schema from 'effect/Schema';
 import React from 'react';
 
-import { faker } from '@dxos/random';
+import { random } from '@dxos/random';
 import { Button, Input } from '@dxos/react-ui';
 import { withLayout, withTheme } from '@dxos/react-ui/testing';
 
-import { translations } from '../../translations';
+import { translations } from '#translations';
 
 import { Settings } from './Settings';
 
-faker.seed(132);
+random.seed(132);
 
 const DefaultStory = () => {
   return (
-    <Settings.Root>
-      <Settings.Section title='Settings' description={faker.lorem.paragraphs(1)}>
-        <Settings.Group>
-          <Settings.ItemInput title={faker.lorem.sentence(2)} description={faker.lorem.paragraphs(1)}>
-            <Input.Root>
-              <Input.TextInput placeholder='Input' />
-            </Input.Root>
-          </Settings.ItemInput>
-          <Settings.ItemInput title={faker.lorem.sentence(2)} description={faker.lorem.paragraphs(2)}>
-            <Input.Root>
-              <Input.Switch />
-            </Input.Root>
-          </Settings.ItemInput>
-          <Settings.ItemInput title={faker.lorem.sentence(3)} description={faker.lorem.paragraphs(2)}>
-            <Button>Test</Button>
-          </Settings.ItemInput>
-        </Settings.Group>
+    <Settings.Viewport>
+      <Settings.Section title='Settings' description={random.lorem.paragraphs(1)}>
+        <Settings.Item title={random.lorem.sentence(2)} description={random.lorem.paragraphs(1)}>
+          <Input.TextInput placeholder='Input' />
+        </Settings.Item>
+        <Settings.Item title={random.lorem.sentence(2)} description={random.lorem.paragraphs(2)}>
+          <Input.Switch />
+        </Settings.Item>
+        <Settings.Item title={random.lorem.sentence(3)} description={random.lorem.paragraphs(2)}>
+          <Button>Test</Button>
+        </Settings.Item>
       </Settings.Section>
-    </Settings.Root>
+      <Settings.Section title='Panel Example'>
+        <Settings.Panel>
+          <h3 className='text-lg mb-2'>Members</h3>
+          <p className='text-description'>Content inside a panel.</p>
+        </Settings.Panel>
+      </Settings.Section>
+    </Settings.Viewport>
   );
 };
 
@@ -54,3 +55,50 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {};
+
+const TestViewModes = ['preview', 'readonly', 'source'] as const;
+const TestViewMode = Schema.Union(...TestViewModes.map((mode) => Schema.Literal(mode)));
+
+const TestSettings = Schema.mutable(
+  Schema.Struct({
+    viewMode: TestViewMode.annotations({ title: 'View mode', description: 'Default document view mode.' }),
+    toolbar: Schema.optional(
+      Schema.Boolean.annotations({ title: 'Show toolbar', description: 'Display formatting toolbar.' }),
+    ),
+    fontSize: Schema.optional(
+      Schema.Number.annotations({ title: 'Font size', description: 'Editor font size in pixels.' }),
+    ),
+    placeholder: Schema.optional(
+      Schema.String.annotations({ title: 'Placeholder', description: 'Default placeholder text.' }),
+    ),
+    debug: Schema.optional(Schema.Boolean.annotations({ title: 'Debug mode', description: 'Enable debug features.' })),
+  }),
+);
+
+type TestSettings = Schema.Schema.Type<typeof TestSettings>;
+
+const FieldSetStory = () => {
+  const [values, setValues] = React.useState<TestSettings>({
+    viewMode: 'preview',
+    toolbar: true,
+    fontSize: 14,
+    debug: false,
+  });
+
+  return (
+    <Settings.Viewport>
+      <Settings.Section title='Plugin Settings (Auto-generated)'>
+        <Settings.FieldSet
+          schema={TestSettings}
+          values={values}
+          onValuesChanged={setValues}
+          visible={(path, values) => path !== 'placeholder' || !!values.debug}
+        />
+      </Settings.Section>
+    </Settings.Viewport>
+  );
+};
+
+export const FieldSet: Story = {
+  render: FieldSetStory,
+};