@dxos/react-ui-form 0.8.4-main.84f28bd → 0.8.4-main.9735255

package/src/components/Form/FormField.tsx

@@ -0,0 +1,286 @@
+//
+// 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;
+} & Pick<FormFieldComponentProps, 'autoFocus' | 'readonly' | 'layout'> &
+  Pick<
+    RefFieldProps,
+    | 'createOptionLabel'
+    | 'createOptionIcon'
+    | 'createInitialValuePath'
+    | 'db'
+    | 'schemaHook'
+    | 'getOptions'
+    | 'onCreate'
+  >;
+
+export const FormField = (props: FormFieldProps) => {
+  const {
+    type,
+    name,
+    path,
+    projection,
+    fieldMap,
+    fieldProvider,
+    readonly,
+    layout,
+
+    // RefFieldProps
+    createOptionLabel,
+    createOptionIcon,
+    createInitialValuePath,
+    db,
+    schemaHook,
+    getOptions: getRefOptions,
+    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,
+    ...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 = getOptions(type);
+  if (options) {
+    return (
+      <SelectField
+        {...fieldProps}
+        options={options.map((option) => ({
+          value: option,
+          label: option.toString(),
+        }))}
+      />
+    );
+  }
+
+  //
+  // Ref field.
+  //
+
+  const refProps = getRefProps(type);
+  if (refProps) {
+    return (
+      <RefField
+        {...fieldProps}
+        {...refProps}
+        createOptionLabel={createOptionLabel}
+        createOptionIcon={createOptionIcon}
+        createInitialValuePath={createInitialValuePath}
+        db={db}
+        schemaHook={schemaHook}
+        getOptions={getRefOptions}
+        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}
+          schemaHook={schemaHook}
+          getOptions={getRefOptions}
+          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 getOptions = (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 Component = ({
+  type,
+  placeholder,
+  readonly,
+  onBlur,
+  onValueChange,
+  ...props
+}: FormFieldComponentProps<string>) => {
+  const handleChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => onValueChange(type, event.target.value),
+    [type, onValueChange],
+  );
+
+  return (
+    <div className='plb-cardSpacingBlock pli-cardSpacingInline'>
+      <FormFieldWrapper<string> {...props}>
+        {({ value = '' }) => (
+          <Input.TextInput
+            disabled={!!readonly}
+            placeholder={placeholder}
+            noAutoFill
+            value={value}
+            onChange={handleChange}
+            onBlur={onBlur}
+          />
+        )}
+      </FormFieldWrapper>
+    </div>
+  );
+};
+
+const meta: Meta<typeof Component> = {
+  title: 'ui/react-ui-form/FormFieldComponent',
+  component: Component,
+  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 Format } from '@dxos/echo/internal';
+import { Icon, Input, Tooltip } from '@dxos/react-ui';
+import { errorText, mx } from '@dxos/ui-theme';
+
+import { type FormFieldStatus } from '../../hooks';
+
+const labelSpacing = 'mbs-inputSpacingBlock mbe-labelSpacingBlock';
+
+/**
+ * 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;
+} & 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;
+  const labelProps = readonly || asChild ? { className: 'text-description text-sm' } : { classNames: '!mlb-0 text-sm' };
+
+  return (
+    <div role='none' className={mx('flex justify-between items-center', labelSpacing)}>
+      <Label {...labelProps}>{label}</Label>
+      {error && (
+        <Tooltip.Trigger asChild content={error} side='bottom'>
+          <Icon icon='ph--warning--regular' size={4} classNames={errorText} />
+        </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 (
+    <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>
+  );
+};
+
+//
+// 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-roseFill font-mono text-sm'>
+          <span className='bg-roseFill text-surfaceText pli-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,125 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { forwardRef, useMemo } from 'react';
+
+import { type AnyProperties } from '@dxos/echo/internal';
+import { type SchemaProperty } from '@dxos/effect';
+import { type ThemedClassName } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+import { isTruthy } from '@dxos/util';
+
+import { type FormHandlerProps } from '../../hooks';
+import { getFormProperties } from '../../util';
+
+import { useFormValues } from './Form';
+import { FormField, type FormFieldProps } from './FormField';
+import { FormFieldErrorBoundary, FormFieldLabel } from './FormFieldComponent';
+
+export type FormFieldSetProps<T extends AnyProperties> = ThemedClassName<
+  {
+    label?: string;
+    exclude?: (props: SchemaProperty[]) => SchemaProperty[];
+    sort?: string[];
+  } & Pick<FormHandlerProps<T>, 'schema'> &
+    Pick<
+      FormFieldProps,
+      | 'path'
+      | 'autoFocus'
+      | 'readonly'
+      | 'layout'
+      | 'projection'
+      | 'fieldMap'
+      | 'fieldProvider'
+      | 'createOptionLabel'
+      | 'createOptionIcon'
+      | 'createInitialValuePath'
+      | 'db'
+      | 'schemaHook'
+      | 'getOptions'
+      | 'onCreate'
+    >
+>;
+
+export const FormFieldSet = forwardRef<HTMLDivElement, FormFieldSetProps<any>>(
+  ({ classNames, label, schema, readonly, path, exclude, sort, projection, layout, ...props }, forwardRef) => {
+    const values = useFormValues(FormFieldSet.displayName!, 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);
+          }
+        }
+
+        // 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.
+      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]);
+
+    if ((readonly || layout === 'static') && values == null) {
+      return null;
+    }
+
+    return (
+      <div
+        role='form'
+        className={mx('is-full', layout === 'inline' && 'flex flex-col gap-2', classNames)}
+        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>
+    );
+  },
+);
+
+FormFieldSet.displayName = 'Form.Fields';

package/src/components/Form/README.md

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