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

package/src/components/Form/FormField/fields/SelectField/SelectField.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 { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '#translations';
+
+import { TestLayout } from '../../../../../testing';
+import { Form } from '../../../Form';
+
+// A literal union auto-dispatches to SelectField.
+const schema = Schema.Struct({
+  status: Schema.Literal('active', 'inactive', 'archived').annotations({ title: 'Status' }),
+}).pipe(Schema.mutable);
+
+type Values = Schema.Schema.Type<typeof schema>;
+
+const DefaultStory = () => {
+  const [values, setValues] = useState<Values>({ status: 'active' });
+  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/SelectField',
+  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/SelectField/SelectField.tsx

@@ -0,0 +1,136 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React, { useCallback } from 'react';
+
+import { invariant } from '@dxos/invariant';
+import { Icon, Select, type SelectRootProps } from '@dxos/react-ui';
+import { getStyles } from '@dxos/ui-theme';
+
+import { type FormFieldRenderer, type FormFieldRendererProps } from '#types';
+
+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, placeholder, options, onValueChange, ...props }: SelectFieldOptions) => {
+  const handleValueChange = useCallback<NonNullable<SelectRootProps['onValueChange']>>(
+    (value) => onValueChange(type, value),
+    [type, onValueChange],
+  );
+
+  return (
+    <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}>
+          <Select.TriggerButton classNames='w-full' disabled={!!readonly} placeholder={placeholder} />
+          {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>
+      )}
+    </FormRow>
+  );
+};
+
+const getIconHueStyles = (iconHue?: string): string | undefined => {
+  const styles = iconHue ? getStyles(iconHue) : 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>
+  );
+};

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

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

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

@@ -11,11 +11,11 @@ import { withLayout, withTheme } from '@dxos/react-ui/testing';
 
 import { translations } from '#translations';
 
-import { TestLayout } from '../../testing';
-import { Form } from '../Form';
+import { TestLayout } from '../../../../../testing';
+import { Form } from '../../../Form';
 import { SelectOptionField } from './SelectOptionField';
 
-const schema = Schema.Struct({
+const TestSchema = Schema.Struct({
   options: Schema.Array(SelectOption).pipe(Schema.mutable),
 }).pipe(Schema.mutable);
 
@@ -32,7 +32,7 @@ const DefaultStory = () => {
   return (
     <TestLayout>
       <Form.Root
-        schema={schema}
+        schema={TestSchema}
         values={values}
         fieldMap={{ options: SelectOptionField }}
         onSave={(values) => setValues(values)}
@@ -49,7 +49,7 @@ const DefaultStory = () => {
 };
 
 const meta = {
-  title: 'ui/react-ui-form/SelectOptionField',
+  title: 'ui/react-ui-form/FormField/SelectOptionField',
   component: SelectOptionField as any,
   render: DefaultStory,
   decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],

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

@@ -6,14 +6,15 @@ import React, { type ChangeEvent, type KeyboardEvent, useCallback, useEffect, us
 
 import { type SelectOption } from '@dxos/echo/Format';
 import { PublicKey } from '@dxos/keys';
-import { type ChromaticPalette, IconButton, Input, Tag, useTranslation } from '@dxos/react-ui';
-import { List } from '@dxos/react-ui-list';
+import { type ChromaticPalette, IconButton, Input, Tag, ToggleIconButton, useTranslation } from '@dxos/react-ui';
+import { OrderedList } from '@dxos/react-ui-list';
 import { HuePicker } from '@dxos/react-ui-pickers';
 import { hues, osTranslations } from '@dxos/ui-theme';
 
 import { translationKey } from '#translations';
+import { type FormFieldRendererProps } from '#types';
 
-import { type FormFieldComponentProps, FormFieldLabel } from '../FormFieldComponent';
+import { FormFieldLabel } from '../../FormRow';
 
 export const SelectOptionField = ({
   type,
@@ -23,7 +24,7 @@ export const SelectOptionField = ({
   getStatus,
   getValue,
   onValueChange,
-}: FormFieldComponentProps<SelectOption[] | undefined>) => {
+}: FormFieldRendererProps<SelectOption[] | undefined>) => {
   const { t } = useTranslation(translationKey);
   const { status, error } = getStatus();
   const [selected, setSelectedId] = useState<string | null>(null);
@@ -123,74 +124,75 @@ export const SelectOptionField = ({
       <FormFieldLabel error={error} readonly={readonly} label={label} path={jsonPath} />
       <div>
         {options && (
-          <List.Root
+          <OrderedList.Root<SelectOption>
             items={options}
             isItem={(_item) => true}
+            getId={(option) => option.id}
             onMove={readonly ? undefined : handleMove}
             readonly={!!readonly}
           >
             {({ items }) => (
-              <div role='list' className='w-full overflow-auto'>
+              <OrderedList.Content classNames='w-full overflow-auto'>
                 {items?.map((item) => (
-                  <div key={item.id}>
-                    <List.Item
-                      role='button'
-                      item={item}
-                      classNames='flex flex-col cursor-pointer rounded-xs dx-hover'
-                      aria-expanded={selected === item.id}
-                    >
-                      <div className='flex items-center'>
-                        <List.ItemDragHandle disabled={!!readonly} />
-                        <List.ItemTitle onClick={() => handleClick(item.id)} classNames='flex-1'>
-                          {/* TODO(ZaymonFC): Move spacer into Tag component. */}
-                          <Tag palette={item.color as ChromaticPalette}>{item.title || '\u200b'}</Tag>
-                        </List.ItemTitle>
-                        <IconButton
-                          iconOnly
-                          variant='ghost'
-                          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)}
-                        />
+                  <OrderedList.Item
+                    key={item.id}
+                    id={item.id}
+                    item={item}
+                    canDrag={!readonly}
+                    classNames='flex flex-col cursor-pointer rounded-xs dx-hover'
+                  >
+                    <div className='flex items-center'>
+                      <OrderedList.DragHandle />
+                      {/* TODO(ZaymonFC): Move spacer into Tag component. */}
+                      <div className='flex grow items-center truncate px-2' onClick={() => handleClick(item.id)}>
+                        <Tag hue={item.color as ChromaticPalette}>{item.title || '\u200b'}</Tag>
                       </div>
-                      {selected === item.id && (
-                        <div className='flex flex-col p-form-padding gap-form-gap dx-density-md'>
-                          <Input.Label classNames='text-sm'>{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')}
-                              ref={selected === item.id ? inputRef : undefined}
-                              value={item.title}
-                              onChange={handleTitleChange(item.id)}
-                              onKeyDown={handleKeyDown}
-                              classNames='flex-1'
-                            />
-                            <HuePicker disabled={!!readonly} value={item.color} onChange={handleColorChange(item.id)} />
-                            <IconButton
-                              disabled={!!readonly}
-                              icon='ph--trash--fill'
-                              iconOnly
-                              label={t('select-option-delete.button')}
-                              onClick={() => handleDelete(item.id)}
-                            />
-                          </div>
+                      <ToggleIconButton
+                        iconOnly
+                        variant='ghost'
+                        active={selected === item.id}
+                        icon='ph--caret-right--regular'
+                        label={t(selected === item.id ? 'collapse.label' : 'expand.label', { ns: osTranslations })}
+                        onClick={() => handleClick(item.id)}
+                      />
+                    </div>
+                    {selected === item.id && (
+                      <div className='flex flex-col p-form-padding gap-form-gap dx-density-md'>
+                        <Input.Label classNames='text-sm'>{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')}
+                            ref={selected === item.id ? inputRef : undefined}
+                            value={item.title}
+                            onChange={handleTitleChange(item.id)}
+                            onKeyDown={handleKeyDown}
+                            classNames='flex-1'
+                          />
+                          <HuePicker disabled={!!readonly} value={item.color} onChange={handleColorChange(item.id)} />
+                          <IconButton
+                            disabled={!!readonly}
+                            icon='ph--trash--fill'
+                            iconOnly
+                            label={t('select-option-delete.button')}
+                            onClick={() => handleDelete(item.id)}
+                          />
                         </div>
-                      )}
-                    </List.Item>
-                  </div>
+                      </div>
+                    )}
+                  </OrderedList.Item>
                 ))}
                 <IconButton
+                  classNames='w-full'
                   variant='ghost'
                   icon='ph--plus--regular'
                   label={t('select-option-add.button')}
                   onClick={handleAdd}
                   disabled={!!readonly}
-                  classNames='w-full'
                 />
-              </div>
+              </OrderedList.Content>
             )}
-          </List.Root>
+          </OrderedList.Root>
         )}
       </div>
     </Input.Root>

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

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

package/src/components/Form/FormField/fields/TextAreaField/TextAreaField.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({
+  notes: Format.Text.annotations({ title: 'Notes' }),
+}).pipe(Schema.mutable);
+
+type Values = Schema.Schema.Type<typeof schema>;
+
+const DefaultStory = () => {
+  const [values, setValues] = useState<Values>({ notes: 'Multi-line\nplain text.' });
+  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/TextAreaField',
+  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/{fields → FormField/fields/TextAreaField}/TextAreaField.tsx

@@ -6,7 +6,9 @@ import React, { useCallback } from 'react';
 
 import { Input, type TextAreaProps } from '@dxos/react-ui';
 
-import { type FormFieldComponentProps, FormFieldWrapper } from '../FormFieldComponent';
+import { type FormFieldRendererProps } from '#types';
+
+import { FormRow } from '../../FormRow';
 
 export const TextAreaField = ({
   type,
@@ -15,14 +17,14 @@ export const TextAreaField = ({
   onValueChange,
   onBlur,
   ...props
-}: FormFieldComponentProps<string>) => {
+}: FormFieldRendererProps<string>) => {
   const handleChange = useCallback<NonNullable<TextAreaProps['onChange']>>(
     (event) => onValueChange(type, event.target.value),
     [type, onValueChange],
   );
 
   return (
-    <FormFieldWrapper<string> readonly={readonly} {...props}>
+    <FormRow<string> readonly={readonly} {...props}>
       {({ value = '' }) => (
         <Input.TextArea
           rows={5}
@@ -33,6 +35,6 @@ export const TextAreaField = ({
           onBlur={onBlur}
         />
       )}
-    </FormFieldWrapper>
+    </FormRow>
   );
 };

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

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

package/src/components/Form/FormField/fields/TextField/TextField.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({
+  name: Schema.String.annotations({ title: 'Name' }),
+}).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/TextField',
+  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/{fields → FormField/fields/TextField}/TextField.tsx

@@ -6,7 +6,9 @@ import React, { useCallback } from 'react';
 
 import { Input, type TextInputProps } from '@dxos/react-ui';
 
-import { type FormFieldComponentProps, FormFieldWrapper } from '../FormFieldComponent';
+import { type FormFieldRendererProps } from '#types';
+
+import { FormRow } from '../../FormRow';
 
 export const TextField = ({
   type,
@@ -15,14 +17,14 @@ export const TextField = ({
   onBlur,
   onValueChange,
   ...props
-}: FormFieldComponentProps<string>) => {
+}: FormFieldRendererProps<string>) => {
   const handleChange = useCallback<NonNullable<TextInputProps['onChange']>>(
     (event) => onValueChange(type, event.target.value),
     [type, onValueChange],
   );
 
   return (
-    <FormFieldWrapper<string> readonly={readonly} {...props}>
+    <FormRow<string> readonly={readonly} {...props}>
       {({ value = '' }) => (
         <Input.TextInput
           noAutoFill
@@ -33,6 +35,6 @@ export const TextField = ({
           onChange={handleChange}
         />
       )}
-    </FormFieldWrapper>
+    </FormRow>
   );
 };

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

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

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

@@ -0,0 +1,55 @@
+//
+// 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';
+import { TupleField } from './TupleField';
+
+// TupleField isn't auto-dispatched and needs a `binding`; wire it via `fieldMap`.
+const schema = Schema.Struct({
+  point: Schema.Struct({ x: Schema.Number, y: Schema.Number }).annotations({ title: 'Point' }),
+}).pipe(Schema.mutable);
+
+type Values = Schema.Schema.Type<typeof schema>;
+
+const DefaultStory = () => {
+  const [values, setValues] = useState<Values>({ point: { x: 1, y: 2 } });
+  return (
+    <TestLayout json={values}>
+      <Form.Root
+        schema={schema}
+        values={values}
+        fieldMap={{ point: (props) => <TupleField {...props} binding={['x', 'y']} /> }}
+        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/TupleField',
+  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/{fields → FormField/fields/TupleField}/TupleField.tsx

@@ -8,7 +8,9 @@ import { Input } from '@dxos/react-ui';
 import { mx } from '@dxos/ui-theme';
 import { safeParseFloat } from '@dxos/util';
 
-import { type FormFieldComponentProps, FormFieldLabel } from '../FormFieldComponent';
+import { type FormFieldRendererProps } from '#types';
+
+import { FormFieldLabel } from '../../FormRow';
 
 const gridCols = ['grid-cols-1', 'grid-cols-2', 'grid-cols-3', 'grid-cols-4'];
 
@@ -22,7 +24,7 @@ export const TupleField = ({
   getValue,
   onValueChange,
   onBlur,
-}: FormFieldComponentProps<Record<string, number>> & {
+}: FormFieldRendererProps<Record<string, number>> & {
   binding: string[];
 }) => {
   const { status, error } = getStatus();

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

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