@dxos/react-ui-form 0.8.4-main.3eb6e50203 → 0.8.4-main.3fbcb4aa9b

package/src/components/Form/Form.tsx

@@ -3,14 +3,25 @@
 //
 
 import { createContext } from '@radix-ui/react-context';
+import * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
-import type * as SchemaAST from 'effect/SchemaAST';
+import * as SchemaAST from 'effect/SchemaAST';
 import React, { type PropsWithChildren, useEffect, useMemo, useRef } from 'react';
 
+import { Annotation as EchoAnnotation } from '@dxos/echo';
 import { type AnyProperties } from '@dxos/echo/internal';
 import { createJsonPath, getValue as getValue$ } from '@dxos/effect';
-import { IconButton, type IconButtonProps, ScrollArea, type ThemedClassName, useTranslation } from '@dxos/react-ui';
-import { mx } from '@dxos/ui-theme';
+import {
+  IconButton,
+  type IconButtonProps,
+  ScrollArea,
+  type ThemedClassName,
+  useMergeRefs,
+  useTranslation,
+} from '@dxos/react-ui';
+import { composable, composableProps, mx, withColumn } from '@dxos/ui-theme';
+
+import { translationKey } from '#translations';
 
 import {
   type FormHandler,
@@ -19,38 +30,35 @@ import {
   useFormHandler,
   useKeyHandler,
 } from '../../hooks';
-import { translationKey } from '../../translations';
-import { setValueEchoAware } from '../../util';
-
 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
-// [ ] Don't call save/autoSave if value hasn't changed
-// [ ] Fix onCancel (restore values)
-// [ ] Fix useSchema Type.Obj.Any cast
-// [ ] Remove @dxos/echo-db deps
-// [ ] TableCellEditor (handleEnter/ModalController).
-// [ ] Use FormFieldWrapper uniformly
-// [ ] Inline tables for object arrays
-// [ ] Defer query until popover
-// [ ] Omit id from sub properties.
-// [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)
+// TODO(burdon): Move styles to form.ts (as with ui-theme).
 
-// TODO(burdon): Move to @dxos/schema (re-export here).
+// TODO(burdon): Reconcile with @dxos/echo.
 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;
 
+/**
+ * Drop fields annotated with `FormInputAnnotation.set(false)` from a schema so
+ * the form's validator doesn't trip on required-but-hidden fields. Used by
+ * the picker's inline create form, where a `FactoryAnnotation` typically
+ * supplies the hidden values (e.g. a backing-object Ref) outside the form.
+ */
+export const omitHiddenFormFields = <S extends Schema.Schema.AnyNoContext>(schema: S): S => {
+  const properties = SchemaAST.getPropertySignatures(schema.ast);
+  const hidden = properties
+    .filter((prop) => Option.getOrElse(EchoAnnotation.FormInputAnnotation.getFromAst(prop.type), () => true) === false)
+    .map((prop) => prop.name as string);
+  return hidden.length === 0 ? schema : (schema.pipe(Schema.omit(...(hidden as [string, ...string[]]))) as any);
+};
+
 //
 // Context
 //
@@ -70,7 +78,10 @@ type FormContextValue<T extends AnyProperties = any> = {
    * Testing.
    */
   testId?: string;
-} & Pick<NaturalFormFieldSetProps<T>, 'readonly' | 'layout' | 'fieldMap' | 'fieldProvider'>;
+} & Pick<
+  NaturalFormFieldSetProps<T>,
+  'readonly' | 'layout' | 'fieldMap' | 'fieldProvider' | 'projection' | 'createTypename' | 'createFieldMap' | 'db'
+>;
 
 const [FormContextProvider, useFormContext] = createContext<FormContextValue>('Form');
 
@@ -84,19 +95,25 @@ const useFormValues: {
     path: (string | number)[] | undefined,
     defaultValue: () => T,
   ): T | undefined;
-} = (componentName: string, path: (string | number)[] = [], defaultValue?: () => any) => {
-  const jsonPath = createJsonPath(path);
+} = (componentName: string, path?: (string | number)[], defaultValue?: () => any) => {
+  const stablePath = useMemo(() => path ?? [], [path ? path.join('.') : undefined]);
+  const jsonPath = createJsonPath(stablePath);
   const {
-    form: { values },
+    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 && defaultValue) {
-      setValueEchoAware(values, jsonPath, defaultValue());
+    if (value == null && defaultValue && lastAppliedPathRef.current !== jsonPath) {
+      lastAppliedPathRef.current = jsonPath;
+      onValueChange(stablePath, SchemaAST.stringKeyword, defaultValue());
     }
-  }, [value, defaultValue]);
+  }, [value, defaultValue, onValueChange, stablePath, jsonPath]);
 
   return value;
 };
@@ -166,16 +183,15 @@ FormRoot.displayName = 'Form.Root';
 
 const FORM_VIEWPORT_NAME = 'Form.Viewport';
 
-type FormViewportProps = PropsWithChildren<{}>;
+type FormViewportProps = {};
 
-// TODO(burdon): Ref and props (allow asChild).
-const FormViewport = ({ children }: FormViewportProps) => {
+const FormViewport = composable<HTMLDivElement>(({ children, ...props }, forwardedRef) => {
   return (
-    <ScrollArea.Root orientation='vertical'>
+    <ScrollArea.Root {...composableProps(props)} orientation='vertical' centered padding thin ref={forwardedRef}>
       <ScrollArea.Viewport>{children}</ScrollArea.Viewport>
     </ScrollArea.Root>
   );
-};
+});
 
 FormViewport.displayName = FORM_VIEWPORT_NAME;
 
@@ -187,23 +203,25 @@ const FORM_CONTENT_NAME = 'Form.Content';
 
 type FormContentProps = ThemedClassName<PropsWithChildren<{}>>;
 
-// TOOD(burdon): Figure out nesting (indent and testId).
-const FormContent = ({ classNames, children }: FormContentProps) => {
+const FormContent = composable<HTMLDivElement, FormContentProps>(({ children, ...props }, forwardedRef) => {
   const { form, testId } = useFormContext(FORM_CONTENT_NAME);
-  const ref = useRef<HTMLDivElement>(null);
-  useKeyHandler(ref.current, form);
+  const localRef = useRef<HTMLDivElement>(null);
+  const mergedRef = useMergeRefs([forwardedRef, localRef]);
+  useKeyHandler(localRef, form);
 
   return (
     <div
-      ref={ref}
-      role='form'
-      className={mx('flex flex-col is-full pli-cardSpacingInline density-fine', classNames)}
+      {...composableProps(props, {
+        role: 'form',
+        classNames: mx(withColumn.center(), 'flex flex-col w-full pb-form-gap'),
+      })}
       data-testid={testId}
+      ref={mergedRef}
     >
       {children}
     </div>
   );
-};
+});
 
 FormContent.displayName = FORM_CONTENT_NAME;
 
@@ -213,12 +231,12 @@ FormContent.displayName = FORM_CONTENT_NAME;
 
 const FORM_FIELDSET_NAME = 'Form.FieldSet';
 
-type FormFieldSetProps = ThemedClassName<{}>;
+type FormFieldSetProps = ThemedClassName<NaturalFormFieldSetProps<any>>;
 
-const FormFieldSet = ({ classNames }: FormFieldSetProps) => {
-  const { form, ...props } = useFormContext(FORM_FIELDSET_NAME);
+const FormFieldSet = (props: FormFieldSetProps) => {
+  const { form, ...contextProps } = useFormContext(FORM_FIELDSET_NAME);
 
-  return <NaturalFormFieldSet classNames={classNames} schema={form.schema} {...props} />;
+  return <NaturalFormFieldSet schema={form.schema} {...contextProps} {...props} />;
 };
 
 FormFieldSet.displayName = FORM_FIELDSET_NAME;
@@ -247,12 +265,14 @@ const FormActions = ({ classNames }: FormActionsProps) => {
   //   Deprecate FormSubmit ans use FormActions without Cancel button if no callback is supplied.
 
   return (
-    <div role='none' className={mx('grid grid-flow-col auto-cols-fr gap-2 pbs-cardSpacingBlock', classNames)}>
+    <div
+      className={mx(withColumn.center(), 'grid grid-flow-col gap-form-gap auto-cols-fr py-form-padding', classNames)}
+    >
       {onCancel && (
         <IconButton
           icon='ph--x--regular'
           iconEnd
-          label={t('cancel button label')}
+          label={t('cancel-button.label')}
           onClick={onCancel}
           data-testid='cancel-button'
         />
@@ -264,7 +284,7 @@ const FormActions = ({ classNames }: FormActionsProps) => {
           disabled={!canSave}
           icon='ph--check--regular'
           iconEnd
-          label={t('save button label')}
+          label={t('save-button.label')}
           onClick={onSave}
           data-testid='save-button'
         />
@@ -275,6 +295,31 @@ const FormActions = ({ classNames }: FormActionsProps) => {
 
 FormActions.displayName = FORM_ACTIONS_NAME;
 
+//
+// Section
+//
+
+const FORM_SECTION_NAME = 'Form.Section';
+
+type FormSectionProps = ThemedClassName<{ label: string; description?: string }>;
+
+const FormSection = composable<HTMLDivElement, FormSectionProps>(
+  ({ children, label, description, ...props }, forwardedRef) => {
+    return (
+      <div
+        {...composableProps(props, { classNames: 'flex flex-col pt-form-section-gap first:pt-0' })}
+        ref={forwardedRef}
+      >
+        <h2 className='text-lg'>{label}</h2>
+        {description && <p className='text-description'>{description}</p>}
+        {children}
+      </div>
+    );
+  },
+);
+
+FormSection.displayName = FORM_SECTION_NAME;
+
 //
 // Submit
 //
@@ -296,14 +341,14 @@ const FormSubmit = ({ classNames, label, icon, disabled }: FormSubmitProps) => {
   }
 
   return (
-    <div role='none' className={mx('flex is-full pbs-cardSpacingBlock', classNames)}>
+    <div className={mx('flex w-full pt-form-padding', classNames)}>
       <IconButton
-        classNames='is-full'
+        classNames='w-full'
         type='submit'
         variant='primary'
         disabled={disabled ?? !canSave}
         icon={icon ?? 'ph--check--regular'}
-        label={label ?? t('save button label')}
+        label={label ?? t('save-button.label')}
         onClick={onSave}
         data-testid='save-button'
       />
@@ -322,10 +367,11 @@ export const Form = {
   Root: FormRoot,
   Viewport: FormViewport,
   Content: FormContent,
+  Section: FormSection,
   FieldSet: FormFieldSet,
+  Label: FormFieldLabel,
   Actions: FormActions,
   Submit: FormSubmit,
-  Label: FormFieldLabel,
 };
 
 export { useFormContext, useFormValues, useFormFieldState };
@@ -334,8 +380,9 @@ export type {
   FormRootProps,
   FormViewportProps,
   FormContentProps,
+  FormSectionProps,
   FormFieldSetProps,
+  FormFieldLabelProps,
   FormActionsProps,
   FormSubmitProps,
-  FormFieldLabelProps as LabelProps,
 };

package/src/components/Form/FormField.tsx

@@ -23,9 +23,9 @@ import {
 import { useTranslation } from '@dxos/react-ui';
 import { type ProjectionModel } from '@dxos/schema';
 
-import { translationKey } from '../../translations';
-import { getRefProps } from '../../util';
+import { translationKey } from '#translations';
 
+import { getRefProps } from '../../util';
 import {
   ArrayField,
   BooleanField,
@@ -78,14 +78,21 @@ export type FormFieldProps = {
    * Function to lookup custom renderers for specific properties.
    */
   fieldProvider?: FormFieldProvider;
+  /**
+   * 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.
+   */
+  createTypename?: string;
 } & Pick<FormFieldComponentProps, 'autoFocus' | 'readonly' | 'layout'> &
   Pick<
     RefFieldProps,
     | 'createOptionLabel'
     | 'createOptionIcon'
     | 'createInitialValuePath'
+    | 'createFieldMap'
     | 'db'
-    | 'schemaHook'
+    | 'useSchema'
     | 'getOptions'
     | 'onCreate'
   >;
@@ -102,12 +109,14 @@ export const FormField = (props: FormFieldProps) => {
     layout,
 
     // RefFieldProps
+    createTypename,
     createOptionLabel,
     createOptionIcon,
     createInitialValuePath,
+    createFieldMap,
     db,
-    schemaHook,
-    getOptions: getRefOptions,
+    useSchema: schemaHook,
+    getOptions,
     onCreate,
   } = props;
   const { t } = useTranslation(translationKey);
@@ -117,7 +126,7 @@ export const FormField = (props: FormFieldProps) => {
 
   const label = useMemo(() => title ?? String.capitalize(name), [title, name]);
   const placeholder = useMemo(
-    () => (examples?.length ? `${t('example placeholder')}: ${examples[0]}` : (description ?? label)),
+    () => (examples?.length ? `${t('example.placeholder')}: ${examples[0]}` : (description ?? label)),
     [examples, description, label],
   );
 
@@ -129,6 +138,7 @@ export const FormField = (props: FormFieldProps) => {
     label,
     placeholder,
     layout,
+    db,
     ...fieldState,
   };
 
@@ -169,15 +179,23 @@ export const FormField = (props: FormFieldProps) => {
   // Select field.
   //
 
-  const options = getOptions(type);
+  const options = getSelectOptions(type);
   if (options) {
+    // Resolve labels from projection metadata when available.
+    const fieldProjections = projection?.getFieldProjections();
+    const fieldProjection = fieldProjections?.find((fp) => fp.field.path === name);
+    const selectOptions = fieldProjection?.props.options;
+
     return (
       <SelectField
         {...fieldProps}
-        options={options.map((option) => ({
-          value: option,
-          label: option.toString(),
-        }))}
+        options={options.map((option) => {
+          const selectOption = selectOptions?.find((so) => so.id === globalThis.String(option));
+          return {
+            value: option,
+            label: selectOption?.title ?? option.toString(),
+          };
+        })}
       />
     );
   }
@@ -188,16 +206,18 @@ export const FormField = (props: FormFieldProps) => {
 
   const refProps = getRefProps(type);
   if (refProps) {
+    const isCreateTarget = !createTypename || refProps.typename === createTypename;
     return (
       <RefField
         {...fieldProps}
         {...refProps}
-        createOptionLabel={createOptionLabel}
-        createOptionIcon={createOptionIcon}
-        createInitialValuePath={createInitialValuePath}
+        createOptionLabel={isCreateTarget ? createOptionLabel : undefined}
+        createOptionIcon={isCreateTarget ? createOptionIcon : undefined}
+        createInitialValuePath={isCreateTarget ? createInitialValuePath : undefined}
+        createFieldMap={isCreateTarget ? createFieldMap : undefined}
         db={db}
-        schemaHook={schemaHook}
-        getOptions={getRefOptions}
+        useSchema={schemaHook}
+        getOptions={getOptions}
         onCreate={onCreate}
       />
     );
@@ -229,8 +249,8 @@ export const FormField = (props: FormFieldProps) => {
           createOptionIcon={createOptionIcon}
           createInitialValuePath={createInitialValuePath}
           db={db}
-          schemaHook={schemaHook}
-          getOptions={getRefOptions}
+          useSchema={schemaHook}
+          getOptions={getOptions}
           onCreate={onCreate}
         />
       );
@@ -277,7 +297,7 @@ const getFormField = ({ type, format }: FormFieldComponentProps): FormFieldCompo
   }
 };
 
-const getOptions = (ast: SchemaAST.AST): Format.Options[] | undefined => {
+const getSelectOptions = (ast: SchemaAST.AST): Format.Options[] | undefined => {
   if (isLiteralUnion(ast)) {
     return ast.types.map((type) => type.literal).filter((v): v is string | number => v !== null);
   }

package/src/components/Form/FormFieldComponent.stories.tsx

@@ -10,7 +10,7 @@ import { withLayout, withTheme } from '@dxos/react-ui/testing';
 
 import { type FormFieldComponentProps, FormFieldWrapper } from './FormFieldComponent';
 
-const Component = ({
+const DefaultStory = ({
   type,
   placeholder,
   readonly,
@@ -24,7 +24,7 @@ const Component = ({
   );
 
   return (
-    <div className='plb-cardSpacingBlock pli-cardSpacingInline'>
+    <div className='p-form-padding'>
       <FormFieldWrapper<string> {...props}>
         {({ value = '' }) => (
           <Input.TextInput
@@ -41,9 +41,9 @@ const Component = ({
   );
 };
 
-const meta: Meta<typeof Component> = {
+const meta: Meta<typeof DefaultStory> = {
   title: 'ui/react-ui-form/FormFieldComponent',
-  component: Component,
+  component: DefaultStory,
   decorators: [withTheme(), withLayout({ layout: 'column' })],
   parameters: {
     layout: 'fullscreen',

package/src/components/Form/FormFieldComponent.tsx

@@ -13,14 +13,13 @@ import React, {
   type ReactNode,
 } from 'react';
 
+import { type Database } from '@dxos/echo';
 import { type Format } from '@dxos/echo/internal';
 import { Icon, Input, Tooltip } from '@dxos/react-ui';
-import { errorText } from '@dxos/ui-theme';
+import { inputTextLabel } from '@dxos/ui-theme';
 
 import { type FormFieldStatus } from '../../hooks';
 
-const labelSpacing = 'mbs-inputSpacingBlock mbe-labelSpacingBlock';
-
 /**
  * Dynamic props passed to input components.
  */
@@ -33,7 +32,6 @@ export type FormFieldStateProps<T = any> = {
 
 /**
  * Presentation mode.
- *
  * - full: Show label, control, and status.
  * - compact: Show label and control.
  * - inline: Control only.
@@ -53,6 +51,8 @@ export type FormFieldComponentProps<T = any> = {
   placeholder?: string;
   autoFocus?: boolean;
   layout?: Presentation;
+  /** Database the form is editing against; populated for fields whose value is an ECHO object/Ref. */
+  db?: Database.Database;
 } & FormFieldStateProps<T>;
 
 /**
@@ -80,14 +80,14 @@ export type FormFieldLabelProps = {
 export const FormFieldLabel = ({ label, error, readonly, asChild }: FormFieldLabelProps) => {
   const Label = readonly || asChild ? 'span' : Input.Label;
   return (
-    <>
-      <Label>{label}</Label>
+    <div className='flex items-center justify-between'>
+      <Label className={inputTextLabel}>{label}</Label>
       {error && (
         <Tooltip.Trigger asChild content={error} side='bottom'>
-          <Icon icon='ph--warning--regular' size={4} classNames={errorText} />
+          <Icon icon='ph--warning--regular' size={4} classNames='text-error-text' />
         </Tooltip.Trigger>
       )}
-    </>
+    </div>
   );
 };
 
@@ -116,7 +116,7 @@ export const FormFieldWrapper = <T,>(props: FormFieldWrapperProps<T>) => {
   const str = String(value ?? '');
 
   return (
-    <div role='none' className='contents'>
+    <div className='contents'>
       <Input.Root validationValence={status}>
         {layout !== 'inline' && <FormFieldLabel error={error} readonly={readonly} label={label} />}
         {layout === 'static' ? <p>{str}</p> : children ? children({ value }) : null}
@@ -158,8 +158,8 @@ export class FormFieldErrorBoundary extends Component<FormFieldErrorBoundaryProp
   override render() {
     if (this.state.error) {
       return (
-        <div className='flex gap-2 border border-roseFill font-mono text-sm'>
-          <span className='bg-roseFill text-surfaceText pli-1 font-thin'>ERROR</span>
+        <div className='flex gap-2 border border-rose-fill font-mono text-sm'>
+          <span className='bg-rose-fill text-surface-text px-1 font-thin'>ERROR</span>
           {String(this.props.path?.join('.'))}
         </div>
       );