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

package/src/hooks/useFormHandler.ts

@@ -0,0 +1,348 @@
+//
+// 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, getValue as getValue$, setValue as setValue$ } from '@dxos/echo/internal';
+import { type JsonPath, createJsonPath, fromEffectValidationPath } 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: () => {
+      setValues(valuesProp ?? defaultValues);
+      setChanged({});
+      setTouched({});
+      setErrors({});
+      setSaving(false);
+    },
+  });
+
+  // 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.
+      const newValues = { ...setValue$(values, jsonPath, parsedValue) };
+      setValues(newValues);
+
+      // TODO(burdon): Check value has changed from original.
+      const newChanged = { ...changed, [jsonPath]: true };
+      setChanged({ ...changed, [jsonPath]: true });
+
+      // 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/hooks/useQueryRefOptions.ts

@@ -2,52 +2,69 @@
 // Copyright 2025 DXOS.org
 //
 
-import { useEffect, useState } from 'react';
+import { useCallback, useState } from 'react';
 
-import { type TypeAnnotation } from '@dxos/echo-schema';
 import { type DXN } from '@dxos/keys';
 import { log } from '@dxos/log';
-import { type TagPickerItemData } from '@dxos/react-ui-tag-picker';
+import { useAsyncEffect } from '@dxos/react-ui';
+import { type Palette } from '@dxos/react-ui-types';
 import { type MaybePromise } from '@dxos/util';
 
-export type RefOption = { dxn: DXN; label?: string };
-export type QueryRefOptions = (type: TypeAnnotation) => MaybePromise<RefOption[]>;
+export type RefOption = {
+  dxn: DXN;
+  label?: string;
+};
+
+export type QueryRefOptions = ({ typename }: { typename: string }) => MaybePromise<RefOption[]>;
 
-type UseQueryRefOptionsProps = { refTypeInfo: TypeAnnotation | undefined; onQueryRefOptions?: QueryRefOptions };
+export type QueryTag = {
+  id: string;
+  label: string;
+  hue?: Palette;
+};
+
+type UseQueryRefOptionsProps = {
+  typename?: string;
+  onQueryRefOptions?: QueryRefOptions;
+};
 
 /**
  * Hook to query reference options based on type information.
  * Used internally within forms to fetch and format reference options for reference fields.
  */
-export const useQueryRefOptions = ({ refTypeInfo, onQueryRefOptions }: UseQueryRefOptionsProps) => {
-  const [options, setOptions] = useState<TagPickerItemData[]>([]);
+export const useQueryRefOptions = ({ typename, onQueryRefOptions }: UseQueryRefOptionsProps) => {
+  const [options, setOptions] = useState<QueryTag[]>([]);
   const [loading, setLoading] = useState(false);
+  const [state, setState] = useState({});
+  const update = useCallback(() => setState({}), []);
 
-  useEffect(() => {
-    if (!refTypeInfo || !onQueryRefOptions) {
+  useAsyncEffect(async () => {
+    if (!typename || !onQueryRefOptions) {
       return;
     }
 
-    const fetchOptions = async () => {
-      setLoading(true);
-      try {
-        const fetchedOptions = await onQueryRefOptions(refTypeInfo);
-        setOptions(
-          fetchedOptions.map((option) => {
-            const dxn = option.dxn.toString() as string;
-            return { id: dxn, label: option.label ?? dxn, hue: 'neutral' as any };
-          }),
-        );
-      } catch (error) {
-        log.error('Failed to fetch ref options:', error);
-        setOptions([]);
-      } finally {
-        setLoading(false);
-      }
-    };
-
-    void fetchOptions();
-  }, [refTypeInfo, onQueryRefOptions]);
-
-  return { options, loading };
+    setLoading(true);
+    try {
+      // TODO(wittjosiah): This should be a reactive query so that the options are always up to date.
+      const options = await onQueryRefOptions({ typename });
+      log('options', { options: options.length });
+      setOptions(
+        options.map((option) => {
+          const dxn = option.dxn.toString() as string;
+          return {
+            id: dxn,
+            label: option.label ?? dxn,
+            hue: 'neutral' as any,
+          };
+        }),
+      );
+    } catch (error) {
+      log.error('Failed to fetch ref options:', error);
+      setOptions([]);
+    } finally {
+      setLoading(false);
+    }
+  }, [typename, onQueryRefOptions, state]);
+
+  return { options, update, loading };
 };

package/src/hooks/useRefQueryOptions.ts

@@ -0,0 +1,37 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useCallback } from 'react';
+
+import { Obj } from '@dxos/echo';
+import { Filter, type Space } from '@dxos/react-client/echo';
+import { isNonNullable } from '@dxos/util';
+
+import { type QueryRefOptions } from './useQueryRefOptions';
+
+type UseRefQueryOptionsProps = { space?: Space };
+
+export const useRefQueryOptions = ({ space }: UseRefQueryOptionsProps): QueryRefOptions => {
+  return useCallback<QueryRefOptions>(
+    async ({ typename }) => {
+      if (!space) {
+        return [];
+      }
+
+      const query = space.db.query(Filter.typename(typename));
+      const objects = await query.run();
+      return objects
+        .map((object) => {
+          const dxn = Obj.getDXN(object);
+          if (!dxn) {
+            return undefined;
+          }
+
+          return { dxn, label: Obj.getLabel(object) ?? object?.id ?? '' };
+        })
+        .filter(isNonNullable);
+    },
+    [space],
+  );
+};

package/src/translations.ts

@@ -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',
@@ -25,10 +25,19 @@ export const translations = [
         '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…',
 
-        // 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',
@@ -43,7 +52,7 @@ export const translations = [
         'format hostname': 'Hostname',
         'format integer': 'Integer',
         'format json': 'JSON',
-        'format latlng': 'Geopoint',
+        'format lnglat': 'Geopoint',
         'format markdown': 'Markdown',
         'format percent': 'Percent',
         'format ref': 'Reference',
@@ -60,11 +69,11 @@ export const translations = [
         'format url': 'URL',
         'format uuid': 'UUID',
 
-        // Placeholders.
-        'placeholder latitude': 'Latitude',
-        'placeholder longitude': 'Longitude',
+        // GeoPointField.
+        'latitude label': 'Latitude',
+        'longitude label': 'Longitude',
 
-        // SelectOptionsInput.
+        // SelectOptionsField.
         'select option label': 'Label',
         'select option label placeholder': 'Option label',
         'select option color': 'Color',
@@ -72,8 +81,8 @@ export const translations = [
         'select option add': 'Add option',
 
         // System schema message.
-        'system schema title': 'System Schema',
-        'system schema description': 'This is a system schema and cannot be modified.',
+        'system schema title': 'System type',
+        'system schema description': 'System type: cannot add or remove fields.',
       },
     },
   },