@dxos/react-ui-form 0.8.4-main.ae835ea → 0.8.4-main.bc674ce

package/src/hooks/useFormHandler.ts

@@ -0,0 +1,362 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useControllableState } from '@radix-ui/react-use-controllable-state';
+import type * as Schema from 'effect/Schema';
+import type * as SchemaAST from 'effect/SchemaAST';
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+import { Obj } from '@dxos/echo';
+import { type AnyProperties } from '@dxos/echo/internal';
+import {
+  type JsonPath,
+  createJsonPath,
+  fromEffectValidationPath,
+  getValue as getValue$,
+  setValue as setValue$,
+} from '@dxos/effect';
+import { log } from '@dxos/log';
+import { useDefaultValue } from '@dxos/react-ui';
+import { type ValidationError, validateSchema } from '@dxos/schema';
+import { type MaybePromise } from '@dxos/util';
+
+import { setValueEchoAware } from '../util';
+
+export type FormFieldStatus = {
+  status?: 'error';
+  error?: string;
+};
+
+/**
+ * Form properties.
+ */
+export interface FormHandlerProps<T extends AnyProperties> {
+  /**
+   * Effect schema (Type literal).
+   */
+  schema?: Schema.Schema<T, any>;
+
+  /**
+   * Values for the form if controlled.
+   */
+  values?: Partial<T>;
+
+  /**
+   * Default values for the form which will be used if values is not provided.
+   */
+  defaultValues?: Partial<T>;
+
+  /**
+   * Auto-save the form when the values change.
+   */
+  autoSave?: boolean;
+
+  /**
+   * Callback for value changes. Note: This is called even when values are invalid.
+   * Sometimes the parent component may want to know about changes even if the form is
+   * in an invalid state.
+   */
+  onValuesChanged?: (values: Partial<T>, meta: FormUpdateMeta<T>) => void;
+
+  /**
+   * Custom validation function that runs only after schema validation passes.
+   * Use this for complex validation logic that can't be expressed in the schema.
+   * @returns Array of validation errors, or undefined if validation passes
+   */
+  onValidate?: (values: T) => ValidationError[] | undefined;
+
+  /**
+   * Called when the form is submitted and passes validation.
+   */
+  onSave?: (values: T, meta: FormUpdateMeta<T>) => MaybePromise<void>;
+
+  /**
+   * Called when the form is canceled.
+   */
+  onCancel?: () => void;
+}
+
+export type FormUpdateMeta<T extends AnyProperties> = {
+  changed: FormHandler<T>['changed'];
+  isValid: boolean;
+};
+
+/**
+ * Form handler properties and methods.
+ */
+export type FormHandler<T extends AnyProperties> = Pick<FormHandlerProps<T>, 'schema' | 'autoSave'> & {
+  /** Initial values (which may not pass validation). */
+  values: Partial<T>;
+
+  /** Map of changed fields. */
+  changed: Record<JsonPath, boolean>;
+  // TODO(burdon): How is this different from above?
+  touched: Record<JsonPath, boolean>;
+
+  /** Map of error strings. */
+  errors: Record<JsonPath, string>;
+
+  /** Whether the form can be saved (i.e., data is valid). */
+  isValid: boolean;
+  // TODO(burdon): Why is this needed separately from isValid?
+  canSave: boolean;
+
+  onSave: () => void;
+  onCancel: () => void;
+
+  //
+  // Form field state management
+  //
+
+  getStatus: (path: string | (string | number)[]) => FormFieldStatus;
+  getValue: <V>(path: (string | number)[]) => V | undefined;
+  onBlur: (path: (string | number)[]) => void;
+  onValueChange: <V>(path: (string | number)[], type: SchemaAST.AST, value: V) => void;
+};
+
+/**
+ * Creates a hook for managing form state, including values, validation, and submission.
+ * Deeply integrated with `@dxos/schema` for schema-based validation.
+ */
+export const useFormHandler = <T extends AnyProperties>({
+  schema,
+  autoSave,
+  values: valuesProp,
+  defaultValues: defaultValuesProp,
+  onValuesChanged,
+  onValidate,
+  onSave,
+  onCancel,
+  ...props
+}: FormHandlerProps<T>): FormHandler<T> => {
+  const [changed, setChanged] = useState<Record<JsonPath, boolean>>({});
+  const [touched, setTouched] = useState<Record<JsonPath, boolean>>({});
+  const [errors, setErrors] = useState<Record<JsonPath, string>>({});
+  const [saving, setSaving] = useState(false);
+  const defaultValues = useDefaultValue<Partial<T>>(defaultValuesProp, () => ({}));
+  const [values$, setValues] = useControllableState<Partial<T>>({
+    prop: valuesProp,
+    defaultProp: defaultValues,
+    onChange: () => {
+      setValues(valuesProp ?? defaultValues);
+      setChanged({});
+      setTouched({});
+      setErrors({});
+      setSaving(false);
+    },
+  });
+  // TODO(wittjosiah): Upgrade @radix-ui/react-use-controllable-state.
+  const values = values$ as Partial<T>;
+
+  // Validate.
+  const validate = useCallback(
+    (values: Partial<T>): values is T => {
+      if (!schema) {
+        return false;
+      }
+
+      let errors: ValidationError[] = validateSchema(schema, values) ?? [];
+      log('validate', { values, errors });
+      if (errors.length === 0 && onValidate) {
+        const validatedValues = values as T;
+        errors = onValidate(validatedValues) ?? [];
+      }
+
+      setErrors(flatMap(errors));
+      const valid = errors.length === 0;
+      return valid;
+    },
+    [schema, onValidate],
+  );
+
+  // Validate on schema change.
+  const [schemaChanged, setSchemaChanged] = useState(false);
+  useEffect(() => setSchemaChanged(true), [schema]);
+  useEffect(() => {
+    if (schemaChanged) {
+      validate(values);
+      setSchemaChanged(false);
+    }
+  }, [validate, values, schemaChanged]);
+
+  const isValid = useMemo(() => {
+    return Object.keys(errors).length === 0;
+  }, [errors]);
+
+  /**
+   * NOTE: We can submit if there is no touched field that has an error.
+   * If there's a validation message visible in the form, submit should be disabled.
+   */
+  const canSave = useMemo(
+    () =>
+      !saving &&
+      // Check if any error paths that are touched have errors.
+      !Object.entries(touched).some(
+        ([path, isTouched]) =>
+          isTouched &&
+          Object.keys(errors).some(
+            (errorPath) => errorPath === path || errorPath.startsWith(`${path}.`) || errorPath.startsWith(`${path}[`),
+          ),
+      ),
+    [touched, errors, saving],
+  );
+
+  const handleSave = useCallback(async () => {
+    if (validate(values)) {
+      setSaving(true);
+      try {
+        await onSave?.(values, { changed, isValid });
+      } finally {
+        setSaving(false);
+      }
+    }
+  }, [values, validate, onSave, changed, isValid]);
+
+  const handleCancel = useCallback(() => {
+    onCancel?.();
+  }, [onCancel]);
+
+  //
+  // Fields.
+  //
+
+  const getStatus = useCallback<FormHandler<T>['getStatus']>(
+    (path) => {
+      const jsonPath = Array.isArray(path) ? createJsonPath(path) : path;
+      const [_, error] =
+        Object.entries(errors).find(
+          ([errorPath]) =>
+            errorPath === jsonPath || errorPath.startsWith(`${jsonPath}.`) || errorPath.startsWith(`${jsonPath}[`),
+        ) ?? [];
+
+      // Only show errors for touched fields.
+      const isTouched = touched[jsonPath as JsonPath];
+      if (!isTouched) {
+        return {
+          status: undefined,
+          error: undefined,
+        };
+      }
+
+      return {
+        status: error ? 'error' : undefined,
+        error: error ? (error ?? undefined) : undefined,
+      };
+    },
+    [errors, touched],
+  );
+
+  const getValue = useCallback<FormHandler<T>['getValue']>(
+    (path) => {
+      return getValue$(values, createJsonPath(path));
+    },
+    [values],
+  );
+
+  const onValueChange = useCallback<FormHandler<T>['onValueChange']>(
+    (path, type, value) => {
+      log('onValueChange', { path, value });
+
+      const jsonPath = createJsonPath(path);
+      let parsedValue = value as any;
+      try {
+        if (type._tag === 'NumberKeyword') {
+          parsedValue = parseFloat(value as string) || 0;
+        }
+      } catch (err) {
+        log.catch(err);
+        parsedValue = undefined;
+      }
+
+      // Update.
+      // For ECHO objects, mutate in place via Obj.change(); for plain objects, spread to create new reference.
+      const newValues = Obj.isObject(values)
+        ? (setValueEchoAware(values, jsonPath, parsedValue), values)
+        : { ...setValue$(values, jsonPath, parsedValue) };
+      setValues(newValues);
+
+      // TODO(burdon): Check value has changed from original.
+      const newChanged = { [jsonPath]: true };
+      setChanged({ ...changed, ...newChanged });
+
+      // Validate.
+      const isValid = validate(newValues);
+
+      // Callback.
+      onValuesChanged?.(newValues, { isValid, changed: newChanged });
+    },
+    [values, changed, validate, onValuesChanged],
+  );
+
+  const onBlur = useCallback(
+    async (path: (string | number)[]) => {
+      const jsonPath = createJsonPath(path);
+
+      // TODO(burdon): Check value has changed from original.
+      setTouched((touched) => ({ ...touched, [jsonPath]: true }));
+      const isValid = validate(values);
+
+      // Auto-save when a field is blurred and is valid.
+      if (Object.keys(changed).length > 0 && isValid && autoSave) {
+        await onSave?.(values as T, { changed, isValid });
+      }
+    },
+    [validate, values, changed, autoSave, onSave],
+  );
+
+  return useMemo<FormHandler<T>>(
+    () => ({
+      // State.
+      schema,
+      values,
+      errors,
+      touched,
+      changed,
+      isValid,
+      canSave,
+      autoSave,
+
+      // Actions.
+      onSave: handleSave,
+      onCancel: handleCancel,
+
+      // Field utils.
+      getStatus,
+      getValue,
+      onBlur,
+      onValueChange,
+
+      ...props,
+    }),
+    [
+      schema,
+      values,
+      errors,
+      touched,
+      changed,
+      canSave,
+      isValid,
+      getStatus,
+      getValue,
+      onBlur,
+      onValueChange,
+      onSave,
+      onCancel,
+    ],
+  );
+};
+
+const flatMap = (errors: ValidationError[]) => {
+  return errors.reduce(
+    (result, { path, message }) => {
+      // Convert the validation error path format to our JsonPath format.
+      const jsonPath = fromEffectValidationPath(path);
+      if (!(jsonPath in result)) {
+        result[jsonPath] = message;
+      }
+      return result;
+    },
+    {} as Record<JsonPath, string>,
+  );
+};

package/src/hooks/useKeyHandler.tsx

@@ -0,0 +1,37 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useCallback, useEffect } from 'react';
+
+import { addEventListener } from '@dxos/async';
+
+import { type FormHandler } from './useFormHandler';
+
+/**
+ * Key handler.
+ */
+export const useKeyHandler = (formElement: HTMLDivElement | null, form: FormHandler<any>) => {
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent) => {
+      switch (event.key) {
+        case 'Enter': {
+          if (event.metaKey && form.canSave) {
+            form.onSave();
+          }
+          break;
+        }
+      }
+    },
+    [form.isValid, form.canSave, form.onSave, form.autoSave],
+  );
+
+  useEffect(() => {
+    if (!formElement) {
+      return;
+    }
+
+    // TODO(burdon): Move to @dxos/dom-util.
+    return addEventListener(formElement, 'keydown', handleKeyDown);
+  }, [formElement, handleKeyDown]);
+};

package/src/translations.ts

@@ -4,7 +4,7 @@
 
 import { type Resource } from '@dxos/react-ui';
 
-export const translationKey = 'react-ui-form';
+export const translationKey = '@dxos/react-ui-form';
 
 export const translations = [
   {
@@ -15,7 +15,7 @@ export const translations = [
         'empty readonly ref field label': '(none)',
 
         // TODO(burdon): Standardize field/property.
-        'button add property': 'Add property',
+        'add property button label': 'Add property',
         'field property label': 'Property',
         'field property placeholder': 'Property name',
         'field format label': 'Type',
@@ -32,9 +32,12 @@ export const translations = [
         'ref field placeholder_one': 'Select…',
         'ref field placeholder_other': 'Select items…',
 
-        // TODO(burdon): Factor out?
-        'button cancel': 'Cancel',
-        'button save': 'Save',
+        'example placeholder': 'Example',
+        'latitude placeholder': 'Latitude (e.g., 40.7128)',
+        'longitude placeholder': 'Longitude (e.g., -74.0060)',
+
+        'cancel button label': 'Cancel',
+        'save button label': 'Save',
 
         // FormatEnum
         'format boolean': 'Boolean',
@@ -66,11 +69,11 @@ export const translations = [
         'format url': 'URL',
         'format uuid': 'UUID',
 
-        // GeoPointInput.
+        // GeoPointField.
         'latitude label': 'Latitude',
         'longitude label': 'Longitude',
 
-        // SelectOptionsInput.
+        // SelectOptionsField.
         'select option label': 'Label',
         'select option label placeholder': 'Option label',
         'select option color': 'Color',
@@ -78,9 +81,8 @@ export const translations = [
         'select option add': 'Add option',
 
         // System schema message.
-        'system schema title': 'System record type',
-        'system schema description':
-          'This is a system record type and cannot be modified, though the view can still be configured.',
+        'system schema title': 'System type',
+        'system schema description': 'System type: cannot add or remove fields.',
       },
     },
   },

package/src/util/echo.ts

@@ -0,0 +1,25 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Obj } from '@dxos/echo';
+import { type JsonPath, setValue as setValuePlain, splitJsonPath } from '@dxos/effect';
+
+/**
+ * Sets a value on an object, using Obj.change() if it's an ECHO object.
+ */
+// TODO(wittjosiah): Consider refactoring Form to not know about ECHO at all.
+//   Instead of directly mutating the values object, Form could work with a plain
+//   object copy and communicate all mutations through callbacks (e.g., onValuesChanged).
+//   The caller would then be responsible for applying changes to ECHO objects via
+//   Obj.change(). This would keep Form agnostic to the underlying data layer and
+//   avoid coupling react-ui-form to @dxos/echo.
+export const setValueEchoAware = <T extends object>(obj: T, path: JsonPath, value: any): T => {
+  if (Obj.isObject(obj)) {
+    Obj.change(obj, (mutableObj) => {
+      Obj.setValue(mutableObj, splitJsonPath(path), value);
+    });
+    return obj;
+  }
+  return setValuePlain(obj, path, value);
+};

package/src/util/field.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { FormatEnum, GeoLocation, TypeEnum } from '@dxos/echo/internal';
+import { Format, GeoLocation, TypeEnum } from '@dxos/echo/internal';
 import { type ValidationError } from '@dxos/schema';
 
 /**
@@ -13,7 +13,7 @@ import { type ValidationError } from '@dxos/schema';
  */
 export type ParseProps = {
   type?: TypeEnum;
-  format?: FormatEnum;
+  format?: Format.TypeFormat;
   value: any;
 };
 
@@ -57,31 +57,31 @@ export const parseValue = ({ type, format, value }: ParseProps) => {
   }
 
   switch (format) {
-    case FormatEnum.Boolean:
+    case Format.TypeFormat.Boolean:
       return parseScalar(TypeEnum.Boolean);
 
-    case FormatEnum.Number:
-    case FormatEnum.Percent:
-    case FormatEnum.Currency:
+    case Format.TypeFormat.Number:
+    case Format.TypeFormat.Percent:
+    case Format.TypeFormat.Currency:
       return parseScalar(TypeEnum.Number);
 
-    case FormatEnum.String:
-    case FormatEnum.Markdown: {
+    case Format.TypeFormat.String:
+    case Format.TypeFormat.Markdown: {
       return parseScalar(TypeEnum.String);
     }
 
-    case FormatEnum.Ref:
-      throw new Error(`unexpected format: ${FormatEnum.Ref}`);
+    case Format.TypeFormat.Ref:
+      throw new Error(`unexpected format: ${Format.TypeFormat.Ref}`);
 
-    case FormatEnum.DateTime:
-    case FormatEnum.Date:
-    case FormatEnum.Time:
-    case FormatEnum.Timestamp: {
+    case Format.TypeFormat.DateTime:
+    case Format.TypeFormat.Date:
+    case Format.TypeFormat.Time:
+    case Format.TypeFormat.Timestamp: {
       const date = new Date(value as string | number);
       return isNaN(date.getTime()) ? null : date;
     }
 
-    case FormatEnum.GeoPoint: {
+    case Format.TypeFormat.GeoPoint: {
       // Parse string in format "lat,long" to GeoPoint [longitude, latitude].
       if (typeof value === 'string') {
         // Only keep digits, decimal points, minus signs, and commas.
@@ -108,23 +108,23 @@ export const parseValue = ({ type, format, value }: ParseProps) => {
 // TODO(burdon): Type and format.
 export type CellClassesForFieldTypeProps = {
   type?: TypeEnum;
-  format?: FormatEnum;
+  format?: Format.TypeFormat;
 };
 
 export const cellClassesForFieldType = ({ type, format }: CellClassesForFieldTypeProps): string[] | undefined => {
   switch (format || type) {
-    case FormatEnum.Markdown:
+    case Format.TypeFormat.Markdown:
       return undefined;
-    case FormatEnum.Time:
-    case FormatEnum.Timestamp:
-    case FormatEnum.DateTime:
-    case FormatEnum.Date:
-    case FormatEnum.Duration:
+    case Format.TypeFormat.Time:
+    case Format.TypeFormat.Timestamp:
+    case Format.TypeFormat.DateTime:
+    case Format.TypeFormat.Date:
+    case Format.TypeFormat.Duration:
       return ['font-mono', 'text-right'];
-    case FormatEnum.Currency:
+    case Format.TypeFormat.Currency:
       return ['text-right'];
-    case FormatEnum.JSON:
-    case FormatEnum.DID:
+    case Format.TypeFormat.JSON:
+    case Format.TypeFormat.DID:
       return ['font-mono'];
     case TypeEnum.Number:
     case TypeEnum.Boolean:

package/src/util/formatting.ts

@@ -4,11 +4,11 @@
 
 import { format as formatDate } from 'date-fns/format';
 
-import { FormatEnum, GeoLocation, TypeEnum } from '@dxos/echo/internal';
+import { Format, GeoLocation, TypeEnum } from '@dxos/echo/internal';
 
 type ValueFormatProps = {
   type: TypeEnum;
-  format?: FormatEnum | undefined;
+  format?: Format.TypeFormat | undefined;
   value: any;
   locale?: string | undefined;
 };
@@ -41,20 +41,20 @@ export const formatForDisplay = ({ type, format, value, locale = undefined }: Va
   }
 
   switch (format) {
-    case FormatEnum.Boolean: {
+    case Format.TypeFormat.Boolean: {
       return formatScalar(TypeEnum.Boolean);
     }
-    case FormatEnum.Number: {
+    case Format.TypeFormat.Number: {
       return formatScalar(TypeEnum.Number);
     }
-    case FormatEnum.String:
-    case FormatEnum.Ref: {
+    case Format.TypeFormat.String:
+    case Format.TypeFormat.Ref: {
       return formatScalar(TypeEnum.String);
     }
-    case FormatEnum.Percent: {
+    case Format.TypeFormat.Percent: {
       return `${(value as number) * 100}%`;
     }
-    case FormatEnum.Currency: {
+    case Format.TypeFormat.Currency: {
       // TODO(burdon): Get from property annotation.
       return (value as number).toLocaleString(locale, {
         style: 'currency',
@@ -63,28 +63,28 @@ export const formatForDisplay = ({ type, format, value, locale = undefined }: Va
         maximumFractionDigits: 2,
       });
     }
-    case FormatEnum.Date: {
+    case Format.TypeFormat.Date: {
       try {
         return formatDate(new Date(value as number), 'yyyy-MM-dd');
       } catch (error) {
         return 'Invalid Date';
       }
     }
-    case FormatEnum.Time: {
+    case Format.TypeFormat.Time: {
       try {
         return formatDate(new Date(value as number), 'HH:mm:ss');
       } catch (error) {
         return 'Invalid Time';
       }
     }
-    case FormatEnum.DateTime: {
+    case Format.TypeFormat.DateTime: {
       try {
         return formatDate(new Date(value as number), 'yyyy-MM-dd HH:mm:ss');
       } catch (error) {
         return 'Invalid DateTime';
       }
     }
-    case FormatEnum.GeoPoint: {
+    case Format.TypeFormat.GeoPoint: {
       if (value === null || value === undefined) {
         return '';
       }
@@ -125,31 +125,31 @@ export const formatForEditing = ({ type, format, value, locale = undefined }: Va
   }
 
   switch (format) {
-    case FormatEnum.Boolean:
-    case FormatEnum.Number:
-    case FormatEnum.String:
-    case FormatEnum.Ref: {
+    case Format.TypeFormat.Boolean:
+    case Format.TypeFormat.Number:
+    case Format.TypeFormat.String:
+    case Format.TypeFormat.Ref: {
       return formatScalar(type);
     }
-    case FormatEnum.Percent: {
+    case Format.TypeFormat.Percent: {
       return String(value * 100);
     }
-    case FormatEnum.Currency: {
+    case Format.TypeFormat.Currency: {
       return String(value);
     }
-    case FormatEnum.DateTime: {
+    case Format.TypeFormat.DateTime: {
       const date = new Date(value as number);
       return date.toISOString();
     }
-    case FormatEnum.Date: {
+    case Format.TypeFormat.Date: {
       const date = new Date(value as number);
       return date.toISOString().split('T')[0];
     }
-    case FormatEnum.Time: {
+    case Format.TypeFormat.Time: {
       const date = new Date(value as number);
       return date.toISOString().split('T')[1].split('.')[0];
     }
-    case FormatEnum.GeoPoint: {
+    case Format.TypeFormat.GeoPoint: {
       // Handle null or undefined
       if (value === null || value === undefined) {
         return '';