@dxos/react-ui-form 0.8.4-main.7ace549 → 0.8.4-main.8360d9e660

package/src/components/Form/Form.tsx

@@ -1,122 +1,359 @@
 //
-// Copyright 2024 DXOS.org
-//
-
-import { useFocusFinders } from '@fluentui/react-tabster';
-import type * as Schema from 'effect/Schema';
-import React, { type ReactElement, useCallback, useEffect, useRef } from 'react';
-
-import { type AnyProperties, type PropertyKey } from '@dxos/echo/internal';
-import { type ThemedClassName } from '@dxos/react-ui';
-import { cardDialogOverflow, cardSpacing } from '@dxos/react-ui-stack';
-import { type ProjectionModel, type SchemaProperty } from '@dxos/schema';
-
-import { type FormHandler, type FormOptions } from '../../hooks';
-
-import { FormActions, type FormOuterSpacing } from './FormActions';
-import { FormFields, type FormFieldsProps } from './FormContent';
-import { FormProvider } from './FormContext';
-import { type InputComponent, type InputProps } from './Input';
-
-export type PropsFilter<T extends AnyProperties> = (props: SchemaProperty<T>[]) => SchemaProperty<T>[];
-
-export type ComponentLookup = (args: {
-  prop: string;
-  schema: Schema.Schema<any>;
-  inputProps: InputProps;
-}) => ReactElement | undefined;
-
-export type CustomInputMap = Partial<Record<string, InputComponent>>;
-
-export type FormProps<T extends AnyProperties> = ThemedClassName<{
-  id?: string;
-  values: Partial<T>;
-  // TODO(burdon): Autofocus first input.
-  autoFocus?: boolean;
-  // TODO(burdon): Change to JsonPath includes/excludes.
-  filter?: PropsFilter<T>;
-  sort?: PropertyKey<T>[];
-  projection?: ProjectionModel;
-  autoSave?: boolean;
-  outerSpacing?: FormOuterSpacing;
-  onCancel?: () => void;
-}> &
-  Pick<FormOptions<T>, 'schema' | 'onValuesChanged' | 'onValidate' | 'onSave'> &
-  // TODO(wittjosiah): This needs to support different ref field options per field.
-  FormFieldsProps;
-
-export const Form = <T extends AnyProperties>({
-  classNames,
-  id,
-  testId,
-  values: initialValues,
-  autoFocus,
-  readonly,
-  autoSave,
-  outerSpacing = true,
+// Copyright 2025 DXOS.org
+//
+
+import { createContext } from '@radix-ui/react-context';
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+import React, { type PropsWithChildren, useEffect, useMemo, useRef } from 'react';
+
+import { type AnyProperties } from '@dxos/echo/internal';
+import { createJsonPath, getValue as getValue$ } from '@dxos/effect';
+import {
+  IconButton,
+  type IconButtonProps,
+  ScrollArea,
+  type ScrollAreaRootProps,
+  type ThemedClassName,
+  useTranslation,
+} from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+
+import {
+  type FormHandler,
+  type FormHandlerProps,
+  type FormUpdateMeta,
+  useFormHandler,
+  useKeyHandler,
+} from '../../hooks';
+import { translationKey } from '../../translations';
+
+import { FormFieldLabel, type FormFieldLabelProps, type FormFieldStateProps } from './FormFieldComponent';
+import {
+  FormFieldSet as NaturalFormFieldSet,
+  type FormFieldSetProps as NaturalFormFieldSetProps,
+} from './FormFieldSet';
+
+// New features/polish
+// [x] Unify readonly/inline modes.
+// [x] Refs
+//   [x] Single-select (fix popover)
+//   [x] Multi-select (array)
+// [ ] auto save doesn't work for combobox + select due to only firing on blur (workaround is to use onValuesChanged).
+// [ ] Don't call save/autoSave if value hasn't changed.
+// [ ] Fix onCancel (restore values).
+// [ ] Fix useSchema Type.AnyObj cast.
+// [ ] TableCellEditor (handleEnter/ModalController).
+// [ ] Use FormFieldWrapper uniformly
+// [ ] Inline tables.
+// [ ] Defer query until popover.
+// [ ] Omit id from sub properties.
+
+// TODO(burdon): Move to @dxos/schema (re-export here).
+export type ExcludeId<S extends Schema.Schema.AnyNoContext> = Omit<Schema.Schema.Type<S>, 'id'>;
+
+// TODO(burdon): Move to @dxos/schema (re-export here).
+export const omitId = <S extends Schema.Schema.AnyNoContext>(schema: S): Schema.Schema<ExcludeId<S>, ExcludeId<S>> =>
+  schema.pipe(Schema.omit('id')) as any;
+
+//
+// Context
+//
+
+type FormContextValue<T extends AnyProperties = any> = {
+  /**
+   * Form handler.
+   */
+  form: FormHandler<T>;
+
+  /**
+   * Show debug info.
+   */
+  debug?: boolean;
+
+  /**
+   * Testing.
+   */
+  testId?: string;
+} & Pick<NaturalFormFieldSetProps<T>, 'readonly' | 'layout' | 'fieldMap' | 'fieldProvider' | 'projection'>;
+
+const [FormContextProvider, useFormContext] = createContext<FormContextValue>('Form');
+
+/**
+ * Get the current form values.
+ */
+const useFormValues: {
+  <T extends AnyProperties>(componentName: string, path?: (string | number)[]): T;
+  <T extends AnyProperties>(
+    componentName: string,
+    path: (string | number)[] | undefined,
+    defaultValue: () => T,
+  ): T | undefined;
+} = (componentName: string, path?: (string | number)[], defaultValue?: () => any) => {
+  const stablePath = useMemo(() => path ?? [], [path ? path.join('.') : undefined]);
+  const jsonPath = createJsonPath(stablePath);
+  const {
+    form: { values, onValueChange },
+  } = useFormContext(componentName);
+
+  const value = getValue$(values, jsonPath);
+
+  // Apply default value once when the field has no value. lastAppliedPathRef prevents
+  // re-applying on every render (e.g. when defaultValue() returns null) and ensures
+  // we apply per path when the hook is used for different fields.
+  const lastAppliedPathRef = useRef<string | null>(null);
+  useEffect(() => {
+    if (value == null && defaultValue && lastAppliedPathRef.current !== jsonPath) {
+      lastAppliedPathRef.current = jsonPath;
+      onValueChange(stablePath, SchemaAST.stringKeyword, defaultValue());
+    }
+  }, [value, defaultValue, onValueChange, stablePath, jsonPath]);
+
+  return value;
+};
+
+/**
+ * Get the state props for the given field.
+ */
+const useFormFieldState = (componentName: string, path: (string | number)[] = []): FormFieldStateProps => {
+  const stablePath = useMemo(() => path, [Array.isArray(path) ? path.join('.') : path]);
+  const {
+    form: { getStatus, getValue, onBlur, onValueChange },
+  } = useFormContext(componentName);
+
+  return useMemo(
+    () => ({
+      getStatus: () => getStatus(stablePath),
+      getValue: () => getValue(stablePath),
+      onBlur: () => onBlur(stablePath),
+      onValueChange: (ast: SchemaAST.AST, value: any) => onValueChange(stablePath, ast, value),
+    }),
+    [getStatus, getValue, onBlur, onValueChange, stablePath],
+  );
+};
+
+//
+// Root
+//
+
+type FormRootProps<T extends AnyProperties = AnyProperties> = PropsWithChildren<
+  {
+    /**
+     * Called when the form is submitted and passes validation.
+     */
+    onSave?: (values: T, meta: FormUpdateMeta<T>) => void;
+
+    /**
+     * Called when the form is canceled to abandon/undo any pending changes.
+     */
+    onCancel?: () => void;
+  } & Omit<FormContextValue<T>, 'form'> &
+    Pick<FormHandlerProps<T>, 'schema' | 'autoSave' | 'values' | 'defaultValues' | 'onValidate' | 'onValuesChanged'> &
+    Omit<NaturalFormFieldSetProps<T>, 'schema' | 'path'>
+>;
+
+const FormRoot = <T extends AnyProperties = AnyProperties>({
+  children,
   schema,
-  onCancel,
-  onValuesChanged,
-  onValidate,
+  values,
   onSave,
+  onCancel,
   ...props
-}: FormProps<T>) => {
-  const formRef = useRef<HTMLDivElement>(null);
+}: FormRootProps<T>) => {
+  const form = useFormHandler({ schema, values, onSave, onCancel, ...props });
 
-  // Focus the first focusable element within this form.
-  const { findFirstFocusable } = useFocusFinders();
-  useEffect(() => {
-    if (autoFocus && formRef.current) {
-      const firstFocusable = findFirstFocusable(formRef.current);
-      if (firstFocusable) {
-        firstFocusable.focus();
-      }
-    }
-  }, [autoFocus]);
-
-  // TODO(burdon): Name?
-  const handleValid = useCallback(
-    async (values: any, meta: { changed: FormHandler<T>['changed'] }) => {
-      if (autoSave) {
-        await onSave?.(values, meta);
-      }
-    },
-    [autoSave, onSave],
+  return (
+    <FormContextProvider form={form} {...props}>
+      {children}
+    </FormContextProvider>
   );
+};
 
+FormRoot.displayName = 'Form.Root';
+
+//
+// Viewport
+//
+
+const FORM_VIEWPORT_NAME = 'Form.Viewport';
+
+type FormViewportProps = PropsWithChildren<ScrollAreaRootProps>;
+
+const FormViewport = ({
+  children,
+  classNames,
+  margin = true,
+  padding = true,
+  thin = true,
+  ...props
+}: FormViewportProps) => {
   return (
-    <FormProvider
-      formRef={formRef}
-      schema={schema}
-      autoSave={autoSave}
-      initialValues={initialValues}
-      onValuesChanged={onValuesChanged}
-      onValidate={onValidate}
-      onValid={handleValid}
-      onSave={onSave}
+    <ScrollArea.Root
+      orientation='vertical'
+      classNames={classNames}
+      margin={margin}
+      padding={padding}
+      thin={thin}
+      {...props}
     >
-      <div role='none' className='contents' {...(id && { 'data-object-id': id })} data-testid={testId}>
-        <FormFields
-          {...props}
-          ref={formRef}
-          classNames={[
-            outerSpacing === 'blockStart-0'
-              ? 'pli-cardSpacingInline mbe-cardSpacingBlock [&>.mbs-inputSpacingBlock:first-child]:!mbs-0'
-              : outerSpacing === 'scroll-fields'
-                ? 'pli-cardSpacingInline pbe-cardSpacingBlock'
-                : outerSpacing
-                  ? cardSpacing
-                  : false,
-            outerSpacing === 'scroll-fields' && cardDialogOverflow,
-            classNames,
-          ]}
-          readonly={readonly}
-          schema={schema}
+      <ScrollArea.Viewport>{children}</ScrollArea.Viewport>
+    </ScrollArea.Root>
+  );
+};
+
+FormViewport.displayName = FORM_VIEWPORT_NAME;
+
+//
+// Content
+//
+
+const FORM_CONTENT_NAME = 'Form.Content';
+
+type FormContentProps = ThemedClassName<PropsWithChildren<{}>>;
+
+const FormContent = ({ classNames, children }: FormContentProps) => {
+  const { form, testId } = useFormContext(FORM_CONTENT_NAME);
+  const ref = useRef<HTMLDivElement>(null);
+  useKeyHandler(ref.current, form);
+
+  return (
+    <div ref={ref} role='form' className={mx('w-full flex flex-col gap-form-padding', classNames)} data-testid={testId}>
+      {children}
+    </div>
+  );
+};
+
+FormContent.displayName = FORM_CONTENT_NAME;
+
+//
+// FieldSet
+//
+
+const FORM_FIELDSET_NAME = 'Form.FieldSet';
+
+type FormFieldSetProps = ThemedClassName<NaturalFormFieldSetProps<any>>;
+
+const FormFieldSet = (props: FormFieldSetProps) => {
+  const { form, ...contextProps } = useFormContext(FORM_FIELDSET_NAME);
+
+  return <NaturalFormFieldSet schema={form.schema} {...contextProps} {...props} />;
+};
+
+FormFieldSet.displayName = FORM_FIELDSET_NAME;
+
+//
+// Actions
+//
+
+const FORM_ACTIONS_NAME = 'Form.Actions';
+
+type FormActionsProps = ThemedClassName<{}>;
+
+const FormActions = ({ classNames }: FormActionsProps) => {
+  const { t } = useTranslation(translationKey);
+  const {
+    form: { canSave, onSave, onCancel },
+    readonly,
+    layout,
+  } = useFormContext(FORM_ACTIONS_NAME);
+
+  if (readonly || layout === 'static') {
+    return null;
+  }
+
+  // TODO(burdon): Currently onCancel is a no-op; implement "revert values".
+  //   Deprecate FormSubmit ans use FormActions without Cancel button if no callback is supplied.
+
+  return (
+    <div role='none' className={mx('grid grid-flow-col gap-2 auto-cols-fr py-form-padding', classNames)}>
+      {onCancel && (
+        <IconButton
+          icon='ph--x--regular'
+          iconEnd
+          label={t('cancel button label')}
+          onClick={onCancel}
+          data-testid='cancel-button'
+        />
+      )}
+      {onSave && (
+        <IconButton
+          type='submit'
+          variant='primary'
+          disabled={!canSave}
+          icon='ph--check--regular'
+          iconEnd
+          label={t('save button label')}
+          onClick={onSave}
+          data-testid='save-button'
         />
-        {(onCancel || onSave) && !autoSave && !readonly && (
-          <FormActions readonly={readonly} onCancel={onCancel} outerSpacing={outerSpacing} />
-        )}
-      </div>
-    </FormProvider>
+      )}
+    </div>
   );
 };
+
+FormActions.displayName = FORM_ACTIONS_NAME;
+
+//
+// Submit
+//
+
+const FORM_SUBMIT_NAME = 'Form.Submit';
+
+type FormSubmitProps = ThemedClassName<Partial<Pick<IconButtonProps, 'icon' | 'label' | 'disabled'>>>;
+
+const FormSubmit = ({ classNames, label, icon, disabled }: FormSubmitProps) => {
+  const { t } = useTranslation(translationKey);
+  const {
+    form: { canSave, onSave },
+    readonly,
+    layout,
+  } = useFormContext(FORM_SUBMIT_NAME);
+
+  if (readonly || layout === 'static') {
+    return null;
+  }
+
+  return (
+    <div role='none' className={mx('flex w-full pt-form-padding', classNames)}>
+      <IconButton
+        classNames='w-full'
+        type='submit'
+        variant='primary'
+        disabled={disabled ?? !canSave}
+        icon={icon ?? 'ph--check--regular'}
+        label={label ?? t('save button label')}
+        onClick={onSave}
+        data-testid='save-button'
+      />
+    </div>
+  );
+};
+
+FormSubmit.displayName = FORM_SUBMIT_NAME;
+
+//
+// Form
+// https://www.radix-ui.com/primitives/docs/guides/composition
+//
+
+export const Form = {
+  Root: FormRoot,
+  Viewport: FormViewport,
+  Content: FormContent,
+  FieldSet: FormFieldSet,
+  Label: FormFieldLabel,
+  Actions: FormActions,
+  Submit: FormSubmit,
+};
+
+export { useFormContext, useFormValues, useFormFieldState };
+
+export type {
+  FormRootProps,
+  FormViewportProps,
+  FormContentProps,
+  FormFieldSetProps,
+  FormFieldLabelProps,
+  FormActionsProps,
+  FormSubmitProps,
+};