@estiva-app/ui 0.52.0 → 0.53.0

package/dist/suggestionPopup.d.ts

@@ -22,6 +22,15 @@ export interface SuggestionPopupOptions<T> {
     sections?: (items: T[], query: string) => readonly SuggestionMenuSection<T>[];
     itemKey: (item: T) => string;
     row: (item: T) => SuggestionMenuRow;
+    /**
+     * With `refresh`: called with a listener while the list is open; the app
+     * calls it when its data has changed (a search landing), and the open list is
+     * drawn again for the same query. Returns the unsubscribe, run when the list
+     * closes however it closes.
+     */
+    subscribe?: (listener: () => void) => () => void;
+    /** The items for a query, as the plugin's `items` answers — asked again when `subscribe` fires. */
+    refresh?: (query: string) => T[];
 }
 /**
  * The `render` of a Tiptap suggestion plugin, drawn as a `SuggestionMenu` —

package/dist/suggestionPopup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"suggestionPopup.d.ts","sourceRoot":"","sources":["../src/suggestionPopup.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAA0B,iBAAiB,EAAmB,MAAM,oBAAoB,CAAA;AACpG,OAAO,EAA6C,KAAK,iBAAiB,EAAE,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAchI;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED,mFAAmF;AACnF,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAA;IACjB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAA;IACb,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAA;IACjB,yGAAyG;IACzG,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,KAAK,SAAS,qBAAqB,CAAC,CAAC,CAAC,EAAE,CAAA;IAC7E,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAA;IAC5B,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,iBAAiB,CAAA;CACpC;AA0BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAgClH"}
+{"version":3,"file":"suggestionPopup.d.ts","sourceRoot":"","sources":["../src/suggestionPopup.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAA0B,iBAAiB,EAAmB,MAAM,oBAAoB,CAAA;AACpG,OAAO,EAA6C,KAAK,iBAAiB,EAAE,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAchI;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED,mFAAmF;AACnF,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAA;IACjB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAA;IACb,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAA;IACjB,yGAAyG;IACzG,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,KAAK,SAAS,qBAAqB,CAAC,CAAC,CAAC,EAAE,CAAA;IAC7E,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAA;IAC5B,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,iBAAiB,CAAA;IACnC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAA;IAChD,mGAAmG;IACnG,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,CAAC,EAAE,CAAA;CACjC;AA0BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAmDlH"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",

package/registry.json

@@ -4,7 +4,7 @@
     "kind": "package",
     "repo": "estiva-ui",
     "package": "@estiva-app/ui",
-    "packageVersion": "0.52.0",
+    "packageVersion": "0.53.0",
     "exports": 120,
     "typeExports": 128,
     "files": null
@@ -4587,7 +4587,7 @@
       "kind": "helper",
       "importPath": "@estiva-app/ui/editor",
       "sourceFile": "src/ComposerTriggers.tsx",
-      "purpose": "The list `[` opens: one section of `label: snippet` rows, the same box as the people list.",
+      "purpose": "The list `[` opens: `label: snippet` rows, the same box as the people list.",
       "purposeFrom": "comment",
       "props": [
         {
@@ -5568,6 +5568,18 @@
           "takes": "a handler",
           "required": true,
           "note": null
+        },
+        {
+          "name": "subscribe",
+          "takes": "a handler",
+          "required": false,
+          "note": "With `refresh`: called with a listener while the list is open; the app calls it when its data has changed (a search landing), and the open list is drawn again for the same query."
+        },
+        {
+          "name": "refresh",
+          "takes": "a handler",
+          "required": false,
+          "note": "The items for a query, as the plugin's `items` answers — asked again when `subscribe` fires."
         }
       ],
       "variants": [],

package/src/ComposerTriggers.mdx

@@ -77,6 +77,13 @@ const urgent = editor ? urgentPubkeys(editor) : undefined
   functions, so they read the app's current data. `@` shows the first six
   names holding the query; `[` the last six whose label or `search` (default:
   `snippet`) holds it.
+- **`[` in sections, filled in as answers land:** pass `sections(query)` in
+  place of `items` — labelled groups the app has already narrowed and ordered;
+  an empty group is not drawn — and `subscribe(listener)`, which the app calls
+  when a slower answer (a search) has landed. The open list is drawn again for
+  the same query; nothing waits for it. A row's `description` is its second
+  line, which the chip does not wear. A row the person has arrowed to stays
+  highlighted when the list is drawn again.
 - **An app's own node name:** `CaptionedReference.extend({ name: 'yourName' })`
   and `ReferenceTrigger.configure({ nodeName: 'yourName' })`. The chip's HTML
   attribute follows the name (`data-your-name`).

package/src/ComposerTriggers.stories.tsx

@@ -13,6 +13,7 @@ import {
   typeTrigger,
   type CaptionedItem,
   type MentionPerson,
+  type ReferenceSection,
   type SlashSection,
 } from './ComposerTriggers'
 
@@ -43,6 +44,21 @@ const ITEMS: CaptionedItem[] = ['one', 'two', 'three'].map((n) => ({
   uri: `nostr:item-${n}`,
 }))
 
+const DESCRIBED: CaptionedItem[] = ['four', 'five'].map((n) => ({
+  id: `item-${n}`,
+  label: 'Label',
+  snippet: `Item ${n}`,
+  uri: `nostr:item-${n}`,
+  description: 'Label',
+}))
+
+const matching = (items: CaptionedItem[], query: string) => items.filter((item) => item.snippet.toLowerCase().includes(query.toLowerCase()))
+
+const SECTIONS = (query: string): ReferenceSection[] => [
+  { label: 'Group one', items: matching(ITEMS, query) },
+  { label: 'Group two', items: matching(DESCRIBED, query) },
+]
+
 const INSERT: SlashSection = {
   label: 'Insert',
   commands: [
@@ -51,7 +67,7 @@ const INSERT: SlashSection = {
   ],
 }
 
-function Composer({ code }: { code: 'inline' | 'block' }) {
+function Composer({ code, sections }: { code: 'inline' | 'block'; sections?: typeof SECTIONS }) {
   const editor = useEditor({
     extensions: [
       StarterKit,
@@ -60,6 +76,7 @@ function Composer({ code }: { code: 'inline' | 'block' }) {
       CaptionedReference.configure({ icon: <IconSquareRounded size={14} stroke={1.5} /> }),
       ReferenceTrigger.configure({
         items: () => ITEMS,
+        sections,
         ariaLabel: 'Items',
         sectionLabel: 'Items',
         icon: <IconSquareRounded size={16} stroke={1.5} className="text-text-secondary" />,
@@ -77,3 +94,6 @@ export const Default: Story = { render: () => <Composer code="inline" /> }
 
 /** Code as a block of its own, for an editor of a block document. */
 export const CodeAsABlock: Story = { render: () => <Composer code="block" /> }
+
+/** `[` with the app's own groups, each headed, a row with a second line. */
+export const ReferencesInSections: Story = { render: () => <Composer code="inline" sections={SECTIONS} /> }

package/src/ComposerTriggers.test.tsx

@@ -139,6 +139,67 @@ describe('[', () => {
     expect(editor!.getHTML()).toContain('data-message-mention="true"')
   })
 
+  it('draws the app’s sections in order, skips an empty one, and redraws the open list when told', async () => {
+    const listeners = new Set<() => void>()
+    let late: CaptionedItem[] = []
+    const sections = (query: string) => [
+      { label: 'Recent', items: ITEMS.slice(0, 2).filter((item) => item.snippet.includes(query)) },
+      { label: 'Empty', items: [] },
+      { label: 'Found', items: late },
+    ]
+    function Sectioned() {
+      const made = useEditor({
+        extensions: [
+          StarterKit,
+          Chip,
+          ReferenceTrigger.configure({
+            items: () => [],
+            sections,
+            subscribe: (listener) => {
+              listeners.add(listener)
+              return () => listeners.delete(listener)
+            },
+            nodeName: 'messageMention',
+            ariaLabel: 'Things',
+            sectionLabel: 'Things',
+          }),
+        ],
+      })
+      editor = made
+      return <EditorContent editor={made} />
+    }
+    render(<Sectioned />)
+    await type('[')
+    expect(options()).toEqual(['Ada: line 0', 'Ada: line 1'])
+    expect(screen.getByText('Recent')).toBeTruthy()
+    expect(screen.queryByText('Empty')).toBeNull()
+    expect(listeners.size).toBe(1)
+
+    // The person arrows to a row, then a late answer lands: their row stays highlighted.
+    await press('ArrowDown')
+    late = [{ id: 'f'.repeat(64), label: 'Plan', snippet: 'Q3 roadmap', uri: 'nostr:naddr1example', description: 'Planning' }]
+    await act(async () => listeners.forEach((listener) => listener()))
+    expect(options()).toEqual(['Ada: line 0', 'Ada: line 1', 'Plan: Q3 roadmapPlanning'])
+    expect(screen.getByText('Found')).toBeTruthy()
+    await press('Enter')
+    expect(nodes().map((node) => node.attrs.id)).toEqual([ITEMS[1].id])
+    expect(listeners.size).toBe(0)
+
+    // A row that arrived late is picked like any other.
+    await type('[')
+    await press('ArrowDown')
+    await press('ArrowDown')
+    await press('Enter')
+    expect(nodes()[1]).toEqual({ type: 'messageMention', attrs: { id: 'f'.repeat(64), label: 'Plan', snippet: 'Q3 roadmap', uri: 'nostr:naddr1example' } })
+
+    await type('[')
+    expect(listeners.size).toBe(1)
+    await press('Escape')
+    expect(screen.queryByRole('listbox')).toBeNull()
+    // Escape closes the list and stops listening.
+    expect(listeners.size).toBe(0)
+  })
+
   it('matches who said it, or the text it searches', () => {
     expect(filterReferences(ITEMS, 'bea').map((item) => item.id)).toEqual([ITEMS[7].id])
     expect(filterReferences(ITEMS, '**line** 3').map((item) => item.id)).toEqual([ITEMS[3].id])

package/src/ComposerTriggers.tsx

@@ -211,6 +211,14 @@ export interface CaptionedItem {
   uri: string
   /** What the query is matched against beside `label`. Default: `snippet`. */
   search?: string
+  /** The row's second line, e.g. where the thing sits. The chip does not wear it. */
+  description?: string
+}
+
+/** One labelled group of `[`'s rows, in the order the list draws them. */
+export interface ReferenceSection {
+  label: string
+  items: readonly CaptionedItem[]
 }
 
 /** How many references the list shows. */
@@ -289,25 +297,57 @@ export interface ReferenceMenuOptions {
   icon: ReactNode
 }
 
-/** The list `[` opens: one section of `label: snippet` rows, the same box as the people list. */
+/** A row as the list holds it: which section it is drawn under, when the list has several. */
+type ListedItem = CaptionedItem & { section?: string }
+
+/**
+ * The list `[` opens: `label: snippet` rows, the same box as the people list.
+ * One section headed `sectionLabel`, or — when the rows say which section they
+ * are in — a heading for each, in the order the rows arrive.
+ */
 export function referenceMenu({ ariaLabel, sectionLabel, icon }: ReferenceMenuOptions): SuggestionPopupOptions<CaptionedItem> {
   return {
     ariaLabel,
     width: 'w-[658px]',
     maxHeight: 'max-h-[360px]',
-    sections: (items) => [{ label: sectionLabel, items, className: 'px-2' }],
+    sections: (items: ListedItem[]) => {
+      const groups: { label: string; items: CaptionedItem[]; className: string }[] = []
+      for (const item of items) {
+        const label = item.section ?? sectionLabel
+        const last = groups[groups.length - 1]
+        if (last?.label === label) last.items.push(item)
+        else groups.push({ label, items: [item], className: 'px-2' })
+      }
+      return groups
+    },
     itemKey: (item) => `reference-${item.id}`,
-    row: (item) => ({ leading: icon, label: captionOf(item.label, item.snippet), hint: <EnterHint /> }),
+    row: (item) => ({ leading: icon, label: captionOf(item.label, item.snippet), description: item.description, hint: <EnterHint /> }),
   }
 }
 
 export interface ReferenceTriggerOptions extends ReferenceMenuOptions {
-  /** Everything `[` can offer, asked each time the query changes. */
+  /** Everything `[` can offer, asked each time the query changes. Narrowed by {@link filterReferences}. */
   items: () => readonly CaptionedItem[]
+  /**
+   * In place of `items`: the sections to draw for what was typed, already
+   * narrowed and ordered by the app. Empty sections are not drawn.
+   */
+  sections?: (query: string) => readonly ReferenceSection[]
+  /**
+   * Called with a listener while the list is open; the app calls it when what
+   * `sections` would answer has changed — a search landing — and the open list
+   * is drawn again for the same query. Returns the unsubscribe.
+   */
+  subscribe?: (listener: () => void) => () => void
   /** The node a pick inserts. Default `captionedReference`. */
   nodeName: string
 }
 
+const listed = (options: ReferenceTriggerOptions, query: string): ListedItem[] =>
+  options.sections
+    ? options.sections(query).flatMap((section) => section.items.map((item) => ({ ...item, section: section.label })))
+    : filterReferences(options.items(), query)
+
 /**
  * `[` — reference something, inserted as a {@link CaptionedReference} chip.
  *
@@ -331,8 +371,8 @@ export const ReferenceTrigger = Extension.create<ReferenceTriggerOptions>({
           const type = state.schema.nodes[options.nodeName]
           return !!type && !!state.doc.resolve(range.from).parent.type.contentMatch.matchType(type)
         },
-        items: ({ query }) => filterReferences(options.items(), query),
-        render: suggestionPopup(referenceMenu(options)),
+        items: ({ query }) => listed(options, query),
+        render: suggestionPopup({ ...referenceMenu(options), subscribe: options.subscribe, refresh: (query) => listed(options, query) }),
         command: ({ editor, range, props: item }) => {
           editor
             .chain()

package/src/SuggestionMenu.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useId, useImperativeHandle, useMemo, useState, type ReactNode, type Ref } from 'react'
+import { useCallback, useEffect, useId, useImperativeHandle, useMemo, useRef, useState, type ReactNode, type Ref } from 'react'
 import { MenuItem, MenuSection, MenuSeparator, type MenuItemProps } from './Menu'
 import { Popover } from './Popover'
 
@@ -85,8 +85,18 @@ export function SuggestionMenu<T>({ rect, editorElement, ariaLabel, width, maxHe
   const base = useId()
   const listboxId = `${base}-list`
 
-  // A new list is a new list: the old index may not exist in it.
-  useEffect(() => setHighlight(0), [keys])
+  // The row the person arrowed to, by key — read as the list was when they
+  // moved, so not re-run when `keys` changes.
+  const chosen = useRef<string | null>(null)
+  useEffect(() => void (chosen.current = highlight > 0 ? (keys.split('\n')[highlight] ?? null) : null), [highlight])
+
+  // A new list is a new list: the old index may not exist in it. A row the
+  // person arrowed to stays highlighted while it is still listed, so an answer
+  // landing late does not move their pick under the Enter key.
+  useEffect(() => {
+    const at = chosen.current ? keys.split('\n').indexOf(chosen.current) : -1
+    setHighlight(at > 0 ? at : 0)
+  }, [keys])
 
   useImperativeHandle(handle, () => ({
     // The editor hands its arrow keys to this list: Base UI's lists need a text field of their own, and an editor is not one.

package/src/suggestionPopup.tsx

@@ -44,6 +44,15 @@ export interface SuggestionPopupOptions<T> {
   sections?: (items: T[], query: string) => readonly SuggestionMenuSection<T>[]
   itemKey: (item: T) => string
   row: (item: T) => SuggestionMenuRow
+  /**
+   * With `refresh`: called with a listener while the list is open; the app
+   * calls it when its data has changed (a search landing), and the open list is
+   * drawn again for the same query. Returns the unsubscribe, run when the list
+   * closes however it closes.
+   */
+  subscribe?: (listener: () => void) => () => void
+  /** The items for a query, as the plugin's `items` answers — asked again when `subscribe` fires. */
+  refresh?: (query: string) => T[]
 }
 
 type Props<T> = SuggestionProps<T> & { options: SuggestionPopupOptions<T> }
@@ -88,7 +97,12 @@ export function suggestionPopup<T>(options: SuggestionPopupOptions<T>): NonNulla
   return () => {
     let component: ReactRenderer<SuggestionMenuHandle, Props<T>> | null = null
     let container: HTMLDivElement | null = null
+    let last: SuggestionProps<T> | null = null
+    let unsubscribe: (() => void) | undefined
     const exit = () => {
+      unsubscribe?.()
+      unsubscribe = undefined
+      last = null
       if (!component) return
       openCount = Math.max(0, openCount - 1)
       lastClose = Date.now()
@@ -104,8 +118,22 @@ export function suggestionPopup<T>(options: SuggestionPopupOptions<T>): NonNulla
         container = document.createElement('div')
         document.body.appendChild(container)
         container.appendChild(component.element)
+        last = props
+        const { subscribe, refresh } = options
+        if (subscribe && refresh) {
+          // The plugin asks for items only when the query changes; an answer
+          // landing later draws the open list again with the same props.
+          unsubscribe = subscribe(() => {
+            if (!last || !component) return
+            last = { ...last, items: refresh(last.query) }
+            component.updateProps({ ...last, options })
+          })
+        }
+      },
+      onUpdate: (props) => {
+        last = props
+        component?.updateProps({ ...props, options })
       },
-      onUpdate: (props) => component?.updateProps({ ...props, options }),
       onKeyDown: ({ event }: SuggestionKeyDownProps) => {
         if (event.key === 'Escape') {
           exit()