@dxos/react-ui-form 0.8.4-main.84f28bd → 0.8.4-main.a4bbb77

package/src/components/Form/FormContent.tsx

@@ -9,36 +9,51 @@ import React, { 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) => {
@@ -62,7 +77,7 @@ export const FormField = ({
       type,
       format,
       label,
-      disabled: readonly,
+      readonly,
       placeholder,
       ...inputProps,
     },
@@ -82,7 +97,7 @@ export const FormField = ({
         label={label}
         inputOnly={inline}
         placeholder={placeholder}
-        disabled={readonly}
+        readonly={readonly}
         {...inputProps}
       />
     );
@@ -102,9 +117,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 +151,7 @@ export const FormField = ({
         label={label}
         inputOnly={inline}
         placeholder={placeholder}
-        disabled={readonly}
+        readonly={readonly}
         {...inputProps}
       />
     );
@@ -146,7 +166,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 +194,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,36 +210,90 @@ 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}>
@@ -227,13 +305,15 @@ export const FormFields = forwardRef<HTMLDivElement, FormFieldsProps>(
                 property={property}
                 path={[...(path ?? []), property.name]}
                 readonly={readonly}
+                projection={projection}
                 onQueryRefOptions={onQueryRefOptions}
                 lookupComponent={lookupComponent}
                 Custom={Custom}
+                {...props}
               />
             );
           })
-          .filter(isNotFalsy)}
+          .filter(isTruthy)}
       </div>
     );
   },

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 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;
   }
 >) => {

package/src/components/Form/Input.tsx

@@ -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,65 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type SchemaAST } from 'effect';
-import React, { useCallback, useMemo, type FocusEvent } from 'react';
+import { type Schema, type SchemaAST } from 'effect';
+import React, { type KeyboardEvent, type MouseEvent, useCallback, useMemo, useState } from 'react';
 
 import {
+  type EchoSchema,
   Expando,
-  getTypeAnnotation,
   Ref,
   ReferenceAnnotationId,
   type ReferenceAnnotationValue,
+  getTypeAnnotation,
 } from '@dxos/echo-schema';
 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, Popover, useTranslation } from '@dxos/react-ui';
+import { PopoverCombobox } from '@dxos/react-ui-searchlist';
 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';
 
-type RefFieldProps = InputProps & {
+import { TextInput } from './Defaults';
+import { Form } from './Form';
+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
@@ -52,21 +72,70 @@ export const RefField = ({
   );
   const { options: availableOptions, loading: _loading } = useQueryRefOptions({ refTypeInfo, onQueryRefOptions });
 
+  const [showForm, setShowForm] = useState(false);
+  const [searchString, setSearchString] = useState('');
+
+  const handleFormSave = useCallback(
+    (values: any) => {
+      onCreate?.(values);
+      setShowForm(false);
+      setSearchString('');
+    },
+    [refTypeInfo, onCreate],
+  );
+
+  const handleFormCancel = useCallback(() => {
+    setShowForm(false);
+    setSearchString('');
+  }, []);
+
+  // TODO(thure): The following workarounds are necessary because `onSelect` is called after the Popover is already
+  //  closed. Augment/refactor CmdK, if possible, to facilitate stopping event default & propagation.
+
+  const handleClick = useCallback(
+    (event: MouseEvent) => {
+      if (createSchema && (event.target as HTMLElement).closest('[data-value="__create__"]')) {
+        event.stopPropagation();
+        event.preventDefault();
+        setShowForm(true);
+      }
+    },
+    [createSchema],
+  );
+
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent) => {
+      if (
+        event.key === 'Enter' &&
+        createSchema &&
+        (event.currentTarget as HTMLElement).querySelector(
+          '[role="option"][aria-selected="true"][data-value="__create__"]',
+        )
+      ) {
+        event.stopPropagation();
+        event.preventDefault();
+        setShowForm(true);
+      }
+    },
+    [createSchema],
+  );
+
   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 +156,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,8 +183,6 @@ export const RefField = ({
     [availableOptions, array, onValueChange],
   );
 
-  const tagPickerMode: TagPickerMode = useMemo(() => (array ? 'multi-select' : 'single-select'), [array]);
-
   if (!refTypeInfo) {
     return null;
   }
@@ -132,32 +190,124 @@ export const RefField = ({
   const { status, error } = restInputProps.getStatus();
 
   const items = handleGetValue();
+  const selectedIds = useMemo(() => items.map((i: any) => i.id), [items]);
+  const labelById = useMemo(
+    () =>
+      availableOptions.reduce((acc: Record<string, string>, option) => {
+        acc[option.id.toLowerCase()] = option.label.toLowerCase();
+        return acc;
+      }, {}),
+    [availableOptions],
+  );
+  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'
-          />
+          <PopoverCombobox.Root>
+            <PopoverCombobox.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>
+            </PopoverCombobox.Trigger>
+            <PopoverCombobox.Content
+              filter={(value, search) =>
+                value === '__create__' || labelById[value]?.includes(search.toLowerCase()) ? 1 : 0
+              }
+              onClickCapture={handleClick}
+              onKeyDownCapture={handleKeyDown}
+            >
+              {showForm && createSchema ? (
+                <Popover.Viewport>
+                  <Form
+                    schema={createSchema}
+                    values={createInitialValuePath ? { [createInitialValuePath]: searchString } : {}}
+                    onSave={handleFormSave}
+                    onCancel={handleFormCancel}
+                    testId='create-referenced-object-form'
+                  />
+                </Popover.Viewport>
+              ) : (
+                <>
+                  <PopoverCombobox.Input
+                    placeholder={t('ref field combobox input placeholder')}
+                    value={searchString}
+                    onValueChange={(v) => setSearchString(v)}
+                    autoFocus
+                  />
+                  <PopoverCombobox.List>
+                    {availableOptions.map((option) => (
+                      <PopoverCombobox.Item
+                        key={option.id}
+                        value={option.id}
+                        onSelect={() => toggleSelect(option.id)}
+                        classNames='flex items-center gap-2'
+                      >
+                        <span className='grow'>{option.label}</span>
+                        {selectedIds.includes(option.id) && <Icon icon='ph--check--regular' />}
+                      </PopoverCombobox.Item>
+                    ))}
+                    {searchString.length > 0 && createOptionLabel && createOptionIcon && createSchema && (
+                      <PopoverCombobox.Item value='__create__' classNames='flex items-center gap-2'>
+                        <Icon icon={createOptionIcon} />
+                        {t(createOptionLabel[0], { ns: createOptionLabel[1].ns, text: searchString })}
+                      </PopoverCombobox.Item>
+                    )}
+                  </PopoverCombobox.List>
+                </>
+              )}
+              <PopoverCombobox.Arrow />
+            </PopoverCombobox.Content>
+          </PopoverCombobox.Root>
         )}
       </div>
       {inputOnly && <Input.DescriptionAndValidation>{error}</Input.DescriptionAndValidation>}
@@ -168,7 +318,7 @@ export const RefField = ({
 const RefFieldFallback = ({
   type,
   label,
-  disabled,
+  readonly,
   placeholder,
   inputOnly,
   getValue,
@@ -202,7 +352,7 @@ const RefFieldFallback = ({
     <TextInput
       type={type}
       label={label}
-      disabled={disabled}
+      readonly={readonly}
       placeholder={placeholder}
       inputOnly={inputOnly}
       getValue={handleGetValue as <V>() => V | undefined}