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

package/src/components/Form/FormField.tsx

@@ -7,9 +7,9 @@ import * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 import * as String from 'effect/String';
-import React, { useMemo } from 'react';
+import React, { PropsWithChildren, useMemo } from 'react';
 
-import { Format } from '@dxos/echo';
+import { Annotation, Format } from '@dxos/echo';
 import {
   createJsonPath,
   findNode,
@@ -20,8 +20,9 @@ import {
   isLiteralUnion,
   isNestedType,
 } from '@dxos/effect';
-import { useTranslation } from '@dxos/react-ui';
+import { IconButton, IconButtonProps, useTranslation } from '@dxos/react-ui';
 import { type ProjectionModel } from '@dxos/schema';
+import { mx } from '@dxos/ui-theme';
 
 import { translationKey } from '#translations';
 
@@ -29,7 +30,9 @@ import { getRefProps } from '../../util';
 import {
   ArrayField,
   BooleanField,
+  DateField,
   GeoPointField,
+  InlineRefField,
   MarkdownField,
   NumberField,
   RefField,
@@ -54,9 +57,14 @@ export type FormFieldProps = {
   type: SchemaAST.AST;
 
   /**
-   * Name of the property.
+   * Name of the property. Used to derive a default label
+   * (`title ?? capitalize(name)`) and as the projection lookup key. Pass
+   * `null` to suppress the header label entirely -- the form still renders
+   * the field/struct, but `FormFieldSet`'s top-level `<FormFieldLabel>` is
+   * skipped. Used by `ArrayField` for object-array items, where every item
+   * would otherwise repeat the array's parent name.
    */
-  name: string;
+  name: string | null;
 
   /**
    * Path to the current object from the root. Used with nested forms.
@@ -78,6 +86,7 @@ export type FormFieldProps = {
    * Function to lookup custom renderers for specific properties.
    */
   fieldProvider?: FormFieldProvider;
+
   /**
    * Typename of the ref type that the create props apply to.
    * When set, createOptionLabel/createOptionIcon/createInitialValuePath/createFieldMap/onCreate
@@ -92,7 +101,7 @@ export type FormFieldProps = {
     | 'createInitialValuePath'
     | 'createFieldMap'
     | 'db'
-    | 'useSchema'
+    | 'useType'
     | 'getOptions'
     | 'onCreate'
   >;
@@ -115,7 +124,7 @@ export const FormField = (props: FormFieldProps) => {
     createInitialValuePath,
     createFieldMap,
     db,
-    useSchema: schemaHook,
+    useType: schemaHook,
     getOptions,
     onCreate,
   } = props;
@@ -124,36 +133,53 @@ export const FormField = (props: FormFieldProps) => {
   const description = getAnnotation<string>(SchemaAST.DescriptionAnnotationId)(type);
   const examples = getAnnotation<string[]>(SchemaAST.ExamplesAnnotationId)(type);
 
-  const label = useMemo(() => title ?? String.capitalize(name), [title, name]);
+  // `name === null` means "no header" -- collapse to an empty string so
+  // downstream consumers keep their `label: string` types, and the falsy
+  // value lets `FormFieldSet`'s `label && <FormFieldLabel ...>` guard skip
+  // the header.
+  const label = useMemo(() => title ?? (name == null ? '' : String.capitalize(name)), [title, name]);
   const placeholder = useMemo(
     () => (examples?.length ? `${t('example.placeholder')}: ${examples[0]}` : (description ?? label)),
     [examples, description, label],
   );
 
   const fieldState = useFormFieldState(FormField.displayName, path);
+  const jsonPath = createJsonPath(path ?? []);
   const fieldProps: FormFieldComponentProps = {
     type,
     format: Format.FormatAnnotation.getFromAst(type).pipe((annotation) => Option.getOrUndefined(annotation)),
     readonly,
     label,
+    jsonPath,
     placeholder,
     layout,
     db,
     ...fieldState,
   };
 
+  // Omit empty fields entirely in read-only mode -- an empty value has nothing
+  // to display, so a labelled row with a blank input is just noise. This
+  // mirrors what `FormFieldWrapper` already does for `layout === 'static'`, but
+  // covers every field type (including those that bypass the wrapper:
+  // RefField, SelectField, MarkdownField, ...). Container fields
+  // (`ArrayField`, nested-struct -> `FormFieldSet`) keep their own
+  // empty-value checks, but those branches only apply when the value is
+  // actually a non-null array/object, so this check doesn't interfere.
+  if (readonly && fieldState.getValue() == null) {
+    return null;
+  }
+
   //
   // Custom field.
   //
 
-  const jsonPath = createJsonPath(path ?? []);
   const CustomField = fieldMap?.[jsonPath];
   if (CustomField) {
     return <CustomField {...fieldProps} />;
   }
 
   // TODO(burdon): Expensive to create schema each time; pass AST?
-  const component = fieldProvider?.({ schema: Schema.make(type), prop: name, fieldProps });
+  const component = fieldProvider?.({ schema: Schema.make(type), prop: name ?? '', fieldProps });
   if (component) {
     return component;
   }
@@ -206,6 +232,12 @@ export const FormField = (props: FormFieldProps) => {
 
   const refProps = getRefProps(type);
   if (refProps) {
+    // Inline a single referenced object's own fields (nested form) instead of a picker.
+    const inline = Annotation.FormInlineAnnotation.getFromAst(refProps.ast).pipe(Option.getOrElse(() => false));
+    if (inline && !refProps.isArray) {
+      return <InlineRefField {...fieldProps} {...refProps} db={db} useType={schemaHook} onCreate={onCreate} />;
+    }
+
     const isCreateTarget = !createTypename || refProps.typename === createTypename;
     return (
       <RefField
@@ -216,7 +248,7 @@ export const FormField = (props: FormFieldProps) => {
         createInitialValuePath={isCreateTarget ? createInitialValuePath : undefined}
         createFieldMap={isCreateTarget ? createFieldMap : undefined}
         db={db}
-        useSchema={schemaHook}
+        useType={schemaHook}
         getOptions={getOptions}
         onCreate={onCreate}
       />
@@ -236,23 +268,25 @@ export const FormField = (props: FormFieldProps) => {
     if (typeLiteral) {
       const schema = Schema.make(typeLiteral);
       return (
-        <FormFieldSet
-          schema={schema}
-          path={path}
-          readonly={readonly}
-          layout={layout}
-          label={label}
-          projection={projection}
-          fieldMap={fieldMap}
-          fieldProvider={fieldProvider}
-          createOptionLabel={createOptionLabel}
-          createOptionIcon={createOptionIcon}
-          createInitialValuePath={createInitialValuePath}
-          db={db}
-          useSchema={schemaHook}
-          getOptions={getOptions}
-          onCreate={onCreate}
-        />
+        <Nesting>
+          <FormFieldSet
+            schema={schema}
+            path={path}
+            readonly={readonly}
+            layout={layout}
+            label={label}
+            projection={projection}
+            fieldMap={fieldMap}
+            fieldProvider={fieldProvider}
+            createOptionLabel={createOptionLabel}
+            createOptionIcon={createOptionIcon}
+            createInitialValuePath={createInitialValuePath}
+            db={db}
+            useType={schemaHook}
+            getOptions={getOptions}
+            onCreate={onCreate}
+          />
+        </Nesting>
       );
     }
   }
@@ -262,6 +296,26 @@ export const FormField = (props: FormFieldProps) => {
 
 FormField.displayName = 'Form.FormField';
 
+//
+// Layout components
+//
+
+// TODO(burdon): Options (nested or flat).
+// TODO(burdon): Support collapsible.
+export const Nesting = ({ children }: PropsWithChildren) => (
+  <div className='px-2 border border-subdued-separator rounded-sm mt-2'>
+    <div className='pb-2'>{children}</div>
+  </div>
+);
+
+export const IconBlock = ({ inline, ...props }: IconButtonProps & { inline?: boolean }) => {
+  return (
+    <div className={mx('h-full flex px-1', inline ? 'items-center' : 'flex-col pt-2.5')}>
+      <IconButton variant='ghost' density='xs' square iconOnly {...props} />
+    </div>
+  );
+};
+
 /**
  * Get property input component.
  */
@@ -272,9 +326,12 @@ const getFormField = ({ type, format }: FormFieldComponentProps): FormFieldCompo
 
   const formatField = Match.value(format).pipe(
     Match.withReturnType<FormFieldComponent | undefined>(),
+    Match.when(Format.TypeFormat.Date, () => DateField),
+    Match.when(Format.TypeFormat.DateTime, () => DateField),
     Match.when(Format.TypeFormat.GeoPoint, () => GeoPointField),
     Match.when(Format.TypeFormat.Markdown, () => MarkdownField),
     Match.when(Format.TypeFormat.Text, () => TextAreaField),
+    Match.when(Format.TypeFormat.Time, () => DateField),
     Match.orElse(() => undefined),
   );
   if (formatField) {

package/src/components/Form/FormFieldComponent.tsx

@@ -2,6 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
+import { format as formatDate } from 'date-fns';
 import type * as Schema from 'effect/Schema';
 import type * as SchemaAST from 'effect/SchemaAST';
 import React, {
@@ -13,12 +14,13 @@ import React, {
   type ReactNode,
 } from 'react';
 
-import { type Database } from '@dxos/echo';
-import { type Format } from '@dxos/echo/internal';
+import { type Database, Format } from '@dxos/echo';
 import { Icon, Input, Tooltip } from '@dxos/react-ui';
-import { inputTextLabel } from '@dxos/ui-theme';
+import { inputTextLabel } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
 
 import { type FormFieldStatus } from '../../hooks';
+import { useFormTooltips } from './FormTooltipsContext';
 
 /**
  * Dynamic props passed to input components.
@@ -44,29 +46,33 @@ export type Presentation = 'full' | 'compact' | 'inline' | 'static';
  * Props passed to input components.
  */
 export type FormFieldComponentProps<T = any> = {
+  /** Database the form is editing against; populated for fields whose value is an ECHO object/Ref. */
+  db?: Database.Database;
   type: SchemaAST.AST;
   format?: Format.TypeFormat;
   readonly?: boolean;
   label: string;
+  /**
+   * Dotted JSON path of this field within the form values (e.g.
+   * `runtime.client.storage.persistent`). Forwarded to `FormFieldLabel` so
+   * that it can render the path as a debug hint when the enclosing
+   * `Form.Root` has `debug` enabled.
+   */
+  jsonPath?: string;
   placeholder?: string;
   autoFocus?: boolean;
   layout?: Presentation;
-  /** Database the form is editing against; populated for fields whose value is an ECHO object/Ref. */
-  db?: Database.Database;
 } & FormFieldStateProps<T>;
 
-/**
- * Form field component.
- */
 export type FormFieldComponent = FC<FormFieldComponentProps>;
 
 export type FormFieldMap = Record<string, FormFieldComponent>;
 
 export type FormFieldProvider = (props: {
-  prop: string; // TODO(burdon): Path?
+  prop: string;
   schema: Schema.Schema<any>;
   fieldProps: FormFieldComponentProps;
-}) => ReactElement | undefined;
+}) => ReactElement | null | undefined;
 
 //
 // FormFieldLabel
@@ -75,13 +81,30 @@ export type FormFieldProvider = (props: {
 export type FormFieldLabelProps = {
   asChild?: boolean;
   error?: string;
+  /**
+   * JSON path of the field this label describes (e.g. `runtime.client.storage.persistent`).
+   * Surfaced as a hover tooltip on the label when the enclosing `Form.Root`
+   * has `tooltips` enabled (the default) -- useful for spotting which field
+   * maps to which path when authoring schemas or filing bugs against a form.
+   * Callers can supply the path unconditionally; the label suppresses the
+   * tooltip when `Form.Root tooltips={false}`.
+   */
+  path?: string;
 } & Pick<FormFieldComponentProps, 'label' | 'readonly'>;
 
-export const FormFieldLabel = ({ label, error, readonly, asChild }: FormFieldLabelProps) => {
+export const FormFieldLabel = ({ label, error, readonly, asChild, path }: FormFieldLabelProps) => {
+  const tooltips = useFormTooltips();
   const Label = readonly || asChild ? 'span' : Input.Label;
+  const labelNode = <Label className={mx(inputTextLabel, 'text-sm')}>{label}</Label>;
   return (
     <div className='flex items-center justify-between'>
-      <Label className={inputTextLabel}>{label}</Label>
+      {tooltips && path ? (
+        <Tooltip.Trigger asChild content={path} side='bottom'>
+          {labelNode}
+        </Tooltip.Trigger>
+      ) : (
+        labelNode
+      )}
       {error && (
         <Tooltip.Trigger asChild content={error} side='bottom'>
           <Icon icon='ph--warning--regular' size={4} classNames='text-error-text' />
@@ -99,13 +122,39 @@ FormFieldLabel.displayName = 'Form.FieldLabel';
 
 export type FormFieldWrapperProps<T = any> = Pick<
   FormFieldComponentProps,
-  'readonly' | 'label' | 'layout' | 'getStatus' | 'getValue'
+  'readonly' | 'label' | 'layout' | 'getStatus' | 'getValue' | 'jsonPath' | 'format'
 > & {
   children?: (props: { value: T }) => ReactNode;
 };
 
+/**
+ * Formats a value for `static` (read-only, plain-DOM) presentation based on its
+ * type `format`. Dates/times are rendered human-readable; everything else falls
+ * back to `String(value)`.
+ */
+const formatStaticValue = (value: unknown, format?: Format.TypeFormat): string => {
+  if (value == null) {
+    return '';
+  }
+
+  switch (format) {
+    case Format.TypeFormat.DateTime:
+    case Format.TypeFormat.Date:
+    case Format.TypeFormat.Time: {
+      const date = new Date(value as string);
+      if (Number.isNaN(date.getTime())) {
+        return String(value);
+      }
+      const pattern = format === Format.TypeFormat.DateTime ? 'PPp' : format === Format.TypeFormat.Date ? 'PP' : 'p';
+      return formatDate(date, pattern);
+    }
+    default:
+      return String(value);
+  }
+};
+
 export const FormFieldWrapper = <T,>(props: FormFieldWrapperProps<T>) => {
-  const { children, readonly, layout, label, getStatus, getValue } = props;
+  const { children, readonly, layout, label, jsonPath, format, getStatus, getValue } = props;
   const { status, error } = getStatus();
 
   const value = getValue();
@@ -113,14 +162,20 @@ export const FormFieldWrapper = <T,>(props: FormFieldWrapperProps<T>) => {
     return null;
   }
 
-  const str = String(value ?? '');
+  const str = formatStaticValue(value, format);
 
   return (
     <div className='contents'>
       <Input.Root validationValence={status}>
-        {layout !== 'inline' && <FormFieldLabel error={error} readonly={readonly} label={label} />}
-        {layout === 'static' ? <p>{str}</p> : children ? children({ value }) : null}
-        {layout === 'full' && (
+        {layout !== 'inline' && <FormFieldLabel error={error} readonly={readonly} label={label} path={jsonPath} />}
+        {layout === 'static' ? (
+          <p className='truncate min-w-0' title={str}>
+            {str}
+          </p>
+        ) : children ? (
+          children({ value })
+        ) : null}
+        {layout === 'full' && error && (
           <Input.DescriptionAndValidation>
             <Input.Validation>{error}</Input.Validation>
           </Input.DescriptionAndValidation>
@@ -158,8 +213,8 @@ export class FormFieldErrorBoundary extends Component<FormFieldErrorBoundaryProp
   override render() {
     if (this.state.error) {
       return (
-        <div className='flex gap-2 border border-rose-fill font-mono text-sm'>
-          <span className='bg-rose-fill text-base-foreground px-1 font-thin'>ERROR</span>
+        <div className='flex gap-2 border border-rose-bg font-mono text-sm'>
+          <span className='bg-rose-bg text-base-fg px-1 font-thin'>ERROR</span>
           {String(this.props.path?.join('.'))}
         </div>
       );

package/src/components/Form/FormFieldSet.tsx

@@ -2,16 +2,18 @@
 // Copyright 2025 DXOS.org
 //
 
+import * as Option from 'effect/Option';
 import React, { useMemo } from 'react';
 
 import { type AnyProperties } from '@dxos/echo/internal';
-import { type SchemaProperty } from '@dxos/effect';
+import { createJsonPath, type SchemaProperty } from '@dxos/effect';
 
 import { type FormHandlerProps } from '../../hooks';
 import { getFormProperties } 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';
 
 const FORM_FIELDSET_NAME = 'Form.FieldSet';
 
@@ -19,6 +21,12 @@ export type FormFieldSetProps<T extends AnyProperties> = {
   label?: string;
   sort?: string[];
   exclude?: (props: SchemaProperty[]) => 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,
@@ -35,7 +43,7 @@ export type FormFieldSetProps<T extends AnyProperties> = {
     | 'createInitialValuePath'
     | 'createFieldMap'
     | 'db'
-    | 'useSchema'
+    | 'useType'
     | 'getOptions'
     | 'onCreate'
   >;
@@ -52,6 +60,7 @@ export const FormFieldSet = ({
   exclude,
   projection,
   layout,
+  layoutName = DEFAULT_LAYOUT_NAME,
   ...props
 }: FormFieldSetProps<any>) => {
   const values = useFormValues(FORM_FIELDSET_NAME, path);
@@ -60,9 +69,29 @@ export const FormFieldSet = ({
     return null;
   }
 
+  // If the schema carries a layout template, hand off to <Form.Layout/> which renders the DSL.
+  // Linear rendering still runs when no annotation is present, so existing call sites are unchanged.
+  const layouts = schema ? Option.getOrUndefined(FormLayoutAnnotation.get(schema)) : undefined;
+  if (layouts?.[layoutName] !== undefined && schema) {
+    return (
+      <>
+        {layout !== 'inline' && label && <FormFieldLabel label={label} path={createJsonPath(path ?? [])} asChild />}
+        <FormLayout
+          schema={schema}
+          name={layoutName}
+          path={path}
+          readonly={readonly}
+          layout={layout}
+          projection={projection}
+          {...props}
+        />
+      </>
+    );
+  }
+
   return (
     <>
-      {layout !== 'inline' && label && <FormFieldLabel label={label} asChild />}
+      {layout !== 'inline' && label && <FormFieldLabel label={label} path={createJsonPath(path ?? [])} asChild />}
       {properties.map((property) => {
         const name = property.name.toString();
         return (

package/src/components/Form/FormTooltipsContext.ts

@@ -0,0 +1,25 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { createContext, useContext } from 'react';
+
+/**
+ * A standalone context for the `tooltips` flag (Form.Root's only label
+ * decoration today: a JSON-path hover tooltip rendered by
+ * `FormFieldLabel`).
+ *
+ * Lives in its own module so that `FormFieldComponent.tsx` -- imported at
+ * the top of `Form.tsx` -- can read the flag without re-importing from
+ * `Form.tsx`. That round-trip used to create a circular module-eval
+ * dependency that intermittently hit a TDZ ("Cannot access 'FormFieldLabel'
+ * before initialization") in browser-mode storybook tests.
+ *
+ * Defaults to `true` both when `Form.Root` doesn't pass an explicit value
+ * AND when there is no enclosing `Form.Root` (e.g. `FormFieldWrapper`
+ * stories that render an input without a Form provider).
+ */
+export const FormTooltipsContext = createContext<boolean>(true);
+
+/** Returns whether the enclosing `Form.Root` has field tooltips enabled. */
+export const useFormTooltips = (): boolean => useContext(FormTooltipsContext);

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

@@ -0,0 +1,51 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { composeStories } from '@storybook/react';
+import { act, cleanup, screen, within } from '@testing-library/react';
+import { afterEach, describe, expect, test } from 'vitest';
+
+import * as stories from './FormLayout.stories';
+
+const { NestedLabel, NestedLabelStatic } = composeStories(stories);
+
+describe('FormLayout — nested fields', () => {
+  afterEach(async () => {
+    // Flush pending React scheduler work before teardown to prevent
+    // "window is not defined" errors from setImmediate callbacks firing after happy-dom cleanup.
+    await act(async () => {});
+    cleanup();
+  });
+
+  test('renders nested struct labels and dotted sub-fields', { timeout: 30_000 }, async () => {
+    await NestedLabel.run();
+
+    // `<field name="origin"/>` / `<field name="destination"/>` auto-convert to the
+    // place's `LabelAnnotation` label (the `name` field), rendered as read-only text.
+    // `findByText` retries while the async client provider initializes.
+    expect(await screen.findByText('John F. Kennedy Intl')).toBeInTheDocument();
+    expect(await screen.findByText('Charles de Gaulle')).toBeInTheDocument();
+
+    // `<field name="origin.code"/>` / `<field name="destination.code"/>` drill into the
+    // leaf sub-field, rendered as editable inputs holding the code.
+    expect(await screen.findByDisplayValue('JFK')).toBeInTheDocument();
+    expect(await screen.findByDisplayValue('CDG')).toBeInTheDocument();
+  });
+
+  test('static layout formats dates and renders labels as read-only text', { timeout: 30_000 }, async () => {
+    await NestedLabelStatic.run();
+
+    // Scope assertions to the form: the debug panel echoes the raw values JSON.
+    const form = await screen.findByRole('form');
+
+    // The depart date renders human-readable (contains the year) rather than the raw ISO
+    // string. Match `2026` and assert no ISO time fragment leaks through — timezone-robust.
+    expect(within(form).getByText(/2026/)).toBeInTheDocument();
+    expect(within(form).queryByText(/T\d\d:\d\d/)).toBeNull();
+
+    // Nested struct labels and dotted sub-fields render as static text (not inputs).
+    expect(within(form).getByText('John F. Kennedy Intl')).toBeInTheDocument();
+    expect(within(form).getByText('JFK')).toBeInTheDocument();
+  });
+});