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

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.)

package/src/components/Form/fields/ArrayField.tsx

@@ -0,0 +1,185 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Option from 'effect/Option';
+import * as SchemaAST from 'effect/SchemaAST';
+import React, { useCallback } from 'react';
+
+import { Ref } from '@dxos/echo';
+import {
+  createJsonPath,
+  findNode,
+  getArrayElementType,
+  getDiscriminatedType,
+  isDiscriminatedUnion,
+  isNestedType,
+} from '@dxos/effect';
+import { IconButton, IconButtonProps, useTranslation } from '@dxos/react-ui';
+
+import { translationKey } from '#translations';
+
+import { getFormProperties } from '../../../util';
+import { useFormValues } from '../Form';
+import { FormField, type FormFieldProps } from '../FormField';
+import { FormFieldLabel, type FormFieldStateProps } from '../FormFieldComponent';
+
+export type ArrayFieldProps = {
+  label: string;
+  fieldProps: FormFieldStateProps;
+} & FormFieldProps;
+
+export const ArrayField = ({
+  type,
+  path,
+  label,
+  readonly,
+  layout,
+  fieldProps: inputProps,
+  ...props
+}: ArrayFieldProps) => {
+  const { t } = useTranslation(translationKey);
+  const elementType = getArrayElementType(type);
+  const { onValueChange } = inputProps;
+  const values = useFormValues(ArrayField.displayName, path, () => []);
+
+  const getDefaultObjectValue = (typeNode: SchemaAST.AST): any => {
+    const baseNode = findNode(typeNode, isDiscriminatedUnion);
+    const typeLiteral = baseNode ? getDiscriminatedType(baseNode, {}) : findNode(typeNode, SchemaAST.isTypeLiteral);
+    if (!typeLiteral) {
+      return {};
+    }
+
+    return Object.fromEntries(
+      getFormProperties(typeLiteral).map((prop) => {
+        const defaultValue = SchemaAST.getDefaultAnnotation(prop.type).pipe((annotation) =>
+          Option.getOrUndefined(annotation),
+        );
+        return [prop.name, defaultValue];
+      }),
+    );
+  };
+
+  const handleAdd = useCallback(() => {
+    const defaultValue =
+      isNestedType(type) && elementType ? getDefaultObjectValue(elementType) : getDefaultValue(elementType);
+    // `values` is `undefined` on first render for arrays whose parent path
+    // hasn't been materialised in the form values yet (e.g. `package.repos`
+    // when the form starts with no `package`). `useFormValues`'s default-
+    // value effect would eventually backfill it to `[]`, but until then the
+    // old `values && ...` guard silently swallowed the click. Treat a
+    // missing array as empty so Add always produces `[defaultValue]`.
+    onValueChange(type, [...(values ?? []), defaultValue]);
+  }, [onValueChange, type, elementType, values]);
+
+  const handleDelete = useCallback(
+    (idx: number) => {
+      onValueChange(
+        type,
+        values?.filter((_, i) => i !== idx),
+      );
+    },
+    [onValueChange, type, values],
+  );
+
+  if (!elementType || ((readonly || layout === 'static') && values && values.length < 1)) {
+    return null;
+  }
+
+  const renderItemAsObject = elementType && isNestedType(elementType) && !Ref.isRefType(elementType);
+
+  return (
+    <>
+      {(layout !== 'static' || (values && values.length > 0)) && (
+        <div className='flex items-center gap-2'>
+          <div className='flex-1 min-w-0'>
+            <FormFieldLabel readonly={readonly} label={label} path={createJsonPath(path ?? [])} asChild />
+          </div>
+          {!readonly && layout !== 'static' && (
+            <IconBlock icon='ph--plus--regular' label={t('add-item.button')} onClick={handleAdd} />
+          )}
+        </div>
+      )}
+
+      <div className='flex flex-col'>
+        {values?.map((_, index) => {
+          const isLast = index === values.length - 1;
+          // Object items: each row contains a recursively-rendered FormField
+          //   (multiple sub-rows for the object's fields) wrapped in a border,
+          //   with the delete button bottom-aligned next to it.
+          // Scalar items: a single-row inline FormField with a center-aligned
+          //   delete button. Refs and primitive arrays use this layout.
+          const fieldField = (
+            <FormField
+              {...props}
+              autoFocus={isLast}
+              type={elementType}
+              // Suppress the per-item header for object items only — the recursive
+              // form already renders labels for each sub-field. Scalar items
+              // (refs, primitives) keep the parent name so inline-layout
+              // children (e.g. RefField) have a real label to use as a
+              // fallback placeholder.
+              {...(renderItemAsObject && { name: null })}
+              path={[...(path ?? []), index]}
+              readonly={readonly || layout === 'static'}
+              layout={renderItemAsObject ? (layout === 'static' ? 'static' : undefined) : 'inline'}
+            />
+          );
+
+          return (
+            <div key={index} className='grid grid-cols-[1fr_min-content] items-center mb-1 last:mb-form-gap'>
+              {renderItemAsObject ? (
+                <div className='p-1 border border-subdued-separator'>{fieldField}</div>
+              ) : (
+                fieldField
+              )}
+
+              {!readonly && layout !== 'static' && (
+                <IconBlock icon='ph--x--regular' label={t('remove-item.button')} onClick={() => handleDelete(index)} />
+              )}
+            </div>
+          );
+        })}
+      </div>
+    </>
+  );
+};
+
+ArrayField.displayName = 'Form.ArrayField';
+
+const IconBlock = (props: IconButtonProps) => {
+  return (
+    <div className='flex items-center h-full px-1'>
+      <IconButton variant='ghost' density='xs' square iconOnly {...props} />
+    </div>
+  );
+};
+
+/**
+ * Returns the default empty value for a given AST.
+ * Used for initializing new array values etc.
+ */
+// TODO(wittjosiah): Factor out?
+export const getDefaultValue = (ast?: SchemaAST.AST): any => {
+  switch (ast?._tag) {
+    case 'StringKeyword': {
+      return '';
+    }
+    case 'NumberKeyword': {
+      return 0;
+    }
+    case 'BooleanKeyword': {
+      return false;
+    }
+    case 'Suspend': {
+      return getDefaultValue(ast.f());
+    }
+    default: {
+      if (ast && isNestedType(ast)) {
+        return {};
+      } else {
+        throw new Error(`Unsupported type: ${ast?._tag}`);
+      }
+    }
+  }
+};

package/src/components/Form/fields/BooleanField.tsx

@@ -0,0 +1,22 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React, { useCallback } from 'react';
+
+import { Input, type SwitchProps } from '@dxos/react-ui';
+
+import { type FormFieldComponentProps, FormFieldWrapper } from '../FormFieldComponent';
+
+export const BooleanField = ({ type, readonly, onValueChange, ...props }: FormFieldComponentProps<boolean>) => {
+  const handleChange = useCallback<NonNullable<SwitchProps['onCheckedChange']>>(
+    (value) => onValueChange?.(type, value),
+    [type, onValueChange],
+  );
+
+  return (
+    <FormFieldWrapper<boolean> readonly={readonly} {...props}>
+      {({ value }) => <Input.Switch disabled={!!readonly} checked={value} onCheckedChange={handleChange} />}
+    </FormFieldWrapper>
+  );
+};

package/src/components/Form/fields/DateField.tsx

@@ -0,0 +1,95 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { format as formatDate } from 'date-fns';
+import React, { useCallback } from 'react';
+
+import { Format } from '@dxos/echo';
+import { Input } from '@dxos/react-ui';
+
+import { type FormFieldComponentProps, FormFieldWrapper } from '../FormFieldComponent';
+
+/**
+ * Stored value shapes:
+ * - `Format.DateTime` -> ISO 8601 (`2018-11-13T20:20:39.000Z`).
+ * - `Format.Date`     -> `YYYY-MM-DD`.
+ * - `Format.Time`     -> `HH:mm:ss`.
+ *
+ * Segmented input value shapes (react-aria-components-backed):
+ * - `Input.DateTime` -> `YYYY-MM-DDTHH:mm` in local time.
+ * - `Input.Date`     -> `YYYY-MM-DD`.
+ * - `Input.Time`     -> `HH:mm`.
+ */
+
+/** ISO 8601 → `YYYY-MM-DDTHH:mm` in the user's local timezone. */
+const isoToLocalDateTime = (value: string | undefined): string => {
+  if (!value) {
+    return '';
+  }
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    return '';
+  }
+  return formatDate(date, "yyyy-MM-dd'T'HH:mm");
+};
+
+/** `YYYY-MM-DDTHH:mm` (local) → ISO 8601 with timezone. */
+const localDateTimeToIso = (value: string): string | undefined => {
+  if (!value) {
+    return undefined;
+  }
+  // Treat the input as local time. `new Date('YYYY-MM-DDTHH:mm')` parses as local.
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? undefined : date.toISOString();
+};
+
+export const DateField = ({
+  type,
+  format,
+  readonly,
+  placeholder: _placeholder,
+  onValueChange,
+  onBlur: _onBlur,
+  ...props
+}: FormFieldComponentProps<string>) => {
+  const handleSimpleChange = useCallback((next: string) => onValueChange(type, next), [type, onValueChange]);
+
+  const handleDateTimeChange = useCallback(
+    (next: string) => {
+      const iso = localDateTimeToIso(next);
+      onValueChange(type, iso as string);
+    },
+    [type, onValueChange],
+  );
+
+  return (
+    <FormFieldWrapper<string> readonly={readonly} {...props}>
+      {({ value }) => {
+        switch (format) {
+          case Format.TypeFormat.Date:
+            return (
+              <div className='grid grid-cols-[1fr_min-content] items-center gap-1'>
+                <Input.Date disabled={!!readonly} value={value ?? ''} onValueChange={handleSimpleChange} />
+                <Input.TriggerIcon />
+              </div>
+            );
+          case Format.TypeFormat.Time:
+            return <Input.Time disabled={!!readonly} value={value ?? ''} onValueChange={handleSimpleChange} />;
+          case Format.TypeFormat.DateTime:
+          default:
+            return (
+              <div className='grid grid-cols-[1fr_min-content] items-center gap-1'>
+                <Input.DateTime
+                  disabled={!!readonly}
+                  value={isoToLocalDateTime(value)}
+                  onValueChange={handleDateTimeChange}
+                />
+                <Input.TriggerIcon />
+              </div>
+            );
+        }
+      }}
+    </FormFieldWrapper>
+  );
+};