@dxos/react-ui-form 0.9.0 → 0.9.1-main.c7dcc2e112

package/src/components/Form/FormControls.tsx

@@ -0,0 +1,320 @@
+//
+// 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 { mx } from '@dxos/ui-theme';
+
+import { translationKey } from '#translations';
+
+import {
+  FormContextProvider,
+  type FormContextValue,
+  type FormHandlerProps,
+  type FormUpdateMeta,
+  useFormContext,
+  useFormHandler,
+  useKeyHandler,
+} from '../../hooks';
+import {
+  FormFieldSet as NaturalFormFieldSet,
+  type FormFieldSetProps as NaturalFormFieldSetProps,
+} from './FormFieldSet';
+import { FormLayout as NaturalFormLayout, type FormLayoutProps as NaturalFormLayoutProps } from './FormLayout';
+
+//
+// Root
+//
+
+export 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'>
+>;
+
+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 = 'xs', ...props }, forwardedRef) => {
+    // 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)} orientation='vertical' centered padding thin ref={forwardedRef}>
+            <ScrollArea.Viewport>{children}</ScrollArea.Viewport>
+          </ScrollArea.Root>
+        </Column.Root>
+      );
+    }
+
+    return (
+      <Column.Root {...composableProps(props)} gutter={gutter} classNames={['w-full min-w-0', span]} 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 } = useFormContext(FORM_CONTENT_NAME);
+  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'),
+      })}
+      data-testid={testId}
+      ref={mergedRef}
+    >
+      {children}
+    </div>
+  );
+});
+
+FormContent.displayName = FORM_CONTENT_NAME;
+
+//
+// FieldSet
+//
+
+const FORM_FIELDSET_NAME = 'Form.FieldSet';
+
+export type FormFieldSetProps = ThemedClassName<NaturalFormFieldSetProps<any>>;
+
+export const FormFieldSet = (props: FormFieldSetProps) => {
+  const { form, ...contextProps } = useFormContext(FORM_FIELDSET_NAME);
+
+  return <NaturalFormFieldSet schema={form.schema} {...contextProps} {...props} />;
+};
+
+FormFieldSet.displayName = FORM_FIELDSET_NAME;
+
+//
+// Layout
+//
+
+const FORM_LAYOUT_NAME = 'Form.Layout';
+
+export type FormLayoutProps = Omit<NaturalFormLayoutProps, 'schema'> & { schema?: NaturalFormLayoutProps['schema'] };
+
+export const FormLayout = ({ schema, ...props }: FormLayoutProps) => {
+  const { form, ...contextProps } = useFormContext(FORM_LAYOUT_NAME);
+  const resolvedSchema = schema ?? form.schema;
+  if (!resolvedSchema) {
+    return null;
+  }
+
+  return <NaturalFormLayout schema={resolvedSchema} {...contextProps} {...props} />;
+};
+
+FormLayout.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(), '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')}
+          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<{ label?: string; description?: string }>;
+
+export 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}
+      >
+        {label && <h2 className='text-lg'>{label}</h2>}
+        {description && <p className='text-description'>{description}</p>}
+        {children}
+      </div>
+    );
+  },
+);
+
+FormSection.displayName = FORM_SECTION_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('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;
+
+//
+// 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/FieldHeader.tsx

@@ -0,0 +1,36 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React from 'react';
+
+import { CompactIconButton } from './FormField';
+import { FormFieldLabel } from './FormFieldWrapper';
+
+export type FieldHeaderProps = {
+  label: string;
+  /** JSON path forwarded to the label as field metadata. */
+  path?: string;
+  readonly?: boolean;
+  /** Trailing inline add affordance; omit to hide it. */
+  add?: { icon?: string; label: string; disabled?: boolean; onClick: () => void };
+};
+
+/**
+ * Header row for an array/list field: a label with an optional inline add button.
+ */
+export const FieldHeader = ({ label, path, readonly, add }: FieldHeaderProps) => (
+  <div className='flex items-center gap-2'>
+    <div className='flex-1 min-w-0'>
+      <FormFieldLabel readonly={readonly} label={label} path={path} standalone />
+    </div>
+    {!readonly && add && (
+      <CompactIconButton
+        disabled={add.disabled}
+        icon={add.icon ?? 'ph--plus--regular'}
+        label={add.label}
+        onClick={add.onClick}
+      />
+    )}
+  </div>
+);

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

@@ -11,13 +11,20 @@ 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 { IconBlock, IconButton, IconButtonProps, useTranslation } from '@dxos/react-ui';
 
 import { translationKey } from '#translations';
-
-import { getRefProps } from '../../util';
+import {
+  type CreateOptions,
+  type FormFieldOptions,
+  type FormFieldRenderer,
+  type FormFieldRendererProps,
+  type RefFieldDataProps,
+} from '#types';
+
+import { useFormFieldState } from '../../../hooks';
+import { getRefProps } from '../../../util';
+import { FormFieldSet } from '../FormFieldSet';
 import {
   ArrayField,
   BooleanField,
@@ -27,19 +34,10 @@ import {
   MarkdownField,
   NumberField,
   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 = {
   /**
@@ -61,41 +59,10 @@ export type FormFieldProps = {
    * 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.
-   */
-  fieldMap?: FormFieldMap;
-
-  /**
-   * 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'
-    | 'useType'
-    | 'getOptions'
-    | 'onCreate'
-  >;
+  autoFocus?: boolean;
+} & FormFieldOptions &
+  Pick<RefFieldDataProps, 'getOptions' | 'onCreate' | 'useType'> &
+  CreateOptions;
 
 export const FormField = (props: FormFieldProps) => {
   const {
@@ -115,7 +82,7 @@ export const FormField = (props: FormFieldProps) => {
     createInitialValuePath,
     createFieldMap,
     db,
-    useType: schemaHook,
+    useType,
     getOptions,
     onCreate,
   } = props;
@@ -136,7 +103,7 @@ export const FormField = (props: FormFieldProps) => {
 
   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,
@@ -226,7 +193,7 @@ export const FormField = (props: FormFieldProps) => {
     // 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));
     if (inline && !refProps.isArray) {
-      return <InlineRefField {...fieldProps} {...refProps} db={db} useType={schemaHook} onCreate={onCreate} />;
+      return <InlineRefField {...fieldProps} {...refProps} db={db} useType={useType} onCreate={onCreate} />;
     }
 
     const isCreateTarget = !createTypename || refProps.typename === createTypename;
@@ -239,7 +206,7 @@ export const FormField = (props: FormFieldProps) => {
         createInitialValuePath={isCreateTarget ? createInitialValuePath : undefined}
         createFieldMap={isCreateTarget ? createFieldMap : undefined}
         db={db}
-        useType={schemaHook}
+        useType={useType}
         getOptions={getOptions}
         onCreate={onCreate}
       />
@@ -273,7 +240,7 @@ export const FormField = (props: FormFieldProps) => {
           createOptionIcon={createOptionIcon}
           createInitialValuePath={createInitialValuePath}
           db={db}
-          useType={schemaHook}
+          useType={useType}
           getOptions={getOptions}
           onCreate={onCreate}
         />
@@ -290,24 +257,33 @@ FormField.displayName = 'Form.FormField';
 // Layout components
 //
 
-export const IconBlock = ({ inline, ...props }: IconButtonProps & { inline?: boolean }) => {
+export const CompactIconButton = (props: IconButtonProps) => {
   return (
-    <div className={mx('h-full flex px-1', inline ? 'items-center' : 'flex-col pt-2.5')}>
+    // IconBlock defaults to aria-hidden (decorative slot); the button is interactive, so un-hide it.
+    <IconBlock aria-hidden={false} classNames='my-[1px]'>
       <IconButton variant='ghost' density='xs' square iconOnly {...props} />
-    </div>
+    </IconBlock>
   );
 };
 
 /**
  * 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),

package/src/components/Form/{FormFieldComponent.stories.tsx → FormField/FormFieldWrapper.stories.tsx}

@@ -8,7 +8,10 @@ import React, { type ChangeEvent, useCallback } from 'react';
 import { Input } from '@dxos/react-ui';
 import { withLayout, withTheme } from '@dxos/react-ui/testing';
 
-import { type FormFieldComponentProps, FormFieldWrapper } from './FormFieldComponent';
+import { type FormFieldRendererProps } from '#types';
+
+import { Form } from '../Form';
+import { FormFieldWrapper } from './FormFieldWrapper';
 
 const DefaultStory = ({
   type,
@@ -17,32 +20,36 @@ const DefaultStory = ({
   onBlur,
   onValueChange,
   ...props
-}: FormFieldComponentProps<string>) => {
+}: FormFieldRendererProps<string>) => {
   const handleChange = useCallback(
     (event: ChangeEvent<HTMLInputElement>) => onValueChange(type, event.target.value),
     [type, onValueChange],
   );
 
   return (
-    <div className='p-form-padding'>
-      <FormFieldWrapper<string> {...props}>
-        {({ value = '' }) => (
-          <Input.TextInput
-            disabled={!!readonly}
-            placeholder={placeholder}
-            noAutoFill
-            value={value}
-            onChange={handleChange}
-            onBlur={onBlur}
-          />
-        )}
-      </FormFieldWrapper>
-    </div>
+    <Form.Root>
+      <Form.Viewport>
+        <Form.Content>
+          <FormFieldWrapper<string> {...props}>
+            {({ value = '' }) => (
+              <Input.TextInput
+                disabled={!!readonly}
+                placeholder={placeholder}
+                noAutoFill
+                value={value}
+                onChange={handleChange}
+                onBlur={onBlur}
+              />
+            )}
+          </FormFieldWrapper>
+        </Form.Content>
+      </Form.Viewport>
+    </Form.Root>
   );
 };
 
 const meta: Meta<typeof DefaultStory> = {
-  title: 'ui/react-ui-form/FormFieldComponent',
+  title: 'ui/react-ui-form/FormFieldWrapper',
   component: DefaultStory,
   decorators: [withTheme(), withLayout({ layout: 'column' })],
   parameters: {