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

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

@@ -11,23 +11,40 @@ import { safeParseFloat } from '@dxos/util';
 
 import { type FormFieldRendererProps } from '#types';
 
-import { FormFieldWrapper } from '../../FormFieldWrapper';
+import { FormRow } from '../../FormRow';
 
 /**
- * Extracts numeric `minimum`/`maximum` bounds from a Refinement AST's JSON schema annotation
- * (e.g. produced by Schema.between). Returns undefined when no bounds are declared.
+ * Extracts numeric constraints (`minimum`/`maximum` bounds and whether the value must be an integer)
+ * by walking the chain of Refinement ASTs and reading each one's JSON schema annotation (e.g. produced
+ * by `Schema.between` / `Schema.int`). Returns empty constraints when none are declared.
  */
-const getRefinementBounds = (ast: SchemaAST.AST): { min?: number; max?: number } => {
-  if (!SchemaAST.isRefinement(ast)) {
-    return {};
-  }
-  const jsonSchema = Option.getOrUndefined(SchemaAST.getJSONSchemaAnnotation(ast));
-  if (jsonSchema == null) {
-    return {};
+export const getNumericConstraints = (ast: SchemaAST.AST): { min?: number; max?: number; integer: boolean } => {
+  let node: SchemaAST.AST | undefined = ast;
+  let min: number | undefined;
+  let max: number | undefined;
+  let integer = false;
+  // Nested refinements (e.g. `Schema.int()` + `Schema.between()`) each carry their own JSON schema
+  // fragment, so accumulate across the chain rather than reading only the outermost node.
+  while (node && SchemaAST.isRefinement(node)) {
+    const jsonSchema = Option.getOrUndefined(SchemaAST.getJSONSchemaAnnotation(node));
+    if (jsonSchema != null) {
+      // Stacked refinements intersect: keep the strictest bound (largest min, smallest max).
+      if ('minimum' in jsonSchema && typeof jsonSchema.minimum === 'number') {
+        min = min === undefined ? jsonSchema.minimum : Math.max(min, jsonSchema.minimum);
+      }
+      if ('maximum' in jsonSchema && typeof jsonSchema.maximum === 'number') {
+        max = max === undefined ? jsonSchema.maximum : Math.min(max, jsonSchema.maximum);
+      }
+      if (
+        ('type' in jsonSchema && jsonSchema.type === 'integer') ||
+        ('multipleOf' in jsonSchema && jsonSchema.multipleOf === 1)
+      ) {
+        integer = true;
+      }
+    }
+    node = node.from;
   }
-  const min = 'minimum' in jsonSchema && typeof jsonSchema.minimum === 'number' ? jsonSchema.minimum : undefined;
-  const max = 'maximum' in jsonSchema && typeof jsonSchema.maximum === 'number' ? jsonSchema.maximum : undefined;
-  return { min, max };
+  return { min, max, integer };
 };
 
 export const NumberField = ({
@@ -39,7 +56,23 @@ export const NumberField = ({
   onBlur,
   ...props
 }: FormFieldRendererProps<number>) => {
-  const { min, max } = getRefinementBounds(type);
+  const { min, max, integer } = getNumericConstraints(type);
+
+  // Clamp to the declared bounds (and round when integer) so the committed value respects the schema's
+  // natural limits — `<input type="number">`'s min/max only constrain the spinner, not typed input.
+  const clamp = useCallback(
+    (n: number) => {
+      let value = integer ? Math.round(n) : n;
+      if (min !== undefined) {
+        value = Math.max(min, value);
+      }
+      if (max !== undefined) {
+        value = Math.min(max, value);
+      }
+      return value;
+    },
+    [min, max, integer],
+  );
 
   // Track raw string input so the user can clear the field before typing a new number.
   // We only commit to onValueChange when the raw string parses to a valid number.
@@ -64,26 +97,31 @@ export const NumberField = ({
       setRaw(value);
       const parsed = safeParseFloat(value);
       if (parsed !== undefined) {
-        onValueChange(type, parsed);
+        onValueChange(type, clamp(parsed));
       }
     },
-    [type, onValueChange],
+    [type, onValueChange, clamp],
   );
 
   const handleBlur = useCallback(
     (event: React.FocusEvent<HTMLElement>) => {
-      // If the field was left empty or invalid, reset to the last committed value.
-      if (safeParseFloat(raw) === undefined) {
+      const parsed = safeParseFloat(raw);
+      if (parsed === undefined) {
+        // The field was left empty or invalid; reset to the last committed value.
         const committed = getValue();
         setRaw(committed !== undefined ? String(committed) : '');
+      } else {
+        // Reflect the clamped value even when it equals the previously committed one (so `externalValue`
+        // doesn't change), otherwise the input keeps showing the out-of-range text the user typed.
+        setRaw(String(clamp(parsed)));
       }
       onBlur(event);
     },
-    [raw, getValue, onBlur],
+    [raw, getValue, onBlur, clamp],
   );
 
   return (
-    <FormFieldWrapper<number> readonly={readonly} getValue={getValue} {...props}>
+    <FormRow<number> readonly={readonly} getValue={getValue} {...props}>
       {() => (
         <Input.TextInput
           type='number'
@@ -92,10 +130,11 @@ export const NumberField = ({
           value={raw}
           min={min}
           max={max}
+          step={integer ? 1 : undefined}
           onChange={handleChange}
           onBlur={handleBlur}
         />
       )}
-    </FormFieldWrapper>
+    </FormRow>
   );
 };

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

@@ -0,0 +1,53 @@
+//
+// 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 { Format } from '@dxos/echo';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '#translations';
+
+import { TestLayout } from '../../../../../testing';
+import { Form } from '../../../Form';
+
+const schema = Schema.Struct({
+  name: Schema.String.annotations({ title: 'Name' }).pipe(Format.FormatAnnotation.set(Format.TypeFormat.Password)),
+}).pipe(Schema.mutable);
+
+type Values = Schema.Schema.Type<typeof schema>;
+
+const DefaultStory = () => {
+  const [values, setValues] = useState<Values>({ name: 'Alice' });
+  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/PasswordField',
+  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/PasswordField/PasswordField.tsx

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

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

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

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

@@ -10,13 +10,14 @@ import { useType as defaultUseType } from '@dxos/echo-react';
 import { ReferenceAnnotationId, type ReferenceAnnotationValue } from '@dxos/echo/Annotation';
 import { SchemaEx } from '@dxos/effect';
 import { DXN, URI } from '@dxos/keys';
-import { Button, Icon, Input, useTranslation } from '@dxos/react-ui';
+import { IconButton, Input, useTranslation } from '@dxos/react-ui';
 
 import { translationKey } from '#translations';
 
 import { omitId } from '../../../../../util';
-import { FormContent, FormFieldSet, FormRoot } from '../../../FormControls';
-import { FormFieldLabel } from '../../FormFieldWrapper';
+import { FormContent, FormFieldSetController, FormRoot } from '../../../FormControls';
+import { FormFieldLabel } from '../../FormRow';
+import { presentationFor } from '../../presentation';
 import { type RefFieldProps } from './RefField';
 
 /**
@@ -34,7 +35,8 @@ export const InlineRefField = (props: RefFieldProps) => {
     readonly,
     label,
     jsonPath,
-    layout,
+    presentation,
+    required,
     db,
     getValue,
     onValueChange,
@@ -42,6 +44,7 @@ export const InlineRefField = (props: RefFieldProps) => {
     useType = defaultUseType,
   } = props;
   const { t } = useTranslation(translationKey);
+  const resolved = presentationFor(presentation);
 
   const reference = getValue() as Ref.Ref<any> | undefined;
   const typename = useMemo(
@@ -67,16 +70,19 @@ export const InlineRefField = (props: RefFieldProps) => {
 
   return (
     <Input.Root>
-      {layout !== 'inline' && <FormFieldLabel readonly={readonly} label={label} path={jsonPath} />}
+      {resolved.showLabel && <FormFieldLabel readonly={readonly} required={required} label={label} path={jsonPath} />}
       {reference ? (
         <InlineForm reference={reference} db={db} readonly={readonly} useType={useType} />
       ) : (
         !readonly &&
         onCreate && (
-          <Button classNames='w-full gap-form-gap' disabled={!createType || !db} onClick={() => void handleCreate()}>
-            <Icon icon='ph--plus--regular' size={4} />
-            <span>{label || t('ref-field.placeholder')}</span>
-          </Button>
+          <IconButton
+            classNames='w-full gap-form-gap'
+            disabled={!createType || !db}
+            icon='ph--plus--regular'
+            label={label || t('ref-field.placeholder')}
+            onClick={() => void handleCreate()}
+          />
         )
       )}
     </Input.Root>
@@ -132,7 +138,7 @@ const InlineForm = ({ reference, db, readonly, useType = defaultUseType }: Inlin
   return (
     <FormRoot db={db} schema={formSchema} defaultValues={defaultValues as any} onValuesChanged={handleChange}>
       <FormContent>
-        <FormFieldSet collapsible readonly={readonly} />
+        <FormFieldSetController collapsible readonly={readonly} />
       </FormContent>
     </FormRoot>
   );

package/src/components/Form/FormField/fields/RefField/RefField.test.ts

@@ -29,6 +29,14 @@ describe('findRefOption', () => {
     expect(findRefOption({ '/': LOCAL }, options)?.label).toBe('Target');
   });
 
+  test('matches a keyed-entity ref by direct URI equality', ({ expect }) => {
+    // Keyed/registry entities (skills, operations) are referenced by a named DXN with no parseable
+    // EID; the option id and the ref uri are the same named URI, so they match by direct equality.
+    const named = 'dxn:type:example.com/skill/research';
+    const keyedOptions: RefOption[] = [...options, { id: named, label: 'Research' }];
+    expect(findRefOption({ '/': named }, keyedOptions)?.label).toBe('Research');
+  });
+
   test('returns undefined for a non-ref value', ({ expect }) => {
     expect(findRefOption('not-a-ref', options)).toBeUndefined();
     expect(findRefOption(undefined, options)).toBeUndefined();

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

@@ -6,7 +6,7 @@ import React, { useCallback, useMemo, useState } from 'react';
 
 import '@dxos/lit-ui/dx-tag-picker.pcss';
 import { Entity, Filter, Obj, Query, Ref, Scope, Type } from '@dxos/echo';
-import { useQuery, useType as defaultUseType } from '@dxos/echo-react';
+import { useType as defaultUseType, useQuery } from '@dxos/echo-react';
 import { ANY_OBJECT_TYPENAME, ReferenceAnnotationId, type ReferenceAnnotationValue } from '@dxos/echo/internal';
 import { SchemaEx } from '@dxos/effect';
 import { DXN, EID, URI } from '@dxos/keys';
@@ -19,7 +19,8 @@ import { type CreateOptions, type FormFieldRendererProps, type RefFieldDataProps
 
 import { omitHiddenFormFields, omitId } from '../../../../../util';
 import { ObjectPicker } from '../../../../ObjectPicker';
-import { FormFieldLabel } from '../../FormFieldWrapper';
+import { FormFieldLabel } from '../../FormRow';
+import { presentationFor } from '../../presentation';
 
 // TODO(burdon): Factor out.
 const isRefSnapshot = (val: any): val is { '/': string } => {
@@ -40,7 +41,14 @@ export const findRefOption = (value: unknown, options: RefOption[]): RefOption |
   if (!isRef && !isRefSnapshot(value)) {
     return undefined;
   }
-  const valueEid = EID.tryParse(isRef ? value.uri : value['/']);
+  const valueUri = isRef ? value.uri : value['/'];
+  // Keyed/registry entities (skills, operations) are referenced by a named DXN rather than an
+  // entity-id, so they carry no parseable EID; match those by direct URI equality against the option id.
+  const directMatch = options.find((option) => option.id === valueUri);
+  if (directMatch) {
+    return directMatch;
+  }
+  const valueEid = EID.tryParse(valueUri);
   if (!valueEid) {
     return undefined;
   }
@@ -86,7 +94,7 @@ const defaultUseResults: NonNullable<RefFieldProps['useResults']> = (db, typenam
       : typename === ANY_OBJECT_TYPENAME
         ? // Untyped refs show space objects only; the registry is too broad for "any".
           Query.select(Filter.everything())
-        : // Include registry scope so keyed entities (blueprints, operations) appear as options.
+        : // Include registry scope so keyed entities (skills, operations) appear as options.
           Query.select(Filter.type(DXN.make(typename))).from(Scope.space(), Scope.registry()),
   );
 
@@ -99,7 +107,8 @@ export const RefField = (props: RefFieldProps) => {
     label,
     jsonPath,
     placeholder,
-    layout,
+    presentation,
+    required,
     getStatus,
     getValue,
     createOptionLabel,
@@ -111,10 +120,12 @@ export const RefField = (props: RefFieldProps) => {
     useResults = defaultUseResults,
     getOptions = defaultGetOptions,
     onCreate,
+    resolveCreateEntry,
     onValueChange,
   } = props;
   const { t } = useTranslation(translationKey);
   const { status, error } = getStatus();
+  const resolved = presentationFor(presentation);
 
   const typename = useMemo(
     () => (type ? SchemaEx.findAnnotation<ReferenceAnnotationValue>(type, ReferenceAnnotationId)?.typename : undefined),
@@ -145,24 +156,31 @@ export const RefField = (props: RefFieldProps) => {
   const selectedIds = useMemo(() => (item ? [item.id] : []), [item]);
   const createSchema = useType(db, typename && typename !== ANY_OBJECT_TYPENAME ? DXN.make(typename) : undefined);
 
+  // Per-typename override supplied by the caller (e.g. SpaceCapabilities.CreateObjectEntry).
+  const createEntry = typename ? resolveCreateEntry?.(typename) : undefined;
+
   // 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));
+      // 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.
+      if (createEntry?.createObject && db) {
+        const newObject = await createEntry.createObject(values, db);
+        if (newObject) {
+          onValueChange(type, Ref.make(newObject));
+        }
+      } else if (createSchema && onCreate) {
+        const newObject = await onCreate(createSchema, values);
+        if (newObject) {
+          onValueChange(type, Ref.make(newObject));
+        }
       }
       setOpen(false);
     },
-    [createSchema, onCreate, type, onValueChange],
+    [createEntry, db, createSchema, onCreate, type, onValueChange],
   );
 
   const handleUpdate = useCallback(
@@ -185,13 +203,15 @@ export const RefField = (props: RefFieldProps) => {
     [item, handleUpdate],
   );
 
-  if (!typename || ((readonly || layout === 'static') && !item)) {
+  if (!typename || ((readonly || resolved.isStatic) && !item)) {
     return null;
   }
 
   return (
     <Input.Root validationValence={status}>
-      {layout !== 'inline' && <FormFieldLabel error={error} readonly={readonly} label={label} path={jsonPath} />}
+      {resolved.showLabel && (
+        <FormFieldLabel error={error} readonly={readonly} required={required} label={label} path={jsonPath} />
+      )}
       <div>
         {readonly ? (
           !item ? (
@@ -226,22 +246,29 @@ export const RefField = (props: RefFieldProps) => {
                 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(Type.getSchema(createSchema)))}
+                // Prefer the plugin-registered inputSchema; fall back to stripping hidden fields
+                // (`FormInputAnnotation.set(false)`) from the raw ECHO type schema so the form's
+                // validator doesn't reject required-but-hidden fields such as backing-object refs
+                // supplied by a `FactoryAnnotation`.
+                createSchema={
+                  createEntry?.inputSchema ??
+                  (createSchema && omitHiddenFormFields(omitId(Type.getSchema(createSchema))))
+                }
                 createOptionLabel={createOptionLabel}
                 createOptionIcon={createOptionIcon}
                 createInitialValuePath={createInitialValuePath}
                 createFieldMap={createFieldMap}
-                onCreate={handleCreate}
+                // Offer inline create when the caller wired a handler OR a plugin-registered
+                // createObject override is available. A resolvable `createSchema` alone is not
+                // enough (e.g. operation refs, whose objects can't be created ad hoc).
+                onCreate={onCreate || createEntry?.createObject ? handleCreate : undefined}
                 onSelect={handleSelect}
               />
             </ObjectPicker.Portal>
           </ObjectPicker.Root>
         )}
       </div>
-      {layout === 'full' && <Input.DescriptionAndValidation>{error}</Input.DescriptionAndValidation>}
+      {resolved.showError && <Input.DescriptionAndValidation>{error}</Input.DescriptionAndValidation>}
     </Input.Root>
   );
 };

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

@@ -4,71 +4,59 @@
 
 import React, { useCallback } from 'react';
 
-import { Icon, Input, Select, type SelectRootProps } from '@dxos/react-ui';
+import { invariant } from '@dxos/invariant';
+import { Icon, Select, type SelectRootProps } from '@dxos/react-ui';
 import { getStyles } from '@dxos/ui-theme';
 
-import { type FormFieldRendererProps } from '#types';
+import { type FormFieldRenderer, type FormFieldRendererProps } from '#types';
 
-import { FormFieldLabel } from '../../FormFieldWrapper';
+import { FormRow } from '../../FormRow';
 
 export type SelectFieldOptions = FormFieldRendererProps & {
   options?: Array<{ value: string | number; label?: string; secondaryLabel?: string; icon?: string; iconHue?: string }>;
 };
 
-export const SelectField = ({
-  type,
-  readonly,
-  label,
-  jsonPath,
-  layout,
-  placeholder,
-  options,
-  getStatus,
-  getValue,
-  onValueChange,
-}: SelectFieldOptions) => {
-  const { status, error } = getStatus();
-  const value = getValue() as string | undefined;
-
+export const SelectField = ({ type, readonly, placeholder, options, onValueChange, ...props }: SelectFieldOptions) => {
   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} path={jsonPath} />}
-      {layout === 'static' ? (
-        <p>{options?.find(({ value: optionValue }) => optionValue === value)?.label ?? String(value)}</p>
-      ) : (
+    <FormRow<string>
+      readonly={readonly}
+      renderStatic={(value) => (
+        <p className='truncate min-w-0'>
+          {options?.find(({ value: optionValue }) => optionValue === value)?.label ?? String(value)}
+        </p>
+      )}
+      {...props}
+    >
+      {({ value }) => (
         <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, secondaryLabel, icon, iconHue }) => (
-                  // NOTE: Numeric values are converted to and from strings.
-                  <Select.Option key={String(value)} value={String(value)}>
-                    <span className='flex items-center flex-row gap-2'>
-                      {icon && <Icon icon={icon} classNames={getIconHueStyles(iconHue)} />}
-                      {label ?? String(value)}
-                      {secondaryLabel && <span className='text-subdued text-xs'>{secondaryLabel}</span>}
-                    </span>
-                  </Select.Option>
-                ))}
-              </Select.Viewport>
-              <Select.Arrow />
-            </Select.Content>
-          </Select.Portal>
+          {options?.length !== 0 && (
+            <Select.Portal>
+              <Select.Content>
+                <Select.Viewport>
+                  {options?.map(({ value, label, secondaryLabel, icon, iconHue }) => (
+                    // NOTE: Numeric values are converted to and from strings.
+                    <Select.Option key={String(value)} value={String(value)}>
+                      <span className='flex items-center flex-row gap-2'>
+                        {icon && <Icon icon={icon} classNames={getIconHueStyles(iconHue)} />}
+                        {label ?? String(value)}
+                        {secondaryLabel && <span className='text-subdued text-xs'>{secondaryLabel}</span>}
+                      </span>
+                    </Select.Option>
+                  ))}
+                </Select.Viewport>
+                <Select.Arrow />
+              </Select.Content>
+            </Select.Portal>
+          )}
         </Select.Root>
       )}
-      {layout === 'full' && <Input.DescriptionAndValidation>{error}</Input.DescriptionAndValidation>}
-    </Input.Root>
+    </FormRow>
   );
 };
 
@@ -77,3 +65,72 @@ const getIconHueStyles = (iconHue?: string): string | undefined => {
 
   return styles?.fg;
 };
+
+export type SelectFieldOption = {
+  value: string;
+  label?: string;
+};
+
+export type CreateSelectFieldOptions = {
+  /** Options to display. Strings are used as both value and label. */
+  options: ReadonlyArray<string | SelectFieldOption>;
+  /** Label for the sentinel option that maps to `undefined`. Defaults to `'Default'`. Pass `null` to omit. */
+  defaultLabel?: string | null;
+};
+
+/**
+ * Factory for a `fieldMap` entry (keyed by JSON path) that renders a Select over a fixed list of
+ * options, with an optional sentinel mapping to `undefined`. Use for fields whose choices come from a
+ * runtime list rather than the schema (e.g. available model ids).
+ */
+export const createSelectField = ({
+  options,
+  defaultLabel = 'Default',
+}: CreateSelectFieldOptions): FormFieldRenderer => {
+  const normalized = options.map((option) => (typeof option === 'string' ? { value: option, label: option } : option));
+  const hasDefault = defaultLabel !== null;
+  // The sentinel maps to `undefined`. Radix forbids an empty-string `Select.Item` value, so use a
+  // non-empty placeholder; reserved (a real option with this value would be unrepresentable).
+  const sentinel = '__default__';
+  invariant(
+    !normalized.some((option) => option.value === sentinel),
+    `createSelectField: option value '${sentinel}' is reserved.`,
+  );
+
+  return ({ type, readonly, onValueChange, ...props }: FormFieldRendererProps<string | undefined>) => (
+    <FormRow<string>
+      readonly={readonly}
+      renderStatic={(value) => (
+        <p className='truncate min-w-0'>
+          {normalized.find((option) => option.value === value)?.label ?? String(value ?? '')}
+        </p>
+      )}
+      {...props}
+    >
+      {({ value }) => (
+        <Select.Root
+          disabled={!!readonly}
+          value={value ?? sentinel}
+          onValueChange={(next) => onValueChange(type, hasDefault && next === sentinel ? undefined : next)}
+        >
+          <Select.TriggerButton classNames='w-full' disabled={!!readonly} />
+          {normalized.length > 0 && (
+            <Select.Portal>
+              <Select.Content>
+                <Select.Viewport>
+                  {hasDefault && <Select.Option value={sentinel}>{defaultLabel}</Select.Option>}
+                  {normalized.map((option) => (
+                    <Select.Option key={option.value} value={option.value}>
+                      {option.label ?? option.value}
+                    </Select.Option>
+                  ))}
+                </Select.Viewport>
+                <Select.Arrow />
+              </Select.Content>
+            </Select.Portal>
+          )}
+        </Select.Root>
+      )}
+    </FormRow>
+  );
+};