@dxos/react-ui-form 0.8.4-main.72ec0f3 → 0.8.4-main.74a063c4e0

package/src/hooks/index.ts

@@ -2,6 +2,5 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './useForm';
-export * from './useRefQueryLookupHandler';
-export * from './useQueryRefOptions';
+export * from './useFormHandler';
+export * from './useKeyHandler';

package/src/hooks/useFormHandler.ts

@@ -0,0 +1,380 @@
+//
+// 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 { type AnyProperties } from '@dxos/echo/internal';
+import { type JsonPath, createJsonPath, fromEffectValidationPath, getValue as getValue$ } 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';
+
+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: () => {
+      // Only reset when controlled: parent passed new values.
+      // Uncontrolled updates come from setValues in onValueChange.
+      if (valuesProp !== undefined) {
+        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);
+      const pathArray = path;
+      let parsedValue = value as any;
+      try {
+        if (type._tag === 'NumberKeyword') {
+          parsedValue = parseFloat(value as string) || 0;
+        }
+      } catch (err) {
+        log.catch(err);
+        parsedValue = undefined;
+      }
+
+      // Create merged values for validation and callback. Form never mutates; parent applies via onValuesChanged.
+      const newValues = mergeAtPath(values, pathArray as (string | number)[], parsedValue) as Partial<T>;
+
+      // TODO(burdon): Check value has changed from original.
+      const newChanged = { [jsonPath]: true };
+      setChanged((prev) => ({ ...prev, ...newChanged }));
+
+      // Validate.
+      const isValid = validate(newValues);
+
+      // Notify parent; parent is responsible for applying the change.
+      onValuesChanged?.(newValues, { isValid, changed: newChanged });
+
+      // For uncontrolled mode, update internal state. Controlled mode relies on parent to pass new values.
+      if (valuesProp === undefined) {
+        setValues(newValues);
+      }
+    },
+    [values, validate, onValuesChanged, valuesProp],
+  );
+
+  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,
+    ],
+  );
+};
+
+/**
+ * Creates a new object with value at path. Does not mutate source.
+ * Preserves arrays when path segments are numeric indices.
+ */
+const mergeAtPath = (obj: any, path: readonly (string | number)[], value: any): any => {
+  if (path.length === 0) {
+    return value;
+  }
+
+  const [head, ...rest] = path;
+  const child = rest.length === 0 ? value : mergeAtPath(obj?.[head], rest, value);
+
+  if (Array.isArray(obj)) {
+    const copy = [...obj];
+    copy[head as number] = child;
+    return copy;
+  }
+
+  return { ...obj, [head]: child };
+};
+
+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 { type RefObject, useCallback, useLayoutEffect } from 'react';
+
+import { addEventListener } from '@dxos/async';
+
+import { type FormHandler } from './useFormHandler';
+
+/**
+ * Key handler.
+ */
+export const useKeyHandler = (elRef: RefObject<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],
+  );
+
+  useLayoutEffect(() => {
+    const el = elRef.current;
+    if (!el) {
+      return;
+    }
+
+    return addEventListener(el, 'keydown', handleKeyDown);
+  }, [elRef, handleKeyDown]);
+};

package/src/translations.ts

@@ -4,82 +4,84 @@
 
 import { type Resource } from '@dxos/react-ui';
 
-export const translationKey = 'react-ui-form';
+export const translationKey = '@dxos/react-ui-form';
 
 export const translations = [
   {
     'en-US': {
       [translationKey]: {
-        'fields label': 'Fields',
-        'hidden fields label': 'Hidden Fields',
-        'empty readonly ref field label': '(none)',
+        'fields.label': 'Fields',
+        'hidden-fields.label': 'Hidden Fields',
+        'empty-readonly-ref-field.label': '(none)',
 
-        // TODO(burdon): Standardize field/property.
-        'add property button': 'Add property',
-        'field property label': 'Property',
-        'field property placeholder': 'Property name',
-        'field format label': 'Type',
-        'field path label': 'Field path',
-        'add field': 'Add field',
-        'delete field': 'Delete field',
-        'field limit reached': 'Maximum number of fields reached',
-        'boolean input true value': 'Yes',
-        'boolean input false value': 'No',
-        'show field label': 'Show field',
-        'hide field label': 'Hide field',
-        'delete field label': 'Delete field',
-        'ref field combobox input placeholder': 'Search…',
-        'ref field placeholder_one': 'Select…',
-        'ref field placeholder_other': 'Select items…',
+        'add-property-button.label': 'Add property',
+        'field-property.label': 'Property',
+        'field-property.placeholder': 'Property name',
+        'field-format.label': 'Type',
+        'field-path.label': 'Field path',
+        'add-field.button': 'Add field',
+        'boolean-input-true.value': 'Yes',
+        'boolean-input-false.value': 'No',
+        'show-field.label': 'Show field',
+        'hide-field.label': 'Hide field',
+        'delete-field.label': 'Delete field',
+        'ref-field-combobox-input.placeholder': 'Search…',
+        'ref-field.placeholder': 'Select…',
+        'ref-field.placeholder_one': 'Select…',
+        'ref-field.placeholder_other': 'Select items…',
+        'create-option.label': 'Create',
 
-        // TODO(burdon): Factor out?
-        'save button': 'Save',
+        'example.placeholder': 'Example',
+        'latitude.placeholder': 'Latitude (e.g., 40.7128)',
+        'longitude.placeholder': 'Longitude (e.g., -74.0060)',
 
-        // FormatEnum
-        'format boolean': 'Boolean',
-        'format currency': 'Currency',
-        'format date': 'Date',
-        'format date-time': 'DateTime',
-        'format did': 'DID',
-        'format duration': 'Duration',
-        'format dxn': 'DXN',
-        'format email': 'Email',
-        'format formula': 'Formula',
-        'format hostname': 'Hostname',
-        'format integer': 'Integer',
-        'format json': 'JSON',
-        'format lnglat': 'Geopoint',
-        'format markdown': 'Markdown',
-        'format percent': 'Percent',
-        'format ref': 'Reference',
-        'format regex': 'RegExp',
-        'format string': 'String',
-        'format single-select': 'Select',
-        'format multi-select': 'Multi-select',
-        'format text': 'Long text',
-        'format time': 'Time',
-        'format timestamp': 'Timestamp',
-        'format user': 'User',
-        'format number': 'Number',
-        'format uri': 'URI',
-        'format url': 'URL',
-        'format uuid': 'UUID',
+        'cancel-button.label': 'Cancel',
+        'save-button.label': 'Save',
 
-        // GeoPointInput.
-        'latitude label': 'Latitude',
-        'longitude label': 'Longitude',
+        // TypeFormat
+        'format.boolean.label': 'Boolean',
+        'format.currency.label': 'Currency',
+        'format.date.label': 'Date',
+        'format.date-time.label': 'DateTime',
+        'format.did.label': 'DID',
+        'format.duration.label': 'Duration',
+        'format.dxn.label': 'DXN',
+        'format.email.label': 'Email',
+        'format.formula.label': 'Formula',
+        'format.hostname.label': 'Hostname',
+        'format.integer.label': 'Integer',
+        'format.json.label': 'JSON',
+        'format.lnglat.label': 'Geopoint',
+        'format.markdown.label': 'Markdown',
+        'format.percent.label': 'Percent',
+        'format.ref.label': 'Reference',
+        'format.regex.label': 'RegExp',
+        'format.string.label': 'String',
+        'format.single-select.label': 'Select',
+        'format.multi-select.label': 'Multi-select',
+        'format.text.label': 'Long text',
+        'format.time.label': 'Time',
+        'format.timestamp.label': 'Timestamp',
+        'format.user.label': 'User',
+        'format.number.label': 'Number',
+        'format.uri.label': 'URI',
+        'format.url.label': 'URL',
+        'format.uuid.label': 'UUID',
 
-        // SelectOptionsInput.
-        'select option label': 'Label',
-        'select option label placeholder': 'Option label',
-        'select option color': 'Color',
-        'select option delete': 'Delete',
-        'select option add': 'Add option',
+        // GeoPointField.
+        'latitude.label': 'Latitude',
+        'longitude.label': 'Longitude',
+
+        // SelectOptionsField.
+        'select-option.label': 'Label',
+        'select-option-label.placeholder': 'Option label',
+        'select-option-delete.button': 'Delete',
+        'select-option-add.button': '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.',
+        'remove.button': 'Remove',
       },
     },
   },

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: