@estiva-app/ui 0.67.0 → 0.69.0

package/src/ReferenceCards.test.tsx

@@ -0,0 +1,143 @@
+// @vitest-environment jsdom
+/**
+ * A reference's card in a block document (SPEC §13.3): the choice is `embed` on
+ * the `reference` node, kept through `getJSON`, and the slot it asks for sits
+ * after its line and keeps its element while the line lives.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { act, cleanup, render } from '@testing-library/react'
+import { createPortal } from 'react-dom'
+import { Editor } from '@tiptap/core'
+import { NodeSelection, TextSelection } from '@tiptap/pm/state'
+import StarterKit from '@tiptap/starter-kit'
+import { BlockId, ReferenceNode } from './BlockNodes'
+import { ReferenceCards, referenceAtSelection, referenceCardPlacements, setReferenceCard, useReferenceCards } from './ReferenceCards'
+
+const EXTENSIONS = [StarterKit, BlockId, ReferenceNode, ReferenceCards]
+const V = 'nostr:naddr1example'
+const W = 'nostr:naddr1other'
+
+type Json = { type: string; attrs?: Record<string, unknown>; content?: Json[] }
+const json = (ed: Editor) => ed.getJSON() as Json
+
+const ref = (uri: string, attrs: Record<string, unknown> = {}) => ({ type: 'reference', attrs: { uri, ...attrs } })
+const DOCUMENT = {
+  type: 'doc',
+  content: [
+    { type: 'paragraph', attrs: { blockId: 'p1' }, content: [{ type: 'text', text: 'Blocked by ' }, ref(V, { embed: 'detailed' }), { type: 'text', text: ' for now' }] },
+    { type: 'paragraph', attrs: { blockId: 'p2' }, content: [ref(W)] },
+    { type: 'bulletList', attrs: { blockId: 'l1' }, content: [{ type: 'listItem', attrs: { blockId: 'i1' }, content: [{ type: 'paragraph', content: [ref(W, { embed: 'huge' })] }] }] },
+  ],
+}
+
+let editor: Editor | undefined
+afterEach(() => {
+  cleanup()
+  editor?.destroy()
+  editor = undefined
+})
+
+const select = (ed: Editor, uri: string) => {
+  let at = -1
+  ed.state.doc.descendants((node, pos) => {
+    if (at < 0 && node.type.name === 'reference' && node.attrs.uri === uri) at = pos
+  })
+  ed.view.dispatch(ed.state.tr.setSelection(NodeSelection.create(ed.state.doc, at)))
+}
+
+describe('ReferenceNode keeps the card', () => {
+  it('holds embed and extra through getJSON', () => {
+    editor = new Editor({ extensions: EXTENSIONS, content: { type: 'doc', content: [{ type: 'paragraph', content: [ref(V, { embed: 'compact', extra: { later: 1 } })] }] } })
+    const node = json(editor).content?.[0].content?.[0]
+    expect(node?.attrs?.embed).toBe('compact')
+    expect(node?.attrs?.extra).toEqual({ later: 1 })
+  })
+})
+
+describe('referenceCardPlacements', () => {
+  it('asks for a slot after each line whose chips chose a card, keyed by block id', () => {
+    editor = new Editor({ extensions: EXTENSIONS, content: DOCUMENT })
+    const placements = referenceCardPlacements(editor.state.doc)
+    expect(placements.map((p) => [p.key, p.cards])).toEqual([
+      ['b:p1', [{ uri: V, layout: 'detailed' }]],
+      // A list item's paragraph carries no id of its own: the item's is used. An unknown layout is compact.
+      ['b:i1', [{ uri: W, layout: 'compact' }]],
+    ])
+  })
+
+  it('draws an empty, non-editable slot inside the line', () => {
+    editor = new Editor({ extensions: EXTENSIONS, content: DOCUMENT })
+    const slot = editor.view.dom.querySelector('[data-reference-cards="b:p1"]')
+    expect(slot?.getAttribute('contenteditable')).toBe('false')
+    expect(slot?.closest('p')?.textContent).toContain('for now')
+    expect(editor.view.dom.querySelectorAll('[data-reference-cards]')).toHaveLength(2)
+  })
+})
+
+describe('choosing a card', () => {
+  it('reads and sets the selected chip\'s card, and none removes it', () => {
+    editor = new Editor({ extensions: EXTENSIONS, content: DOCUMENT })
+    select(editor, W)
+    expect(referenceAtSelection(editor.state)).toMatchObject({ uri: W, layout: 'none' })
+
+    expect(setReferenceCard(editor, 'detailed')).toBe(true)
+    expect(referenceAtSelection(editor.state)).toMatchObject({ uri: W, layout: 'detailed' })
+    expect(referenceCardPlacements(editor.state.doc).map((p) => p.key)).toEqual(['b:p1', 'b:p2', 'b:i1'])
+
+    setReferenceCard(editor, 'none')
+    expect(json(editor).content?.[1].content?.[0].attrs?.embed).toBeNull()
+    expect(referenceCardPlacements(editor.state.doc).map((p) => p.key)).toEqual(['b:p1', 'b:i1'])
+  })
+
+  it('finds the one chip in a selected range of spaces and that chip, and keeps the range', () => {
+    editor = new Editor({ extensions: EXTENSIONS, content: DOCUMENT })
+    // The second paragraph is the chip alone: select across all of it, as Shift+arrow does.
+    let start = -1
+    editor.state.doc.forEach((node, offset, index) => {
+      if (index === 1) start = offset + 1
+    })
+    editor.view.dispatch(editor.state.tr.setSelection(TextSelection.create(editor.state.doc, start, start + 1)))
+    expect(referenceAtSelection(editor.state)).toMatchObject({ uri: W, layout: 'none' })
+    setReferenceCard(editor, 'compact')
+    expect(editor.state.selection.from).toBe(start)
+    expect(editor.state.selection.to).toBe(start + 1)
+    expect(referenceAtSelection(editor.state)).toMatchObject({ uri: W, layout: 'compact' })
+  })
+
+  it('offers nothing for a range with words in it, or with two chips', () => {
+    editor = new Editor({ extensions: EXTENSIONS, content: DOCUMENT })
+    // "Blocked by " and the chip after it.
+    editor.view.dispatch(editor.state.tr.setSelection(TextSelection.create(editor.state.doc, 1, 13)))
+    expect(referenceAtSelection(editor.state)).toBeNull()
+    editor.view.dispatch(editor.state.tr.setSelection(TextSelection.create(editor.state.doc, 1, editor.state.doc.content.size - 1)))
+    expect(referenceAtSelection(editor.state)).toBeNull()
+  })
+
+  it('offers nothing when no chip is selected', () => {
+    editor = new Editor({ extensions: EXTENSIONS, content: DOCUMENT })
+    expect(referenceAtSelection(editor.state)).toBeNull()
+    expect(setReferenceCard(editor, 'compact')).toBe(false)
+  })
+})
+
+describe('useReferenceCards', () => {
+  function Cards({ ed }: { ed: Editor }) {
+    const slots = useReferenceCards(ed)
+    return <>{slots.map((s) => createPortal(<span data-card={s.cards.map((c) => c.layout).join(',')} />, s.element, s.key))}</>
+  }
+
+  it('portals the app\'s cards into the slots, and typing keeps the slot\'s element', () => {
+    editor = new Editor({ extensions: EXTENSIONS, content: DOCUMENT })
+    const ed = editor
+    render(<Cards ed={ed} />)
+    const before = ed.view.dom.querySelector('[data-reference-cards="b:p1"]')
+    expect(before?.querySelector('[data-card="detailed"]')).not.toBeNull()
+
+    act(() => {
+      ed.commands.insertContentAt(1, 'Still ')
+    })
+    const after = ed.view.dom.querySelector('[data-reference-cards="b:p1"]')
+    expect(after).toBe(before)
+    expect(after?.querySelector('[data-card="detailed"]')).not.toBeNull()
+  })
+})

package/src/ReferenceCards.ts

@@ -0,0 +1,225 @@
+/**
+ * The cards a block document's writer chose, drawn after the line that holds
+ * each reference — SPEC §13.3, "A reference's card".
+ *
+ * The choice is `embed` on the `reference` node (`ReferenceNode`), so the card
+ * moves and goes with its chip. What a card looks like is the app's — it knows
+ * how to resolve an object and draw its row or its card — so this extension
+ * draws nothing itself: after every textblock whose chips ask for a card it
+ * places one empty, non-editable slot, and `useReferenceCards` hands the app
+ * those slots to portal its cards into. A portal, rather than a React root per
+ * slot, keeps the app's providers around the card.
+ *
+ * **A slot keeps its element while its block lives.** It is keyed by the
+ * nearest block id (the `blockId` attribute), so typing above a card does not
+ * re-make its element, and the card does not reload on every keystroke.
+ *
+ * The slot sits at the end of the textblock, inside it: a paragraph's card is
+ * under the paragraph, a list item's under the item at its indent, a table
+ * cell's in the cell.
+ */
+import { Extension, type Editor } from '@tiptap/core'
+import type { Node as PmNode } from '@tiptap/pm/model'
+import { NodeSelection, Plugin, PluginKey, type EditorState } from '@tiptap/pm/state'
+import { Decoration, DecorationSet } from '@tiptap/pm/view'
+import { useEffect, useState } from 'react'
+
+/** A layout a writer can choose; `none` is no card. */
+export type ReferenceCardLayout = 'none' | 'compact' | 'detailed'
+
+/** One card to draw: the reference's `nostr:` URI and how much to show. */
+export interface ReferenceCard {
+  uri: string
+  layout: Exclude<ReferenceCardLayout, 'none'>
+}
+
+/** One slot: where an app draws the cards of one line. */
+export interface ReferenceCardSlot {
+  key: string
+  element: HTMLElement
+  cards: ReferenceCard[]
+}
+
+interface Placement {
+  key: string
+  /** The end of the textblock's content, where the slot goes. */
+  pos: number
+  cards: ReferenceCard[]
+}
+
+/** `embed` as a node holds it: an unknown string draws as compact (§13.3), anything else is none. */
+function layoutOf(raw: unknown): ReferenceCard['layout'] | undefined {
+  if (typeof raw !== 'string' || raw === '' || raw === 'none') return undefined
+  return raw === 'detailed' ? 'detailed' : 'compact'
+}
+
+/** Every line that asks for a card, in document order. */
+export function referenceCardPlacements(doc: PmNode): Placement[] {
+  const out: Placement[] = []
+  const seen = new Map<string, number>()
+  doc.descendants((node, pos, parent) => {
+    if (!node.isTextblock) return true
+    const cards: ReferenceCard[] = []
+    node.forEach((child) => {
+      if (child.type.name !== 'reference') return
+      const layout = layoutOf(child.attrs.embed)
+      // A URL chip whose URL is not resolved yet (`LinkChips`) has nothing to draw a card of, yet.
+      if (layout && child.attrs.uri) cards.push({ uri: String(child.attrs.uri), layout })
+    })
+    if (cards.length) {
+      // The textblock's own id, or its list item's or cell's: the nearest one.
+      const id = node.attrs.blockId ?? parent?.attrs.blockId
+      const base = id ? `b:${String(id)}` : `p:${pos}`
+      const n = seen.get(base) ?? 0
+      seen.set(base, n + 1)
+      out.push({ key: n ? `${base}:${n}` : base, pos: pos + node.nodeSize - 1, cards })
+    }
+    return false
+  })
+  return out
+}
+
+interface ReferenceCardsStorage {
+  /** One element per slot key, made once and reused, so the app's portal stays put. */
+  elements: Map<string, HTMLElement>
+}
+
+const key = new PluginKey<DecorationSet>('referenceCards')
+
+function elementFor(storage: ReferenceCardsStorage, slotKey: string): HTMLElement {
+  let element = storage.elements.get(slotKey)
+  if (!element) {
+    element = document.createElement('div')
+    element.setAttribute('data-reference-cards', slotKey)
+    element.setAttribute('contenteditable', 'false')
+    storage.elements.set(slotKey, element)
+  }
+  return element
+}
+
+function storageOf(editor: Editor): ReferenceCardsStorage | undefined {
+  return (editor.storage as unknown as { referenceCards?: ReferenceCardsStorage }).referenceCards
+}
+
+/**
+ * Places a slot after each line whose chips ask for a card. Pair it with
+ * `ReferenceNode`, and draw the cards with `useReferenceCards`.
+ */
+export const ReferenceCards = Extension.create<Record<string, never>, ReferenceCardsStorage>({
+  name: 'referenceCards',
+  addStorage() {
+    return { elements: new Map() }
+  },
+  addProseMirrorPlugins() {
+    const storage = this.storage
+    const decorate = (doc: PmNode) =>
+      DecorationSet.create(
+        doc,
+        referenceCardPlacements(doc).map((p) =>
+          Decoration.widget(p.pos, () => elementFor(storage, p.key), {
+            key: p.key,
+            side: 1,
+            ignoreSelection: true,
+            // A click on a card is the card's, not a caret placement in the line.
+            stopEvent: () => true,
+          }),
+        ),
+      )
+    return [
+      new Plugin<DecorationSet>({
+        key,
+        state: {
+          init: (_, state) => decorate(state.doc),
+          apply: (tr, set) => (tr.docChanged ? decorate(tr.doc) : set),
+        },
+        props: { decorations: (state) => key.getState(state) },
+      }),
+    ]
+  },
+})
+
+/**
+ * The slots to draw cards into, kept current as the document changes. Draw
+ * each with `createPortal(<cards/>, slot.element)`, keyed by `slot.key`.
+ */
+export function useReferenceCards(editor: Editor | null): ReferenceCardSlot[] {
+  const [slots, setSlots] = useState<ReferenceCardSlot[]>([])
+  useEffect(() => {
+    if (!editor) return
+    const storage = storageOf(editor)
+    if (!storage) return
+    let last = ''
+    const read = () => {
+      if (editor.isDestroyed) return
+      const next = referenceCardPlacements(editor.state.doc).map((p) => ({ key: p.key, element: elementFor(storage, p.key), cards: p.cards }))
+      // Only a change in what is drawn re-renders the app; typing does not.
+      const signature = JSON.stringify(next.map((s) => [s.key, s.cards]))
+      if (signature === last) return
+      last = signature
+      const live = new Set(next.map((s) => s.key))
+      for (const k of storage.elements.keys()) if (!live.has(k)) storage.elements.delete(k)
+      setSlots(next)
+    }
+    read()
+    editor.on('transaction', read)
+    return () => {
+      editor.off('transaction', read)
+    }
+  }, [editor])
+  return slots
+}
+
+/**
+ * The chip the person has selected, with what it names and its card — or null.
+ *
+ * Selected as a node (a click, where a click on the chip does not follow its
+ * link), or inside a selected range that holds that one chip and nothing but
+ * spaces besides (Shift+arrow over it, or a drag across it): an app whose chip
+ * is a link has no other way to select it.
+ */
+export function referenceAtSelection(state: EditorState): { pos: number; uri: string; layout: ReferenceCardLayout } | null {
+  const { selection } = state
+  let found: { pos: number; node: PmNode } | null = null
+  if (selection instanceof NodeSelection) {
+    if (selection.node.type.name === 'reference') found = { pos: selection.from, node: selection.node }
+  } else if (!selection.empty) {
+    let only = true
+    state.doc.nodesBetween(selection.from, selection.to, (node, pos) => {
+      if (node.type.name === 'reference') {
+        if (found) only = false
+        found = { pos, node }
+        return false
+      }
+      if (node.isText) {
+        const from = Math.max(selection.from, pos) - pos
+        const to = Math.min(selection.to, pos + node.nodeSize) - pos
+        if ((node.text ?? '').slice(from, to).trim() !== '') only = false
+      }
+      return true
+    })
+    if (!only) found = null
+  }
+  if (!found) return null
+  const { pos, node } = found as { pos: number; node: PmNode }
+  // A URL chip that names nothing yet has no card to choose.
+  if (!node.attrs.uri) return null
+  return { pos, uri: String(node.attrs.uri ?? ''), layout: layoutOf(node.attrs.embed) ?? 'none' }
+}
+
+/** Sets the card of the selected chip. `none` removes it. The selection stays as it was. */
+export function setReferenceCard(editor: Editor, layout: ReferenceCardLayout): boolean {
+  const at = referenceAtSelection(editor.state)
+  return at ? setReferenceCardAt(editor, at.pos, layout) : false
+}
+
+/** Sets the card of the chip at `pos` — one that names something. `none` removes it. The selection stays as it was. */
+export function setReferenceCardAt(editor: Editor, pos: number, layout: ReferenceCardLayout): boolean {
+  const node = editor.state.doc.nodeAt(pos)
+  if (!node || node.type.name !== 'reference' || !node.attrs.uri) return false
+  const wasNode = editor.state.selection instanceof NodeSelection && editor.state.selection.from === pos
+  // Same size, so a range maps onto itself; a node selection is made again, since the node is replaced.
+  const tr = editor.state.tr.setNodeMarkup(pos, undefined, { ...node.attrs, embed: layout === 'none' ? null : layout })
+  if (wasNode) tr.setSelection(NodeSelection.create(tr.doc, pos))
+  editor.view.dispatch(tr)
+  return true
+}

package/src/ReferenceMenu.mdx

@@ -0,0 +1,75 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks'
+import * as ReferenceMenuStories from './ReferenceMenu.stories'
+
+<Meta of={ReferenceMenuStories} />
+
+# ReferenceMenu
+
+What a chip in a document offers whoever is writing it: **Open**, and its
+**Card** — none, compact or detailed. The card draws after the chip's line.
+
+<Canvas of={ReferenceMenuStories.InAnEditor} />
+
+## When
+
+- **An editor of a document whose chips can ask for a card**: pair it with
+  **ReferenceNode**, which draws the chip, and **ReferenceCards**, which places
+  the card. With **LinkChips**, a pasted URL that becomes its chip opens the
+  menu too.
+
+## When not
+
+- A document that is only read → **RichText**: a click on a chip follows it.
+- An editor whose chips take no card → leave it out, and a click on a chip
+  follows it as when reading.
+
+## How
+
+```tsx
+import { EditorContent, useEditor } from '@tiptap/react'
+import { ReferenceCards, ReferenceMenu, ReferenceMenuView, ReferenceNode, isReferenceMenuOpen } from '@estiva-app/ui/editor'
+
+const editor = useEditor({
+  extensions: [/* … */ ReferenceNode.configure({ view: Chip }), ReferenceCards, ReferenceMenu],
+  editorProps: {
+    handleKeyDown: (view, event) => {
+      // While the menu is open, Escape is its own: it closes the menu.
+      if (event.key === 'Escape' && isReferenceMenuOpen(view.state)) return false
+      // …
+    },
+  },
+})
+
+<EditorContent editor={editor} />
+<ReferenceMenuView editor={editor} />
+```
+
+- **A click on a chip while editing** opens the menu under it, instead of
+  following the chip. Not editing, the click follows it.
+- **A chip just put in** — pasted, picked with `[`, or a pasted URL becoming its
+  chip — opens the menu by itself. It takes no focus: typing on closes it, and
+  the chip keeps no card.
+- **Open** does what a click on the chip does when reading: the app's chip gets
+  the click. A chip with nothing to click opens its URL in a new tab.
+- Open is offered only when there is something to open: the chip's own link
+  or button, or its URL. A chip whose URL names nothing yet offers Open only;
+  one with neither has no menu, and a click goes on to it.
+- The menu closes when the editor loses focus, so a card is never chosen after
+  the editor has saved on leaving.
+- Choosing a card is an undo step; the menu closes.
+
+## What it owns
+
+Nothing. Its box is the Popover; it holds which chip the menu is open on, and its keys.
+
+## Keys
+
+| Key | Does |
+| --- | --- |
+| Enter, on a selected chip | Opens the menu, its first row highlighted |
+| ↓ / ↑ | Moves through the rows; nothing is highlighted until then |
+| Enter | Chooses the highlighted row; with none, the editor's own Enter |
+| Escape | Closes the menu |
+
+The panel takes no focus, so it is reached only through these keys. A key with
+Shift, Ctrl, Alt or Cmd stays the editor's: Shift+↓ extends the selection.

package/src/ReferenceMenu.stories.tsx

@@ -0,0 +1,59 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { BlockId, ReferenceNode, type ReferenceViewProps } from './BlockNodes'
+import { Card } from './Card'
+import { InlineChip } from './InlineChip'
+import { ReferenceCards, useReferenceCards } from './ReferenceCards'
+import { ReferenceMenu, ReferenceMenuView } from './ReferenceMenu'
+import { richTextClassName } from './RichText'
+
+/**
+ * Click the chip: its menu opens under it — Open, and a card of none, compact
+ * or detailed. The chip is a placeholder naming what it points at, and the
+ * card a line naming its layout: the real ones are the app's.
+ */
+const meta = {
+  title: 'Primitives/ReferenceMenu',
+  parameters: { layout: 'padded' },
+} satisfies Meta
+
+export default meta
+type Story = StoryObj
+
+function Placeholder({ uri }: ReferenceViewProps) {
+  return <InlineChip>Item for {uri}</InlineChip>
+}
+
+function Box() {
+  const editor = useEditor({
+    extensions: [StarterKit.configure({ link: false }), BlockId, ReferenceNode.configure({ view: Placeholder }), ReferenceCards, ReferenceMenu],
+    content: {
+      type: 'doc',
+      content: [
+        {
+          type: 'paragraph',
+          attrs: { blockId: 'p1' },
+          content: [
+            { type: 'text', text: 'See ' },
+            { type: 'reference', attrs: { uri: 'nostr:naddr1one' } },
+            { type: 'text', text: ' for the details.' },
+          ],
+        },
+      ],
+    },
+    editorProps: { attributes: { class: richTextClassName('default', 'outline-none'), 'aria-label': 'Text' } },
+  })
+  const slots = useReferenceCards(editor)
+  const cards = slots.flatMap((slot) => slot.cards.map((card) => `${card.layout} card for ${card.uri}`))
+  return (
+    <Card fill="surface" className="flex w-[520px] flex-col gap-2 p-3">
+      <EditorContent editor={editor} />
+      <ReferenceMenuView editor={editor} />
+      <p className="text-caption text-text-secondary">{cards.length ? cards.join(', ') : 'No card'}</p>
+    </Card>
+  )
+}
+
+/** A chip in a sentence: click it to open its menu, and choose a card. */
+export const InAnEditor: Story = { render: () => <Box /> }