@estiva-app/ui 0.66.0 → 0.68.0

package/src/LinkChips.ts

@@ -0,0 +1,243 @@
+/**
+ * An app URL in a document reads as the chip of what it names — SPEC §13.3,
+ * "A reference's card", and §7.7.
+ *
+ * The URL stays the URL: the chip is the `reference` node with `href` set (a
+ * URL chip, `ReferenceNode`), which a document writes back as the URL it was,
+ * plain text with no card and a `link` mark with one. Never a `nostr:`
+ * reference in its place: the URL is how a person addresses the object.
+ *
+ * What a URL names is the app's to say — its manifests and its relay — so the
+ * app hands this extension two functions: `referenceOf`, what it has resolved
+ * so far, and `ask`, to look up the URLs it has not. A URL that names nothing,
+ * or whose answer has not come back, stays text; when `ask` settles the
+ * document is looked at again.
+ *
+ * The URL being typed stays text while the caret is in it or at its end, so a
+ * half-typed address never turns into a chip under the person's fingers. A
+ * pasted URL is whole, so it is asked about and made a chip at once, the caret
+ * still at its end — where `ReferenceMenu` opens its menu.
+ */
+import { Extension, type Editor } from '@tiptap/core'
+import type { Node as PmNode } from '@tiptap/pm/model'
+import { Plugin, PluginKey, type EditorState, type Selection, type Transaction } from '@tiptap/pm/state'
+
+export interface LinkChipsOptions {
+  /**
+   * The `nostr:` reference an app URL names, from what the app has resolved
+   * (§7.7) — protocol's `referenceOfLink(url, resolveLink)`. Undefined while it
+   * names nothing, or its answer has not come back.
+   */
+  referenceOf: ((url: string) => string | undefined) | null
+  /** Look up what these URLs name. When it settles, the document is looked at again. */
+  ask: ((urls: string[]) => Promise<unknown> | void) | null
+  /**
+   * How many URLs one editor asks about in its life, the first ones; the rest
+   * stay text. An app's answer can cost a relay query, and a document pasted
+   * full of links must not spend the writer's quota. Default 24.
+   */
+  limit: number
+}
+
+interface LinkChipsState {
+  options: LinkChipsOptions
+  /** The last few pastes, mapped through every edit since. */
+  pasted: PastedRange[]
+}
+
+const key = new PluginKey<LinkChipsState>('linkChips')
+
+/** The meta on the transaction that made chips: `{ pasted }`. */
+export const CHIPS_MADE = 'linkChipsMade'
+
+/** How many pastes are remembered; one is what the person just did. */
+const PASTES_KEPT = 8
+
+/**
+ * A link on words in marker text (skipped), or a bare URL — the grammar of
+ * protocol's `urlRunsIn`, which a reader turns into chips by, so what an editor
+ * makes a chip is what a reader would.
+ */
+const LINK_OR_URL = /(\[[^[\]\n]+\]\((?:https?:\/\/|mailto:)[^\s)]+\))|(https?:\/\/[^\s<>"'`]+)/g
+const TRAILING = new Set(['.', ',', ';', ':', '!', '?', ')', ']'])
+
+/** Each URL and where it sits; `end` is where its run ends before trailing punctuation is trimmed, which typing may yet continue. */
+function urlRuns(text: string): { url: string; from: number; to: number; end: number }[] {
+  if (!text.includes('://')) return []
+  const out: { url: string; from: number; to: number; end: number }[] = []
+  for (const m of text.matchAll(LINK_OR_URL)) {
+    if (m[1]) continue
+    const start = m.index
+    if (text.slice(Math.max(0, start - 2), start) === '](' || text[start - 1] === '[') continue
+    let end = m[0].length
+    while (end > 0 && TRAILING.has(m[0][end - 1])) end--
+    out.push({ url: m[0].slice(0, end), from: start, to: start + end, end: start + m[0].length })
+  }
+  return out
+}
+
+interface Found {
+  /** Text URLs that name something: made chips. */
+  chips: { from: number; to: number; url: string; uri: string; marks: string[]; pasted: boolean }[]
+  /** URL chips whose URL is answered now: given their reference. */
+  fills: { pos: number; uri: string }[]
+  /** Every URL still waiting for an answer, or naming nothing. */
+  open: string[]
+}
+
+/** Where something was pasted: a URL wholly inside one was not typed, so the caret at its end does not hold it as text. */
+export interface PastedRange {
+  from: number
+  to: number
+}
+
+/**
+ * What to change in a document, and what to ask. `selection` null treats no
+ * URL as being typed; a URL inside one of `pasted` is never being typed.
+ */
+export function findLinkChips(doc: PmNode, selection: Selection | null, referenceOf: LinkChipsOptions['referenceOf'], pasted: readonly PastedRange[] = []): Found {
+  const found: Found = { chips: [], fills: [], open: [] }
+  const open = new Set<string>()
+  doc.descendants((node, pos) => {
+    // A fence is literal (§13.1): its URLs are text.
+    if (node.type.spec.code) return false
+    if (node.type.name === 'reference') {
+      const href = typeof node.attrs.href === 'string' ? node.attrs.href : ''
+      if (href && !node.attrs.uri) {
+        const uri = referenceOf?.(href)
+        if (uri) found.fills.push({ pos, uri })
+        else open.add(href)
+      }
+      return false
+    }
+    if (!node.isText || !node.text) return true
+    // A URL in code is literal, and one already linked on purpose is the link's.
+    if (node.marks.some((m) => m.type.spec.code || m.type.name === 'code' || m.type.name === 'link')) return false
+    for (const run of urlRuns(node.text)) {
+      const from = pos + run.from
+      const to = pos + run.to
+      // Being typed or selected: the caret inside it or at its end (`https://a.` is still being typed), or a
+      // selection over any of it. A caret before it is not.
+      // A pasted URL is whole: it becomes its chip with the caret still at its end, so its menu can open at once.
+      const wasPasted = pasted.some((range) => range.from <= from && pos + run.end <= range.to)
+      const typing = selection && selection.to > from && selection.from <= pos + run.end
+      if (typing && !(selection.empty && wasPasted)) continue
+      const uri = referenceOf?.(run.url)
+      if (uri) found.chips.push({ from, to, url: run.url, uri, marks: node.marks.map((m) => m.type.name), pasted: wasPasted })
+      else open.add(run.url)
+    }
+    return false
+  })
+  found.open = [...open]
+  return found
+}
+
+function apply(state: EditorState, found: Found): Transaction | null {
+  if (!found.chips.length && !found.fills.length) return null
+  const type = state.schema.nodes.reference
+  if (!type) return null
+  const tr = state.tr
+  // A fill keeps the node's size, so the chips' positions still hold; the chips go last first.
+  for (const { pos, uri } of found.fills) {
+    const node = tr.doc.nodeAt(pos)
+    if (node) tr.setNodeMarkup(pos, undefined, { ...node.attrs, uri })
+  }
+  for (const chip of [...found.chips].reverse()) {
+    tr.replaceWith(chip.from, chip.to, type.create({ uri: chip.uri, href: chip.url, marks: chip.marks }))
+  }
+  // Not a step of the person's: undo takes back what they typed, not the chip it became.
+  // Whether a pasted URL became its chip: `ReferenceMenu` opens on that one, never on a URL typed by hand.
+  return tr.setMeta('addToHistory', false).setMeta(CHIPS_MADE, { pasted: found.chips.some((chip) => chip.pasted) })
+}
+
+/**
+ * Look at the document again — after the app learned what more URLs name some
+ * other way. Dispatches only when there is a chip to make: an empty
+ * transaction would wake every other plugin (a trailing paragraph appears).
+ */
+export function refreshLinkChips(editor: Editor): void {
+  if (editor.isDestroyed) return
+  const chips = key.getState(editor.state)
+  if (!chips) return
+  const tr = apply(editor.state, findLinkChips(editor.state.doc, editor.state.selection, chips.options.referenceOf, chips.pasted))
+  if (tr) editor.view.dispatch(tr)
+}
+
+/**
+ * Turns the app URLs in a document into URL chips. Pair it with `ReferenceNode`;
+ * `ReferenceCards` then draws a card a URL chip asks for.
+ */
+export const LinkChips = Extension.create<LinkChipsOptions>({
+  name: 'linkChips',
+  addOptions() {
+    return { referenceOf: null, ask: null, limit: 24 }
+  },
+  addProseMirrorPlugins() {
+    const options = this.options
+    const editor = this.editor
+    return [
+      new Plugin<LinkChipsState>({
+        key,
+        // The options, where `refreshLinkChips` can read them from the state alone, and where the last pastes landed.
+        state: {
+          init: () => ({ options, pasted: [] }),
+          apply: (tr, value, before, after) => {
+            if (!tr.docChanged) return value
+            // A paste edited inside is being typed again: forgotten, so each keystroke in it is not an ask (security review).
+            const pasted = value.pasted
+              .map((range) => ({ from: tr.mapping.map(range.from, 1), to: tr.mapping.map(range.to, -1), size: range.to - range.from }))
+              .filter((range) => range.from < range.to && range.to - range.from === range.size)
+              .map(({ from, to }) => ({ from, to }))
+            if (tr.getMeta('uiEvent') === 'paste') {
+              const from = tr.mapping.map(before.selection.from, -1)
+              if (from < after.selection.to) pasted.push({ from, to: after.selection.to })
+            }
+            return { options, pasted: pasted.slice(-PASTES_KEPT) }
+          },
+        },
+        appendTransaction: (trs, _old, state) => {
+          if (!trs.some((tr) => tr.docChanged || tr.selectionSet)) return null
+          return apply(state, findLinkChips(state.doc, state.selection, options.referenceOf, key.getState(state)?.pasted))
+        },
+        view: (view) => {
+          // Each URL is asked once; one whose ask failed is forgotten, so a later look asks again.
+          const asked = new Set<string>()
+          // The URL being typed is not asked about: each prefix of it would spend one of `limit`, and a query.
+          const look = (state: EditorState) => {
+            if (!options.ask) return
+            const { open } = findLinkChips(state.doc, state.selection, options.referenceOf, key.getState(state)?.pasted)
+            const fresh = open.filter((url) => !asked.has(url)).slice(0, Math.max(0, options.limit - asked.size))
+            if (!fresh.length) return
+            for (const url of fresh) asked.add(url)
+            const forget = () => {
+              for (const url of fresh) asked.delete(url)
+            }
+            let answer: Promise<unknown> | void
+            try {
+              answer = options.ask(fresh)
+            } catch {
+              forget()
+              return
+            }
+            void Promise.resolve(answer).then(() => refreshLinkChips(editor), forget)
+          }
+          look(view.state)
+          // Once the view is up, so a dispatch lands: what the app already knows turns into chips on open.
+          queueMicrotask(() => {
+            try {
+              refreshLinkChips(editor)
+            } catch {
+              // Unmounted before it ran.
+            }
+          })
+          return {
+            update: (next, prev) => {
+              // A caret leaving a URL finishes it, so a move is looked at as an edit is.
+              if (next.state.doc !== prev.doc || !next.state.selection.eq(prev.selection)) look(next.state)
+            },
+          }
+        },
+      }),
+    ]
+  },
+})

package/src/NavItem.mdx

@@ -30,6 +30,14 @@ count — a muted mono number whose tooltip says what it counts.
 
 <Canvas of={NavItemStories.WithMenu} />
 
+- One thing done often enough to stay in sight — take the row off a list —
+  is `action`: an icon, its tooltip and its handler, the shape of a
+  **SectionHeader**'s actions. It shows with the ⋮, in the count's place, and
+  before the ⋮ when the row has a menu too. One, never a row of them: a second
+  thing to do goes in the menu.
+
+<Canvas of={NavItemStories.WithAction} />
+
 - A row with rows under it takes them as `children`: more `NavItem`s. The
   row stays a link; while it is pointed at or focused, its icon becomes the
   arrow that folds them, in the icon's own place, and they slide shut. For a
@@ -77,6 +85,8 @@ import { NavItem } from '@estiva-app/ui'
 - The label truncates; the count never gives up its width.
 - `menu` is the items only: `menu={<MenuItem label="Move to Folder…" onClick={move} />}`.
   The ⋮'s name is `More options for {label}` unless `menuLabel` says otherwise.
+- `action` is `{ icon, tooltip, onClick }`: `action={{ icon: <IconX size={16} stroke={1.5} />, tooltip: 'Remove from list', onClick: remove }}`.
+  Its name is `{tooltip}: {label}`.
 - `children` start open; `defaultOpen={false}` starts them folded, and
   `open` with `onOpenChange` hands the state to the app. The arrow's name is
   `Hide what is under {label}` or `Show what is under {label}`.

package/src/NavItem.stories.tsx

@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
-import { IconSquareRounded } from '@tabler/icons-react'
+import { IconSquareRounded, IconX } from '@tabler/icons-react'
 import { Chip } from './Chip'
 import { MenuItem } from './Menu'
 import { NavItem } from './NavItem'
@@ -109,3 +109,25 @@ export const UnreadUrgent: Story = {
 export const UnreadWithMenu: Story = {
   args: { icon: placeholder, unread: true, menu: MENU },
 }
+
+const REMOVE = { icon: <IconX size={16} stroke={1.5} />, tooltip: 'Remove from list', onClick: () => {} }
+
+/** One button of its own, in sight rather than in a menu: point at the row and it takes the count's place, as the ⋮ does. */
+export const WithAction: Story = {
+  args: { icon: placeholder, action: REMOVE },
+}
+
+/** The button and the ⋮ together: the button sits before it, and a long label stops short of both. */
+export const WithActionAndMenu: Story = {
+  args: { label: 'An item whose label runs much longer than the column has room for', icon: placeholder, action: REMOVE, menu: MENU },
+}
+
+/** A hint and a button: point at it and the chip shows, then the button — a row whose state is a word (here, archived) and which can be taken off the list. */
+export const WithActionAndHint: Story = {
+  args: { label: 'An item whose label runs much longer than the column has room for', icon: placeholder, action: REMOVE, hint: <Chip type="neutral" label="Archived" /> },
+}
+
+/** Unread, with a button: point at it and the button lands on the dot. */
+export const UnreadWithAction: Story = {
+  args: { icon: placeholder, unread: true, action: REMOVE },
+}

package/src/NavItem.test.tsx

@@ -141,3 +141,39 @@ describe('NavItem unread', () => {
     expect(menu?.className).toContain('right-1')
   })
 })
+
+describe('NavItem with a button of its own', () => {
+  const remove = (onClick = () => {}) => ({ icon: <svg />, tooltip: 'Remove from list', onClick })
+
+  it('draws the button beside the link, named for its row, and a click runs it, not the link', async () => {
+    const onClick = vi.fn()
+    const onLink = vi.fn()
+    render(<NavItem href="#" label="Item one" action={remove(onClick)} onClick={onLink} />)
+    const button = screen.getByRole('button', { name: 'Remove from list: Item one' })
+    expect(button.closest('a')).toBeNull()
+    await userEvent.click(button)
+    expect(onClick).toHaveBeenCalledOnce()
+    expect(onLink).not.toHaveBeenCalled()
+  })
+
+  it('shows with the row, as the ⋮ does: in its place at right-1, always on a screen with no hover', () => {
+    render(<NavItem href="#" label="Item one" action={remove()} />)
+    const box = screen.getByRole('button', { name: 'Remove from list: Item one' }).closest('[data-nav-menu]')!
+    expect(box.className.split(' ')).toEqual(expect.arrayContaining(['right-1', 'opacity-0', 'group-hover/nav:opacity-100', '[@media(hover:none)]:opacity-100']))
+  })
+
+  it('with a menu too, sits before the ⋮, and the row keeps room for both while they show', () => {
+    const { container } = render(<NavItem href="#" label="Item one" action={remove()} menu={<span>Action</span>} />)
+    const buttons = [...container.querySelectorAll('[data-nav-menu] button')].map((b) => b.getAttribute('aria-label'))
+    expect(buttons).toEqual(['Remove from list: Item one', 'More options for Item one'])
+    const kept = [...container.querySelectorAll('a > [aria-hidden="true"]')].map((s) => s.className.split(' '))
+    expect(kept).toHaveLength(2)
+    expect(kept[0]).toContain('w-5')
+    expect(kept[1]).toContain('w-6')
+  })
+
+  it('lands on the dot, which steps aside for it', () => {
+    const { container } = render(<NavItem href="#" label="Item one" unread action={remove()} />)
+    expect(container.querySelector('[data-unread]')!.parentElement!.className.split(' ')).toContain('group-hover/nav:opacity-0')
+  })
+})

package/src/NavItem.tsx

@@ -6,6 +6,7 @@ import { cn } from './cn'
 import { COLLAPSIBLE_PANEL_CLASSES, COUNT_TEXT_CLASSES, SIDEBAR_ROW_CLASSES, SIDEBAR_ROW_TEXT_CLASSES } from './looks'
 import { IconButton } from './IconButton'
 import { Menu } from './Menu'
+import type { SectionAction } from './SectionHeader'
 import { UnreadDot } from './UnreadDot'
 import { WithTooltip } from './Tooltip'
 
@@ -33,6 +34,13 @@ import { WithTooltip } from './Tooltip'
  * link, like the ⋮. The rows slide as `CollapsibleSection`'s do, indented
  * past the icon so their icons start under this row's label.
  *
+ * `action` is one button of its own beside the ⋮ — any icon, with its tooltip
+ * (Katerina, 14 October: Peek's Open work keeps its ✕ "Remove from list" in
+ * sight, not inside a menu). The same shape as a `SectionHeader`'s actions,
+ * and drawn the same way: an `IconButton` that shows with the ⋮, in the
+ * count's place, before the ⋮ when there is one. One, never a row of them: a
+ * second thing to do goes in the menu.
+ *
  * `hint` is shown only while the row is pointed at or focused, left of the
  * count — a neutral `Chip`, typically. It takes its own room while it shows,
  * so the label ends with "…" before it instead of running under it.
@@ -60,6 +68,8 @@ export interface NavItemProps extends Omit<ComponentPropsWithoutRef<'a'>, 'href'
   menu?: ReactNode
   /** The ⋮'s accessible name and tooltip. Default "More options for {label}". */
   menuLabel?: string
+  /** One button beside the ⋮, shown with it: any 16px icon, its tooltip and its handler — a `SectionHeader` action's shape. With a menu too, it sits before the ⋮. */
+  action?: SectionAction
   /** Shown only while the row is pointed at or focused, left of the count: a neutral `Chip`, typically. */
   hint?: ReactNode
   /** Something new here: brighter words, the label in medium, and the `UnreadDot` at the right. Say so in the row's own words for assistive tech too. */
@@ -85,6 +95,7 @@ export function NavItem({
   icon,
   menu,
   menuLabel,
+  action,
   hint,
   unread = false,
   urgent = false,
@@ -107,7 +118,8 @@ export function NavItem({
   }
   // The row draws beside it — the ⋮, the arrow — so the pointer can leave the
   // link for them while the row still reads as the one it is on.
-  const besides = menu != null || hasRows
+  const buttons = (menu != null ? 1 : 0) + (action ? 1 : 0)
+  const besides = buttons > 0 || hasRows
   // What sits at the right at rest, after the count: the dot, or the badge.
   const mark = unread ? (urgent ? <UrgentMark /> : <UnreadDot />) : null
   // Under the ⋮ while it shows: the count and the mark step aside for it.
@@ -117,7 +129,7 @@ export function NavItem({
   // hidden (Katerina, 5 October).
   // A screen with no hover shows the ⋮ always (below), so what it lands on
   // steps aside always: the row reads as it does under a pointer.
-  const stepsAside = menu != null && 'transition-opacity group-hover/nav:opacity-0 group-has-[:focus-visible]/nav:opacity-0 group-has-[[data-nav-menu]_[aria-expanded=true]]/nav:opacity-0 [@media(hover:none)]:opacity-0'
+  const stepsAside = buttons > 0 && 'transition-opacity group-hover/nav:opacity-0 group-has-[:focus-visible]/nav:opacity-0 group-has-[[data-nav-menu]_[aria-expanded=true]]/nav:opacity-0 [@media(hover:none)]:opacity-0'
 
   const row = (
     <a
@@ -134,7 +146,7 @@ export function NavItem({
         // look while the ⋮ is pointed at and while its menu is open. The same
         // for the arrow.
         besides && !active && 'group-hover/nav:bg-bg-hover group-hover/nav:text-text-primary',
-        menu != null && !active && 'group-has-[[data-nav-menu]_[aria-expanded=true]]/nav:bg-bg-hover group-has-[[data-nav-menu]_[aria-expanded=true]]/nav:text-text-primary',
+        buttons > 0 && !active && 'group-has-[[data-nav-menu]_[aria-expanded=true]]/nav:bg-bg-hover group-has-[[data-nav-menu]_[aria-expanded=true]]/nav:text-text-primary',
         className,
       )}
       {...props}
@@ -156,6 +168,11 @@ export function NavItem({
         // Takes room only while it shows, so the label gives way to it.
         <span className="hidden shrink-0 items-center group-hover/nav:flex group-has-[:focus-visible]/nav:flex">{hint}</span>
       )}
+      {buttons > 1 && (
+        // Two buttons: the second one's room (24px and the 4px between them, the
+        // row's 8px gap making up the rest), kept only while they show.
+        <span aria-hidden="true" className="hidden w-5 shrink-0 group-hover/nav:block group-has-[:focus-visible]/nav:block group-has-[[data-nav-menu]_[aria-expanded=true]]/nav:block [@media(hover:none)]:block" />
+      )}
       {count ? (
         <WithTooltip label={countLabel ?? `${count} open`}>
           {/* A 16px box, centred: the slot is an icon's width, so a number
@@ -179,7 +196,7 @@ export function NavItem({
         // of the ⋮ (8px from the edge to the 16px box), one column with a
         // folder heading's dot and ⋮ (Katerina, 5 October).
         <span className={cn('-mr-1 flex shrink-0', stepsAside)}>{mark}</span>
-      ) : menu != null && !count ? (
+      ) : buttons > 0 && !count ? (
         // Nothing at the right, but a menu: no room is kept at rest, so the
         // label has the row's whole width; while the ⋮ shows, its 24px slot
         // is kept, so a long label ends before it instead of running under it.
@@ -210,7 +227,7 @@ export function NavItem({
           </IconButton>
         </div>
       )}
-      {menu != null && (
+      {buttons > 0 && (
         // `right-1`: the 24px button's 16px icon ends 8px from the row's
         // edge, where a count ends (px-2) — and where a SectionHeader's
         // actions and ⋮ end, so a folder's ⋮ and its rows' ⋮ are one column
@@ -219,17 +236,24 @@ export function NavItem({
         // right of the slot's centre.
         // On a screen with no hover it always shows: nothing there can point
         // at the row, and the menu has no other way in.
-        <div data-nav-menu className={cn('absolute inset-y-0 right-1 flex items-center', 'opacity-0 transition-opacity group-hover/nav:opacity-100 group-has-[:focus-visible]/nav:opacity-100 has-[[aria-expanded=true]]:opacity-100 [@media(hover:none)]:opacity-100')}>
-          <Menu
-            align="right"
-            trigger={
-              <IconButton tooltip="More options" aria-label={name}>
-                <IconDotsVertical size={16} stroke={1.5} />
-              </IconButton>
-            }
-          >
-            {menu}
-          </Menu>
+        <div data-nav-menu className={cn('absolute inset-y-0 right-1 flex items-center gap-1', 'opacity-0 transition-opacity group-hover/nav:opacity-100 group-has-[:focus-visible]/nav:opacity-100 has-[[aria-expanded=true]]:opacity-100 [@media(hover:none)]:opacity-100')}>
+          {action && (
+            <IconButton tooltip={action.tooltip} aria-label={`${action.tooltip}: ${label}`} onClick={action.onClick}>
+              {action.icon}
+            </IconButton>
+          )}
+          {menu != null && (
+            <Menu
+              align="right"
+              trigger={
+                <IconButton tooltip="More options" aria-label={name}>
+                  <IconDotsVertical size={16} stroke={1.5} />
+                </IconButton>
+              }
+            >
+              {menu}
+            </Menu>
+          )}
         </div>
       )}
     </div>

package/src/ReferenceCards.mdx

@@ -0,0 +1,79 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks'
+import * as ReferenceCardsStories from './ReferenceCards.stories'
+
+<Meta of={ReferenceCardsStories} />
+
+# ReferenceCards
+
+A chip in a document can ask for a card after its line: compact, detailed or
+none. The choice is the chip's own `embed`, so the card moves and goes with it.
+This draws no card itself. It places a slot after each line that asks for
+one, and the app draws its own card into it.
+
+<Canvas of={ReferenceCardsStories.InAnEditor} />
+
+## When
+
+- **An editor of a document whose chips can carry a card**: pair it with
+  **ReferenceNode**, which holds the choice, and **SelectionToolbar**, where
+  the app offers it for the selected chip.
+
+## When not
+
+- A document that is only read → **RichText**, with each block's cards drawn
+  after it from the text's own description of them.
+- A text whose cards travel beside it rather than on its chips → the app keeps
+  that choice itself, and this has nothing to read.
+
+## How
+
+```tsx
+import { createPortal } from 'react-dom'
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { ToolbarButton } from '@estiva-app/ui'
+import {
+  BlockId,
+  ReferenceCards,
+  ReferenceNode,
+  SelectionToolbar,
+  referenceAtSelection,
+  setReferenceCard,
+  useReferenceCards,
+  type ReferenceCard,
+  type ReferenceViewProps,
+} from '@estiva-app/ui/editor'
+
+const Reference = ({ uri }: ReferenceViewProps) => <span>{uri}</span>
+const Cards = ({ cards }: { cards: ReferenceCard[] }) => <div>{cards.map((card) => card.layout).join(', ')}</div>
+
+const editor = useEditor({ extensions: [StarterKit, BlockId, ReferenceNode.configure({ view: Reference }), ReferenceCards] })
+const slots = useReferenceCards(editor)
+const chip = editor ? referenceAtSelection(editor.state) : null
+
+;<>
+  <EditorContent editor={editor} />
+  {slots.map((slot) => createPortal(<Cards cards={slot.cards} />, slot.element, slot.key))}
+  <SelectionToolbar editor={editor}>
+    {chip && editor && (
+      <ToolbarButton aria-label="Detailed" pressed={chip.layout === 'detailed'} onMouseDown={(e) => e.preventDefault()} onClick={() => setReferenceCard(editor, chip.layout === 'detailed' ? 'none' : 'detailed')}>
+        D
+      </ToolbarButton>
+    )}
+  </SelectionToolbar>
+</>
+```
+
+- **A slot keeps its element while its line lives.** It is keyed by the
+  line's block id, so typing above a card does not make it load again.
+- **The slot is not text.** It cannot be typed into or selected, and a click
+  on a card stays the card's.
+- **A layout this version does not know draws as compact.** The writer asked
+  for a card, and the smallest is the safe reading.
+- **Press without taking the focus.** A button in the toolbar prevents its
+  press's default, or the editor loses the chip's selection and the toolbar
+  goes.
+
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.

package/src/ReferenceCards.stories.tsx

@@ -0,0 +1,64 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+// @estiva-escape(no-hand-rolled-behaviour): the slots ReferenceCards places inside the document are drawn into by a portal, which keeps the app's providers around its card
+import { createPortal } from 'react-dom'
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { BlockId, ReferenceNode } from './BlockNodes'
+import { Card } from './Card'
+import { ReferenceCards, useReferenceCards } from './ReferenceCards'
+import { richTextClassName } from './RichText'
+
+/**
+ * A chip that asks for a card gets a slot after its line, and the app draws
+ * its card there. Here the "card" is a stand-in box naming the layout: the real
+ * one is the app's, which knows how to resolve what the chip points at.
+ */
+const meta = {
+  title: 'Primitives/ReferenceCards',
+  parameters: { layout: 'padded' },
+} satisfies Meta
+
+export default meta
+type Story = StoryObj
+
+const ref = (uri: string, embed?: string) => ({ type: 'reference', attrs: { uri, ...(embed ? { embed } : {}) } })
+
+function Box() {
+  const editor = useEditor({
+    extensions: [StarterKit, BlockId, ReferenceNode, ReferenceCards],
+    content: {
+      type: 'doc',
+      content: [
+        { type: 'paragraph', attrs: { blockId: 'p1' }, content: [{ type: 'text', text: 'Blocked by ' }, ref('nostr:naddr1first', 'detailed'), { type: 'text', text: ' until it ships.' }] },
+        { type: 'paragraph', attrs: { blockId: 'p2' }, content: [{ type: 'text', text: 'See also ' }, ref('nostr:naddr1second')] },
+        { type: 'paragraph', attrs: { blockId: 'p3' }, content: [ref('nostr:naddr1third', 'compact')] },
+      ],
+    },
+    editorProps: { attributes: { class: richTextClassName('default', 'outline-none'), 'aria-label': 'Text' } },
+  })
+  const slots = useReferenceCards(editor)
+  // @estiva-escape(no-hand-rolled-behaviour): the app's card goes into the slot ReferenceCards placed after its line, inside the document; no Base UI part owns a place in an editor's text
+  return (
+    <Card fill="surface" className="flex w-[520px] flex-col gap-2 p-3">
+      <EditorContent editor={editor} />
+      {slots.map((slot) =>
+        createPortal(
+          <div className="mt-2 flex flex-col gap-2">
+            {slot.cards.map((card, i) => (
+              <Card key={`${card.uri}-${i}`} fill="surface" className="p-3">
+                <span className="text-body-2 text-text-secondary">
+                  {card.layout} card for {card.uri}
+                </span>
+              </Card>
+            ))}
+          </div>,
+          slot.element,
+          slot.key,
+        ),
+      )}
+    </Card>
+  )
+}
+
+/** Three chips: a detailed card after the first line, none for the second, a compact one after the third. */
+export const InAnEditor: Story = { render: () => <Box /> }