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

package/src/components/Form/FormField/fields/SelectOptionField/SelectOptionField.tsx

@@ -14,7 +14,7 @@ import { hues, osTranslations } from '@dxos/ui-theme';
 import { translationKey } from '#translations';
 import { type FormFieldRendererProps } from '#types';
 
-import { FormFieldLabel } from '../../FormFieldWrapper';
+import { FormFieldLabel } from '../../FormRow';
 
 export const SelectOptionField = ({
   type,
@@ -145,7 +145,7 @@ export const SelectOptionField = ({
                       <OrderedList.DragHandle />
                       {/* TODO(ZaymonFC): Move spacer into Tag component. */}
                       <div className='flex grow items-center truncate px-2' onClick={() => handleClick(item.id)}>
-                        <Tag palette={item.color as ChromaticPalette}>{item.title || '\u200b'}</Tag>
+                        <Tag hue={item.color as ChromaticPalette}>{item.title || '\u200b'}</Tag>
                       </div>
                       <ToggleIconButton
                         iconOnly
@@ -183,12 +183,12 @@ export const SelectOptionField = ({
                   </OrderedList.Item>
                 ))}
                 <IconButton
+                  classNames='w-full'
                   variant='ghost'
                   icon='ph--plus--regular'
                   label={t('select-option-add.button')}
                   onClick={handleAdd}
                   disabled={!!readonly}
-                  classNames='w-full'
                 />
               </OrderedList.Content>
             )}

package/src/components/Form/FormField/fields/TextAreaField/TextAreaField.tsx

@@ -8,7 +8,7 @@ import { Input, type TextAreaProps } from '@dxos/react-ui';
 
 import { type FormFieldRendererProps } from '#types';
 
-import { FormFieldWrapper } from '../../FormFieldWrapper';
+import { FormRow } from '../../FormRow';
 
 export const TextAreaField = ({
   type,
@@ -24,7 +24,7 @@ export const TextAreaField = ({
   );
 
   return (
-    <FormFieldWrapper<string> readonly={readonly} {...props}>
+    <FormRow<string> readonly={readonly} {...props}>
       {({ value = '' }) => (
         <Input.TextArea
           rows={5}
@@ -35,6 +35,6 @@ export const TextAreaField = ({
           onBlur={onBlur}
         />
       )}
-    </FormFieldWrapper>
+    </FormRow>
   );
 };

package/src/components/Form/FormField/fields/TextField/TextField.tsx

@@ -8,7 +8,7 @@ import { Input, type TextInputProps } from '@dxos/react-ui';
 
 import { type FormFieldRendererProps } from '#types';
 
-import { FormFieldWrapper } from '../../FormFieldWrapper';
+import { FormRow } from '../../FormRow';
 
 export const TextField = ({
   type,
@@ -24,7 +24,7 @@ export const TextField = ({
   );
 
   return (
-    <FormFieldWrapper<string> readonly={readonly} {...props}>
+    <FormRow<string> readonly={readonly} {...props}>
       {({ value = '' }) => (
         <Input.TextInput
           noAutoFill
@@ -35,6 +35,6 @@ export const TextField = ({
           onChange={handleChange}
         />
       )}
-    </FormFieldWrapper>
+    </FormRow>
   );
 };

package/src/components/Form/FormField/fields/TupleField/TupleField.tsx

@@ -10,7 +10,7 @@ import { safeParseFloat } from '@dxos/util';
 
 import { type FormFieldRendererProps } from '#types';
 
-import { FormFieldLabel } from '../../FormFieldWrapper';
+import { FormFieldLabel } from '../../FormRow';
 
 const gridCols = ['grid-cols-1', 'grid-cols-2', 'grid-cols-3', 'grid-cols-4'];
 

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

@@ -3,11 +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 './MarkdownField';
 export * from './NumberField';
+export * from './PasswordField';
 export * from './RefField';
 export * from './SelectField';
 export * from './SelectOptionField';

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

@@ -2,7 +2,9 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './FieldHeader';
-export * from './FormField';
 export * from './fields';
-export * from './FormFieldWrapper';
+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/FormFieldSet.tsx

@@ -3,65 +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 { ToggleIconButton, useTranslation } from '@dxos/react-ui';
+import { type Merge } from '@dxos/util';
 
-import { translationKey } from '#translations';
-import { type CreateOptions, type FormFieldOptions, type RefFieldDataProps } from '#types';
+import { type FieldContext } from '#types';
 
 import { type FormHandlerProps, useFormValues } from '../../../hooks';
 import { getRootFormProperties } from '../../../util';
-import { FormField, FormFieldErrorBoundary, FormFieldLabel, type FormFieldProps } from '../FormField';
+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'> &
-  FormFieldOptions &
-  CreateOptions &
-  Pick<RefFieldDataProps, '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. useSelection 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;
   }
@@ -89,6 +90,7 @@ export const FormFieldSet = ({
               type={property.type}
               name={name}
               path={[...(path ?? []), name]}
+              required={!property.isOptional}
               readonly={readonly}
               layout={layout}
               projection={projection}
@@ -99,56 +101,33 @@ export const FormFieldSet = ({
       })
     );
 
-  const showBody = !(collapsible && collapsed);
-  const content = (
-    <>
-      {layout !== 'inline' && label && (
-        <FormFieldLabel
-          standalone
-          classNames='pl-2'
-          label={label}
-          path={SchemaEx.createJsonPath(path ?? [])}
-          button={
-            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')}
-              />
-            )
-          }
-          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 mb-1'>{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,
@@ -160,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) {
@@ -193,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

@@ -3,3 +3,4 @@
 //
 
 export * from './FormFieldSet';
+export * from './FormFieldSetContainer';

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

@@ -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/FormLayout/FormLayout.tsx

@@ -15,10 +15,10 @@ import { Input } from '@dxos/react-ui';
 
 import { type FormPresentation } from '#types';
 
-import { useFormFieldState } from '../../../hooks';
-import { FormField, type FormFieldProps } from '../FormField';
-import { FormFieldErrorBoundary, FormFieldLabel } from '../FormField';
-import { LayoutParseError, type LayoutNode, parseLayout } from './parser';
+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';
 
@@ -115,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;
 
@@ -130,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>
@@ -152,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;
 };
 
 /**
@@ -216,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,
   };
 };
 
@@ -232,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);
@@ -239,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

@@ -3,4 +3,4 @@
 //
 
 export { FormLayout, type FormLayoutProps } from './FormLayout';
-export { LayoutParseError, parseLayout, type LayoutNode } from './parser';
+export { type LayoutNode, LayoutParseError, parseLayout } from './parser';

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/ObjectForm/ObjectForm.tsx

@@ -99,12 +99,12 @@ export const ObjectForm = ({ object, type }: ObjectFormProps) => {
 };
 
 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/ObjectPicker/ObjectPicker.tsx

@@ -129,6 +129,7 @@ const ObjectPickerContent = forwardRef<HTMLDivElement, ObjectPickerContentProps>
               key={option.id}
               value={option.id}
               label={option.label}
+              description={option.description}
               checked={selectedIds?.includes(option.id)}
               onSelect={() => onSelect?.(option.id)}
               classNames='flex items-center gap-2'

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

@@ -7,7 +7,7 @@ import * as Schema from 'effect/Schema';
 import React, { useEffect } from 'react';
 import { expect, userEvent, within } from 'storybook/test';
 
-import { DXN, Annotation, Filter, Obj, Ref, Tag, Type } from '@dxos/echo';
+import { Annotation, DXN, Filter, Obj, Ref, Tag, Type } from '@dxos/echo';
 import { FormInputAnnotation, LabelAnnotation } from '@dxos/echo/Annotation';
 import { useQuery } from '@dxos/react-client/echo';
 import { useClientStory, withClientProvider } from '@dxos/react-client/testing';