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

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,11 +14,13 @@ import React, {
   type ReactNode,
 } from 'react';
 
-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.
@@ -31,7 +34,6 @@ export type FormFieldStateProps<T = any> = {
 
 /**
  * Presentation mode.
- *
  * - full: Show label, control, and status.
  * - compact: Show label and control.
  * - inline: Control only.
@@ -44,27 +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;
 } & 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
@@ -73,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 role='none' className='flex items-center justify-between'>
-      <Label className={inputTextLabel}>{label}</Label>
+    <div className='flex items-center justify-between'>
+      {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' />
@@ -97,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();
@@ -111,14 +162,20 @@ export const FormFieldWrapper = <T,>(props: FormFieldWrapperProps<T>) => {
     return null;
   }
 
-  const str = String(value ?? '');
+  const str = formatStaticValue(value, format);
 
   return (
-    <div role='none' className='contents'>
+    <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>
@@ -156,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-surface-text 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,26 +2,31 @@
 // Copyright 2025 DXOS.org
 //
 
-import React, { forwardRef, useMemo } from 'react';
+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 { mx } from '@dxos/ui-theme';
-import { isTruthy } from '@dxos/util';
+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';
 
 export type FormFieldSetProps<T extends AnyProperties> = {
   label?: string;
-  exclude?: (props: SchemaProperty[]) => SchemaProperty[];
   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,
@@ -32,11 +37,13 @@ export type FormFieldSetProps<T extends AnyProperties> = {
     | 'projection'
     | 'fieldMap'
     | 'fieldProvider'
+    | 'createTypename'
     | 'createOptionLabel'
     | 'createOptionIcon'
     | 'createInitialValuePath'
+    | 'createFieldMap'
     | 'db'
-    | 'schemaHook'
+    | 'useType'
     | 'getOptions'
     | 'onCreate'
   >;
@@ -44,80 +51,123 @@ export type FormFieldSetProps<T extends AnyProperties> = {
 /**
  * Renders a set of form fields derived from a schema object.
  */
-export const FormFieldSet = forwardRef<HTMLDivElement, FormFieldSetProps<any>>(
-  ({ label, schema, readonly, path, exclude, sort, projection, layout, ...props }, forwardRef) => {
-    const values = useFormValues(FORM_FIELDSET_NAME, path);
-
-    // TODO(burdon): Updates on every value change.
-    //  Remove values dep if can remove from getSchemaProperties.
-    const properties = useMemo(() => {
-      if (!schema) {
-        return [];
-      }
-
-      // TODO(wittjosiah): Reconcile FormInputAnnotation with projection hidden properties & exclude function.
-      const props = getFormProperties(schema.ast);
-
-      // Use projection-based field management when view and projection are available.
-      if (projection) {
-        const fieldProjections = projection.getFieldProjections();
-        const hiddenProperties = new Set(projection.getHiddenProperties());
-
-        // Filter properties to only include visible ones and order by projection.
-        const visibleProps = props.filter((prop) => !hiddenProperties.has(prop.name.toString()));
-        const orderedProps: SchemaProperty[] = [];
-
-        // Add properties in projection field order.
-        for (const fieldProjection of fieldProjections) {
-          const fieldPath = String(fieldProjection.field.path);
-          const prop = visibleProps.find((p) => p.name === fieldPath);
-          if (prop) {
-            orderedProps.push(prop);
-          }
-        }
+export const FormFieldSet = ({
+  label,
+  schema,
+  readonly,
+  path,
+  sort,
+  exclude,
+  projection,
+  layout,
+  layoutName = DEFAULT_LAYOUT_NAME,
+  ...props
+}: FormFieldSetProps<any>) => {
+  const values = useFormValues(FORM_FIELDSET_NAME, path);
+  const properties = useFormFieldSetProperties({ schema, values, exclude, sort, projection });
+  if ((readonly || layout === 'static') && values == null) {
+    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} path={createJsonPath(path ?? [])} asChild />}
+      {properties.map((property) => {
+        const name = property.name.toString();
+        return (
+          <FormFieldErrorBoundary key={name} path={[...(path ?? []), name]}>
+            <FormField
+              type={property.type}
+              name={name}
+              path={[...(path ?? []), name]}
+              readonly={readonly}
+              layout={layout}
+              projection={projection}
+              {...props}
+            />
+          </FormFieldErrorBoundary>
+        );
+      })}
+    </>
+  );
+};
 
-        // Add any remaining properties not in projection.
-        const projectionPaths = new Set(fieldProjections.map((projection) => String(projection.field.path)));
-        const remainingProps = visibleProps.filter((prop) => !projectionPaths.has(prop.name.toString()));
-        orderedProps.push(...remainingProps);
-        return orderedProps;
-      }
+FormFieldSet.displayName = FORM_FIELDSET_NAME;
 
-      // Fallback to legacy filter/sort behavior.
-      const filtered = exclude ? exclude(props) : props;
-      return sort
-        ? filtered.sort(({ name: a }, { name: b }) => sort.indexOf(a.toString()) - sort.indexOf(b.toString()))
-        : filtered;
-    }, [schema, values, exclude, sort, projection?.fields]);
+type UseFormFieldSetPropertiesParams = Pick<FormFieldSetProps<any>, 'schema' | 'exclude' | 'projection' | 'sort'> & {
+  values: AnyProperties | undefined;
+  sort?: string[];
+};
 
-    if ((readonly || layout === 'static') && values == null) {
-      return null;
+/**
+ * Resolves ordered schema properties for a field set (projection order, exclude, or sort).
+ */
+const useFormFieldSetProperties = ({
+  schema,
+  exclude,
+  projection,
+  values,
+  sort,
+}: UseFormFieldSetPropertiesParams): SchemaProperty[] => {
+  // TODO(burdon): Updates on every value change.
+  //  Remove values dep if can remove from getSchemaProperties.
+  return useMemo(() => {
+    if (!schema) {
+      return [];
     }
 
-    return (
-      <div role='form' className={mx('w-full', layout === 'inline' && 'flex flex-col gap-2')} ref={forwardRef}>
-        {layout !== 'inline' && label && <FormFieldLabel label={label} asChild />}
-        {properties
-          .map((property) => {
-            const name = property.name.toString();
-            return (
-              <FormFieldErrorBoundary key={name} path={[...(path ?? []), name]}>
-                <FormField
-                  type={property.type}
-                  name={name}
-                  path={[...(path ?? []), name]}
-                  readonly={readonly}
-                  layout={layout}
-                  projection={projection}
-                  {...props}
-                />
-              </FormFieldErrorBoundary>
-            );
-          })
-          .filter(isTruthy)}
-      </div>
-    );
-  },
-);
+    // TODO(wittjosiah): Reconcile FormInputAnnotation with projection hidden properties & exclude function.
+    const schemaProps = getFormProperties(schema.ast);
+    const filteredProps = exclude ? exclude(schemaProps) : schemaProps;
+
+    // Use projection-based field management when view and projection are available.
+    if (projection) {
+      const fieldProjections = projection.getFieldProjections();
+      const hiddenProperties = new Set(projection.getHiddenProperties());
+
+      // Filter properties to only include visible ones and order by projection.
+      const visibleProps = filteredProps.filter((prop) => !hiddenProperties.has(prop.name.toString()));
+      const orderedProps: SchemaProperty[] = [];
+
+      // Add properties in projection field order.
+      for (const fieldProjection of fieldProjections) {
+        const fieldPath = String(fieldProjection.field.path);
+        const prop = visibleProps.find((prop) => prop.name === fieldPath);
+        if (prop) {
+          orderedProps.push(prop);
+        }
+      }
 
-FormFieldSet.displayName = FORM_FIELDSET_NAME;
+      // Add any remaining properties not in projection.
+      const projectionPaths = new Set(fieldProjections.map((projection) => String(projection.field.path)));
+      const remainingProps = visibleProps.filter((prop) => !projectionPaths.has(prop.name.toString()));
+      orderedProps.push(...remainingProps);
+      return orderedProps;
+    }
+
+    // Fallback to legacy filter/sort behavior.
+    return sort
+      ? [...filteredProps].sort(({ name: a }, { name: b }) => sort.indexOf(a.toString()) - sort.indexOf(b.toString()))
+      : filteredProps;
+  }, [schema, values, exclude, sort, projection]);
+};

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();
+  });
+});