@dxos/react-ui-form 0.8.4-main.e8ec1fe → 0.8.4-main.effb148878

package/src/components/ObjectTree/ObjectTree.stories.tsx

@@ -0,0 +1,134 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { parseProto } from '@dxos/effect-proto';
+import { log } from '@dxos/log';
+import { type Config as ConfigProto, Runtime } from '@dxos/protocols/proto/dxos/config';
+// Raw .proto source resolved through `@dxos/protocols`'s `./proto/dxos/*.proto`
+// exports entry. Vite's `?raw` query suffix returns the file as a string so we
+// can hand it straight to `parseProto` -- the same flow the unit test uses.
+import configProto from '@dxos/protocols/proto/dxos/config.proto?raw';
+import { Syntax } from '@dxos/react-ui-syntax-highlighter';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '#translations';
+
+import { Form } from '../Form';
+import { ObjectTree } from './ObjectTree';
+
+const registry = parseProto(configProto);
+const ConfigSchema = registry.get('dxos.config.Config');
+
+// A representative Config value that exercises nested messages, arrays, enums
+// (rendered as their string names by the proto codec), and `google.protobuf.Any`.
+const value: ConfigProto = {
+  version: 1,
+  runtime: {
+    client: {
+      log: { filter: 'info', prefix: 'app' },
+      storage: {
+        persistent: true,
+        sqliteMode: Runtime.Client.Storage.SqliteMode.OPFS,
+        dataRoot: '/var/lib/dxos',
+      },
+      edgeFeatures: {
+        echoReplicator: true,
+        subductionReplicator: true,
+        signaling: true,
+      },
+      servicesMode: Runtime.Client.ServicesMode.SHARED_WORKER,
+      enableSnapshots: false,
+      snapshotInterval: 60_000,
+    },
+    app: {
+      org: 'DXOS',
+      theme: 'dark',
+      website: 'https://dxos.org',
+      build: {
+        timestamp: '2026-05-22T12:00:00Z',
+        commitHash: 'abc1234',
+        version: '0.8.3',
+        branch: 'main',
+      },
+    },
+    services: {
+      edge: { url: 'wss://edge.dxos.org' },
+      signaling: [
+        { server: 'wss://signal-1.dxos.org', api: 'v1' },
+        { server: 'wss://signal-2.dxos.org', api: 'v1' },
+      ],
+      iceProviders: [{ urls: 'turn:turn.dxos.org' }],
+    },
+    keys: [
+      { name: 'OPENAI_API_KEY', value: 'sk-...' },
+      { name: 'ANTHROPIC_API_KEY', value: 'ant-...' },
+    ],
+  },
+};
+
+const meta = {
+  title: 'ui/react-ui-form/ObjectTree',
+  component: ObjectTree,
+  decorators: [withTheme(), withLayout({ layout: 'column', scroll: true })],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof ObjectTree>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    schema: ConfigSchema,
+    value: value,
+  },
+};
+
+export const JSON = () => (
+  <Syntax.Root data={value}>
+    <Syntax.Content>
+      <Syntax.Filter />
+      <Syntax.Viewport>
+        <Syntax.Code />
+      </Syntax.Viewport>
+    </Syntax.Content>
+  </Syntax.Root>
+);
+
+// Renders the same proto-derived `ConfigSchema` + `value` through the
+// interactive `Form` component, for side-by-side comparison with the
+// read-only ObjectTree above. `db` is intentionally omitted -- the proto
+// schema is not an ECHO type, so there's no space/database in play.
+export const WithForm = () => (
+  <Form.Root
+    schema={ConfigSchema as any}
+    defaultValues={value as any}
+    onSave={(next) => log.info('save', { next })}
+    onCancel={() => log.info('cancel')}
+  >
+    <Form.Viewport>
+      <Form.Content>
+        <Form.FieldSet />
+        <Form.Actions />
+      </Form.Content>
+    </Form.Viewport>
+  </Form.Root>
+);
+
+export const WithReadOnlyForm = () => (
+  <Form.Root schema={ConfigSchema as any} defaultValues={value as any} readonly={true}>
+    <Form.Viewport>
+      <Form.Content>
+        <Form.FieldSet />
+        <Form.Actions />
+      </Form.Content>
+    </Form.Viewport>
+  </Form.Root>
+);

package/src/components/ObjectTree/ObjectTree.tsx

@@ -0,0 +1,190 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// A minimal, read-only schema-driven viewer. Walks an Effect Schema and a
+// matching value and produces a flat list of indented key/value rows -- one
+// per leaf field, with nested Struct fields contributing a header row plus
+// recursively-indented children, and arrays expanded as `[index]` rows.
+//
+// Designed to drive a hierarchical editor over schemas produced by
+// `@dxos/effect-proto` (e.g. the proto-generated `dxos.config.Config`
+// schema), but works for any Effect Struct schema.
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+import React, { type ReactElement, type ReactNode, type RefAttributes } from 'react';
+
+import { composable, composableProps } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+import { type ComposableProps } from '@dxos/ui-types';
+
+export type ObjectTreeProps<T> = {
+  schema: Schema.Schema<T, any, never>;
+  value: T;
+};
+
+/**
+ * Render a value as a sequence of key/value rows whose shape and order are
+ * driven by `schema`. Object-typed properties become a header row whose
+ * children are indented under it; arrays expand element-by-element.
+ *
+ * Composable: spreads unknown props (incl. `className` / `classNames` /
+ * `style` / `role`) onto its root `<div>` and forwards its ref, so it can
+ * be slotted into themed parents like `Panel.Content`.
+ */
+const ObjectTreeImpl = composable<HTMLDivElement, ObjectTreeProps<any>>(({ schema, value, ...props }, forwardedRef) => (
+  <div {...composableProps(props, { role: 'table', classNames: 'font-mono text-sm w-full' })} ref={forwardedRef}>
+    <Node ast={schema.ast} value={value} label={null} depth={0} />
+  </div>
+));
+
+ObjectTreeImpl.displayName = 'ObjectTree';
+
+// `composable<HTMLDivElement, ObjectTreeProps<any>>` erases the `T` type
+// parameter inside the factory; the cast restores the generic signature for
+// consumers without changing the underlying component (the COMPOSABLE marker
+// stays attached). This is the pattern documented on `composable()` itself.
+export const ObjectTree = ObjectTreeImpl as unknown as <T>(
+  props: ComposableProps<ObjectTreeProps<T>> & RefAttributes<HTMLDivElement>,
+) => ReactElement | null;
+
+/**
+ * Peel wrappers that don't affect the runtime shape: Refinements pass their
+ * `from`, Suspends resolve via `f()`, and Transformations expose the encoded
+ * (input) side. Repeated unwrapping handles chains like `Schema.suspend ->
+ * Refinement -> TypeLiteral`.
+ */
+const unwrap = (ast: SchemaAST.AST): SchemaAST.AST => {
+  if (SchemaAST.isRefinement(ast)) {
+    return unwrap(ast.from);
+  }
+  if (SchemaAST.isSuspend(ast)) {
+    return unwrap(ast.f());
+  }
+  if (SchemaAST.isTransformation(ast)) {
+    return unwrap(ast.from);
+  }
+  return ast;
+};
+
+/**
+ * Effect models `Schema.optional(X)` as a property whose type AST is
+ * `Union(X, UndefinedKeyword)`. For walking purposes we want X -- the
+ * undefined branch carries no schema information for the viewer.
+ */
+const stripOptional = (ast: SchemaAST.AST): SchemaAST.AST => {
+  if (!SchemaAST.isUnion(ast)) {
+    return ast;
+  }
+  const nonUndef = ast.types.filter((t) => !SchemaAST.isUndefinedKeyword(t));
+  return nonUndef.length === 1 ? nonUndef[0] : ast;
+};
+
+type NodeProps = {
+  ast: SchemaAST.AST;
+  value: unknown;
+  /** Row label; `null` means render children directly without a header row. */
+  label: ReactNode | null;
+  depth: number;
+};
+
+const Node = ({ ast, value, label, depth }: NodeProps) => {
+  const inner = unwrap(stripOptional(ast));
+
+  // Struct: header row + indented children. Skipping the header at depth 0
+  // keeps the root flush-left.
+  if (SchemaAST.isTypeLiteral(inner) && isPlainObject(value)) {
+    const childDepth = label === null ? depth : depth + 1;
+    return (
+      <>
+        {label !== null && <Row label={label} value={null} depth={depth} kind='group' />}
+        {inner.propertySignatures.map((prop) => (
+          <Node
+            key={String(prop.name)}
+            ast={prop.type}
+            value={(value as Record<string, unknown>)[String(prop.name)]}
+            label={String(prop.name)}
+            depth={childDepth}
+          />
+        ))}
+      </>
+    );
+  }
+
+  // Array (`Schema.Array(X)` -> TupleType with single rest element).
+  if (SchemaAST.isTupleType(inner) && Array.isArray(value)) {
+    const elemType = inner.rest[0]?.type;
+    return (
+      <>
+        {label !== null && <Row label={label} value={`Array(${value.length})`} depth={depth} kind='group' />}
+        {value.map((item, index) => (
+          <Node
+            key={index}
+            ast={elemType ?? SchemaAST.unknownKeyword}
+            value={item}
+            label={`[${index}]`}
+            depth={depth + 1}
+          />
+        ))}
+      </>
+    );
+  }
+
+  // Leaf (scalars, unions of literals, unknown, etc.).
+  return <Row label={label ?? ''} value={formatLeaf(value)} depth={depth} kind='leaf' />;
+};
+
+type RowProps = {
+  label: ReactNode;
+  value: ReactNode;
+  depth: number;
+  kind: 'group' | 'leaf';
+};
+
+const Row = ({ label, value, depth }: RowProps) => (
+  <div role='row' className={mx('flex items-baseline gap-3 py-1')} style={{ paddingInlineStart: 8 + depth * 16 }}>
+    <div role='cell' className='text-subdued'>
+      {label}
+    </div>
+    <div role='cell' className={mx('break-all text-base-foreground')}>
+      {value}
+    </div>
+  </div>
+);
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * Format a leaf value for display. Strings are quoted so empty strings are
+ * visible; missing values surface as an em-dash so the row stays present.
+ */
+const formatLeaf = (value: unknown): ReactNode => {
+  if (value === undefined) {
+    return null;
+  }
+
+  if (value === null) {
+    return <span className='text-description'>null</span>;
+  }
+
+  switch (typeof value) {
+    case 'string':
+      // Quote strings so empty strings remain visible (`""` rather than blank).
+      return <span className='text-blue-text'>{JSON.stringify(value)}</span>;
+    case 'number':
+    case 'bigint':
+      return <span className='text-green-text'>{String(value)}</span>;
+    case 'boolean':
+      return <span className='text-purple-text'>{String(value)}</span>;
+    default:
+      // Objects we couldn't expand via schema (e.g. `google.protobuf.Any` -> Unknown)
+      // are rendered as compact JSON.
+      try {
+        return JSON.stringify(value);
+      } catch {
+        return String(value);
+      }
+  }
+};

package/src/components/ObjectTree/index.ts

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

package/src/components/Settings/AUDIT.md

@@ -0,0 +1,51 @@
+# Plugin Settings Audit
+
+Tracks which plugin settings panels use schema-driven `Settings.FieldSet` and which still hand-roll their controls.
+
+The target shape for a plugin settings panel is:
+
+```tsx
+<SettingsForm.Viewport>
+  <SettingsForm.Section title={t('settings.title', { ns: meta.id })}>
+    <SettingsForm.FieldSet
+      readonly={!onSettingsChange}
+      schema={Settings.Settings}
+      values={settings}
+      onValuesChanged={(values) => onSettingsChange?.(() => values)}
+    />
+  </SettingsForm.Section>
+</SettingsForm.Viewport>
+```
+
+Field labels and descriptions come from `.annotations({ title, description })` on each schema field. Use `fieldMap` for runtime-driven option lists (model pickers, etc.). Use the `visible` callback to gate fields on environment or sibling values.
+
+## FieldSet adopters
+
+| Plugin                 | Notes                                                                                                    |
+| ---------------------- | -------------------------------------------------------------------------------------------------------- |
+| `plugin-assistant`     | Nested `modelDefaults` struct; `fieldMap` provides per-provider model selectors via `createSelectField`. |
+| `plugin-crx`           | Two booleans.                                                                                            |
+| `plugin-deck`          | Five booleans; `enableNativeRedirect` hidden via `visible` when `isSocket`.                              |
+| `plugin-inbox`         | Single boolean.                                                                                          |
+| `plugin-markdown`      | Original reference adopter. `snippets` text field gated via `visible`/`fieldMap`.                        |
+| `plugin-meeting`       | Single boolean.                                                                                          |
+| `plugin-observability` | Boolean; info `Message.Root` banner kept above `FieldSet`.                                               |
+| `plugin-presenter`     | Single boolean.                                                                                          |
+| `plugin-sample`        | Single boolean.                                                                                          |
+| `plugin-script`        | Mixed: auth `Button` retained as a manual `SettingsForm.Item`; `editorInputMode` rendered by `FieldSet`. |
+| `plugin-sketch`        | Boolean + `gridType` literal union (rendered as a Select — was previously a Switch).                     |
+
+## Skipped
+
+| Plugin             | Reason                                                                                                                                                               |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `plugin-debug`     | Action buttons (download diagnostics, download logs, repair), `Toast`, and a storage-adapter selector wired to `client.config` rather than the plugin settings atom. |
+| `plugin-space`     | Renders a list of spaces with per-space "open settings" buttons — not bound to any schema field.                                                                     |
+| `plugin-spacetime` | Section is currently empty; nothing to render.                                                                                                                       |
+| `plugin-thread`    | Settings schema is `Schema.Struct({})` — nothing to render.                                                                                                          |
+
+## When to extend `SettingsFieldSet` vs. add a custom field
+
+- **Extend `SettingsFieldSet`** when the rendering rule applies generally to a schema construct (e.g. nested structs recursing into sibling fields, literal unions becoming Selects). Keep auto-detection in `detectFieldType`.
+- **Use `fieldMap`** when the schema can't fully describe the rendering — runtime-driven option lists, custom inputs, or override of the auto-rendered control. Use the typed form `SettingsFieldMap<T>` (or `satisfies SettingsFieldMap<Settings>`) so the entries are checked against the values shape.
+- **Drop back to manual `SettingsForm.Item`** when the panel needs UI that isn't bound to a settings field at all (action buttons, info banners, lists of external entities). These coexist as siblings of `FieldSet` inside the same `Section`.

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

@@ -0,0 +1,104 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Schema from 'effect/Schema';
+import React from 'react';
+
+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 { Settings } from './Settings';
+
+random.seed(132);
+
+const DefaultStory = () => {
+  return (
+    <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.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>
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-form/Settings',
+  render: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta;
+
+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

@@ -0,0 +1,81 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { type PropsWithChildren } from 'react';
+
+import { type Label, ScrollArea, type ThemedClassName, toLocalizedString, useTranslation } from '@dxos/react-ui';
+import { composable, composableProps } from '@dxos/react-ui';
+import { 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';
+
+//
+// Root (headless — no styling, no scroll).
+//
+
+type SettingsRootProps = ThemedClassName<PropsWithChildren>;
+
+const SettingsRoot = ({ children, classNames }: SettingsRootProps) => {
+  return <div className={mx('flex flex-col gap-2', classNames)}>{children}</div>;
+};
+
+SettingsRoot.displayName = SETTINGS_ROOT_NAME;
+
+//
+// Viewport (scroll area + padding + document layout).
+//
+
+const SettingsViewport = composable<HTMLDivElement>(({ children, ...props }, forwardedRef) => {
+  return (
+    <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>
+  );
+});
+
+SettingsViewport.displayName = SETTINGS_VIEWPORT_NAME;
+
+//
+// Section (title + optional description + children with spacing).
+//
+
+type SettingsSectionProps = PropsWithChildren<{
+  title: Label;
+  description?: Label;
+}>;
+
+const SettingsSection = ({ title, description, children }: SettingsSectionProps) => {
+  const { t } = useTranslation(translationKey);
+  return (
+    <>
+      <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>
+    </>
+  );
+};
+
+SettingsSection.displayName = SETTINGS_SECTION_NAME;
+
+//
+// Settings
+//
+
+export const Settings = {
+  Root: SettingsRoot,
+  Viewport: SettingsViewport,
+  Section: SettingsSection,
+  Panel: SettingsPanel,
+  Item: SettingsItem,
+  FieldSet: SettingsFieldSet,
+};