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

package/src/components/ObjectProperties/ObjectProperties.tsx

@@ -15,15 +15,17 @@ import { HuePicker } from '@dxos/react-ui-pickers';
 import { FactoryAnnotation } from '@dxos/schema';
 
 import { translationKey } from '#translations';
-import { type FormFieldMap } from '#types';
+import { type FormFieldMap, type RefFieldDataProps } from '#types';
 
 import { Form, META_TAGS_KEY, withMetaTags } from '../Form';
 
-export type ObjectPropertiesProps = PropsWithChildren<{ object: Obj.Unknown }>;
+export type ObjectPropertiesProps = PropsWithChildren<
+  { object: Obj.Unknown } & Pick<RefFieldDataProps, 'getCreateDefaults' | 'resolveCreateEntry'>
+>;
 
 // TODO(wittjosiah): Reconcile w/ ObjectForm.
 export const ObjectProperties = composable<HTMLDivElement, ObjectPropertiesProps>(
-  ({ children, object, ...props }, forwardedRef) => {
+  ({ children, object, getCreateDefaults, resolveCreateEntry, ...props }, forwardedRef) => {
     const db = Obj.getDatabase(object);
     const meta = Obj.getMeta(object);
     // `meta.tags` already holds `Ref<Tag>`s (materialized by the database handler).
@@ -111,6 +113,7 @@ export const ObjectProperties = composable<HTMLDivElement, ObjectPropertiesProps
 
     return (
       <Form.Root
+        db={db}
         schema={formSchema}
         defaultValues={values as any}
         createTypename={Type.getTypename(Tag.Tag)}
@@ -118,14 +121,15 @@ export const ObjectProperties = composable<HTMLDivElement, ObjectPropertiesProps
         createOptionLabel={['add-tag.label', { ns: translationKey }]}
         createInitialValuePath='label'
         createFieldMap={createFieldMap}
-        db={db}
         onValuesChanged={handleChange}
         onCreate={handleCreate}
+        getCreateDefaults={getCreateDefaults}
+        resolveCreateEntry={resolveCreateEntry}
       >
-        <Form.Viewport {...composableProps(props)} ref={forwardedRef}>
+        <Form.Viewport {...composableProps(props)} scroll ref={forwardedRef}>
           <Form.Content>
             <Form.FieldSet />
-            {children}
+            <Form.Section>{children}</Form.Section>
           </Form.Content>
         </Form.Viewport>
       </Form.Root>
@@ -134,12 +138,12 @@ export const ObjectProperties = composable<HTMLDivElement, ObjectPropertiesProps
 );
 
 const createFieldMap: FormFieldMap = {
-  hue: ({ type, label, layout, getValue, onValueChange }) => {
+  hue: ({ type, label, presentation, 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} />}
+        {presentation !== 'inline' && <Form.Label label={label} />}
         <HuePicker value={getValue()} onChange={handleChange} onReset={handleReset} />
       </>
     );

package/src/components/RefEditor/RefEditor.stories.tsx

@@ -69,11 +69,11 @@ const PeopleGrid = ({ db }: { db?: Database.Database }) => {
   );
 };
 
-type StoryProps = Partial<Pick<RefEditorProps, 'value' | 'mode' | 'activateOnTyping' | 'autoFocus'>>;
+type StoryArgs = Partial<Pick<RefEditorProps, 'value' | 'mode' | 'activateOnTyping' | 'autoFocus'>>;
 
 // NOTE: The Person config (type/match/getValues) is supplied in render, not args — Storybook's
 // arg traversal attempts to mutate the proxied ECHO schema and crashes.
-const DefaultStory = ({ value: initialValue, ...args }: StoryProps) => {
+const DefaultStory = ({ value: initialValue, ...args }: StoryArgs) => {
   const { space } = useClientStory();
   const [value, setValue] = useState(initialValue ?? '');
 

package/src/components/RefEditor/RefEditor.tsx

@@ -246,7 +246,7 @@ export const RefEditor = forwardRef<EditorController, RefEditorProps>(
       >
         <Editor.View
           // TOOD(burdon): Use same style as react-ui Input.
-          classNames='border border-separator rounded-xs px-2'
+          classNames='border border-input-separator rounded-xs px-2'
           {...props}
           initialValue={value}
           selectionEnd

package/src/components/ViewEditor/ViewEditor.stories.tsx

@@ -35,9 +35,9 @@ export type ViewEditorDebugObjects = {
   projection: ProjectionModel;
 };
 
-type DefaultStoryProps = Pick<ViewEditorProps, 'readonly' | 'mode'>;
+type StoryArgs = Pick<ViewEditorProps, 'readonly' | 'mode'>;
 
-const DefaultStory = (props: DefaultStoryProps) => {
+const DefaultStory = (props: StoryArgs) => {
   const { space } = useClientStory();
   const [type, setType] = useState<Type.AnyEntity>();
   const [view, setView] = useState<View.View>();

package/src/components/ViewEditor/ViewEditor.test.tsx

@@ -138,11 +138,17 @@ describe('ViewEditor', () => {
     expect(addedPropertyProjection!.props.property).toBe('added_property');
   });
 
-  // TODO(mykola): Fix flaky test.
-  test('delete property', { retry: 2 }, async () => {
+  test('delete property', async () => {
     await Default.run();
     await waitForViewEditor();
 
+    // Wait for the field list to render — useObject(view) inside ViewEditor resolves
+    // asynchronously after the outer story's type/view state is set, so the debug
+    // element can appear before the list items are in the DOM.
+    await waitFor(() => {
+      expect(screen.getByText('name')).toBeInTheDocument();
+    });
+
     // Find the delete button for the 'name' property.
     const nameProperty = screen.getByText('name');
     const propertyRow = nameProperty.closest('[role="listitem"]');

package/src/components/ViewEditor/ViewEditor.tsx

@@ -39,10 +39,10 @@ import {
 import { mx } from '@dxos/ui-theme';
 
 import { translationKey } from '#translations';
-import { type FormFieldRenderer, type FormFieldRendererProps, type FormFieldMap } from '#types';
+import { type FormFieldMap, type FormFieldRenderer, type FormFieldRendererProps } from '#types';
 
 import { FieldEditor } from '../FieldEditor';
-import { CompactIconButton, FieldHeader, Form, FormFieldLabel, type FormRootProps } from '../Form';
+import { CompactIconButton, Form, FormFieldHeader, FormFieldLabel, type FormRootProps } from '../Form';
 
 export type ViewEditorProps = ThemedClassName<
   {
@@ -352,7 +352,7 @@ const FieldList = ({ type, view, registry, readonly, showHeading = false, onDele
     >
       {({ items: fields }) => (
         <>
-          <FieldHeader
+          <FormFieldHeader
             label={t('fields.label')}
             readonly={readonly}
             add={{

package/src/components/index.ts

@@ -9,5 +9,4 @@ export * from './ObjectPicker';
 export * from './ObjectProperties';
 export * from './ObjectTree';
 export * from './RefEditor';
-export * from './Settings';
 export * from './ViewEditor';

package/src/hooks/index.ts

@@ -2,6 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
+export * from './useAsyncFieldEffect';
 export * from './useFormContext';
 export * from './useFormHandler';
 export * from './useKeyHandler';

package/src/hooks/useAsyncFieldEffect.ts

@@ -0,0 +1,81 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import { useEffect, useRef, useState } from 'react';
+
+import { type AnyProperties } from '@dxos/echo/internal';
+
+/** Picks the declared dependency fields from the form values — the subset a dynamic field subscribes to. */
+export const pickValues = (values: AnyProperties | undefined, deps: readonly string[]): Record<string, unknown> => {
+  const subset: Record<string, unknown> = {};
+  for (const dep of deps) {
+    subset[dep] = values?.[dep];
+  }
+  return subset;
+};
+
+export type AsyncFieldEffectState<A> = {
+  loading: boolean;
+  error: unknown;
+  data: A | undefined;
+};
+
+export type UseAsyncFieldEffectOptions = {
+  /** Debounce applied before running, so per-keystroke value changes coalesce into one run. */
+  debounceMs?: number;
+  /** When false, the effect is not run and prior data/error is cleared. */
+  enabled?: boolean;
+};
+
+/**
+ * Runs a self-contained Effect (`R = never`) whenever `key` changes, debounced and abortable. Used by
+ * dynamic form fields to load select options, derive values, or validate against an external source from
+ * the current form values. The latest `factory` is always used, but a run is only (re)triggered when
+ * `key` changes — derive `key` from the inputs the factory actually reads. Re-running interrupts the
+ * prior run (cancelling any in-flight request).
+ */
+export const useAsyncFieldEffect = <A>(
+  factory: () => Effect.Effect<A, unknown>,
+  key: string,
+  { debounceMs = 400, enabled = true }: UseAsyncFieldEffectOptions = {},
+): AsyncFieldEffectState<A> => {
+  const factoryRef = useRef(factory);
+  factoryRef.current = factory;
+  const [state, setState] = useState<AsyncFieldEffectState<A>>({ loading: false, error: undefined, data: undefined });
+
+  useEffect(() => {
+    if (!enabled) {
+      setState({ loading: false, error: undefined, data: undefined });
+      return;
+    }
+
+    let cancel: (() => void) | undefined;
+    const timer = setTimeout(() => {
+      setState((prev) => ({ ...prev, loading: true, error: undefined }));
+      cancel = Effect.runCallback(factoryRef.current(), {
+        onExit: (exit: Exit.Exit<A, unknown>) => {
+          Exit.match(exit, {
+            onSuccess: (data) => setState({ loading: false, error: undefined, data }),
+            onFailure: (cause) => {
+              // A superseding run interrupts this one; ignore the resulting interruption.
+              if (!Cause.isInterruptedOnly(cause)) {
+                setState((prev) => ({ loading: false, error: Cause.squash(cause), data: prev.data }));
+              }
+            },
+          });
+        },
+      });
+    }, debounceMs);
+
+    return () => {
+      clearTimeout(timer);
+      cancel?.();
+    };
+  }, [key, enabled, debounceMs]);
+
+  return state;
+};

package/src/hooks/useFormContext.ts

@@ -9,8 +9,9 @@ import { useEffect, useMemo, useRef } from 'react';
 import { type AnyProperties } from '@dxos/echo/internal';
 import { SchemaEx } from '@dxos/effect';
 
-import { type CreateOptions, type FormFieldOptions, type FormFieldStateProps } from '#types';
+import { type FieldContext, type FormFieldStateProps } from '#types';
 
+import { type FormVariant } from '../components/Form/Form.theme';
 import { type FormHandler } from './useFormHandler';
 
 //
@@ -27,8 +28,10 @@ export type FormContextValue<T extends AnyProperties = any> = {
    * Testing.
    */
   testId?: string;
-} & FormFieldOptions &
-  Pick<CreateOptions, 'createFieldMap'>;
+
+  /** Visual variant applied across the form's parts (see Form.theme). */
+  variant?: FormVariant;
+} & FieldContext;
 
 export const [FormContextProvider, useFormContext] = createContext<FormContextValue>('Form');
 

package/src/hooks/useFormHandler.ts

@@ -77,17 +77,21 @@ export type FormHandler<T extends AnyProperties> = Pick<FormHandlerProps<T>, 'sc
   /** Initial values (which may not pass validation). */
   values: Partial<T>;
 
-  /** Map of changed fields. */
+  /** Fields whose value has been edited (set by `onValueChange`). Gates autosave-on-blur. */
   changed: Record<SchemaEx.JsonPath, boolean>;
-  // TODO(burdon): How is this different from above?
+  /** Fields the user has interacted with (set by `onBlur`). Gates error *visibility* — errors only surface once touched. */
   touched: Record<SchemaEx.JsonPath, boolean>;
 
   /** Map of error strings. */
   errors: Record<SchemaEx.JsonPath, string>;
 
-  /** Whether the form can be saved (i.e., data is valid). */
+  /** Whether the values pass validation (no errors at all). */
   isValid: boolean;
-  // TODO(burdon): Why is this needed separately from isValid?
+  /**
+   * Whether the submit affordance should be enabled. Stricter than `isValid`: it also requires no save
+   * in flight (`saving`) and only blocks on errors for *touched* fields, so a pristine form with
+   * not-yet-touched required fields can still show an enabled control.
+   */
   canSave: boolean;
 
   onSave: () => void;
@@ -325,6 +329,7 @@ export const useFormHandler = <T extends AnyProperties>({
     }),
     [
       schema,
+      autoSave,
       values,
       errors,
       touched,
@@ -335,8 +340,8 @@ export const useFormHandler = <T extends AnyProperties>({
       getValue,
       onBlur,
       onValueChange,
-      onSave,
-      onCancel,
+      handleSave,
+      handleCancel,
     ],
   );
 };

package/src/index.ts

@@ -2,6 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
+export * from './annotations';
 export * from './components';
 export * from './hooks';
 export * from './types';

package/src/testing/TestLayout.tsx

@@ -7,23 +7,26 @@ import React, { type PropsWithChildren } from 'react';
 import { type ThemedClassName } from '@dxos/react-ui';
 import { composableProps, slottable } from '@dxos/react-ui';
 import { Syntax } from '@dxos/react-ui-syntax-highlighter';
+import { mx } from '@dxos/ui-theme';
 
-type TestLayoutProps = PropsWithChildren<{ json?: any }>;
+type TestLayoutProps = PropsWithChildren<{ json?: unknown }>;
 
 export const TestLayout = ({ children, json }: TestLayoutProps) => {
   return (
-    <div className='dx-container grid grid-cols-[1fr_1fr] p-4 gap-4'>
+    <div className={mx('dx-container grid grid-cols-1 p-4 gap-4', !!json && 'grid-cols-[1fr_1fr]')}>
       <TestPanel>{children}</TestPanel>
-      <TestPanel>
-        <Syntax.Root data={json}>
-          <Syntax.Content>
-            <Syntax.Filter />
-            <Syntax.Viewport>
-              <Syntax.Code testId='debug' classNames='text-sm' />
-            </Syntax.Viewport>
-          </Syntax.Content>
-        </Syntax.Root>
-      </TestPanel>
+      {!!json && (
+        <TestPanel>
+          <Syntax.Root data={json}>
+            <Syntax.Content>
+              <Syntax.Filter />
+              <Syntax.Viewport>
+                <Syntax.Code testId='debug' classNames='text-sm' />
+              </Syntax.Viewport>
+            </Syntax.Content>
+          </Syntax.Root>
+        </TestPanel>
+      )}
     </div>
   );
 };

package/src/testing/schema.ts

@@ -12,48 +12,48 @@ import { Annotation, DXN, Format, Ref, Tag, Type } from '@dxos/echo';
  * structs, refs, ref arrays, enums, and the various formats.
  */
 
-export const Organization = Schema.Struct({
-  name: Schema.String.pipe(Schema.minLength(1)).annotations({ title: 'Full name' }),
-}).pipe(Type.makeObject(DXN.make('com.example.type.organization', '0.1.0')));
+export class Organization extends Type.makeObject<Organization>(DXN.make('com.example.type.organization', '0.1.0'))(
+  Schema.Struct({
+    name: Schema.String.pipe(Schema.minLength(1)).annotations({ title: 'Full name' }),
+  }),
+) {}
 
-export type Organization = Type.InstanceType<typeof Organization>;
-
-export const Person = Schema.Struct({
-  name: Schema.String.pipe(Schema.minLength(1)).annotations({ title: 'Full name' }),
-  ignore: Schema.String.pipe(Annotation.FormInputAnnotation.set(false), Schema.optional),
-  active: Schema.optional(Schema.Boolean.annotations({ title: 'Active' })),
-  address: Schema.optional(
-    Schema.Struct({
-      street: Schema.String,
-      city: Schema.String,
-      // TODO(burdon): Constrain input control.
-      state: Schema.String.pipe(Schema.minLength(2), Schema.maxLength(2)).annotations({
-        title: 'State',
-        description: 'State code',
-      }),
-      zip: Schema.Number.annotations({ title: 'ZIP Code' }),
-    }).annotations({ title: 'Address' }),
-  ),
-  employer: Schema.optional(Ref.Ref(Organization).annotations({ title: 'Employer' })),
-  tags: Schema.optional(Schema.Array(Ref.Ref(Tag.Tag)).annotations({ title: 'Tags' })),
-  status: Schema.optional(Schema.Literal('active', 'inactive').annotations({ title: 'Status' })),
-  notes: Schema.optional(Format.Text.annotations({ title: 'Notes' })),
-  location: Schema.optional(Format.GeoPoint.annotations({ title: 'Location' })),
-  birthday: Schema.optional(Format.DateOnly.annotations({ title: 'Birthday' })),
-  meetingAt: Schema.optional(Format.DateTime.annotations({ title: 'Next meeting' })),
-  reminderAt: Schema.optional(Format.TimeOnly.annotations({ title: 'Reminder time' })),
-  tasks: Schema.optional(Schema.Array(Schema.String).annotations({ title: 'Tasks' })),
-  locations: Schema.optional(Schema.Array(Format.GeoPoint).annotations({ title: 'Locations' })),
-  identities: Schema.optional(
-    Schema.Array(
+export class Person extends Type.makeObject<Person>(DXN.make('org.dxos.type.person', '0.1.0'))(
+  Schema.Struct({
+    name: Schema.String.pipe(Schema.minLength(1)).annotations({ title: 'Full name' }),
+    ignore: Schema.String.pipe(Annotation.FormInputAnnotation.set(false), Schema.optional),
+    active: Schema.optional(Schema.Boolean.annotations({ title: 'Active' })),
+    address: Schema.optional(
       Schema.Struct({
-        type: Schema.String.annotations({ title: 'Type' }),
-        value: Schema.String.annotations({ title: 'Value' }),
-      }).annotations({ title: 'Identities' }),
-    ).annotations({
-      title: 'Identities',
-    }),
-  ),
-}).pipe(Type.makeObject(DXN.make('org.dxos.type.person', '0.1.0')));
-
-export type Person = Type.InstanceType<typeof Person>;
+        street: Schema.String,
+        city: Schema.String,
+        // TODO(burdon): Constrain input control.
+        state: Schema.String.pipe(Schema.minLength(2), Schema.maxLength(2)).annotations({
+          title: 'State',
+          description: 'State code',
+        }),
+        zip: Schema.Number.annotations({ title: 'ZIP Code' }),
+      }).annotations({ title: 'Address' }),
+    ),
+    employer: Schema.optional(Ref.Ref(Organization).annotations({ title: 'Employer' })),
+    tags: Schema.optional(Schema.Array(Ref.Ref(Tag.Tag)).annotations({ title: 'Tags' })),
+    status: Schema.optional(Schema.Literal('active', 'inactive').annotations({ title: 'Status' })),
+    notes: Schema.optional(Format.Text.annotations({ title: 'Notes' })),
+    location: Schema.optional(Format.GeoPoint.annotations({ title: 'Location' })),
+    birthday: Schema.optional(Format.DateOnly.annotations({ title: 'Birthday' })),
+    meetingAt: Schema.optional(Format.DateTime.annotations({ title: 'Next meeting' })),
+    reminderAt: Schema.optional(Format.TimeOnly.annotations({ title: 'Reminder time' })),
+    tasks: Schema.optional(Schema.Array(Schema.String).annotations({ title: 'Tasks' })),
+    locations: Schema.optional(Schema.Array(Format.GeoPoint).annotations({ title: 'Locations' })),
+    identities: Schema.optional(
+      Schema.Array(
+        Schema.Struct({
+          type: Schema.String.annotations({ title: 'Type' }),
+          value: Schema.String.annotations({ title: 'Value' }),
+        }).annotations({ title: 'Identities' }),
+      ).annotations({
+        title: 'Identities',
+      }),
+    ),
+  }),
+) {}

package/src/types.ts

@@ -52,13 +52,21 @@ export type FormFieldRendererProps<T = any> = {
   format?: Format.TypeFormat;
   readonly?: boolean;
   label: string;
+  /**
+   * Human-readable description (from the schema's description annotation). Rendered as visible text
+   * only when the resolved presentation opts in; otherwise it falls back to the input placeholder.
+   */
+  description?: string;
   /**
    * Dotted JSON path of this field within the form values (e.g. `runtime.client.storage.persistent`).
    */
   jsonPath?: string;
   placeholder?: string;
   autoFocus?: boolean;
-  layout?: FormPresentation;
+  /** Presentation mode for the field (full/compact/inline/static); see {@link FormPresentation}. */
+  presentation?: FormPresentation;
+  /** Whether the field is required (non-optional in the schema); surfaces a trailing asterisk on the label. */
+  required?: boolean;
 } & FormFieldStateProps<T>;
 
 export type FormFieldRenderer = FC<FormFieldRendererProps>;
@@ -75,6 +83,18 @@ export type FormFieldProvider = (props: {
 // Ref / create contracts.
 //
 
+/**
+ * Per-typename override for the ref-field inline create form and its submission handler.
+ * The type parameter S links the form schema's decoded type to the createObject values argument,
+ * ensuring the schema and the handler agree on the shape of the form data.
+ */
+export type CreateEntryOverride<S extends Schema.Schema.AnyNoContext = Schema.Schema.AnyNoContext> = {
+  /** Replaces the raw ECHO type schema for the inline create form. */
+  inputSchema?: S;
+  /** Runs instead of the default onCreate(schema, values) path; values are typed from inputSchema. */
+  createObject?: (values: Schema.Schema.Type<S>, db: Database.Database) => Promise<Obj.Unknown>;
+};
+
 /**
  * Configuration for the inline "create a new referenced object" affordance, shared by every
  * surface that can spawn a ref target (the picker, `RefField`, and the `Form*` props that forward
@@ -91,6 +111,8 @@ export type CreateOptions = {
 export type RefOption = {
   id: string;
   label: string;
+  /** Optional secondary line shown beneath the label in the picker list. */
+  description?: string;
   hue?: Palette;
 };
 
@@ -112,6 +134,20 @@ export type RefFieldDataProps = {
    * object is then wired into this slot's form value as a Ref.
    */
   onCreate?: (schema: Type.AnyEntity, values: any) => Obj.Unknown | Promise<Obj.Unknown> | undefined | void;
+  /**
+   * Supply default values for a newly-created owned object when the user clicks "add" on an owned-ref
+   * array field (see `FormCreateAnnotation`). Keyed by the field's json path so a container can pre-populate
+   * the new object (e.g. a back-reference to the parent). The returned values are passed to
+   * `onCreate(schema, values)` before the object is persisted.
+   */
+  getCreateDefaults?: (props: { jsonPath: string; schema: Type.AnyEntity }) => Record<string, unknown> | undefined;
+  /**
+   * Optional resolver that maps a ref's typename to a {@link CreateEntryOverride}, replacing the
+   * raw ECHO type schema and/or the default `onCreate` path with plugin-registered create logic
+   * (e.g. `SpaceCapabilities.CreateObjectEntry`). When absent or returning `undefined` for a given
+   * typename the existing fallback behaviour is preserved.
+   */
+  resolveCreateEntry?: (typename: string) => CreateEntryOverride | undefined;
 };
 
 /**
@@ -132,3 +168,19 @@ export type FormFieldOptions = {
    */
   createTypename?: string;
 };
+
+/**
+ * The subset of {@link RefFieldDataProps} that is forwarded down the field recursion. `useResults`
+ * is consumed only by `RefField` itself (it defaults internally), so it is not threaded.
+ */
+export type RefThreadedProps = Pick<
+  RefFieldDataProps,
+  'useType' | 'getOptions' | 'onCreate' | 'getCreateDefaults' | 'resolveCreateEntry'
+>;
+
+/**
+ * Form-wide configuration threaded unchanged down the entire field recursion. This is the single
+ * canonical source for the bag that `FormContextValue`, `FormFieldProps`, and `FormFieldSetProps`
+ * all carry — so none of them re-Picks fragments of the others.
+ */
+export type FieldContext = FormFieldOptions & CreateOptions & RefThreadedProps;

package/src/util/index.ts

@@ -3,7 +3,6 @@
 //
 
 export * from './field';
-export * from './field-type';
 export * from './formatting';
 export * from './omit';
 export * from './properties';

package/src/util/omit.ts

@@ -9,14 +9,13 @@ import * as SchemaAST from 'effect/SchemaAST';
 import { Annotation, Type } from '@dxos/echo';
 
 // TODO(burdon): Reconcile with @dxos/echo.
-export type ExcludeId<S extends Schema.Schema.AnyNoContext | Type.AnyEntity> = Omit<
-  S extends Type.AnyEntity
-    ? Type.InstanceType<S>
-    : S extends Schema.Schema.AnyNoContext
-      ? Schema.Schema.Type<S>
-      : never,
-  'id'
->;
+// Distributive: applied per union member so `ExcludeId<A | B>` → `ExcludeId<A> | ExcludeId<B>` rather
+// than `Omit<InstanceType<A> | InstanceType<B>, 'id'>` (which would intersect away per-member narrowing).
+export type ExcludeId<S extends Schema.Schema.AnyNoContext | Type.AnyEntity> = S extends Type.AnyEntity
+  ? Omit<Type.InstanceType<S>, 'id'>
+  : S extends Schema.Schema.AnyNoContext
+    ? Omit<Schema.Schema.Type<S>, 'id'>
+    : never;
 
 // TODO(burdon): Move to @dxos/schema (re-export here).
 export const omitId = <S extends Schema.Schema.AnyNoContext | Type.AnyEntity>(
@@ -25,9 +24,24 @@ export const omitId = <S extends Schema.Schema.AnyNoContext | Type.AnyEntity>(
   const schema = Type.isType(schemaOrType)
     ? Type.getSchema(schemaOrType)
     : (schemaOrType as Schema.Schema.AnyNoContext);
-  // Cast: `Schema.omit` cannot statically express the `ExcludeId<S>` result type, so the pipe
-  // returns a widened schema; the runtime shape matches the declared return type.
-  return schema.pipe(Schema.omit('id')) as any;
+  // Cast: `Schema.omit` cannot statically express the `ExcludeId<S>` result type, so the result is a
+  // widened schema; the runtime shape matches the declared return type.
+  return omitIdFromSchema(schema) as any;
+};
+
+/**
+ * Removes the `id` field where present, preserving the schema's shape. Recurses into unions so a
+ * discriminated (create) schema keeps its discriminant — `Schema.omit('id')` is a struct operation and
+ * would otherwise flatten the union, breaking variant rendering. A no-op when there is no `id` (plain
+ * create structs that never carried one).
+ */
+const omitIdFromSchema = (schema: Schema.Schema.AnyNoContext): Schema.Schema.AnyNoContext => {
+  const ast = schema.ast;
+  if (SchemaAST.isUnion(ast)) {
+    return Schema.Union(...ast.types.map((type) => omitIdFromSchema(Schema.make(type))));
+  }
+  const hasId = SchemaAST.getPropertySignatures(ast).some((prop) => prop.name === 'id');
+  return hasId ? schema.pipe(Schema.omit('id')) : schema;
 };
 
 /**