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

package/src/components/Form/FormField/FormFieldHeader.tsx

@@ -0,0 +1,68 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { type ReactNode } from 'react';
+
+import { CompactIconButton } from './FormField';
+import { FormFieldLabel } from './FormRow';
+
+export type FormFieldHeaderProps = {
+  label: string;
+  /** JSON path forwarded to the label as field metadata. */
+  path?: string;
+  required?: boolean;
+  readonly?: boolean;
+  classNames?: string;
+  /** Trailing inline add affordance; omit to hide it. */
+  add?: { icon?: string; label: string; disabled?: boolean; onClick: () => void };
+  /** Extra trailing controls placed after the add affordance (e.g. a collapse toggle). */
+  actions?: ReactNode;
+  /** Header row click (e.g. toggle collapse). The add affordance stops propagation so it doesn't trigger this. */
+  onClick?: () => void;
+};
+
+/**
+ * Header row for a labelled group or list: a label with optional trailing controls (an inline add
+ * affordance and/or arbitrary `actions`). Shared by array/list fields ({@link ArrayField}, the view
+ * editor) and {@link FormFieldSetContainer}'s collapse header, so all group/list headers render identically.
+ */
+export const FormFieldHeader = ({
+  label,
+  path,
+  required,
+  readonly,
+  classNames,
+  add,
+  actions,
+  onClick,
+}: FormFieldHeaderProps) => (
+  <FormFieldLabel
+    standalone
+    classNames={classNames}
+    label={label}
+    required={required}
+    readonly={readonly}
+    path={path}
+    button={
+      (!readonly && add) || actions ? (
+        <>
+          {!readonly && add && (
+            <CompactIconButton
+              disabled={add.disabled}
+              icon={add.icon ?? 'ph--plus--regular'}
+              label={add.label}
+              onClick={(event) => {
+                // Don't let the add click bubble to the header's onClick (e.g. collapse toggle).
+                event.stopPropagation();
+                add.onClick();
+              }}
+            />
+          )}
+          {actions}
+        </>
+      ) : undefined
+    }
+    onClick={onClick}
+  />
+);

package/src/components/Form/FormField/FormRow.stories.tsx

@@ -0,0 +1,97 @@
+//
+// 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 FormFieldRendererProps } from '#types';
+
+import { Form } from '../Form';
+import { FormRow } from './FormRow';
+
+const DefaultStory = ({
+  type,
+  placeholder,
+  readonly,
+  onBlur,
+  onValueChange,
+  ...props
+}: FormFieldRendererProps<string>) => {
+  const handleChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => onValueChange(type, event.target.value),
+    [type, onValueChange],
+  );
+
+  return (
+    <Form.Root>
+      <Form.Viewport>
+        <Form.Content>
+          <FormRow<string> {...props}>
+            {({ value = '' }) => (
+              <Input.TextInput
+                disabled={!!readonly}
+                placeholder={placeholder}
+                noAutoFill
+                value={value}
+                onChange={handleChange}
+                onBlur={onBlur}
+              />
+            )}
+          </FormRow>
+        </Form.Content>
+      </Form.Viewport>
+    </Form.Root>
+  );
+};
+
+const meta: Meta<typeof DefaultStory> = {
+  title: 'ui/react-ui-form/FormRow',
+  component: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  parameters: {
+    layout: 'fullscreen',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const props: Story['args'] = {
+  label: 'Label',
+  required: true,
+  getStatus: () => ({ status: 'error', error: 'Required field' }),
+  getValue: () => 'DXOS',
+};
+
+export const Default: Story = {
+  args: {
+    ...props,
+    presentation: 'full',
+  },
+};
+
+export const Compact: Story = {
+  args: {
+    ...props,
+    presentation: 'compact',
+  },
+};
+
+export const Inline: Story = {
+  args: {
+    ...props,
+    presentation: 'inline',
+  },
+};
+
+export const Static: Story = {
+  args: {
+    ...props,
+    presentation: 'static',
+  },
+};

package/src/components/Form/FormField/FormRow.tsx

@@ -0,0 +1,298 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { format as formatDate } from 'date-fns';
+import React, { Component, type PropsWithChildren, type ReactNode, type Ref } from 'react';
+
+import { Format } from '@dxos/echo';
+import { Icon, Input, type ThemedClassName, Tooltip } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+
+import { type FormFieldRendererProps } from '#types';
+
+import { useFormContext } from '../../../hooks';
+import { type FormVariant, formTheme } from '../Form.theme';
+import { type FormFieldPresentation, presentationFor } from './presentation';
+
+//
+// FormFieldLabel
+//
+
+export type FormFieldLabelProps = ThemedClassName<
+  {
+    /** 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;
+    /** Class applied to the inner label text node, overriding the default size/color (e.g. `text-lg`). */
+    labelClassName?: string;
+    /** Form variant; selects the label's chrome (e.g. `settings` enlarges the text and places it in the field grid). */
+    variant?: FormVariant;
+    error?: string;
+    /**
+     * JSON path of the field this label describes (e.g. `runtime.client.storage.persistent`).
+     * Field metadata; accepted by callers but not currently rendered.
+     */
+    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<FormFieldRendererProps, 'label' | 'readonly' | 'required'>
+>;
+
+export const FormFieldLabel = ({
+  classNames,
+  labelClassName,
+  variant = 'default',
+  label,
+  error,
+  readonly,
+  required,
+  standalone,
+  button,
+  onClick,
+}: FormFieldLabelProps) => {
+  const styles = formTheme.styles({ variant });
+  // Render the required asterisk via a `::after` pseudo-element rather than a DOM node: it keeps the
+  // label's `textContent` exactly `label`, so fields stay locatable by their exact label text
+  // (`getByLabelText('Name')`), which the DOM-text-based query would otherwise miss as `Name *`.
+  // The `fieldLabelText` slot is applied last so a variant/caller size/color (e.g. `text-lg`) wins over
+  const labelClassNames = mx(
+    'text-sm text-description',
+    required && "after:content-['*'] after:ms-0.5 after:text-warning-text",
+    styles.fieldLabelText({ class: labelClassName }),
+  );
+
+  // `Input.Label` is a themed primitive that reads `classNames` (and ignores `className`), whereas the
+  // plain `span` used for read-only/standalone labels reads `className`.
+  const labelNode =
+    readonly || standalone ? (
+      <span className={labelClassNames}>{label}</span>
+    ) : (
+      <Input.Label classNames={labelClassNames}>{label}</Input.Label>
+    );
+
+  return (
+    <div className={styles.fieldLabel({ class: mx(onClick && 'cursor-pointer', classNames) })} onClick={onClick}>
+      {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';
+
+//
+// FormRow
+//
+
+/**
+ * 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);
+  }
+};
+
+const FORM_ROW_NAME = 'Form.Row';
+
+export type FormRowProps<T = any> = ThemedClassName<
+  Pick<FormFieldRendererProps<T>, 'readonly' | 'label' | 'description' | 'presentation' | 'required'> &
+    Partial<Pick<FormFieldRendererProps<T>, 'getStatus' | 'getValue' | 'jsonPath' | 'format'>> & {
+      /**
+       * Ref to the row's outer element. Enables measurement/positioning (e.g. a future virtualized
+       * field set) without forwarding through the generic component.
+       */
+      rootRef?: Ref<HTMLDivElement>;
+      /**
+       * Render the label as a standalone `<span>` (group/multi-input fields with no single associated control).
+       */
+      standalone?: boolean;
+      /**
+       * Override the read-only/`static` rendering of the value. Fields whose value is not plain text
+       * (refs, selects, markdown) supply this; the default formats scalars/dates via `formatStaticValue`.
+       * Return `null` to render nothing (e.g. an empty/unresolved value).
+       */
+      renderStatic?: (value: T | undefined) => ReactNode;
+      /**
+       * Validation/error content rendered in the validation slot. Supplied directly in action mode; in
+       * field mode it is derived from `getStatus`.
+       */
+      validation?: ReactNode;
+      /**
+       * The control. A render-prop binds to the form value (field mode: `Input.Root` validation, static
+       * rendering, value via `getValue`). Plain nodes render an arbitrary control with no value wiring
+       * (action mode, e.g. a button) — the labeled-card escape hatch for an arbitrary control.
+       *
+       * `value` is `T | undefined` because `getValue()` returns no value when the field is unset (optional
+       * schema properties, freshly-added array items); renderers default it (e.g. `{ value = '' }`).
+       */
+      children?: ReactNode | ((props: { value: T | undefined; presentation: FormFieldPresentation }) => ReactNode);
+    }
+>;
+
+/**
+ * A labeled card row — the single shell behind both schema fields and free-form "action" rows. Field
+ * renderers pass a render-prop `children` (field mode: bound to the form value, with validation and
+ * static rendering); consumers pass plain `children` for an arbitrary control (action mode), the
+ * affordance for an arbitrary labeled control (action rows, settings cards).
+ */
+export const FormRow = <T,>({
+  classNames,
+  children,
+  readonly,
+  presentation,
+  label,
+  description,
+  jsonPath,
+  format,
+  required,
+  standalone,
+  renderStatic,
+  validation,
+  getStatus,
+  getValue,
+  rootRef,
+}: FormRowProps<T>) => {
+  const { variant = 'default' } = useFormContext(FORM_ROW_NAME);
+  const styles = formTheme.styles({ variant });
+  const { showDescription } = formTheme.behavior[variant];
+  const resolved = presentationFor(presentation);
+
+  //
+  // Field mode: a render-prop control bound to the form value.
+  //
+  if (typeof children === 'function' && getStatus && getValue) {
+    const { status, error } = getStatus();
+    const value: T | undefined = getValue();
+    if (resolved.isStatic && value == null) {
+      return null;
+    }
+
+    const control = resolved.isStatic
+      ? (renderStatic?.(value) ?? <p className='truncate min-w-0'>{formatStaticValue(value, format)}</p>)
+      : children({ value, presentation: resolved });
+
+    return (
+      <Input.Root validationValence={status}>
+        <div className={styles.field({ class: classNames })} ref={rootRef}>
+          {resolved.showLabel && (
+            <FormFieldLabel
+              variant={variant}
+              error={error}
+              readonly={readonly}
+              required={required}
+              standalone={standalone}
+              label={label}
+              path={jsonPath}
+            />
+          )}
+          {showDescription && description && (
+            <Input.Description classNames={styles.fieldDescription()}>{description}</Input.Description>
+          )}
+          <div className={styles.fieldControl()}>{control}</div>
+          {resolved.showError && error && (
+            <div className={styles.fieldValidation()}>
+              <Input.DescriptionAndValidation>
+                <Input.Validation>{error}</Input.Validation>
+              </Input.DescriptionAndValidation>
+            </div>
+          )}
+        </div>
+      </Input.Root>
+    );
+  }
+
+  //
+  // Action mode: an arbitrary control with a standalone label; no value/`Input.Root` wiring.
+  //
+  return (
+    <div ref={rootRef} className={styles.field({ class: classNames })}>
+      {resolved.showLabel && label && (
+        <FormFieldLabel
+          variant={variant}
+          readonly={readonly}
+          required={required}
+          standalone
+          label={label}
+          path={jsonPath}
+        />
+      )}
+      {showDescription && description && <p className={styles.fieldDescription()}>{description}</p>}
+      <div className={styles.fieldControl()}>{typeof children === 'function' ? null : children}</div>
+      {validation && <div className={styles.fieldValidation()}>{validation}</div>}
+    </div>
+  );
+};
+
+FormRow.displayName = FORM_ROW_NAME;
+
+//
+// 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-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>
+      );
+    }
+
+    return this.props.children;
+  }
+
+  private resetError() {
+    this.setState({ error: undefined });
+  }
+}

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

@@ -0,0 +1,119 @@
+//
+// 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);
+
+const OrderedPipeline = Schema.Struct({
+  ...headerFields,
+  columns: columnsField.pipe(FormOrderedAnnotation.set(true)),
+}).pipe(Schema.mutable);
+
+const StringPipeline = Schema.Struct({
+  ...headerFields,
+  columns: Schema.Array(Schema.String).pipe(FormOrderedAnnotation.set(true)),
+}).pipe(Schema.mutable);
+
+type PipelineValues = { name?: string; description?: string; columns: readonly unknown[] };
+
+// Object-array columns (matches `Pipeline` / `OrderedPipeline`).
+const objectColumns: PipelineValues = {
+  name: 'Sales',
+  description: 'Lead qualification pipeline.',
+  columns: [{ name: 'Contacts' }, { name: 'Organizations' }, { name: 'Tasks' }, { name: 'Messages', value: 100 }],
+};
+
+// String-array columns (matches `StringPipeline`); feeding object columns here renders `[object Object]`.
+const stringColumns: PipelineValues = {
+  name: 'Sales',
+  description: 'Lead qualification pipeline.',
+  columns: ['Contacts', 'Organizations', 'Tasks', 'Messages'],
+};
+
+const DefaultStory = ({ schema, values: initial }: { schema: Schema.Schema<any>; values: PipelineValues }) => {
+  const [values, setValues] = useState<PipelineValues>(initial);
+
+  return (
+    <TestLayout json={values}>
+      <Form.Root
+        schema={schema}
+        values={values}
+        onValuesChanged={(next) => setValues((prev) => ({ ...prev, ...next }))}
+      >
+        <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 DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => <DefaultStory schema={Pipeline} values={objectColumns} />,
+};
+
+export const Ordered: Story = {
+  render: () => <DefaultStory schema={OrderedPipeline} values={objectColumns} />,
+};
+
+export const Simple: Story = {
+  render: () => <DefaultStory schema={StringPipeline} values={stringColumns} />,
+};