@dxos/react-ui-form 0.7.1-staging.599df14

package/src/components/ViewEditor/ViewEditor.tsx

@@ -0,0 +1,158 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React, { useCallback, useMemo, useState } from 'react';
+
+import { type SchemaResolver } from '@dxos/echo-db';
+import { AST, Format, type MutableSchema, S } from '@dxos/echo-schema';
+import { IconButton, type ThemedClassName, useTranslation } from '@dxos/react-ui';
+import { List } from '@dxos/react-ui-list';
+import { ghostHover, inputTextLabel, mx } from '@dxos/react-ui-theme';
+import { FieldSchema, type FieldType, type ViewType, ViewProjection, VIEW_FIELD_LIMIT } from '@dxos/schema';
+import { arrayMove } from '@dxos/util';
+
+import { translationKey } from '../../translations';
+import { FieldEditor } from '../FieldEditor';
+import { Form } from '../Form';
+
+const grid = 'grid grid-cols-[32px_1fr_32px] min-bs-[2.5rem]';
+
+const ViewMetaSchema = S.Struct({
+  name: S.String.annotations({
+    [AST.TitleAnnotationId]: 'View',
+  }),
+  type: Format.DXN.annotations({
+    [AST.TitleAnnotationId]: 'Typename',
+  }),
+}).pipe(S.mutable);
+
+type ViewMetaType = S.Schema.Type<typeof ViewMetaSchema>;
+
+export type ViewEditorProps = ThemedClassName<{
+  schema: MutableSchema;
+  view: ViewType;
+  registry?: SchemaResolver;
+  readonly?: boolean;
+  showHeading?: boolean;
+  onDelete: (fieldId: string) => void;
+}>;
+
+/**
+ * Schema-based object form.
+ */
+export const ViewEditor = ({
+  classNames,
+  schema,
+  view,
+  registry,
+  readonly,
+  showHeading = false,
+  onDelete,
+}: ViewEditorProps) => {
+  const { t } = useTranslation(translationKey);
+  const projection = useMemo(() => new ViewProjection(schema, view), [schema, view]);
+  const [field, setField] = useState<FieldType>();
+
+  // TODO(burdon): Should be reactive.
+  const viewValues = useMemo(() => {
+    return {
+      name: view.name,
+      // TODO(burdon): Need to warn user of possible consequences of editing.
+      // TODO(burdon): Settings should have domain name owned by user.
+      type: view.query.type,
+    };
+  }, [view]);
+
+  const handleViewUpdate = useCallback(
+    ({ name, type }: ViewMetaType) => {
+      requestAnimationFrame(() => {
+        view.name = name;
+        view.query.type = type;
+        schema.updateTypename(type);
+      });
+    },
+    [view, schema],
+  );
+
+  const handleSelect = useCallback((field: FieldType) => {
+    setField((f) => (f === field ? undefined : field));
+  }, []);
+
+  const handleAdd = useCallback(() => {
+    const field = projection.createFieldProjection();
+    setField(field);
+  }, [view]);
+
+  const handleMove = useCallback(
+    (fromIndex: number, toIndex: number) => {
+      arrayMove(view.fields, fromIndex, toIndex);
+    },
+    [view.fields],
+  );
+
+  const handleClose = useCallback(() => setField(undefined), []);
+
+  return (
+    <div role='none' className={mx('flex flex-col w-full divide-y divide-separator', classNames)}>
+      <Form<ViewMetaType> autoFocus autoSave schema={ViewMetaSchema} values={viewValues} onSubmit={handleViewUpdate} />
+
+      <div>
+        {/* TODO(burdon): Clean up common form ux. */}
+        <div role='none' className='p-2'>
+          <label className={mx(inputTextLabel)}>{t('fields label')}</label>
+        </div>
+
+        <List.Root<FieldType>
+          items={view.fields}
+          isItem={S.is(FieldSchema)}
+          getId={(field) => field.id}
+          onMove={handleMove}
+        >
+          {({ items: fields }) => (
+            <>
+              {showHeading && (
+                <div role='heading' className={grid}>
+                  <div />
+                  <div className='flex items-center text-sm'>{t('field path label')}</div>
+                </div>
+              )}
+
+              <div role='list' className='flex flex-col w-full'>
+                {fields?.map((field) => (
+                  <List.Item<FieldType> key={field.id} item={field} classNames={mx(grid, ghostHover, 'cursor-pointer')}>
+                    <List.ItemDragHandle />
+                    <List.ItemTitle onClick={() => handleSelect(field)}>{field.path}</List.ItemTitle>
+                    <List.ItemDeleteButton disabled={view.fields.length <= 1} onClick={() => onDelete(field.id)} />
+                  </List.Item>
+                ))}
+              </div>
+            </>
+          )}
+        </List.Root>
+      </div>
+
+      {field && (
+        <FieldEditor
+          key={field.id}
+          view={view}
+          projection={projection}
+          field={field}
+          registry={registry}
+          onClose={handleClose}
+        />
+      )}
+      {!readonly && !field && (
+        <div className='flex p-2 justify-center'>
+          <IconButton
+            icon='ph--plus--regular'
+            label={t('button add property')}
+            onClick={handleAdd}
+            // TODO(burdon): Show field limit in ux (not tooltip).
+            disabled={view.fields.length >= VIEW_FIELD_LIMIT}
+          />
+        </div>
+      )}
+    </div>
+  );
+};

package/src/components/ViewEditor/index.ts

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

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

@@ -0,0 +1,62 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import '@dxos-theme';
+
+import { type Meta, type StoryObj } from '@storybook/react';
+import React from 'react';
+
+import { create } from '@dxos/echo-schema';
+import { testData, testView, TestSchema, type TestType } from '@dxos/schema/testing';
+import { withTheme, withLayout } from '@dxos/storybook-utils';
+
+import { type DeprecatedFormProps, DeprecatedForm } from './Form';
+import translations from '../../translations';
+import { TestLayout, TestPanel } from '../testing';
+
+const DefaultStory = (props: DeprecatedFormProps) => (
+  <TestLayout json={{ props }}>
+    <TestPanel>
+      <DeprecatedForm {...props} />
+    </TestPanel>
+  </TestLayout>
+);
+
+const meta: Meta<typeof DefaultStory> = {
+  title: 'ui/react-ui-form/DeprecatedForm',
+  component: DeprecatedForm,
+  render: DefaultStory,
+  decorators: [withLayout({ fullscreen: true }), withTheme],
+  parameters: {
+    translations,
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<DeprecatedFormProps<TestType>>;
+
+export const Default: Story = {
+  args: {
+    object: create(testData),
+    view: create(testView),
+    schema: TestSchema,
+  },
+};
+
+export const Empty: Story = {
+  args: {
+    view: create(testView),
+    schema: TestSchema,
+  },
+};
+
+export const Readonly: Story = {
+  args: {
+    object: create(testData),
+    view: create(testView),
+    schema: TestSchema,
+    readonly: true,
+  },
+};

package/src/components/deprecated/Form.tsx

@@ -0,0 +1,119 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Option, pipe } from 'effect';
+import React, { useState } from 'react';
+
+import { AST, type S, findProperty } from '@dxos/effect';
+import { Input, type ThemedClassName, type TextInputProps as NativeTextInputProps } from '@dxos/react-ui';
+import { mx } from '@dxos/react-ui-theme';
+import { type ViewType, getFieldValue, setFieldValue } from '@dxos/schema';
+
+export type DeprecatedFormProps<T extends {} = {}> = ThemedClassName<{
+  view: ViewType;
+  object: T;
+  schema?: S.Schema<T>;
+  readonly?: boolean;
+}>;
+
+/**
+ * Schema-based object form.
+ */
+export const DeprecatedForm = <T extends {} = {}>({
+  classNames,
+  view,
+  object,
+  schema,
+  readonly,
+}: DeprecatedFormProps<T>) => {
+  return (
+    <div role='none' className={mx('flex flex-col w-full gap-2 p-2', classNames)}>
+      {view.fields.map((field) => {
+        const prop = schema && findProperty(schema, field.path);
+        const title = (prop && pipe(AST.getTitleAnnotation(prop), Option.getOrUndefined)) ?? '';
+        const description = (prop && pipe(AST.getDescriptionAnnotation(prop), Option.getOrUndefined)) ?? title;
+        // const format =
+        //   (prop && (getPatternAnnotation(prop) ?? (AST.isNumberKeyword(prop) && RealNumberFormat))) || undefined;
+
+        //
+        // Boolean
+        //
+
+        if (prop && AST.isBooleanKeyword(prop)) {
+          const value = object && getFieldValue(object, field);
+          const onChange = (checked: boolean) => {
+            setFieldValue(object, field, checked);
+          };
+
+          return (
+            <div key={field.path} className='flex flex-col w-full gap-1'>
+              <Input.Root>
+                <Input.Label classNames='px-1'>{title}</Input.Label>
+                <Input.Switch disabled={readonly} checked={!!value} onCheckedChange={(checked) => onChange(checked)} />
+              </Input.Root>
+            </div>
+          );
+        }
+
+        //
+        // Strings
+        // TODO(burdon): Other types:
+        //  - RichText editor
+        //  - Numbers (with formatting: commas, currency, etc.)
+        //  - Date (https://ark-ui.com/react/docs/components/date-picker)
+        //  - Enum (single/multi-select)
+        //
+
+        const value = object ? getFieldValue(object, field) : undefined;
+
+        return (
+          <div key={field.path} className='flex flex-col w-full gap-1'>
+            <Input.Root>
+              <Input.Label classNames='px-1'>{title}</Input.Label>
+              <TextInput
+                disabled={readonly}
+                placeholder={description}
+                // format={format}
+                value={value ? String(value) : ''}
+                onChange={(event) => setFieldValue(object, field, event.target.value)}
+              />
+            </Input.Root>
+          </div>
+        );
+      })}
+    </div>
+  );
+};
+
+type TextInputProps = {
+  // format?: PatternAnnotation;
+} & Omit<NativeTextInputProps, 'style'>;
+
+/**
+ * @deprecated
+ */
+// TODO(burdon): Remove.
+// TODO(burdon): Use schema validation directly.
+const TextInput = ({ onChange, ...props }: TextInputProps) => {
+  const [valid, _setValid] = useState(true);
+
+  const handleChange: NativeTextInputProps['onChange'] = (ev) => {
+    // const text = ev.target.value;
+    // if (!format?.filter || text.match(format.filter)) {
+    onChange?.(ev);
+    //   if (format?.valid) {
+    //     setValid(format.valid.test(text));
+    //   }
+    // }
+  };
+
+  return (
+    <Input.TextInput
+      {...props}
+      // TODO(burdon): validationValence on Input.
+      style={valid ? {} : ({ '--tw-ring-color': 'red' } as any)}
+      onChange={handleChange}
+    />
+  );
+};

package/src/components/deprecated/FormInput.tsx

@@ -0,0 +1,58 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React, { type JSX, type PropsWithChildren } from 'react';
+
+import { Input } from '@dxos/react-ui';
+
+export type DeprecatedFormInputProps = {
+  label: string;
+  description?: JSX.Element;
+  secondary?: JSX.Element;
+};
+
+/**
+ * @deprecated
+ */
+// TODO(burdon): Still used in ObservabilitySettings and all settings.
+export const DeprecatedFormInput = ({
+  label,
+  description,
+  secondary,
+  children,
+}: PropsWithChildren<DeprecatedFormInputProps>) => {
+  const primary = (
+    <div role='none' className='flex w-full gap-4 py-1'>
+      <Input.Root>
+        <div role='none' className='flex flex-col w-full'>
+          {/* TODO(burdon): Consistent height for controls (e.g., Select, Textbox, and Checkbox are all different). */}
+          <Input.Label classNames='flex min-h-[40px] items-center'>{label}</Input.Label>
+          {description && (
+            <Input.DescriptionAndValidation classNames='mbs-0.5'>
+              <Input.Description>{description}</Input.Description>
+            </Input.DescriptionAndValidation>
+          )}
+        </div>
+
+        <div role='none'>
+          <div role='none' className='flex min-h-[40px] items-center'>
+            {children}
+          </div>
+        </div>
+      </Input.Root>
+    </div>
+  );
+
+  if (secondary) {
+    // console.log(secondary);
+    return (
+      <div role='none' className='flex flex-col w-full'>
+        {primary}
+        {secondary}
+      </div>
+    );
+  }
+
+  return primary;
+};

package/src/components/deprecated/index.ts

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

package/src/components/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './deprecated';
+
+export * from './FieldEditor';
+export * from './Form';
+export * from './ViewEditor';

package/src/components/testing.tsx

@@ -0,0 +1,24 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React, { type PropsWithChildren } from 'react';
+
+import { type ThemedClassName } from '@dxos/react-ui';
+import { SyntaxHighlighter } from '@dxos/react-ui-syntax-highlighter';
+import { mx } from '@dxos/react-ui-theme';
+
+export const TestPanel = ({ classNames, children }: ThemedClassName<PropsWithChildren>) => (
+  <div className='flex flex-col p-4'>
+    <div className={mx('flex flex-col border border-separator rounded w-[300px]', classNames)}>{children}</div>
+  </div>
+);
+
+export const TestLayout = ({ classNames, json, children }: ThemedClassName<PropsWithChildren<{ json?: any }>>) => (
+  <div className='w-full h-full grid grid-cols-3'>
+    <div className={mx('flex col-span-2 w-full justify-center overflow-y-auto', classNames)}>{children}</div>
+    <SyntaxHighlighter language='json' className='w-full text-xs font-thin'>
+      {JSON.stringify(json, null, 2)}
+    </SyntaxHighlighter>
+  </div>
+);

package/src/hooks/index.ts

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

package/src/hooks/useForm.ts

@@ -0,0 +1,229 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type FocusEvent, useCallback, useEffect, useMemo, useState } from 'react';
+
+import { type SimpleType, type S } from '@dxos/effect';
+import { invariant } from '@dxos/invariant';
+import { log } from '@dxos/log';
+import { validateSchema, type PropertyKey, type ValidationError } from '@dxos/schema';
+
+/**
+ * Return type from `useForm` hook.
+ */
+export type FormHandler<T extends object = {}> = {
+  //
+  // Form state management.
+  //
+
+  values: T;
+  errors: Record<PropertyKey<T>, string>;
+  touched: Record<PropertyKey<T>, boolean>;
+  changed: Record<PropertyKey<T>, boolean>;
+  canSubmit: boolean;
+  handleSubmit: () => void;
+
+  //
+  // Form input component helpers.
+  //
+
+  getStatus: (property: PropertyKey<T>) => { status?: 'error'; error?: string };
+  getValue: <V>(property: PropertyKey<T>) => V;
+  onValueChange: <V>(property: PropertyKey<T>, type: SimpleType, value: V) => void;
+  onBlur: (event: FocusEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
+};
+
+/**
+ * Hook options.
+ */
+export interface FormOptions<T extends object> {
+  schema: S.Schema<T>;
+
+  // TODO(burdon): Are these reactive?
+  initialValues: T;
+
+  /**
+   * Callback for value changes. Note: This is called even when values are invalid.
+   * Sometimes the parent component may want to know about changes even if the form is
+   * in an invalid state.
+   */
+  onValuesChanged?: (values: T) => void;
+
+  /**
+   * Custom validation function that runs only after schema validation passes.
+   * Use this for complex validation logic that can't be expressed in the schema.
+   * @returns Array of validation errors, or undefined if validation passes
+   */
+  // TODO(burdon): Change to key x value.
+  onValidate?: (values: T) => ValidationError[] | undefined;
+
+  /**
+   * Called when the form is valid.
+   */
+  onValid?: (values: T, meta: { changed: FormHandler<T>['changed'] }) => void;
+
+  /**
+   * Called when the form is submitted and passes validation.
+   */
+  onSubmit?: (values: T, meta: { changed: FormHandler<T>['changed'] }) => void;
+}
+
+/**
+ * Creates a hook for managing form state, including values, validation, and submission.
+ * Deeply integrated with `@dxos/schema` for schema-based validation.
+ */
+export const useForm = <T extends object>({
+  schema,
+  initialValues,
+  onValuesChanged,
+  onValidate,
+  onValid,
+  onSubmit,
+}: FormOptions<T>): FormHandler<T> => {
+  const [values, setValues] = useState<T>(initialValues);
+  useEffect(() => {
+    setValues(initialValues);
+  }, [initialValues]);
+
+  const [touched, setTouched] = useState<Record<PropertyKey<T>, boolean>>(createKeySet(initialValues, false));
+  const [changed, setChanged] = useState<Record<PropertyKey<T>, boolean>>(createKeySet(initialValues, false));
+  const [errors, setErrors] = useState<Record<PropertyKey<T>, string>>({} as Record<PropertyKey<T>, string>);
+
+  //
+  // Validation.
+  //
+
+  // TODO(burdon): Validate each property separately.
+  const validate = useCallback(
+    (values: T) => {
+      let errors: ValidationError[] = validateSchema(schema, values) ?? [];
+      if (errors.length === 0 && onValidate) {
+        errors = onValidate(values) ?? [];
+      }
+
+      setErrors(flatMap(errors));
+      return errors.length === 0;
+    },
+    [schema, onValidate],
+  );
+
+  // Validate on schema change.
+  const [schemaDirty, setSchemaDirty] = useState(false);
+  useEffect(() => setSchemaDirty(true), [schema]);
+  useEffect(() => {
+    if (schemaDirty) {
+      validate(values);
+      setSchemaDirty(false);
+    }
+  }, [values, schemaDirty]);
+
+  /**
+   * NOTE: We can submit if there is no touched field that has an error.
+   * Basically, if there's a validation message visible in the form, submit should be disabled.
+   */
+  const canSubmit = useMemo(
+    () =>
+      Object.keys(values).every(
+        (property) => touched[property as PropertyKey<T>] === false || !errors[property as PropertyKey<T>],
+      ),
+    [values, touched, errors],
+  );
+
+  const handleSubmit = useCallback(() => {
+    if (validate(values)) {
+      onSubmit?.(values, { changed });
+    }
+  }, [values, validate, onSubmit]);
+
+  //
+  // Fields.
+  //
+
+  const getStatus = useCallback<FormHandler<T>['getStatus']>(
+    (property: PropertyKey<T>) => ({
+      status: errors[property] ? 'error' : undefined,
+      error: errors[property] ? errors[property] : undefined,
+    }),
+    [touched, errors],
+  );
+
+  // TODO(burdon): Use path to extract hierarchical value.
+  const getValue = <V>(property: PropertyKey<T>): V => {
+    return values[property] as V;
+  };
+
+  // TODO(burdon): Use path to set hierarchical value.
+  const onValueChange = (property: PropertyKey<T>, type: SimpleType, value: any) => {
+    let parsedValue = value;
+    try {
+      if (type === 'number') {
+        parsedValue = parseFloat(value as string) || 0;
+      }
+    } catch (err) {
+      log.catch(err);
+      parsedValue = undefined;
+    }
+
+    const newValues = { ...values, [property]: parsedValue };
+    setValues(newValues);
+    setChanged((prev) => ({ ...prev, [property]: true }));
+    onValuesChanged?.(newValues);
+
+    const isValid = validate(newValues);
+    if (isValid && onValid) {
+      onValid(newValues, { changed });
+    }
+  };
+
+  // TODO(burdon): This is a leaky abstraction: the hook ideally shouldn't get involved in UX.
+  const onBlur = useCallback(
+    (event: FocusEvent<HTMLInputElement | HTMLTextAreaElement>) => {
+      const { name } = event.target;
+      setTouched((touched) => ({ ...touched, [name]: true }));
+
+      // TODO(Zan): This should be configurable behavior.
+      if (event.relatedTarget?.getAttribute('type') === 'submit') {
+        // NOTE: We do this here instead of onSubmit because the blur event is triggered before the submit event
+        //  and results in the submit button being disabled when the form is invalid.
+        setTouched(createKeySet(values, true));
+      }
+
+      validate(values);
+    },
+    [validate, values],
+  );
+
+  return {
+    // State.
+    values,
+    errors,
+    touched,
+    changed,
+    canSubmit,
+    handleSubmit,
+
+    // Field utils.
+    getStatus,
+    getValue,
+    onValueChange,
+    onBlur,
+  } satisfies FormHandler<T>;
+};
+
+const createKeySet = <T extends object, V>(obj: T, value: V): Record<PropertyKey<T>, V> => {
+  invariant(obj);
+  return Object.keys(obj).reduce((acc, key) => ({ ...acc, [key]: value }), {} as Record<PropertyKey<T>, V>);
+};
+
+const flatMap = <T extends object>(errors: ValidationError[]) => {
+  return errors.reduce(
+    (result, { path, message }) => {
+      if (!(path in result)) {
+        result[path as PropertyKey<T>] = message;
+      }
+      return result;
+    },
+    {} as Record<PropertyKey<T>, string>,
+  );
+};

package/src/index.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import translations from './translations';
+
+export * from './components';
+export * from './hooks';
+export * from './util';
+
+export { translations };