@dxos/react-ui-form 0.8.4-main.2e9d522 → 0.8.4-main.3c1ae3b

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 Component = ({
+  type,
+  placeholder,
+  readonly,
+  onBlur,
+  onValueChange,
+  ...props
+}: FormFieldComponentProps<string>) => {
+  const handleChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => onValueChange(type, event.target.value),
+    [type, onValueChange],
+  );
+
+  return (
+    <div className='plb-cardSpacingBlock pli-cardSpacingInline'>
+      <FormFieldWrapper<string> {...props}>
+        {({ value = '' }) => (
+          <Input.TextInput
+            disabled={!!readonly}
+            placeholder={placeholder}
+            noAutoFill
+            value={value}
+            onChange={handleChange}
+            onBlur={onBlur}
+          />
+        )}
+      </FormFieldWrapper>
+    </div>
+  );
+};
+
+const meta: Meta<typeof Component> = {
+  title: 'ui/react-ui-form/FormFieldComponent',
+  component: Component,
+  decorators: [withTheme, withLayout({ container: '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,173 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+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 Format } from '@dxos/echo/internal';
+import { Icon, Input, Tooltip } from '@dxos/react-ui';
+import { labelSpacing } from '@dxos/react-ui-stack';
+import { errorText, mx } from '@dxos/react-ui-theme';
+
+import { type FormFieldStatus } from '../../hooks';
+
+/**
+ * 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> = {
+  type: SchemaAST.AST;
+  format?: Format.TypeFormat;
+  readonly?: boolean;
+  label: string;
+  placeholder?: string;
+  autoFocus?: boolean;
+  layout?: Presentation;
+} & FormFieldStateProps<T>;
+
+/**
+ * Form field component.
+ */
+export type FormFieldComponent = FC<FormFieldComponentProps>;
+
+export type FormFieldMap = Record<string, FormFieldComponent>;
+
+export type FormFieldProvider = (props: {
+  prop: string; // TODO(burdon): Path?
+  schema: Schema.Schema<any>;
+  fieldProps: FormFieldComponentProps;
+}) => ReactElement | undefined;
+
+//
+// FormFieldLabel
+//
+
+export type FormFieldLabelProps = {
+  asChild?: boolean;
+  error?: string;
+} & Pick<FormFieldComponentProps, 'label' | 'readonly'>;
+
+export const FormFieldLabel = ({ label, error, readonly, asChild }: FormFieldLabelProps) => {
+  const Label = readonly || asChild ? 'span' : Input.Label;
+  const labelProps = readonly || asChild ? { className: 'text-description text-sm' } : { classNames: '!mlb-0 text-sm' };
+
+  return (
+    <div role='none' className={mx('flex justify-between items-center', labelSpacing)}>
+      <Label {...labelProps}>{label}</Label>
+      {error && (
+        <Tooltip.Trigger asChild content={error} side='bottom'>
+          <Icon icon='ph--warning--regular' size={4} classNames={errorText} />
+        </Tooltip.Trigger>
+      )}
+    </div>
+  );
+};
+
+FormFieldLabel.displayName = 'Form.FieldLabel';
+
+//
+// FormFieldWrapper
+//
+
+export type FormFieldWrapperProps<T = any> = Pick<
+  FormFieldComponentProps,
+  'readonly' | 'label' | 'layout' | 'getStatus' | 'getValue'
+> & {
+  children?: (props: { value: T }) => ReactNode;
+};
+
+export const FormFieldWrapper = <T,>(props: FormFieldWrapperProps<T>) => {
+  const { children, readonly, layout, label, getStatus, getValue } = props;
+  const { status, error } = getStatus();
+
+  const value = getValue();
+  if (layout === 'static' && value == null) {
+    return null;
+  }
+
+  const str = String(value ?? '');
+
+  return (
+    <Input.Root validationValence={status}>
+      {layout !== 'inline' && <FormFieldLabel error={error} readonly={readonly} label={label} />}
+      {layout === 'static' ? <p>{str}</p> : children ? children({ value }) : null}
+      {layout === 'full' && (
+        <Input.DescriptionAndValidation>
+          <Input.Validation>{error}</Input.Validation>
+        </Input.DescriptionAndValidation>
+      )}
+    </Input.Root>
+  );
+};
+
+//
+// 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-roseFill font-mono text-sm'>
+          <span className='bg-roseFill text-surfaceText pli-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/FormFieldSet.tsx

@@ -0,0 +1,124 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { forwardRef, useMemo } from 'react';
+
+import { type AnyProperties } from '@dxos/echo/internal';
+import { type SchemaProperty } from '@dxos/effect';
+import { type ThemedClassName } from '@dxos/react-ui';
+import { mx } from '@dxos/react-ui-theme';
+import { isTruthy } from '@dxos/util';
+
+import { type FormHandlerProps } from '../../hooks';
+import { getFormProperties } from '../../util';
+
+import { useFormValues } from './Form';
+import { FormField, type FormFieldProps } from './FormField';
+import { FormFieldErrorBoundary, FormFieldLabel } from './FormFieldComponent';
+
+export type FormFieldSetProps<T extends AnyProperties> = ThemedClassName<
+  {
+    label?: string;
+    exclude?: (props: SchemaProperty[]) => SchemaProperty[];
+    sort?: string[];
+  } & Pick<FormHandlerProps<T>, 'schema'> &
+    Pick<
+      FormFieldProps,
+      | 'path'
+      | 'autoFocus'
+      | 'readonly'
+      | 'layout'
+      | 'projection'
+      | 'fieldMap'
+      | 'fieldProvider'
+      | 'createSchema'
+      | 'createOptionLabel'
+      | 'createOptionIcon'
+      | 'createInitialValuePath'
+      | 'onCreate'
+      | 'onQueryRefOptions'
+    >
+>;
+
+export const FormFieldSet = forwardRef<HTMLDivElement, FormFieldSetProps<any>>(
+  ({ classNames, label, schema, readonly, path, exclude, sort, projection, layout, ...props }, forwardRef) => {
+    const values = useFormValues(FormFieldSet.displayName!, path);
+
+    // TODO(burdon): Updates on every value change.
+    //  Remove values dep if can remove from getSchemaProperties.
+    const properties = useMemo(() => {
+      if (!schema) {
+        return [];
+      }
+
+      // TODO(wittjosiah): Reconcile FormInputAnnotation with projection hidden properties & exclude function.
+      const props = getFormProperties(schema.ast);
+
+      // Use projection-based field management when view and projection are available.
+      if (projection) {
+        const fieldProjections = projection.getFieldProjections();
+        const hiddenProperties = new Set(projection.getHiddenProperties());
+
+        // Filter properties to only include visible ones and order by projection.
+        const visibleProps = props.filter((prop) => !hiddenProperties.has(prop.name.toString()));
+        const orderedProps: SchemaProperty[] = [];
+
+        // Add properties in projection field order.
+        for (const fieldProjection of fieldProjections) {
+          const fieldPath = String(fieldProjection.field.path);
+          const prop = visibleProps.find((p) => p.name === fieldPath);
+          if (prop) {
+            orderedProps.push(prop);
+          }
+        }
+
+        // Add any remaining properties not in projection.
+        const projectionPaths = new Set(fieldProjections.map((projection) => String(projection.field.path)));
+        const remainingProps = visibleProps.filter((prop) => !projectionPaths.has(prop.name.toString()));
+        orderedProps.push(...remainingProps);
+        return orderedProps;
+      }
+
+      // Fallback to legacy filter/sort behavior.
+      const filtered = exclude ? exclude(props) : props;
+      return sort
+        ? filtered.sort(({ name: a }, { name: b }) => sort.indexOf(a.toString()) - sort.indexOf(b.toString()))
+        : filtered;
+    }, [schema, values, exclude, sort, projection?.fields]);
+
+    if ((readonly || layout === 'static') && values == null) {
+      return null;
+    }
+
+    return (
+      <div
+        role='form'
+        className={mx('is-full', layout === 'inline' && 'flex flex-col gap-2', classNames)}
+        ref={forwardRef}
+      >
+        {layout !== 'inline' && label && <FormFieldLabel label={label} asChild />}
+        {properties
+          .map((property) => {
+            const name = property.name.toString();
+            return (
+              <FormFieldErrorBoundary key={name} path={[...(path ?? []), name]}>
+                <FormField
+                  type={property.type}
+                  name={name}
+                  path={[...(path ?? []), name]}
+                  readonly={readonly}
+                  layout={layout}
+                  projection={projection}
+                  {...props}
+                />
+              </FormFieldErrorBoundary>
+            );
+          })
+          .filter(isTruthy)}
+      </div>
+    );
+  },
+);
+
+FormFieldSet.displayName = 'Form.Fields';

package/src/components/Form/README.md

@@ -0,0 +1,3 @@
+# Form
+
+- [ ] Layout options (e.g., label on the side.)

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

@@ -0,0 +1,154 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Option from 'effect/Option';
+import * as SchemaAST from 'effect/SchemaAST';
+import React, { Fragment, useCallback } from 'react';
+
+import { findNode, getArrayElementType, getDiscriminatedType, isDiscriminatedUnion, isNestedType } from '@dxos/effect';
+import { invariant } from '@dxos/invariant';
+import { IconButton, useTranslation } from '@dxos/react-ui';
+
+import { translationKey } from '../../../translations';
+import { getFormProperties } from '../../../util';
+import { useFormValues } from '../Form';
+import { FormField, type FormFieldProps } from '../FormField';
+import { FormFieldLabel, type FormFieldStateProps } from '../FormFieldComponent';
+
+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 = getArrayElementType(type);
+  const { onValueChange } = inputProps;
+
+  // TODO(wittjosiah): The fallback to an empty array stops the form from crashing but isn't immediately live.
+  //  It doesn't become live until another field is touched, but that's better than the whole form crashing.
+  const values = useFormValues(ArrayField.displayName, path) ?? [];
+  invariant(Array.isArray(values), `Expected array at: ${path?.join('.')}`);
+
+  const getDefaultObjectValue = (typeNode: SchemaAST.AST): any => {
+    const baseNode = findNode(typeNode, isDiscriminatedUnion);
+    const typeLiteral = baseNode ? getDiscriminatedType(baseNode, {}) : 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 =
+      isNestedType(type) && elementType ? getDefaultObjectValue(elementType) : getDefaultValue(elementType);
+    onValueChange(type, [...values, defaultValue]);
+  }, [onValueChange, type, elementType, values]);
+
+  const handleDelete = useCallback(
+    (idx: number) => {
+      onValueChange(
+        type,
+        values.filter((_, i) => i !== idx),
+      );
+    },
+    [onValueChange, type, values],
+  );
+
+  if (!elementType || ((readonly || layout === 'static') && values.length < 1)) {
+    return null;
+  }
+
+  return (
+    <>
+      {(layout !== 'static' || values.length > 0) && <FormFieldLabel readonly={readonly} label={label} asChild />}
+
+      <div role='none' className='flex flex-col gap-2'>
+        {values.map((_, index) => {
+          return (
+            <div role='none' key={index} className='grid grid-cols-[1fr_min-content] gap-2 last:mb-3'>
+              <FormField
+                autoFocus={index === values.length - 1}
+                type={elementType}
+                path={[...(path ?? []), index]}
+                readonly={readonly || layout === 'static'}
+                layout='inline'
+                {...props}
+              />
+
+              {!readonly && layout !== 'static' && (
+                <div role='none' className='flex flex-col bs-full justify-end'>
+                  {/* NOTE: Aligns with center of last field if multi-field object. */}
+                  <div role='none' className='flex items-center bs-[var(--line-height)]'>
+                    <IconButton
+                      icon='ph--x--regular'
+                      iconOnly
+                      label={t('button remove')}
+                      onClick={() => handleDelete(index)}
+                      classNames='self-center'
+                    />
+                  </div>
+                </div>
+              )}
+            </div>
+          );
+        })}
+      </div>
+
+      {/* TODO(burdon): Get label from schema. */}
+      {!readonly && layout !== 'static' && (
+        <IconButton
+          classNames='flex is-full _mlb-cardSpacingBlock'
+          icon='ph--plus--regular'
+          label={t('add field')}
+          onClick={handleAdd}
+        />
+      )}
+    </>
+  );
+};
+
+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;
+    }
+    default: {
+      if (ast && isNestedType(ast)) {
+        return {};
+      } else {
+        throw new Error(`Unsupported type: ${ast?._tag}`);
+      }
+    }
+  }
+};

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

@@ -0,0 +1,22 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React, { useCallback } from 'react';
+
+import { Input, type SwitchProps } from '@dxos/react-ui';
+
+import { type FormFieldComponentProps, FormFieldWrapper } from '../FormFieldComponent';
+
+export const BooleanField = ({ type, readonly, onValueChange, ...props }: FormFieldComponentProps<boolean>) => {
+  const handleChange = useCallback<NonNullable<SwitchProps['onCheckedChange']>>(
+    (value) => onValueChange?.(type, value),
+    [type, onValueChange],
+  );
+
+  return (
+    <FormFieldWrapper<boolean> readonly={readonly} {...props}>
+      {({ value }) => <Input.Switch disabled={!!readonly} checked={value} onCheckedChange={handleChange} />}
+    </FormFieldWrapper>
+  );
+};

package/src/components/Form/fields/GeoPointField.tsx

@@ -0,0 +1,120 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React, { type ChangeEvent, useCallback, useEffect, useMemo, useState } from 'react';
+
+import { GeoLocation, type GeoPoint } from '@dxos/echo/internal';
+import { Input, useTranslation } from '@dxos/react-ui';
+import { safeParseFloat } from '@dxos/util';
+
+import { translationKey } from '../../../translations';
+import { type FormFieldComponentProps, FormFieldLabel } from '../FormFieldComponent';
+
+export const GeoPointField = ({
+  type,
+  label,
+  readonly,
+  layout,
+  getStatus,
+  getValue,
+  onValueChange,
+  onBlur,
+}: FormFieldComponentProps<GeoPoint>) => {
+  const { t } = useTranslation(translationKey);
+  const { status, error } = getStatus();
+  const geoPoint = useMemo<GeoPoint>(() => getValue() ?? [0, 0], [getValue]);
+  const value = useMemo(() => GeoLocation.fromGeoPoint(geoPoint), [geoPoint]);
+
+  const [longitudeText, setLongitudeText] = useState(value.longitude?.toString());
+  const [latitudeText, setLatitudeText] = useState(value.latitude?.toString());
+  useEffect(() => {
+    const location = GeoLocation.fromGeoPoint(geoPoint);
+    setLongitudeText(location.longitude?.toString());
+    setLatitudeText(location.latitude?.toString());
+  }, [geoPoint]);
+
+  const handleChange = useCallback(
+    (coordinateType: keyof Pick<GeoLocation, 'longitude' | 'latitude'>, setText: (text: string) => void) =>
+      (event: ChangeEvent<HTMLInputElement>) => {
+        const inputText = event.target.value;
+        setText(inputText);
+        if (inputText !== '' && inputText !== '-') {
+          const coord = safeParseFloat(inputText);
+          if (coord !== undefined && !isNaN(coord)) {
+            const currentLocation = GeoLocation.fromGeoPoint(getValue() ?? [0, 0]);
+            const newLocation = { ...currentLocation, [coordinateType]: coord };
+            const newValue = GeoLocation.toGeoPoint(newLocation);
+            onValueChange(type, newValue);
+          }
+        }
+      },
+    [type, getValue, onValueChange],
+  );
+
+  if ((readonly || layout === 'static') && !value?.latitude && !value?.longitude) {
+    return null;
+  }
+
+  return (
+    <Input.Root validationValence={status}>
+      {layout !== 'inline' && <FormFieldLabel error={error} readonly={readonly} label={label} asChild />}
+      {layout === 'static' ? (
+        <LatLng {...value} />
+      ) : (
+        <div role='none' className='grid grid-cols-2 gap-2'>
+          <div>
+            <Input.Root>
+              {layout !== 'inline' && <Input.Label>{t('latitude label')}</Input.Label>}
+              <Input.TextInput
+                type='number'
+                step='0.00001'
+                min='-90'
+                max='90'
+                disabled={!!readonly}
+                placeholder={t('latitude placeholder')}
+                value={latitudeText ?? ''}
+                onChange={handleChange('latitude', setLatitudeText)}
+                onBlur={onBlur}
+              />
+            </Input.Root>
+          </div>
+          <div>
+            <Input.Root>
+              {layout !== 'inline' && <Input.Label>{t('longitude label')}</Input.Label>}
+              <Input.TextInput
+                type='number'
+                step='0.00001'
+                min='-180'
+                max='180'
+                disabled={!!readonly}
+                placeholder={t('longitude placeholder')}
+                value={longitudeText ?? ''}
+                onChange={handleChange('longitude', setLongitudeText)}
+                onBlur={onBlur}
+              />
+            </Input.Root>
+          </div>
+        </div>
+      )}
+    </Input.Root>
+  );
+};
+
+const LatLng = ({ latitude = 0, longitude = 0 }: GeoLocation) => {
+  const latHem = latitude >= 0 ? 'N' : 'S';
+  const lngHem = longitude >= 0 ? 'E' : 'W';
+
+  return (
+    <span className='inline-flex items-center gap-1'>
+      <span>
+        <span>{Math.abs(latitude).toFixed(5)}</span>
+        <span className='text-subdued'>°{latHem}</span>
+      </span>
+      <span>
+        <span>{Math.abs(longitude).toFixed(5)}</span>
+        <span className='text-subdued'>°{lngHem}</span>
+      </span>
+    </span>
+  );
+};