@dxos/react-ui-form 0.8.4-main.f9ba587 → 0.8.4-main.fffef41

package/src/components/Form/FormContent.tsx

@@ -2,50 +2,67 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Schema, SchemaAST, pipe } from 'effect';
-import { capitalize } from 'effect/String';
-import React, { forwardRef, useMemo } from 'react';
+import * as Function from 'effect/Function';
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+import * as StringEffect from 'effect/String';
+import React, { Component, type PropsWithChildren, type ReactNode, forwardRef, useMemo } from 'react';
 
 import { createJsonPath, findNode, getDiscriminatedType, isDiscriminatedUnion } from '@dxos/effect';
 import { type ThemedClassName } from '@dxos/react-ui';
 import { mx } from '@dxos/react-ui-theme';
-import { getSchemaProperties, type SchemaProperty } from '@dxos/schema';
-import { isNotFalsy } from '@dxos/util';
+import { type ProjectionModel, type SchemaProperty, getSchemaProperties } from '@dxos/schema';
+import { isTruthy } from '@dxos/util';
+
+import { type QueryRefOptions } from '../../hooks';
+import { getRefProps } from '../../util';
 
 import { ArrayField } from './ArrayField';
 import { SelectInput } from './Defaults';
+import { getInputComponent } from './factory';
 import { type ComponentLookup } from './Form';
-import { useInputProps, useFormValues } from './FormContext';
+import { useFormValues, useInputProps } from './FormContext';
 import { type InputComponent } from './Input';
-import { RefField } from './RefField';
-import { getInputComponent } from './factory';
-import { type QueryRefOptions } from '../../hooks';
-import { getRefProps } from '../../util';
+import { RefField, type RefFieldProps } from './RefField';
 
 export type FormFieldProps = {
   property: SchemaProperty<any>;
   path?: (string | number)[];
-  readonly?: boolean;
   /** Used to indicate if input should be presented inline (e.g. for array items). */
   inline?: boolean;
-  onQueryRefOptions?: QueryRefOptions;
+  projection?: ProjectionModel;
   lookupComponent?: ComponentLookup;
   Custom?: Partial<Record<string, InputComponent>>;
-};
+} & Pick<
+  RefFieldProps,
+  | 'readonly'
+  | 'onQueryRefOptions'
+  | 'createOptionLabel'
+  | 'createOptionIcon'
+  | 'onCreate'
+  | 'createSchema'
+  | 'createInitialValuePath'
+>;
 
 export const FormField = ({
   property,
   path,
   readonly,
   inline,
+  projection,
   onQueryRefOptions,
+  createOptionLabel,
+  createOptionIcon,
+  onCreate,
+  createSchema,
+  createInitialValuePath,
   lookupComponent,
   Custom,
 }: FormFieldProps) => {
   const { ast, name, type, format, title, description, options, examples, array } = property;
   const inputProps = useInputProps(path);
 
-  const label = useMemo(() => title ?? pipe(name, capitalize), [title, name]);
+  const label = useMemo(() => title ?? Function.pipe(name, StringEffect.capitalize), [title, name]);
   const placeholder = useMemo(
     () => (examples?.length ? `Example: "${examples[0]}"` : description),
     [examples, description],
@@ -62,7 +79,7 @@ export const FormField = ({
       type,
       format,
       label,
-      disabled: readonly,
+      readonly,
       placeholder,
       ...inputProps,
     },
@@ -82,7 +99,7 @@ export const FormField = ({
         label={label}
         inputOnly={inline}
         placeholder={placeholder}
-        disabled={readonly}
+        readonly={readonly}
         {...inputProps}
       />
     );
@@ -102,9 +119,14 @@ export const FormField = ({
         format={format}
         label={label}
         placeholder={placeholder}
-        disabled={readonly}
+        readonly={readonly}
         inputOnly={inline}
         onQueryRefOptions={onQueryRefOptions}
+        createOptionLabel={createOptionLabel}
+        createOptionIcon={createOptionIcon}
+        onCreate={onCreate}
+        createSchema={createSchema}
+        createInitialValuePath={createInitialValuePath}
         {...inputProps}
       />
     );
@@ -131,7 +153,7 @@ export const FormField = ({
         label={label}
         inputOnly={inline}
         placeholder={placeholder}
-        disabled={readonly}
+        readonly={readonly}
         {...inputProps}
       />
     );
@@ -146,7 +168,7 @@ export const FormField = ({
       <SelectInput
         type={type}
         format={format}
-        disabled={readonly}
+        readonly={readonly}
         inputOnly={inline}
         label={label}
         options={options.map((option) => ({ value: option, label: String(option) }))}
@@ -174,7 +196,11 @@ export const FormField = ({
             schema={Schema.make(typeLiteral)}
             path={path}
             readonly={readonly}
+            projection={projection}
             onQueryRefOptions={onQueryRefOptions}
+            createOptionLabel={createOptionLabel}
+            createOptionIcon={createOptionIcon}
+            onCreate={onCreate}
             Custom={Custom}
             lookupComponent={lookupComponent}
           />
@@ -186,55 +212,151 @@ export const FormField = ({
   return null;
 };
 
-export type FormFieldsProps = ThemedClassName<{
-  testId?: string;
-  readonly?: boolean;
-  schema: Schema.Schema.All;
-  /**
-   * Path to the current object from the root. Used with nested forms.
-   */
-  path?: (string | number)[];
-  filter?: (props: SchemaProperty<any>[]) => SchemaProperty<any>[];
-  sort?: string[];
-  lookupComponent?: ComponentLookup;
-  /**
-   * Map of custom renderers for specific properties.
-   * Prefer lookupComponent for plugin specific input surfaces.
-   */
-  Custom?: Partial<Record<string, InputComponent>>;
-  onQueryRefOptions?: QueryRefOptions;
-}>;
+export type FormFieldsProps = ThemedClassName<
+  {
+    testId?: string;
+    schema: Schema.Schema.All;
+    /**
+     * Path to the current object from the root. Used with nested forms.
+     */
+    path?: (string | number)[];
+    filter?: (props: SchemaProperty<any>[]) => SchemaProperty<any>[];
+    sort?: string[];
+    /**
+     * Optional projection for projection-based field management
+     */
+    projection?: ProjectionModel;
+    lookupComponent?: ComponentLookup;
+    /**
+     * Map of custom renderers for specific properties.
+     * Prefer lookupComponent for plugin specific input surfaces.
+     */
+    Custom?: Partial<Record<string, InputComponent>>;
+    onQueryRefOptions?: QueryRefOptions;
+  } & Pick<FormFieldProps, 'readonly'> &
+    Pick<
+      RefFieldProps,
+      | 'onQueryRefOptions'
+      | 'createOptionLabel'
+      | 'createOptionIcon'
+      | 'onCreate'
+      | 'createSchema'
+      | 'createInitialValuePath'
+    >
+>;
 
 export const FormFields = forwardRef<HTMLDivElement, FormFieldsProps>(
   (
-    { classNames, testId, schema, path, filter, sort, readonly, lookupComponent, Custom, onQueryRefOptions },
+    {
+      classNames,
+      schema,
+      path,
+      filter,
+      sort,
+      projection,
+      readonly,
+      lookupComponent,
+      Custom,
+      onQueryRefOptions,
+      ...props
+    },
     forwardRef,
   ) => {
     const values = useFormValues(path);
     const properties = useMemo(() => {
       const props = getSchemaProperties(schema.ast, values);
+
+      // 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));
+        const orderedProps: SchemaProperty<any>[] = [];
+
+        // 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((fp) => String(fp.field.path)));
+        const remainingProps = visibleProps.filter((prop) => !projectionPaths.has(prop.name));
+        orderedProps.push(...remainingProps);
+
+        return orderedProps;
+      }
+
+      // Fallback to legacy filter/sort behavior
       const filtered = filter ? filter(props) : props;
       return sort ? filtered.sort((a, b) => sort.indexOf(a.name) - sort.indexOf(b.name)) : filtered;
-    }, [schema, values, filter, sort]);
+    }, [schema, values, filter, sort, projection?.fields]);
 
     return (
       <div role='form' className={mx('is-full', classNames)} ref={forwardRef}>
         {properties
           .map((property) => {
             return (
-              <FormField
-                key={property.name}
-                property={property}
-                path={[...(path ?? []), property.name]}
-                readonly={readonly}
-                onQueryRefOptions={onQueryRefOptions}
-                lookupComponent={lookupComponent}
-                Custom={Custom}
-              />
+              <ErrorBoundary key={property.name} path={[...(path ?? []), property.name]}>
+                <FormField
+                  property={property}
+                  path={[...(path ?? []), property.name]}
+                  readonly={readonly}
+                  projection={projection}
+                  onQueryRefOptions={onQueryRefOptions}
+                  lookupComponent={lookupComponent}
+                  Custom={Custom}
+                  {...props}
+                />
+              </ErrorBoundary>
             );
           })
-          .filter(isNotFalsy)}
+          .filter(isTruthy)}
       </div>
     );
   },
 );
+
+type ErrorState = {
+  error: Error | undefined;
+};
+
+type ErrorBoundaryProps = PropsWithChildren<{
+  path?: (string | number)[];
+}>;
+
+class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorState> {
+  static getDerivedStateFromError(error: Error): { error: Error } {
+    return { error };
+  }
+
+  override state = { error: undefined };
+
+  override componentDidUpdate(prevProps: ErrorBoundaryProps): void {
+    if (prevProps.path !== this.props.path) {
+      this.resetError();
+    }
+  }
+
+  override render(): ReactNode {
+    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(): void {
+    this.setState({ error: undefined });
+  }
+}

package/src/components/Form/FormContext.tsx

@@ -3,19 +3,19 @@
 //
 
 import React, {
-  createContext,
+  type FocusEvent,
+  type PropsWithChildren,
   type RefObject,
+  createContext,
+  useCallback,
   useContext,
   useEffect,
   useMemo,
-  type FocusEvent,
-  type PropsWithChildren,
-  useCallback,
 } from 'react';
 
 import { raise } from '@dxos/debug';
-import { type BaseObject, getValue } from '@dxos/echo-schema';
-import { createJsonPath, type SimpleType } from '@dxos/effect';
+import { type BaseObject, getValue } from '@dxos/echo/internal';
+import { type SimpleType, createJsonPath } from '@dxos/effect';
 
 import { type FormHandler, type FormOptions, useForm } from '../../hooks';
 
@@ -62,7 +62,7 @@ export const FormProvider = ({
   ...formOptions
 }: PropsWithChildren<
   FormOptions<any> & {
-    formRef?: RefObject<HTMLDivElement>;
+    formRef?: RefObject<HTMLDivElement | null>;
     autoSave?: boolean;
   }
 >) => {
@@ -92,7 +92,7 @@ export const FormProvider = ({
         }
       }
     },
-    [form, autoSave],
+    [form.canSave, form.formIsValid, form.handleSave, autoSave],
   );
 
   useEffect(() => {

package/src/components/Form/Input.tsx

@@ -4,7 +4,7 @@
 
 import React, { type FC } from 'react';
 
-import { type FormatEnum } from '@dxos/echo-schema';
+import { type FormatEnum } from '@dxos/echo/internal';
 import { type SimpleType } from '@dxos/effect';
 import { Icon, Input, Tooltip } from '@dxos/react-ui';
 import { labelSpacing } from '@dxos/react-ui-stack';
@@ -19,9 +19,12 @@ export type InputProps = {
   type: SimpleType;
   format?: FormatEnum;
   label: string;
-  disabled?: boolean;
   placeholder?: string;
   inputOnly?: boolean;
+  /**
+   * Specifies the readonly variant: either disabled inputs, elements indicating they are usually editable but currently are not; or `static`, a field’s representation as regular content without signifiers that it is ever editable.
+   */
+  readonly?: 'disabled-input' | 'static' | false;
 } & FormInputStateProps;
 
 /**

package/src/components/Form/RefField.tsx

@@ -2,45 +2,67 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type SchemaAST } from 'effect';
-import React, { useCallback, useMemo, type FocusEvent } from 'react';
+import '@dxos/lit-ui/dx-tag-picker.pcss';
+
+import type * as Schema from 'effect/Schema';
+import type * as SchemaAST from 'effect/SchemaAST';
+import React, { useCallback, useMemo } from 'react';
 
 import {
+  type EchoSchema,
   Expando,
-  getTypeAnnotation,
   Ref,
   ReferenceAnnotationId,
   type ReferenceAnnotationValue,
-} from '@dxos/echo-schema';
+  getTypeAnnotation,
+} from '@dxos/echo/internal';
 import { findAnnotation } from '@dxos/effect';
 import { DXN } from '@dxos/keys';
-import { DxRefTag } from '@dxos/lit-ui/react';
-import { Input, useTranslation } from '@dxos/react-ui';
-import { TagPicker, type TagPickerMode, type TagPickerItemData } from '@dxos/react-ui-tag-picker';
+import { type DxTagPickerItemClick } from '@dxos/lit-ui';
+import { DxAnchor, DxTagPickerItem } from '@dxos/lit-ui/react';
+import { Button, Icon, Input, useTranslation } from '@dxos/react-ui';
 import { descriptionText, mx } from '@dxos/react-ui-theme';
 import { isNonNullable } from '@dxos/util';
 
-import { TextInput } from './Defaults';
-import { InputHeader, type InputProps } from './Input';
 import { type QueryRefOptions, useQueryRefOptions } from '../../hooks';
 import { translationKey } from '../../translations';
+import { ObjectPicker } from '../ObjectPicker';
 
-type RefFieldProps = InputProps & {
+import { TextInput } from './Defaults';
+import { InputHeader, type InputProps } from './Input';
+
+export type RefFieldProps = InputProps & {
   ast?: SchemaAST.AST;
   array?: boolean;
+  createOptionLabel?: [string, { ns: string }];
+  createOptionIcon?: string;
+  onCreate?: (values: any) => void;
+  createSchema?: Schema.Schema.AnyNoContext;
+  createInitialValuePath?: string;
   onQueryRefOptions?: QueryRefOptions;
+  schema?: EchoSchema;
+};
+
+// TODO(thure): Is this a standard that should be better canonized?
+const isRefSnapShot = (val: any): val is { '/': string } => {
+  return typeof val === 'object' && typeof (val as any)?.['/'] === 'string';
 };
 
 export const RefField = ({
   type,
   label,
-  disabled,
+  readonly,
   placeholder,
   inputOnly,
   array,
   ast,
   getValue,
+  createOptionLabel,
+  createOptionIcon,
   onBlur,
+  onCreate,
+  createSchema,
+  createInitialValuePath,
   onQueryRefOptions,
   onValueChange,
   ...restInputProps
@@ -50,23 +72,28 @@ export const RefField = ({
     () => (ast ? findAnnotation<ReferenceAnnotationValue>(ast, ReferenceAnnotationId) : undefined),
     [ast],
   );
-  const { options: availableOptions, loading: _loading } = useQueryRefOptions({ refTypeInfo, onQueryRefOptions });
+  const {
+    options: availableOptions,
+    update: updateOptions,
+    loading: _loading,
+  } = useQueryRefOptions({ refTypeInfo, onQueryRefOptions });
 
   if ((refTypeInfo && refTypeInfo?.typename === getTypeAnnotation(Expando)?.typename) || !onQueryRefOptions) {
     // If ref type is expando, fall back to taking a DXN in string format.
     return (
       <RefFieldFallback
-        {...{ type, label, placeholder, disabled, inputOnly, getValue, onBlur, onValueChange, ...restInputProps }}
+        {...{ type, label, placeholder, readonly, inputOnly, getValue, onBlur, onValueChange, ...restInputProps }}
       />
     );
   }
 
-  const handleGetValue = useCallback((): TagPickerItemData[] => {
+  const handleGetValue = useCallback(() => {
     const formValue = getValue();
 
     const unknownToRefOption = (val: unknown) => {
-      if (Ref.isRef(val)) {
-        const dxnString = val.dxn.toString();
+      const isRef = Ref.isRef(val);
+      if (isRef || isRefSnapShot(val)) {
+        const dxnString = isRef ? val.dxn.toString() : val['/'];
         const matchingOption = availableOptions.find((option) => option.id === dxnString);
         if (matchingOption) {
           return matchingOption;
@@ -87,15 +114,6 @@ export const RefField = ({
     return [];
   }, [getValue, availableOptions, array]);
 
-  const handleSearch = useCallback(
-    (text: string, ids: string[]): TagPickerItemData[] =>
-      availableOptions
-        .filter((option) => !ids.includes(option.id))
-        .filter((option) => option.label.toLowerCase().includes(text.toLowerCase()))
-        .map((option) => ({ id: option.id, label: option.label, hue: option.hue as any })),
-    [availableOptions],
-  );
-
   const handleUpdate = useCallback(
     (ids: string[]) => {
       if (ids.length === 0) {
@@ -123,7 +141,13 @@ export const RefField = ({
     [availableOptions, array, onValueChange],
   );
 
-  const tagPickerMode: TagPickerMode = useMemo(() => (array ? 'multi-select' : 'single-select'), [array]);
+  const handleCreate = useCallback(
+    (values: any) => {
+      onCreate?.(values);
+      updateOptions();
+    },
+    [onCreate, updateOptions],
+  );
 
   if (!refTypeInfo) {
     return null;
@@ -132,32 +156,78 @@ export const RefField = ({
   const { status, error } = restInputProps.getStatus();
 
   const items = handleGetValue();
+  const selectedIds = useMemo(() => items.map((i: any) => i.id), [items]);
+  const toggleSelect = useCallback(
+    (id: string) => {
+      if (array) {
+        const nextIds = selectedIds.includes(id) ? selectedIds.filter((x) => x !== id) : [...selectedIds, id];
+        handleUpdate(nextIds);
+      } else {
+        if (selectedIds[0] === id) {
+          handleUpdate([]);
+        } else {
+          handleUpdate([id]);
+        }
+      }
+    },
+    [array, selectedIds, handleUpdate],
+  );
 
   // NOTE(thure): I left both predicates in-place in case we decide to add variants which do render readonly but empty values.
-  return disabled && items.length < 1 ? null : (
+  return readonly && items.length < 1 ? null : (
     <Input.Root validationValence={status}>
       {!inputOnly && <InputHeader error={error} label={label} />}
       <div data-no-submit>
-        {disabled ? (
+        {readonly ? (
           items.length < 1 ? (
             <p className={mx(descriptionText, 'mbe-2')}>{t('empty readonly ref field label')}</p>
           ) : (
             items.map((item) => (
-              <DxRefTag key={item.id} refid={item.id} rootclassname='mie-1' style={{ marginInlineEnd: '.25rem' }}>
+              <DxAnchor key={item.id} refid={item.id} rootclassname='mie-1'>
                 {item.label}
-              </DxRefTag>
+              </DxAnchor>
             ))
           )
         ) : (
-          <TagPicker
-            readonly={disabled}
-            items={items}
-            mode={tagPickerMode}
-            onBlur={(event) => onBlur(event as unknown as FocusEvent<HTMLElement>)}
-            onUpdate={handleUpdate}
-            onSearch={handleSearch}
-            classNames='bg-inputSurface p-1.5 rounded-sm'
-          />
+          <ObjectPicker.Root>
+            <ObjectPicker.Trigger asChild>
+              <Button variant='ghost' classNames='is-full text-start gap-2'>
+                <div role='none' className='grow'>
+                  {items?.length ? (
+                    items?.map((item) => (
+                      <DxTagPickerItem
+                        key={item.id}
+                        itemId={item.id}
+                        label={item.label}
+                        {...(item.hue ? { hue: item.hue } : {})}
+                        removeLabel={t('remove item label')}
+                        onItemClick={(event: DxTagPickerItemClick) => {
+                          if (event.action === 'remove') {
+                            toggleSelect(item.id);
+                          }
+                        }}
+                      />
+                    ))
+                  ) : (
+                    <span className='text-description'>
+                      {placeholder ?? t('ref field placeholder', { count: array ? 99 : 1 })}
+                    </span>
+                  )}
+                </div>
+                <Icon size={3} icon='ph--caret-down--bold' />
+              </Button>
+            </ObjectPicker.Trigger>
+            <ObjectPicker.Content
+              options={availableOptions}
+              selectedIds={selectedIds}
+              onSelect={toggleSelect}
+              createSchema={createSchema}
+              createOptionLabel={createOptionLabel}
+              createOptionIcon={createOptionIcon}
+              createInitialValuePath={createInitialValuePath}
+              onCreate={handleCreate}
+            />
+          </ObjectPicker.Root>
         )}
       </div>
       {inputOnly && <Input.DescriptionAndValidation>{error}</Input.DescriptionAndValidation>}
@@ -168,7 +238,7 @@ export const RefField = ({
 const RefFieldFallback = ({
   type,
   label,
-  disabled,
+  readonly,
   placeholder,
   inputOnly,
   getValue,
@@ -202,7 +272,7 @@ const RefFieldFallback = ({
     <TextInput
       type={type}
       label={label}
-      disabled={disabled}
+      readonly={readonly}
       placeholder={placeholder}
       inputOnly={inputOnly}
       getValue={handleGetValue as <V>() => V | undefined}