@dxos/react-ui-form 0.9.0 → 0.9.1-staging.ee54ba693a

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

@@ -0,0 +1,328 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Option from 'effect/Option';
+import * as SchemaAST from 'effect/SchemaAST';
+import React, { type ReactNode, useCallback, useRef } from 'react';
+
+import { Annotation, Ref } from '@dxos/echo';
+import { useType as defaultUseType } from '@dxos/echo-react';
+import { SchemaEx } from '@dxos/effect';
+import { DXN } from '@dxos/keys';
+import { log } from '@dxos/log';
+import { useTranslation } from '@dxos/react-ui';
+import { OrderedList } from '@dxos/react-ui-list';
+import { mx } from '@dxos/ui-theme';
+import { arrayMove } from '@dxos/util';
+
+import { translationKey } from '#translations';
+import { type FormFieldStateProps } from '#types';
+
+import { useFormValues } from '../../../../../hooks';
+import { getFormProperties } from '../../../../../util';
+import { CompactIconButton, FormField, type FormFieldProps } from '../../FormField';
+import { FormFieldHeader } from '../../FormFieldHeader';
+
+// Synthetic id assigned to each row when rendering an ordered list. Plain form
+// values have no stable identity, so drag-and-drop (which requires a stable key
+// surviving the `onValuesChanged` round-trip) is given one here and kept in
+// lockstep with the array via the add/delete/move handlers.
+const DND_ID = '__dndId';
+
+type OrderedItem = {
+  [DND_ID]: string;
+  value: unknown;
+  index: number;
+};
+
+const isOrderedItem = (item: any): item is OrderedItem =>
+  !!item && typeof item === 'object' && typeof item[DND_ID] === 'string';
+
+const getOrderedId = (item: OrderedItem): string => item[DND_ID];
+
+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 = SchemaEx.getArrayElementType(type);
+  const { onValueChange } = inputProps;
+  const values = useFormValues(ArrayField.displayName, path, () => []);
+
+  // Order is meaningful and user-controllable -> render as a drag-to-reorder list.
+  const ordered = Annotation.FormOrderedAnnotation.getFromAst(type).pipe(Option.getOrElse(() => false));
+
+  // Owned-ref array (`FormCreateAnnotation`): "add" creates a new target object of the annotation's typename,
+  // and each row renders that target inline (no existing-object picker).
+  const { db, onCreate, getCreateDefaults, useType = defaultUseType } = props;
+  const createTypename = Annotation.FormCreateAnnotation.getFromAst(type).pipe(Option.getOrUndefined);
+  const createSchema = useType(db, createTypename ? DXN.make(createTypename) : undefined);
+  const createInline =
+    !!createTypename && !!elementType && Ref.isRefType(elementType) && !readonly && layout !== 'static';
+
+  // Synthetic identity map (see `DND_ID`). The counter only advances when the
+  // array grows; reconciliation here covers the initial mount and any external
+  // length change, while the handlers below keep ids aligned on mutation.
+  const idsRef = useRef<string[]>([]);
+  const counterRef = useRef(0);
+  const nextId = useCallback(() => `${DND_ID}-${counterRef.current++}`, []);
+
+  // Create a new owned target object and append its ref (see `createInline`).
+  const handleAddCreate = useCallback(async () => {
+    if (!createSchema || !onCreate) {
+      return;
+    }
+    // Let the container pre-populate the new object (e.g. a back-reference to the parent).
+    const defaults = getCreateDefaults?.({ jsonPath: SchemaEx.createJsonPath(path ?? []), schema: createSchema }) ?? {};
+    const created = await onCreate(createSchema, defaults);
+    if (!created) {
+      return;
+    }
+    idsRef.current.push(nextId());
+    onValueChange(type, [...(values ?? []), Ref.make(created)]);
+  }, [createSchema, onCreate, getCreateDefaults, onValueChange, type, path, values, nextId]);
+
+  const getDefaultObjectValue = (typeNode: SchemaAST.AST): any => {
+    const baseNode = SchemaEx.findNode(typeNode, SchemaEx.isDiscriminatedUnion);
+    const typeLiteral = baseNode
+      ? SchemaEx.getDiscriminatedType(baseNode, {})
+      : SchemaEx.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(() => {
+    let defaultValue;
+    try {
+      defaultValue =
+        elementType && SchemaEx.isNestedType(elementType)
+          ? getDefaultObjectValue(elementType)
+          : getDefaultValue(elementType);
+    } catch (err) {
+      // `getDefaultValue` throws on element types it can't seed (runs in this click handler, so an
+      // unguarded throw would be uncaught). Skip the add rather than crash the form.
+      log.catch(err);
+      return;
+    }
+    idsRef.current.push(nextId());
+    // `values` is `undefined` on first render for arrays whose parent path
+    // hasn't been materialised in the form values yet (e.g. `package.repos`
+    // when the form starts with no `package`). `useFormValues`'s default-
+    // value effect would eventually backfill it to `[]`, but until then the
+    // old `values && ...` guard silently swallowed the click. Treat a
+    // missing array as empty so Add always produces `[defaultValue]`.
+    onValueChange(type, [...(values ?? []), defaultValue]);
+  }, [onValueChange, type, elementType, values, nextId]);
+
+  const handleDelete = useCallback(
+    (idx: number) => {
+      idsRef.current.splice(idx, 1);
+      onValueChange(
+        type,
+        values?.filter((_, i) => i !== idx),
+      );
+    },
+    [onValueChange, type, values],
+  );
+
+  const handleMove = useCallback(
+    (fromIndex: number, toIndex: number) => {
+      const next = [...(values ?? [])];
+      arrayMove(next, fromIndex, toIndex);
+      arrayMove(idsRef.current, fromIndex, toIndex);
+      onValueChange(type, next);
+    },
+    [onValueChange, type, values],
+  );
+
+  if (!elementType || ((readonly || layout === 'static') && values && values.length < 1)) {
+    return null;
+  }
+
+  const renderItemAsObject = elementType && SchemaEx.isNestedType(elementType) && !Ref.isRefType(elementType);
+
+  // Object items: a recursively-rendered FormField (multiple sub-rows for the
+  // object's fields). Scalar items (refs, primitives): a single inline FormField.
+  const renderField = (index: number, isLast: boolean): ReactNode => {
+    const field = (
+      <FormField
+        {...props}
+        autoFocus={isLast}
+        type={elementType}
+        // Suppress the per-item header for object items and owned-ref items (both render their own
+        // sub-field labels). Scalar items (refs, primitives) take the array's resolved label (e.g. its
+        // `title` annotation, `Tags`) so inline-layout children (e.g. RefField) have a real label to use
+        // as a fallback placeholder, rather than re-deriving it from the raw array property name (`_tags`).
+        {...(renderItemAsObject || createInline ? { name: null } : { label })}
+        path={[...(path ?? []), index]}
+        readonly={readonly || layout === 'static'}
+        layout={renderItemAsObject ? (layout === 'static' ? 'static' : undefined) : 'inline'}
+        refInline={createInline || undefined}
+      />
+    );
+
+    // TODO(burdon): Hacky.
+    // An owned inline object form must establish its own column context: otherwise it inherits the parent
+    // form's `--dx-col` (center) placement and collapses into the array row's narrow second track.
+    return createInline ? (
+      <div role='none' className='w-full min-w-0 [--dx-col:auto]'>
+        {field}
+      </div>
+    ) : (
+      field
+    );
+  };
+
+  const header = (layout !== 'static' || (values && values.length > 0)) && (
+    <FormFieldHeader
+      label={label}
+      path={SchemaEx.createJsonPath(path ?? [])}
+      readonly={readonly}
+      add={
+        layout !== 'static'
+          ? { label: t('add-item.button'), onClick: createInline ? () => void handleAddCreate() : handleAdd }
+          : undefined
+      }
+    />
+  );
+
+  //
+  // Ordered (drag-to-reorder) list.
+  //
+
+  if (ordered && !readonly && layout !== 'static') {
+    // Reconcile synthetic ids with the current values (initial mount / external change).
+    const ids = idsRef.current;
+    const count = values?.length ?? 0;
+    while (ids.length < count) {
+      ids.push(nextId());
+    }
+    if (ids.length > count) {
+      ids.length = count;
+    }
+
+    const items: OrderedItem[] = (values ?? []).map((value, index) => ({ value, index, [DND_ID]: ids[index] }));
+
+    return (
+      <>
+        {header}
+        <OrderedList.Root<OrderedItem> items={items} isItem={isOrderedItem} getId={getOrderedId} onMove={handleMove}>
+          {({ items }) => (
+            <OrderedList.Content>
+              {items.map((item) => (
+                <OrderedList.Item<OrderedItem>
+                  key={getOrderedId(item)}
+                  id={getOrderedId(item)}
+                  item={item}
+                  classNames='grid grid-cols-[min-content_1fr_min-content] items-start gap-1 p-0 pb-1'
+                >
+                  <OrderedList.DragHandle />
+                  {renderField(item.index, item.index === items.length - 1)}
+                  <CompactIconButton
+                    icon='ph--x--regular'
+                    label={t('remove-item.button')}
+                    onClick={() => handleDelete(item.index)}
+                  />
+                </OrderedList.Item>
+              ))}
+            </OrderedList.Content>
+          )}
+        </OrderedList.Root>
+      </>
+    );
+  }
+
+  //
+  // Static list.
+  //
+
+  return (
+    <>
+      {header}
+      <div className='flex flex-col gap-2'>
+        {values?.map((_, index) => {
+          const isLast = index === values.length - 1;
+          return (
+            <div
+              key={index}
+              className={mx(
+                'grid grid-cols-[minmax(0,1fr)_min-content] gap-1',
+                renderItemAsObject || createInline ? 'items-start' : 'items-center',
+              )}
+            >
+              {renderField(index, isLast)}
+              {!readonly && layout !== 'static' && (
+                <CompactIconButton
+                  icon='ph--x--regular'
+                  label={t('remove-item.button')}
+                  onClick={() => handleDelete(index)}
+                />
+              )}
+            </div>
+          );
+        })}
+      </div>
+    </>
+  );
+};
+
+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;
+    }
+    case 'Suspend': {
+      return getDefaultValue(ast.f());
+    }
+    case 'Refinement': {
+      // Use minimum from JSON schema annotation (e.g. Schema.between(1, 31)) as the default
+      // so new array items start within the valid range.
+      const jsonSchema = Option.getOrUndefined(SchemaAST.getJSONSchemaAnnotation(ast));
+      if (jsonSchema != null && 'minimum' in jsonSchema && typeof jsonSchema.minimum === 'number') {
+        return jsonSchema.minimum;
+      }
+      return getDefaultValue(ast.from);
+    }
+    default: {
+      if (ast && SchemaEx.isNestedType(ast)) {
+        return {};
+      } else {
+        throw new Error(`Unsupported type: ${ast?._tag}`);
+      }
+    }
+  }
+};

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

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

package/src/components/Form/FormField/fields/AsyncSelectField/AsyncSelectField.tsx

@@ -0,0 +1,59 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useEffect, useMemo, useRef } from 'react';
+
+import { type AnyProperties } from '@dxos/echo/internal';
+
+import { type FormFieldRendererProps } from '#types';
+
+import { type OptionsLookup, type OptionsLookupEntry } from '../../../../../annotations';
+import { pickValues, useAsyncFieldEffect, useFormValues } from '../../../../../hooks';
+import { SelectField } from '../SelectField';
+
+export type AsyncSelectFieldProps = FormFieldRendererProps<string> & {
+  /** Loads the selectable options from the lookup's declared dependency fields. */
+  lookup: OptionsLookup;
+};
+
+/**
+ * A select whose options are loaded dynamically (debounced) from the fields the lookup declares in its
+ * `deps`, via an {@link Annotation.OptionsLookup}. Re-runs only when one of those values changes.
+ * Auto-selects the sole option when exactly one resolves and nothing is chosen yet.
+ */
+export const AsyncSelectField = ({ lookup, ...fieldProps }: AsyncSelectFieldProps) => {
+  const values = useFormValues<AnyProperties>(AsyncSelectField.displayName);
+  const subset = useMemo(() => pickValues(values, lookup.deps), [values, lookup.deps]);
+  const key = useMemo(() => JSON.stringify(subset), [subset]);
+  const { loading, data } = useAsyncFieldEffect<readonly OptionsLookupEntry[]>(() => lookup.load(subset), key);
+  const options = data ?? [];
+
+  const { type, placeholder } = fieldProps;
+  const current = fieldProps.getValue();
+  // `onValueChange` changes identity on every edit; hold it in a ref so auto-select depends only on the
+  // resolved `data` and current value (avoids an effect-refire loop).
+  const onValueChangeRef = useRef(fieldProps.onValueChange);
+  onValueChangeRef.current = fieldProps.onValueChange;
+  // Track which `data` reference has already been auto-selected so clearing the field does not trigger
+  // repeated re-selection of the same single option.
+  const autoSelectedDataRef = useRef<typeof data>(undefined);
+  useEffect(() => {
+    if ((current == null || current === '') && data?.length === 1 && data !== autoSelectedDataRef.current) {
+      autoSelectedDataRef.current = data;
+      onValueChangeRef.current(type, data[0].value);
+    }
+  }, [current, data, type]);
+
+  const resolvedPlaceholder = loading ? 'Loading…' : options.length === 0 ? 'No options available' : placeholder;
+
+  return (
+    <SelectField
+      {...fieldProps}
+      placeholder={resolvedPlaceholder}
+      options={options.map(({ value, label, secondaryLabel, icon }) => ({ value, label, secondaryLabel, icon }))}
+    />
+  );
+};
+
+AsyncSelectField.displayName = 'Form.AsyncSelectField';

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

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

package/src/components/Form/FormField/fields/AutofillField/AutofillField.tsx

@@ -0,0 +1,67 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useEffect, useMemo, useRef } from 'react';
+
+import { type AnyProperties } from '@dxos/echo/internal';
+
+import { type FormFieldRendererProps } from '#types';
+
+import { type Autofill } from '../../../../../annotations';
+import { pickValues, useAsyncFieldEffect, useFormValues } from '../../../../../hooks';
+import { TextField } from '../TextField';
+
+export type AutofillFieldProps = FormFieldRendererProps<string> & {
+  /** Derives this field's value from the autofill's declared dependency fields (e.g. a sibling URL). */
+  autofill: Autofill;
+};
+
+/**
+ * An editable text field that pre-fills its value (debounced) from the fields the autofill declares in
+ * its `deps`, via an {@link Autofill}. Re-runs only when one of those values changes. The
+ * derived value is written only while the user has not typed their own (the field is empty or still
+ * holds the last auto-filled value), so a manual edit is never clobbered.
+ */
+export const AutofillField = ({ autofill, ...fieldProps }: AutofillFieldProps) => {
+  const values = useFormValues<AnyProperties>(AutofillField.displayName);
+  const subset = useMemo(() => pickValues(values, autofill.deps), [values, autofill.deps]);
+  const key = useMemo(() => JSON.stringify(subset), [subset]);
+  const { data } = useAsyncFieldEffect<string | undefined>(() => autofill.derive(subset), key);
+
+  // Read field state through refs so the write effect depends only on the derived `data` — `getValue`
+  // and `onValueChange` change identity on every value edit, and depending on them would re-fire the
+  // effect after it writes, re-applying the same value in an infinite loop.
+  const { type } = fieldProps;
+  const getValueRef = useRef(fieldProps.getValue);
+  getValueRef.current = fieldProps.getValue;
+  const onValueChangeRef = useRef(fieldProps.onValueChange);
+  onValueChangeRef.current = fieldProps.onValueChange;
+  const lastFilledRef = useRef<string | undefined>(undefined);
+
+  useEffect(() => {
+    const current = getValueRef.current();
+    if (typeof data !== 'string' || data.length === 0) {
+      // Derivation stopped returning a value — clear the field if it still holds our last fill so stale
+      // auto-filled text doesn't persist after the source field is cleared.
+      if (lastFilledRef.current != null && current === lastFilledRef.current) {
+        lastFilledRef.current = undefined;
+        onValueChangeRef.current(type, '');
+      }
+      return;
+    }
+    if (current === data) {
+      lastFilledRef.current = data;
+      return;
+    }
+    // Only fill while the user has not typed their own value (empty, or still our last fill).
+    if (current == null || current === '' || current === lastFilledRef.current) {
+      lastFilledRef.current = data;
+      onValueChangeRef.current(type, data);
+    }
+  }, [data, type]);
+
+  return <TextField {...fieldProps} />;
+};
+
+AutofillField.displayName = 'Form.AutofillField';

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

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

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

@@ -0,0 +1,52 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Schema from 'effect/Schema';
+import React, { useState } from 'react';
+
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '#translations';
+
+import { TestLayout } from '../../../../../testing';
+import { Form } from '../../../Form';
+
+const schema = Schema.Struct({
+  active: Schema.Boolean.annotations({ title: 'Active' }),
+}).pipe(Schema.mutable);
+
+type Values = Schema.Schema.Type<typeof schema>;
+
+const DefaultStory = () => {
+  const [values, setValues] = useState<Values>({ active: true });
+  return (
+    <TestLayout json={values}>
+      <Form.Root
+        schema={schema}
+        values={values}
+        onValuesChanged={(values) => setValues((prev) => ({ ...prev, ...values }))}
+      >
+        <Form.Viewport>
+          <Form.Content>
+            <Form.FieldSet />
+          </Form.Content>
+        </Form.Viewport>
+      </Form.Root>
+    </TestLayout>
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-form/FormField/BooleanField',
+  render: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
+  parameters: { layout: 'fullscreen', translations },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

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

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

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

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

package/src/components/Form/FormField/fields/ComboboxField/ComboboxField.tsx

@@ -0,0 +1,104 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useCallback, useMemo, useState } from 'react';
+
+import { type AnyProperties } from '@dxos/echo/internal';
+import { Combobox } from '@dxos/react-ui-list';
+
+import { type FormFieldRendererProps } from '#types';
+
+import { type OptionsLookup, type OptionsLookupEntry } from '../../../../../annotations';
+import { pickValues, useAsyncFieldEffect, useFormValues } from '../../../../../hooks';
+import { FormRow } from '../../FormRow';
+
+export type ComboboxFieldProps = FormFieldRendererProps<string> & {
+  /** Loads suggestions from the lookup's declared dependency fields (typically the field's own value). */
+  lookup: OptionsLookup;
+};
+
+/**
+ * An editable combobox built on the shared {@link Combobox} primitive (trigger + popover search list,
+ * the same family as `ObjectPicker`/`SearchList`). The trigger shows the current value; opening it reveals
+ * a search input that loads suggestions (debounced) via an {@link OptionsLookup} and filters
+ * them as you type. The literal typed text is offered as a fallback option at the bottom (deduped), so a
+ * value not among the suggestions can still be selected. No options are shown until something is typed.
+ */
+export const ComboboxField = ({ lookup, type, readonly, placeholder, onValueChange, ...props }: ComboboxFieldProps) => {
+  const values = useFormValues<AnyProperties>(ComboboxField.displayName);
+  const ownKey = props.jsonPath;
+  const [query, setQuery] = useState('');
+
+  // When the combobox searches on its own field (its name is among `deps`), feed the live query to the
+  // loader so remote suggestions track typing; otherwise the loader reads the committed sibling values.
+  const lookupValues = useMemo(() => {
+    const subset = pickValues(values, lookup.deps);
+    if (ownKey && lookup.deps.includes(ownKey)) {
+      subset[ownKey] = query;
+    }
+    return subset;
+  }, [values, lookup.deps, ownKey, query]);
+  const key = useMemo(() => JSON.stringify(lookupValues), [lookupValues]);
+  const { data } = useAsyncFieldEffect<readonly OptionsLookupEntry[]>(() => lookup.load(lookupValues), key);
+
+  const trimmed = query.trim();
+  const normalized = trimmed.toLowerCase();
+  // No options until something is typed; then filter the loaded suggestions by the input text.
+  const results = useMemo(
+    () =>
+      normalized.length === 0
+        ? []
+        : (data ?? []).filter((option) => (option.label ?? option.value).toLowerCase().includes(normalized)),
+    [data, normalized],
+  );
+  const hasExact = results.some((option) => option.value === trimmed);
+
+  const handleValueChange = useCallback((next: string) => onValueChange(type, next), [onValueChange, type]);
+  const handleOpenChange = useCallback((open: boolean) => {
+    if (!open) {
+      setQuery('');
+    }
+  }, []);
+
+  return (
+    <FormRow<string>
+      readonly={readonly}
+      renderStatic={(value) => <p className='truncate min-w-0'>{value ?? ''}</p>}
+      {...props}
+    >
+      {({ value = '' }) => (
+        <Combobox.Root
+          value={value}
+          onValueChange={handleValueChange}
+          onOpenChange={handleOpenChange}
+          placeholder={placeholder}
+        >
+          {/* Full-width trigger (default renders value/placeholder + caret) to match the other fields. */}
+          <Combobox.Trigger disabled={!!readonly} classNames='w-full' />
+          <Combobox.Portal>
+            {/* Keep the first result highlighted as the list changes while typing. */}
+            <Combobox.Content resetSelectionOnChange>
+              <Combobox.Input autoFocus value={query} onValueChange={setQuery} placeholder={placeholder} />
+              <Combobox.List>
+                {results.map((option) => (
+                  <Combobox.Item
+                    key={option.value}
+                    value={option.value}
+                    label={option.label ?? option.value}
+                    suffix={option.secondaryLabel}
+                  />
+                ))}
+                {/* The literal typed text as a fallback option at the bottom, unless a suggestion already is it. */}
+                {normalized.length > 0 && !hasExact && <Combobox.Item value={trimmed} label={trimmed} />}
+              </Combobox.List>
+              <Combobox.Arrow />
+            </Combobox.Content>
+          </Combobox.Portal>
+        </Combobox.Root>
+      )}
+    </FormRow>
+  );
+};
+
+ComboboxField.displayName = 'Form.ComboboxField';

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

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