@dxos/react-ui-form 0.8.4-main.c85a9c8dae → 0.8.4-main.d05539e30a

package/src/components/Settings/Settings.stories.tsx

@@ -3,39 +3,40 @@
 //
 
 import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Schema from 'effect/Schema';
 import React from 'react';
 
-import { faker } from '@dxos/random';
+import { random } from '@dxos/random';
 import { Button, Input } from '@dxos/react-ui';
 import { withLayout, withTheme } from '@dxos/react-ui/testing';
 
-import { translations } from '../../translations';
+import { translations } from '#translations';
 
 import { Settings } from './Settings';
 
-faker.seed(132);
+random.seed(132);
 
 const DefaultStory = () => {
   return (
-    <Settings.Root>
-      <Settings.Section title='Settings' description={faker.lorem.paragraphs(1)}>
-        <Settings.Group>
-          <Settings.ItemInput title={faker.lorem.sentence(2)} description={faker.lorem.paragraphs(1)}>
-            <Input.Root>
-              <Input.TextInput placeholder='Input' />
-            </Input.Root>
-          </Settings.ItemInput>
-          <Settings.ItemInput title={faker.lorem.sentence(2)} description={faker.lorem.paragraphs(2)}>
-            <Input.Root>
-              <Input.Switch />
-            </Input.Root>
-          </Settings.ItemInput>
-          <Settings.ItemInput title={faker.lorem.sentence(3)} description={faker.lorem.paragraphs(2)}>
-            <Button>Test</Button>
-          </Settings.ItemInput>
-        </Settings.Group>
+    <Settings.Viewport>
+      <Settings.Section title='Settings' description={random.lorem.paragraphs(1)}>
+        <Settings.Item title={random.lorem.sentence(2)} description={random.lorem.paragraphs(1)}>
+          <Input.TextInput placeholder='Input' />
+        </Settings.Item>
+        <Settings.Item title={random.lorem.sentence(2)} description={random.lorem.paragraphs(2)}>
+          <Input.Switch />
+        </Settings.Item>
+        <Settings.Item title={random.lorem.sentence(3)} description={random.lorem.paragraphs(2)}>
+          <Button>Test</Button>
+        </Settings.Item>
       </Settings.Section>
-    </Settings.Root>
+      <Settings.Section title='Panel Example'>
+        <Settings.Panel>
+          <h3 className='text-lg mb-2'>Members</h3>
+          <p className='text-description'>Content inside a panel.</p>
+        </Settings.Panel>
+      </Settings.Section>
+    </Settings.Viewport>
   );
 };
 
@@ -54,3 +55,50 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {};
+
+const TestViewModes = ['preview', 'readonly', 'source'] as const;
+const TestViewMode = Schema.Union(...TestViewModes.map((mode) => Schema.Literal(mode)));
+
+const TestSettings = Schema.mutable(
+  Schema.Struct({
+    viewMode: TestViewMode.annotations({ title: 'View mode', description: 'Default document view mode.' }),
+    toolbar: Schema.optional(
+      Schema.Boolean.annotations({ title: 'Show toolbar', description: 'Display formatting toolbar.' }),
+    ),
+    fontSize: Schema.optional(
+      Schema.Number.annotations({ title: 'Font size', description: 'Editor font size in pixels.' }),
+    ),
+    placeholder: Schema.optional(
+      Schema.String.annotations({ title: 'Placeholder', description: 'Default placeholder text.' }),
+    ),
+    debug: Schema.optional(Schema.Boolean.annotations({ title: 'Debug mode', description: 'Enable debug features.' })),
+  }),
+);
+
+type TestSettings = Schema.Schema.Type<typeof TestSettings>;
+
+const FieldSetStory = () => {
+  const [values, setValues] = React.useState<TestSettings>({
+    viewMode: 'preview',
+    toolbar: true,
+    fontSize: 14,
+    debug: false,
+  });
+
+  return (
+    <Settings.Viewport>
+      <Settings.Section title='Plugin Settings (Auto-generated)'>
+        <Settings.FieldSet
+          schema={TestSettings}
+          values={values}
+          onValuesChanged={setValues}
+          visible={(path, values) => path !== 'placeholder' || !!values.debug}
+        />
+      </Settings.Section>
+    </Settings.Viewport>
+  );
+};
+
+export const FieldSet: Story = {
+  render: FieldSetStory,
+};

package/src/components/Settings/Settings.tsx

@@ -4,213 +4,67 @@
 
 import React, { type PropsWithChildren } from 'react';
 
-import {
-  Button,
-  type ButtonProps,
-  Input,
-  type Label,
-  ScrollArea,
-  type ThemedClassName,
-  toLocalizedString,
-  useTranslation,
-} from '@dxos/react-ui';
-import { mx } from '@dxos/ui-theme';
-
-import { translationKey } from '../../translations';
+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 { 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_SECTION_HEADING_NAME = 'Settings.SectionHeading';
-const SETTINGS_GROUP_NAME = 'Settings.Group';
-const SETTINGS_GROUP_BUTTON_NAME = 'Settings.GroupButton';
-const SETTINGS_CONTAINER_NAME = 'Settings.Container';
-const SETTINGS_FRAME_NAME = 'Settings.Frame';
-const SETTINGS_FRAME_ITEM_NAME = 'Settings.FrameItem';
-const SETTINGS_ITEM_NAME = 'Settings.Item';
-const SETTINGS_ITEM_INPUT_NAME = 'Settings.ItemInput';
-
-const styles = {
-  title: 'pb-trim-md text-base-surface-text text-lg',
-  description: 'text-base text-description',
-  grid: 'grid grid-cols-1 md:grid-cols-[1fr_1fr] gap-x-trim-lg',
-};
 
 //
-// Root
+// Root (headless — no styling, no scroll).
 //
 
-type SettingsRootProps = PropsWithChildren;
+type SettingsRootProps = ThemedClassName<PropsWithChildren>;
 
-const SettingsRoot = ({ children }: SettingsRootProps) => {
-  return (
-    <ScrollArea.Root orientation='vertical' className='dx-article'>
-      <ScrollArea.Viewport classNames='p-trim-md'>{children}</ScrollArea.Viewport>
-    </ScrollArea.Root>
-  );
+const SettingsRoot = ({ children, classNames }: SettingsRootProps) => {
+  return <div className={mx('flex flex-col gap-2', classNames)}>{children}</div>;
 };
 
 SettingsRoot.displayName = SETTINGS_ROOT_NAME;
 
 //
-// Section
+// Viewport (scroll area + padding + document layout).
 //
 
-type SettingsSectionProps = PropsWithChildren<{
-  title: Label;
-  description?: Label;
-}>;
-
-const SettingsSection = ({ title, description, children }: SettingsSectionProps) => {
+const SettingsViewport = composable<HTMLDivElement>(({ children, ...props }, forwardedRef) => {
   return (
-    <>
-      <SettingsSectionHeading title={title} description={description} />
-      <div className='w-full pt-trim-md space-y-trim-md'>{children}</div>
-    </>
-  );
-};
-
-SettingsSection.displayName = SETTINGS_SECTION_NAME;
-
-//
-// Section Heading
-//
-
-const SettingsSectionHeading = ({ title, description }: Omit<SettingsSectionProps, 'children'>) => {
-  const { t } = useTranslation(translationKey);
-  return (
-    <>
-      <h2 className='px-trim-md mt-trim-md mb-trim-md text-xl'>{toLocalizedString(title, t)}</h2>
-      {description && <p className='px-trim-md my-trim-md text-description'>{toLocalizedString(description, t)}</p>}
-    </>
-  );
-};
-
-SettingsSectionHeading.displayName = SETTINGS_SECTION_HEADING_NAME;
-
-//
-// Group Button
-//
-
-const SettingsGroupButton = ({ classNames, ...props }: ButtonProps) => {
-  return <Button {...props} classNames={['md:col-span-2', classNames]} />;
-};
-
-SettingsGroupButton.displayName = SETTINGS_GROUP_BUTTON_NAME;
-
-//
-// Group
-//
-
-type SettingsGroupProps = ThemedClassName<PropsWithChildren>;
-
-const SettingsGroup = ({ children, classNames }: SettingsGroupProps) => (
-  <div role='none' className={mx('group space-y-trim-md', classNames)}>
-    {children}
-  </div>
-);
-
-SettingsGroup.displayName = SETTINGS_GROUP_NAME;
-
-//
-// Frame
-//
-
-const SettingsFrame = ({ children }: SettingsGroupProps) => (
-  <div role='none' className='p-trim-md border border-separator rounded-md'>
-    {children}
-  </div>
-);
-
-SettingsFrame.displayName = SETTINGS_FRAME_NAME;
-
-//
-// Frame Item
-//
-
-const SettingsFrameItem = ({ title, description, children }: SettingsItemProps) => {
-  const { t } = useTranslation(translationKey);
-
-  return (
-    <div role='group' className='min-w-0'>
-      <h3 className='text-lg mb-2'>{toLocalizedString(title, t)}</h3>
-      {description && <p className='my-trim-sm md:mb-0 text-description'>{toLocalizedString(description, t)}</p>}
-      {children}
-    </div>
-  );
-};
-
-SettingsFrameItem.displayName = SETTINGS_FRAME_ITEM_NAME;
-
-//
-// Container
-//
-
-const SettingsContainer = ({ classNames, children }: ThemedClassName<PropsWithChildren>) => {
-  return (
-    <div
-      role='none'
-      className={mx([
-        'dx-article',
-        '*:first:mt-0! *:last:mb-0! px-trim-md py-trim-md',
-        'border border-separator rounded-md',
-        classNames,
-      ])}
-    >
-      {children}
-    </div>
+    <ScrollArea.Root {...composableProps(props)} orientation='vertical' centered thin ref={forwardedRef}>
+      <ScrollArea.Viewport classNames='px-4 pointer-coarse:px-2'>
+        <div className='dx-document flex flex-col gap-2 py-4'>{children}</div>
+      </ScrollArea.Viewport>
+    </ScrollArea.Root>
   );
-};
+});
 
-SettingsContainer.displayName = SETTINGS_CONTAINER_NAME;
+SettingsViewport.displayName = SETTINGS_VIEWPORT_NAME;
 
 //
-// Item
+// Section (title + optional description + children with spacing).
 //
 
-type SettingsItemProps = PropsWithChildren<{
+type SettingsSectionProps = PropsWithChildren<{
   title: Label;
   description?: Label;
 }>;
 
-const SettingsItem = ({ title, description = '', children }: SettingsItemProps) => {
-  const { t } = useTranslation(translationKey);
-
-  return (
-    <SettingsContainer classNames={styles.grid}>
-      <h3 className={mx(styles.title, 'md:col-span-2')}>{toLocalizedString(title, t)}</h3>
-      <p className={styles.description}>{toLocalizedString(description, t)}</p>
-      <div role='none' className='overflow-hidden text-end py-1'>
-        {children}
-      </div>
-    </SettingsContainer>
-  );
-};
-
-SettingsItem.displayName = SETTINGS_ITEM_NAME;
-
-//
-// Item Input
-//
-
-const SettingsItemInput = ({ title, description = '', children }: SettingsItemProps) => {
+const SettingsSection = ({ title, description, children }: SettingsSectionProps) => {
   const { t } = useTranslation(translationKey);
-
   return (
-    <Input.Root>
-      <SettingsContainer classNames={styles.grid}>
-        <Input.Label classNames={mx(styles.title, 'md:col-span-2')}>{toLocalizedString(title, t)}</Input.Label>
-        <Input.DescriptionAndValidation>
-          <Input.Description classNames={styles.description}>{toLocalizedString(description, t)}</Input.Description>
-        </Input.DescriptionAndValidation>
-        <div role='none' className='text-end py-1'>
-          {children}
-        </div>
-      </SettingsContainer>
-    </Input.Root>
+    <>
+      <h2 className='px-trim-md mt-trim-md text-xl'>{toLocalizedString(title, t)}</h2>
+      {description && <p className='px-trim-md text-description'>{toLocalizedString(description, t)}</p>}
+      <div className='w-full pt-trim-md space-y-trim-md'>{children}</div>
+    </>
   );
 };
 
-SettingsItemInput.displayName = SETTINGS_ITEM_INPUT_NAME;
+SettingsSection.displayName = SETTINGS_SECTION_NAME;
 
 //
 // Settings
@@ -218,13 +72,9 @@ SettingsItemInput.displayName = SETTINGS_ITEM_INPUT_NAME;
 
 export const Settings = {
   Root: SettingsRoot,
+  Viewport: SettingsViewport,
   Section: SettingsSection,
-  SectionHeading: SettingsSectionHeading,
-  Group: SettingsGroup,
-  GroupButton: SettingsGroupButton,
-  Container: SettingsContainer,
-  Frame: SettingsFrame,
-  FrameItem: SettingsFrameItem,
+  Panel: SettingsPanel,
   Item: SettingsItem,
-  ItemInput: SettingsItemInput,
+  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,58 @@
+//
+// 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 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-foreground 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 className='text-end py-1'>{children}</div>
+      </SettingsPanel>
+    </Input.Root>
+  );
+};
+
+SettingsItem.displayName = SETTINGS_ITEM_NAME;