@dxos/react-ui-form 0.8.4-main.fd6878d → 0.8.4-staging.60fe92afc8

package/src/components/Form/FormField.tsx

@@ -0,0 +1,345 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Match from 'effect/Match';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+import * as String from 'effect/String';
+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 { getRefProps } from '../../util';
+import {
+  ArrayField,
+  BooleanField,
+  DateField,
+  GeoPointField,
+  InlineRefField,
+  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 = {
+  /**
+   * AST of the property to render.
+   */
+  type: SchemaAST.AST;
+
+  /**
+   * Name of the property. Used to derive a default label
+   * (`title ?? capitalize(name)`) and as the projection lookup key. Pass
+   * `null` to suppress the header label entirely -- the form still renders
+   * the field/struct, but `FormFieldSet`'s top-level `<FormFieldLabel>` is
+   * skipped. Used by `ArrayField` for object-array items, where every item
+   * would otherwise repeat the array's parent name.
+   */
+  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.
+   */
+  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'
+  >;
+
+export const FormField = (props: FormFieldProps) => {
+  const {
+    type,
+    name,
+    path,
+    projection,
+    fieldMap,
+    fieldProvider,
+    readonly,
+    layout,
+
+    // RefFieldProps
+    createTypename,
+    createOptionLabel,
+    createOptionIcon,
+    createInitialValuePath,
+    createFieldMap,
+    db,
+    useType: schemaHook,
+    getOptions,
+    onCreate,
+  } = 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 placeholder = useMemo(
+    () => (examples?.length ? `${t('example.placeholder')}: ${examples[0]}` : (description ?? label)),
+    [examples, description, label],
+  );
+
+  const fieldState = useFormFieldState(FormField.displayName, path);
+  const jsonPath = SchemaEx.createJsonPath(path ?? []);
+  const fieldProps: FormFieldComponentProps = {
+    type,
+    format: Format.FormatAnnotation.getFromAst(type).pipe((annotation) => Option.getOrUndefined(annotation)),
+    readonly,
+    label,
+    jsonPath,
+    placeholder,
+    layout,
+    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
+  // covers every field type (including those that bypass the wrapper:
+  // RefField, SelectField, MarkdownField, ...). Container fields
+  // (`ArrayField`, nested-struct -> `FormFieldSet`) keep their own
+  // empty-value checks, but those branches only apply when the value is
+  // actually a non-null array/object, so this check doesn't interfere.
+  if (readonly && fieldState.getValue() == null) {
+    return null;
+  }
+
+  //
+  // Custom field.
+  //
+
+  const CustomField = fieldMap?.[jsonPath];
+  if (CustomField) {
+    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;
+  }
+
+  //
+  // Array field.
+  //
+
+  if (SchemaEx.isArrayType(type)) {
+    return <ArrayField fieldProps={fieldState} label={label} {...props} />;
+  }
+
+  //
+  // Regular field.
+  //
+
+  const Field = getFormField(fieldProps);
+  if (Field) {
+    return <Field {...fieldProps} />;
+  }
+
+  //
+  // Select field.
+  //
+
+  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) => {
+          const selectOption = selectOptions?.find((so) => so.id === globalThis.String(option));
+          return {
+            value: option,
+            label: selectOption?.title ?? option.toString(),
+          };
+        })}
+      />
+    );
+  }
+
+  //
+  // Ref field.
+  //
+
+  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));
+    if (inline && !refProps.isArray) {
+      return <InlineRefField {...fieldProps} {...refProps} db={db} useType={schemaHook} onCreate={onCreate} />;
+    }
+
+    const isCreateTarget = !createTypename || refProps.typename === createTypename;
+    return (
+      <RefField
+        {...fieldProps}
+        {...refProps}
+        createOptionLabel={isCreateTarget ? createOptionLabel : undefined}
+        createOptionIcon={isCreateTarget ? createOptionIcon : undefined}
+        createInitialValuePath={isCreateTarget ? createInitialValuePath : undefined}
+        createFieldMap={isCreateTarget ? createFieldMap : undefined}
+        db={db}
+        useType={schemaHook}
+        getOptions={getOptions}
+        onCreate={onCreate}
+      />
+    );
+  }
+
+  //
+  // Nested Object field.
+  //
+
+  if (SchemaEx.isNestedType(type)) {
+    const baseNode = SchemaEx.findNode(type, SchemaEx.isDiscriminatedUnion);
+    const typeLiteral = baseNode
+      ? SchemaEx.getDiscriminatedType(baseNode, fieldState.getValue() as any)
+      : SchemaEx.findNode(type, SchemaAST.isTypeLiteral);
+
+    if (typeLiteral) {
+      const schema = Schema.make(typeLiteral);
+      return (
+        <FormFieldSet
+          schema={schema}
+          path={path}
+          readonly={readonly}
+          layout={layout}
+          label={label}
+          collapsible
+          projection={projection}
+          fieldMap={fieldMap}
+          fieldProvider={fieldProvider}
+          createOptionLabel={createOptionLabel}
+          createOptionIcon={createOptionIcon}
+          createInitialValuePath={createInitialValuePath}
+          db={db}
+          useType={schemaHook}
+          getOptions={getOptions}
+          onCreate={onCreate}
+        />
+      );
+    }
+  }
+
+  return null;
+};
+
+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>
+  );
+};
+
+/**
+ * Get property input component.
+ */
+const getFormField = ({ type, format }: FormFieldComponentProps): FormFieldComponent | undefined => {
+  //
+  // Standard formats.
+  //
+
+  const formatField = Match.value(format).pipe(
+    Match.withReturnType<FormFieldComponent | 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.Text, () => TextAreaField),
+    Match.when(Format.TypeFormat.Time, () => DateField),
+    Match.orElse(() => undefined),
+  );
+  if (formatField) {
+    return formatField;
+  }
+
+  //
+  // Standard types.
+  //
+
+  switch (type._tag) {
+    // TODO(wittjosiah): Schema.Any is currently used to represent template inputs.
+    case 'AnyKeyword':
+    case 'StringKeyword':
+      return TextField;
+    case 'NumberKeyword':
+      return NumberField;
+    case 'BooleanKeyword':
+      return BooleanField;
+  }
+};
+
+const getSelectOptions = (ast: SchemaAST.AST): Format.Options[] | undefined => {
+  if (SchemaEx.isLiteralUnion(ast)) {
+    return ast.types.map((type) => type.literal).filter((v): v is string | number => v !== null);
+  }
+
+  return Format.OptionsAnnotation.getFromAst(ast).pipe((annotation) => Option.getOrUndefined(annotation));
+};

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

@@ -0,0 +1,65 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+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';
+
+const DefaultStory = ({
+  type,
+  placeholder,
+  readonly,
+  onBlur,
+  onValueChange,
+  ...props
+}: FormFieldComponentProps<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>
+  );
+};
+
+const meta: Meta<typeof DefaultStory> = {
+  title: 'ui/react-ui-form/FormFieldComponent',
+  component: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  parameters: {
+    layout: 'fullscreen',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    label: 'Label',
+    getStatus: () => ({ status: 'error', error: 'Required field' }),
+    getValue: () => 'DXOS',
+    onBlur: () => {},
+    onValueChange: () => {},
+  },
+};

package/src/components/Form/FormFieldComponent.tsx

@@ -0,0 +1,253 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { format as formatDate } from 'date-fns';
+import type * as Schema from 'effect/Schema';
+import type * as SchemaAST from 'effect/SchemaAST';
+import React, {
+  Component,
+  type FC,
+  type FocusEvent,
+  type PropsWithChildren,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+
+import { type Database, Format } from '@dxos/echo';
+import { Icon, Input, ThemedClassName, Tooltip } from '@dxos/react-ui';
+import { inputTextLabel } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+
+import { type FormFieldStatus } from '../../hooks';
+import { useFormTooltips } from './FormTooltipsContext';
+
+/**
+ * Dynamic props passed to input components.
+ */
+export type FormFieldStateProps<T = any> = {
+  getStatus: () => FormFieldStatus;
+  getValue: () => T | undefined;
+  onBlur: (event: FocusEvent<HTMLElement>) => void;
+  onValueChange: (type: SchemaAST.AST, value: T) => void;
+};
+
+/**
+ * Presentation mode.
+ * - full: Show label, control, and status.
+ * - compact: Show label and control.
+ * - inline: Control only.
+ * - static: Plain DOM; omit all undefined values.
+ */
+// TODO(burdon): 'inline' should be orthogonal to the layout (e.g., array of inline static).
+export type Presentation = 'full' | 'compact' | 'inline' | 'static';
+
+/**
+ * Props passed to input components.
+ */
+export type FormFieldComponentProps<T = any> = {
+  /** Database the form is editing against; populated for fields whose value is an ECHO object/Ref. */
+  db?: Database.Database;
+  type: SchemaAST.AST;
+  format?: Format.TypeFormat;
+  readonly?: boolean;
+  label: string;
+  /**
+   * Dotted JSON path of this field within the form values (e.g.
+   * `runtime.client.storage.persistent`). Forwarded to `FormFieldLabel` so
+   * that it can render the path as a debug hint when the enclosing
+   * `Form.Root` has `debug` enabled.
+   */
+  jsonPath?: string;
+  placeholder?: string;
+  autoFocus?: boolean;
+  layout?: Presentation;
+} & FormFieldStateProps<T>;
+
+export type FormFieldComponent = FC<FormFieldComponentProps>;
+
+export type FormFieldMap = Record<string, FormFieldComponent>;
+
+export type FormFieldProvider = (props: {
+  prop: string;
+  schema: Schema.Schema<any>;
+  fieldProps: FormFieldComponentProps;
+}) => ReactElement | null | undefined;
+
+//
+// FormFieldLabel
+//
+
+export type FormFieldLabelProps = ThemedClassName<
+  {
+    asChild?: boolean;
+    error?: string;
+    /**
+     * JSON path of the field this label describes (e.g. `runtime.client.storage.persistent`).
+     * Surfaced as a hover tooltip on the label when the enclosing `Form.Root`
+     * has `tooltips` enabled (the default) -- useful for spotting which field
+     * maps to which path when authoring schemas or filing bugs against a form.
+     * Callers can supply the path unconditionally; the label suppresses the
+     * tooltip when `Form.Root tooltips={false}`.
+     */
+    path?: string;
+    /**
+     * Trailing button rendered at the end of the label row (third grid column).
+     * Used by nested-object field sets to surface a collapse toggle.
+     */
+    button?: ReactNode;
+    onClick?: () => void;
+  } & Pick<FormFieldComponentProps, 'label' | 'readonly'>
+>;
+
+export const FormFieldLabel = ({
+  classNames,
+  label,
+  error,
+  readonly,
+  asChild,
+  path,
+  button,
+  onClick,
+}: FormFieldLabelProps) => {
+  const tooltips = useFormTooltips();
+  const Label = readonly || asChild ? 'span' : Input.Label;
+  const labelNode = <Label className={mx(inputTextLabel, 'text-sm')}>{label}</Label>;
+
+  return (
+    <div
+      className={mx('grid grid-cols-[1fr_auto_auto] items-center select-none', onClick && 'cursor-pointer', classNames)}
+      onClick={onClick}
+    >
+      {tooltips && path ? (
+        <Tooltip.Trigger asChild content={path} side='bottom'>
+          {labelNode}
+        </Tooltip.Trigger>
+      ) : (
+        labelNode
+      )}
+      {error ? (
+        <Tooltip.Trigger asChild content={error} side='bottom'>
+          <Icon icon='ph--warning--regular' size={4} classNames='text-error-text' />
+        </Tooltip.Trigger>
+      ) : (
+        <span />
+      )}
+      {button}
+    </div>
+  );
+};
+
+FormFieldLabel.displayName = 'Form.FieldLabel';
+
+//
+// FormFieldWrapper
+//
+
+export type FormFieldWrapperProps<T = any> = Pick<
+  FormFieldComponentProps,
+  'readonly' | 'label' | 'layout' | 'getStatus' | 'getValue' | 'jsonPath' | 'format'
+> & {
+  children?: (props: { value: T }) => ReactNode;
+};
+
+/**
+ * Formats a value for `static` (read-only, plain-DOM) presentation based on its
+ * type `format`. Dates/times are rendered human-readable; everything else falls
+ * back to `String(value)`.
+ */
+const formatStaticValue = (value: unknown, format?: Format.TypeFormat): string => {
+  if (value == null) {
+    return '';
+  }
+
+  switch (format) {
+    case Format.TypeFormat.DateTime:
+    case Format.TypeFormat.Date:
+    case Format.TypeFormat.Time: {
+      const date = new Date(value as string);
+      if (Number.isNaN(date.getTime())) {
+        return String(value);
+      }
+      const pattern = format === Format.TypeFormat.DateTime ? 'PPp' : format === Format.TypeFormat.Date ? 'PP' : 'p';
+      return formatDate(date, pattern);
+    }
+    default:
+      return String(value);
+  }
+};
+
+export const FormFieldWrapper = <T,>(props: FormFieldWrapperProps<T>) => {
+  const { children, readonly, layout, label, jsonPath, format, getStatus, getValue } = props;
+  const { status, error } = getStatus();
+
+  const value = getValue();
+  if (layout === 'static' && value == null) {
+    return null;
+  }
+
+  const str = formatStaticValue(value, format);
+
+  return (
+    <div className='contents'>
+      <Input.Root validationValence={status}>
+        {layout !== 'inline' && <FormFieldLabel error={error} readonly={readonly} label={label} path={jsonPath} />}
+        {layout === 'static' ? (
+          <p className='truncate min-w-0' title={str}>
+            {str}
+          </p>
+        ) : children ? (
+          children({ value })
+        ) : null}
+        {layout === 'full' && error && (
+          <Input.DescriptionAndValidation>
+            <Input.Validation>{error}</Input.Validation>
+          </Input.DescriptionAndValidation>
+        )}
+      </Input.Root>
+    </div>
+  );
+};
+
+//
+// FormFieldErrorBoundary
+//
+
+type FormFieldErrorState = {
+  error: Error | undefined;
+};
+
+type FormFieldErrorBoundaryProps = PropsWithChildren<{
+  path?: (string | number)[];
+}>;
+
+export class FormFieldErrorBoundary extends Component<FormFieldErrorBoundaryProps, FormFieldErrorState> {
+  static getDerivedStateFromError(error: Error): { error: Error } {
+    return { error };
+  }
+
+  override state = { error: undefined };
+
+  override componentDidUpdate(prevProps: FormFieldErrorBoundaryProps) {
+    if (prevProps.path !== this.props.path) {
+      this.resetError();
+    }
+  }
+
+  override render() {
+    if (this.state.error) {
+      return (
+        <div className='flex gap-2 border border-rose-bg font-mono text-sm'>
+          <span className='bg-rose-bg text-base-fg px-1 font-thin'>ERROR</span>
+          {String(this.props.path?.join('.'))}
+        </div>
+      );
+    }
+
+    return this.props.children;
+  }
+
+  private resetError() {
+    this.setState({ error: undefined });
+  }
+}