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

package/src/components/Form/Form.theme.test.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { formTheme } from './Form.theme';
+
+describe('formTheme', () => {
+  test('default variant adds no chrome to the field', ({ expect }) => {
+    const styles = formTheme.styles({ variant: 'default' });
+    expect(styles.field()).toBeFalsy();
+    expect(formTheme.behavior.default.showDescription).toBe(false);
+  });
+
+  test('settings variant frames the field and shows the description', ({ expect }) => {
+    const styles = formTheme.styles({ variant: 'settings' });
+    // Assert stable invariants (bordered, grid-framed, prominent label, right-aligned control),
+    // not the specific grid mechanism, so the test survives layout tweaks.
+    expect(styles.field()).toContain('border');
+    expect(styles.field()).toContain('grid');
+    expect(styles.fieldLabel()).toContain('[grid-area:header]');
+    expect(styles.fieldLabelText()).toContain('text-lg');
+    expect(styles.fieldControl()).toContain('justify-end');
+    expect(formTheme.behavior.settings.showDescription).toBe(true);
+  });
+
+  test('per-slot override wins', ({ expect }) => {
+    const styles = formTheme.styles({ variant: 'settings' });
+    expect(styles.fieldLabelText({ class: 'text-2xl' })).toContain('text-2xl');
+    expect(styles.fieldLabelText({ class: 'text-2xl' })).not.toContain('text-lg');
+  });
+});

package/src/components/Form/Form.theme.ts

@@ -0,0 +1,86 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type VariantProps, mx, tv } from '@dxos/ui-theme';
+
+/** Visual variants for {@link Form}. `settings` is the bordered two-column settings-panel look. */
+export type FormVariant = NonNullable<VariantProps<typeof formStyles>['variant']>;
+
+/** Non-className behavior flags, keyed by {@link FormVariant}. */
+export type FormBehavior = { showDescription: boolean };
+
+const formStyles = tv({
+  slots: {
+    viewport: '',
+    content: '',
+    section: 'flex flex-col py-form-section-gap first:pt-0',
+    group: 'flex flex-col gap-3 p-trim-md border border-separator rounded-sm',
+    sectionHeader: '',
+    sectionTitle: 'text-lg',
+    sectionDescription: 'text-description',
+    fieldSet: '',
+    field: '',
+    fieldLabel: 'h-8 grid grid-cols-[1fr_auto_auto] items-center select-none',
+    fieldLabelText: '',
+    fieldDescription: 'text-description',
+    fieldControl: '',
+    fieldValidation: '',
+    // Action bar (cancel/save), equal-width columns flowing horizontally.
+    actions: 'grid grid-flow-col gap-form-gap auto-cols-fr py-form-padding',
+    // Standalone submit row (full-width primary button).
+    submit: 'flex w-full pt-form-padding',
+    // Collapsible field-set body: indented column of sub-fields.
+    fieldSetBody: 'flex flex-col gap-2 px-2 pb-2',
+    // Bordered container wrapping a collapsible nested group, plus its top spacing.
+    fieldSetBox: 'border border-subdued-separator rounded-sm',
+    fieldSetBoxOuter: 'pt-trim-md',
+  },
+  variants: {
+    variant: {
+      default: {},
+      settings: {
+        content: 'dx-document',
+        // Gap on the section spaces its direct children — section title/description and, for action
+        // panels, the `Form.Row`s placed directly in the section (which have no `fieldSet` wrapper).
+        section: 'py-form-section-gap! gap-trim-md',
+        sectionHeader: 'pb-form-section-gap',
+        sectionTitle: 'px-trim-md text-xl',
+        sectionDescription: 'px-trim-md',
+        // No top padding: the section gap already separates the field set from the title above it.
+        fieldSet: 'flex flex-col gap-trim-md',
+        field: mx(
+          'grid',
+          'grid-cols-1 [grid-template-areas:"header""description""control""validation"]',
+          'md:grid-cols-2 md:[grid-template-areas:"header_header""description_control""validation_validation"]',
+          'gap-x-trim-lg gap-y-0 p-trim-md border border-input-separator rounded-md',
+        ),
+        fieldLabel: '[grid-area:header]',
+        fieldLabelText: 'text-base-fg text-lg',
+        fieldDescription: '[grid-area:description] pt-1 text-description',
+        fieldControl: '[grid-area:control] flex justify-end items-start md:text-right pt-3 md:pt-0',
+        fieldValidation: '[grid-area:validation]',
+      },
+    },
+  },
+  defaultVariants: {
+    variant: 'default',
+  },
+});
+
+/** {@link Form} theme template: a tailwind-variants recipe (`styles`) plus non-class `behavior`. */
+export const formTheme = {
+  styles: formStyles,
+  behavior: {
+    default: {
+      showDescription: false,
+    },
+    settings: {
+      showDescription: true,
+    },
+  } satisfies Record<FormVariant, FormBehavior>,
+};
+
+/** Slot names of {@link formTheme.styles}, for `bridgeTv` registration. */
+// Object.keys widens to string[]; the slot names are statically known.
+export const formSlots = Object.keys(formTheme.styles()) as Array<keyof ReturnType<typeof formTheme.styles>>;

package/src/components/Form/Form.tsx

@@ -2,474 +2,51 @@
 // Copyright 2025 DXOS.org
 //
 
-import { createContext } from '@radix-ui/react-context';
-import * as Option from 'effect/Option';
-import * as Schema from 'effect/Schema';
-import * as SchemaAST from 'effect/SchemaAST';
-import React, { type PropsWithChildren, useEffect, useMemo, useRef } from 'react';
-
-import { Annotation as EchoAnnotation, Type } from '@dxos/echo';
-import { type AnyProperties } from '@dxos/echo/internal';
-import { SchemaEx } from '@dxos/effect';
-import {
-  Column,
-  type ColumnRootProps,
-  IconButton,
-  type IconButtonProps,
-  Input,
-  ScrollArea,
-  type ThemedClassName,
-  useMergeRefs,
-  useTranslation,
-} from '@dxos/react-ui';
-import { composable, composableProps, withColumn } from '@dxos/react-ui';
-import { mx } from '@dxos/ui-theme';
-
-import { translationKey } from '#translations';
-
 import {
-  type FormHandler,
-  type FormHandlerProps,
-  type FormUpdateMeta,
-  useFormHandler,
-  useKeyHandler,
-} from '../../hooks';
-import { FormFieldLabel, type FormFieldLabelProps, type FormFieldStateProps } from './FormFieldComponent';
-import {
-  FormFieldSet as NaturalFormFieldSet,
-  type FormFieldSetProps as NaturalFormFieldSetProps,
-} from './FormFieldSet';
-import { FormTooltipsContext } from './FormTooltipsContext';
-import { FormLayout as NaturalFormLayout } from './Layout';
-import { type FormLayoutProps as NaturalFormLayoutProps } from './Layout/FormLayout';
-
-// TODO(burdon): Move styles to form.ts (as with ui-theme).
-
-// TODO(burdon): Reconcile with @dxos/echo.
-export type ExcludeId<S extends Schema.Schema.AnyNoContext | Type.AnyEntity> = Omit<
-  S extends Type.AnyEntity
-    ? Type.InstanceType<S>
-    : S extends Schema.Schema.AnyNoContext
-      ? Schema.Schema.Type<S>
-      : never,
-  'id'
->;
-
-// TODO(burdon): Move to @dxos/schema (re-export here).
-export const omitId = <S extends Schema.Schema.AnyNoContext | Type.AnyEntity>(
-  schemaOrType: S,
-): Schema.Schema<ExcludeId<S>, ExcludeId<S>> => {
-  const schema = Type.isType(schemaOrType)
-    ? Type.getSchema(schemaOrType)
-    : (schemaOrType as Schema.Schema.AnyNoContext);
-  return 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
-//
-
-type FormContextValue<T extends AnyProperties = any> = {
-  /**
-   * Form handler.
-   */
-  form: FormHandler<T>;
-
-  /**
-   * Show field tooltips (currently: JSON path on each label). Defaults to
-   * `true`; pass `false` to suppress.
-   */
-  tooltips?: boolean;
-
-  /**
-   * Testing.
-   */
-  testId?: string;
-} & Pick<
-  NaturalFormFieldSetProps<T>,
-  'readonly' | 'layout' | 'fieldMap' | 'fieldProvider' | 'projection' | 'createTypename' | 'createFieldMap' | 'db'
->;
-
-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 = SchemaEx.createJsonPath(stablePath);
-  const {
-    form: { values, onValueChange },
-  } = useFormContext(componentName);
-
-  const value = SchemaEx.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,
-  values,
-  onSave,
-  onCancel,
-  ...props
-}: FormRootProps<T>) => {
-  const form = useFormHandler({ schema, values, onSave, onCancel, ...props });
-
-  return (
-    <FormTooltipsContext.Provider value={props.tooltips ?? true}>
-      <FormContextProvider form={form} {...props}>
-        {children}
-      </FormContextProvider>
-    </FormTooltipsContext.Provider>
-  );
-};
-
-FormRoot.displayName = 'Form.Root';
-
-//
-// Viewport
-//
-
-const FORM_VIEWPORT_NAME = 'Form.Viewport';
-
-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).
-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';
-
-type FormContentProps = ThemedClassName<PropsWithChildren<{}>>;
-
-// The viewed body: centered in the viewport's gutter. Pure body — the gutter Column is owned by `Form.Viewport`.
-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';
-
-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;
-
-//
-// Layout
-//
-
-const FORM_LAYOUT_NAME = 'Form.Layout';
-
-type FormLayoutProps = Omit<NaturalFormLayoutProps, 'schema'> & { schema?: NaturalFormLayoutProps['schema'] };
-
-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';
-
-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
-      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';
-
-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}
-      >
-        {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';
-
-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 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';
-
-type FormErrorProps = ThemedClassName<PropsWithChildren>;
-
-/** Form-level error/validation message (e.g. a failed submit), styled via the error valence. */
-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;
-
-//
-// Form
-// https://www.radix-ui.com/primitives/docs/guides/composition
-//
+  FormActions,
+  type FormActionsProps,
+  FormContent,
+  type FormContentProps,
+  FormError,
+  FormFieldSetController,
+  FormGroup,
+  type FormGroupProps,
+  FormLayoutController,
+  type FormLayoutProps,
+  FormRoot,
+  type FormRootProps,
+  FormSection,
+  type FormSectionProps,
+  FormSubmit,
+  type FormSubmitProps,
+  FormViewport,
+  type FormViewportProps,
+} from './FormControls';
+import { FormFieldLabel, FormRow, type FormRowProps } from './FormField';
 
 export const Form = {
   Root: FormRoot,
   Viewport: FormViewport,
   Content: FormContent,
   Section: FormSection,
-  FieldSet: FormFieldSet,
-  Layout: FormLayout,
+  Group: FormGroup,
+  FieldSet: FormFieldSetController,
+  Layout: FormLayoutController,
   Label: FormFieldLabel,
+  Row: FormRow,
   Actions: FormActions,
   Submit: FormSubmit,
   Error: FormError,
 };
 
-export { useFormContext, useFormValues, useFormFieldState };
-
 export type {
-  FormRootProps,
-  FormViewportProps,
+  FormActionsProps,
   FormContentProps,
-  FormSectionProps,
-  FormFieldSetProps,
+  FormGroupProps,
   FormLayoutProps,
-  FormFieldLabelProps,
-  FormActionsProps,
+  FormRootProps,
+  FormRowProps,
+  FormSectionProps,
   FormSubmitProps,
+  FormViewportProps,
 };