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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/react-ui-form",
-  "version": "0.8.4-main.9be5663bfe",
+  "version": "0.8.4-main.abd8ff62ef",
   "description": "Data components.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -11,54 +11,55 @@
   "license": "MIT",
   "author": "DXOS.org",
   "type": "module",
+  "imports": {
+    "#translations": "./src/translations.ts"
+  },
   "exports": {
     ".": {
       "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs",
       "node": "./dist/lib/node-esm/index.mjs"
+    },
+    "./translations": {
+      "source": "./src/translations.ts",
+      "types": "./dist/types/src/translations.d.ts",
+      "browser": "./dist/lib/browser/translations.mjs",
+      "node": "./dist/lib/node-esm/translations.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {}
-  },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "@atlaskit/pragmatic-drag-and-drop": "1.7.7",
-    "@atlaskit/pragmatic-drag-and-drop-hitbox": "1.1.0",
     "@effect-atom/atom-react": "^0.5.0",
     "@fluentui/react-tabster": "9.26.11",
     "@radix-ui/react-context": "1.1.1",
     "@radix-ui/react-use-controllable-state": "1.1.0",
     "date-fns": "^3.6.0",
     "tabster": "^8.5.5",
-    "@dxos/debug": "0.8.4-main.9be5663bfe",
-    "@dxos/echo": "0.8.4-main.9be5663bfe",
-    "@dxos/app-toolkit": "0.8.4-main.9be5663bfe",
-    "@dxos/async": "0.8.4-main.9be5663bfe",
-    "@dxos/echo-query": "0.8.4-main.9be5663bfe",
-    "@dxos/effect": "0.8.4-main.9be5663bfe",
-    "@dxos/keys": "0.8.4-main.9be5663bfe",
-    "@dxos/invariant": "0.8.4-main.9be5663bfe",
-    "@dxos/lit-ui": "0.8.4-main.9be5663bfe",
-    "@dxos/log": "0.8.4-main.9be5663bfe",
-    "@dxos/react-ui-components": "0.8.4-main.9be5663bfe",
-    "@dxos/react-client": "0.8.4-main.9be5663bfe",
-    "@dxos/react-ui-editor": "0.8.4-main.9be5663bfe",
-    "@dxos/echo-react": "0.8.4-main.9be5663bfe",
-    "@dxos/react-ui-list": "0.8.4-main.9be5663bfe",
-    "@dxos/react-ui-mosaic": "0.8.4-main.9be5663bfe",
-    "@dxos/react-ui-search": "0.8.4-main.9be5663bfe",
-    "@dxos/react-ui-stack": "0.8.4-main.9be5663bfe",
-    "@dxos/schema": "0.8.4-main.9be5663bfe",
-    "@dxos/react-ui-pickers": "0.8.4-main.9be5663bfe",
-    "@dxos/types": "0.8.4-main.9be5663bfe",
-    "@dxos/ui-types": "0.8.4-main.9be5663bfe",
-    "@dxos/util": "0.8.4-main.9be5663bfe"
+    "@dxos/async": "0.8.4-main.abd8ff62ef",
+    "@dxos/echo": "0.8.4-main.abd8ff62ef",
+    "@dxos/echo-atom": "0.8.4-main.abd8ff62ef",
+    "@dxos/echo-react": "0.8.4-main.abd8ff62ef",
+    "@dxos/effect": "0.8.4-main.abd8ff62ef",
+    "@dxos/invariant": "0.8.4-main.abd8ff62ef",
+    "@dxos/keys": "0.8.4-main.abd8ff62ef",
+    "@dxos/echo-db": "0.8.4-main.abd8ff62ef",
+    "@dxos/lit-ui": "0.8.4-main.abd8ff62ef",
+    "@dxos/react-client": "0.8.4-main.abd8ff62ef",
+    "@dxos/log": "0.8.4-main.abd8ff62ef",
+    "@dxos/react-ui-list": "0.8.4-main.abd8ff62ef",
+    "@dxos/react-ui-pickers": "0.8.4-main.abd8ff62ef",
+    "@dxos/react-ui-components": "0.8.4-main.abd8ff62ef",
+    "@dxos/react-ui-search": "0.8.4-main.abd8ff62ef",
+    "@dxos/schema": "0.8.4-main.abd8ff62ef",
+    "@dxos/types": "0.8.4-main.abd8ff62ef",
+    "@dxos/ui-editor": "0.8.4-main.abd8ff62ef",
+    "@dxos/util": "0.8.4-main.abd8ff62ef",
+    "@dxos/react-ui-editor": "0.8.4-main.abd8ff62ef"
   },
   "devDependencies": {
     "@types/react": "~19.2.7",
@@ -67,20 +68,20 @@
     "fast-check": "^3.19.0",
     "react": "~19.2.3",
     "react-dom": "~19.2.3",
-    "vite": "^7.1.11",
-    "@dxos/random": "0.8.4-main.9be5663bfe",
-    "@dxos/react-client": "0.8.4-main.9be5663bfe",
-    "@dxos/react-ui": "0.8.4-main.9be5663bfe",
-    "@dxos/react-ui-syntax-highlighter": "0.8.4-main.9be5663bfe",
-    "@dxos/storybook-utils": "0.8.4-main.9be5663bfe",
-    "@dxos/ui-theme": "0.8.4-main.9be5663bfe"
+    "vite": "^8.0.10",
+    "@dxos/random": "0.8.4-main.abd8ff62ef",
+    "@dxos/react-client": "0.8.4-main.abd8ff62ef",
+    "@dxos/storybook-utils": "0.8.4-main.abd8ff62ef",
+    "@dxos/react-ui": "0.8.4-main.abd8ff62ef",
+    "@dxos/ui-theme": "0.8.4-main.abd8ff62ef",
+    "@dxos/react-ui-syntax-highlighter": "0.8.4-main.abd8ff62ef"
   },
   "peerDependencies": {
     "effect": "3.20.0",
     "react": "~19.2.3",
     "react-dom": "~19.2.3",
-    "@dxos/react-ui": "0.8.4-main.9be5663bfe",
-    "@dxos/ui-theme": "0.8.4-main.9be5663bfe"
+    "@dxos/ui-theme": "0.8.4-main.abd8ff62ef",
+    "@dxos/react-ui": "0.8.4-main.abd8ff62ef"
   },
   "publishConfig": {
     "access": "public"

package/src/components/FieldEditor/FieldEditor.stories.tsx

@@ -12,7 +12,8 @@ import { withLayout, withTheme } from '@dxos/react-ui/testing';
 import { ProjectionModel, ViewModel, createEchoChangeCallback } from '@dxos/schema';
 import { Example } from '@dxos/schema/testing';
 
-import { translations } from '../../translations';
+import { translations } from '#translations';
+
 import { FIELD_EDITOR_DEBUG_SYMBOL, TestLayout } from '../testing';
 import { FieldEditor, type FieldEditorProps } from './FieldEditor';
 
@@ -70,9 +71,7 @@ const DefaultStory = () => {
 
   return (
     <TestLayout json={json}>
-      <div role='none' className='col-span-full'>
-        <FieldEditor {...props} />
-      </div>
+      <FieldEditor {...props} />
     </TestLayout>
   );
 };

package/src/components/FieldEditor/FieldEditor.tsx

@@ -16,7 +16,8 @@ import {
   getFormatSchema,
 } from '@dxos/schema';
 
-import { translationKey } from '../../translations';
+import { translationKey } from '#translations';
+
 import { getFormProperties } from '../../util';
 import { Form, type FormFieldMap, type FormRootProps, SelectField, SelectOptionField } from '../Form';
 
@@ -151,7 +152,7 @@ export const FieldEditor = ({ readonly, projection, field, registry, view, onSav
   const handleSave = useCallback<NonNullable<FormRootProps<PropertyType>['onSave']>>(
     (props) => {
       if (view) {
-        Obj.change(view, () => {
+        Obj.update(view, () => {
           projection.setFieldProjection({ field, props });
         });
       } else {

package/src/components/Form/Form.stories.tsx

@@ -14,7 +14,8 @@ import { withClientProvider } from '@dxos/react-client/testing';
 import { Tooltip } from '@dxos/react-ui';
 import { Loading, withLayout, withTheme } from '@dxos/react-ui/testing';
 
-import { translations } from '../../translations';
+import { translations } from '#translations';
+
 import { TestLayout } from '../testing';
 import { type ExcludeId, Form, type FormRootProps, omitId } from './Form';
 
@@ -72,8 +73,8 @@ const Person = Schema.Struct({
 export interface Person extends Schema.Schema.Type<typeof Person> {}
 
 type DefaultStoryProps<T extends AnyProperties> = {
+  schema?: Schema.Schema<T>;
   debug?: boolean;
-  schema: Schema.Schema<T>;
 } & FormRootProps<T>;
 
 const DefaultStory = <T extends AnyProperties = AnyProperties>({
@@ -102,7 +103,7 @@ const DefaultStory = <T extends AnyProperties = AnyProperties>({
 
   return (
     <Tooltip.Provider>
-      <TestLayout json={{ values, schema: schema.ast }}>
+      <TestLayout json={{ values, schema: schema?.ast }}>
         <Form.Root
           debug={debug}
           schema={schema}
@@ -129,7 +130,6 @@ const meta = {
   title: 'ui/react-ui-form/Form',
   component: Form.Root,
   render: DefaultStory,
-
   decorators: [
     withTheme(),
     withLayout({ layout: 'fullscreen' }),
@@ -186,16 +186,5 @@ export const Static: Story<ExcludeId<typeof Person>> = {
 };
 
 export const Empty: Story<ExcludeId<typeof Person>> = {
-  render: () => (
-    <TestLayout>
-      <Form.Root>
-        <Form.Viewport>
-          <Form.Content>
-            <Form.FieldSet />
-            <Form.Actions />
-          </Form.Content>
-        </Form.Viewport>
-      </Form.Root>
-    </TestLayout>
-  ),
+  args: {},
 };

package/src/components/Form/Form.tsx

@@ -3,10 +3,12 @@
 //
 
 import { createContext } from '@radix-ui/react-context';
+import * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 import React, { type PropsWithChildren, useEffect, useMemo, useRef } from 'react';
 
+import { Annotation as EchoAnnotation } from '@dxos/echo';
 import { type AnyProperties } from '@dxos/echo/internal';
 import { createJsonPath, getValue as getValue$ } from '@dxos/effect';
 import {
@@ -17,7 +19,9 @@ import {
   useMergeRefs,
   useTranslation,
 } from '@dxos/react-ui';
-import { composable, composableProps, mx } from '@dxos/ui-theme';
+import { composable, composableProps, mx, withColumn } from '@dxos/ui-theme';
+
+import { translationKey } from '#translations';
 
 import {
   type FormHandler,
@@ -26,22 +30,35 @@ import {
   useFormHandler,
   useKeyHandler,
 } from '../../hooks';
-import { translationKey } from '../../translations';
 import { FormFieldLabel, type FormFieldLabelProps, type FormFieldStateProps } from './FormFieldComponent';
 import {
   FormFieldSet as NaturalFormFieldSet,
   type FormFieldSetProps as NaturalFormFieldSetProps,
 } from './FormFieldSet';
 
-// TODO(burdon): Move styles to form.ts.
+// TODO(burdon): Move styles to form.ts (as with ui-theme).
 
-// TODO(burdon): Move to @dxos/schema (re-export here).
+// TODO(burdon): Reconcile with @dxos/echo.
 export type ExcludeId<S extends Schema.Schema.AnyNoContext> = Omit<Schema.Schema.Type<S>, 'id'>;
 
 // TODO(burdon): Move to @dxos/schema (re-export here).
 export const omitId = <S extends Schema.Schema.AnyNoContext>(schema: S): Schema.Schema<ExcludeId<S>, ExcludeId<S>> =>
   schema.pipe(Schema.omit('id')) as any;
 
+/**
+ * Drop fields annotated with `FormInputAnnotation.set(false)` from a schema so
+ * the form's validator doesn't trip on required-but-hidden fields. Used by
+ * the picker's inline create form, where a `FactoryAnnotation` typically
+ * supplies the hidden values (e.g. a backing-object Ref) outside the form.
+ */
+export const omitHiddenFormFields = <S extends Schema.Schema.AnyNoContext>(schema: S): S => {
+  const properties = SchemaAST.getPropertySignatures(schema.ast);
+  const hidden = properties
+    .filter((prop) => Option.getOrElse(EchoAnnotation.FormInputAnnotation.getFromAst(prop.type), () => true) === false)
+    .map((prop) => prop.name as string);
+  return hidden.length === 0 ? schema : (schema.pipe(Schema.omit(...(hidden as [string, ...string[]]))) as any);
+};
+
 //
 // Context
 //
@@ -63,7 +80,7 @@ type FormContextValue<T extends AnyProperties = any> = {
   testId?: string;
 } & Pick<
   NaturalFormFieldSetProps<T>,
-  'readonly' | 'layout' | 'fieldMap' | 'fieldProvider' | 'projection' | 'createTypename' | 'createFieldMap'
+  'readonly' | 'layout' | 'fieldMap' | 'fieldProvider' | 'projection' | 'createTypename' | 'createFieldMap' | 'db'
 >;
 
 const [FormContextProvider, useFormContext] = createContext<FormContextValue>('Form');
@@ -194,7 +211,10 @@ const FormContent = composable<HTMLDivElement, FormContentProps>(({ children, ..
 
   return (
     <div
-      {...composableProps(props, { role: 'form', classNames: 'flex flex-col w-full pb-form-gap' })}
+      {...composableProps(props, {
+        role: 'form',
+        classNames: mx(withColumn.center(), 'flex flex-col w-full pb-form-gap'),
+      })}
       data-testid={testId}
       ref={mergedRef}
     >
@@ -245,7 +265,10 @@ const FormActions = ({ classNames }: FormActionsProps) => {
   //   Deprecate FormSubmit ans use FormActions without Cancel button if no callback is supplied.
 
   return (
-    <div role='none' className={mx('grid grid-flow-col gap-form-gap auto-cols-fr py-form-padding', classNames)}>
+    <div
+      role='none'
+      className={mx(withColumn.center(), 'grid grid-flow-col gap-form-gap auto-cols-fr py-form-padding', classNames)}
+    >
       {onCancel && (
         <IconButton
           icon='ph--x--regular'

package/src/components/Form/FormField.tsx

@@ -23,7 +23,8 @@ import {
 import { useTranslation } from '@dxos/react-ui';
 import { type ProjectionModel } from '@dxos/schema';
 
-import { translationKey } from '../../translations';
+import { translationKey } from '#translations';
+
 import { getRefProps } from '../../util';
 import {
   ArrayField,
@@ -91,7 +92,7 @@ export type FormFieldProps = {
     | 'createInitialValuePath'
     | 'createFieldMap'
     | 'db'
-    | 'schemaHook'
+    | 'useSchema'
     | 'getOptions'
     | 'onCreate'
   >;
@@ -114,7 +115,7 @@ export const FormField = (props: FormFieldProps) => {
     createInitialValuePath,
     createFieldMap,
     db,
-    schemaHook,
+    useSchema: schemaHook,
     getOptions,
     onCreate,
   } = props;
@@ -137,6 +138,7 @@ export const FormField = (props: FormFieldProps) => {
     label,
     placeholder,
     layout,
+    db,
     ...fieldState,
   };
 
@@ -214,7 +216,7 @@ export const FormField = (props: FormFieldProps) => {
         createInitialValuePath={isCreateTarget ? createInitialValuePath : undefined}
         createFieldMap={isCreateTarget ? createFieldMap : undefined}
         db={db}
-        schemaHook={schemaHook}
+        useSchema={schemaHook}
         getOptions={getOptions}
         onCreate={onCreate}
       />
@@ -247,7 +249,7 @@ export const FormField = (props: FormFieldProps) => {
           createOptionIcon={createOptionIcon}
           createInitialValuePath={createInitialValuePath}
           db={db}
-          schemaHook={schemaHook}
+          useSchema={schemaHook}
           getOptions={getOptions}
           onCreate={onCreate}
         />

package/src/components/Form/FormFieldComponent.tsx

@@ -13,6 +13,7 @@ import React, {
   type ReactNode,
 } from 'react';
 
+import { type Database } from '@dxos/echo';
 import { type Format } from '@dxos/echo/internal';
 import { Icon, Input, Tooltip } from '@dxos/react-ui';
 import { inputTextLabel } from '@dxos/ui-theme';
@@ -50,6 +51,8 @@ export type FormFieldComponentProps<T = any> = {
   placeholder?: string;
   autoFocus?: boolean;
   layout?: Presentation;
+  /** Database the form is editing against; populated for fields whose value is an ECHO object/Ref. */
+  db?: Database.Database;
 } & FormFieldStateProps<T>;
 
 /**

package/src/components/Form/FormFieldSet.tsx

@@ -35,7 +35,7 @@ export type FormFieldSetProps<T extends AnyProperties> = {
     | 'createInitialValuePath'
     | 'createFieldMap'
     | 'db'
-    | 'schemaHook'
+    | 'useSchema'
     | 'getOptions'
     | 'onCreate'
   >;
@@ -55,9 +55,7 @@ export const FormFieldSet = ({
   ...props
 }: FormFieldSetProps<any>) => {
   const values = useFormValues(FORM_FIELDSET_NAME, path);
-
   const properties = useFormFieldSetProperties({ schema, values, exclude, sort, projection });
-
   if ((readonly || layout === 'static') && values == null) {
     return null;
   }

package/src/components/Form/fields/ArrayField.tsx

@@ -9,7 +9,8 @@ import React, { useCallback } from 'react';
 import { findNode, getArrayElementType, getDiscriminatedType, isDiscriminatedUnion, isNestedType } from '@dxos/effect';
 import { IconButton, useTranslation } from '@dxos/react-ui';
 
-import { translationKey } from '../../../translations';
+import { translationKey } from '#translations';
+
 import { getFormProperties } from '../../../util';
 import { useFormValues } from '../Form';
 import { FormField, type FormFieldProps } from '../FormField';
@@ -80,7 +81,11 @@ export const ArrayField = ({
       <div role='none' className='flex flex-col gap-form-gap'>
         {values?.map((_, index) => {
           return (
-            <div role='none' key={index} className='flex gap-form-gap last:mb-form-gap items-center'>
+            <div
+              role='none'
+              key={index}
+              className='grid grid-cols-[1fr_min-content] gap-form-gap last:mb-form-gap items-center'
+            >
               <FormField
                 autoFocus={index === values.length - 1}
                 type={elementType}
@@ -114,7 +119,7 @@ export const ArrayField = ({
         <IconButton
           classNames='flex w-full'
           icon='ph--plus--regular'
-          label={t('add-field.button')}
+          label={t('add-item.button')}
           onClick={handleAdd}
         />
       )}

package/src/components/Form/fields/GeoPointField.tsx

@@ -8,7 +8,8 @@ import { GeoLocation, type GeoPoint } from '@dxos/echo/internal';
 import { Input, useTranslation } from '@dxos/react-ui';
 import { safeParseFloat } from '@dxos/util';
 
-import { translationKey } from '../../../translations';
+import { translationKey } from '#translations';
+
 import { type FormFieldComponentProps, FormFieldLabel } from '../FormFieldComponent';
 
 export const GeoPointField = ({

package/src/components/Form/fields/MarkdownField.stories.tsx

@@ -0,0 +1,206 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Schema from 'effect/Schema';
+import React, { useMemo } from 'react';
+import { expect, userEvent } from 'storybook/test';
+
+import { Filter, Format, Obj, Ref } from '@dxos/echo';
+import { useQuery } from '@dxos/react-client/echo';
+import { useClientStory, withClientProvider } from '@dxos/react-client/testing';
+import { Panel } from '@dxos/react-ui';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { Text } from '@dxos/schema';
+
+import { translations } from '#translations';
+
+import { TestLayout } from '../../testing';
+import { Form } from '../Form';
+
+//
+// String-backed markdown.
+//
+
+const StringSchema = Schema.Struct({
+  notes: Schema.String.pipe(Format.FormatAnnotation.set(Format.TypeFormat.Markdown)).annotations({ title: 'Notes' }),
+});
+
+const StringStory = () => (
+  <TestLayout>
+    <Form.Root schema={StringSchema} defaultValues={{ notes: '# Hello\n\nMarkdown text *here*.' }}>
+      <Form.Viewport>
+        <Form.Content>
+          <Form.FieldSet />
+        </Form.Content>
+      </Form.Viewport>
+    </Form.Root>
+  </TestLayout>
+);
+
+//
+// Ref<Text>-backed markdown.
+//
+
+const TextNoteHolder = Schema.Struct({
+  instructions: Ref.Ref(Text.Text)
+    .pipe(Format.FormatAnnotation.set(Format.TypeFormat.Markdown))
+    .annotations({ title: 'Instructions' }),
+});
+
+const RefStory = () => {
+  const { space } = useClientStory();
+  const [text] = useQuery(space?.db, Filter.type(Text.Text));
+  const values = useMemo(() => (text ? { instructions: Ref.make(text) } : undefined), [text]);
+
+  if (!space || !values) {
+    return null;
+  }
+
+  return (
+    <TestLayout>
+      <Panel.Root>
+        <Panel.Content asChild>
+          <Form.Root schema={TextNoteHolder} values={values as any} db={space.db}>
+            <Form.Viewport>
+              <Form.Content>
+                <Form.FieldSet />
+              </Form.Content>
+            </Form.Viewport>
+          </Form.Root>
+        </Panel.Content>
+      </Panel.Root>
+    </TestLayout>
+  );
+};
+
+//
+// Ref<Text> empty — shows the create button.
+//
+
+const EmptyRefSchema = Schema.Struct({
+  instructions: Schema.optional(
+    Ref.Ref(Text.Text)
+      .pipe(Format.FormatAnnotation.set(Format.TypeFormat.Markdown))
+      .annotations({ title: 'Instructions' }),
+  ),
+});
+
+const EmptyRefStory = () => {
+  const { space } = useClientStory();
+  if (!space) {
+    return null;
+  }
+
+  return (
+    <TestLayout>
+      <Panel.Root>
+        <Panel.Content asChild>
+          <Form.Root schema={EmptyRefSchema} defaultValues={{}} db={space.db}>
+            <Form.Viewport>
+              <Form.Content>
+                <Form.FieldSet />
+              </Form.Content>
+            </Form.Viewport>
+          </Form.Root>
+        </Panel.Content>
+      </Panel.Root>
+    </TestLayout>
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-form/MarkdownField',
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const StringBacked: Story = {
+  render: () => <StringStory />,
+};
+
+// Regression test: keystrokes into a string-backed markdown field must not
+// blur the editor. Previously the EditorView was destroyed and recreated on
+// every change because `onChange` was a useTextEditor dep and form callbacks
+// are unstable across renders.
+export const StringBackedKeepsFocus: Story = {
+  render: () => (
+    <TestLayout>
+      <Form.Root schema={StringSchema} defaultValues={{ notes: '' }}>
+        <Form.Viewport>
+          <Form.Content>
+            <Form.FieldSet />
+          </Form.Content>
+        </Form.Viewport>
+      </Form.Root>
+    </TestLayout>
+  ),
+  play: async ({ canvasElement }) => {
+    const waitFor = async <T,>(predicate: () => T | null | undefined, message: string): Promise<T> => {
+      for (let attempt = 0; attempt < 50; attempt++) {
+        const value = predicate();
+        if (value) {
+          return value;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+      }
+      throw new Error(message);
+    };
+
+    const editorRoot = await waitFor(
+      () => canvasElement.querySelector<HTMLElement>('.cm-editor'),
+      'CodeMirror editor root (.cm-editor) not found',
+    );
+    const editorContent = editorRoot.querySelector<HTMLElement>('.cm-content')!;
+    await expect(editorContent).toBeVisible();
+
+    // Focus editor and wait for focus to settle inside the editor root.
+    editorContent.focus();
+    await waitFor(() => (editorRoot.contains(document.activeElement) ? true : null), 'Editor did not receive focus');
+
+    // Type several characters; focus must be preserved inside the editor root
+    // after every keystroke. Regression: previously the EditorView was
+    // destroyed and recreated on every change, which detached the focused
+    // contentDOM and blurred the input.
+    const phrase = 'hello world';
+    for (const ch of phrase) {
+      await userEvent.keyboard(ch);
+      await expect(editorRoot.contains(document.activeElement)).toBe(true);
+    }
+
+    await expect(editorContent).toHaveTextContent(phrase);
+  },
+};
+
+export const RefPopulated: Story = {
+  render: () => <RefStory />,
+  decorators: [
+    withClientProvider({
+      createIdentity: true,
+      createSpace: true,
+      types: [Text.Text],
+      onCreateSpace: async ({ space }) => {
+        space.db.add(Obj.make(Text.Text, { content: '# Magazine brief\n\nLong-form text describing what to gather.' }));
+      },
+    }),
+  ],
+};
+
+export const RefEmpty: Story = {
+  render: () => <EmptyRefStory />,
+  decorators: [
+    withClientProvider({
+      createIdentity: true,
+      createSpace: true,
+      types: [Text.Text],
+    }),
+  ],
+};