@dxos/react-ui-form 0.8.4-main.fffef41 → 0.9.0

package/src/components/RefEditor/RefEditor.stories.tsx

@@ -0,0 +1,148 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { Fragment, useState } from 'react';
+
+import { type Database, Filter, Obj } from '@dxos/echo';
+import { random } from '@dxos/random';
+import { useQuery } from '@dxos/react-client/echo';
+import { useClientStory, withClientProvider } from '@dxos/react-client/testing';
+import { JsonHighlighter } from '@dxos/react-ui-syntax-highlighter';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { type ValueGenerator, createObjectFactory } from '@dxos/schema/testing';
+import { Person } from '@dxos/types';
+
+import { translations } from '#translations';
+
+import { EMAIL_REGEX } from './ref-editor-extension';
+import { RefEditor, type RefEditorProps } from './RefEditor';
+
+const generator: ValueGenerator = random as any;
+
+random.seed(7);
+
+/**
+ * Generate Person objects into the space. The generator does not populate array fields, so derive
+ * email addresses from each person's name (every other person gets a second work alias so the
+ * email-mode picker shows multiple entries per person).
+ */
+const generatePeople = async (db: Database.Database, count: number) => {
+  const people = await createObjectFactory(db, generator)([{ type: Person.Person, count }]);
+  people.forEach((person, index) => {
+    Obj.update(person, (person: Obj.Mutable<Person.Person>) => {
+      const slug = (person.fullName ?? 'user')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '.')
+        .replace(/^\.+|\.+$/g, '');
+      person.emails = [
+        { value: `${slug}@example.com` },
+        ...(index % 2 === 0 ? [{ label: 'work', value: `${slug}@work.example.com` }] : []),
+        ...(index % 4 === 0 ? [{ label: 'private', value: `${random.lorem.word()}@gmail.com` }] : []),
+      ];
+    });
+  });
+  return people;
+};
+
+/** Person email addresses (the values a person can be captured as in email mode). */
+const getPersonValues = (object: Obj.Unknown): readonly string[] =>
+  Obj.instanceOf(Person.Person, object) ? (object.emails ?? []).map(({ value }) => value) : [];
+
+/**
+ * Dense reference grid of the generated people and their email addresses.
+ */
+const PeopleGrid = ({ db }: { db?: Database.Database }) => {
+  const people = useQuery(db, Filter.type(Person.Person));
+  return (
+    <div className='grid grid-cols-[max-content_1fr] gap-x-4 text-sm text-description'>
+      {people.flatMap((person) =>
+        (person.emails ?? []).map(({ value }) => (
+          <Fragment key={`${person.id}-${value}`}>
+            <span className='truncate'>{person.fullName}</span>
+            <span className='truncate'>{value}</span>
+          </Fragment>
+        )),
+      )}
+    </div>
+  );
+};
+
+type StoryProps = Partial<Pick<RefEditorProps, 'value' | 'mode' | 'activateOnTyping' | 'autoFocus'>>;
+
+// NOTE: The Person config (type/match/getValues) is supplied in render, not args — Storybook's
+// arg traversal attempts to mutate the proxied ECHO schema and crashes.
+const DefaultStory = ({ value: initialValue, ...args }: StoryProps) => {
+  const { space } = useClientStory();
+  const [value, setValue] = useState(initialValue ?? '');
+
+  return (
+    <div className='flex flex-col gap-2'>
+      <RefEditor
+        {...args}
+        value={initialValue}
+        type={Person.Person}
+        match={EMAIL_REGEX}
+        getValues={getPersonValues}
+        icon='ph--user--regular'
+        db={space?.db}
+        onChange={setValue}
+        classNames='border'
+      />
+      <JsonHighlighter data={{ value }} classNames='text-xs' />
+      <PeopleGrid db={space?.db} />
+    </div>
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-form/RefEditor',
+  render: DefaultStory,
+  decorators: [
+    withTheme(),
+    withLayout({ layout: 'column', classNames: 'p-2', scroll: true }),
+    withClientProvider({
+      types: [Person.Person],
+      createIdentity: true,
+      createSpace: true,
+      onCreateSpace: async ({ space }) => {
+        await generatePeople(space.db, 8);
+      },
+    }),
+  ],
+  parameters: {
+    translations,
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    autoFocus: true,
+  },
+};
+
+export const ActivateOnTyping: Story = {
+  args: {
+    autoFocus: true,
+    activateOnTyping: true,
+  },
+};
+
+export const EmailMode: Story = {
+  args: {
+    autoFocus: true,
+    mode: 'email',
+    activateOnTyping: true,
+  },
+};
+
+export const WithEmail: Story = {
+  args: {
+    value: 'someone@example.com ',
+  },
+};

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