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

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

@@ -3,76 +3,13 @@
 //
 
 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';
+import React, { Component, type PropsWithChildren, type ReactNode } from 'react';
 
-/**
- * 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';
+import { Format } from '@dxos/echo';
+import { inputTextLabel, Icon, Input, ThemedClassName, Tooltip } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
 
-/**
- * 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;
+import { type FormFieldRendererProps } from '#types';
 
 //
 // FormFieldLabel
@@ -80,15 +17,12 @@ export type FormFieldProvider = (props: {
 
 export type FormFieldLabelProps = ThemedClassName<
   {
-    asChild?: boolean;
+    /** Render a plain `<span>` instead of an input-associated `Input.Label`, for labels used outside an `Input.Root` (e.g. section/group headers). */
+    standalone?: 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}`.
+     * Field metadata; accepted by callers but not currently rendered.
      */
     path?: string;
     /**
@@ -97,7 +31,7 @@ export type FormFieldLabelProps = ThemedClassName<
      */
     button?: ReactNode;
     onClick?: () => void;
-  } & Pick<FormFieldComponentProps, 'label' | 'readonly'>
+  } & Pick<FormFieldRendererProps, 'label' | 'readonly'>
 >;
 
 export const FormFieldLabel = ({
@@ -105,13 +39,11 @@ export const FormFieldLabel = ({
   label,
   error,
   readonly,
-  asChild,
-  path,
+  standalone,
   button,
   onClick,
 }: FormFieldLabelProps) => {
-  const tooltips = useFormTooltips();
-  const Label = readonly || asChild ? 'span' : Input.Label;
+  const Label = readonly || standalone ? 'span' : Input.Label;
   const labelNode = <Label className={mx(inputTextLabel, 'text-sm')}>{label}</Label>;
 
   return (
@@ -119,13 +51,7 @@ export const FormFieldLabel = ({
       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
-      )}
+      {labelNode}
       {error ? (
         <Tooltip.Trigger asChild content={error} side='bottom'>
           <Icon icon='ph--warning--regular' size={4} classNames='text-error-text' />
@@ -144,13 +70,6 @@ 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
@@ -177,6 +96,13 @@ const formatStaticValue = (value: unknown, format?: Format.TypeFormat): string =
   }
 };
 
+export type FormFieldWrapperProps<T = any> = Pick<
+  FormFieldRendererProps,
+  'readonly' | 'label' | 'layout' | 'getStatus' | 'getValue' | 'jsonPath' | 'format'
+> & {
+  children?: (props: { value: T }) => ReactNode;
+};
+
 export const FormFieldWrapper = <T,>(props: FormFieldWrapperProps<T>) => {
   const { children, readonly, layout, label, jsonPath, format, getStatus, getValue } = props;
   const { status, error } = getStatus();
@@ -237,8 +163,8 @@ export class FormFieldErrorBoundary extends Component<FormFieldErrorBoundaryProp
   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>
+        <div className='flex gap-2 border border-error-border font-mono text-sm'>
+          <span className='bg-error-bg text-base-fg px-1 font-thin'>ERROR</span>
           {String(this.props.path?.join('.'))}
         </div>
       );

package/src/components/Form/FormField/fields/ArrayField/ArrayField.stories.tsx

@@ -0,0 +1,103 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Schema from 'effect/Schema';
+import React, { useState } from 'react';
+
+import { FormLayoutAnnotation, FormOrderedAnnotation, LabelAnnotation } from '@dxos/echo/Annotation';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { trim } from '@dxos/util';
+
+import { translations } from '#translations';
+
+import { TestLayout } from '../../../../../testing';
+import { Form } from '../../../Form';
+
+// Mirrors the structure of `Pipeline` (`@dxos/types`): a scalar header plus an
+// array of `Column`-like structs. The array is the field we render as either a
+// static or an ordered (drag-to-reorder) list.
+const Column = Schema.Struct({
+  name: Schema.String.annotations({ title: 'Name' }),
+  value: Schema.optional(Schema.Number.annotations({ title: 'Value' })),
+}).pipe(
+  Schema.mutable,
+  LabelAnnotation.set(['name']),
+  FormLayoutAnnotation.set({
+    default: trim`
+      <grid cols="2">
+        <field name="name"/>
+        <field name="value"/>
+      </grid>
+    `,
+  }),
+);
+type Column = Schema.Schema.Type<typeof Column>;
+
+const columnsField = Schema.Array(Column).pipe(Schema.mutable, Schema.annotations({ title: 'Columns' }));
+
+const headerFields = {
+  name: Schema.String.pipe(Schema.annotations({ title: 'Name' }), Schema.optional),
+  description: Schema.String.pipe(Schema.annotations({ title: 'Description' }), Schema.optional),
+};
+
+const Pipeline = Schema.Struct({
+  ...headerFields,
+  columns: columnsField,
+}).pipe(Schema.mutable);
+
+// `FormOrderedAnnotation` opts the array into a drag-to-reorder list (see `ArrayField`).
+const OrderedPipeline = Schema.Struct({
+  ...headerFields,
+  columns: columnsField.pipe(FormOrderedAnnotation.set(true)),
+}).pipe(Schema.mutable);
+
+type Pipeline = Schema.Schema.Type<typeof Pipeline>;
+
+const initialValues: Pipeline = {
+  name: 'Sales',
+  description: 'Lead qualification pipeline.',
+  columns: [{ name: 'Contacts' }, { name: 'Organizations' }, { name: 'Tasks' }, { name: 'Messages', value: 100 }],
+};
+
+const StoryComponent = ({ schema }: { schema: typeof Pipeline }) => {
+  const [values, setValues] = useState<Pipeline>(initialValues);
+
+  return (
+    <TestLayout json={values}>
+      <Form.Root
+        schema={schema}
+        values={values}
+        onValuesChanged={(values) => setValues((prev) => ({ ...prev, ...values }))}
+      >
+        <Form.Viewport scroll>
+          <Form.Content>
+            <Form.FieldSet />
+          </Form.Content>
+        </Form.Viewport>
+      </Form.Root>
+    </TestLayout>
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-form/FormField/ArrayField',
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof StoryComponent>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => <StoryComponent schema={Pipeline} />,
+};
+
+export const Ordered: Story = {
+  render: () => <StoryComponent schema={OrderedPipeline} />,
+};

package/src/components/Form/FormField/fields/ArrayField/ArrayField.tsx

@@ -0,0 +1,269 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Option from 'effect/Option';
+import * as SchemaAST from 'effect/SchemaAST';
+import React, { type ReactNode, useCallback, useRef } from 'react';
+
+import { Annotation, Ref } from '@dxos/echo';
+import { SchemaEx } from '@dxos/effect';
+import { useTranslation } from '@dxos/react-ui';
+import { OrderedList } from '@dxos/react-ui-list';
+import { arrayMove } from '@dxos/util';
+
+import { translationKey } from '#translations';
+import { type FormFieldStateProps } from '#types';
+
+import { useFormValues } from '../../../../../hooks';
+import { getFormProperties } from '../../../../../util';
+import { FieldHeader } from '../../FieldHeader';
+import { CompactIconButton, FormField, type FormFieldProps } from '../../FormField';
+
+// Synthetic id assigned to each row when rendering an ordered list. Plain form
+// values have no stable identity, so drag-and-drop (which requires a stable key
+// surviving the `onValuesChanged` round-trip) is given one here and kept in
+// lockstep with the array via the add/delete/move handlers.
+const DND_ID = '__dndId';
+
+type OrderedItem = {
+  [DND_ID]: string;
+  value: unknown;
+  index: number;
+};
+
+const isOrderedItem = (item: any): item is OrderedItem =>
+  !!item && typeof item === 'object' && typeof item[DND_ID] === 'string';
+
+const getOrderedId = (item: OrderedItem): string => item[DND_ID];
+
+export type ArrayFieldProps = {
+  label: string;
+  fieldProps: FormFieldStateProps;
+} & FormFieldProps;
+
+export const ArrayField = ({
+  type,
+  path,
+  label,
+  readonly,
+  layout,
+  fieldProps: inputProps,
+  ...props
+}: ArrayFieldProps) => {
+  const { t } = useTranslation(translationKey);
+  const elementType = SchemaEx.getArrayElementType(type);
+  const { onValueChange } = inputProps;
+  const values = useFormValues(ArrayField.displayName, path, () => []);
+
+  // Order is meaningful and user-controllable -> render as a drag-to-reorder list.
+  const ordered = Annotation.FormOrderedAnnotation.getFromAst(type).pipe(Option.getOrElse(() => false));
+
+  // Synthetic identity map (see `DND_ID`). The counter only advances when the
+  // array grows; reconciliation here covers the initial mount and any external
+  // length change, while the handlers below keep ids aligned on mutation.
+  const idsRef = useRef<string[]>([]);
+  const counterRef = useRef(0);
+  const nextId = useCallback(() => `${DND_ID}-${counterRef.current++}`, []);
+
+  const getDefaultObjectValue = (typeNode: SchemaAST.AST): any => {
+    const baseNode = SchemaEx.findNode(typeNode, SchemaEx.isDiscriminatedUnion);
+    const typeLiteral = baseNode
+      ? SchemaEx.getDiscriminatedType(baseNode, {})
+      : SchemaEx.findNode(typeNode, SchemaAST.isTypeLiteral);
+    if (!typeLiteral) {
+      return {};
+    }
+
+    return Object.fromEntries(
+      getFormProperties(typeLiteral).map((prop) => {
+        const defaultValue = SchemaAST.getDefaultAnnotation(prop.type).pipe((annotation) =>
+          Option.getOrUndefined(annotation),
+        );
+        return [prop.name, defaultValue];
+      }),
+    );
+  };
+
+  const handleAdd = useCallback(() => {
+    const defaultValue =
+      elementType && SchemaEx.isNestedType(elementType)
+        ? getDefaultObjectValue(elementType)
+        : getDefaultValue(elementType);
+    idsRef.current.push(nextId());
+    // `values` is `undefined` on first render for arrays whose parent path
+    // hasn't been materialised in the form values yet (e.g. `package.repos`
+    // when the form starts with no `package`). `useFormValues`'s default-
+    // value effect would eventually backfill it to `[]`, but until then the
+    // old `values && ...` guard silently swallowed the click. Treat a
+    // missing array as empty so Add always produces `[defaultValue]`.
+    onValueChange(type, [...(values ?? []), defaultValue]);
+  }, [onValueChange, type, elementType, values, nextId]);
+
+  const handleDelete = useCallback(
+    (idx: number) => {
+      idsRef.current.splice(idx, 1);
+      onValueChange(
+        type,
+        values?.filter((_, i) => i !== idx),
+      );
+    },
+    [onValueChange, type, values],
+  );
+
+  const handleMove = useCallback(
+    (fromIndex: number, toIndex: number) => {
+      const next = [...(values ?? [])];
+      arrayMove(next, fromIndex, toIndex);
+      arrayMove(idsRef.current, fromIndex, toIndex);
+      onValueChange(type, next);
+    },
+    [onValueChange, type, values],
+  );
+
+  if (!elementType || ((readonly || layout === 'static') && values && values.length < 1)) {
+    return null;
+  }
+
+  const renderItemAsObject = elementType && SchemaEx.isNestedType(elementType) && !Ref.isRefType(elementType);
+
+  // Object items: a recursively-rendered FormField (multiple sub-rows for the
+  // object's fields). Scalar items (refs, primitives): a single inline FormField.
+  const renderField = (index: number, isLast: boolean): ReactNode => (
+    <FormField
+      {...props}
+      autoFocus={isLast}
+      type={elementType}
+      // Suppress the per-item header for object items only — the recursive
+      // form already renders labels for each sub-field. Scalar items
+      // (refs, primitives) keep the parent name so inline-layout children
+      // (e.g. RefField) have a real label to use as a fallback placeholder.
+      {...(renderItemAsObject && { name: null })}
+      path={[...(path ?? []), index]}
+      readonly={readonly || layout === 'static'}
+      layout={renderItemAsObject ? (layout === 'static' ? 'static' : undefined) : 'inline'}
+    />
+  );
+
+  const header = (layout !== 'static' || (values && values.length > 0)) && (
+    <FieldHeader
+      label={label}
+      path={SchemaEx.createJsonPath(path ?? [])}
+      readonly={readonly}
+      add={layout !== 'static' ? { label: t('add-item.button'), onClick: handleAdd } : undefined}
+    />
+  );
+
+  //
+  // Ordered (drag-to-reorder) list.
+  //
+
+  if (ordered && !readonly && layout !== 'static') {
+    // Reconcile synthetic ids with the current values (initial mount / external change).
+    const ids = idsRef.current;
+    const count = values?.length ?? 0;
+    while (ids.length < count) {
+      ids.push(nextId());
+    }
+    if (ids.length > count) {
+      ids.length = count;
+    }
+
+    const items: OrderedItem[] = (values ?? []).map((value, index) => ({ value, index, [DND_ID]: ids[index] }));
+
+    return (
+      <>
+        {header}
+        <OrderedList.Root<OrderedItem> items={items} isItem={isOrderedItem} getId={getOrderedId} onMove={handleMove}>
+          {({ items }) => (
+            <OrderedList.Content>
+              {items.map((item) => (
+                <OrderedList.Item<OrderedItem>
+                  key={getOrderedId(item)}
+                  id={getOrderedId(item)}
+                  item={item}
+                  classNames='grid grid-cols-[min-content_1fr_min-content] items-start gap-1 p-0 pb-1'
+                >
+                  <OrderedList.DragHandle />
+                  {renderField(item.index, item.index === items.length - 1)}
+                  <CompactIconButton
+                    icon='ph--x--regular'
+                    label={t('remove-item.button')}
+                    onClick={() => handleDelete(item.index)}
+                  />
+                </OrderedList.Item>
+              ))}
+            </OrderedList.Content>
+          )}
+        </OrderedList.Root>
+      </>
+    );
+  }
+
+  //
+  // Static list.
+  //
+
+  return (
+    <>
+      {header}
+      <div className='flex flex-col'>
+        {values?.map((_, index) => {
+          const isLast = index === values.length - 1;
+          return (
+            <div key={index} className='grid grid-cols-[1fr_min-content] items-center mb-1 last:mb-form-gap'>
+              {renderField(index, isLast)}
+              {!readonly && layout !== 'static' && (
+                <CompactIconButton
+                  icon='ph--x--regular'
+                  label={t('remove-item.button')}
+                  onClick={() => handleDelete(index)}
+                />
+              )}
+            </div>
+          );
+        })}
+      </div>
+    </>
+  );
+};
+
+ArrayField.displayName = 'Form.ArrayField';
+
+/**
+ * Returns the default empty value for a given AST.
+ * Used for initializing new array values etc.
+ */
+// TODO(wittjosiah): Factor out?
+export const getDefaultValue = (ast?: SchemaAST.AST): any => {
+  switch (ast?._tag) {
+    case 'StringKeyword': {
+      return '';
+    }
+    case 'NumberKeyword': {
+      return 0;
+    }
+    case 'BooleanKeyword': {
+      return false;
+    }
+    case 'Suspend': {
+      return getDefaultValue(ast.f());
+    }
+    case 'Refinement': {
+      // Use minimum from JSON schema annotation (e.g. Schema.between(1, 31)) as the default
+      // so new array items start within the valid range.
+      const jsonSchema = Option.getOrUndefined(SchemaAST.getJSONSchemaAnnotation(ast));
+      if (jsonSchema != null && 'minimum' in jsonSchema && typeof jsonSchema.minimum === 'number') {
+        return jsonSchema.minimum;
+      }
+      return getDefaultValue(ast.from);
+    }
+    default: {
+      if (ast && SchemaEx.isNestedType(ast)) {
+        return {};
+      } else {
+        throw new Error(`Unsupported type: ${ast?._tag}`);
+      }
+    }
+  }
+};

package/src/components/Form/FormField/fields/ArrayField/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './ArrayField';

package/src/components/Form/FormField/fields/BooleanField/BooleanField.stories.tsx

@@ -0,0 +1,52 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Schema from 'effect/Schema';
+import React, { useState } from 'react';
+
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '#translations';
+
+import { TestLayout } from '../../../../../testing';
+import { Form } from '../../../Form';
+
+const schema = Schema.Struct({
+  active: Schema.Boolean.annotations({ title: 'Active' }),
+}).pipe(Schema.mutable);
+
+type Values = Schema.Schema.Type<typeof schema>;
+
+const DefaultStory = () => {
+  const [values, setValues] = useState<Values>({ active: true });
+  return (
+    <TestLayout json={values}>
+      <Form.Root
+        schema={schema}
+        values={values}
+        onValuesChanged={(values) => setValues((prev) => ({ ...prev, ...values }))}
+      >
+        <Form.Viewport>
+          <Form.Content>
+            <Form.FieldSet />
+          </Form.Content>
+        </Form.Viewport>
+      </Form.Root>
+    </TestLayout>
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-form/FormField/BooleanField',
+  render: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
+  parameters: { layout: 'fullscreen', translations },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

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

@@ -6,9 +6,11 @@ import React, { useCallback } from 'react';
 
 import { Input, type SwitchProps } from '@dxos/react-ui';
 
-import { type FormFieldComponentProps, FormFieldWrapper } from '../FormFieldComponent';
+import { type FormFieldRendererProps } from '#types';
 
-export const BooleanField = ({ type, readonly, onValueChange, ...props }: FormFieldComponentProps<boolean>) => {
+import { FormFieldWrapper } from '../../FormFieldWrapper';
+
+export const BooleanField = ({ type, readonly, onValueChange, ...props }: FormFieldRendererProps<boolean>) => {
   const handleChange = useCallback<NonNullable<SwitchProps['onCheckedChange']>>(
     (value) => onValueChange?.(type, value),
     [type, onValueChange],
@@ -16,7 +18,12 @@ export const BooleanField = ({ type, readonly, onValueChange, ...props }: FormFi
 
   return (
     <FormFieldWrapper<boolean> readonly={readonly} {...props}>
-      {({ value }) => <Input.Switch disabled={!!readonly} checked={value} onCheckedChange={handleChange} />}
+      {({ value }) => (
+        // TODO(burdon) Push down to react-ui components (e.g., Input.Root).
+        <div className='flex items-center px-0.5 h-8'>
+          <Input.Switch disabled={!!readonly} checked={value} onCheckedChange={handleChange} />
+        </div>
+      )}
     </FormFieldWrapper>
   );
 };

package/src/components/Form/FormField/fields/BooleanField/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './BooleanField';