@dxos/react-ui-form 0.8.4-main.c4373fc → 0.8.4-main.d05539e30a

package/src/components/ObjectProperties/ObjectProperties.stories.tsx

@@ -0,0 +1,362 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Schema from 'effect/Schema';
+import React, { useEffect } from 'react';
+import { expect, userEvent, within } from 'storybook/test';
+
+import { Annotation, Filter, Obj, Ref, Tag, Type } from '@dxos/echo';
+import { FormInputAnnotation, LabelAnnotation } from '@dxos/echo/internal';
+import { useQuery } from '@dxos/react-client/echo';
+import { useClientStory, withClientProvider } from '@dxos/react-client/testing';
+import { Panel } from '@dxos/react-ui';
+import { Loading, withLayout, withTheme } from '@dxos/react-ui/testing';
+import { FactoryAnnotation, type FactoryFn } from '@dxos/schema';
+import { Pipeline } from '@dxos/types';
+
+import { translations } from '#translations';
+
+import { OBJECT_PROPERTIES_DEBUG_SYMBOL } from '../testing';
+import { ObjectProperties } from './ObjectProperties';
+
+//
+// Test-only schemas exercising a non-Tag ref-array. `Article.authors` is the
+// case the generic create flow currently fails on: the picker creates an
+// Author in the DB but never wires the new Ref into the array slot.
+//
+
+const Author = Schema.Struct({
+  name: Schema.String,
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.test.author',
+    version: '0.1.0',
+  }),
+  LabelAnnotation.set(['name']),
+  Annotation.IconAnnotation.set({ icon: 'ph--user--regular', hue: 'blue' }),
+);
+type Author = Schema.Schema.Type<typeof Author>;
+
+const Article = Schema.Struct({
+  title: Schema.String.pipe(Schema.optional),
+  authors: Schema.Array(Ref.Ref(Author)),
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.test.article',
+    version: '0.1.0',
+  }),
+  LabelAnnotation.set(['title']),
+  Annotation.IconAnnotation.set({ icon: 'ph--article--regular', hue: 'green' }),
+);
+type Article = Schema.Schema.Type<typeof Article>;
+
+//
+// `Note` mirrors the `Subscription.Feed` shape: a required `Ref` field
+// (`backing`) is hidden from the form via `FormInputAnnotation.set(false)`,
+// so `Obj.make(Note, values)` from the picker would reject because the form
+// values can't satisfy the schema. A `FactoryAnnotation` constructs the
+// backing object and links it at create time. `cursor` is an optional hidden
+// field included to exercise the same path for non-required hidden fields.
+//
+const NoteBacking = Schema.Struct({}).pipe(Type.object({ typename: 'org.dxos.test.note-backing', version: '0.1.0' }));
+type NoteBacking = Schema.Schema.Type<typeof NoteBacking>;
+
+const Note = Schema.Struct({
+  title: Schema.String,
+  cursor: Schema.String.pipe(FormInputAnnotation.set(false), Schema.optional),
+  backing: Ref.Ref(NoteBacking).pipe(FormInputAnnotation.set(false)),
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.test.note',
+    version: '0.1.0',
+  }),
+  LabelAnnotation.set(['title']),
+  Annotation.IconAnnotation.set({ icon: 'ph--note--regular', hue: 'amber' }),
+  FactoryAnnotation.set(((values: any) =>
+    Obj.make(Note, { ...values, backing: Ref.make(Obj.make(NoteBacking, {})) })) as FactoryFn),
+);
+type Note = Schema.Schema.Type<typeof Note>;
+
+const Notebook = Schema.Struct({
+  name: Schema.String.pipe(Schema.optional),
+  notes: Schema.Array(Ref.Ref(Note)),
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.test.notebook',
+    version: '0.1.0',
+  }),
+  LabelAnnotation.set(['name']),
+  Annotation.IconAnnotation.set({ icon: 'ph--notebook--regular', hue: 'amber' }),
+);
+type Notebook = Schema.Schema.Type<typeof Notebook>;
+
+//
+// Stories.
+//
+
+export type ObjectPropertiesDebug = {
+  /** Live database the story is rendering against. */
+  db: ReturnType<typeof useClientStory>['space'] extends infer S ? (S extends { db: infer D } ? D : never) : never;
+  /** Object whose properties are being edited. */
+  object: Obj.Unknown;
+};
+
+const PipelineStory = () => {
+  const { space } = useClientStory();
+  const [object] = useQuery(space?.db, Filter.type(Pipeline.Pipeline));
+
+  useEffect(() => {
+    if (typeof window !== 'undefined' && space?.db && object) {
+      (window as any)[OBJECT_PROPERTIES_DEBUG_SYMBOL] = { db: space.db, object } satisfies ObjectPropertiesDebug;
+    }
+  }, [space, object]);
+
+  if (!object) {
+    return <Loading />;
+  }
+  return (
+    <Panel.Root>
+      <Panel.Content asChild>
+        <ObjectProperties object={object} />
+      </Panel.Content>
+    </Panel.Root>
+  );
+};
+
+const ArticleStory = () => {
+  const { space } = useClientStory();
+  const [object] = useQuery(space?.db, Filter.type(Article));
+
+  useEffect(() => {
+    if (typeof window !== 'undefined' && space?.db && object) {
+      (window as any)[OBJECT_PROPERTIES_DEBUG_SYMBOL] = { db: space.db, object } satisfies ObjectPropertiesDebug;
+    }
+  }, [space, object]);
+
+  if (!object) {
+    return <Loading />;
+  }
+  return (
+    <Panel.Root>
+      <Panel.Content asChild>
+        <ObjectProperties object={object} />
+      </Panel.Content>
+    </Panel.Root>
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-form/ObjectProperties',
+  component: ObjectProperties as any,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof PipelineStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const pipelineDecorators = [
+  withClientProvider({
+    createIdentity: true,
+    createSpace: true,
+    types: [Pipeline.Pipeline, Tag.Tag],
+    onCreateSpace: async ({ space }) => {
+      space.db.add(Pipeline.make());
+      space.db.add(Tag.make({ label: 'Tag 1' }));
+      space.db.add(Tag.make({ label: 'Tag 2' }));
+      space.db.add(Tag.make({ label: 'Tag 3' }));
+    },
+  }),
+];
+
+const articleDecorators = [
+  withClientProvider({
+    createIdentity: true,
+    createSpace: true,
+    types: [Article, Author, Tag.Tag],
+    onCreateSpace: async ({ space }) => {
+      space.db.add(Obj.make(Article, { title: 'Untitled article', authors: [] }));
+    },
+  }),
+];
+
+const NotebookStory = () => {
+  const { space } = useClientStory();
+  const [object] = useQuery(space?.db, Filter.type(Notebook));
+
+  useEffect(() => {
+    if (typeof window !== 'undefined' && space?.db && object) {
+      (window as any)[OBJECT_PROPERTIES_DEBUG_SYMBOL] = { db: space.db, object } satisfies ObjectPropertiesDebug;
+    }
+  }, [space, object]);
+
+  if (!object) {
+    return <Loading />;
+  }
+  return (
+    <Panel.Root>
+      <Panel.Content asChild>
+        <ObjectProperties object={object} />
+      </Panel.Content>
+    </Panel.Root>
+  );
+};
+
+const notebookDecorators = [
+  withClientProvider({
+    createIdentity: true,
+    createSpace: true,
+    types: [Notebook, Note, NoteBacking, Tag.Tag],
+    onCreateSpace: async ({ space }) => {
+      space.db.add(Obj.make(Notebook, { name: 'Untitled notebook', notes: [] }));
+    },
+  }),
+];
+
+/**
+ * Default Pipeline form — manual exploration. Includes the Tags picker (which
+ * is the only ref-array path that currently works end-to-end, by virtue of
+ * `Tag.Tag` being special-cased in `ObjectProperties.handleCreate`).
+ */
+export const Default: Story = {
+  render: PipelineStory,
+  decorators: pipelineDecorators,
+};
+
+/**
+ * Tag-creation play. Walks the inline create flow against the Tags picker and
+ * leaves the magazine in the post-Save state for assertions to inspect via
+ * `OBJECT_PROPERTIES_DEBUG_SYMBOL`.
+ *
+ * Expected end-state (currently passes):
+ *   - new Tag.Tag exists in the DB with `label === "PinnedTag"`
+ *   - `Obj.getMeta(object).tags` includes its DXN.
+ */
+export const CreateTagPlay: Story = {
+  render: PipelineStory,
+  decorators: pipelineDecorators,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const body = within(document.body);
+
+    // Tags is `Schema.Array(Ref.Ref(Tag.Tag))` and starts empty, so it renders
+    // as an "Add item" button — same shape as any other ref-array. Click it
+    // to materialise an empty slot, then open the slot's picker.
+    const addButton = await canvas.findByRole('button', { name: /add/i }, { timeout: 10_000 });
+    await userEvent.click(addButton);
+    await new Promise((resolve) => setTimeout(resolve, 250));
+
+    const comboboxes = await canvas.findAllByRole('combobox', undefined, { timeout: 10_000 });
+    await expect(comboboxes.length).toBeGreaterThan(0);
+    await userEvent.click(comboboxes[0]);
+
+    const search = await body.findByPlaceholderText(/search/i, undefined, { timeout: 5000 });
+    await userEvent.type(search, 'PinnedTag');
+
+    // The Tag picker localises the create option as "Add tag" (no text suffix
+    // — the translation has no `{{text}}` placeholder), so match on /add/.
+    const createOption = await body.findByRole('option', { name: /add/i }, { timeout: 3000 });
+    await userEvent.click(createOption);
+
+    const form = await body.findByTestId('create-referenced-object-form', undefined, { timeout: 5000 });
+    const labelInput = await within(form).findByLabelText(/^label$/i);
+    await userEvent.clear(labelInput);
+    await userEvent.type(labelInput, 'PinnedTag');
+    await userEvent.click(await within(form).findByTestId('save-button'));
+
+    // Allow async state updates to flush before the test asserts.
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  },
+};
+
+/**
+ * Ref-array creation play. Walks Add → Open → Create → Save against
+ * `Article.authors`. After the fix, the new Author should be persisted AND
+ * wired into `article.authors[0]`. Today it persists to the DB but the array
+ * slot stays empty.
+ */
+export const CreateRefArrayPlay: Story = {
+  render: ArticleStory,
+  decorators: articleDecorators,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const body = within(document.body);
+
+    // ObjectProperties extends Article with the BaseSchema's `tags` array, so
+    // the form has two "Add item" buttons (Tags + Authors). Pick the last one
+    // — Authors comes after Tags in the rendered order.
+    const addButtons = await canvas.findAllByRole('button', { name: /add/i }, { timeout: 10_000 });
+    await userEvent.click(addButtons[addButtons.length - 1]);
+    await new Promise((resolve) => setTimeout(resolve, 250));
+
+    // Open the empty slot's combobox.
+    const comboboxes = await canvas.findAllByRole('combobox', undefined, { timeout: 10_000 });
+    await expect(comboboxes.length).toBeGreaterThan(0);
+    await userEvent.click(comboboxes[0]);
+
+    const search = await body.findByPlaceholderText(/search/i, undefined, { timeout: 5000 });
+    await userEvent.type(search, 'Ada Lovelace');
+
+    // Author has no `createOptionLabel` → option falls back to "Create".
+    const createOption = await body.findByRole('option', { name: /create/i }, { timeout: 3000 });
+    await userEvent.click(createOption);
+
+    const form = await body.findByTestId('create-referenced-object-form', undefined, { timeout: 5000 });
+    const nameInput = await within(form).findByLabelText(/^name$/i);
+    await userEvent.clear(nameInput);
+    await userEvent.type(nameInput, 'Ada Lovelace');
+    await userEvent.click(await within(form).findByTestId('save-button'));
+
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  },
+};
+
+/**
+ * Ref-array creation against a schema with a hidden required field. `Note`
+ * mirrors the shape of `Subscription.Feed`: the form omits `backing` (a
+ * required `Ref` annotated `FormInputAnnotation.set(false)`) but the schema
+ * requires it. Without `omitHiddenFormFields` + `FactoryAnnotation`, the
+ * form's validator would reject Save and the popover would never close.
+ *
+ * Expected end-state after the fix:
+ *   - new Note exists in DB with a synthesised `backing` ref
+ *   - `notebook.notes[0]` references the new Note
+ *   - the create form is gone
+ */
+export const CreateHiddenFieldPlay: Story = {
+  render: NotebookStory,
+  decorators: notebookDecorators,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const body = within(document.body);
+
+    // Two "Add item" buttons (Tags + Notes) — Notes comes second.
+    const addButtons = await canvas.findAllByRole('button', { name: /add/i }, { timeout: 10_000 });
+    await userEvent.click(addButtons[addButtons.length - 1]);
+    await new Promise((resolve) => setTimeout(resolve, 250));
+
+    const comboboxes = await canvas.findAllByRole('combobox', undefined, { timeout: 10_000 });
+    await expect(comboboxes.length).toBeGreaterThan(0);
+    await userEvent.click(comboboxes[0]);
+
+    const search = await body.findByPlaceholderText(/search/i, undefined, { timeout: 5000 });
+    await userEvent.type(search, 'Ideas');
+
+    const createOption = await body.findByRole('option', { name: /create/i }, { timeout: 3000 });
+    await userEvent.click(createOption);
+
+    const form = await body.findByTestId('create-referenced-object-form', undefined, { timeout: 5000 });
+    const titleInput = await within(form).findByLabelText(/^title$/i);
+    await userEvent.clear(titleInput);
+    await userEvent.type(titleInput, 'Ideas');
+    await userEvent.click(await within(form).findByTestId('save-button'));
+
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  },
+};

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`.