@dxos/react-ui-form 0.9.1-main.c7dcc2e112 → 0.9.1-staging.ee54ba693a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/react-ui-form",
-  "version": "0.9.1-main.c7dcc2e112",
+  "version": "0.9.1-staging.ee54ba693a",
   "description": "Data components.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -44,52 +44,53 @@
     "@radix-ui/react-use-controllable-state": "1.1.0",
     "date-fns": "^3.6.0",
     "tabster": "^8.5.5",
-    "@dxos/echo": "0.9.1-main.c7dcc2e112",
-    "@dxos/echo-protocol": "0.9.1-main.c7dcc2e112",
-    "@dxos/echo-react": "0.9.1-main.c7dcc2e112",
-    "@dxos/async": "0.9.1-main.c7dcc2e112",
-    "@dxos/effect": "0.9.1-main.c7dcc2e112",
-    "@dxos/invariant": "0.9.1-main.c7dcc2e112",
-    "@dxos/keys": "0.9.1-main.c7dcc2e112",
-    "@dxos/lit-ui": "0.9.1-main.c7dcc2e112",
-    "@dxos/react-ui-components": "0.9.1-main.c7dcc2e112",
-    "@dxos/log": "0.9.1-main.c7dcc2e112",
-    "@dxos/react-client": "0.9.1-main.c7dcc2e112",
-    "@dxos/react-ui-editor": "0.9.1-main.c7dcc2e112",
-    "@dxos/react-ui-list": "0.9.1-main.c7dcc2e112",
-    "@dxos/react-ui-pickers": "0.9.1-main.c7dcc2e112",
-    "@dxos/react-ui-search": "0.9.1-main.c7dcc2e112",
-    "@dxos/schema": "0.9.1-main.c7dcc2e112",
-    "@dxos/types": "0.9.1-main.c7dcc2e112",
-    "@dxos/ui": "0.9.1-main.c7dcc2e112",
-    "@dxos/echo-client": "0.9.1-main.c7dcc2e112",
-    "@dxos/ui-editor": "0.9.1-main.c7dcc2e112",
-    "@dxos/util": "0.9.1-main.c7dcc2e112"
+    "@dxos/async": "0.9.1-staging.ee54ba693a",
+    "@dxos/echo-doc": "0.9.1-staging.ee54ba693a",
+    "@dxos/echo": "0.9.1-staging.ee54ba693a",
+    "@dxos/echo-protocol": "0.9.1-staging.ee54ba693a",
+    "@dxos/echo-react": "0.9.1-staging.ee54ba693a",
+    "@dxos/effect": "0.9.1-staging.ee54ba693a",
+    "@dxos/invariant": "0.9.1-staging.ee54ba693a",
+    "@dxos/keys": "0.9.1-staging.ee54ba693a",
+    "@dxos/lit-ui": "0.9.1-staging.ee54ba693a",
+    "@dxos/log": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-client": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui-components": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui-editor": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui-list": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui-markdown": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui-pickers": "0.9.1-staging.ee54ba693a",
+    "@dxos/schema": "0.9.1-staging.ee54ba693a",
+    "@dxos/types": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui-search": "0.9.1-staging.ee54ba693a",
+    "@dxos/ui": "0.9.1-staging.ee54ba693a",
+    "@dxos/util": "0.9.1-staging.ee54ba693a",
+    "@dxos/ui-editor": "0.9.1-staging.ee54ba693a"
   },
   "devDependencies": {
-    "@types/react": "~19.2.7",
+    "@types/react": "~19.2.17",
     "@types/react-dom": "~19.2.3",
-    "effect": "3.21.3",
+    "effect": "3.21.4",
     "fast-check": "^3.19.0",
-    "react": "~19.2.3",
-    "react-dom": "~19.2.3",
+    "react": "~19.2.7",
+    "react-dom": "~19.2.7",
     "vite": "^8.0.16",
-    "@dxos/protocols": "0.9.1-main.c7dcc2e112",
-    "@dxos/random": "0.9.1-main.c7dcc2e112",
-    "@dxos/react-client": "0.9.1-main.c7dcc2e112",
-    "@dxos/react-ui": "0.9.1-main.c7dcc2e112",
-    "@dxos/react-ui-syntax-highlighter": "0.9.1-main.c7dcc2e112",
-    "@dxos/storybook-utils": "0.9.1-main.c7dcc2e112",
-    "@dxos/ui-theme": "0.9.1-main.c7dcc2e112",
-    "@dxos/ui-types": "0.9.1-main.c7dcc2e112",
-    "@dxos/effect-proto": "0.9.1-main.c7dcc2e112"
+    "@dxos/protocols": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-client": "0.9.1-staging.ee54ba693a",
+    "@dxos/effect-proto": "0.9.1-staging.ee54ba693a",
+    "@dxos/random": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui-syntax-highlighter": "0.9.1-staging.ee54ba693a",
+    "@dxos/ui-theme": "0.9.1-staging.ee54ba693a",
+    "@dxos/ui-types": "0.9.1-staging.ee54ba693a",
+    "@dxos/storybook-utils": "0.9.1-staging.ee54ba693a"
   },
   "peerDependencies": {
-    "effect": "3.21.3",
-    "react": "~19.2.3",
-    "react-dom": "~19.2.3",
-    "@dxos/react-ui": "0.9.1-main.c7dcc2e112",
-    "@dxos/ui-theme": "0.9.1-main.c7dcc2e112"
+    "effect": "3.21.4",
+    "react": "~19.2.7",
+    "react-dom": "~19.2.7",
+    "@dxos/ui-theme": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui": "0.9.1-staging.ee54ba693a"
   },
   "publishConfig": {
     "access": "public"

package/src/annotations.ts

@@ -0,0 +1,63 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Effect from 'effect/Effect';
+
+import { createAnnotationHelper } from '@dxos/echo/internal';
+
+/** One selectable option produced by an {@link OptionsLookup}. */
+export type OptionsLookupEntry = { value: string; label?: string; secondaryLabel?: string; icon?: string };
+
+/**
+ * Loads a select field's options dynamically from a declared subset of the form values, so a select can
+ * depend on a sibling field (e.g. publications for a typed handle). `deps` are the field names the loader
+ * reads; the form re-runs it only when one of those values changes. The returned Effect must be
+ * self-contained (`R = never`): it provides its own dependencies (network layer, etc.) in the closure.
+ * Construct via {@link optionsLookup} for typed `deps`/`values`. Pass `{ combobox: true }` to render
+ * an editable combobox (type-to-search) instead of a constrained select.
+ */
+export type OptionsLookup = {
+  readonly deps: readonly string[];
+  readonly load: (values: any) => Effect.Effect<readonly OptionsLookupEntry[], unknown>;
+  readonly combobox?: boolean;
+};
+
+export const OptionsLookupAnnotationId = Symbol.for('@dxos/schema/annotation/OptionsLookup');
+export const OptionsLookupAnnotation = createAnnotationHelper<OptionsLookup>(OptionsLookupAnnotationId);
+
+/**
+ * Builds an {@link OptionsLookup} typed against a schema's value type `Values`: `deps` is checked
+ * against its field names, and `load` receives only those fields, narrowed. Pass `{ combobox: true }` to
+ * render an editable combobox.
+ */
+export const optionsLookup =
+  <Values>() =>
+  <const Deps extends readonly (keyof Values & string)[]>(
+    deps: Deps,
+    load: (values: Pick<Values, Deps[number]>) => Effect.Effect<readonly OptionsLookupEntry[], unknown>,
+    options?: { combobox?: boolean },
+  ): OptionsLookup => ({ deps, load, combobox: options?.combobox });
+
+/**
+ * Derives a (text) field's value from a declared subset of the form values, so a field can be pre-filled
+ * from a sibling (e.g. a feed name fetched from a typed URL). `deps` are the field names the derivation
+ * reads; the form re-runs it only when one of those changes. The returned Effect must be self-contained
+ * (`R = never`); `undefined` means "no value to fill". The form pre-fills only while the user has not
+ * typed their own value, so a manual edit is never clobbered. Construct via {@link autofill}.
+ */
+export type Autofill = {
+  readonly deps: readonly string[];
+  readonly derive: (values: any) => Effect.Effect<string | undefined, unknown>;
+};
+
+export const AutofillAnnotationId = Symbol.for('@dxos/schema/annotation/Autofill');
+export const AutofillAnnotation = createAnnotationHelper<Autofill>(AutofillAnnotationId);
+
+/** Builds an {@link Autofill} typed against a schema's value type `Values` (see {@link optionsLookup}). */
+export const autofill =
+  <Values>() =>
+  <const Deps extends readonly (keyof Values & string)[]>(
+    deps: Deps,
+    derive: (values: Pick<Values, Deps[number]>) => Effect.Effect<string | undefined, unknown>,
+  ): Autofill => ({ deps, derive });

package/src/components/FieldEditor/FieldEditor.tsx

@@ -58,7 +58,10 @@ export const FieldEditor = ({ readonly, projection, field, registry, view, onSav
 
   const [referenceSchema, setReferenceSchema] = useState<Type.Type>();
   useEffect(() => {
-    setReferenceSchema(schemas.find((schema) => Type.getTypename(schema) === props?.referenceSchema));
+    // A React state setter invokes a function argument as an updater. A class-based `Type.Type` is
+    // itself a function, so it must be stored via an updater lambda — passing it directly makes React
+    // call it as `Organization(prev)`, throwing "Class constructor … cannot be invoked without 'new'".
+    setReferenceSchema(() => schemas.find((schema) => Type.getTypename(schema) === props?.referenceSchema));
   }, [schemas, props?.referenceSchema]);
 
   // TODO(burdon): Need to wrap otherwise throws error:
@@ -191,7 +194,7 @@ export const FieldEditor = ({ readonly, projection, field, registry, view, onSav
       readonly={readonly}
       schema={fieldSchema}
       values={props}
-      exclude={propIsNotType}
+      filter={propIsNotType}
       sort={['property', 'format']}
       onValuesChanged={handleValuesChanged}
       onValidate={handleValidate}

package/src/components/Form/DESIGN.md

@@ -0,0 +1,24 @@
+# `@dxos/react-ui-form` — Design
+
+Schema-driven forms. Give `Form.Root` an Effect `schema` + `values`; the field set renders typed
+controls automatically. Bespoke controls drop in via `Form.Row` or a per-path `fieldMap`.
+
+## Component hierarchy
+
+```text
+Form.Root                               context: schema, values, validation, onValuesChanged
+└─ Form.Viewport                        scroll chrome
+   └─ Form.Content
+      ├─ Form.Section                   titled group of fields
+      │  ├─ Form.FieldSet               schema-driven field set
+      │  │  └─ FormFieldSetContainer    group wrapper: FormFieldHeader (label + collapse) over the body
+      │  │     └─ FormField             one per schema property; dispatches by type:
+      │  │        ├─ ArrayField         array → FormFieldHeader + item rows
+      │  │        ├─ Form.FieldSet      nested object → recurses (its own FormFieldSetContainer)
+      │  │        └─ Form.Row           scalar → label + description + the control (<field>)
+      │  └─ Form.Row                    OR a hand-written row (label + description + any control)
+      ├─ Form.Layout                    alternative to FieldSet: lays fields out per a parsed layout spec
+      └─ Form.Actions
+         └─ Form.Submit
+            Form.Error
+```

package/src/components/Form/Form.stories.tsx

@@ -3,35 +3,38 @@
 //
 
 import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Effect from 'effect/Effect';
 import * as Schema from 'effect/Schema';
-import React, { useCallback, useState } from 'react';
+import React, { useCallback, useMemo, useState } from 'react';
 
-import { Obj, Tag, Type } from '@dxos/echo';
+import { Annotation, Filter, Format, Obj, Ref, Tag, Type } from '@dxos/echo';
 import { type AnyProperties } from '@dxos/echo/internal';
 import { log } from '@dxos/log';
-import { useSpaces } from '@dxos/react-client/echo';
+import { useQuery, useSpaces } from '@dxos/react-client/echo';
 import { withClientProvider } from '@dxos/react-client/testing';
 import { Tooltip } from '@dxos/react-ui';
 import { Loading, withLayout, withTheme } from '@dxos/react-ui/testing';
+import { Text } from '@dxos/schema';
 
 import { translations } from '#translations';
 
+import { AutofillAnnotation, OptionsLookupAnnotation, autofill, optionsLookup } from '../../annotations';
 import { Organization, Person, TestLayout } from '../../testing';
 import { type ExcludeId, omitId } from '../../util';
 import { Form, type FormRootProps } from './Form';
 
-type DefaultStoryProps<T extends AnyProperties> = {
-  schema?: Schema.Schema<T>;
-} & FormRootProps<T>;
+type StoryArgs<T extends AnyProperties> = FormRootProps<T> & { json?: boolean };
 
 const DefaultStory = <T extends AnyProperties = AnyProperties>({
   schema,
   values: valuesProp,
+  json = true,
   ...props
-}: DefaultStoryProps<T>) => {
+}: StoryArgs<T>) => {
   const [values, setValues] = useState<Partial<T>>(valuesProp ?? {});
   const spaces = useSpaces();
   const space = spaces[0];
+
   const handleSave = useCallback<NonNullable<FormRootProps<T>['onSave']>>((values) => {
     log.info('save', { values, meta });
     setValues(values);
@@ -48,7 +51,7 @@ const DefaultStory = <T extends AnyProperties = AnyProperties>({
 
   return (
     <Tooltip.Provider>
-      <TestLayout json={{ values, schema: schema?.ast }}>
+      <TestLayout json={json ? { values, schema: schema?.ast } : undefined}>
         <Form.Root
           schema={schema}
           defaultValues={values}
@@ -59,7 +62,7 @@ const DefaultStory = <T extends AnyProperties = AnyProperties>({
         >
           <Form.Viewport scroll>
             <Form.Content>
-              <Form.Section label='Section' description='This is a section' />
+              <Form.Section title='Section' description='This is a [section description](https://dxos.org).' />
               <Form.FieldSet />
               <Form.Actions />
             </Form.Content>
@@ -80,11 +83,12 @@ const meta = {
     withClientProvider({
       createIdentity: true,
       createSpace: true,
-      types: [Tag.Tag, Organization, Person],
+      types: [Tag.Tag, Organization, Person, Text.Text],
       onCreateSpace: ({ space }) => {
         [
           ...Array.from({ length: 3 }).map((_, i) => Obj.make(Tag.Tag, { label: `Tag ${i}` })),
           ...Array.from({ length: 50 }).map((_, i) => Obj.make(Organization, { name: `Organization ${i}` })),
+          Obj.make(Text.Text, { content: '# Brief\n\nEdit this **inline** markdown text.' }),
         ].map((obj) => space.db.add(obj));
       },
     }),
@@ -93,12 +97,10 @@ const meta = {
     layout: 'fullscreen',
     translations,
   },
-} satisfies Meta<DefaultStoryProps<any>>;
+} satisfies Meta<StoryArgs<any>>;
 
 export default meta;
 
-type Story<T extends AnyProperties> = StoryObj<DefaultStoryProps<T>>;
-
 const PersonSchema = Type.getSchema(Person);
 
 const values: Partial<Person> = {
@@ -110,6 +112,8 @@ const values: Partial<Person> = {
   reminderAt: '09:00:00',
 };
 
+type Story<T extends AnyProperties> = StoryObj<StoryArgs<T>>;
+
 /**
  * Build a data-entry surface by handing an Effect schema to `Form.Root` — the form derives its fields,
  * types, validation, and selects from the schema, so you don't hand-wire one control per property.
@@ -147,6 +151,246 @@ export const Static: Story<ExcludeId<typeof PersonSchema>> = {
   },
 };
 
+const SettingsSchema = Schema.mutable(
+  Schema.Struct({
+    viewMode: Schema.Literal('preview', 'readonly', 'source').annotations({
+      title: 'Default view mode',
+      description: 'Set whether documents open in editing or read-only mode.',
+    }),
+    toolbar: Schema.optional(
+      Schema.Boolean.annotations({
+        title: 'Show toolbar',
+        description: 'Display a formatting toolbar above the editor.',
+      }),
+    ),
+    fontSize: Schema.optional(
+      Schema.Number.annotations({ title: 'Font size', description: 'Editor font size, in pixels.' }),
+    ),
+  }),
+);
+
+export const Variants: Story<Schema.Schema.Type<typeof SettingsSchema>> = {
+  render: (args) => (
+    <div className='grid grid-cols-2 w-full'>
+      <DefaultStory {...args} />
+      <DefaultStory {...args} variant='settings' />
+    </div>
+  ),
+  args: {
+    json: false,
+    schema: SettingsSchema,
+    values: {
+      viewMode: 'preview',
+      toolbar: true,
+      fontSize: 14,
+    },
+  },
+};
+
+const InlineMarkdownTextSchema = Schema.mutable(
+  Schema.Struct({
+    text: Schema.String,
+    instructions: Ref.Ref(Text.Text).pipe(
+      Format.FormatAnnotation.set(Format.TypeFormat.Markdown),
+      Annotation.FormInlineAnnotation.set(true),
+      Schema.annotations({
+        title: 'Instructions',
+        description: 'Ref to a Text object with both markdown and inline-ref annotations.',
+      }),
+    ),
+  }),
+);
+
+const InlineMarkdownTextStory = (args: StoryArgs<any>) => {
+  const spaces = useSpaces();
+  const space = spaces[0];
+  const [text] = useQuery(space?.db, Filter.type(Text.Text));
+  const values = useMemo(() => (text ? { instructions: Ref.make(text) } : undefined), [text]);
+
+  if (!space || !values) {
+    return <Loading />;
+  }
+
+  return (
+    <DefaultStory
+      {...args}
+      schema={InlineMarkdownTextSchema}
+      values={values}
+      onCreate={(_type, props) => space.db.add(Obj.make(Text.Text, { content: '', ...props }))}
+    />
+  );
+};
+
+/**
+ * Exercises a `Ref<Text>` field carrying both `Format.TypeFormat.Markdown` and
+ * `FormInlineAnnotation` — the markdown editor should render inline rather than
+ * opening a ref picker or nested struct form.
+ */
+export const InlineMarkdownText: Story<any> = {
+  render: (args) => <InlineMarkdownTextStory {...args} />,
+  args: {
+    autoSave: true,
+  },
+};
+
 export const Empty: Story<ExcludeId<typeof PersonSchema>> = {
   args: {},
 };
+
+// Demonstrates the value-driven dynamic-field annotations (here backed by in-memory Effects with an
+// artificial delay rather than network calls, so the story is deterministic): a select whose options
+// derive from the `query` field, and a text field auto-filled from the `url` field. Each annotation
+// declares the fields it depends on, so it only re-runs when one of those changes. Structural validation
+// is the schema's own job (`Format.URL`).
+const isValidUrl = Schema.is(Format.URL);
+
+// Base struct (no dynamic annotations) — its value type drives the typed `deps`/`values` below.
+const DynamicFieldsBase = Schema.Struct({
+  query: Schema.String.annotations({ title: 'Query', description: 'Type to load the choices below.' }),
+  choice: Schema.optional(Schema.String),
+  tag: Schema.optional(Schema.String),
+  url: Format.URL.annotations({ title: 'URL', description: 'A valid URL auto-fills the name below.' }),
+  name: Schema.optional(Schema.String),
+});
+type DynamicFieldsValues = Schema.Schema.Type<typeof DynamicFieldsBase>;
+
+const TAG_VOCABULARY = ['react', 'effect', 'schema', 'echo', 'composer'];
+
+const DynamicFieldsSchema = Schema.mutable(
+  Schema.Struct({
+    ...DynamicFieldsBase.fields,
+    choice: Schema.optional(
+      Schema.String.pipe(
+        OptionsLookupAnnotation.set(
+          optionsLookup<DynamicFieldsValues>()(['query'], ({ query }) =>
+            (query && query.length > 0
+              ? Effect.succeed(
+                  [1, 2, 3].map((index) => ({ value: `${query}-${index}`, label: `${query} choice ${index}` })),
+                )
+              : Effect.succeed([])
+            ).pipe(Effect.delay('600 millis')),
+          ),
+        ),
+        Schema.annotations({ title: 'Choice', description: 'Options load from the query (after a delay).' }),
+      ),
+    ),
+    // Combobox: the field's own value is the query; the typed text is the auto-selected first option.
+    tag: Schema.optional(
+      Schema.String.pipe(
+        OptionsLookupAnnotation.set(
+          optionsLookup<DynamicFieldsValues>()(
+            // No deps: the pool is fetched once; the combobox filters it by the typed text client-side.
+            [],
+            () =>
+              Effect.succeed(TAG_VOCABULARY.map((value) => ({ value, label: value }))).pipe(Effect.delay('400 millis')),
+            { combobox: true },
+          ),
+        ),
+        Schema.annotations({ title: 'Tag', description: 'Combobox: type to filter; your text stays selectable.' }),
+      ),
+    ),
+    name: Schema.optional(
+      Schema.String.pipe(
+        // Only derive a value once the URL is structurally valid, and only after the artificial wait —
+        // an incomplete/invalid URL produces nothing.
+        AutofillAnnotation.set(
+          autofill<DynamicFieldsValues>()(['url'], ({ url }) =>
+            isValidUrl(url)
+              ? Effect.succeed(`Feed for ${url}`).pipe(Effect.delay('800 millis'))
+              : Effect.succeed(undefined),
+          ),
+        ),
+        Schema.annotations({ title: 'Name', description: 'Auto-filled from a valid URL (editable).' }),
+      ),
+    ),
+  }),
+);
+
+/**
+ * Exercises the dynamic-field annotations: `OptionsLookupAnnotation` (select options loaded from a
+ * sibling) and `AutofillAnnotation` (value derived from a sibling, gated on validity and delayed). Each
+ * runs a self-contained Effect from the current form values.
+ */
+export const DynamicFields: Story<Schema.Schema.Type<typeof DynamicFieldsSchema>> = {
+  args: {
+    json: true,
+    schema: DynamicFieldsSchema,
+  },
+};
+
+// Discriminated-union create form mirroring the magazine create-feed schema: a `type` selector picks the
+// member, whose fields then render — `standard-site` (handle combobox → publication select) or `rss`
+// (URL → auto-filled name). Backed by in-memory Effects so the story is deterministic. Regression harness
+// for union create forms (e.g. the `omitId` union-flattening bug).
+const HANDLE_SUGGESTIONS = ['dxos.org', 'alice.bsky.social', 'bob.example.com'];
+
+const StandardSiteCreateBase = Schema.Struct({
+  type: Schema.Literal('standard-site'),
+  handle: Schema.String.annotations({ title: 'Handle', description: 'atproto handle, e.g. dxos.org.' }),
+  // No `name`: the feed name is taken from the selected publication.
+  publication: Schema.String.annotations({ title: 'Publication', description: 'Choose a publication.' }),
+});
+type StandardSiteValues = Schema.Schema.Type<typeof StandardSiteCreateBase>;
+
+const StandardSiteCreate = Schema.Struct({
+  ...StandardSiteCreateBase.fields,
+  handle: StandardSiteCreateBase.fields.handle.pipe(
+    OptionsLookupAnnotation.set(
+      optionsLookup<StandardSiteValues>()(
+        ['handle'],
+        () =>
+          Effect.succeed(HANDLE_SUGGESTIONS.map((value) => ({ value, label: value }))).pipe(Effect.delay('300 millis')),
+        { combobox: true },
+      ),
+    ),
+  ),
+  publication: StandardSiteCreateBase.fields.publication.pipe(
+    OptionsLookupAnnotation.set(
+      optionsLookup<StandardSiteValues>()(['handle'], ({ handle }) =>
+        Effect.succeed(
+          handle
+            ? [
+                { value: `at://${handle}/pub/blog`, label: `${handle} — Blog` },
+                { value: `at://${handle}/pub/notes`, label: `${handle} — Notes` },
+              ]
+            : [],
+        ).pipe(Effect.delay('300 millis')),
+      ),
+    ),
+  ),
+});
+
+const RssCreateBase = Schema.Struct({
+  type: Schema.Literal('rss'),
+  url: Format.URL.annotations({ title: 'URL', description: 'RSS feed URL.' }),
+  name: Schema.optional(Schema.String.annotations({ title: 'Name' })),
+});
+type RssValues = Schema.Schema.Type<typeof RssCreateBase>;
+
+const RssCreate = Schema.Struct({
+  ...RssCreateBase.fields,
+  name: Schema.optional(
+    Schema.String.pipe(
+      AutofillAnnotation.set(
+        autofill<RssValues>()(['url'], ({ url }) =>
+          isValidUrl(url)
+            ? Effect.succeed(`Feed for ${url}`).pipe(Effect.delay('500 millis'))
+            : Effect.succeed(undefined),
+        ),
+      ),
+    ).annotations({ title: 'Name' }),
+  ),
+});
+
+const CreateFeedSchema = Schema.Union(StandardSiteCreate, RssCreate);
+
+/**
+ * A discriminated-union create form: selecting `type` reveals that member's fields (combobox + select for
+ * `standard-site`, URL + autofill for `rss`). Mirrors the magazine create-feed schema.
+ */
+export const DiscriminatedUnion: Story<Schema.Schema.Type<typeof CreateFeedSchema>> = {
+  args: {
+    json: true,
+    schema: CreateFeedSchema,
+  },
+};

package/src/components/Form/Form.theme.test.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { formTheme } from './Form.theme';
+
+describe('formTheme', () => {
+  test('default variant adds no chrome to the field', ({ expect }) => {
+    const styles = formTheme.styles({ variant: 'default' });
+    expect(styles.field()).toBeFalsy();
+    expect(formTheme.behavior.default.showDescription).toBe(false);
+  });
+
+  test('settings variant frames the field and shows the description', ({ expect }) => {
+    const styles = formTheme.styles({ variant: 'settings' });
+    // Assert stable invariants (bordered, grid-framed, prominent label, right-aligned control),
+    // not the specific grid mechanism, so the test survives layout tweaks.
+    expect(styles.field()).toContain('border');
+    expect(styles.field()).toContain('grid');
+    expect(styles.fieldLabel()).toContain('[grid-area:header]');
+    expect(styles.fieldLabelText()).toContain('text-lg');
+    expect(styles.fieldControl()).toContain('justify-end');
+    expect(formTheme.behavior.settings.showDescription).toBe(true);
+  });
+
+  test('per-slot override wins', ({ expect }) => {
+    const styles = formTheme.styles({ variant: 'settings' });
+    expect(styles.fieldLabelText({ class: 'text-2xl' })).toContain('text-2xl');
+    expect(styles.fieldLabelText({ class: 'text-2xl' })).not.toContain('text-lg');
+  });
+});