@dxos/react-ui-query 0.12.0

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@dxos/react-ui-query",
+  "version": "0.12.0",
+  "description": "Editors for ECHO queries: a query-language input and a type/tag form.",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
+  "license": "FSL-1.1-Apache-2.0",
+  "author": "DXOS.org",
+  "sideEffects": false,
+  "type": "module",
+  "imports": {
+    "#translations": {
+      "source": "./src/translations.ts",
+      "types": "./dist/types/src/translations.d.ts",
+      "default": "./dist/lib/translations.mjs"
+    }
+  },
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/types/src/index.d.ts",
+      "import": "./dist/lib/index.mjs"
+    },
+    "./translations": {
+      "source": "./src/translations.ts",
+      "types": "./dist/types/src/translations.d.ts",
+      "import": "./dist/lib/translations.mjs"
+    }
+  },
+  "types": "dist/types/src/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@codemirror/language": "^6.12.4",
+    "@codemirror/state": "^6.7.4",
+    "@codemirror/view": "^6.43.11",
+    "@lezer/common": "^1.5.2",
+    "@lezer/highlight": "^1.2.3",
+    "json5": "^2.2.3",
+    "@dxos/echo": "0.12.0",
+    "@dxos/keys": "0.12.0",
+    "@dxos/echo-query": "0.12.0",
+    "@dxos/ui-editor": "0.12.0",
+    "@dxos/ui": "0.12.0",
+    "@dxos/react-ui-editor": "0.12.0"
+  },
+  "devDependencies": {
+    "@storybook/react-vite": "^10.6.0",
+    "@types/react": "~19.2.17",
+    "@types/react-dom": "~19.2.3",
+    "effect": "4.0.0",
+    "jsdom": "^29.1.1",
+    "react": "~19.2.7",
+    "react-dom": "~19.2.7",
+    "vite": "^8.2.2",
+    "@dxos/react-client": "0.12.0",
+    "@dxos/react-ui-syntax-highlighter": "0.12.0",
+    "@dxos/react-ui": "0.12.0",
+    "@dxos/ui-theme": "0.12.0",
+    "@dxos/types": "0.12.0"
+  },
+  "peerDependencies": {
+    "effect": "4.0.0",
+    "react": "~19.2.7",
+    "react-dom": "~19.2.7",
+    "@dxos/react-ui": "^0.12.0",
+    "@dxos/ui-theme": "^0.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/components/QueryEditor/QueryEditor.stories.tsx

@@ -0,0 +1,165 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { EditorView } from '@codemirror/view';
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useCallback, useMemo, useState } from 'react';
+import { expect, userEvent, waitFor } from 'storybook/test';
+
+import { type Filter, Tag } from '@dxos/echo';
+import { useClientStory, withClientProvider } from '@dxos/react-client/testing';
+import { Toolbar } from '@dxos/react-ui';
+import { JsonHighlighter } from '@dxos/react-ui-syntax-highlighter';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { Employer, Organization, Person, Pipeline } from '@dxos/types';
+
+import { translations } from '#translations';
+
+import { QueryEditor, type QueryEditorProps } from './QueryEditor.tsx';
+
+// Create tags at render time to avoid Storybook serialization issues with ECHO objects.
+const createTags = (): Tag.Map => ({
+  tag_1: Tag.make({ label: 'Important' }),
+  tag_2: Tag.make({ label: 'Investor' }),
+  tag_3: Tag.make({ label: 'New' }),
+});
+
+const DefaultStory = (args: QueryEditorProps) => {
+  const { space } = useClientStory();
+  const [filter, setFilter] = useState<Filter.Any>();
+  // Create tags and builder at render time to avoid Storybook serialization issues.
+  const tags = useMemo(() => args.tags ?? createTags(), [args.tags]);
+
+  // The editor parses the DSL itself; a story that rebuilt the filter here would be exercising its
+  // own `QueryBuilder` rather than the component's.
+  const handleFilterChange = useCallback<NonNullable<QueryEditorProps['onFilterChange']>>(
+    ({ filter }) => setFilter(filter),
+    [],
+  );
+
+  return (
+    <div className='flex flex-col gap-2'>
+      <Toolbar.Root>
+        <QueryEditor {...args} db={space?.db} tags={tags} onFilterChange={handleFilterChange} />
+      </Toolbar.Root>
+
+      <JsonHighlighter data={filter} classNames='text-xs' />
+    </div>
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-query/QueryEditor',
+  component: QueryEditor,
+  render: (args: QueryEditorProps) => <DefaultStory {...args} />,
+  decorators: [
+    withTheme(),
+    withLayout({ layout: 'column' }),
+    withClientProvider({
+      types: [Organization.Organization, Person.Person, Pipeline.Pipeline, Employer.Employer],
+      createIdentity: true,
+    }),
+  ],
+  parameters: {
+    translations,
+  },
+} satisfies Meta<typeof QueryEditor>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const Complex: Story = {
+  args: {
+    autoFocus: true,
+    value: '#important OR type:org.dxos.type.person AND { title: "DXOS", value: true }',
+  },
+};
+
+export const Relation: Story = {
+  args: {
+    autoFocus: true,
+    value: '(type:org.dxos.type.person -> type:org.dxos.type.organization)',
+  },
+};
+
+export const Tags: Story = {
+  args: {
+    autoFocus: true,
+    value: 'type:org.dxos.type.person #investor #new',
+  },
+  play: async ({ canvasElement }) => {
+    const content = await waitFor(() => {
+      const element = canvasElement.querySelector<HTMLElement>('.cm-content');
+      if (!element) {
+        throw new Error('Query editor content not found.');
+      }
+      return element;
+    });
+
+    // The document, not `textContent`: a type filter is drawn as a widget, so the rendered text is
+    // the chip's label rather than what the document holds.
+    const view = EditorView.findFromDOM(content)!;
+
+    // `selectionEnd` puts the caret at the end of the document on the first render.
+    await waitFor(() => expect(view.state.selection.main.head).toEqual(view.state.doc.length));
+
+    // Which is what makes the first keystroke append rather than land in front of the query.
+    await userEvent.keyboard('X');
+    await waitFor(() => expect(view.state.doc.toString()).toEqual('type:org.dxos.type.person #investor #newX '));
+  },
+};
+
+/**
+ * A tag behaves as a single object: one Backspace or Delete removes the whole chip, and text typed
+ * against either edge is separated from it by a space, with a trailing space always left to type
+ * into. Driven through real keystrokes, since atomicity is enforced by CodeMirror's own cursor and
+ * delete commands rather than by the decorations the unit tests inspect.
+ */
+export const Atomic: Story = {
+  args: {
+    autoFocus: true,
+    value: '#test',
+  },
+  play: async ({ canvasElement }) => {
+    const content = await waitFor(() => {
+      const element = canvasElement.querySelector<HTMLElement>('.cm-content');
+      if (!element) {
+        throw new Error('Query editor content not found.');
+      }
+      return element;
+    });
+
+    // The placeholder renders inside the content element, so an empty document is not empty text.
+    const doc = () => (content.querySelector('.cm-placeholder') ? '' : content.textContent);
+
+    await waitFor(() => expect(doc()).toEqual('#test'));
+
+    // No click and no `{End}`: `selectionEnd` is what puts the caret at the end of the document on
+    // the first render, and the caret at the tag's own edge is still in the tag — so this single
+    // Backspace both proves that and takes the whole chip.
+    // `keyboard`, not `type`: the latter clicks the element first, which would move the caret.
+    await userEvent.keyboard('{Backspace}');
+    await waitFor(() => expect(doc()).toEqual(''));
+
+    // Atomic does not mean uneditable: each character lands outside the replaced range and grows it,
+    // so the tag is still typed a character at a time. The chip renders the label the whole way.
+    await userEvent.keyboard('#te');
+    await waitFor(() => expect(doc()).toEqual('#te '));
+    await userEvent.keyboard('st');
+    await waitFor(() => expect(doc()).toEqual('#test '));
+
+    // Typed text is never glued to a chip, in either direction.
+    await userEvent.keyboard('{Home}X');
+    await waitFor(() => expect(doc()).toEqual('X #test '));
+    await userEvent.keyboard('{End}Y');
+    await waitFor(() => expect(doc()).toEqual('X #test Y '));
+
+    // Two deletes for `X `, then a single one for the whole five-character tag.
+    await userEvent.keyboard('{Home}{Delete}{Delete}{Delete}');
+    await waitFor(() => expect(doc()).toEqual(' Y '));
+  },
+};

package/src/components/QueryEditor/QueryEditor.tsx

@@ -0,0 +1,136 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Extension, Prec } from '@codemirror/state';
+import React, { forwardRef, useCallback, useMemo, useRef } from 'react';
+
+import { type BuildResult, QueryBuilder } from '@dxos/echo-query';
+import { type ThemedClassName, useThemeMode, useTranslation } from '@dxos/react-ui';
+import {
+  Editor,
+  type EditorController,
+  type EditorMenuProviderProps,
+  type EditorViewProps,
+  type UseEditorMenuProps,
+  createMenuGroup,
+} from '@dxos/react-ui-editor';
+import { createBasicExtensions, createThemeExtensions, keymap } from '@dxos/ui-editor';
+
+import { translationKey } from '#translations';
+
+import { type CompletionOptions, completions } from './autocomplete.ts';
+import { query } from './query-extension.ts';
+
+export type QueryEditorProps = ThemedClassName<
+  {
+    value?: string;
+    readonly?: boolean;
+    /**
+     * The parsed query, rebuilt on every edit. `filter` is undefined while the text does not parse,
+     * which is what a caller gates a "save this view" affordance on.
+     *
+     * Supplying this is what opts the editor into building a filter at all — the DSL is otherwise
+     * parsed only for decoration, and a caller that wants the raw text pays nothing for a parse it
+     * will not read.
+     */
+    onFilterChange?: (result: BuildResult) => void;
+  } & (CompletionOptions & Omit<EditorViewProps, 'initialValue'> & Pick<EditorMenuProviderProps, 'numItems'>)
+>;
+
+/**
+ * Query editor with decorations and autocomplete.
+ */
+export const QueryEditor = forwardRef<EditorController, QueryEditorProps>(
+  ({ db, tags, value, readonly, numItems = 8, onChange, onFilterChange, ...props }, forwardedRef) => {
+    const { t } = useTranslation(translationKey);
+
+    const getOptions = useMemo(() => completions({ db, tags }), [db, tags]);
+    const getMenu = useCallback<NonNullable<UseEditorMenuProps['getMenu']>>(
+      async (context) => [createMenuGroup({ items: getOptions(context) })],
+      [getOptions],
+    );
+
+    // The editor owns the parse that used to be repeated by every consumer: the DSL was already being
+    // parsed here for decorations, so a caller building its own `QueryBuilder` parsed each keystroke
+    // twice.
+    const builder = useMemo(() => (onFilterChange ? new QueryBuilder(tags) : undefined), [onFilterChange, tags]);
+    const handleChange = useCallback(
+      (doc: string) => {
+        onChange?.(doc);
+        if (builder) {
+          onFilterChange?.(builder.build(doc));
+        }
+      },
+      [onChange, onFilterChange, builder],
+    );
+
+    // Keyed on the tag map's CONTENTS, not its identity: callers rebuild the map each render, and
+    // `useTextEditor` destroys and recreates the view whenever `extensions` changes — so depending on
+    // the object blurred the editor on every keystroke.
+    const tagsKey = useMemo(
+      () =>
+        Object.values(tags ?? {})
+          .map((tag) => `${tag.id}:${tag.label}:${tag.hue ?? ''}`)
+          .join(),
+      [tags],
+    );
+    const tagsRef = useRef(tags);
+    tagsRef.current = tags;
+
+    const themeMode = useThemeMode();
+    const extensions = useMemo<Extension[]>(
+      () => [
+        createBasicExtensions({
+          readOnly: readonly,
+          lineWrapping: false,
+          placeholder: t('query-editor.placeholder'),
+          // A single-line query gains nothing from bracket matching, and CodeMirror's default paints
+          // `.cm-matchingBracket` with a background while focused — a coloured wash over the braces of
+          // an object literal the moment the caret reaches it.
+          bracketMatching: false,
+        }),
+        createThemeExtensions({ themeMode, slots: { scroller: { className: 'scrollbar-none' } } }),
+        query({ tags: tagsRef.current }),
+        Prec.highest(
+          keymap.of([
+            {
+              key: 'Enter',
+              run: () => {
+                // Prevent newline.
+                return true;
+              },
+            },
+          ]),
+        ),
+      ],
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      [readonly, themeMode, tagsKey],
+    );
+
+    return (
+      <Editor.Root
+        ref={forwardedRef}
+        extensions={extensions}
+        numItems={numItems}
+        // `#` opens the tag list. `:` cannot be a trigger — `popoverKeymap` only fires one at a line
+        // start or after a space, and a typename's colon follows `type`; `activateOnTyping` covers it
+        // instead, since `:` is a completion delimiter so the word under the caret is the typename.
+        // The explicit key stays, for re-opening a dismissed menu.
+        trigger={['#']}
+        // NOT `activateOnTyping`: that opens the menu on every word character, and the popover takes
+        // focus each keystroke while returning nothing for most positions. `:` is the only delimiter
+        // with a list behind it, so the typename menu opens there and nowhere else.
+        activateOnDelimiters={[':']}
+        triggerKey='Ctrl-Space'
+        getMenu={getMenu}
+      >
+        {/* `initialValue`, never the controlled `value`: the sync effect behind `value` compares the
+            prop against the document a frame later, and a caller whose state trails fast typing then
+            rewrites the document back to the older text, dropping characters. A caller rewriting the
+            query itself does it through `EditorController.setText`. */}
+        <Editor.View {...props} initialValue={value} onChange={handleChange} selectionEnd />
+      </Editor.Root>
+    );
+  },
+);

package/src/components/QueryEditor/autocomplete.test.ts

@@ -0,0 +1,46 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { EditorState } from '@codemirror/state';
+import { describe, expect, test } from 'vitest';
+
+import { Tag } from '@dxos/echo';
+
+import { completions } from './autocomplete.ts';
+
+const tags: Tag.Map = {
+  tag_1: Tag.make({ label: 'important' }),
+  tag_2: Tag.make({ label: 'investor' }),
+};
+
+/**
+ * Selecting a completion replaces the WHOLE trigger range — the `#` included — and inserts the item
+ * verbatim, so an unprefixed label would drop the `#` and leave text that no longer parses as a tag.
+ */
+describe('tag completions', () => {
+  test('carry the `#`, so the inserted text is still a tag', () => {
+    expect(optionsAt('#')).toEqual(['#important', '#investor']);
+  });
+
+  test('are offered while the label is being typed', () => {
+    expect(optionsAt('#imp')).toEqual(['#important', '#investor']);
+  });
+
+  test('are offered for a tag later in the query', () => {
+    expect(optionsAt('type:org.dxos.Person AND #inv')).toEqual(['#important', '#investor']);
+  });
+
+  test('are not offered away from a tag', () => {
+    expect(optionsAt('type:')).not.toContain('#important');
+  });
+
+  // Only once the string is closed: until then the parser recovers by reading the `"` as an error and
+  // `#imp` as a real tag, so the tree has no string to resolve into.
+  test('are not offered inside a closed string, where `#` is content', () => {
+    expect(optionsAt('{ title: "#imp" }', 14)).toEqual([]);
+  });
+});
+
+const optionsAt = (doc: string, pos = doc.length) =>
+  completions({ tags })({ state: EditorState.create({ doc }), pos, text: doc });

package/src/components/QueryEditor/autocomplete.ts

@@ -0,0 +1,76 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Database, type Tag, Type } from '@dxos/echo';
+import { QueryDSL, formatTag } from '@dxos/echo-query';
+import { type GetMenuContext } from '@dxos/react-ui-editor';
+
+export type CompletionOptions = {
+  db?: Database.Database;
+  tags?: Tag.Map;
+};
+
+/**
+ * Tag labels as they must appear in the document. Selecting a completion REPLACES the whole trigger
+ * range, `#` included, and inserts the item verbatim — so an unprefixed label would silently drop the
+ * `#` and leave text that no longer parses as a tag.
+ */
+const tagCompletions = (tags: Tag.Map): string[] => Object.values(tags).map((tag) => formatTag(tag.label));
+
+/**
+ * Whether the caret sits in a tag the user is still typing: a `#` at the start of the current word,
+ * with only label characters between it and `pos`.
+ */
+const isTypingTag = (text: string, pos: number): boolean => {
+  let index = pos;
+  while (index > 0 && /[a-zA-Z0-9_-]/.test(text[index - 1])) {
+    index--;
+  }
+
+  return index > 0 && text[index - 1] === '#';
+};
+
+export const completions = ({ db, tags }: CompletionOptions) => {
+  const parser = QueryDSL.Parser.configure({ strict: false });
+  return ({ state, pos }: GetMenuContext): string[] => {
+    const text = state.sliceDoc();
+    const tree = parser.parse(text);
+    const { node } = tree.cursorAt(pos, -1);
+
+    // A `#` with no label yet is an error node, not a `TagFilter` — the grammar needs a label
+    // character before it accepts one — so the tree cannot answer for the keystroke that opens a tag.
+    // Inside a string it is content, so the tree is still what settles that.
+    if (tags && isTypingTag(text, pos) && node.type.id !== QueryDSL.Node.String) {
+      return tagCompletions(tags);
+    }
+
+    switch (node.parent?.type.id) {
+      case QueryDSL.Node.TypeFilter: {
+        let range: { from: number; to: number } | undefined;
+        if (node?.type.id === QueryDSL.Node.Identifier) {
+          range = { from: node.from, to: node.to };
+        } else if (node?.type.name === ':') {
+          range = { from: node.from + 1, to: node.to };
+        }
+
+        if (range) {
+          const schema = db ? [...db.graph.registry.list().filter(Type.isType)] : [];
+          return schema.map((schema) => Type.getTypename(schema));
+        }
+
+        break;
+      }
+
+      case QueryDSL.Node.TagFilter: {
+        if (tags) {
+          return tagCompletions(tags);
+        }
+
+        break;
+      }
+    }
+
+    return [];
+  };
+};

package/src/components/QueryEditor/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export type { EditorController } from '@dxos/react-ui-editor';
+
+export * from './QueryEditor.tsx';

package/src/components/QueryEditor/query-extension.test.ts

@@ -0,0 +1,176 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { EditorSelection, EditorState } from '@codemirror/state';
+import { EditorView } from '@codemirror/view';
+import { describe, expect, test } from 'vitest';
+
+import { Tag } from '@dxos/echo';
+import { getHashHue } from '@dxos/ui-theme';
+
+import { buildQueryDecorations, query } from './query-extension.ts';
+
+const tag = Tag.make({ label: 'important' });
+const tags: Tag.Map = { [tag.id]: tag };
+const hue = tag.hue ?? getHashHue(tag.id);
+
+/**
+ * A tag is one object: a widget REPLACES its text, atomically, wherever the caret is — including at
+ * the tag's own edges, so Backspace against it removes the whole chip rather than a character of the
+ * label. It is still typed a character at a time, since an insertion at the range's boundary lands
+ * outside it and grows the node.
+ */
+describe('tag rendering', () => {
+  test('is an atomic chip when the caret is elsewhere', async () => {
+    const view = await viewOf('#important AND #other', 0);
+    expect(decorationsOf(view)).toMatchObject([
+      { from: 0, to: 10, atomic: true },
+      { from: 11, to: 14, atomic: true },
+      { from: 15, to: 21, atomic: true },
+    ]);
+    view.destroy();
+  });
+
+  test('stays an atomic chip with the caret inside it', async () => {
+    const view = await viewOf('#important', 5);
+    expect(decorationsOf(view)).toMatchObject([{ from: 0, to: 10, atomic: true }]);
+    view.destroy();
+  });
+
+  test('stays an atomic chip with the caret at its trailing edge', async () => {
+    // Regression: the caret lands here both while the tag is being typed and after `End`, and an
+    // exception for it left Backspace deleting a character of the label instead of the whole tag.
+    const view = await viewOf('#important', 10);
+    expect(decorationsOf(view)).toMatchObject([{ from: 0, to: 10, atomic: true }]);
+    view.destroy();
+  });
+
+  test('a bare `#` is marked from the keystroke that opens it', async () => {
+    // The grammar needs a label character before it accepts a `Tag`, so this comes from a document
+    // scan rather than the tree — the affordance cannot wait for the parse to succeed.
+    const view = await viewOf('#', 1);
+    expect(decorationsOf(view)).toMatchObject([{ from: 0, to: 1, atomic: false }]);
+    view.destroy();
+  });
+
+  test('every tag is a chip, wherever the caret is', async () => {
+    const view = await viewOf('#alpha #beta', 12);
+    const ranges = decorationsOf(view);
+    expect(ranges.filter((range) => range.atomic).map(({ from, to }) => [from, to])).toEqual([
+      [0, 6],
+      [7, 12],
+    ]);
+    view.destroy();
+  });
+
+  test('the label is rendered once', async () => {
+    const view = await viewOf('#important', 10);
+    expect(view.contentDOM.textContent).toBe('#important');
+    view.destroy();
+  });
+});
+
+/**
+ * Decorations are fed to a `RangeSetBuilder`, which throws on an out-of-order range. The bare-`#`
+ * ranges come from a document scan rather than the syntax tree, so they interleave with the tree's
+ * own and have to be sorted before being added.
+ */
+describe('buildQueryDecorations', () => {
+  test.each([
+    ['', 'empty'],
+    ['#', 'a bare hash'],
+    ['#important', 'a tag'],
+    ['#a #b #c', 'several tags'],
+    ['type:org.dxos.Person AND #important', 'a tag following another filter'],
+    ['{ name: "x" } #tag', 'an object literal before a tag'],
+    ['"# not a tag" #real', 'a hash inside a string'],
+  ])('builds over %j (%s)', async (doc) => {
+    const view = await viewOf(doc);
+    expect(() => decorationsOf(view)).not.toThrow();
+    view.destroy();
+  });
+
+  test('a hash inside a string is not treated as a tag', async () => {
+    const view = await viewOf('"# not a tag"', 0);
+    expect(decorationsOf(view).filter((range) => range.from === 1)).toHaveLength(0);
+    view.destroy();
+  });
+
+  test('the chip is drawn in the tag hue', async () => {
+    const view = await viewOf('#important', 10);
+    // The hue lives in the widget's own DOM, so it is read off the rendered chip rather than a spec.
+    const classes = [...view.contentDOM.querySelectorAll('span')].map((el) => el.className);
+    expect(classes.some((className) => className.includes(hue))).toBe(true);
+    view.destroy();
+  });
+});
+
+/**
+ * Tags are atomic, so text must never end up glued to one — and there has to be a position at the end
+ * of the document that is not adjacent to a chip.
+ */
+describe('spacing', () => {
+  test('typing immediately before a tag is separated from it', async () => {
+    const view = await viewOf('#important', 0);
+    view.dispatch({ changes: { from: 0, insert: 'a' }, selection: EditorSelection.cursor(1) });
+    expect(view.state.doc.toString()).toBe('a #important ');
+    expect(view.state.selection.main.head).toBe(1);
+    view.destroy();
+  });
+
+  test('an insertion leaves a trailing space', async () => {
+    const view = await viewOf('#a', 2);
+    view.dispatch({ changes: { from: 2, insert: 'b' }, selection: EditorSelection.cursor(3) });
+    expect(view.state.doc.toString()).toBe('#ab ');
+    // The caret stays before the trailing space, so typing continues to extend the tag.
+    expect(view.state.selection.main.head).toBe(3);
+    view.destroy();
+  });
+
+  test('the trailing space is not re-added after a deletion', async () => {
+    const view = await viewOf('#a ', 3);
+    view.dispatch({ changes: { from: 2, to: 3 } });
+    expect(view.state.doc.toString()).toBe('#a');
+    view.destroy();
+  });
+
+  test('an empty document is left empty, so the placeholder shows', async () => {
+    const view = await viewOf('x', 1);
+    view.dispatch({ changes: { from: 0, to: 1 } });
+    expect(view.state.doc.toString()).toBe('');
+    view.destroy();
+  });
+});
+
+/**
+ * A mounted, focused view. Focus matters: the tag under the caret is only drawn as live text while the
+ * editor has it, so a blurred editor shows chips throughout.
+ */
+const viewOf = async (doc: string, head = doc.length) => {
+  const parent = document.createElement('div');
+  document.body.appendChild(parent);
+  const view = new EditorView({
+    state: EditorState.create({ doc, selection: EditorSelection.cursor(head), extensions: [query({ tags })] }),
+    parent,
+  });
+  view.contentDOM.dispatchEvent(new FocusEvent('focus'));
+  await new Promise((resolve) => requestAnimationFrame(resolve));
+  return view;
+};
+
+const decorationsOf = (view: EditorView) => {
+  const ranges: { from: number; to: number; atomic: boolean; class?: string }[] = [];
+  const cursor = buildQueryDecorations(view.state, { tags }).iter();
+  while (cursor.value) {
+    ranges.push({
+      from: cursor.from,
+      to: cursor.to,
+      atomic: !!cursor.value.spec.atomic,
+      class: cursor.value.spec.class,
+    });
+    cursor.next();
+  }
+
+  return ranges;
+};