@dxos/react-ui-form 0.8.4-main.fd6878d → 0.8.4-staging.60fe92afc8

package/src/components/RefEditor/RefEditor.tsx

@@ -0,0 +1,275 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Extension, Prec } from '@codemirror/state';
+import { type EditorView } from '@codemirror/view';
+import React, { forwardRef, useCallback, useEffect, useMemo, useRef } from 'react';
+
+import { type Database, Filter, Obj, type Type } from '@dxos/echo';
+import { useQuery } from '@dxos/react-client/echo';
+import { type ThemedClassName, useThemeContext, useTranslation } from '@dxos/react-ui';
+import {
+  Editor,
+  type EditorController,
+  type EditorMenuProviderProps,
+  type EditorViewProps,
+  type UseEditorMenuProps,
+} from '@dxos/react-ui-editor';
+import { createBasicExtensions, createThemeExtensions, insertAtCursor, keymap } from '@dxos/ui-editor';
+import { getHashHue } from '@dxos/ui-theme';
+
+import { translationKey } from '#translations';
+
+import {
+  EMAIL_REGEX,
+  NAME_ADDR_REGEX,
+  type RefEditorMode,
+  type RefInfo,
+  formatMailbox,
+  refEditor,
+  refEditorRedecorate,
+} from './ref-editor-extension';
+
+export type RefEditorProps = ThemedClassName<
+  {
+    /** Database queried for objects of {@link RefEditorProps.type}. */
+    db?: Database.Database;
+    /** ECHO object type whose instances are offered in the typeahead and referenced as `@<id>`. */
+    type: Type.AnyObj;
+    value?: string;
+    readonly?: boolean;
+    /**
+     * Content model:
+     * - `'ref'` (default): the picker only matches existing objects; selection inserts an
+     *   `@<id>` reference (raw tokens accepted by `match` are also allowed).
+     * - `'email'`: the picker shows one item per (object, value) pair and selection captures the
+     *   value; the content is an RFC 5322 mailbox list (`Name <email>, ...`) with the comma
+     *   separators hidden inside the tags.
+     */
+    mode?: RefEditorMode;
+    /** Pluggable raw-token matcher (e.g. {@link EMAIL_REGEX}); matching tokens are accepted as values. */
+    match?: RegExp;
+    /** Display label for an object; defaults to `Obj.getLabel` falling back to the id. */
+    getLabel?: (object: Obj.Unknown) => string;
+    /** Values an object can be captured as in `'email'` mode (e.g. a person's email addresses). */
+    getValues?: (object: Obj.Unknown) => readonly string[];
+    /** Menu item icon. */
+    icon?: string;
+    /** Already-translated placeholder; defaults to a generic hint. */
+    placeholder?: string;
+    /** Open the typeahead while typing (the `@` trigger remains available but is not required). */
+    activateOnTyping?: boolean;
+  } & Omit<EditorViewProps, 'initialValue'> &
+    Pick<EditorMenuProviderProps, 'numItems'>
+>;
+
+/**
+ * Single-line input for a list of object references. Typing `@` (or any text, with
+ * `activateOnTyping`) opens a typeahead menu matching objects of the given type by label (and
+ * by their `getValues` values). The content model depends on {@link RefEditorProps.mode}.
+ * Resolved entries render as atomic tags with the object's label; raw tokens accepted by the
+ * pluggable `match` regexp render as neutral tags.
+ */
+export const RefEditor = forwardRef<EditorController, RefEditorProps>(
+  (
+    {
+      db,
+      type,
+      value,
+      readonly,
+      mode = 'ref',
+      match,
+      getLabel,
+      getValues,
+      icon = 'ph--link--regular',
+      placeholder: placeholderProp,
+      activateOnTyping,
+      numItems = 8,
+      ...props
+    },
+    forwardedRef,
+  ) => {
+    const { t } = useTranslation(translationKey);
+    const { themeMode } = useThemeContext();
+    const getObjectLabel = useCallback(
+      (object: Obj.Unknown) => getLabel?.(object) ?? Obj.getLabel(object) ?? object.id,
+      [getLabel],
+    );
+
+    // Reads go through a ref so the decoration extension stays stable: recreating extensions
+    // destroys and recreates the editor, which would blur the input on data changes.
+    const filter = useMemo(() => Filter.type(type), [type]);
+    const objects = useQuery(db, filter);
+    const refs = useMemo(
+      () =>
+        new Map<string, RefInfo>(
+          objects.map((object) => [object.id, { label: getObjectLabel(object), hue: getHashHue(object.id) }]),
+        ),
+      [objects, getObjectLabel],
+    );
+    const refsRef = useRef(refs);
+    refsRef.current = refs;
+
+    // Internal controller (merged with the forwarded ref) used to re-resolve reference
+    // decorations when object data changes after the document was rendered.
+    const controllerRef = useRef<EditorController | null>(null);
+    const composedRef = useCallback(
+      (controller: EditorController | null) => {
+        controllerRef.current = controller;
+        if (typeof forwardedRef === 'function') {
+          forwardedRef(controller);
+        } else if (forwardedRef) {
+          forwardedRef.current = controller;
+        }
+      },
+      [forwardedRef],
+    );
+    useEffect(() => {
+      controllerRef.current?.view?.dispatch({ effects: refEditorRedecorate.of(null) });
+    }, [refs]);
+
+    const getMenu = useCallback<NonNullable<UseEditorMenuProps['getMenu']>>(
+      async ({ text }) => {
+        const query = (text ?? '').replace(/^@/, '').toLowerCase();
+        const matchesQuery = (object: Obj.Unknown) =>
+          !query ||
+          getObjectLabel(object).toLowerCase().includes(query) ||
+          (getValues?.(object) ?? []).some((entry) => entry.toLowerCase().includes(query));
+
+        if (mode === 'email') {
+          // One item per (object, value) pair; selection captures the value as an RFC 5322 mailbox.
+          const mailboxes = objects
+            .flatMap((object) => (getValues?.(object) ?? []).map((entry) => ({ object, entry })))
+            .filter(
+              ({ object, entry }) =>
+                !query || getObjectLabel(object).toLowerCase().includes(query) || entry.toLowerCase().includes(query),
+            );
+
+          return [
+            {
+              id: 'mailboxes',
+              items: mailboxes.slice(0, numItems * 2).map(({ object, entry }) => ({
+                id: `${object.id}-${entry}`,
+                label: `${getObjectLabel(object)} (${entry})`,
+                icon,
+                onSelect: ({ view, head }: { view: EditorView; head: number }) =>
+                  insertMailbox(view, head, formatMailbox(getObjectLabel(object), entry)),
+              })),
+            },
+          ];
+        }
+
+        // 'ref' mode: only match existing objects.
+        return [
+          {
+            id: 'refs',
+            items: objects
+              .filter(matchesQuery)
+              .slice(0, numItems * 2)
+              .map((object) => {
+                const label = getObjectLabel(object);
+                const detail = getValues?.(object)?.[0];
+                return {
+                  id: object.id,
+                  label: detail && detail !== label ? `${label} (${detail})` : label,
+                  icon,
+                  onSelect: ({ view, head }: { view: EditorView; head: number }) =>
+                    insertAtCursor(view, head, `@${object.id} `),
+                };
+              }),
+          },
+        ];
+      },
+      [objects, numItems, mode, icon, getObjectLabel, getValues],
+    );
+
+    // NOTE: The placeholder is supplied via the popover (Editor.Root) so the trigger hint and the
+    // empty-state hint are a single message; a second basic-extension placeholder would stack with it.
+    // Must be referentially stable: the menu extension is memoized on it, and a new extension
+    // identity destroys and recreates the editor on every keystroke.
+    const placeholder = useMemo(
+      () => ({
+        content: placeholderProp ?? t(activateOnTyping ? 'ref-editor-auto.placeholder' : 'ref-editor.placeholder'),
+        focusOnly: false,
+      }),
+      [t, placeholderProp, activateOnTyping],
+    );
+
+    const extensions = useMemo<Extension[]>(
+      () => [
+        createBasicExtensions({ readOnly: readonly, lineWrapping: false }),
+        createThemeExtensions({ themeMode, slots: { scroller: { className: 'scrollbar-none' } } }),
+        refEditor({ mode, match, getRef: (id) => refsRef.current.get(id) }),
+        Prec.highest(
+          keymap.of([
+            {
+              key: 'Enter',
+              // Commit the in-progress token when it matches (insert the mode's separator, the
+              // same gesture as typing it); always consume the key (single-line input).
+              run: (view) => {
+                const { head } = view.state.selection.main;
+                const line = view.state.doc.lineAt(head);
+                const before = line.text.slice(0, head - line.from);
+                if (mode === 'email') {
+                  const segment = before.slice(before.lastIndexOf(',') + 1).trim();
+                  if (NAME_ADDR_REGEX.test(segment) || (match ?? EMAIL_REGEX).test(segment)) {
+                    insertAtCursor(view, head, ', ');
+                  }
+                } else {
+                  const token = before.slice(before.search(/\S+$/));
+                  if (token && match?.test(token)) {
+                    insertAtCursor(view, head, ' ');
+                  }
+                }
+                return true;
+              },
+            },
+          ]),
+        ),
+      ],
+      [readonly, themeMode, mode, match],
+    );
+
+    return (
+      <Editor.Root
+        extensions={extensions}
+        numItems={numItems}
+        trigger='@'
+        activateOnTyping={activateOnTyping}
+        placeholder={placeholder}
+        // The menu owns its own matching (labels AND values); the built-in label filter would
+        // drop value-matched objects whose label doesn't start with the query.
+        filter={false}
+        getMenu={getMenu}
+        ref={composedRef}
+      >
+        <Editor.View
+          // TOOD(burdon): Use same style as react-ui Input.
+          classNames='border border-separator rounded-xs px-2'
+          {...props}
+          initialValue={value}
+          selectionEnd
+        />
+      </Editor.Root>
+    );
+  },
+);
+
+RefEditor.displayName = 'RefEditor';
+
+/**
+ * Insert an RFC 5322 mailbox, replacing the in-progress segment (anything typed after the last
+ * comma — multi-word queries can leave words outside the popover's completion range).
+ */
+const insertMailbox = (view: EditorView, head: number, mailbox: string) => {
+  const line = view.state.doc.lineAt(head);
+  const before = line.text.slice(0, head - line.from);
+  const lastComma = before.lastIndexOf(',');
+  const from = line.from + (lastComma === -1 ? 0 : lastComma + 1);
+  const insert = `${lastComma === -1 ? '' : ' '}${mailbox}, `;
+  view.dispatch({
+    changes: { from, to: head, insert },
+    selection: { anchor: from + insert.length, head: from + insert.length },
+  });
+};

package/src/components/RefEditor/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './RefEditor';
+export * from './ref-editor-extension';

package/src/components/RefEditor/ref-editor-extension.ts

@@ -0,0 +1,254 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type EditorState, type Extension, RangeSetBuilder, StateEffect, StateField } from '@codemirror/state';
+import { Decoration, type DecorationSet, EditorView, WidgetType } from '@codemirror/view';
+
+import { Domino } from '@dxos/ui';
+import { getHashHue, getStyles, mx } from '@dxos/ui-theme';
+
+/**
+ * Display info for a resolved object reference.
+ */
+export type RefInfo = {
+  label: string;
+  hue?: string;
+};
+
+/**
+ * Content model:
+ * - `'ref'`: whitespace-separated tokens; `@<id>` references to existing objects (and raw tokens
+ *   accepted by the pluggable {@link RefEditorExtensionOptions.match} regexp).
+ * - `'email'`: comma-separated RFC 5322 mailboxes (`Name <email>` or bare `email`); the comma
+ *   separators are consumed into the atomic tags so they are not visible.
+ */
+export type RefEditorMode = 'ref' | 'email';
+
+export type RefEditorExtensionOptions = {
+  mode?: RefEditorMode;
+  /** Resolve an object id referenced as `@<id>` to display info. */
+  getRef?: (id: string) => RefInfo | undefined;
+  /** Pluggable raw-token matcher (e.g. {@link EMAIL_REGEX}); matching tokens render as neutral tags. */
+  match?: RegExp;
+};
+
+/** Matches an object reference token (`@<object id>`). */
+export const REF_REGEX = /^@([A-Za-z0-9]+)$/;
+
+/** Matches a well-formed email address token. */
+export const EMAIL_REGEX = /^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/;
+
+/** Matches an RFC 5322 name-addr (`Name <email>`); group 1 = display name, group 2 = addr-spec. */
+export const NAME_ADDR_REGEX = /^(.*?)\s*<([A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,})>$/;
+
+/** Formats an RFC 5322 mailbox (`Name <email>`). */
+export const formatMailbox = (name: string | undefined, email: string): string => (name ? `${name} <${email}>` : email);
+
+/**
+ * Effect dispatched when reference data changes out-of-band (e.g. objects finish loading) so that
+ * already-rendered reference decorations re-resolve without a document change.
+ */
+export const refEditorRedecorate = StateEffect.define<null>();
+
+/**
+ * CodeMirror extension rendering reference-editor tokens as tags. Tags are atomic: the cursor
+ * cannot enter them and deletion removes the whole token.
+ * - `'ref'` mode: `@<id>` references resolve to the object's label (via
+ *   {@link RefEditorExtensionOptions.getRef}); tokens accepted by the pluggable `match` regexp
+ *   render as neutral tags.
+ * - `'email'` mode: RFC 5322 mailboxes render as tags labelled with the display name (falling
+ *   back to the address); the trailing comma separator is hidden inside the tag's atomic range.
+ */
+export const refEditor = ({ mode = 'ref', getRef, match }: RefEditorExtensionOptions = {}): Extension => {
+  const buildRefDecorations = (state: EditorState) => {
+    const deco = new RangeSetBuilder<Decoration>();
+    const text = state.doc.toString();
+    const tokenRegex = /\S+/g;
+    let tokenMatch: RegExpExecArray | null;
+    while ((tokenMatch = tokenRegex.exec(text))) {
+      const token = tokenMatch[0];
+      const from = tokenMatch.index;
+      const to = from + token.length;
+
+      const refMatch = token.match(REF_REGEX);
+      if (refMatch) {
+        const ref = getRef?.(refMatch[1]);
+        if (ref) {
+          deco.add(
+            from,
+            to,
+            Decoration.widget({
+              widget: new RefWidget(ref.label, ref.hue ?? getHashHue(refMatch[1])),
+              atomic: true,
+            }),
+          );
+        }
+        continue;
+      }
+
+      if (match?.test(token)) {
+        deco.add(
+          from,
+          to,
+          Decoration.widget({
+            widget: new TokenWidget(token),
+            atomic: true,
+          }),
+        );
+      }
+    }
+
+    return deco.finish();
+  };
+
+  const buildEmailDecorations = (state: EditorState) => {
+    const addrRegex = match ?? EMAIL_REGEX;
+    const deco = new RangeSetBuilder<Decoration>();
+    const text = state.doc.toString();
+    // Segments are comma-separated; a segment's atomic range includes its trailing comma (and
+    // following whitespace) so the separator never renders.
+    const segmentRegex = /[^,]+(?:,\s*)?|,\s*/g;
+    let segmentMatch: RegExpExecArray | null;
+    while ((segmentMatch = segmentRegex.exec(text))) {
+      const segment = segmentMatch[0];
+      const commaIndex = segment.indexOf(',');
+      const content = (commaIndex === -1 ? segment : segment.slice(0, commaIndex)).trim();
+      if (!content) {
+        continue;
+      }
+      const leading = segment.length - segment.trimStart().length;
+      const from = segmentMatch.index + leading;
+      const to = segmentMatch.index + segment.length;
+
+      const nameAddr = content.match(NAME_ADDR_REGEX);
+      if (nameAddr) {
+        deco.add(
+          from,
+          to,
+          Decoration.widget({
+            widget: new RefWidget(nameAddr[1] || nameAddr[2], getHashHue(nameAddr[2])),
+            atomic: true,
+          }),
+        );
+      } else if (addrRegex.test(content)) {
+        deco.add(
+          from,
+          to,
+          Decoration.widget({
+            widget: new TokenWidget(content),
+            atomic: true,
+          }),
+        );
+      }
+    }
+
+    return deco.finish();
+  };
+
+  const buildDecorations = mode === 'email' ? buildEmailDecorations : buildRefDecorations;
+
+  return [
+    styles,
+    StateField.define<DecorationSet>({
+      create: (state) => buildDecorations(state),
+      update: (deco, tr) => {
+        if (tr.docChanged || tr.effects.some((effect) => effect.is(refEditorRedecorate))) {
+          return buildDecorations(tr.state);
+        }
+
+        return deco;
+      },
+      provide: (field) => [
+        EditorView.decorations.from(field),
+        EditorView.atomicRanges.of((view) => {
+          const builder = new RangeSetBuilder<Decoration>();
+          const cursor = view.state.field(field).iter();
+          while (cursor.value) {
+            if (cursor.value.spec.atomic) {
+              builder.add(cursor.from, cursor.to, cursor.value);
+            }
+            cursor.next();
+          }
+
+          return builder.finish();
+        }),
+      ],
+    }),
+  ];
+};
+
+const lineHeight = '30px';
+
+/**
+ * NOTE: The outer container vertically aligns the inner text with content in the outer div.
+ */
+const container = (classNames: string, ...children: Domino<HTMLElement>[]) => {
+  const inner = Domino.of('span')
+    .classNames(mx('inline-flex h-[26px] border rounded-xs', classNames))
+    .append(...children);
+  return Domino.of('span').classNames('inline-flex h-[28px] align-middle').append(inner).root;
+};
+
+/**
+ * Resolved reference (object reference or RFC 5322 mailbox), rendered as the object's label.
+ */
+class RefWidget extends WidgetType {
+  constructor(
+    private readonly _label: string,
+    private readonly _hue: string,
+  ) {
+    super();
+  }
+
+  override eq(other: this) {
+    return this._label === other._label && this._hue === other._hue;
+  }
+
+  override toDOM() {
+    const { bg: fill, border, surface } = getStyles(this._hue);
+    return container(
+      border,
+      Domino.of('span').classNames(mx('flex items-center px-1 text-black text-xs', fill)).text('@'),
+      Domino.of('span')
+        .classNames(mx('flex items-center px-1 text-subdued text-sm rounded-r-[3px]', surface))
+        .text(this._label),
+    );
+  }
+}
+
+/**
+ * Raw token accepted by the pluggable matcher (e.g. an email address).
+ */
+class TokenWidget extends WidgetType {
+  constructor(private readonly _token: string) {
+    super();
+  }
+
+  override eq(other: this) {
+    return this._token === other._token;
+  }
+
+  override toDOM() {
+    return container(
+      'border-separator',
+      Domino.of('span').classNames('flex items-center px-1 text-subdued text-sm').text(this._token),
+    );
+  }
+}
+
+const styles = EditorView.theme({
+  '.cm-line': {
+    lineHeight,
+  },
+  // Match the standard Input block size (md density): 2.5rem, 2rem on pointer-fine devices.
+  '.cm-scroller': {
+    alignItems: 'center',
+    minHeight: '2.5rem',
+  },
+  '@media (pointer: fine)': {
+    '.cm-scroller': {
+      minHeight: '2rem',
+    },
+  },
+});

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,
+};