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

package/src/components/Form/{fields → FormField/fields}/index.ts

@@ -3,12 +3,15 @@
 //
 
 export * from './ArrayField';
+export * from './AsyncSelectField';
+export * from './AutofillField';
 export * from './BooleanField';
+export * from './ComboboxField';
 export * from './DateField';
 export * from './GeoPointField';
-export * from './InlineRefField';
 export * from './MarkdownField';
 export * from './NumberField';
+export * from './PasswordField';
 export * from './RefField';
 export * from './SelectField';
 export * from './SelectOptionField';

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

@@ -0,0 +1,10 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './fields';
+export * from './presentation';
+
+export * from './FormFieldHeader';
+export * from './FormField';
+export * from './FormRow';

package/src/components/Form/FormField/presentation.tsx

@@ -0,0 +1,32 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type FormPresentation } from '#types';
+
+/**
+ * Resolved presentation strategy for a field — which parts render, derived from {@link FormPresentation}.
+ * Visual chrome (borders, grid, spacing) is owned by the Form theme recipe, not here.
+ */
+export type FormFieldPresentation = {
+  layout?: FormPresentation;
+  /** Render the value as read-only plain DOM rather than an editable control. */
+  isStatic: boolean;
+  /** Render the field's label row. */
+  showLabel: boolean;
+  /** Render the inline validation/error block beneath the control. */
+  showError: boolean;
+};
+
+/**
+ * Derive the {@link FormFieldPresentation} for a layout.
+ * - `static` renders read-only plain DOM.
+ * - `inline` drops the label (the control stands alone, e.g. an array row).
+ * - `full` adds the inline error block.
+ */
+export const presentationFor = (layout?: FormPresentation): FormFieldPresentation => ({
+  layout,
+  isStatic: layout === 'static',
+  showLabel: layout !== 'inline',
+  showError: layout === 'full',
+});

package/src/components/Form/{FormFieldSet.tsx → FormFieldSet/FormFieldSet.tsx}

@@ -3,81 +3,66 @@
 //
 
 import * as Option from 'effect/Option';
-import React, { useMemo, useState } from 'react';
+import React, { useMemo } from 'react';
 
+import { DEFAULT_LAYOUT_NAME, FormLayoutAnnotation } from '@dxos/echo/Annotation';
 import { type AnyProperties } from '@dxos/echo/internal';
 import { SchemaEx } from '@dxos/effect';
-import { IconButton, useTranslation } from '@dxos/react-ui';
-import { mx } from '@dxos/ui-theme';
+import { type Merge } from '@dxos/util';
 
-import { translationKey } from '#translations';
+import { type FieldContext } from '#types';
 
-import { type FormHandlerProps } from '../../hooks';
-import { getRootFormProperties } from '../../util';
-import { useFormValues } from './Form';
-import { FormField, type FormFieldProps } from './FormField';
-import { FormFieldErrorBoundary, FormFieldLabel } from './FormFieldComponent';
-import { DEFAULT_LAYOUT_NAME, FormLayout, FormLayoutAnnotation } from './Layout';
+import { type FormHandlerProps, useFormValues } from '../../../hooks';
+import { getRootFormProperties } from '../../../util';
+import { FormField, FormFieldErrorBoundary, type FormFieldProps, presentationFor } from '../FormField';
+import { FormLayout } from '../FormLayout';
+import { FormFieldSetContainer } from './FormFieldSetContainer';
 
 const FORM_FIELDSET_NAME = 'Form.FieldSet';
 
-export type FormFieldSetProps<T extends AnyProperties> = {
-  label?: string;
-  sort?: string[];
-  /**
-   * When set, renders a toggle button at the end of the label row that
-   * shows/hides the field set body. Used for nested objects.
-   */
-  collapsible?: boolean;
-  exclude?: (props: SchemaEx.SchemaProperty[]) => SchemaEx.SchemaProperty[];
-  /**
-   * Picks a named layout out of `FormLayoutAnnotation` when present.
-   * Falls back to `'default'`. Ignored when the schema has no annotation
-   * (linear rendering then takes over).
-   */
-  layoutName?: string;
-} & Pick<FormHandlerProps<T>, 'schema'> &
-  Pick<
-    FormFieldProps,
-    | 'path'
-    | 'autoFocus'
-    | 'readonly'
-    | 'layout'
-    | 'projection'
-    | 'fieldMap'
-    | 'fieldProvider'
-    | 'createTypename'
-    | 'createOptionLabel'
-    | 'createOptionIcon'
-    | 'createInitialValuePath'
-    | 'createFieldMap'
-    | 'db'
-    | 'useType'
-    | 'getOptions'
-    | 'onCreate'
-  >;
+export type FormFieldSetProps<T extends AnyProperties> = Merge<
+  {
+    /** Applied to the field set's container (the bordered box when collapsible). */
+    classNames?: string;
+    label?: string;
+    sort?: string[];
+    /**
+     * When set, renders a toggle button at the end of the label row that
+     * shows/hides the field set body. Used for nested objects.
+     */
+    collapsible?: boolean;
+    filter?: (props: SchemaEx.SchemaProperty[]) => SchemaEx.SchemaProperty[];
+    /**
+     * Picks a named layout out of `FormLayoutAnnotation` when present.
+     * Falls back to `'default'`. Ignored when the schema has no annotation
+     * (linear rendering then takes over).
+     */
+    layoutName?: string;
+  },
+  Pick<FormHandlerProps<T>, 'schema'>,
+  Pick<FormFieldProps, 'path' | 'autoFocus'>,
+  FieldContext
+>;
 
 /**
  * Renders a set of form fields derived from a schema object.
  */
 export const FormFieldSet = ({
+  classNames,
   label,
   schema,
   readonly,
   path,
   sort,
   collapsible,
-  exclude,
+  filter,
   projection,
   layout,
   layoutName = DEFAULT_LAYOUT_NAME,
   ...props
 }: FormFieldSetProps<any>) => {
-  const { t } = useTranslation(translationKey);
   const values = useFormValues(FORM_FIELDSET_NAME, path);
-  const properties = useFormFieldSetProperties({ schema, values, exclude, sort, projection });
-  // TODO(burdon): Generalize collapse state (cf. useSelected in react-ui-attention, plugin-markdown cursor state).
-  const [collapsed, setCollapsed] = useState(false);
+  const properties = useFormFieldSetProperties({ schema, values, filter, sort, projection });
   if ((readonly || layout === 'static') && values == null) {
     return null;
   }
@@ -105,6 +90,7 @@ export const FormFieldSet = ({
               type={property.type}
               name={name}
               path={[...(path ?? []), name]}
+              required={!property.isOptional}
               readonly={readonly}
               layout={layout}
               projection={projection}
@@ -115,56 +101,33 @@ export const FormFieldSet = ({
       })
     );
 
-  const showBody = !(collapsible && collapsed);
-  const content = (
-    <>
-      {layout !== 'inline' && label && (
-        <FormFieldLabel
-          asChild
-          classNames='pl-2'
-          label={label}
-          path={SchemaEx.createJsonPath(path ?? [])}
-          button={
-            collapsible && (
-              <IconButton
-                classNames='px-1 mr-0.5'
-                variant='ghost'
-                density='xs'
-                iconOnly
-                icon='ph--caret-right--regular'
-                iconClassNames={mx('transition-transform', !collapsed && 'rotate-90')}
-                label={t(collapsed ? 'expand-fields.label' : 'collapse-fields.label')}
-              />
-            )
-          }
-          onClick={() => setCollapsed((value) => !value)}
-        />
-      )}
-      {showBody && (collapsible ? <div className='px-2 pb-2'>{body}</div> : body)}
-    </>
+  return (
+    <FormFieldSetContainer
+      classNames={classNames}
+      label={label}
+      path={SchemaEx.createJsonPath(path ?? [])}
+      readonly={readonly}
+      presentation={presentationFor(layout)}
+      collapsible={collapsible}
+    >
+      {body}
+    </FormFieldSetContainer>
   );
-
-  // Nested field sets render inside an indented, bordered container with a collapse toggle.
-  if (collapsible) {
-    return <div className='border border-subdued-separator rounded-sm mt-2'>{content}</div>;
-  }
-
-  return content;
 };
 
 FormFieldSet.displayName = FORM_FIELDSET_NAME;
 
-type UseFormFieldSetPropertiesParams = Pick<FormFieldSetProps<any>, 'schema' | 'exclude' | 'projection' | 'sort'> & {
+type UseFormFieldSetPropertiesParams = Pick<FormFieldSetProps<any>, 'schema' | 'filter' | 'projection' | 'sort'> & {
   values: AnyProperties | undefined;
   sort?: string[];
 };
 
 /**
- * Resolves ordered schema properties for a field set (projection order, exclude, or sort).
+ * Resolves ordered schema properties for a field set (projection order, filter, or sort).
  */
 const useFormFieldSetProperties = ({
   schema,
-  exclude,
+  filter,
   projection,
   values,
   sort,
@@ -176,9 +139,9 @@ const useFormFieldSetProperties = ({
       return [];
     }
 
-    // TODO(wittjosiah): Reconcile FormInputAnnotation with projection hidden properties & exclude function.
+    // TODO(wittjosiah): Reconcile FormInputAnnotation with projection hidden properties & filter function.
     const schemaProps = getRootFormProperties(schema.ast, values);
-    const filteredProps = exclude ? exclude(schemaProps) : schemaProps;
+    const filteredProps = filter ? filter(schemaProps) : schemaProps;
 
     // Use projection-based field management when view and projection are available.
     if (projection) {
@@ -209,5 +172,5 @@ const useFormFieldSetProperties = ({
     return sort
       ? [...filteredProps].sort(({ name: a }, { name: b }) => sort.indexOf(a.toString()) - sort.indexOf(b.toString()))
       : filteredProps;
-  }, [schema, values, exclude, sort, projection]);
+  }, [schema, values, filter, sort, projection]);
 };

package/src/components/Form/FormFieldSet/FormFieldSetContainer.tsx

@@ -0,0 +1,93 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { type PropsWithChildren, useState } from 'react';
+
+import { type ThemedClassName, ToggleIconButton, useTranslation } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+
+import { translationKey } from '#translations';
+
+import { formTheme } from '../Form.theme';
+import { FormFieldHeader } from '../FormField/FormFieldHeader';
+import { type FormFieldPresentation } from '../FormField/presentation';
+
+const styles = formTheme.styles();
+
+export type FormFieldSetContainerProps = ThemedClassName<
+  PropsWithChildren<{
+    label?: string;
+    /** JSON path of the group, forwarded to the label as field metadata. */
+    path?: string;
+    readonly?: boolean;
+    presentation: FormFieldPresentation;
+    /**
+     * Render a collapse toggle in the header and wrap the body in an indented, bordered box.
+     * Used for nested objects (struct fields, object-array items, inline refs).
+     */
+    collapsible?: boolean;
+  }>
+>;
+
+/**
+ * Shared chrome for a labelled group of sub-fields: an optional header (label + collapse toggle) and,
+ * when collapsible, an indented bordered container around the body. Nested structs, object-array items,
+ * and inline refs all reach this via `FormFieldSet`, so their visual containment is identical.
+ */
+export const FormFieldSetContainer = ({
+  classNames,
+  label,
+  path,
+  readonly,
+  presentation,
+  collapsible,
+  children,
+}: FormFieldSetContainerProps) => {
+  const { t } = useTranslation(translationKey);
+  // TODO(burdon): Generalize collapse state (cf. useSelection in react-ui-attention, plugin-markdown cursor state).
+  const [collapsed, setCollapsed] = useState(false);
+  const showBody = !(collapsible && collapsed);
+
+  const content = (
+    <>
+      {presentation.showLabel && label && (
+        <FormFieldHeader
+          label={label}
+          path={path}
+          readonly={readonly}
+          classNames='pl-2'
+          actions={
+            collapsible ? (
+              <ToggleIconButton
+                active={!collapsed}
+                classNames='px-1 mr-0.5'
+                variant='ghost'
+                density='xs'
+                iconOnly
+                icon='ph--caret-right--regular'
+                label={t(collapsed ? 'expand-fields.label' : 'collapse-fields.label')}
+              />
+            ) : undefined
+          }
+          onClick={collapsible ? () => setCollapsed((value) => !value) : undefined}
+        />
+      )}
+      {showBody && (collapsible ? <div className={styles.fieldSetBody()}>{children}</div> : children)}
+    </>
+  );
+
+  // Nested groups render inside an indented, bordered container with a collapse toggle. A non-collapsible
+  // group only materializes a wrapper when `classNames` is supplied — otherwise the body flows straight
+  // into the parent grid (the default, grid-transparent behavior).
+  if (collapsible) {
+    return (
+      <div className={styles.fieldSetBoxOuter()}>
+        <div className={styles.fieldSetBox({ class: mx(classNames) })}>{content}</div>
+      </div>
+    );
+  }
+
+  // Only materialize a wrapper when `classNames` is supplied; otherwise stay grid-transparent.
+  return classNames ? <div className={mx(classNames)}>{content}</div> : <>{content}</>;
+};

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

@@ -0,0 +1,6 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './FormFieldSet';
+export * from './FormFieldSetContainer';

package/src/components/Form/{Layout → FormLayout}/FormLayout.stories.tsx

@@ -19,9 +19,9 @@ import { trim } from '@dxos/util';
 
 import { translations } from '#translations';
 
-import { TestLayout, TestPanel } from '../../testing';
-import { Form, type FormRootProps, omitId } from '../Form';
-import { FormLayoutAnnotation } from './annotation';
+import { TestLayout, TestPanel } from '../../../testing';
+import { omitId } from '../../../util';
+import { Form, type FormRootProps } from '../Form';
 import { parseLayout } from './parser';
 
 /**
@@ -84,7 +84,7 @@ const FLIGHT_LAYOUT_COMPACT = trim`
  */
 const AnnotatedFlight = Type.getSchema(Flight)
   .annotations({})
-  .pipe(FormLayoutAnnotation.set({ default: FLIGHT_LAYOUT, compact: FLIGHT_LAYOUT_COMPACT }));
+  .pipe(Annotation.FormLayoutAnnotation.set({ default: FLIGHT_LAYOUT, compact: FLIGHT_LAYOUT_COMPACT }));
 
 /**
  * Sample schema with nested `Place` structs carrying a `LabelAnnotation`.
@@ -125,12 +125,12 @@ const JOURNEY_LAYOUT = trim`
   </grid>
 `;
 
-type StoryProps = {
+type StoryArgs = {
   schema: Schema.Schema<any>;
   template?: string;
 };
 
-const DefaultStory = ({ schema, template }: StoryProps) => {
+const DefaultStory = ({ schema, template }: StoryArgs) => {
   const [values, setValues] = useState<Partial<FlightValues>>(flight);
 
   const handleSave = useCallback<NonNullable<FormRootProps<any>['onSave']>>((next) => {
@@ -164,11 +164,11 @@ const meta = {
     layout: 'fullscreen',
     translations,
   },
-} satisfies Meta<StoryProps>;
+} satisfies Meta<StoryArgs>;
 
 export default meta;
 
-type Story = StoryObj<StoryProps>;
+type Story = StoryObj<StoryArgs>;
 
 /** Baseline: no annotation, no override — `Form.FieldSet` renders linearly (one field per row). */
 export const Linear: Story = {
@@ -383,7 +383,9 @@ const PlaygroundStory = ({ card = false }: PlaygroundStoryProps) => {
                   onChange={setTemplate}
                 />
               </Editor.Root>
-              {error && <div className='border-t border-separator p-2 text-sm text-error-text font-mono'>{error}</div>}
+              {error && (
+                <div className='border-t border-input-separator p-2 text-sm text-error-text font-mono'>{error}</div>
+              )}
             </div>
           </TestPanel>
           <TestPanel>

package/src/components/Form/{Layout → FormLayout}/FormLayout.tsx

@@ -13,11 +13,12 @@ import { type AnyProperties } from '@dxos/echo/internal';
 import { SchemaEx } from '@dxos/effect';
 import { Input } from '@dxos/react-ui';
 
-import { useFormFieldState } from '../Form';
-import { FormField, type FormFieldProps } from '../FormField';
-import { FormFieldErrorBoundary, FormFieldLabel, type Presentation } from '../FormFieldComponent';
-import { DEFAULT_LAYOUT_NAME, FormLayoutAnnotation } from './annotation';
-import { LayoutParseError, type LayoutNode, parseLayout } from './parser';
+import { type FormPresentation } from '#types';
+
+import { useFormContext, useFormFieldState } from '../../../hooks';
+import { formTheme } from '../Form.theme';
+import { FormField, FormFieldErrorBoundary, FormFieldLabel, type FormFieldProps, presentationFor } from '../FormField';
+import { type LayoutNode, LayoutParseError, parseLayout } from './parser';
 
 const FORM_LAYOUT_NAME = 'Form.Layout';
 
@@ -57,14 +58,14 @@ type FormFieldSetSubset = Pick<
 export const FormLayout = ({
   schema,
   template,
-  name = DEFAULT_LAYOUT_NAME,
+  name = Annotation.DEFAULT_LAYOUT_NAME,
   path,
   readonly,
   layout,
   projection,
   ...props
 }: FormLayoutProps) => {
-  const annotated = Option.getOrUndefined(FormLayoutAnnotation.get(schema));
+  const annotated = Option.getOrUndefined(Annotation.FormLayoutAnnotation.get(schema));
   const source = template ?? annotated?.[name];
   if (source === undefined) {
     throw new LayoutParseError(
@@ -114,7 +115,7 @@ const RenderNode = ({ node, schema, basePath, ...props }: RenderNodeProps) => {
     throw new LayoutParseError(`field "${node.name}" not found on schema`);
   }
 
-  const { type, segments, leafName, title, labelType } = resolved;
+  const { type, segments, leafName, title, labelType, required } = resolved;
   const path = [...basePath, ...segments];
   const span = node.span ? { gridColumn: `span ${node.span} / span ${node.span}` } : undefined;
 
@@ -129,7 +130,7 @@ const RenderNode = ({ node, schema, basePath, ...props }: RenderNodeProps) => {
             layout={props.layout}
           />
         ) : (
-          <FormField type={type} name={leafName} path={path} {...props} />
+          <FormField type={type} name={leafName} path={path} required={required} {...props} />
         )}
       </FormFieldErrorBoundary>
     </div>
@@ -151,6 +152,8 @@ export type ResolvedLayoutField = {
    * sub-fields. Undefined for ordinary (non-auto-labelled) fields.
    */
   labelType?: SchemaAST.AST;
+  /** Whether the resolved property is required (non-optional). */
+  required: boolean;
 };
 
 /**
@@ -215,6 +218,7 @@ export const resolveLayoutField = (schema: Schema.Schema<any>, name: string): Re
     leafName: segments[segments.length - 1],
     title,
     labelType: labelled ? labelType : undefined,
+    required: !prop.isOptional,
   };
 };
 
@@ -222,7 +226,7 @@ type LabelFieldProps = {
   schema: Schema.Schema<any>;
   label: string;
   path: (string | number)[];
-  layout?: Presentation;
+  layout?: FormPresentation;
 };
 
 /**
@@ -231,6 +235,8 @@ type LabelFieldProps = {
  * presentation of regular fields.
  */
 const LabelField = ({ schema, label, path, layout }: LabelFieldProps) => {
+  const { variant = 'default' } = useFormContext(FORM_LAYOUT_NAME);
+  const styles = formTheme.styles({ variant });
   const { getValue } = useFormFieldState(FORM_LAYOUT_NAME, path);
   const value = getValue();
   const text = value == null ? undefined : Annotation.getLabelWithSchema(schema, value);
@@ -238,14 +244,19 @@ const LabelField = ({ schema, label, path, layout }: LabelFieldProps) => {
     return null;
   }
 
+  const presentation = presentationFor(layout);
   return (
-    <div className='contents'>
-      <Input.Root>
-        {layout !== 'inline' && <FormFieldLabel readonly label={label} path={SchemaEx.createJsonPath(path)} />}
-        <p className='truncate min-w-0' title={text}>
-          {text}
-        </p>
-      </Input.Root>
-    </div>
+    <Input.Root>
+      <div className={styles.field()}>
+        {presentation.showLabel && (
+          <FormFieldLabel variant={variant} readonly label={label} path={SchemaEx.createJsonPath(path)} />
+        )}
+        <div className={styles.fieldControl()}>
+          <p className='truncate min-w-0' title={text}>
+            {text}
+          </p>
+        </div>
+      </div>
+    </Input.Root>
   );
 };

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

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { FormLayout, type FormLayoutProps } from './FormLayout';
+export { type LayoutNode, LayoutParseError, parseLayout } from './parser';

package/src/components/Form/index.ts

@@ -2,10 +2,8 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './fields';
+export * from './meta-tags';
 
 export * from './Form';
-export * from './FormFieldComponent';
-export * from './FormTooltipsContext';
-export * from './meta-tags';
-export * from './Layout';
+export * from './FormField';
+export * from './FormFieldSet';

package/src/components/Form/meta-tags.test.ts

@@ -11,7 +11,7 @@ import { Obj, Ref, Tag } from '@dxos/echo';
 import { META_TAGS_KEY, withMetaTags } from './meta-tags';
 
 // A feed-host schema whose own `tags` field is a `TagIndex` record (tagId -> objectId[]), not an
-// array — mirrors plugin-commerce `Search`, plugin-inbox `Mailbox`, plugin-feed `Subscription`.
+// array — mirrors plugin-commerce `Search`, plugin-inbox `Mailbox`, plugin-magazine `Subscription`.
 const TagIndexHost = Schema.Struct({
   name: Schema.String.pipe(Schema.optional),
   tags: Schema.Record({ key: Schema.String, value: Schema.Array(Obj.ID) }).pipe(Schema.optional),

package/src/components/Form/meta-tags.ts

@@ -6,7 +6,7 @@ import * as Schema from 'effect/Schema';
 
 import { Ref, Tag } from '@dxos/echo';
 
-import { omitId } from './Form';
+import { omitId } from '../../util';
 
 /**
  * Form-field key for the synthetic meta-tags array spliced into property/create forms.

package/src/components/ObjectForm/ObjectForm.tsx

@@ -10,27 +10,15 @@ import { invariant } from '@dxos/invariant';
 import { HuePicker } from '@dxos/react-ui-pickers';
 
 import { translationKey } from '#translations';
+import { type FormFieldMap } from '#types';
 
-import { Form, type FormFieldMap, META_TAGS_KEY, withMetaTags } from '../Form';
+import { Form, META_TAGS_KEY, withMetaTags } from '../Form';
 
 export type ObjectFormProps = {
   type: Type.AnyEntity;
   object: Obj.Unknown;
 };
 
-const createFieldMap: FormFieldMap = {
-  hue: ({ type, label, layout, getValue, onValueChange }) => {
-    const handleChange = useCallback((nextHue: string) => onValueChange(type, nextHue), [onValueChange, type]);
-    const handleReset = useCallback(() => onValueChange(type, undefined), [onValueChange, type]);
-    return (
-      <>
-        {layout !== 'inline' && <Form.Label label={label} />}
-        <HuePicker value={getValue()} onChange={handleChange} onReset={handleReset} />
-      </>
-    );
-  },
-};
-
 export const ObjectForm = ({ object, type }: ObjectFormProps) => {
   const db = Obj.getDatabase(object);
   const meta = Obj.getMeta(object);
@@ -109,3 +97,16 @@ export const ObjectForm = ({ object, type }: ObjectFormProps) => {
     </Form.Root>
   );
 };
+
+const createFieldMap: FormFieldMap = {
+  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 (
+      <>
+        {presentation !== 'inline' && <Form.Label label={label} />}
+        <HuePicker value={getValue()} onChange={handleChange} onReset={handleReset} />
+      </>
+    );
+  },
+};