@dxos/react-ui-form 0.8.4-main.9be5663bfe → 0.8.4-main.abd8ff62ef

package/src/components/Settings/Settings.tsx

@@ -4,16 +4,17 @@
 
 import React, { type PropsWithChildren } from 'react';
 
-import { Input, type Label, ScrollArea, type ThemedClassName, toLocalizedString, useTranslation } from '@dxos/react-ui';
+import { type Label, ScrollArea, type ThemedClassName, toLocalizedString, useTranslation } from '@dxos/react-ui';
 import { composable, composableProps, mx } from '@dxos/ui-theme';
 
-import { translationKey } from '../../translations';
+import { translationKey } from '#translations';
+
+import { SettingsFieldSet } from './SettingsFieldSet';
+import { SettingsItem, SettingsPanel } from './SettingsItem';
 
 const SETTINGS_ROOT_NAME = 'Settings.Root';
 const SETTINGS_VIEWPORT_NAME = 'Settings.Viewport';
 const SETTINGS_SECTION_NAME = 'Settings.Section';
-const SETTINGS_PANEL_NAME = 'Settings.Panel';
-const SETTINGS_ITEM_NAME = 'Settings.Item';
 
 //
 // Root (headless — no styling, no scroll).
@@ -67,55 +68,6 @@ const SettingsSection = ({ title, description, children }: SettingsSectionProps)
 
 SettingsSection.displayName = SETTINGS_SECTION_NAME;
 
-//
-// Panel (bordered card container).
-//
-
-type SettingsPanelProps = ThemedClassName<PropsWithChildren>;
-
-const SettingsPanel = ({ classNames, children }: SettingsPanelProps) => {
-  return (
-    <div role='none' className={mx('flex flex-col gap-3 p-trim-md border border-separator rounded-sm', classNames)}>
-      {children}
-    </div>
-  );
-};
-
-SettingsPanel.displayName = SETTINGS_PANEL_NAME;
-
-//
-// Item (label + optional description + control, proper label semantics).
-//
-
-type SettingsItemProps = PropsWithChildren<{
-  title: Label;
-  description?: Label;
-}>;
-
-const SettingsItem = ({ title, description = '', children }: SettingsItemProps) => {
-  const { t } = useTranslation(translationKey);
-
-  return (
-    <Input.Root>
-      <SettingsPanel classNames='grid grid-cols-1 md:grid-cols-[1fr_1fr] gap-x-trim-lg gap-y-0'>
-        <Input.Label classNames='pb-trim-md text-base-surface-text text-lg md:col-span-2'>
-          {toLocalizedString(title, t)}
-        </Input.Label>
-        <Input.DescriptionAndValidation>
-          <Input.Description classNames='text-base text-description'>
-            {toLocalizedString(description, t)}
-          </Input.Description>
-        </Input.DescriptionAndValidation>
-        <div role='none' className='text-end py-1'>
-          {children}
-        </div>
-      </SettingsPanel>
-    </Input.Root>
-  );
-};
-
-SettingsItem.displayName = SETTINGS_ITEM_NAME;
-
 //
 // Settings
 //
@@ -126,4 +78,5 @@ export const Settings = {
   Section: SettingsSection,
   Panel: SettingsPanel,
   Item: SettingsItem,
+  FieldSet: SettingsFieldSet,
 };

package/src/components/Settings/SettingsFieldSet.tsx

@@ -0,0 +1,257 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as SchemaAST from 'effect/SchemaAST';
+import * as String from 'effect/String';
+import React, { useCallback, useMemo } from 'react';
+
+import { getAnnotation, type SchemaProperty } from '@dxos/effect';
+import { Input, Select } from '@dxos/react-ui';
+
+import { getFormProperties, type SelectOption, detectFieldType, getSelectOptionsFromAst } from '../../util';
+import { SettingsItem } from './SettingsItem';
+
+//
+// Types
+//
+
+/**
+ * Props for a custom field renderer.
+ * The renderer provides the control only; SettingsItem wrapper is handled by FieldSet.
+ */
+export type SettingsFieldProps<T = any> = {
+  value: T;
+  onChange: (value: T) => void;
+  readonly?: boolean;
+};
+
+/**
+ * Map of property names to either a custom field renderer or a nested field map for struct fields.
+ * When a value type `T` is provided, the map shape is checked against the schema's value type.
+ */
+export type SettingsFieldMap<T extends Record<string, any> = Record<string, any>> = {
+  [K in keyof T]?: NonNullable<T[K]> extends Record<string, any>
+    ? SettingsFieldMap<NonNullable<T[K]>>
+    : React.FC<SettingsFieldProps<T[K]>>;
+};
+
+export type SettingsFieldSetProps<T extends Record<string, any> = Record<string, any>> = {
+  /** Effect Schema for the settings object. */
+  schema: { ast: SchemaAST.AST };
+
+  /** Current settings values. */
+  values: T;
+
+  /** Callback when any value changes. Receives a new complete object. */
+  onValuesChanged?: (values: T) => void;
+
+  /** When true, all controls are disabled. */
+  readonly?: boolean;
+
+  /** Map of property names to custom field renderers. Nested objects map to struct sub-fields. */
+  fieldMap?: SettingsFieldMap<T>;
+
+  /** Control field visibility. Receives the dotted path (e.g. `'modelDefaults.edge'`) at every level. */
+  visible?: (path: string, values: T) => boolean;
+
+  /** Override the order of fields. Fields not listed are appended in schema order. Applied per scope. */
+  sort?: string[];
+
+  /** Internal: dot-path prefix used by recursive struct rendering. */
+  pathPrefix?: string;
+};
+
+//
+// Component
+//
+
+export const SettingsFieldSet = <T extends Record<string, any>>({
+  schema,
+  values,
+  onValuesChanged,
+  readonly,
+  fieldMap,
+  visible,
+  sort,
+  pathPrefix = '',
+}: SettingsFieldSetProps<T>) => {
+  const properties = useMemo(() => {
+    const props = getFormProperties(schema.ast);
+    if (!sort) {
+      return props;
+    }
+    const rank = (name: string) => {
+      const idx = sort.indexOf(name);
+      return idx === -1 ? Number.POSITIVE_INFINITY : idx;
+    };
+    return [...props].sort(({ name: a }, { name: b }) => rank(a.toString()) - rank(b.toString()));
+  }, [schema, sort]);
+
+  const handleChange = useCallback(
+    (name: string, value: unknown) => {
+      onValuesChanged?.({ ...values, [name]: value } as T);
+    },
+    [values, onValuesChanged],
+  );
+
+  return (
+    <>
+      {properties.map((property) => {
+        const name = property.name.toString();
+        const path = pathPrefix ? `${pathPrefix}.${name}` : name;
+        if (visible && !visible(path, values)) {
+          return null;
+        }
+
+        const entry = fieldMap?.[name as keyof typeof fieldMap] as
+          | React.FC<SettingsFieldProps>
+          | SettingsFieldMap
+          | undefined;
+        return (
+          <SettingsFieldItem
+            key={name}
+            path={path}
+            property={property}
+            value={values[name]}
+            onChange={(value) => handleChange(name, value)}
+            readonly={readonly}
+            customField={typeof entry === 'function' ? entry : undefined}
+            nestedFieldMap={typeof entry === 'object' ? entry : undefined}
+            visible={visible as (path: string, values: any) => boolean}
+            sort={sort}
+          />
+        );
+      })}
+    </>
+  );
+};
+
+SettingsFieldSet.displayName = 'Settings.FieldSet';
+
+//
+// Internal: render a single settings field.
+//
+
+type SettingsFieldItemProps = {
+  property: SchemaProperty;
+  path: string;
+  value: any;
+  onChange: (value: any) => void;
+  readonly?: boolean;
+  customField?: React.FC<SettingsFieldProps>;
+  nestedFieldMap?: SettingsFieldMap;
+  visible?: (path: string, values: any) => boolean;
+  sort?: string[];
+};
+
+const SettingsFieldItem = ({
+  property,
+  path,
+  value,
+  onChange,
+  readonly,
+  customField,
+  nestedFieldMap,
+  visible,
+  sort,
+}: SettingsFieldItemProps) => {
+  const { type } = property;
+  const name = property.name.toString();
+  const title = getAnnotation<string>(SchemaAST.TitleAnnotationId)(type) ?? String.capitalize(name);
+  const description = getAnnotation<string>(SchemaAST.DescriptionAnnotationId)(type);
+
+  // Custom field renderer.
+  if (customField) {
+    const CustomField = customField;
+    return (
+      <SettingsItem title={title} description={description}>
+        <CustomField value={value} onChange={onChange} readonly={readonly} />
+      </SettingsItem>
+    );
+  }
+
+  const fieldType = detectFieldType(type);
+
+  switch (fieldType) {
+    case 'struct':
+      return (
+        <SettingsFieldSet
+          schema={{ ast: type }}
+          values={value ?? {}}
+          onValuesChanged={onChange}
+          readonly={readonly}
+          fieldMap={nestedFieldMap}
+          visible={visible}
+          sort={sort}
+          pathPrefix={path}
+        />
+      );
+
+    case 'boolean':
+      return (
+        <SettingsItem title={title} description={description}>
+          <Input.Switch disabled={readonly} checked={!!value} onCheckedChange={(checked) => onChange(!!checked)} />
+        </SettingsItem>
+      );
+
+    case 'select': {
+      const options = getSelectOptionsFromAst(type) ?? [];
+      return (
+        <SettingsItem title={title} description={description}>
+          <Select.Root
+            disabled={readonly}
+            value={value == null ? '' : globalThis.String(value)}
+            onValueChange={(selected) => {
+              const matched = options.find((option) => globalThis.String(option.value) === selected);
+              onChange(matched?.value ?? selected);
+            }}
+          >
+            <Select.TriggerButton disabled={readonly} />
+            <Select.Portal>
+              <Select.Content>
+                <Select.Viewport>
+                  {options.map((option: SelectOption) => (
+                    <Select.Option key={globalThis.String(option.value)} value={globalThis.String(option.value)}>
+                      {option.label ?? globalThis.String(option.value)}
+                    </Select.Option>
+                  ))}
+                </Select.Viewport>
+                <Select.Arrow />
+              </Select.Content>
+            </Select.Portal>
+          </Select.Root>
+        </SettingsItem>
+      );
+    }
+
+    case 'string':
+      return (
+        <SettingsItem title={title} description={description}>
+          <Input.TextInput disabled={readonly} value={value ?? ''} onChange={(event) => onChange(event.target.value)} />
+        </SettingsItem>
+      );
+
+    case 'number':
+      return (
+        <SettingsItem title={title} description={description}>
+          <Input.TextInput
+            disabled={readonly}
+            type='number'
+            value={value ?? ''}
+            onChange={(event) => {
+              if (event.target.value === '') {
+                onChange(undefined);
+                return;
+              }
+              const parsed = Number(event.target.value);
+              onChange(Number.isNaN(parsed) ? undefined : parsed);
+            }}
+          />
+        </SettingsItem>
+      );
+
+    default:
+      return null;
+  }
+};

package/src/components/Settings/SettingsItem.tsx

@@ -0,0 +1,62 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { type PropsWithChildren } from 'react';
+
+import { Input, type Label, type ThemedClassName, toLocalizedString, useTranslation } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+
+import { translationKey } from '#translations';
+
+const SETTINGS_PANEL_NAME = 'Settings.Panel';
+const SETTINGS_ITEM_NAME = 'Settings.Item';
+
+//
+// Panel (bordered card container).
+//
+
+type SettingsPanelProps = ThemedClassName<PropsWithChildren>;
+
+export const SettingsPanel = ({ classNames, children }: SettingsPanelProps) => {
+  return (
+    <div role='none' className={mx('flex flex-col gap-3 p-trim-md border border-separator rounded-sm', classNames)}>
+      {children}
+    </div>
+  );
+};
+
+SettingsPanel.displayName = SETTINGS_PANEL_NAME;
+
+//
+// Item (label + optional description + control, proper label semantics).
+//
+
+type SettingsItemProps = PropsWithChildren<{
+  title: Label;
+  description?: Label;
+}>;
+
+export const SettingsItem = ({ title, description = '', children }: SettingsItemProps) => {
+  const { t } = useTranslation(translationKey);
+
+  return (
+    <Input.Root>
+      <SettingsPanel classNames='grid grid-cols-1 md:grid-cols-[1fr_1fr] gap-x-trim-lg gap-y-0'>
+        <Input.Label classNames='pb-trim-md text-base-surface-text text-lg md:col-span-2'>
+          {toLocalizedString(title, t)}
+        </Input.Label>
+        <Input.DescriptionAndValidation>
+          <Input.Description classNames='text-base text-description'>
+            {toLocalizedString(description, t)}
+          </Input.Description>
+        </Input.DescriptionAndValidation>
+        <div role='none' className='text-end py-1'>
+          {children}
+        </div>
+      </SettingsPanel>
+    </Input.Root>
+  );
+};
+
+SettingsItem.displayName = SETTINGS_ITEM_NAME;

package/src/components/Settings/SettingsSelectField.tsx

@@ -0,0 +1,59 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { Select } from '@dxos/react-ui';
+
+import { type SettingsFieldProps } from './SettingsFieldSet';
+
+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 `SettingsFieldSet` `fieldMap` entry that renders a Select control
+ * over a fixed list of options, with an optional sentinel for `undefined`.
+ */
+export const createSelectField = ({
+  options,
+  defaultLabel = 'Default',
+}: CreateSelectFieldOptions): React.FC<SettingsFieldProps<string | undefined>> => {
+  const normalized = options.map((option) => (typeof option === 'string' ? { value: option, label: option } : option));
+  const hasDefault = defaultLabel !== null;
+  // Per-instance sentinel avoids collisions with real option values; empty string when the
+  // sentinel is omitted so `undefined` maps to a value Select.Root treats as "no selection".
+  const sentinel = hasDefault ? `__default__${Math.random().toString(36).slice(2)}` : '';
+
+  return ({ value, onChange, readonly }) => (
+    <Select.Root
+      disabled={readonly}
+      value={value ?? sentinel}
+      onValueChange={(next) => onChange(hasDefault && next === sentinel ? undefined : next)}
+    >
+      <Select.TriggerButton disabled={readonly} />
+      <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>
+  );
+};

package/src/components/Settings/index.ts

@@ -3,3 +3,5 @@
 //
 
 export * from './Settings';
+export { type SettingsFieldMap, type SettingsFieldProps, type SettingsFieldSetProps } from './SettingsFieldSet';
+export { createSelectField, type CreateSelectFieldOptions, type SelectFieldOption } from './SettingsSelectField';

package/src/components/ViewEditor/ViewEditor.stories.tsx

@@ -16,7 +16,8 @@ import { withLayout, withTheme } from '@dxos/react-ui/testing';
 import { type ProjectionModel, ViewModel, getTypenameFromQuery } from '@dxos/schema';
 import { Employer, Organization, Person, Pipeline } from '@dxos/types';
 
-import { translations } from '../../translations';
+import { translations } from '#translations';
+
 import { TestLayout, VIEW_EDITOR_DEBUG_SYMBOL } from '../testing';
 import { ViewEditor, type ViewEditorProps } from './ViewEditor';
 
@@ -90,7 +91,7 @@ const DefaultStory = (props: DefaultStoryProps) => {
       if (props.mode === 'tag') {
         const queue = target && DXN.tryParse(target) ? target : undefined;
         const query = queue ? Query.fromAst(newQuery).from({ queues: [queue] }) : Query.fromAst(newQuery);
-        Obj.change(view, (view) => {
+        Obj.update(view, (view) => {
           view.query.ast = query.ast as Mutable<typeof query.ast>;
         });
 
@@ -104,12 +105,12 @@ const DefaultStory = (props: DefaultStoryProps) => {
           query,
           jsonSchema: newSchema.jsonSchema,
         });
-        Obj.change(view, (view) => {
+        Obj.update(view, (view) => {
           view.projection = Obj.getSnapshot(newView).projection as Mutable<typeof view.projection>;
         });
         setSchema(() => newSchema);
       } else {
-        Obj.change(view, (view) => {
+        Obj.update(view, (view) => {
           view.query.ast = newQuery as Mutable<typeof newQuery>;
         });
         schema.updateTypename(getTypenameFromQuery(newQuery));
@@ -146,20 +147,18 @@ const DefaultStory = (props: DefaultStoryProps) => {
 
   return (
     <TestLayout json={json}>
-      <div role='none' className='col-span-full'>
-        <ViewEditor
-          ref={projectionRef}
-          schema={schema}
-          view={view}
-          registry={space?.db.schemaRegistry}
-          mode={props.mode}
-          readonly={props.readonly}
-          types={types}
-          tags={tags}
-          onQueryChanged={updateViewQuery}
-          onDelete={handleDelete}
-        />
-      </div>
+      <ViewEditor
+        ref={projectionRef}
+        schema={schema}
+        view={view}
+        registry={space?.db.schemaRegistry}
+        mode={props.mode}
+        readonly={props.readonly}
+        types={types}
+        tags={tags}
+        onQueryChanged={updateViewQuery}
+        onDelete={handleDelete}
+      />
     </TestLayout>
   );
 };

package/src/components/ViewEditor/ViewEditor.tsx

@@ -26,7 +26,8 @@ import {
 } from '@dxos/schema';
 import { mx, osTranslations, subtleHover } from '@dxos/ui-theme';
 
-import { translationKey } from '../../translations';
+import { translationKey } from '#translations';
+
 import { FieldEditor } from '../FieldEditor';
 import {
   Form,
@@ -274,7 +275,7 @@ const FieldList = ({ schema, view, registry, readonly, showHeading = false, onDe
   const handleMove = useCallback(
     (fromIndex: number, toIndex: number) => {
       invariant(!readonly);
-      Obj.change(view, (view) => {
+      Obj.update(view, (view) => {
         // NOTE(ZaymonFC): Using arrayMove here causes a race condition with the kanban model.
         const fields = [...view.projection.fields];
         const [moved] = fields.splice(fromIndex, 1);
@@ -341,7 +342,7 @@ const FieldList = ({ schema, view, registry, readonly, showHeading = false, onDe
                       {field.path}
                     </List.ItemTitle>
                     <List.ItemIconButton
-                      label={t(hidden ? 'show field label' : 'hide field label')}
+                      label={t(hidden ? 'show-field.label' : 'hide-field.label')}
                       data-testid={hidden ? 'show-field-button' : 'hide-field-button'}
                       icon={hidden ? 'ph--eye-closed--regular' : 'ph--eye--regular'}
                       autoHide={false}

package/src/components/testing.tsx

@@ -4,27 +4,25 @@
 
 import React, { type PropsWithChildren } from 'react';
 
-import { Column, type ThemedClassName } from '@dxos/react-ui';
-import { Json } from '@dxos/react-ui-syntax-highlighter';
-import { mx } from '@dxos/ui-theme';
+import { type ThemedClassName } from '@dxos/react-ui';
+import { Syntax } from '@dxos/react-ui-syntax-highlighter';
+import { composableProps, slottable } from '@dxos/ui-theme';
 
-type TestLayoutProps = ThemedClassName<PropsWithChildren<{ json?: any }>>;
+type TestLayoutProps = PropsWithChildren<{ json?: any }>;
 
-export const TestLayout = ({ classNames, children, json }: TestLayoutProps) => {
+export const TestLayout = ({ children, json }: TestLayoutProps) => {
   return (
-    <div className='h-full w-full grid grid-cols-[1fr_1fr] p-4 gap-4 overflow-hidden'>
-      <TestPanel classNames={['dx-container', classNames]}>
-        <Column.Root classNames='dx-container' gutter='sm'>
-          {children}
-        </Column.Root>
-      </TestPanel>
-      <TestPanel classNames={'overflow-hidden'}>
-        <Json.Root data={json}>
-          <Json.Content classNames='h-full'>
-            <Json.Filter />
-            <Json.Data testId='debug' classNames='text-xs' />
-          </Json.Content>
-        </Json.Root>
+    <div role='none' className='dx-container grid grid-cols-[1fr_1fr] p-4 gap-4'>
+      <TestPanel>{children}</TestPanel>
+      <TestPanel>
+        <Syntax.Root data={json}>
+          <Syntax.Content>
+            <Syntax.Filter />
+            <Syntax.Viewport>
+              <Syntax.Code testId='debug' classNames='text-xs' />
+            </Syntax.Viewport>
+          </Syntax.Content>
+        </Syntax.Root>
       </TestPanel>
     </div>
   );
@@ -32,14 +30,15 @@ export const TestLayout = ({ classNames, children, json }: TestLayoutProps) => {
 
 type TestPanelProps = ThemedClassName<PropsWithChildren>;
 
-const TestPanel = ({ classNames, children }: TestPanelProps) => {
+const TestPanel = slottable<HTMLDivElement, TestPanelProps>(({ children }, forwardedRef) => {
   return (
-    <div role='none' className={mx(['dx-document h-full bg-modal-surface rounded-md', classNames])}>
+    <div {...composableProps({ classNames: 'dx-container bg-modal-surface rounded-md' })} ref={forwardedRef}>
       {children}
     </div>
   );
-};
+});
 
 // Symbol for accessing debug objects in tests.
 export const VIEW_EDITOR_DEBUG_SYMBOL = Symbol('viewEditorDebug');
 export const FIELD_EDITOR_DEBUG_SYMBOL = Symbol('fieldEditorDebug');
+export const OBJECT_PROPERTIES_DEBUG_SYMBOL = Symbol('objectPropertiesDebug');

package/src/index.ts

@@ -2,10 +2,6 @@
 // Copyright 2024 DXOS.org
 //
 
-import { translations } from './translations';
-
 export * from './components';
 export * from './hooks';
 export * from './util';
-
-export { translations };

package/src/translations.ts

@@ -14,23 +14,25 @@ export const translations = [
         'hidden-fields.label': 'Hidden Fields',
         'empty-readonly-ref-field.label': '(none)',
 
-        'add-property-button.label': 'Add property',
         'field-property.label': 'Property',
         'field-property.placeholder': 'Property name',
         'field-format.label': 'Type',
         'field-path.label': 'Field path',
-        'add-field.button': 'Add field',
+
+        'add-item.button': 'Add item',
+        'add-property-button.label': 'Add property',
         'boolean-input-true.value': 'Yes',
         'boolean-input-false.value': 'No',
         'show-field.label': 'Show field',
         'hide-field.label': 'Hide field',
         'delete-field.label': 'Delete field',
+        'create-option.label': 'Create',
+        'add-tag.label': 'Add tag',
+
         'ref-field-combobox-input.placeholder': 'Search…',
         'ref-field.placeholder': 'Select…',
         'ref-field.placeholder_one': 'Select…',
         'ref-field.placeholder_other': 'Select items…',
-        'create-option.label': 'Create',
-        'add-tag.label': 'Add tag',
 
         'example.placeholder': 'Example',
         'latitude.placeholder': 'Latitude (e.g., 40.7128)',
@@ -38,6 +40,7 @@ export const translations = [
 
         'cancel-button.label': 'Cancel',
         'save-button.label': 'Save',
+        'create-text.label': 'Create text',
 
         // TypeFormat
         'format.boolean.label': 'Boolean',