@dxos/react-ui-form 0.8.4-main.fffef41 → 0.8.4-staging.60fe92afc8

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

@@ -0,0 +1,251 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+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, { Fragment, useMemo } from 'react';
+
+import { Annotation } from '@dxos/echo';
+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';
+
+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.
+ *
+ * A `<field name=…/>` resolves against the schema:
+ * - A dotted name (`origin.code`) drills into a nested struct and renders the leaf field.
+ * - A name that resolves to a nested struct carrying a `LabelAnnotation` auto-converts
+ *   to the struct's computed label, rendered as a single read-only text (rather than
+ *   expanding the struct's sub-fields).
+ */
+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]);
+
+  return (
+    <RenderNode
+      node={tree}
+      schema={schema}
+      basePath={path ?? []}
+      readonly={readonly}
+      layout={layout}
+      projection={projection}
+      {...props}
+    />
+  );
+};
+
+FormLayout.displayName = FORM_LAYOUT_NAME;
+
+type RenderNodeProps = Omit<FormLayoutProps, 'template' | 'path'> & {
+  node: LayoutNode;
+  basePath: (string | number)[];
+};
+
+const RenderNode = ({ node, schema, 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} schema={schema} basePath={basePath} {...props} />
+          </Fragment>
+        ))}
+      </div>
+    );
+  }
+
+  const resolved = resolveLayoutField(schema, node.name);
+  if (!resolved) {
+    throw new LayoutParseError(`field "${node.name}" not found on schema`);
+  }
+
+  const { type, segments, leafName, title, labelType } = resolved;
+  const path = [...basePath, ...segments];
+  const span = node.span ? { gridColumn: `span ${node.span} / span ${node.span}` } : undefined;
+
+  return (
+    <div className='min-w-0' style={span}>
+      <FormFieldErrorBoundary path={path}>
+        {labelType ? (
+          <LabelField
+            schema={Schema.make(labelType)}
+            label={title ?? String.capitalize(leafName)}
+            path={path}
+            layout={props.layout}
+          />
+        ) : (
+          <FormField type={type} name={leafName} path={path} {...props} />
+        )}
+      </FormFieldErrorBoundary>
+    </div>
+  );
+};
+
+export type ResolvedLayoutField = {
+  /** Resolved leaf AST node for the field. */
+  type: SchemaAST.AST;
+  /** Path segments (dotted names split on `.`). */
+  segments: string[];
+  /** Last path segment; used to derive the field label when there is no `title` annotation. */
+  leafName: string;
+  /** Resolved `title` annotation for the field, if any. */
+  title?: string;
+  /**
+   * Set when the field resolves to a nested struct carrying a `LabelAnnotation` —
+   * the type literal whose computed label should render in place of the struct's
+   * sub-fields. Undefined for ordinary (non-auto-labelled) fields.
+   */
+  labelType?: SchemaAST.AST;
+};
+
+/**
+ * Walks a dotted path of property names through nested struct ASTs, returning the
+ * leaf `PropertySignature` (or `undefined` if any segment is missing).
+ */
+const resolvePropertySignature = (ast: SchemaAST.AST, segments: string[]): SchemaAST.PropertySignature | undefined => {
+  let node: SchemaAST.AST = ast;
+  for (let index = 0; index < segments.length; index++) {
+    const typeLiteral = SchemaEx.findNode(node, SchemaAST.isTypeLiteral);
+    if (!typeLiteral) {
+      return undefined;
+    }
+    const prop = SchemaAST.getPropertySignatures(typeLiteral).find(
+      (p) => globalThis.String(p.name) === segments[index],
+    );
+    if (!prop) {
+      return undefined;
+    }
+    if (index === segments.length - 1) {
+      return prop;
+    }
+    node = prop.type;
+  }
+
+  return undefined;
+};
+
+/**
+ * Resolves a (possibly dotted) layout field name against a schema.
+ * - `origin.code` drills through nested structs to the leaf field.
+ * - A name resolving to a nested struct with a `LabelAnnotation` is flagged via
+ *   `labelType` so the layout can auto-convert it to a single read-only label.
+ * Returns `undefined` when the name does not resolve to a property.
+ */
+export const resolveLayoutField = (schema: Schema.Schema<any>, name: string): ResolvedLayoutField | undefined => {
+  const segments = name.split('.');
+  const prop = resolvePropertySignature(schema.ast, segments);
+  if (!prop) {
+    return undefined;
+  }
+
+  // Normalized leaf type (optional unwrapped, refinements stripped, signature-level
+  // annotations merged) — matches how `getProperties` feeds `FormField`.
+  const { type: baseType } = SchemaEx.getBaseType(prop);
+  const type =
+    prop.annotations && Reflect.ownKeys(prop.annotations).length > 0
+      ? ({ ...baseType, annotations: { ...baseType.annotations, ...prop.annotations } } as SchemaAST.AST)
+      : baseType;
+
+  const title = SchemaEx.getAnnotation<string>(SchemaAST.TitleAnnotationId)(type);
+
+  // Label detection reads the *raw* property type: `SchemaEx.getBaseType`'s `encodedBoundAST`
+  // strips annotations from non-keyword inner types (e.g. nested structs), which would
+  // drop the `LabelAnnotation` we rely on here.
+  const labelType = SchemaEx.findNode(prop.type, SchemaAST.isTypeLiteral);
+  const labelled = labelType != null && Option.isSome(Annotation.LabelAnnotation.getFromAst(labelType));
+
+  return {
+    type,
+    segments,
+    leafName: segments[segments.length - 1],
+    title,
+    labelType: labelled ? labelType : undefined,
+  };
+};
+
+type LabelFieldProps = {
+  schema: Schema.Schema<any>;
+  label: string;
+  path: (string | number)[];
+  layout?: Presentation;
+};
+
+/**
+ * Renders a nested struct value as its computed label (via `LabelAnnotation`),
+ * as a single read-only text. Empty values are omitted, mirroring the static
+ * presentation of regular fields.
+ */
+const LabelField = ({ schema, label, path, layout }: LabelFieldProps) => {
+  const { getValue } = useFormFieldState(FORM_LAYOUT_NAME, path);
+  const value = getValue();
+  const text = value == null ? undefined : Annotation.getLabelWithSchema(schema, value);
+  if (text == null || text.trim().length === 0) {
+    return null;
+  }
+
+  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>
+  );
+};

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';

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

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

package/src/components/Form/Layout/parser.test.ts

@@ -0,0 +1,120 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { LayoutParseError, parseLayout } from './parser';
+
+describe('parseLayout', () => {
+  test('grid with two fields', ({ expect }) => {
+    const tree = parseLayout(`<grid cols="2"><field name="a"/><field name="b"/></grid>`);
+    expect(tree).toEqual({
+      kind: 'grid',
+      cols: 2,
+      children: [
+        { kind: 'field', name: 'a', span: undefined },
+        { kind: 'field', name: 'b', span: undefined },
+      ],
+    });
+  });
+
+  test('field with span attribute', ({ expect }) => {
+    const tree = parseLayout(`<grid cols="3"><field name="a" span="2"/><field name="b"/></grid>`);
+    expect(tree).toEqual({
+      kind: 'grid',
+      cols: 3,
+      children: [
+        { kind: 'field', name: 'a', span: 2 },
+        { kind: 'field', name: 'b', span: undefined },
+      ],
+    });
+  });
+
+  test('dotted field name', ({ expect }) => {
+    const tree = parseLayout(`<grid cols="1"><field name="details.airline"/></grid>`);
+    expect(tree).toEqual({
+      kind: 'grid',
+      cols: 1,
+      children: [{ kind: 'field', name: 'details.airline', span: undefined }],
+    });
+  });
+
+  test('nested grids', ({ expect }) => {
+    const tree = parseLayout(`
+      <grid cols="2">
+        <field name="a"/>
+        <grid cols="2">
+          <field name="b"/>
+          <field name="c"/>
+        </grid>
+      </grid>
+    `);
+    expect(tree.kind).toBe('grid');
+    if (tree.kind !== 'grid') {
+      return;
+    }
+    expect(tree.cols).toBe(2);
+    expect(tree.children).toHaveLength(2);
+    const inner = tree.children[1];
+    expect(inner.kind).toBe('grid');
+    if (inner.kind === 'grid') {
+      expect(inner.cols).toBe(2);
+      expect(inner.children).toHaveLength(2);
+    }
+  });
+
+  test('accepts single-quoted and unquoted attributes', ({ expect }) => {
+    const tree = parseLayout(`<grid cols=2><field name='x' span=3/></grid>`);
+    expect(tree).toEqual({
+      kind: 'grid',
+      cols: 2,
+      children: [{ kind: 'field', name: 'x', span: 3 }],
+    });
+  });
+
+  test('ignores whitespace between tags', ({ expect }) => {
+    const tree = parseLayout(`
+      <grid cols="1">
+        <field name="x"/>
+      </grid>
+    `);
+    expect(tree.kind).toBe('grid');
+  });
+
+  test('empty template throws', ({ expect }) => {
+    expect(() => parseLayout('')).toThrow(LayoutParseError);
+  });
+
+  test('text content between tags throws', ({ expect }) => {
+    expect(() => parseLayout(`<grid cols="1">hello<field name="x"/></grid>`)).toThrow(/unexpected text content/);
+  });
+
+  test('missing required cols attribute throws', ({ expect }) => {
+    expect(() => parseLayout(`<grid><field name="x"/></grid>`)).toThrow(/missing required attribute "cols"/);
+  });
+
+  test('missing required field name throws', ({ expect }) => {
+    expect(() => parseLayout(`<grid cols="1"><field/></grid>`)).toThrow(/missing required attribute "name"/);
+  });
+
+  test('non-integer cols throws', ({ expect }) => {
+    expect(() => parseLayout(`<grid cols="auto"><field name="x"/></grid>`)).toThrow(/expects an integer/);
+  });
+
+  test('non-grid root throws', ({ expect }) => {
+    expect(() => parseLayout(`<field name="x"/>`)).toThrow(/root element must be <grid>/);
+  });
+
+  test('unclosed grid throws', ({ expect }) => {
+    expect(() => parseLayout(`<grid cols="1"><field name="x"/>`)).toThrow(/<grid> not closed/);
+  });
+
+  test('non-self-closing field throws', ({ expect }) => {
+    expect(() => parseLayout(`<grid cols="1"><field name="x"></field></grid>`)).toThrow(/must be self-closing/);
+  });
+
+  test('unknown element throws', ({ expect }) => {
+    expect(() => parseLayout(`<grid cols="1"><row name="x"/></grid>`)).toThrow(/unknown element <row>/);
+  });
+});

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

@@ -0,0 +1,167 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+/**
+ * Minimal XML-style DSL for laying out schema fields in a grid.
+ *
+ * Grammar:
+ *   <grid cols="N">  ...children...  </grid>
+ *   <field name="x" span="N"/>
+ *
+ * - Attributes accept `"…"`, `'…'`, or unquoted integers.
+ * - Whitespace between tags is ignored. Text content (between tags) is forbidden.
+ * - Self-closing form (`<field … />`) is required for `field`; `grid` must use a closing tag.
+ *
+ * The parser is hand-rolled (no HTML parser) because the grammar is tiny.
+ */
+
+/** Node type for the parsed layout tree. */
+export type LayoutNode =
+  | { readonly kind: 'grid'; readonly cols: number; readonly children: readonly LayoutNode[] }
+  | { readonly kind: 'field'; readonly name: string; readonly span?: number };
+
+export class LayoutParseError extends Error {
+  readonly _tag = 'LayoutParseError';
+  constructor(
+    message: string,
+    readonly position?: number,
+  ) {
+    super(position !== undefined ? `${message} (at position ${position})` : message);
+  }
+}
+
+const TAG_RE = /<\s*(\/?)\s*(\w+)([^>]*?)(\/?)\s*>/g;
+const ATTR_RE = /([\w-]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|(\d+))/g;
+
+type Token =
+  | { type: 'open'; name: string; attrs: Record<string, string>; selfClosing: boolean; position: number }
+  | { type: 'close'; name: string; position: number };
+
+const parseAttrs = (raw: string): Record<string, string> => {
+  const attrs: Record<string, string> = {};
+  ATTR_RE.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = ATTR_RE.exec(raw)) !== null) {
+    const [, key, doubleQuoted, singleQuoted, bare] = match;
+    attrs[key] = doubleQuoted ?? singleQuoted ?? bare;
+  }
+  return attrs;
+};
+
+const tokenize = (input: string): Token[] => {
+  const tokens: Token[] = [];
+  TAG_RE.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  let cursor = 0;
+  while ((match = TAG_RE.exec(input)) !== null) {
+    // Validate that any text between the previous tag and this one is whitespace-only.
+    const between = input.slice(cursor, match.index);
+    if (between.trim().length > 0) {
+      throw new LayoutParseError(`unexpected text content: ${JSON.stringify(between.trim())}`, cursor);
+    }
+    const [, slash, name, attrsRaw, selfSlash] = match;
+    if (slash) {
+      tokens.push({ type: 'close', name, position: match.index });
+    } else {
+      tokens.push({
+        type: 'open',
+        name,
+        attrs: parseAttrs(attrsRaw),
+        selfClosing: selfSlash === '/',
+        position: match.index,
+      });
+    }
+    cursor = match.index + match[0].length;
+  }
+  // Any trailing text after the last tag must also be whitespace.
+  const trailing = input.slice(cursor);
+  if (trailing.trim().length > 0) {
+    throw new LayoutParseError(`unexpected text content: ${JSON.stringify(trailing.trim())}`, cursor);
+  }
+  return tokens;
+};
+
+const requireAttr = (attrs: Record<string, string>, key: string, tag: string, position: number): string => {
+  const value = attrs[key];
+  if (value === undefined) {
+    throw new LayoutParseError(`<${tag}> missing required attribute "${key}"`, position);
+  }
+  return value;
+};
+
+const parseInteger = (value: string, attr: string, tag: string, position: number): number => {
+  if (!/^\d+$/.test(value)) {
+    throw new LayoutParseError(
+      `<${tag}> attribute "${attr}" expects an integer, got ${JSON.stringify(value)}`,
+      position,
+    );
+  }
+  return Number.parseInt(value, 10);
+};
+
+/** Parses a layout template string into a single root node. The root must be `<grid>`. */
+export const parseLayout = (template: string): LayoutNode => {
+  const tokens = tokenize(template);
+  if (tokens.length === 0) {
+    throw new LayoutParseError('empty template');
+  }
+
+  let index = 0;
+
+  const parseNode = (): LayoutNode => {
+    const token = tokens[index];
+    if (!token || token.type !== 'open') {
+      throw new LayoutParseError(`expected an opening tag, got ${JSON.stringify(token)}`, token?.position);
+    }
+
+    if (token.name === 'field') {
+      if (!token.selfClosing) {
+        throw new LayoutParseError('<field> must be self-closing (e.g. <field name="x"/>)', token.position);
+      }
+      const name = requireAttr(token.attrs, 'name', 'field', token.position);
+      const spanRaw = token.attrs.span;
+      const span = spanRaw !== undefined ? parseInteger(spanRaw, 'span', 'field', token.position) : undefined;
+      index += 1;
+      return { kind: 'field', name, span };
+    }
+
+    if (token.name === 'grid') {
+      if (token.selfClosing) {
+        throw new LayoutParseError('<grid> must wrap children (cannot self-close)', token.position);
+      }
+      const cols = parseInteger(
+        requireAttr(token.attrs, 'cols', 'grid', token.position),
+        'cols',
+        'grid',
+        token.position,
+      );
+      index += 1;
+      const children: LayoutNode[] = [];
+      while (index < tokens.length && !(tokens[index].type === 'close' && tokens[index].name === 'grid')) {
+        children.push(parseNode());
+      }
+      const closing = tokens[index];
+      if (!closing || closing.type !== 'close' || closing.name !== 'grid') {
+        throw new LayoutParseError('<grid> not closed', token.position);
+      }
+      index += 1;
+      return { kind: 'grid', cols, children };
+    }
+
+    throw new LayoutParseError(`unknown element <${token.name}>`, token.position);
+  };
+
+  const root = parseNode();
+  if (index !== tokens.length) {
+    const trailing = tokens[index];
+    throw new LayoutParseError(
+      `unexpected trailing tag <${trailing.type === 'open' ? '' : '/'}${trailing.name}>`,
+      trailing.position,
+    );
+  }
+  if (root.kind !== 'grid') {
+    throw new LayoutParseError('root element must be <grid>');
+  }
+  return root;
+};

package/src/components/Form/README.md

@@ -0,0 +1,3 @@
+# Form
+
+- [ ] Layout options (e.g., label on the side.)