@dxos/react-ui-form 0.8.4-main.c4373fc → 0.8.4-main.c85a9c8dae

package/src/components/index.ts

@@ -2,8 +2,8 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './ControlSection';
 export * from './FieldEditor';
 export * from './Form';
 export * from './ObjectPicker';
+export * from './Settings';
 export * from './ViewEditor';

package/src/components/testing.tsx

@@ -5,25 +5,30 @@
 import React, { type PropsWithChildren } from 'react';
 
 import { type ThemedClassName } from '@dxos/react-ui';
-import { Card } from '@dxos/react-ui-stack';
 import { JsonFilter } from '@dxos/react-ui-syntax-highlighter';
-import { mx, textBlockWidth } from '@dxos/react-ui-theme';
+import { mx, textBlockWidth } from '@dxos/ui-theme';
 
 type TestLayoutProps = ThemedClassName<PropsWithChildren<{ json?: any }>>;
 
 export const TestLayout = ({ classNames, children, json }: TestLayoutProps) => {
   return (
-    <div className='is-full bs-full grid grid-cols-[1fr_1fr] gap-2 overflow-hidden'>
-      <div className={mx('p-4 justify-center overflow-y-auto', classNames)}>{children}</div>
-      <JsonFilter data={json} classNames='is-full text-xs' testId='debug' />
+    <div className='w-full h-full grid grid-cols-[1fr_1fr] p-4 gap-4 overflow-hidden'>
+      <TestPanel classNames={['flex flex-col h-full overflow-y-auto', classNames]}>{children}</TestPanel>
+      <TestPanel classNames={'overflow-hidden'}>
+        <JsonFilter testId='debug' data={json} classNames='h-full text-xs' />
+      </TestPanel>
     </div>
   );
 };
 
 type TestPanelProps = ThemedClassName<PropsWithChildren>;
 
-export const TestPanel = ({ classNames, children }: TestPanelProps) => {
-  return <Card.StaticRoot classNames={[textBlockWidth, classNames]}>{children}</Card.StaticRoot>;
+const TestPanel = ({ classNames, children }: TestPanelProps) => {
+  return (
+    <div role='none' className={mx(['h-full bg-modal-surface rounded-md', textBlockWidth, classNames])}>
+      {children}
+    </div>
+  );
 };
 
 // Symbol for accessing debug objects in tests.

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 { 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/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: