@dxos/react-ui-form 0.9.0 → 0.9.1-staging.ee54ba693a

package/src/components/Form/FormControls.tsx

@@ -0,0 +1,377 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { type PropsWithChildren, useRef } from 'react';
+
+import { type AnyProperties } from '@dxos/echo/internal';
+import {
+  Column,
+  type ColumnRootProps,
+  IconButton,
+  type IconButtonProps,
+  Input,
+  ScrollArea,
+  type ThemedClassName,
+  composable,
+  composableProps,
+  useMergeRefs,
+  useTranslation,
+  withColumn,
+} from '@dxos/react-ui';
+import { MarkdownView } from '@dxos/react-ui-markdown';
+import { mx } from '@dxos/ui-theme';
+import { type Merge } from '@dxos/util';
+
+import { translationKey } from '#translations';
+
+import {
+  FormContextProvider,
+  type FormContextValue,
+  type FormHandlerProps,
+  type FormUpdateMeta,
+  useFormContext,
+  useFormHandler,
+  useKeyHandler,
+} from '../../hooks';
+import { formTheme } from './Form.theme';
+import { FormFieldSet, type FormFieldSetProps as NaturalFormFieldSetProps } from './FormFieldSet';
+import { FormLayout, type FormLayoutProps as NaturalFormLayoutProps } from './FormLayout';
+
+//
+// Root
+//
+
+export type FormRootProps<T extends AnyProperties = AnyProperties> = Merge<
+  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'>
+>;
+
+// `variant` (from FormContextValue) flows through `...props` into the context for all parts to read.
+export const FormRoot = <T extends AnyProperties = AnyProperties>({
+  children,
+  schema,
+  values,
+  onSave,
+  onCancel,
+  ...props
+}: FormRootProps<T>) => {
+  const form = useFormHandler({ schema, values, onSave, onCancel, ...props });
+
+  return (
+    <FormContextProvider form={form} {...props}>
+      {children}
+    </FormContextProvider>
+  );
+};
+
+FormRoot.displayName = 'Form.Root';
+
+//
+// Viewport
+//
+
+const FORM_VIEWPORT_NAME = 'Form.Viewport';
+
+export type FormViewportProps = {
+  scroll?: boolean;
+  gutter?: ColumnRootProps['gutter'];
+};
+
+// The viewing window: owns the gutter Column (chrome/side-padding).
+// Content-height by default; `scroll` makes it fill its parent and scroll (the gutter then hosts the scrollbar).
+export const FormViewport = composable<HTMLDivElement, FormViewportProps>(
+  ({ children, scroll, gutter = 'sm', ...props }, forwardedRef) => {
+    const { variant = 'default' } = useFormContext(FORM_VIEWPORT_NAME);
+    const styles = formTheme.styles({ variant });
+    // Span the full width when nested inside another Column grid (e.g. Card.Root)
+    // instead of landing in a single narrow track.
+    const span = '[.dx-column-root_&]:col-span-full';
+    if (scroll) {
+      return (
+        <Column.Root gutter={gutter} classNames={['dx-expander', span]}>
+          <ScrollArea.Root
+            {...composableProps(props, { classNames: styles.viewport() })}
+            orientation='vertical'
+            centered
+            padding
+            thin
+            ref={forwardedRef}
+          >
+            <ScrollArea.Viewport>{children}</ScrollArea.Viewport>
+          </ScrollArea.Root>
+        </Column.Root>
+      );
+    }
+
+    return (
+      <Column.Root
+        {...composableProps(props, { classNames: ['w-full min-w-0', span, styles.viewport()] })}
+        gutter={gutter}
+        ref={forwardedRef}
+      >
+        {children}
+      </Column.Root>
+    );
+  },
+);
+
+FormViewport.displayName = FORM_VIEWPORT_NAME;
+
+//
+// Content
+//
+
+const FORM_CONTENT_NAME = 'Form.Content';
+
+export type FormContentProps = ThemedClassName<PropsWithChildren<{}>>;
+
+// The viewed body: centered in the viewport's gutter. Pure body — the gutter Column is owned by `Form.Viewport`.
+export const FormContent = composable<HTMLDivElement, FormContentProps>(({ children, ...props }, forwardedRef) => {
+  const { form, testId, variant = 'default' } = useFormContext(FORM_CONTENT_NAME);
+  const styles = formTheme.styles({ variant });
+  const localRef = useRef<HTMLDivElement>(null);
+  const mergedRef = useMergeRefs([forwardedRef, localRef]);
+  useKeyHandler(localRef, form);
+
+  return (
+    <div
+      {...composableProps(props, {
+        role: 'form',
+        classNames: mx(withColumn.center(), 'flex flex-col w-full dx-document', styles.content()),
+      })}
+      data-testid={testId}
+      ref={mergedRef}
+    >
+      {children}
+    </div>
+  );
+});
+
+FormContent.displayName = FORM_CONTENT_NAME;
+
+//
+// FieldSet
+//
+
+const FORM_FIELDSET_NAME = 'Form.FieldSet';
+
+export type FormFieldSetControllerProps = ThemedClassName<NaturalFormFieldSetProps<any>>;
+
+/** Context-reading binding for `Form.FieldSet`: pulls the schema + field context off the form and delegates to {@link FormFieldSet}. */
+export const FormFieldSetController = ({ classNames, ...props }: FormFieldSetControllerProps) => {
+  const { form, variant = 'default', ...contextProps } = useFormContext(FORM_FIELDSET_NAME);
+  const styles = formTheme.styles({ variant });
+  return (
+    <FormFieldSet
+      schema={form.schema}
+      classNames={styles.fieldSet({ class: classNames })}
+      {...contextProps}
+      {...props}
+    />
+  );
+};
+
+FormFieldSetController.displayName = FORM_FIELDSET_NAME;
+
+//
+// Layout
+//
+
+const FORM_LAYOUT_NAME = 'Form.Layout';
+
+export type FormLayoutProps = Omit<NaturalFormLayoutProps, 'schema'> & { schema?: NaturalFormLayoutProps['schema'] };
+
+/** Context-reading binding for `Form.Layout`: resolves the schema (prop or form) and delegates to {@link FormLayout}. */
+export const FormLayoutController = ({ schema, ...props }: FormLayoutProps) => {
+  const { form, ...contextProps } = useFormContext(FORM_LAYOUT_NAME);
+  const resolvedSchema = schema ?? form.schema;
+  if (!resolvedSchema) {
+    return null;
+  }
+
+  return <FormLayout schema={resolvedSchema} {...contextProps} {...props} />;
+};
+
+FormLayoutController.displayName = FORM_LAYOUT_NAME;
+
+//
+// Actions
+//
+
+const FORM_ACTIONS_NAME = 'Form.Actions';
+
+export type FormActionsProps = ThemedClassName<{}>;
+
+export 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 className={mx(withColumn.center(), formTheme.styles().actions(), 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'
+        />
+      )}
+    </div>
+  );
+};
+
+FormActions.displayName = FORM_ACTIONS_NAME;
+
+//
+// Section
+//
+
+const FORM_SECTION_NAME = 'Form.Section';
+
+export type FormSectionProps = ThemedClassName<{
+  title?: string;
+  description?: string;
+}>;
+
+export const FormSection = composable<HTMLDivElement, FormSectionProps>(
+  ({ children, title, description, ...props }, forwardedRef) => {
+    const { variant = 'default' } = useFormContext(FORM_SECTION_NAME);
+    const styles = formTheme.styles({ variant });
+    return (
+      <div {...composableProps(props, { classNames: styles.section() })} ref={forwardedRef}>
+        {(title || description) && (
+          <div className={styles.sectionHeader()}>
+            {title && <h2 className={styles.sectionTitle()}>{title}</h2>}
+            {description && <MarkdownView classNames={styles.sectionDescription()} content={description} />}
+          </div>
+        )}
+        {children}
+      </div>
+    );
+  },
+);
+
+FormSection.displayName = FORM_SECTION_NAME;
+
+//
+// Group
+//
+
+const FORM_GROUP_NAME = 'Form.Group';
+
+export type FormGroupProps = ThemedClassName<PropsWithChildren>;
+
+/**
+ * A bordered card grouping related rows/controls (e.g. an entity card in a list).
+ * Layout-only and context-free — unlike `Form.FieldSet` it is not schema-driven.
+ */
+export const FormGroup = composable<HTMLDivElement, FormGroupProps>(({ children, ...props }, forwardedRef) => {
+  const { variant = 'default' } = useFormContext(FORM_SECTION_NAME);
+  const styles = formTheme.styles({ variant });
+
+  return (
+    <div {...composableProps(props, { classNames: styles.group() })} ref={forwardedRef}>
+      {children}
+    </div>
+  );
+});
+
+FormGroup.displayName = FORM_GROUP_NAME;
+
+//
+// Submit
+//
+
+const FORM_SUBMIT_NAME = 'Form.Submit';
+
+export type FormSubmitProps = ThemedClassName<Partial<Pick<IconButtonProps, 'icon' | 'label' | 'disabled'>>>;
+
+export 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 className={mx(formTheme.styles().submit(), 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;
+
+//
+// Error
+//
+
+const FORM_ERROR_NAME = 'Form.Error';
+
+export type FormErrorProps = ThemedClassName<PropsWithChildren>;
+
+/** Form-level error/validation message (e.g. a failed submit), styled via the error valence. */
+export const FormError = ({ children, classNames }: FormErrorProps) => {
+  if (!children) {
+    return null;
+  }
+
+  return (
+    <Input.Root validationValence='error'>
+      <Input.Validation classNames={classNames}>{children}</Input.Validation>
+    </Input.Root>
+  );
+};
+
+FormError.displayName = FORM_ERROR_NAME;

package/src/components/Form/{FormField.tsx → FormField/FormField.tsx}

@@ -12,34 +12,31 @@ import React, { useMemo } from 'react';
 import { Annotation, Format } from '@dxos/echo';
 import { SchemaEx } from '@dxos/effect';
 import { IconButton, IconButtonProps, useTranslation } from '@dxos/react-ui';
-import { type ProjectionModel } from '@dxos/schema';
-import { mx } from '@dxos/ui-theme';
 
 import { translationKey } from '#translations';
+import { type FieldContext, type FormFieldRenderer, type FormFieldRendererProps } from '#types';
 
-import { getRefProps } from '../../util';
+import { AutofillAnnotation, OptionsLookupAnnotation } from '../../../annotations';
+import { useFormFieldState } from '../../../hooks';
+import { getRefProps } from '../../../util';
+import { FormFieldSet } from '../FormFieldSet';
 import {
   ArrayField,
+  AsyncSelectField,
+  AutofillField,
   BooleanField,
+  ComboboxField,
   DateField,
   GeoPointField,
   InlineRefField,
   MarkdownField,
   NumberField,
+  PasswordField,
   RefField,
-  type RefFieldProps,
   SelectField,
   TextAreaField,
   TextField,
 } from './fields';
-import { useFormFieldState } from './Form';
-import {
-  type FormFieldComponent,
-  type FormFieldComponentProps,
-  type FormFieldMap,
-  type FormFieldProvider,
-} from './FormFieldComponent';
-import { FormFieldSet } from './FormFieldSet';
 
 export type FormFieldProps = {
   /**
@@ -58,50 +55,34 @@ export type FormFieldProps = {
   name: string | null;
 
   /**
-   * Path to the current object from the root. Used with nested forms.
-   */
-  path?: (string | number)[];
-
-  /**
-   * Optional projection for projection-based field management.
-   */
-  projection?: ProjectionModel;
-
-  /**
-   * Map of custom renderers for specific properties.
-   * Prefer fieldProvider for plugin specific input surfaces.
+   * Explicit label, overriding the `title ?? capitalize(name)` derivation. Used by `ArrayField` to
+   * give scalar/ref items the array's resolved title (e.g. `Tags`) rather than re-capitalizing the
+   * raw array property name (e.g. `_tags`), since the element type carries no title of its own.
    */
-  fieldMap?: FormFieldMap;
+  label?: string;
 
   /**
-   * Function to lookup custom renderers for specific properties.
+   * Path to the current object from the root. Used with nested forms.
    */
-  fieldProvider?: FormFieldProvider;
-
+  path?: (string | number)[];
+  autoFocus?: boolean;
+  /** Whether the field is required (non-optional in the schema). Drives the label asterisk. */
+  required?: boolean;
   /**
-   * Typename of the ref type that the create props apply to.
-   * When set, createOptionLabel/createOptionIcon/createInitialValuePath/createFieldMap/onCreate
-   * are only passed to ref fields whose typename matches.
+   * Force a `Ref` field to render its target inline (a nested form) instead of the picker.
+   * Set by `ArrayField` for owned-ref arrays (`FormCreateAnnotation`); equivalent to
+   * `FormInlineAnnotation` but driven by the parent array rather than the element's own AST.
    */
-  createTypename?: string;
-} & Pick<FormFieldComponentProps, 'autoFocus' | 'readonly' | 'layout'> &
-  Pick<
-    RefFieldProps,
-    | 'createOptionLabel'
-    | 'createOptionIcon'
-    | 'createInitialValuePath'
-    | 'createFieldMap'
-    | 'db'
-    | 'useType'
-    | 'getOptions'
-    | 'onCreate'
-  >;
+  refInline?: boolean;
+} & FieldContext;
 
 export const FormField = (props: FormFieldProps) => {
   const {
     type,
     name,
+    label: labelProp,
     path,
+    required,
     projection,
     fieldMap,
     fieldProvider,
@@ -115,42 +96,49 @@ export const FormField = (props: FormFieldProps) => {
     createInitialValuePath,
     createFieldMap,
     db,
-    useType: schemaHook,
+    useType,
     getOptions,
     onCreate,
+    resolveCreateEntry,
+    refInline,
   } = props;
   const { t } = useTranslation(translationKey);
   const title = SchemaEx.getAnnotation<string>(SchemaAST.TitleAnnotationId)(type);
   const description = SchemaEx.getAnnotation<string>(SchemaAST.DescriptionAnnotationId)(type);
   const examples = SchemaEx.getAnnotation<string[]>(SchemaAST.ExamplesAnnotationId)(type);
 
-  // `name === null` means "no header" -- collapse to an empty string so
-  // downstream consumers keep their `label: string` types, and the falsy
-  // value lets `FormFieldSet`'s `label && <FormFieldLabel ...>` guard skip
-  // the header.
-  const label = useMemo(() => title ?? (name == null ? '' : String.capitalize(name)), [title, name]);
+  const label = useMemo(
+    () => labelProp ?? title ?? (name == null ? '' : String.capitalize(name)),
+    [labelProp, title, name],
+  );
   const placeholder = useMemo(
     () => (examples?.length ? `${t('example.placeholder')}: ${examples[0]}` : (description ?? label)),
-    [examples, description, label],
+    [examples, description, label, t],
   );
 
+  // Build the schema for `fieldProvider` only when one is registered, memoized by `type` (the AST) so
+  // we don't reconstruct it on every render.
+  const providerSchema = useMemo(() => (fieldProvider ? Schema.make(type) : undefined), [fieldProvider, type]);
+
   const fieldState = useFormFieldState(FormField.displayName, path);
   const jsonPath = SchemaEx.createJsonPath(path ?? []);
-  const fieldProps: FormFieldComponentProps = {
+  const fieldProps: FormFieldRendererProps = {
     type,
     format: Format.FormatAnnotation.getFromAst(type).pipe((annotation) => Option.getOrUndefined(annotation)),
     readonly,
     label,
+    description,
     jsonPath,
     placeholder,
-    layout,
+    presentation: layout,
+    required,
     db,
     ...fieldState,
   };
 
   // Omit empty fields entirely in read-only mode -- an empty value has nothing
   // to display, so a labelled row with a blank input is just noise. This
-  // mirrors what `FormFieldWrapper` already does for `layout === 'static'`, but
+  // mirrors what `FormRow` already does for `presentation === 'static'`, but
   // covers every field type (including those that bypass the wrapper:
   // RefField, SelectField, MarkdownField, ...). Container fields
   // (`ArrayField`, nested-struct -> `FormFieldSet`) keep their own
@@ -169,10 +157,29 @@ export const FormField = (props: FormFieldProps) => {
     return <CustomField {...fieldProps} />;
   }
 
-  // TODO(burdon): Expensive to create schema each time; pass AST?
-  const component = fieldProvider?.({ schema: Schema.make(type), prop: name ?? '', fieldProps });
-  if (component) {
-    return component;
+  if (fieldProvider && providerSchema) {
+    const component = fieldProvider({ schema: providerSchema, prop: name ?? '', fieldProps });
+    if (component) {
+      return component;
+    }
+  }
+
+  //
+  // Dynamic, value-driven fields (options/value/validation loaded via a self-contained Effect annotation).
+  //
+
+  const optionsLookup = Option.getOrUndefined(OptionsLookupAnnotation.getFromAst(type));
+  if (optionsLookup) {
+    return optionsLookup.combobox ? (
+      <ComboboxField {...fieldProps} lookup={optionsLookup} />
+    ) : (
+      <AsyncSelectField {...fieldProps} lookup={optionsLookup} />
+    );
+  }
+
+  const autofill = Option.getOrUndefined(AutofillAnnotation.getFromAst(type));
+  if (autofill) {
+    return <AutofillField {...fieldProps} autofill={autofill} />;
   }
 
   //
@@ -223,10 +230,21 @@ export const FormField = (props: FormFieldProps) => {
 
   const refProps = getRefProps(type);
   if (refProps) {
-    // Inline a single referenced object's own fields (nested form) instead of a picker.
-    const inline = Annotation.FormInlineAnnotation.getFromAst(refProps.ast).pipe(Option.getOrElse(() => false));
+    // Inline a single referenced object's own fields (nested form) instead of a picker. `refInline` lets a
+    // parent (e.g. an owned-ref `ArrayField`) force this for elements whose own AST carries no annotation.
+    const inline =
+      refInline || Annotation.FormInlineAnnotation.getFromAst(refProps.ast).pipe(Option.getOrElse(() => false));
     if (inline && !refProps.isArray) {
-      return <InlineRefField {...fieldProps} {...refProps} db={db} useType={schemaHook} onCreate={onCreate} />;
+      return (
+        <InlineRefField
+          {...fieldProps}
+          {...refProps}
+          db={db}
+          useType={useType}
+          onCreate={onCreate}
+          resolveCreateEntry={resolveCreateEntry}
+        />
+      );
     }
 
     const isCreateTarget = !createTypename || refProps.typename === createTypename;
@@ -239,9 +257,10 @@ export const FormField = (props: FormFieldProps) => {
         createInitialValuePath={isCreateTarget ? createInitialValuePath : undefined}
         createFieldMap={isCreateTarget ? createFieldMap : undefined}
         db={db}
-        useType={schemaHook}
+        useType={useType}
         getOptions={getOptions}
         onCreate={onCreate}
+        resolveCreateEntry={resolveCreateEntry}
       />
     );
   }
@@ -273,9 +292,10 @@ export const FormField = (props: FormFieldProps) => {
           createOptionIcon={createOptionIcon}
           createInitialValuePath={createInitialValuePath}
           db={db}
-          useType={schemaHook}
+          useType={useType}
           getOptions={getOptions}
           onCreate={onCreate}
+          resolveCreateEntry={resolveCreateEntry}
         />
       );
     }
@@ -290,28 +310,33 @@ FormField.displayName = 'Form.FormField';
 // Layout components
 //
 
-export const IconBlock = ({ inline, ...props }: IconButtonProps & { inline?: boolean }) => {
-  return (
-    <div className={mx('h-full flex px-1', inline ? 'items-center' : 'flex-col pt-2.5')}>
-      <IconButton variant='ghost' density='xs' square iconOnly {...props} />
-    </div>
-  );
+export const CompactIconButton = (props: IconButtonProps) => {
+  return <IconButton variant='ghost' iconOnly {...props} />;
 };
 
 /**
  * Get property input component.
  */
-const getFormField = ({ type, format }: FormFieldComponentProps): FormFieldComponent | undefined => {
+const getFormField = ({
+  type,
+  format,
+}: Pick<FormFieldRendererProps, 'type' | 'format'>): FormFieldRenderer | undefined => {
+  // Unwrap refinements (e.g. Schema.Number.pipe(Schema.between(...))) to their base type.
+  if (SchemaAST.isRefinement(type)) {
+    return getFormField({ type: type.from, format });
+  }
+
   //
   // Standard formats.
   //
 
   const formatField = Match.value(format).pipe(
-    Match.withReturnType<FormFieldComponent | undefined>(),
+    Match.withReturnType<FormFieldRenderer | undefined>(),
     Match.when(Format.TypeFormat.Date, () => DateField),
     Match.when(Format.TypeFormat.DateTime, () => DateField),
     Match.when(Format.TypeFormat.GeoPoint, () => GeoPointField),
     Match.when(Format.TypeFormat.Markdown, () => MarkdownField),
+    Match.when(Format.TypeFormat.Password, () => PasswordField),
     Match.when(Format.TypeFormat.Text, () => TextAreaField),
     Match.when(Format.TypeFormat.Time, () => DateField),
     Match.orElse(() => undefined),
@@ -334,6 +359,8 @@ const getFormField = ({ type, format }: FormFieldComponentProps): FormFieldCompo
     case 'BooleanKeyword':
       return BooleanField;
   }
+
+  return undefined;
 };
 
 const getSelectOptions = (ast: SchemaAST.AST): Format.Options[] | undefined => {