@dxos/react-ui-form 0.8.4-main.9735255 → 0.8.4-main.9be5663bfe

package/src/components/Form/Form.tsx

@@ -4,13 +4,20 @@
 
 import { createContext } from '@radix-ui/react-context';
 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 { 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 } from '@dxos/ui-theme';
 
 import {
   type FormHandler,
@@ -20,29 +27,13 @@ import {
   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.
 
 // TODO(burdon): Move to @dxos/schema (re-export here).
 export type ExcludeId<S extends Schema.Schema.AnyNoContext> = Omit<Schema.Schema.Type<S>, 'id'>;
@@ -70,7 +61,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'
+>;
 
 const [FormContextProvider, useFormContext] = createContext<FormContextValue>('Form');
 
@@ -84,19 +78,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;
 };
@@ -164,65 +164,69 @@ FormRoot.displayName = 'Form.Root';
 // Viewport
 //
 
-type FormViewportProps = ThemedClassName<PropsWithChildren<{}>>;
+const FORM_VIEWPORT_NAME = 'Form.Viewport';
 
-const FormViewport = ({ classNames, children }: FormViewportProps) => {
+type FormViewportProps = {};
+
+const FormViewport = composable<HTMLDivElement>(({ children, ...props }, forwardedRef) => {
   return (
-    <ScrollArea.Root>
-      <ScrollArea.Viewport classNames={['plb-cardSpacingBlock', classNames]}>{children}</ScrollArea.Viewport>
-      <ScrollArea.Scrollbar orientation='vertical'>
-        <ScrollArea.Thumb />
-      </ScrollArea.Scrollbar>
+    <ScrollArea.Root {...composableProps(props)} orientation='vertical' centered padding thin ref={forwardedRef}>
+      <ScrollArea.Viewport>{children}</ScrollArea.Viewport>
     </ScrollArea.Root>
   );
-};
+});
 
-FormViewport.displayName = 'Form.Viewport';
+FormViewport.displayName = FORM_VIEWPORT_NAME;
 
 //
 // Content
 //
 
+const FORM_CONTENT_NAME = 'Form.Content';
+
 type FormContentProps = ThemedClassName<PropsWithChildren<{}>>;
 
-// TOOD(burdon): Figure out nesting (indent and testId).
-const FormContent = ({ classNames, children }: FormContentProps) => {
-  const { form, testId } = useFormContext(FormContent.displayName);
-  const ref = useRef<HTMLDivElement>(null);
-  useKeyHandler(ref.current, form);
+const FormContent = composable<HTMLDivElement, FormContentProps>(({ children, ...props }, forwardedRef) => {
+  const { form, testId } = useFormContext(FORM_CONTENT_NAME);
+  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: 'flex flex-col w-full pb-form-gap' })}
       data-testid={testId}
+      ref={mergedRef}
     >
       {children}
     </div>
   );
-};
+});
 
-FormContent.displayName = 'Form.Content';
+FormContent.displayName = FORM_CONTENT_NAME;
 
 //
 // FieldSet
 //
 
-type FormFieldSetProps = ThemedClassName<{}>;
+const FORM_FIELDSET_NAME = 'Form.FieldSet';
+
+type FormFieldSetProps = ThemedClassName<NaturalFormFieldSetProps<any>>;
 
-const FormFieldSet = ({ classNames }: FormFieldSetProps) => {
-  const { form, ...props } = useFormContext(FormFieldSet.displayName);
+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';
+FormFieldSet.displayName = FORM_FIELDSET_NAME;
 
 //
 // Actions
 //
 
+const FORM_ACTIONS_NAME = 'Form.Actions';
+
 type FormActionsProps = ThemedClassName<{}>;
 
 const FormActions = ({ classNames }: FormActionsProps) => {
@@ -231,7 +235,7 @@ const FormActions = ({ classNames }: FormActionsProps) => {
     form: { canSave, onSave, onCancel },
     readonly,
     layout,
-  } = useFormContext(FormActions.displayName);
+  } = useFormContext(FORM_ACTIONS_NAME);
 
   if (readonly || layout === 'static') {
     return null;
@@ -241,12 +245,12 @@ 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 role='none' className={mx('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'
         />
@@ -258,7 +262,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'
         />
@@ -267,35 +271,62 @@ const FormActions = ({ classNames }: FormActionsProps) => {
   );
 };
 
-FormActions.displayName = 'Form.Actions';
+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
 //
 
-type FormSubmitProps = ThemedClassName<Partial<Pick<IconButtonProps, 'icon' | 'label'>>>;
+const FORM_SUBMIT_NAME = 'Form.Submit';
+
+type FormSubmitProps = ThemedClassName<Partial<Pick<IconButtonProps, 'icon' | 'label' | 'disabled'>>>;
 
-const FormSubmit = ({ classNames, label, icon }: FormSubmitProps) => {
+const FormSubmit = ({ classNames, label, icon, disabled }: FormSubmitProps) => {
   const { t } = useTranslation(translationKey);
   const {
     form: { canSave, onSave },
     readonly,
     layout,
-  } = useFormContext(FormSubmit.displayName);
+  } = useFormContext(FORM_SUBMIT_NAME);
 
   if (readonly || layout === 'static') {
     return null;
   }
 
   return (
-    <div role='none' className={mx('flex is-full pbs-cardSpacingBlock', classNames)}>
+    <div role='none' className={mx('flex w-full pt-form-padding', classNames)}>
       <IconButton
-        classNames='is-full'
+        classNames='w-full'
         type='submit'
         variant='primary'
-        disabled={!canSave}
+        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'
       />
@@ -303,7 +334,7 @@ const FormSubmit = ({ classNames, label, icon }: FormSubmitProps) => {
   );
 };
 
-FormSubmit.displayName = 'Form.Submit';
+FormSubmit.displayName = FORM_SUBMIT_NAME;
 
 //
 // Form
@@ -314,10 +345,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 };
@@ -326,7 +358,9 @@ export type {
   FormRootProps,
   FormViewportProps,
   FormContentProps,
+  FormSectionProps,
   FormFieldSetProps,
+  FormFieldLabelProps,
   FormActionsProps,
-  FormFieldLabelProps as LabelProps,
+  FormSubmitProps,
 };

package/src/components/Form/FormField.tsx

@@ -25,7 +25,6 @@ import { type ProjectionModel } from '@dxos/schema';
 
 import { translationKey } from '../../translations';
 import { getRefProps } from '../../util';
-
 import {
   ArrayField,
   BooleanField,
@@ -78,12 +77,19 @@ 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'
     | 'getOptions'
@@ -102,12 +108,14 @@ export const FormField = (props: FormFieldProps) => {
     layout,
 
     // RefFieldProps
+    createTypename,
     createOptionLabel,
     createOptionIcon,
     createInitialValuePath,
+    createFieldMap,
     db,
     schemaHook,
-    getOptions: getRefOptions,
+    getOptions,
     onCreate,
   } = props;
   const { t } = useTranslation(translationKey);
@@ -117,7 +125,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],
   );
 
@@ -169,15 +177,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 +204,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}
+        getOptions={getOptions}
         onCreate={onCreate}
       />
     );
@@ -230,7 +248,7 @@ export const FormField = (props: FormFieldProps) => {
           createInitialValuePath={createInitialValuePath}
           db={db}
           schemaHook={schemaHook}
-          getOptions={getRefOptions}
+          getOptions={getOptions}
           onCreate={onCreate}
         />
       );
@@ -277,7 +295,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,10 +41,10 @@ const Component = ({
   );
 };
 
-const meta: Meta<typeof Component> = {
+const meta: Meta<typeof DefaultStory> = {
   title: 'ui/react-ui-form/FormFieldComponent',
-  component: Component,
-  decorators: [withTheme, withLayout({ layout: 'column' })],
+  component: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
   parameters: {
     layout: 'fullscreen',
   },

package/src/components/Form/FormFieldComponent.tsx

@@ -15,12 +15,10 @@ import React, {
 
 import { type Format } from '@dxos/echo/internal';
 import { Icon, Input, Tooltip } from '@dxos/react-ui';
-import { errorText, mx } 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 +31,6 @@ export type FormFieldStateProps<T = any> = {
 
 /**
  * Presentation mode.
- *
  * - full: Show label, control, and status.
  * - compact: Show label and control.
  * - inline: Control only.
@@ -79,14 +76,12 @@ export type FormFieldLabelProps = {
 
 export const FormFieldLabel = ({ label, error, readonly, asChild }: FormFieldLabelProps) => {
   const Label = readonly || asChild ? 'span' : Input.Label;
-  const labelProps = readonly || asChild ? { className: 'text-description text-sm' } : { classNames: '!mlb-0 text-sm' };
-
   return (
-    <div role='none' className={mx('flex justify-between items-center', labelSpacing)}>
-      <Label {...labelProps}>{label}</Label>
+    <div role='none' 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>
@@ -118,15 +113,17 @@ export const FormFieldWrapper = <T,>(props: FormFieldWrapperProps<T>) => {
   const str = String(value ?? '');
 
   return (
-    <Input.Root validationValence={status}>
-      {layout !== 'inline' && <FormFieldLabel error={error} readonly={readonly} label={label} />}
-      {layout === 'static' ? <p>{str}</p> : children ? children({ value }) : null}
-      {layout === 'full' && (
-        <Input.DescriptionAndValidation>
-          <Input.Validation>{error}</Input.Validation>
-        </Input.DescriptionAndValidation>
-      )}
-    </Input.Root>
+    <div role='none' className='contents'>
+      <Input.Root validationValence={status}>
+        {layout !== 'inline' && <FormFieldLabel error={error} readonly={readonly} label={label} />}
+        {layout === 'static' ? <p>{str}</p> : children ? children({ value }) : null}
+        {layout === 'full' && (
+          <Input.DescriptionAndValidation>
+            <Input.Validation>{error}</Input.Validation>
+          </Input.DescriptionAndValidation>
+        )}
+      </Input.Root>
+    </div>
   );
 };
 
@@ -158,8 +155,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>
       );