@dxos/react-ui-form 0.8.4-main.406dc2a → 0.8.4-main.422d1c7879

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

@@ -0,0 +1,228 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useCallback, useMemo, useState } from 'react';
+
+import '@dxos/lit-ui/dx-tag-picker.pcss';
+import { type Database, Entity, Filter, Obj, Ref, Type } from '@dxos/echo';
+import { useQuery, useSchema as defaultUseSchema } from '@dxos/echo-react';
+import { ReferenceAnnotationId, type ReferenceAnnotationValue } from '@dxos/echo/internal';
+import { findAnnotation } from '@dxos/effect';
+import { DXN } from '@dxos/keys';
+import { DxAnchor } from '@dxos/lit-ui/react';
+import { Button, Icon, Input, useTranslation } from '@dxos/react-ui';
+import { ParentLabelAnnotationId } from '@dxos/schema';
+
+import { translationKey } from '../../../translations';
+import { ObjectPicker, type ObjectPickerContentProps, type RefOption } from '../../ObjectPicker';
+import { omitHiddenFormFields, omitId } from '../Form';
+import { type FormFieldComponentProps, FormFieldLabel } from '../FormFieldComponent';
+
+// TODO(burdon): Factor out.
+const isRefSnapshot = (val: any): val is { '/': string } => {
+  return typeof val === 'object' && typeof (val as any)?.['/'] === 'string';
+};
+
+const defaultGetOptions: NonNullable<RefFieldProps['getOptions']> = (results, { parentLabel } = {}) =>
+  results.map((result) => {
+    const id = Entity.getDXN(result).toString();
+    const parent = parentLabel ? Obj.getParent(result as Obj.Unknown) : undefined;
+    const label = parent ? Entity.getLabel(parent) : Entity.getLabel(result);
+    return { id, label: label ?? id };
+  });
+
+const defaultUseResults: NonNullable<RefFieldProps['useResults']> = (db, typename) =>
+  useQuery(
+    db,
+    typename
+      ? // For Ref.Ref(Obj.Unknown) we want to show all objects.
+        typename === Type.getTypename(Obj.Unknown)
+        ? Filter.everything()
+        : Filter.typename(typename)
+      : Filter.nothing(),
+  );
+
+export type RefFieldProps = FormFieldComponentProps &
+  Pick<
+    ObjectPickerContentProps,
+    'createOptionLabel' | 'createOptionIcon' | 'createInitialValuePath' | 'createFieldMap'
+  > & {
+    db?: Database.Database;
+    // TODO(burdon): Replace hooks with callbacks.
+    useSchema?: (db?: Database.Database, typename?: string) => Type.AnyEntity;
+    useResults?: (db?: Database.Database, typename?: string) => Entity.Any[];
+    getOptions?: (objects: Entity.Any[], options?: { parentLabel?: boolean }) => RefOption[];
+    /**
+     * Persist a newly-created object. Called after the user fills out the
+     * inline create form and clicks Save. Should add the object to the
+     * database and return it (sync or async). The returned object is then
+     * wired into this slot's form value as a Ref.
+     */
+    onCreate?: (schema: Type.AnyEntity, values: any) => Obj.Unknown | Promise<Obj.Unknown> | undefined | void;
+  };
+
+export const RefField = (props: RefFieldProps) => {
+  const {
+    type,
+    readonly,
+    label,
+    placeholder,
+    layout,
+    getStatus,
+    getValue,
+    createOptionLabel,
+    createOptionIcon,
+    createInitialValuePath,
+    createFieldMap,
+    db,
+    useSchema = defaultUseSchema,
+    useResults = defaultUseResults,
+    getOptions = defaultGetOptions,
+    onCreate,
+    onValueChange,
+  } = props;
+  const { t } = useTranslation(translationKey);
+  const { status, error } = getStatus();
+
+  const typename = useMemo(
+    () => (type ? findAnnotation<ReferenceAnnotationValue>(type, ReferenceAnnotationId)?.typename : undefined),
+    [type],
+  );
+
+  const results = useResults(db, typename);
+  const options = useMemo(() => {
+    const parentLabel = type ? findAnnotation<boolean>(type, ParentLabelAnnotationId) === true : false;
+    return getOptions(results, { parentLabel });
+  }, [results, getOptions, type]);
+
+  const handleGetValue = useCallback(() => {
+    const formValue = getValue();
+    // Match form-value Refs against options by the bare object id (last DXN
+    // segment), not by full DXN string. Ref.make uses
+    // `DXN.fromLocalObjectId(id)` (`dxn:echo:@:<id>`), but
+    // `Entity.getDXN(obj)` on a registered object produces the space-scoped
+    // form (`dxn:echo:<spaceId>:<id>`). String-comparing the two never
+    // matches, so the just-created Ref's option lookup fails and the slot
+    // displays as empty even though the underlying form value IS set.
+    const dxnToObjectId = (dxn: string): string => dxn.split(':').pop() ?? dxn;
+
+    const unknownToRefOption = (value: unknown) => {
+      const isRef = Ref.isRef(value);
+      if (isRef || isRefSnapshot(value)) {
+        const dxnString = isRef ? value.dxn.toString() : value['/'];
+        const objectId = dxnToObjectId(dxnString);
+        const matchingOption = options.find((option) => dxnToObjectId(option.id) === objectId);
+        if (matchingOption) {
+          return matchingOption;
+        }
+      }
+
+      return undefined;
+    };
+
+    return unknownToRefOption(formValue);
+  }, [options, getValue]);
+
+  const item = handleGetValue();
+  const selectedIds = useMemo(() => (item ? [item.id] : []), [item]);
+  const createSchema = useSchema(db, typename);
+
+  // Lift the popover open state so we can dismiss it after a successful create.
+  const [open, setOpen] = useState(false);
+
+  const handleCreate = useCallback(
+    async (values: any) => {
+      if (!createSchema || !onCreate) {
+        return;
+      }
+      const newObject = await onCreate(createSchema, values);
+      if (newObject) {
+        // Wire the newly-created object into this slot's form value. ArrayField
+        // owns the array; this RefField represents a single slot, so writing a
+        // Ref via `onValueChange` populates that slot.
+        onValueChange(type, Ref.make(newObject));
+      }
+      setOpen(false);
+    },
+    [createSchema, onCreate, type, onValueChange],
+  );
+
+  const handleUpdate = useCallback(
+    (id: string | undefined) => {
+      const item = options.find((option) => option.id === id);
+      const ref = item ? Ref.fromDXN(DXN.parse(item.id)) : undefined;
+      onValueChange(type, ref);
+    },
+    [options, type, onValueChange],
+  );
+
+  const handleSelect = useCallback(
+    (id: string) => {
+      if (item?.id === id) {
+        handleUpdate(undefined);
+      } else {
+        handleUpdate(id);
+      }
+    },
+    [item, handleUpdate],
+  );
+
+  if (!typename || ((readonly || layout === 'static') && !item)) {
+    return null;
+  }
+
+  return (
+    <Input.Root validationValence={status}>
+      {layout !== 'inline' && <FormFieldLabel error={error} readonly={readonly} label={label} />}
+      <div>
+        {readonly ? (
+          !item ? (
+            <p className='text-description mb-2'>{t('empty-readonly-ref-field.label')}</p>
+          ) : (
+            <DxAnchor key={item.id} dxn={item.id} rootclassname='me-1'>
+              {item.label}
+            </DxAnchor>
+          )
+        ) : (
+          <ObjectPicker.Root open={open} onOpenChange={setOpen}>
+            <ObjectPicker.Trigger asChild classNames='p-0'>
+              {item ? (
+                <div role='none' className='flex gap-form-gap w-full'>
+                  <Input.Root key={item.id}>
+                    <Input.TextInput value={item.label} readOnly classNames='w-full' />
+                  </Input.Root>
+                </div>
+              ) : (
+                <Button classNames='w-full text-start gap-form-gap'>
+                  <div role='none' className='grow overflow-hidden'>
+                    <span className='truncate text-description'>{placeholder ?? t('ref-field.placeholder')}</span>
+                  </div>
+                  <Icon size={3} icon='ph--caret-down--bold' />
+                </Button>
+              )}
+            </ObjectPicker.Trigger>
+            <ObjectPicker.Portal>
+              <ObjectPicker.Content
+                classNames='dx-card-popover-width'
+                options={options}
+                selectedIds={selectedIds}
+                // Strip hidden (`FormInputAnnotation.set(false)`) fields so the
+                // form's validator doesn't reject required-but-hidden fields
+                // such as backing-object refs supplied by a `FactoryAnnotation`.
+                createSchema={createSchema && omitHiddenFormFields(omitId(createSchema))}
+                createOptionLabel={createOptionLabel}
+                createOptionIcon={createOptionIcon}
+                createInitialValuePath={createInitialValuePath}
+                createFieldMap={createFieldMap}
+                onCreate={handleCreate}
+                onSelect={handleSelect}
+              />
+            </ObjectPicker.Portal>
+          </ObjectPicker.Root>
+        )}
+      </div>
+      {layout === 'full' && <Input.DescriptionAndValidation>{error}</Input.DescriptionAndValidation>}
+    </Input.Root>
+  );
+};

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

@@ -0,0 +1,65 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React, { useCallback } from 'react';
+
+import { Input, Select, type SelectRootProps } from '@dxos/react-ui';
+
+import { type FormFieldComponentProps, FormFieldLabel } from '../FormFieldComponent';
+
+export type SelectFieldOptions = FormFieldComponentProps & {
+  options?: Array<{ value: string | number; label?: string }>;
+};
+
+export const SelectField = ({
+  type,
+  readonly,
+  label,
+  layout,
+  placeholder,
+  options,
+  getStatus,
+  getValue,
+  onValueChange,
+}: SelectFieldOptions) => {
+  const { status, error } = getStatus();
+  const value = getValue() as string | undefined;
+
+  const handleValueChange = useCallback<NonNullable<SelectRootProps['onValueChange']>>(
+    (value) => onValueChange(type, value),
+    [type, onValueChange],
+  );
+
+  if ((readonly || layout === 'static') && value == null) {
+    return null;
+  }
+
+  return (
+    <Input.Root validationValence={status}>
+      {layout !== 'inline' && <FormFieldLabel error={error} readonly={readonly} label={label} />}
+      {layout === 'static' ? (
+        <p>{options?.find(({ value: optionValue }) => optionValue === value)?.label ?? String(value)}</p>
+      ) : (
+        <Select.Root value={value} onValueChange={handleValueChange}>
+          {/* TODO(burdon): Placeholder not working? */}
+          <Select.TriggerButton classNames='w-full' disabled={!!readonly} placeholder={placeholder} />
+          <Select.Portal>
+            <Select.Content>
+              <Select.Viewport>
+                {options?.map(({ value, label }) => (
+                  // NOTE: Numeric values are converted to and from strings.
+                  <Select.Option key={String(value)} value={String(value)}>
+                    {label ?? String(value)}
+                  </Select.Option>
+                ))}
+              </Select.Viewport>
+              <Select.Arrow />
+            </Select.Content>
+          </Select.Portal>
+        </Select.Root>
+      )}
+      {layout === 'full' && <Input.DescriptionAndValidation>{error}</Input.DescriptionAndValidation>}
+    </Input.Root>
+  );
+};

package/src/components/Form/{custom/SelectOptionsInput.stories.tsx → fields/SelectOptionField.stories.tsx}

@@ -6,17 +6,16 @@ import { type Meta, type StoryObj } from '@storybook/react-vite';
 import * as Schema from 'effect/Schema';
 import React, { useState } from 'react';
 
-import { type SelectOption, SelectOptionSchema } from '@dxos/echo/internal';
-import { withTheme } from '@dxos/react-ui/testing';
+import { SelectOption } from '@dxos/echo/internal';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
 
 import { translations } from '../../../translations';
-import { TestLayout, TestPanel } from '../../testing';
+import { TestLayout } from '../../testing';
 import { Form } from '../Form';
-
-import { SelectOptionInput } from './SelectOptionsInput';
+import { SelectOptionField } from './SelectOptionField';
 
 const schema = Schema.Struct({
-  options: Schema.Array(SelectOptionSchema).pipe(Schema.mutable),
+  options: Schema.Array(SelectOption).pipe(Schema.mutable),
 }).pipe(Schema.mutable);
 
 const DefaultStory = () => {
@@ -31,23 +30,28 @@ const DefaultStory = () => {
 
   return (
     <TestLayout>
-      <TestPanel>
-        <Form
-          schema={schema}
-          values={values}
-          onSave={(vals) => setValues(vals)}
-          Custom={{ options: SelectOptionInput }}
-        />
-      </TestPanel>
+      <Form.Root
+        schema={schema}
+        values={values}
+        fieldMap={{ options: SelectOptionField }}
+        onSave={(values) => setValues(values)}
+      >
+        <Form.Viewport>
+          <Form.Content>
+            <Form.FieldSet />
+            <Form.Actions />
+          </Form.Content>
+        </Form.Viewport>
+      </Form.Root>
     </TestLayout>
   );
 };
 
 const meta = {
-  title: 'ui/react-ui-form/SelectOptionsInput',
-  component: SelectOptionInput as any,
+  title: 'ui/react-ui-form/SelectOptionField',
+  component: SelectOptionField as any,
   render: DefaultStory,
-  decorators: [withTheme],
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
   parameters: {
     layout: 'fullscreen',
     translations,

package/src/components/Form/{custom/SelectOptionsInput.tsx → fields/SelectOptionField.tsx}

@@ -9,25 +9,32 @@ import { PublicKey } from '@dxos/keys';
 import { type ChromaticPalette, IconButton, Input, Tag, useTranslation } from '@dxos/react-ui';
 import { List } from '@dxos/react-ui-list';
 import { HuePicker } from '@dxos/react-ui-pickers';
-import { hues, subtleHover } from '@dxos/react-ui-theme';
+import { hues, osTranslations, subtleHover } from '@dxos/ui-theme';
 
 import { translationKey } from '../../../translations';
-import { InputHeader, type InputProps } from '../Input';
-
-export const SelectOptionInput = ({ type, label, readonly, getStatus, getValue, onValueChange }: InputProps) => {
+import { type FormFieldComponentProps, FormFieldLabel } from '../FormFieldComponent';
+
+export const SelectOptionField = ({
+  type,
+  readonly,
+  label,
+  getStatus,
+  getValue,
+  onValueChange,
+}: FormFieldComponentProps<SelectOption[] | undefined>) => {
+  const { t } = useTranslation(translationKey);
+  const { status, error } = getStatus();
   const [selected, setSelectedId] = useState<string | null>(null);
   const [isNewOption, setIsNewOption] = useState(false);
   const inputRef = useRef<HTMLInputElement>(null);
-  const { t } = useTranslation(translationKey);
-  const { status, error } = getStatus();
-  const options = getValue<SelectOption[] | undefined>();
+  const options = getValue();
 
   // Initialization.
   useEffect(() => {
     if (options === undefined) {
       onValueChange(type, []);
     }
-  }, [options, onValueChange, type]);
+  }, [options, type, onValueChange]);
 
   const randomHue = () => {
     const usedHues = new Set(options?.map((option) => option.color) ?? []);
@@ -88,8 +95,8 @@ export const SelectOptionInput = ({ type, label, readonly, getStatus, getValue,
     [options, type, onValueChange],
   );
 
-  const handleKeyDown = useCallback((e: KeyboardEvent<HTMLInputElement>) => {
-    if (e.key === 'Enter') {
+  const handleKeyDown = useCallback((ev: KeyboardEvent<HTMLInputElement>) => {
+    if (ev.key === 'Enter') {
       setSelectedId(null);
     }
   }, []);
@@ -111,12 +118,12 @@ export const SelectOptionInput = ({ type, label, readonly, getStatus, getValue,
 
   return (
     <Input.Root validationValence={status}>
-      <InputHeader error={error} label={label} />
+      <FormFieldLabel error={error} readonly={readonly} label={label} />
       <div role='none'>
         {options && (
           <List.Root
             items={options}
-            isItem={(item) => true}
+            isItem={(_item) => true}
             onMove={readonly ? undefined : handleMove}
             readonly={!!readonly}
           >
@@ -127,7 +134,7 @@ export const SelectOptionInput = ({ type, label, readonly, getStatus, getValue,
                     <List.Item
                       role='button'
                       item={item}
-                      classNames={[subtleHover, 'flex flex-col cursor-pointer rounded-sm']}
+                      classNames={[subtleHover, 'flex flex-col cursor-pointer rounded-xs']}
                       aria-expanded={selected === item.id}
                     >
                       <div className='flex items-center'>
@@ -139,32 +146,30 @@ export const SelectOptionInput = ({ type, label, readonly, getStatus, getValue,
                         <IconButton
                           iconOnly
                           variant='ghost'
-                          label={t(selected === item.id ? 'collapse label' : 'expand label', { ns: 'os' })}
+                          label={t(selected === item.id ? 'collapse label' : 'expand label', { ns: osTranslations })}
                           icon={selected === item.id ? 'ph--caret-down--regular' : 'ph--caret-right--regular'}
                           onClick={() => handleClick(item.id)}
                         />
                       </div>
                       {selected === item.id && (
-                        <div className='pli-cardSpacingInline plb-cardSpacingBlock flex flex-col gap-1 density-fine'>
-                          {/* 16px to match drag handle width. */}
-                          <Input.Label classNames='text-xs'>{t('select option label')}</Input.Label>
-                          <div className='grid grid-cols-[1fr_min-content_min-content] gap-1'>
+                        <div className='flex flex-col p-form-padding gap-form-gap dx-density-fine'>
+                          <Input.Label classNames='text-xs'>{t('select-option.label')}</Input.Label>
+                          <div className='grid grid-cols-[1fr_min-content_min-content] gap-form-gap'>
                             <Input.TextInput
                               disabled={!!readonly}
-                              placeholder={t('select option label placeholder')}
+                              placeholder={t('select-option-label.placeholder')}
                               ref={selected === item.id ? inputRef : undefined}
                               value={item.title}
                               onChange={handleTitleChange(item.id)}
                               onKeyDown={handleKeyDown}
                               classNames='flex-1'
-                              data-no-submit
                             />
                             <HuePicker disabled={!!readonly} value={item.color} onChange={handleColorChange(item.id)} />
                             <IconButton
                               disabled={!!readonly}
                               icon='ph--trash--fill'
                               iconOnly
-                              label={t('select option delete')}
+                              label={t('select-option-delete.button')}
                               onClick={() => handleDelete(item.id)}
                             />
                           </div>
@@ -176,10 +181,10 @@ export const SelectOptionInput = ({ type, label, readonly, getStatus, getValue,
                 <IconButton
                   variant='ghost'
                   icon='ph--plus--regular'
-                  label={t('select option add')}
+                  label={t('select-option-add.button')}
                   onClick={handleAdd}
                   disabled={!!readonly}
-                  classNames='is-full'
+                  classNames='w-full'
                 />
               </div>
             )}

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

@@ -0,0 +1,38 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React, { useCallback } from 'react';
+
+import { Input, type TextAreaProps } from '@dxos/react-ui';
+
+import { type FormFieldComponentProps, FormFieldWrapper } from '../FormFieldComponent';
+
+export const TextAreaField = ({
+  type,
+  readonly,
+  placeholder,
+  onValueChange,
+  onBlur,
+  ...props
+}: FormFieldComponentProps<string>) => {
+  const handleChange = useCallback<NonNullable<TextAreaProps['onChange']>>(
+    (event) => onValueChange(type, event.target.value),
+    [type, onValueChange],
+  );
+
+  return (
+    <FormFieldWrapper<string> readonly={readonly} {...props}>
+      {({ value = '' }) => (
+        <Input.TextArea
+          rows={3}
+          disabled={!!readonly}
+          placeholder={placeholder}
+          value={value}
+          onChange={handleChange}
+          onBlur={onBlur}
+        />
+      )}
+    </FormFieldWrapper>
+  );
+};

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

@@ -0,0 +1,38 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React, { useCallback } from 'react';
+
+import { Input, type TextInputProps } from '@dxos/react-ui';
+
+import { type FormFieldComponentProps, FormFieldWrapper } from '../FormFieldComponent';
+
+export const TextField = ({
+  type,
+  readonly,
+  placeholder,
+  onBlur,
+  onValueChange,
+  ...props
+}: FormFieldComponentProps<string>) => {
+  const handleChange = useCallback<NonNullable<TextInputProps['onChange']>>(
+    (event) => onValueChange(type, event.target.value),
+    [type, onValueChange],
+  );
+
+  return (
+    <FormFieldWrapper<string> readonly={readonly} {...props}>
+      {({ value = '' }) => (
+        <Input.TextInput
+          noAutoFill
+          disabled={!!readonly}
+          placeholder={placeholder}
+          value={value}
+          onBlur={onBlur}
+          onChange={handleChange}
+        />
+      )}
+    </FormFieldWrapper>
+  );
+};

package/src/components/Form/{custom/TupleInput.tsx → fields/TupleField.tsx}

@@ -5,39 +5,46 @@
 import React from 'react';
 
 import { Input } from '@dxos/react-ui';
-import { mx } from '@dxos/react-ui-theme';
+import { mx } from '@dxos/ui-theme';
 import { safeParseFloat } from '@dxos/util';
 
-import { InputHeader, type InputProps } from '../Input';
+import { type FormFieldComponentProps, FormFieldLabel } from '../FormFieldComponent';
 
 const gridCols = ['grid-cols-1', 'grid-cols-2', 'grid-cols-3', 'grid-cols-4'];
 
-export const TupleInput = ({
+export const TupleField = ({
   binding,
   type,
-  label,
   readonly,
+  label,
   getStatus,
   getValue,
   onValueChange,
   onBlur,
-}: InputProps & { binding: string[] }) => {
+}: FormFieldComponentProps<Record<string, number>> & {
+  binding: string[];
+}) => {
   const { status, error } = getStatus();
 
   // TODO(burdon): Generalize number/float/string, etc.
-  const values: Record<string, number> = getValue<Record<string, number>>() ?? {};
+  const values: Record<string, number> = getValue() ?? {};
 
   return (
     <Input.Root validationValence={status}>
-      <InputHeader error={error} label={label} />
-      <div className={mx('grid gap-2', gridCols[binding.length - 1])}>
+      <FormFieldLabel error={error} readonly={readonly} label={label} />
+      <div className={mx('grid gap-form-gap', gridCols[binding.length - 1])}>
         {binding.map((prop) => (
           <Input.TextInput
             key={prop}
             type='number'
             disabled={!!readonly}
             value={values[prop]}
-            onChange={(event) => onValueChange(type, { ...values, [prop]: safeParseFloat(event.target.value, 0) })}
+            onChange={(event) => {
+              onValueChange(type, {
+                ...values,
+                [prop]: safeParseFloat(event.target.value, 0),
+              });
+            }}
             onBlur={onBlur}
           />
         ))}

package/src/components/Form/fields/index.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './ArrayField';
+export * from './BooleanField';
+export * from './GeoPointField';
+export * from './MarkdownField';
+export * from './NumberField';
+export * from './RefField';
+export * from './SelectField';
+export * from './SelectOptionField';
+export * from './TextField';
+export * from './TextAreaField';
+export * from './TupleField';

package/src/components/Form/index.ts

@@ -2,8 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './custom';
-export * from './Defaults';
+export * from './fields';
+
 export * from './Form';
-export * from './FormContext';
-export * from './Input';
+export * from './FormFieldComponent';