@dxos/react-ui-form 0.8.4-main.2e9d522 → 0.8.4-main.3c1ae3b

package/src/components/Form/Form.tsx

@@ -1,108 +1,316 @@
 //
-// Copyright 2024 DXOS.org
-//
-
-import { type Schema } from 'effect';
-import React, { type ReactElement, useEffect, useMemo, useRef } from 'react';
-
-import { type BaseObject, type PropertyKey } from '@dxos/echo-schema';
-import { type ThemedClassName } from '@dxos/react-ui';
-import { cardDialogOverflow, cardSpacing } from '@dxos/react-ui-stack';
-import { type SchemaProperty } from '@dxos/schema';
-
-import { FormActions, type FormOuterSpacing } from './FormActions';
-import { FormFields, type FormFieldsProps } from './FormContent';
-import { FormProvider } from './FormContext';
-import { type InputProps, type InputComponent } from './Input';
-import { type FormOptions } from '../../hooks';
-
-export type PropsFilter<T extends BaseObject> = (props: SchemaProperty<T>[]) => SchemaProperty<T>[];
-
-export type ComponentLookup = (args: {
-  prop: string;
-  schema: Schema.Schema<any>;
-  inputProps: InputProps;
-}) => ReactElement | undefined;
-
-export type CustomInputMap = Partial<Record<string, InputComponent>>;
-
-export type FormProps<T extends BaseObject> = ThemedClassName<{
-  values: Partial<T>;
-  // TODO(burdon): Autofocus first input.
-  autoFocus?: boolean;
-  // TODO(burdon): Change to JsonPath includes/excludes.
-  filter?: PropsFilter<T>;
-  sort?: PropertyKey<T>[];
-  autoSave?: boolean;
-  outerSpacing?: FormOuterSpacing;
-  onCancel?: () => void;
-}> &
-  Pick<FormOptions<T>, 'schema' | 'onValuesChanged' | 'onValidate' | 'onSave'> &
-  FormFieldsProps;
-
-export const Form = <T extends BaseObject>({
-  classNames,
-  testId,
-  values: initialValues,
-  autoFocus,
-  readonly,
-  autoSave,
-  outerSpacing = true,
-  onCancel,
+// Copyright 2025 DXOS.org
+//
+
+import { createContext } from '@radix-ui/react-context';
+import * as Schema from 'effect/Schema';
+import type * as SchemaAST from 'effect/SchemaAST';
+import React, { type PropsWithChildren, useMemo, useRef } from 'react';
+
+import { type AnyProperties } from '@dxos/echo/internal';
+import { createJsonPath, getValue as getValue$ } from '@dxos/effect';
+import { IconButton, type IconButtonProps, ScrollArea, type ThemedClassName, useTranslation } from '@dxos/react-ui';
+import { mx } from '@dxos/react-ui-theme';
+
+import {
+  type FormHandler,
+  type FormHandlerProps,
+  type FormUpdateMeta,
+  useFormHandler,
+  useKeyHandler,
+} from '../../hooks';
+import { translationKey } from '../../translations';
+
+import { FormFieldLabel, type FormFieldLabelProps, type FormFieldStateProps } from './FormFieldComponent';
+import {
+  FormFieldSet as NaturalFormFieldSet,
+  type FormFieldSetProps as NaturalFormFieldSetProps,
+} from './FormFieldSet';
+
+// New features/polish
+// [x] Unify readonly/inline modes
+// [ ] Don't call save/autoSave if value hasn't changed
+// [ ] Fix onCancel (restore values)
+// [ ] Fix useSchema Type.Obj.Any cast
+// [ ] Remove @dxos/echo-db deps
+// [ ] TableCellEditor (handleEnter/ModalController).
+// [ ] Use FormFieldWrapper uniformly
+// [ ] Inline tables for object arrays
+// [ ] Defer query until popover
+// [ ] Omit id from sub properties.
+// [x] Refs
+//   [x] Single-select (fix popover)
+//   [x] Multi-select (array)
+// [ ] auto save doesn't work for combobox + select due to only firing on blur (workaround is to use onValuesChanged)
+
+// TODO(burdon): Move to @dxos/schema (re-export here).
+export type ExcludeId<S extends Schema.Schema.AnyNoContext> = Omit<Schema.Schema.Type<S>, 'id'>;
+
+// TODO(burdon): Move to @dxos/schema (re-export here).
+export const omitId = <S extends Schema.Schema.AnyNoContext>(schema: S): Schema.Schema<ExcludeId<S>, ExcludeId<S>> =>
+  schema.pipe(Schema.omit('id')) as any;
+
+//
+// Context
+//
+
+type FormContextValue<T extends AnyProperties = any> = {
+  /**
+   * Form handler.
+   */
+  form: FormHandler<T>;
+
+  /**
+   * Show debug info.
+   */
+  debug?: boolean;
+
+  /**
+   * Testing.
+   */
+  testId?: string;
+} & Pick<NaturalFormFieldSetProps<T>, 'readonly' | 'layout' | 'fieldMap' | 'fieldProvider'>;
+
+const [FormContextProvider, useFormContext] = createContext<FormContextValue>('Form');
+
+/**
+ * Get the current form values.
+ */
+const useFormValues = <T extends AnyProperties>(componentName: string, path: (string | number)[] = []): T => {
+  const jsonPath = createJsonPath(path);
+  const {
+    form: { values },
+  } = useFormContext(componentName);
+
+  return getValue$(values, jsonPath) as T;
+};
+
+/**
+ * Get the state props for the given field.
+ */
+const useFormFieldState = (componentName: string, path: (string | number)[] = []): FormFieldStateProps => {
+  const stablePath = useMemo(() => path, [Array.isArray(path) ? path.join('.') : path]);
+  const {
+    form: { getStatus, getValue, onBlur, onValueChange },
+  } = useFormContext(componentName);
+
+  return useMemo(
+    () => ({
+      getStatus: () => getStatus(stablePath),
+      getValue: () => getValue(stablePath),
+      onBlur: () => onBlur(stablePath),
+      onValueChange: (ast: SchemaAST.AST, value: any) => onValueChange(stablePath, ast, value),
+    }),
+    [getStatus, getValue, onBlur, onValueChange, stablePath],
+  );
+};
+
+//
+// Root
+//
+
+type FormRootProps<T extends AnyProperties = AnyProperties> = PropsWithChildren<
+  {
+    /**
+     * Called when the form is submitted and passes validation.
+     */
+    onSave?: (values: T, meta: FormUpdateMeta<T>) => void;
+
+    /**
+     * Called when the form is canceled to abandon/undo any pending changes.
+     */
+    onCancel?: () => void;
+  } & Omit<FormContextValue<T>, 'form'> &
+    Pick<FormHandlerProps<T>, 'schema' | 'autoSave' | 'values' | 'defaultValues' | 'onValidate' | 'onValuesChanged'> &
+    Omit<NaturalFormFieldSetProps<T>, 'schema' | 'path'>
+>;
+
+const FormRoot = <T extends AnyProperties = AnyProperties>({
+  children,
   schema,
-  onValuesChanged,
-  onValidate,
+  values,
   onSave,
+  onCancel,
   ...props
-}: FormProps<T>) => {
-  const formRef = useRef<HTMLDivElement>(null);
-
-  // TODO(burdon): Rename.
-  const handleValid = useMemo(() => (autoSave ? onSave : undefined), [autoSave, onSave]);
-
-  // Focus the first input element within this form.
-  useEffect(() => {
-    if (autoFocus && formRef.current) {
-      const input = formRef.current.querySelector('input');
-      if (input) {
-        input.focus();
-      }
-    }
-  }, [autoFocus]);
+}: FormRootProps<T>) => {
+  const form = useFormHandler({ schema, values, onSave, onCancel, ...props });
+
+  return (
+    <FormContextProvider form={form} {...props}>
+      {children}
+    </FormContextProvider>
+  );
+};
+
+FormRoot.displayName = 'Form.Root';
+
+//
+// Viewport
+//
+
+type FormViewportProps = ThemedClassName<PropsWithChildren<{}>>;
+
+const FormViewport = ({ classNames, children }: FormViewportProps) => {
+  return (
+    <ScrollArea.Root>
+      <ScrollArea.Viewport classNames={['plb-cardSpacingBlock', classNames]}>{children}</ScrollArea.Viewport>
+      <ScrollArea.Scrollbar orientation='vertical'>
+        <ScrollArea.Thumb />
+      </ScrollArea.Scrollbar>
+    </ScrollArea.Root>
+  );
+};
+
+FormViewport.displayName = 'Form.Viewport';
+
+//
+// Content
+//
+
+type FormContentProps = ThemedClassName<PropsWithChildren<{}>>;
+
+// TOOD(burdon): Figure out nesting (indent and testId).
+const FormContent = ({ classNames, children }: FormContentProps) => {
+  const { form, testId } = useFormContext(FormContent.displayName);
+  const ref = useRef<HTMLDivElement>(null);
+  useKeyHandler(ref.current, form);
 
   return (
-    <FormProvider
-      formRef={formRef}
-      schema={schema}
-      autoSave={autoSave}
-      initialValues={initialValues}
-      onValuesChanged={onValuesChanged}
-      onValidate={onValidate}
-      onValid={handleValid}
-      onSave={onSave}
+    <div
+      ref={ref}
+      role='form'
+      className={mx('flex flex-col is-full pli-cardSpacingInline', classNames)}
+      data-testid={testId}
     >
-      <div role='none' className='contents' data-testid={testId}>
-        <FormFields
-          {...props}
-          ref={formRef}
-          classNames={[
-            outerSpacing === 'blockStart-0'
-              ? 'pli-cardSpacingInline mbe-cardSpacingBlock [&>.mbs-inputSpacingBlock:first-child]:!mbs-0'
-              : outerSpacing === 'scroll-fields'
-                ? 'pli-cardSpacingInline pbe-cardSpacingBlock'
-                : outerSpacing
-                  ? cardSpacing
-                  : false,
-            outerSpacing === 'scroll-fields' && cardDialogOverflow,
-            classNames,
-          ]}
-          readonly={readonly}
-          schema={schema}
+      {children}
+    </div>
+  );
+};
+
+FormContent.displayName = 'Form.Content';
+
+//
+// FieldSet
+//
+
+type FormFieldSetProps = ThemedClassName<{}>;
+
+const FormFieldSet = ({ classNames }: FormFieldSetProps) => {
+  const { form, ...props } = useFormContext(FormFieldSet.displayName);
+
+  return <NaturalFormFieldSet classNames={classNames} schema={form.schema} {...props} />;
+};
+
+FormFieldSet.displayName = 'Form.FieldSet';
+
+//
+// Actions
+//
+
+type FormActionsProps = ThemedClassName<{}>;
+
+const FormActions = ({ classNames }: FormActionsProps) => {
+  const { t } = useTranslation(translationKey);
+  const {
+    form: { isValid, onSave, onCancel },
+    readonly,
+    layout,
+  } = useFormContext(FormActions.displayName);
+
+  if (readonly || layout === 'static') {
+    return null;
+  }
+
+  // TODO(burdon): Currently onCancel is a no-op; implement "revert values".
+  //   Deprecate FormSubmit ans use FormActions without Cancel button if no callback is supplied.
+
+  return (
+    <div role='none' className={mx('grid grid-flow-col auto-cols-fr gap-2 pbs-cardSpacingBlock', classNames)}>
+      {onCancel && (
+        <IconButton
+          icon='ph--x--regular'
+          iconEnd
+          label={t('cancel button label')}
+          onClick={onCancel}
+          data-testid='cancel-button'
+        />
+      )}
+      {onSave && (
+        <IconButton
+          type='submit'
+          variant='primary'
+          disabled={!isValid}
+          icon='ph--check--regular'
+          iconEnd
+          label={t('save button label')}
+          onClick={onSave}
+          data-testid='save-button'
         />
-        {(onCancel || onSave) && !autoSave && (
-          <FormActions readonly={readonly} onCancel={onCancel} outerSpacing={outerSpacing} />
-        )}
-      </div>
-    </FormProvider>
+      )}
+    </div>
+  );
+};
+
+FormActions.displayName = 'Form.Actions';
+
+//
+// Submit
+//
+
+type FormSubmitProps = ThemedClassName<Partial<Pick<IconButtonProps, 'icon' | 'label'>>>;
+
+const FormSubmit = ({ classNames, label, icon }: FormSubmitProps) => {
+  const { t } = useTranslation(translationKey);
+  const {
+    form: { isValid, onSave },
+    readonly,
+    layout,
+  } = useFormContext(FormSubmit.displayName);
+
+  if (readonly || layout === 'static') {
+    return null;
+  }
+
+  return (
+    <div role='none' className={mx('flex is-full pbs-cardSpacingBlock', classNames)}>
+      <IconButton
+        classNames='is-full'
+        type='submit'
+        variant='primary'
+        disabled={!isValid}
+        icon={icon ?? 'ph--check--regular'}
+        label={label ?? t('save button label')}
+        onClick={onSave}
+        data-testid='save-button'
+      />
+    </div>
   );
 };
+
+FormSubmit.displayName = 'Form.Submit';
+
+//
+// Form
+// https://www.radix-ui.com/primitives/docs/guides/composition
+//
+
+export const Form = {
+  Root: FormRoot,
+  Viewport: FormViewport,
+  Content: FormContent,
+  FieldSet: FormFieldSet,
+  Actions: FormActions,
+  Submit: FormSubmit,
+  Label: FormFieldLabel,
+};
+
+export { useFormContext, useFormValues, useFormFieldState };
+
+export type {
+  FormRootProps,
+  FormViewportProps,
+  FormContentProps,
+  FormFieldSetProps,
+  FormActionsProps,
+  FormFieldLabelProps as LabelProps,
+};

package/src/components/Form/FormField.tsx

@@ -0,0 +1,280 @@
+//
+// 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<
+  RefFieldProps,
+  | 'autoFocus'
+  | 'readonly'
+  | 'layout'
+  | 'createSchema'
+  | 'createOptionLabel'
+  | 'createOptionIcon'
+  | 'createInitialValuePath'
+  | 'onCreate'
+  | 'onQueryRefOptions'
+>;
+
+export const FormField = (props: FormFieldProps) => {
+  const {
+    type,
+    name,
+    path,
+    projection,
+    fieldMap,
+    fieldProvider,
+    readonly,
+    layout,
+    createSchema,
+    createOptionLabel,
+    createOptionIcon,
+    createInitialValuePath,
+    onCreate,
+    onQueryRefOptions,
+  } = 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}
+        createSchema={createSchema}
+        createOptionLabel={createOptionLabel}
+        createOptionIcon={createOptionIcon}
+        createInitialValuePath={createInitialValuePath}
+        onCreate={onCreate}
+        onQueryRefOptions={onQueryRefOptions}
+      />
+    );
+  }
+
+  //
+  // 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}
+          onCreate={onCreate}
+          onQueryRefOptions={onQueryRefOptions}
+        />
+      );
+    }
+  }
+
+  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));
+};