@dxos/react-ui-form 0.8.4-main.ead640a → 0.8.4-main.effb148878

package/src/components/Form/FormFieldSet.tsx

@@ -0,0 +1,173 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Option from 'effect/Option';
+import React, { useMemo } from 'react';
+
+import { type AnyProperties } from '@dxos/echo/internal';
+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;
+  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,
+    | 'path'
+    | 'autoFocus'
+    | 'readonly'
+    | 'layout'
+    | 'projection'
+    | 'fieldMap'
+    | 'fieldProvider'
+    | 'createTypename'
+    | 'createOptionLabel'
+    | 'createOptionIcon'
+    | 'createInitialValuePath'
+    | 'createFieldMap'
+    | 'db'
+    | 'useType'
+    | 'getOptions'
+    | 'onCreate'
+  >;
+
+/**
+ * Renders a set of form fields derived from a schema object.
+ */
+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>
+        );
+      })}
+    </>
+  );
+};
+
+FormFieldSet.displayName = FORM_FIELDSET_NAME;
+
+type UseFormFieldSetPropertiesParams = Pick<FormFieldSetProps<any>, 'schema' | 'exclude' | 'projection' | 'sort'> & {
+  values: AnyProperties | undefined;
+  sort?: string[];
+};
+
+/**
+ * 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 [];
+    }
+
+    // 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);
+        }
+      }
+
+      // 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.tsx

@@ -0,0 +1,339 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { xml } from '@codemirror/lang-xml';
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Schema from 'effect/Schema';
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
+
+import { DXN, Format, Type } from '@dxos/echo';
+import { withClientProvider } from '@dxos/react-client/testing';
+import { Card, Tooltip, useThemeContext } from '@dxos/react-ui';
+import { Editor } from '@dxos/react-ui-editor';
+import { Syntax } from '@dxos/react-ui-syntax-highlighter';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { createBasicExtensions, createThemeExtensions } from '@dxos/ui-editor';
+import { mx } from '@dxos/ui-theme';
+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 { parseLayout } from './parser';
+
+/**
+ * Sample schema: a Flight booking carries airline, flight number, route, dates,
+ * cabin class. Without an annotation `<Form.FieldSet/>` renders one field per
+ * row (see the `Linear` story). The `FormLayoutAnnotation` on this schema
+ * arranges the same fields in a 2-column grid with selective spans.
+ */
+const Flight = Schema.Struct({
+  airline: Schema.optional(Schema.String.annotations({ title: 'Airline' })),
+  flightNumber: Schema.optional(Schema.String.annotations({ title: 'Flight #' })),
+  origin: Schema.optional(Schema.String.annotations({ title: 'From' })),
+  destination: Schema.optional(Schema.String.annotations({ title: 'To' })),
+  departAt: Schema.optional(Format.DateTime.annotations({ title: 'Depart' })),
+  arriveAt: Schema.optional(Format.DateTime.annotations({ title: 'Arrive' })),
+  cabin: Schema.optional(Schema.Literal('economy', 'premium', 'business', 'first').annotations({ title: 'Cabin' })),
+  notes: Schema.optional(Format.Text.annotations({ title: 'Notes' })),
+}).pipe(Type.makeObject(DXN.make('com.example.type.flight', '0.1.0')));
+
+export type Flight = Type.InstanceType<typeof Flight>;
+
+type FlightValues = Omit<Type.InstanceType<typeof Flight>, 'id'>;
+
+const flight = {
+  airline: 'Air France',
+  flightNumber: 'AF-1',
+  origin: 'JFK',
+  destination: 'CDG',
+  departAt: '2026-06-01T15:30:00.000Z',
+  arriveAt: '2026-06-02T09:30:00.000Z',
+  cabin: 'economy',
+} satisfies Partial<FlightValues>;
+
+const FLIGHT_LAYOUT = trim`
+  <grid cols="2">
+    <field name="airline"/>
+    <field name="flightNumber"/>
+    <field name="origin"/>
+    <field name="destination"/>
+    <field name="departAt"/>
+    <field name="arriveAt"/>
+    <field name="cabin" span="2"/>
+    <field name="notes" span="2"/>
+  </grid>
+`;
+
+/** Compact variant — single column, only the headline fields. */
+const FLIGHT_LAYOUT_COMPACT = trim`
+  <grid cols="1">
+    <field name="airline"/>
+    <field name="flightNumber"/>
+    <field name="departAt"/>
+  </grid>
+`;
+
+/**
+ * Same schema annotated with two named layouts. `Form.Layout name="…"`
+ * (or `Form.FieldSet layoutName="…"`) picks the variant; without a name
+ * the `'default'` entry is used.
+ */
+const AnnotatedFlight = Type.getSchema(Flight)
+  .annotations({})
+  .pipe(FormLayoutAnnotation.set({ default: FLIGHT_LAYOUT, compact: FLIGHT_LAYOUT_COMPACT }));
+
+type StoryProps = {
+  schema: Schema.Schema<any>;
+  template?: string;
+};
+
+const DefaultStory = ({ schema, template }: StoryProps) => {
+  const [values, setValues] = useState<Partial<FlightValues>>(flight);
+
+  const handleSave = useCallback<NonNullable<FormRootProps<any>['onSave']>>((next) => {
+    setValues(next as Partial<FlightValues>);
+  }, []);
+
+  return (
+    <Tooltip.Provider>
+      <TestLayout json={{ values }}>
+        <Form.Root schema={schema} defaultValues={values} onSave={handleSave} autoSave>
+          <Form.Viewport>
+            <Form.Content>
+              {template !== undefined ? <Form.Layout schema={schema} template={template} /> : <Form.FieldSet />}
+            </Form.Content>
+          </Form.Viewport>
+        </Form.Root>
+      </TestLayout>
+    </Tooltip.Provider>
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-form/FormLayout',
+  render: DefaultStory,
+  decorators: [
+    withTheme(),
+    withLayout({ layout: 'fullscreen' }),
+    withClientProvider({ createIdentity: true, createSpace: true }),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<StoryProps>;
+
+export default meta;
+
+type Story = StoryObj<StoryProps>;
+
+/** Baseline: no annotation, no override — `Form.FieldSet` renders linearly (one field per row). */
+export const Linear: Story = {
+  args: {
+    schema: omitId(Type.getSchema(Flight)),
+  },
+};
+
+/** `Form.Layout` invoked directly with a `template` prop, bypassing any annotation. */
+export const TemplateProp: Story = {
+  args: {
+    schema: omitId(Type.getSchema(Flight)),
+    template: FLIGHT_LAYOUT,
+  },
+};
+
+/** Schema carries `FormLayoutAnnotation`; `Form.FieldSet` auto-detects and delegates. */
+export const SchemaAnnotation: Story = {
+  args: {
+    schema: omitId(AnnotatedFlight),
+  },
+};
+
+/**
+ * Same annotated schema, but the story switches between the two named
+ * layouts (`default` and `compact`) via a radio above the form.
+ */
+const NamedAnnotationStory = () => {
+  const schema = useMemo(() => omitId(AnnotatedFlight) as unknown as Schema.Schema<any>, []);
+  const [layoutName, setLayoutName] = useState<'default' | 'compact'>('default');
+  const [values, setValues] = useState<Partial<FlightValues>>(flight);
+
+  const handleSave = useCallback<NonNullable<FormRootProps<any>['onSave']>>((next) => {
+    setValues(next as Flight);
+  }, []);
+
+  return (
+    <Tooltip.Provider>
+      <TestLayout json={{ layoutName, values }}>
+        <div className='flex flex-col gap-2'>
+          <div className='flex gap-2 text-sm'>
+            {(['default', 'compact'] as const).map((name) => (
+              <label key={name} className='flex items-center gap-1'>
+                <input type='radio' name='layout' checked={layoutName === name} onChange={() => setLayoutName(name)} />
+                {name}
+              </label>
+            ))}
+          </div>
+          <Form.Root schema={schema} defaultValues={values} onSave={handleSave} autoSave>
+            <Form.Viewport>
+              <Form.Content>
+                <Form.FieldSet layoutName={layoutName} />
+              </Form.Content>
+            </Form.Viewport>
+          </Form.Root>
+        </div>
+      </TestLayout>
+    </Tooltip.Provider>
+  );
+};
+
+export const NamedAnnotation: Story = {
+  render: () => <NamedAnnotationStory />,
+};
+
+/**
+ * Live playground: the layout template lives in a code editor on the right.
+ * The form on the left re-renders as you type. If the template fails to
+ * parse, the previous valid layout stays on screen and an error banner
+ * surfaces under the editor.
+ */
+type PlaygroundStoryProps = {
+  /** Wrap the rendered form in `Card.Root` / `Card.Body` chrome. */
+  card?: boolean;
+};
+
+const PlaygroundStory = ({ card = false }: PlaygroundStoryProps) => {
+  const schema = useMemo(() => omitId(Type.getSchema(Flight)) as unknown as Schema.Schema<any>, []);
+  const [template, setTemplate] = useState(FLIGHT_LAYOUT);
+  const [lastValid, setLastValid] = useState(FLIGHT_LAYOUT);
+  const [error, setError] = useState<string | undefined>();
+
+  useEffect(() => {
+    try {
+      parseLayout(template);
+      setLastValid(template);
+      setError(undefined);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    }
+  }, [template]);
+
+  const [values, setValues] = useState<Partial<FlightValues>>(flight);
+
+  const handleSave = useCallback<NonNullable<FormRootProps<any>['onSave']>>((next) => {
+    setValues(next as Partial<FlightValues>);
+  }, []);
+
+  const { themeMode } = useThemeContext();
+  const extensions = useMemo(
+    () => [
+      xml(),
+      createBasicExtensions({ placeholder: 'Edit layout DSL…' }),
+      createThemeExtensions({ themeMode, syntaxHighlighting: true }),
+    ],
+    [themeMode],
+  );
+
+  const renderForm = (readonly = false) => (
+    <Form.Root
+      schema={schema}
+      defaultValues={values}
+      layout={readonly ? 'static' : 'full'}
+      readonly={readonly}
+      autoSave
+      onSave={handleSave}
+    >
+      <Form.Viewport>
+        <Form.Content>
+          <Form.Layout schema={schema} template={lastValid} />
+        </Form.Content>
+      </Form.Viewport>
+    </Form.Root>
+  );
+
+  return (
+    <Tooltip.Provider>
+      <div
+        className={mx(
+          'dx-container grid grid-rows-1 p-4 gap-4 overflow-hidden',
+          card ? 'grid-cols-[var(--spacing-card-min-width)_var(--spacing-card-min-width)_1fr]' : 'grid-cols-2',
+        )}
+      >
+        {card ? (
+          <>
+            <div>
+              <Card.Root fullWidth>
+                <Card.Header>
+                  <Card.DragHandle />
+                  <Card.Title>Read-only</Card.Title>
+                  <Card.ActionIconButton action='close' onClick={() => console.log('close')} />
+                </Card.Header>
+                <Card.Body>{renderForm(true)}</Card.Body>
+              </Card.Root>
+            </div>
+            <div>
+              <Card.Root fullWidth>
+                <Card.Header>
+                  <Card.DragHandle />
+                  <Card.Title>Editable</Card.Title>
+                  <Card.ActionIconButton action='close' onClick={() => console.log('close')} />
+                </Card.Header>
+                <Card.Body>{renderForm(false)}</Card.Body>
+              </Card.Root>
+            </div>
+          </>
+        ) : (
+          <TestPanel>{renderForm(false)}</TestPanel>
+        )}
+        <div className='grid grid-rows-3 gap-4 overflow-hidden'>
+          <TestPanel>
+            <div className='flex flex-col h-full overflow-hidden'>
+              <Editor.Root>
+                <Editor.View
+                  classNames='flex-1 overflow-auto font-mono text-sm p-2'
+                  extensions={extensions}
+                  value={template}
+                  onChange={setTemplate}
+                />
+              </Editor.Root>
+              {error && <div className='border-t border-separator p-2 text-sm text-error-text font-mono'>{error}</div>}
+            </div>
+          </TestPanel>
+          <TestPanel>
+            <Syntax.Root data={schema.ast}>
+              <Syntax.Content>
+                <Syntax.Filter />
+                <Syntax.Viewport>
+                  <Syntax.Code testId='schema' classNames='text-sm' />
+                </Syntax.Viewport>
+              </Syntax.Content>
+            </Syntax.Root>
+          </TestPanel>
+          <TestPanel>
+            <Syntax.Root data={values}>
+              <Syntax.Content>
+                <Syntax.Filter />
+                <Syntax.Viewport>
+                  <Syntax.Code testId='data' classNames='text-sm' />
+                </Syntax.Viewport>
+              </Syntax.Content>
+            </Syntax.Root>
+          </TestPanel>
+        </div>
+      </div>
+    </Tooltip.Provider>
+  );
+};
+
+export const FormPlayground: Story = {
+  render: () => <PlaygroundStory />,
+};
+
+/** Same playground, but the form is rendered inside a `Card.Root` / `Card.Body`. */
+export const CardPlayground: Story = {
+  render: () => <PlaygroundStory card />,
+};

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

@@ -0,0 +1,123 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Option from 'effect/Option';
+import type * as Schema from 'effect/Schema';
+import React, { Fragment, useMemo } from 'react';
+
+import { type AnyProperties } from '@dxos/echo/internal';
+import { type SchemaProperty } from '@dxos/effect';
+
+import { getFormProperties } from '../../../util';
+import { FormField, type FormFieldProps } from '../FormField';
+import { FormFieldErrorBoundary } from '../FormFieldComponent';
+import { DEFAULT_LAYOUT_NAME, FormLayoutAnnotation } from './annotation';
+import { LayoutParseError, type LayoutNode, parseLayout } from './parser';
+
+const FORM_LAYOUT_NAME = 'Form.Layout';
+
+export type FormLayoutProps = {
+  /**
+   * Template string in the FormLayout DSL (`<grid cols=…><field name=…/></grid>`).
+   * If omitted, the layout is read from the schema's `FormLayoutAnnotation` —
+   * the entry named by `name` (default: `'default'`).
+   */
+  template?: string;
+  /**
+   * Picks a named layout out of `FormLayoutAnnotation`'s map when no
+   * explicit `template` is supplied. Defaults to `'default'`.
+   */
+  name?: string;
+} & Pick<FormFieldSetSubset, 'schema' | 'path' | 'readonly' | 'layout' | 'projection' | 'fieldMap' | 'fieldProvider'>;
+
+type FormFieldSetSubset = Pick<
+  FormFieldProps,
+  'path' | 'readonly' | 'layout' | 'projection' | 'fieldMap' | 'fieldProvider'
+> & {
+  schema: Schema.Schema<AnyProperties>;
+};
+
+/**
+ * Lays out schema fields according to a `FormLayout` DSL template. The template
+ * is either passed via the `template` prop or read from the schema's
+ * `FormLayoutAnnotation`. Fields not referenced in the template are hidden —
+ * the template controls exactly what renders.
+ */
+export const FormLayout = ({
+  schema,
+  template,
+  name = DEFAULT_LAYOUT_NAME,
+  path,
+  readonly,
+  layout,
+  projection,
+  ...props
+}: FormLayoutProps) => {
+  const annotated = Option.getOrUndefined(FormLayoutAnnotation.get(schema));
+  const source = template ?? annotated?.[name];
+  if (source === undefined) {
+    throw new LayoutParseError(
+      annotated
+        ? `no layout named "${name}" on schema (available: ${Object.keys(annotated).join(', ') || '∅'})`
+        : `no template provided and schema has no FormLayoutAnnotation`,
+    );
+  }
+
+  const tree = useMemo(() => parseLayout(source), [source]);
+  const properties = useMemo(() => {
+    const map = new Map<string, SchemaProperty>();
+    for (const property of getFormProperties(schema.ast)) {
+      map.set(String(property.name), property);
+    }
+    return map;
+  }, [schema]);
+
+  return (
+    <RenderNode
+      node={tree}
+      properties={properties}
+      basePath={path ?? []}
+      readonly={readonly}
+      layout={layout}
+      projection={projection}
+      {...props}
+    />
+  );
+};
+
+FormLayout.displayName = FORM_LAYOUT_NAME;
+
+type RenderNodeProps = Omit<FormLayoutProps, 'schema' | 'template' | 'path'> & {
+  node: LayoutNode;
+  properties: Map<string, SchemaProperty>;
+  basePath: (string | number)[];
+};
+
+const RenderNode = ({ node, properties, basePath, ...props }: RenderNodeProps) => {
+  if (node.kind === 'grid') {
+    return (
+      <div className='grid gap-x-form-gap' style={{ gridTemplateColumns: `repeat(${node.cols}, minmax(0, 1fr))` }}>
+        {node.children.map((child, index) => (
+          <Fragment key={index}>
+            <RenderNode node={child} properties={properties} basePath={basePath} {...props} />
+          </Fragment>
+        ))}
+      </div>
+    );
+  }
+
+  const property = properties.get(node.name);
+  if (!property) {
+    throw new LayoutParseError(`field "${node.name}" not found on schema`);
+  }
+  const path = [...basePath, node.name];
+  const span = node.span ? { gridColumn: `span ${node.span} / span ${node.span}` } : undefined;
+  return (
+    <div className='min-w-0' style={span}>
+      <FormFieldErrorBoundary path={path}>
+        <FormField type={property.type} name={node.name} path={path} {...props} />
+      </FormFieldErrorBoundary>
+    </div>
+  );
+};

package/src/components/Form/Layout/annotation.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { createAnnotationHelper } from '@dxos/echo/internal';
+
+/**
+ * Annotation carrying one or more named `FormLayout` DSL templates that
+ * control how `Form.FieldSet` / `Form.Layout` arrange a schema's fields.
+ * Callers select a variant via the `name` prop; the implicit name is
+ * `DEFAULT_LAYOUT_NAME` (`'default'`).
+ *
+ * Templates use a minimal XML grammar — see `parser.ts`. Example:
+ *
+ *   FormLayoutAnnotation.set({
+ *     default: `
+ *       <grid cols="2">
+ *         <field name="origin"/>
+ *         <field name="destination"/>
+ *         <field name="provider" span="2"/>
+ *       </grid>
+ *     `,
+ *     card: `
+ *       <grid cols="1">
+ *         <field name="provider"/>
+ *         <field name="number"/>
+ *       </grid>
+ *     `,
+ *   })
+ */
+export const FormLayoutAnnotationId = Symbol.for('@dxos/react-ui-form/annotation/Layout');
+
+export type FormLayoutMap = Record<string, string>;
+
+export const FormLayoutAnnotation = createAnnotationHelper<FormLayoutMap>(FormLayoutAnnotationId);
+
+/** Name used when no explicit variant is requested. */
+export const DEFAULT_LAYOUT_NAME = 'default';