@dxos/react-ui-form 0.8.4-main.f5c0578 → 0.8.4-main.fcc0d83b33

package/src/components/Form/FormField.tsx

@@ -0,0 +1,306 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Match from 'effect/Match';
+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 { Format } from '@dxos/echo';
+import {
+  createJsonPath,
+  findNode,
+  getAnnotation,
+  getDiscriminatedType,
+  isArrayType,
+  isDiscriminatedUnion,
+  isLiteralUnion,
+  isNestedType,
+} from '@dxos/effect';
+import { useTranslation } from '@dxos/react-ui';
+import { type ProjectionModel } from '@dxos/schema';
+
+import { translationKey } from '#translations';
+
+import { getRefProps } from '../../util';
+import {
+  ArrayField,
+  BooleanField,
+  GeoPointField,
+  MarkdownField,
+  NumberField,
+  RefField,
+  type RefFieldProps,
+  SelectField,
+  TextAreaField,
+  TextField,
+} from './fields';
+import { useFormFieldState } from './Form';
+import {
+  type FormFieldComponent,
+  type FormFieldComponentProps,
+  type FormFieldMap,
+  type FormFieldProvider,
+} from './FormFieldComponent';
+import { FormFieldSet } from './FormFieldSet';
+
+export type FormFieldProps = {
+  /**
+   * AST of the property to render.
+   */
+  type: SchemaAST.AST;
+
+  /**
+   * Name of the property.
+   */
+  name: string;
+
+  /**
+   * Path to the current object from the root. Used with nested forms.
+   */
+  path?: (string | number)[];
+
+  /**
+   * Optional projection for projection-based field management.
+   */
+  projection?: ProjectionModel;
+
+  /**
+   * Map of custom renderers for specific properties.
+   * Prefer fieldProvider for plugin specific input surfaces.
+   */
+  fieldMap?: FormFieldMap;
+
+  /**
+   * 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
+   * are only passed to ref fields whose typename matches.
+   */
+  createTypename?: string;
+} & Pick<FormFieldComponentProps, 'autoFocus' | 'readonly' | 'layout'> &
+  Pick<
+    RefFieldProps,
+    | 'createOptionLabel'
+    | 'createOptionIcon'
+    | 'createInitialValuePath'
+    | 'createFieldMap'
+    | 'db'
+    | 'useSchema'
+    | 'getOptions'
+    | 'onCreate'
+  >;
+
+export const FormField = (props: FormFieldProps) => {
+  const {
+    type,
+    name,
+    path,
+    projection,
+    fieldMap,
+    fieldProvider,
+    readonly,
+    layout,
+
+    // RefFieldProps
+    createTypename,
+    createOptionLabel,
+    createOptionIcon,
+    createInitialValuePath,
+    createFieldMap,
+    db,
+    useSchema: schemaHook,
+    getOptions,
+    onCreate,
+  } = props;
+  const { t } = useTranslation(translationKey);
+  const title = getAnnotation<string>(SchemaAST.TitleAnnotationId)(type);
+  const description = getAnnotation<string>(SchemaAST.DescriptionAnnotationId)(type);
+  const examples = getAnnotation<string[]>(SchemaAST.ExamplesAnnotationId)(type);
+
+  const label = useMemo(() => title ?? 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 fieldProps: FormFieldComponentProps = {
+    type,
+    format: Format.FormatAnnotation.getFromAst(type).pipe((annotation) => Option.getOrUndefined(annotation)),
+    readonly,
+    label,
+    placeholder,
+    layout,
+    db,
+    ...fieldState,
+  };
+
+  //
+  // 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 });
+  if (component) {
+    return component;
+  }
+
+  //
+  // Array field.
+  //
+
+  if (isArrayType(type)) {
+    return <ArrayField fieldProps={fieldState} label={label} {...props} />;
+  }
+
+  //
+  // Regular field.
+  //
+
+  const Field = getFormField(fieldProps);
+  if (Field) {
+    return <Field {...fieldProps} />;
+  }
+
+  //
+  // Select field.
+  //
+
+  const options = getSelectOptions(type);
+  if (options) {
+    // Resolve labels from projection metadata when available.
+    const fieldProjections = projection?.getFieldProjections();
+    const fieldProjection = fieldProjections?.find((fp) => fp.field.path === name);
+    const selectOptions = fieldProjection?.props.options;
+
+    return (
+      <SelectField
+        {...fieldProps}
+        options={options.map((option) => {
+          const selectOption = selectOptions?.find((so) => so.id === globalThis.String(option));
+          return {
+            value: option,
+            label: selectOption?.title ?? option.toString(),
+          };
+        })}
+      />
+    );
+  }
+
+  //
+  // Ref field.
+  //
+
+  const refProps = getRefProps(type);
+  if (refProps) {
+    const isCreateTarget = !createTypename || refProps.typename === createTypename;
+    return (
+      <RefField
+        {...fieldProps}
+        {...refProps}
+        createOptionLabel={isCreateTarget ? createOptionLabel : undefined}
+        createOptionIcon={isCreateTarget ? createOptionIcon : undefined}
+        createInitialValuePath={isCreateTarget ? createInitialValuePath : undefined}
+        createFieldMap={isCreateTarget ? createFieldMap : undefined}
+        db={db}
+        useSchema={schemaHook}
+        getOptions={getOptions}
+        onCreate={onCreate}
+      />
+    );
+  }
+
+  //
+  // Nested Object field.
+  //
+
+  if (isNestedType(type)) {
+    const baseNode = findNode(type, isDiscriminatedUnion);
+    const typeLiteral = baseNode
+      ? getDiscriminatedType(baseNode, fieldState.getValue() as any)
+      : findNode(type, SchemaAST.isTypeLiteral);
+
+    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}
+        />
+      );
+    }
+  }
+
+  return null;
+};
+
+FormField.displayName = 'Form.FormField';
+
+/**
+ * Get property input component.
+ */
+const getFormField = ({ type, format }: FormFieldComponentProps): FormFieldComponent | undefined => {
+  //
+  // Standard formats.
+  //
+
+  const formatField = Match.value(format).pipe(
+    Match.withReturnType<FormFieldComponent | undefined>(),
+    Match.when(Format.TypeFormat.GeoPoint, () => GeoPointField),
+    Match.when(Format.TypeFormat.Markdown, () => MarkdownField),
+    Match.when(Format.TypeFormat.Text, () => TextAreaField),
+    Match.orElse(() => undefined),
+  );
+  if (formatField) {
+    return formatField;
+  }
+
+  //
+  // Standard types.
+  //
+
+  switch (type._tag) {
+    // TODO(wittjosiah): Schema.Any is currently used to represent template inputs.
+    case 'AnyKeyword':
+    case 'StringKeyword':
+      return TextField;
+    case 'NumberKeyword':
+      return NumberField;
+    case 'BooleanKeyword':
+      return BooleanField;
+  }
+};
+
+const getSelectOptions = (ast: SchemaAST.AST): Format.Options[] | undefined => {
+  if (isLiteralUnion(ast)) {
+    return ast.types.map((type) => type.literal).filter((v): v is string | number => v !== null);
+  }
+
+  return Format.OptionsAnnotation.getFromAst(ast).pipe((annotation) => Option.getOrUndefined(annotation));
+};

package/src/components/Form/FormFieldComponent.stories.tsx

@@ -0,0 +1,65 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { type ChangeEvent, useCallback } from 'react';
+
+import { Input } from '@dxos/react-ui';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { type FormFieldComponentProps, FormFieldWrapper } from './FormFieldComponent';
+
+const DefaultStory = ({
+  type,
+  placeholder,
+  readonly,
+  onBlur,
+  onValueChange,
+  ...props
+}: FormFieldComponentProps<string>) => {
+  const handleChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => onValueChange(type, event.target.value),
+    [type, onValueChange],
+  );
+
+  return (
+    <div className='p-form-padding'>
+      <FormFieldWrapper<string> {...props}>
+        {({ value = '' }) => (
+          <Input.TextInput
+            disabled={!!readonly}
+            placeholder={placeholder}
+            noAutoFill
+            value={value}
+            onChange={handleChange}
+            onBlur={onBlur}
+          />
+        )}
+      </FormFieldWrapper>
+    </div>
+  );
+};
+
+const meta: Meta<typeof DefaultStory> = {
+  title: 'ui/react-ui-form/FormFieldComponent',
+  component: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  parameters: {
+    layout: 'fullscreen',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    label: 'Label',
+    getStatus: () => ({ status: 'error', error: 'Required field' }),
+    getValue: () => 'DXOS',
+    onBlur: () => {},
+    onValueChange: () => {},
+  },
+};

package/src/components/Form/FormFieldComponent.tsx

@@ -0,0 +1,174 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import type * as Schema from 'effect/Schema';
+import type * as SchemaAST from 'effect/SchemaAST';
+import React, {
+  Component,
+  type FC,
+  type FocusEvent,
+  type PropsWithChildren,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+
+import { type Database } from '@dxos/echo';
+import { type Format } from '@dxos/echo/internal';
+import { Icon, Input, Tooltip } from '@dxos/react-ui';
+import { inputTextLabel } from '@dxos/ui-theme';
+
+import { type FormFieldStatus } from '../../hooks';
+
+/**
+ * Dynamic props passed to input components.
+ */
+export type FormFieldStateProps<T = any> = {
+  getStatus: () => FormFieldStatus;
+  getValue: () => T | undefined;
+  onBlur: (event: FocusEvent<HTMLElement>) => void;
+  onValueChange: (type: SchemaAST.AST, value: T) => void;
+};
+
+/**
+ * Presentation mode.
+ * - full: Show label, control, and status.
+ * - compact: Show label and control.
+ * - inline: Control only.
+ * - static: Plain DOM; omit all undefined values.
+ */
+// TODO(burdon): 'inline' should be orthogonal to the layout (e.g., array of inline static).
+export type Presentation = 'full' | 'compact' | 'inline' | 'static';
+
+/**
+ * Props passed to input components.
+ */
+export type FormFieldComponentProps<T = any> = {
+  type: SchemaAST.AST;
+  format?: Format.TypeFormat;
+  readonly?: boolean;
+  label: 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?
+  schema: Schema.Schema<any>;
+  fieldProps: FormFieldComponentProps;
+}) => ReactElement | undefined;
+
+//
+// FormFieldLabel
+//
+
+export type FormFieldLabelProps = {
+  asChild?: boolean;
+  error?: string;
+} & Pick<FormFieldComponentProps, 'label' | 'readonly'>;
+
+export const FormFieldLabel = ({ label, error, readonly, asChild }: FormFieldLabelProps) => {
+  const Label = readonly || asChild ? 'span' : Input.Label;
+  return (
+    <div role='none' className='flex items-center justify-between'>
+      <Label className={inputTextLabel}>{label}</Label>
+      {error && (
+        <Tooltip.Trigger asChild content={error} side='bottom'>
+          <Icon icon='ph--warning--regular' size={4} classNames='text-error-text' />
+        </Tooltip.Trigger>
+      )}
+    </div>
+  );
+};
+
+FormFieldLabel.displayName = 'Form.FieldLabel';
+
+//
+// FormFieldWrapper
+//
+
+export type FormFieldWrapperProps<T = any> = Pick<
+  FormFieldComponentProps,
+  'readonly' | 'label' | 'layout' | 'getStatus' | 'getValue'
+> & {
+  children?: (props: { value: T }) => ReactNode;
+};
+
+export const FormFieldWrapper = <T,>(props: FormFieldWrapperProps<T>) => {
+  const { children, readonly, layout, label, getStatus, getValue } = props;
+  const { status, error } = getStatus();
+
+  const value = getValue();
+  if (layout === 'static' && value == null) {
+    return null;
+  }
+
+  const str = String(value ?? '');
+
+  return (
+    <div role='none' 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' && (
+          <Input.DescriptionAndValidation>
+            <Input.Validation>{error}</Input.Validation>
+          </Input.DescriptionAndValidation>
+        )}
+      </Input.Root>
+    </div>
+  );
+};
+
+//
+// FormFieldErrorBoundary
+//
+
+type FormFieldErrorState = {
+  error: Error | undefined;
+};
+
+type FormFieldErrorBoundaryProps = PropsWithChildren<{
+  path?: (string | number)[];
+}>;
+
+export class FormFieldErrorBoundary extends Component<FormFieldErrorBoundaryProps, FormFieldErrorState> {
+  static getDerivedStateFromError(error: Error): { error: Error } {
+    return { error };
+  }
+
+  override state = { error: undefined };
+
+  override componentDidUpdate(prevProps: FormFieldErrorBoundaryProps) {
+    if (prevProps.path !== this.props.path) {
+      this.resetError();
+    }
+  }
+
+  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>
+          {String(this.props.path?.join('.'))}
+        </div>
+      );
+    }
+
+    return this.props.children;
+  }
+
+  private resetError() {
+    this.setState({ error: undefined });
+  }
+}

package/src/components/Form/FormFieldSet.tsx

@@ -0,0 +1,144 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useMemo } from 'react';
+
+import { type AnyProperties } from '@dxos/echo/internal';
+import { 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';
+
+const FORM_FIELDSET_NAME = 'Form.FieldSet';
+
+export type FormFieldSetProps<T extends AnyProperties> = {
+  label?: string;
+  sort?: string[];
+  exclude?: (props: SchemaProperty[]) => SchemaProperty[];
+} & Pick<FormHandlerProps<T>, 'schema'> &
+  Pick<
+    FormFieldProps,
+    | 'path'
+    | 'autoFocus'
+    | 'readonly'
+    | 'layout'
+    | 'projection'
+    | 'fieldMap'
+    | 'fieldProvider'
+    | 'createTypename'
+    | 'createOptionLabel'
+    | 'createOptionIcon'
+    | 'createInitialValuePath'
+    | 'createFieldMap'
+    | 'db'
+    | 'useSchema'
+    | 'getOptions'
+    | 'onCreate'
+  >;
+
+/**
+ * Renders a set of form fields derived from a schema object.
+ */
+export const FormFieldSet = ({
+  label,
+  schema,
+  readonly,
+  path,
+  sort,
+  exclude,
+  projection,
+  layout,
+  ...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;
+  }
+
+  return (
+    <>
+      {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>
+        );
+      })}
+    </>
+  );
+};
+
+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/README.md

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