@dxos/react-ui-form 0.7.5-main.9d26e3a → 0.7.5-main.e9bb01b

package/src/components/Form/Form.tsx

@@ -2,29 +2,28 @@
 // Copyright 2024 DXOS.org
 //
 
-import { pipe } from 'effect';
-import { capitalize } from 'effect/String';
-import React, { useEffect, useMemo } from 'react';
+import React, { type ReactElement, useMemo } from 'react';
 
-import { AST, type BaseObject, S, type PropertyKey, type FormatEnum } from '@dxos/echo-schema';
-import { findNode, getDiscriminatedType, isDiscriminatedUnion, SimpleType } from '@dxos/effect';
-import { log } from '@dxos/log';
-import { IconButton, type ThemedClassName, useTranslation } from '@dxos/react-ui';
+import { type BaseObject, type S, type PropertyKey } from '@dxos/echo-schema';
+import { type ThemedClassName } from '@dxos/react-ui';
 import { mx } from '@dxos/react-ui-theme';
-import { getSchemaProperties, type SchemaProperty } from '@dxos/schema';
-import { isNotFalsy } from '@dxos/util';
+import { type SchemaProperty } from '@dxos/schema';
 
-import { SelectInput } from './Defaults';
-import { InputHeader, type InputComponent } from './Input';
-import { getInputComponent } from './factory';
-import { type FormHandler, type FormOptions, useForm } from '../../hooks';
-import { translationKey } from '../../translations';
+import { FormActions } from './FormActions';
+import { FormFields } from './FormContent';
+import { FormProvider } from './FormContext';
+import { type InputProps, type InputComponent } from './Input';
+import { type FormOptions } from '../../hooks';
 
-// TODO(burdon): Rename package react-ui-form; delete react-ui-card.
+export type PropsFilter<T extends BaseObject> = (props: SchemaProperty<T>[]) => SchemaProperty<T>[];
 
-const padding = 'px-2';
+export type ComponentLookup = (args: {
+  prop: string;
+  schema: S.Schema<any>;
+  inputProps: InputProps;
+}) => ReactElement | undefined;
 
-export type PropsFilter<T extends BaseObject> = (props: SchemaProperty<T>[]) => SchemaProperty<T>[];
+export type CustomInputMap = Partial<Record<string, InputComponent>>;
 
 export type FormProps<T extends BaseObject> = ThemedClassName<
   {
@@ -42,18 +41,15 @@ export type FormProps<T extends BaseObject> = ThemedClassName<
     autoSave?: boolean;
     testId?: string;
     onCancel?: () => void;
-
+    lookupComponent?: ComponentLookup;
     /**
      * Map of custom renderers for specific properties.
+     * Prefer lookupComponent for plugin specific input surfaces.
      */
-    Custom?: Partial<Record<string, InputComponent<T>>>;
+    Custom?: CustomInputMap;
   } & Pick<FormOptions<T>, 'schema' | 'onValuesChanged' | 'onValidate' | 'onSave'>
 >;
 
-/**
- * General purpose form component that displays field controls based on the given schema.
- */
-// TODO(burdon): Area to show general validation errors.
 export const Form = <T extends BaseObject>({
   classNames,
   schema,
@@ -68,319 +64,32 @@ export const Form = <T extends BaseObject>({
   onValidate,
   onSave,
   onCancel,
+  lookupComponent,
   Custom,
 }: FormProps<T>) => {
   const onValid = useMemo(() => (autoSave ? onSave : undefined), [autoSave, onSave]);
-  const { canSave, values, errors, handleSave, ...inputProps } = useForm<T>({
-    schema,
-    initialValues,
-    onValuesChanged,
-    onValidate,
-    onValid,
-    onSave,
-  });
-
-  // Filter and sort props.
-  // TODO(burdon): Move into useForm?
-  const properties = useMemo(() => {
-    const props = getSchemaProperties<T>(schema.ast, values);
-    const filtered = filter ? filter(props) : props;
-    const findIndex = (props: PropertyKey<T>[], prop: PropertyKey<T>) => {
-      const idx = props.findIndex((p) => p === prop);
-      return idx === -1 ? Infinity : idx;
-    };
-
-    return sort ? filtered.sort(({ name: a }, { name: b }) => findIndex(sort, a) - findIndex(sort, b)) : filtered;
-  }, [schema, filter, values]);
-
-  // TODO(burdon): Highlight in UX.
-  useEffect(() => {
-    if (errors && Object.keys(errors).length) {
-      log.warn('validation', { errors });
-    }
-  }, [errors]);
 
   return (
-    <div role='form' className={mx('flex flex-col w-full gap-2 py-2', classNames)} data-testid={testId}>
-      {properties
-        .map((property) => {
-          const { ast, name, type, format, title, description, examples, options, array } = property;
-          const key = [...path, name];
-          const label = title ?? pipe(name, capitalize);
-          const placeholder = examples?.length ? `Example: "${examples[0]}"` : description;
-
-          // Get generic input.
-          // TODO(ZaymonFC): We might need to switch this to using globs since we're now indexing into arrays.
-          let InputComponent = Custom?.[key.join('.')];
-          if (!InputComponent) {
-            // Select.
-            if (options) {
-              return (
-                <div key={name} role='none' className={padding}>
-                  <SelectInput
-                    type={type}
-                    format={format}
-                    property={name}
-                    disabled={readonly}
-                    label={label}
-                    options={options.map((option) => ({ value: option, label: String(option) }))}
-                    placeholder={placeholder}
-                    {...inputProps}
-                  />
-                </div>
-              );
-            }
-
-            InputComponent = getInputComponent<T>(type, format);
-
-            // TODO(ZaymonFC): Array handling is inelegant. We need to push this complexity down into SDK/Schema.
-            if (array) {
-              return (
-                <ArrayField
-                  key={name}
-                  name={name}
-                  type={type}
-                  array={true}
-                  label={label}
-                  ast={ast}
-                  values={values}
-                  format={format}
-                  readonly={readonly}
-                  placeholder={placeholder}
-                  inputProps={inputProps}
-                  Custom={Custom}
-                />
-              );
-            }
-          }
-
-          if (!InputComponent) {
-            // Recursively render form.
-            if (type === 'object') {
-              const baseNode = findNode(ast, isDiscriminatedUnion);
-              const typeLiteral = baseNode
-                ? getDiscriminatedType(baseNode, values[name] as any)
-                : findNode(ast, AST.isTypeLiteral);
-
-              if (typeLiteral) {
-                const schema = S.make(typeLiteral);
-                return (
-                  <div key={name} role='none'>
-                    <div className={padding}>{label}</div>
-                    <Form<any>
-                      schema={schema}
-                      path={key}
-                      values={values[name] ?? {}}
-                      onValuesChanged={(childValues) => {
-                        inputProps.onValueChange(name, 'object', childValues);
-                      }}
-                      Custom={Custom as any}
-                    />
-                  </div>
-                );
-              }
-            }
-
-            log('no renderer for property', { name, type });
-            return null;
-          }
-
-          return (
-            <div key={name} role='none' className={padding}>
-              <InputComponent
-                type={type}
-                format={format}
-                property={name}
-                disabled={readonly}
-                label={label}
-                placeholder={placeholder}
-                {...inputProps}
-              />
-            </div>
-          );
-        })
-        .filter(isNotFalsy)}
-      {(onCancel || onSave) && !autoSave && (
-        <FormActions onCancel={onCancel} onSubmit={handleSave} canSubmit={canSave} readonly={readonly} />
-      )}
-    </div>
-  );
-};
-
-type ArrayFieldProps<T extends BaseObject> = {
-  name: PropertyKey<T>;
-  type: SimpleType;
-  array: true;
-  label: string;
-  ast: AST.AST;
-  values: Record<string, any>;
-  format?: FormatEnum;
-  readonly?: boolean;
-  placeholder?: string;
-  inputProps: Pick<FormHandler<T>, 'getStatus' | 'getValue' | 'onValueChange' | 'onBlur'>;
-  Custom?: Partial<Record<string, InputComponent<T>>>;
-};
-
-const ArrayField = <T extends BaseObject>({
-  name,
-  type,
-  label,
-  ast,
-  values,
-  format,
-  readonly,
-  placeholder,
-  inputProps,
-  Custom,
-}: ArrayFieldProps<T>) => {
-  const { t } = useTranslation(translationKey);
-  const arrayValues = (values[name] ?? []) as any[];
-  const key = [name];
-
-  // TODO(ZaymonFC): Should this unwrapping happen at a lower level?
-  const tupleType = findNode(ast, AST.isTupleType);
-  const elementType = (tupleType as AST.TupleType | undefined)?.rest[0]?.type;
-
-  if (type === 'object' && elementType) {
-    const baseNode = findNode(elementType, isDiscriminatedUnion);
-    const typeLiteral = baseNode
-      ? getDiscriminatedType(baseNode, values[name] as any)
-      : findNode(elementType, AST.isTypeLiteral);
-
-    if (typeLiteral) {
-      const schema = S.make(typeLiteral);
-
-      return (
-        <div key={name} role='none' className={mx(padding)}>
-          <InputHeader>{label}</InputHeader>
-          <div role='none' className='flex flex-col gap-1'>
-            {arrayValues.map((value, index) => {
-              return (
-                <div key={index} role='none' className='flex items-center gap-1'>
-                  <div role='none' className='flex-1'>
-                    <Form<any>
-                      schema={schema}
-                      path={[...key, `[${index}]`]}
-                      values={value}
-                      onValuesChanged={(childValues) => {
-                        const newValues = [...arrayValues];
-                        newValues[index] = childValues;
-                        inputProps.onValueChange(name, 'object', newValues);
-                      }}
-                      Custom={Custom as any}
-                    />
-                  </div>
-                  <IconButton
-                    icon='ph--trash--regular'
-                    iconOnly
-                    label={t('button remove')}
-                    onClick={() => {
-                      const newValues = arrayValues.filter((_, i) => i !== index);
-                      inputProps.onValueChange(name, type, newValues);
-                    }}
-                  />
-                </div>
-              );
-            })}
-          </div>
-          <div role='none' className='flex justify-between items-center plb-1'>
-            <IconButton
-              icon='ph--plus--regular'
-              iconOnly
-              label={t('button add')}
-              onClick={() => {
-                const newValues = [...arrayValues, {}];
-                inputProps.onValueChange(name, type, newValues);
-              }}
-            />
-          </div>
-        </div>
-      );
-    }
-    return (
-      <div key={name} role='none'>
-        Nested form not supported in arrays, yet.
-      </div>
-    );
-  }
-
-  const InputComponent = getInputComponent<T>(type, format);
-  if (!InputComponent) {
-    return null;
-  }
-
-  return (
-    <div role='none' key='meta-input' className={mx(padding)}>
-      <InputHeader>{label}</InputHeader>
-      <div role='none' className='flex flex-col gap-1'>
-        {arrayValues.map((_, index) => (
-          <div key={index} role='none' className='flex items-start gap-1'>
-            <div role='none' className='flex-1'>
-              <InputComponent
-                type={type}
-                format={format}
-                label={label}
-                inputOnly
-                property={`${name}[${index}]` as PropertyKey<T>}
-                disabled={readonly}
-                placeholder={placeholder}
-                {...inputProps}
-              />
-            </div>
-            <IconButton
-              icon='ph--trash--regular'
-              iconOnly
-              label={t('button remove')}
-              onClick={() => {
-                const newValues = arrayValues.filter((_, i) => i !== index);
-                inputProps.onValueChange(name, type, newValues);
-              }}
-            />
-          </div>
-        ))}
-      </div>
-      <div role='none' className='flex justify-between items-center plb-1'>
-        <IconButton
-          icon='ph--plus--regular'
-          iconOnly
-          label={t('button add')}
-          onClick={() => {
-            const newValues = [...arrayValues, SimpleType.getDefaultValue(type)];
-            inputProps.onValueChange(name, type, newValues);
-          }}
+    <FormProvider
+      schema={schema}
+      initialValues={initialValues}
+      onValuesChanged={onValuesChanged}
+      onValidate={onValidate}
+      onValid={onValid}
+      onSave={onSave}
+    >
+      <div role='none' className={mx('p-2', classNames)} data-testid={testId}>
+        <FormFields
+          schema={schema}
+          path={path}
+          readonly={readonly}
+          filter={filter}
+          sort={sort}
+          lookupComponent={lookupComponent}
+          Custom={Custom}
         />
+        {(onCancel || onSave) && !autoSave && <FormActions onCancel={onCancel} readonly={readonly} />}
       </div>
-    </div>
-  );
-};
-
-type FormActionsProps = {
-  readonly?: boolean;
-  canSubmit: boolean;
-  onCancel?: () => void;
-  onSubmit: () => void;
-};
-
-export const FormActions = ({ onCancel, onSubmit, canSubmit, readonly }: FormActionsProps) => {
-  const { t } = useTranslation(translationKey);
-
-  return (
-    <div role='none' className='flex justify-center'>
-      <div role='none' className={mx(onCancel && !readonly && 'grid grid-cols-2 gap-2')}>
-        {onCancel && !readonly && (
-          <IconButton data-testid='cancel-button' icon='ph--x--regular' label={t('button cancel')} onClick={onCancel} />
-        )}
-        {onSubmit && (
-          <IconButton
-            type='submit'
-            data-testid='save-button'
-            disabled={!canSubmit}
-            icon='ph--check--regular'
-            label={t('button save')}
-            onClick={onSubmit}
-          />
-        )}
-      </div>
-    </div>
+    </FormProvider>
   );
 };

package/src/components/Form/FormActions.tsx

@@ -0,0 +1,41 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { IconButton, useTranslation } from '@dxos/react-ui';
+import { mx } from '@dxos/react-ui-theme';
+
+import { useFormContext } from './FormContext';
+import { translationKey } from '../../translations';
+
+export type FormActionsProps = {
+  readonly?: boolean;
+  onCancel?: () => void;
+};
+
+export const FormActions = ({ onCancel, readonly }: FormActionsProps) => {
+  const { t } = useTranslation(translationKey);
+  const { canSave, handleSave } = useFormContext();
+
+  return (
+    <div role='none' className='flex justify-center'>
+      <div role='none' className={mx(onCancel && !readonly && 'grid grid-cols-2 gap-2')}>
+        {onCancel && !readonly && (
+          <IconButton data-testid='cancel-button' icon='ph--x--regular' label={t('button cancel')} onClick={onCancel} />
+        )}
+        {handleSave && (
+          <IconButton
+            type='submit'
+            data-testid='save-button'
+            disabled={!canSave}
+            icon='ph--check--regular'
+            label={t('button save')}
+            onClick={handleSave}
+          />
+        )}
+      </div>
+    </div>
+  );
+};

package/src/components/Form/FormContent.tsx

@@ -0,0 +1,173 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { pipe } from 'effect';
+import { capitalize } from 'effect/String';
+import React, { useMemo } from 'react';
+
+import { AST, S } from '@dxos/echo-schema';
+import { createJsonPath, findNode, getDiscriminatedType, isDiscriminatedUnion } from '@dxos/effect';
+import { mx } from '@dxos/react-ui-theme';
+import { getSchemaProperties, type SchemaProperty } from '@dxos/schema';
+import { isNotFalsy } from '@dxos/util';
+
+import { ArrayField } from './ArrayField';
+import { SelectInput } from './Defaults';
+import { type ComponentLookup } from './Form';
+import { useInputProps, useFormValues } from './FormContext';
+import { type InputComponent } from './Input';
+import { getInputComponent } from './factory';
+
+export type FormContentProps = {
+  schema: S.Schema.All;
+  path?: (string | number)[];
+  filter?: (props: SchemaProperty<any>[]) => SchemaProperty<any>[];
+  sort?: string[];
+  readonly?: boolean;
+  lookupComponent?: ComponentLookup;
+  Custom?: Partial<Record<string, InputComponent>>;
+};
+
+export type FormFieldProps = {
+  property: SchemaProperty<any>;
+  path?: (string | number)[];
+  readonly?: boolean;
+  /** Used to indicate if input should be presented inline (e.g. for array items). */
+  inline?: boolean;
+  lookupComponent?: ComponentLookup;
+  Custom?: Partial<Record<string, InputComponent>>;
+};
+
+export const FormField = ({ property, path, readonly, inline, lookupComponent, Custom }: FormFieldProps) => {
+  const inputProps = useInputProps(path);
+  const { ast, name, type, format, title, description, options, examples, array } = property;
+
+  const label = useMemo(() => title ?? pipe(name, capitalize), [title, name]);
+  const placeholder = useMemo(
+    () => (examples?.length ? `Example: "${examples[0]}"` : description),
+    [examples, description],
+  );
+
+  const FoundComponent = lookupComponent?.({
+    prop: name,
+    schema: S.make(ast),
+    inputProps: {
+      type,
+      format,
+      label,
+      disabled: readonly,
+      placeholder,
+      ...inputProps,
+    },
+  });
+
+  if (FoundComponent) {
+    return <div role='none'>{FoundComponent}</div>;
+  }
+
+  const jsonPath = createJsonPath(path ?? []);
+  const CustomComponent = Custom?.[jsonPath];
+  if (CustomComponent) {
+    return (
+      // TODO(ZaymonFC): We should try to remove this div wrapper.
+      <div role='none'>
+        <CustomComponent
+          type={type}
+          format={format}
+          label={label}
+          inputOnly={inline}
+          placeholder={placeholder}
+          disabled={readonly}
+          {...inputProps}
+        />
+      </div>
+    );
+  }
+
+  if (array) {
+    return <ArrayField property={property} path={path} inputProps={inputProps} readonly={readonly} Custom={Custom} />;
+  }
+
+  const InputComponent = getInputComponent(type, format);
+  if (InputComponent) {
+    return (
+      <div role='none'>
+        <InputComponent
+          type={type}
+          format={format}
+          label={label}
+          inputOnly={inline}
+          placeholder={placeholder}
+          disabled={readonly}
+          {...inputProps}
+        />
+      </div>
+    );
+  }
+
+  if (options) {
+    return (
+      <div role='none'>
+        <SelectInput
+          type={type}
+          format={format}
+          disabled={readonly}
+          inputOnly={inline}
+          label={label}
+          options={options.map((option) => ({ value: option, label: String(option) }))}
+          placeholder={placeholder}
+          {...inputProps}
+        />
+      </div>
+    );
+  }
+
+  if (type === 'object') {
+    const baseNode = findNode(ast, isDiscriminatedUnion);
+    const typeLiteral = baseNode
+      ? getDiscriminatedType(baseNode, inputProps.getValue() as any)
+      : findNode(ast, AST.isTypeLiteral);
+
+    if (typeLiteral) {
+      return (
+        <div role='none'>
+          {!inline && <div>{label}</div>}
+          <FormFields schema={S.make(typeLiteral)} path={path} readonly={readonly} Custom={Custom} />
+        </div>
+      );
+    }
+  }
+
+  return null;
+};
+
+export const FormFields = ({ schema, path, filter, sort, readonly, lookupComponent, Custom }: FormContentProps) => {
+  const values = useFormValues(path);
+
+  const properties = useMemo(() => {
+    const props = getSchemaProperties(schema.ast, values);
+    const filtered = filter ? filter(props) : props;
+
+    return sort ? filtered.sort((a, b) => sort.indexOf(a.name) - sort.indexOf(b.name)) : filtered;
+  }, [schema, values, filter, sort]);
+
+  return (
+    <div role='form' className={mx('flex flex-col w-full gap-2 py-2')}>
+      {properties
+        .map((property) => {
+          return (
+            <FormField
+              key={property.name}
+              property={property}
+              path={[...(path ?? []), property.name]}
+              readonly={readonly}
+              lookupComponent={lookupComponent}
+              Custom={Custom}
+            />
+          );
+        })
+        .filter(isNotFalsy)}
+    </div>
+  );
+};

package/src/components/Form/FormContext.tsx

@@ -0,0 +1,48 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { createContext, useContext, type FocusEvent, type PropsWithChildren } from 'react';
+
+import { raise } from '@dxos/debug';
+import { type BaseObject, getValue } from '@dxos/echo-schema';
+import { createJsonPath, type SimpleType } from '@dxos/effect';
+
+import { type FormHandler, type FormOptions, useForm } from '../../hooks';
+
+type FormContextValue<T extends BaseObject> = FormHandler<T>;
+
+const FormContext = createContext<FormContextValue<any> | undefined>(undefined);
+
+export const useFormContext = <T extends BaseObject>(): FormContextValue<T> => {
+  return useContext(FormContext) ?? raise(new Error('Missing FormContext'));
+};
+
+export const useFormValues = (path: (string | number)[] = []): any => {
+  const { values: formValues } = useFormContext();
+  const jsonPath = createJsonPath(path);
+  return getValue(formValues, jsonPath) as BaseObject;
+};
+
+export type FormInputStateProps = {
+  getStatus: () => { status?: 'error'; error?: string };
+  getValue: <V>() => V | undefined;
+  onValueChange: (type: SimpleType, value: any) => void;
+  onBlur: (event: FocusEvent<HTMLElement>) => void;
+};
+
+export const useInputProps = (path: (string | number)[] = []): FormInputStateProps => {
+  const { getStatus, getValue: getFormValue, onValueChange, onTouched } = useFormContext();
+
+  return {
+    getStatus: () => getStatus(path),
+    getValue: () => getFormValue(path),
+    onValueChange: (type: SimpleType, value: any) => onValueChange(path, type, value),
+    onBlur: () => onTouched(path),
+  };
+};
+
+export const FormProvider = ({ children, ...formOptions }: PropsWithChildren<FormOptions<any>>) => {
+  const formHandler = useForm(formOptions);
+  return <FormContext.Provider value={formHandler}>{children}</FormContext.Provider>;
+};