@estiva-app/ui 0.50.4 → 0.52.0

package/src/ComposerTriggers.mdx

@@ -0,0 +1,108 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks'
+import * as ComposerTriggersStories from './ComposerTriggers.stories'
+
+<Meta of={ComposerTriggersStories} />
+
+# ComposerTriggers
+
+The four keys a composer shares across apps: `@` and `!@` to mention a person,
+`[` to reference something, `/` to format the line or insert something. Each
+opens a `SuggestionMenu` at the caret; a pick inserts a chip.
+
+<Canvas of={ComposerTriggersStories.Default} />
+
+## When
+
+- **`PersonMention` and `UrgentPersonMention`** — any editor whose text names
+  people. The urgent one is the same chip in the urgent tone.
+- **`CaptionedReference` and `ReferenceTrigger`** — referencing something the
+  app can list, drawn as who wrote it and its opening words.
+- **`SlashCommands`** — `formatSection()` first, then only the rows the app can
+  perform. `formatSection('block')` makes Code a block, for an editor of a
+  block document.
+
+## When not
+
+- Formatting text already written → **SelectionToolbar**. Bold, italic and
+  underline are not in `/` for that reason.
+- A list that is not opened by a key typed in an editor → **CommandPalette** or
+  **Menu**.
+- Drawing a sent body → **RichText**. These are for editing only.
+
+## How
+
+```tsx
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { IconSquareRounded } from '@tabler/icons-react'
+import {
+  CaptionedReference,
+  PersonMention,
+  ReferenceTrigger,
+  SlashCommands,
+  UrgentPersonMention,
+  formatSection,
+  typeTrigger,
+  urgentPubkeys,
+  type CaptionedItem,
+  type MentionPerson,
+} from '@estiva-app/ui/editor'
+
+const people = (): MentionPerson[] => [{ id: 'one', name: 'Person one', pubkey: null }]
+const items = (): CaptionedItem[] => [{ id: 'one', label: 'Person one', snippet: 'Item one', uri: 'nostr:item' }]
+
+const editor = useEditor({
+  extensions: [
+    StarterKit,
+    PersonMention.configure({ people }),
+    UrgentPersonMention.configure({ people }),
+    CaptionedReference.configure({ icon: <IconSquareRounded size={14} stroke={1.5} /> }),
+    ReferenceTrigger.configure({ items, ariaLabel: 'Items', sectionLabel: 'Items', icon: <IconSquareRounded size={16} stroke={1.5} /> }),
+    SlashCommands.configure({
+      sections: [formatSection(), { label: 'Insert', commands: [{ key: 'insert-@', row: { label: 'Mention', shortcut: '@' }, run: typeTrigger('@') }] }],
+    }),
+  ],
+})
+
+const urgent = editor ? urgentPubkeys(editor) : undefined
+
+<EditorContent editor={editor} />
+```
+
+- **The body is written by `@estiva-app/conversation`, not here.** A mention
+  chip carries `pubkey` and `label` for its `mentionText`; a reference chip
+  carries the `uri` the app built with that package, written back verbatim. The
+  urgency is not in the text: hand `urgentPubkeys(editor)` to `urgentTagsFor`.
+- **The lists ask each time the query changes.** `people` and `items` are
+  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.
+- **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`).
+- **A row that opens another list** runs `typeTrigger('@')`: it types the key
+  once the `/query` is gone.
+- An open list is reported by `isSuggestionActive()`, so an editor that sends
+  on Enter does not send on the Enter that picked a row.
+
+<Canvas of={ComposerTriggersStories.CodeAsABlock} />
+
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.
+
+## Keys
+
+The lists are `SuggestionMenu`s, and their keys are its own. What the body
+says, the tags it earns and sending stay the app's.
+
+
+| Key | Does |
+| --- | --- |
+| `@` after a space or at the line's start | Opens the people list |
+| `!@` | Opens the urgent list |
+| `[` | Opens the reference list |
+| `/` after a space or at the line's start | Opens Format and the app's sections |
+| ↑ ↓ | Move the highlight, wrapping at the ends |
+| Enter | Inserts the highlighted row, or runs it |
+| Escape | Closes the list |

package/src/ComposerTriggers.stories.tsx

@@ -0,0 +1,79 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconSquareRounded } from '@tabler/icons-react'
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { richTextClassName } from './RichText'
+import {
+  CaptionedReference,
+  PersonMention,
+  ReferenceTrigger,
+  SlashCommands,
+  UrgentPersonMention,
+  formatSection,
+  typeTrigger,
+  type CaptionedItem,
+  type MentionPerson,
+  type SlashSection,
+} from './ComposerTriggers'
+
+/**
+ * The four composer triggers: `@` and `!@` offer a person, `[` offers
+ * something to reference, and `/` formats the line or inserts something.
+ * Type one of them in the box.
+ */
+const meta = {
+  title: 'Primitives/ComposerTriggers',
+  parameters: { layout: 'padded' },
+} satisfies Meta
+
+export default meta
+type Story = StoryObj
+
+const PEOPLE: MentionPerson[] = ['one', 'two', 'three', 'four', 'five', 'six', 'seven'].map((n, i) => ({
+  id: `person-${n}`,
+  name: `Person ${n}`,
+  description: i % 2 === 0 ? 'Label' : undefined,
+  pubkey: null,
+}))
+
+const ITEMS: CaptionedItem[] = ['one', 'two', 'three'].map((n) => ({
+  id: `item-${n}`,
+  label: 'Person one',
+  snippet: `Item ${n}`,
+  uri: `nostr:item-${n}`,
+}))
+
+const INSERT: SlashSection = {
+  label: 'Insert',
+  commands: [
+    { key: 'insert-@', row: { label: 'Mention', shortcut: '@' }, keywords: ['@'], run: typeTrigger('@') },
+    { key: 'insert-[', row: { label: 'Reference', shortcut: '[' }, keywords: ['['], run: typeTrigger('[') },
+  ],
+}
+
+function Composer({ code }: { code: 'inline' | 'block' }) {
+  const editor = useEditor({
+    extensions: [
+      StarterKit,
+      PersonMention.configure({ people: () => PEOPLE }),
+      UrgentPersonMention.configure({ people: () => PEOPLE }),
+      CaptionedReference.configure({ icon: <IconSquareRounded size={14} stroke={1.5} /> }),
+      ReferenceTrigger.configure({
+        items: () => ITEMS,
+        ariaLabel: 'Items',
+        sectionLabel: 'Items',
+        icon: <IconSquareRounded size={16} stroke={1.5} className="text-text-secondary" />,
+      }),
+      SlashCommands.configure({ sections: [formatSection(code), INSERT] }),
+    ],
+    content: '<p>Type @, !@, [ or / after a space: </p>',
+    editorProps: { attributes: { class: richTextClassName('default', 'min-h-[80px] w-[480px] rounded-md border border-border-default p-3 outline-none') } },
+  })
+  return <EditorContent editor={editor} />
+}
+
+/** Code as a mark inside the line. */
+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" /> }

package/src/ComposerTriggers.test.tsx

@@ -0,0 +1,207 @@
+// @vitest-environment jsdom
+/**
+ * The composer triggers (CON-27, moved from Peek's `mention.tsx` and
+ * `slashCommands.tsx`): each opens its list at the caret, and a pick inserts
+ * the chip the body is written from.
+ */
+import { act } from 'react'
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
+import { render, screen, cleanup, within } from '@testing-library/react'
+import type { Editor } from '@tiptap/core'
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import {
+  CaptionedReference,
+  PersonMention,
+  ReferenceTrigger,
+  SlashCommands,
+  UrgentPersonMention,
+  filterPeople,
+  filterReferences,
+  filterSlashSections,
+  formatSection,
+  typeTrigger,
+  urgentPubkeys,
+  type CaptionedItem,
+  type MentionPerson,
+  type SlashSection,
+} from './ComposerTriggers'
+
+const KEY = 'b'.repeat(64)
+const PEOPLE: MentionPerson[] = [
+  { id: 'ada', name: 'Ada Lovelace', description: 'Engineering', pubkey: KEY },
+  { id: 'bea', name: 'Bea', pubkey: null },
+  ...['Cy', 'Di', 'Ed', 'Flo', 'Gus'].map((name) => ({ id: name.toLowerCase(), name })),
+]
+const ITEMS: CaptionedItem[] = Array.from({ length: 8 }, (_, i) => ({
+  id: `${i}`.repeat(64),
+  label: i === 7 ? 'Bea' : 'Ada',
+  snippet: `line ${i}`,
+  uri: `nostr:nevent1example${i}`,
+  search: `**line** ${i}`,
+}))
+const APP_SECTION: SlashSection = {
+  label: 'Shortcuts',
+  commands: [{ key: 'shortcut-@', row: { label: 'Mention', shortcut: '@' }, keywords: ['@', 'Mention a person'], run: typeTrigger('@') }],
+}
+
+// An app's own name for the chip, as Peek's `messageMention`.
+const Chip = CaptionedReference.extend({ name: 'messageMention' })
+
+let editor: Editor | null = null
+
+function Composer() {
+  const made = useEditor({
+    extensions: [
+      StarterKit,
+      PersonMention.configure({ people: () => PEOPLE }),
+      UrgentPersonMention.configure({ people: () => PEOPLE }),
+      Chip,
+      ReferenceTrigger.configure({ items: () => ITEMS, nodeName: 'messageMention', ariaLabel: 'Things', sectionLabel: 'Things' }),
+      SlashCommands.configure({ sections: [formatSection(), APP_SECTION] }),
+    ],
+  })
+  editor = made
+  return <EditorContent editor={made} />
+}
+
+async function type(text: string) {
+  await act(async () => {
+    editor!.chain().focus().insertContent(text).run()
+  })
+}
+
+async function press(key: string) {
+  await act(async () => {
+    editor!.view.someProp('handleKeyDown', (handle) => handle(editor!.view, new KeyboardEvent('keydown', { key })))
+  })
+}
+
+// The highlighted row also draws its Enter hint; the label is what is compared.
+const options = () => within(screen.getByRole('listbox')).getAllByRole('option').map((one) => one.textContent?.replace('↩ Enter', ''))
+const nodes = () => {
+  const found: { type: string; attrs: Record<string, unknown> }[] = []
+  editor!.state.doc.descendants((node) => {
+    if (node.isInline && !node.isText) found.push({ type: node.type.name, attrs: node.attrs })
+  })
+  return found
+}
+
+// jsdom lays nothing out, so it has no `scrollIntoView`; the highlighted row calls it.
+beforeAll(() => {
+  Element.prototype.scrollIntoView = vi.fn()
+  ;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+})
+
+afterEach(() => {
+  editor?.destroy()
+  editor = null
+  cleanup()
+})
+
+describe('@ and !@', () => {
+  it('lists the first six people, narrowed by name, and a pick inserts a chip with their key', async () => {
+    render(<Composer />)
+    await type('@')
+    expect(screen.getByRole('listbox', { name: 'People' })).toBeTruthy()
+    expect(options()).toHaveLength(6)
+    await type('ada')
+    expect(options()).toHaveLength(1)
+    await press('Enter')
+    expect(nodes()).toEqual([{ type: 'mention', attrs: { id: 'ada', label: 'Ada Lovelace', pubkey: KEY } }])
+    expect(editor!.getHTML()).toContain('data-mention="true"')
+    expect(screen.queryByRole('listbox')).toBeNull()
+  })
+
+  it('opens the urgent list on !@, and the document reports whose key it names', async () => {
+    render(<Composer />)
+    await type('!@')
+    expect(screen.getByRole('listbox', { name: 'Urgent mention' })).toBeTruthy()
+    await press('Enter')
+    expect(nodes()[0]).toEqual({ type: 'urgentMention', attrs: { id: 'ada', label: 'Ada Lovelace', pubkey: KEY } })
+    expect(urgentPubkeys(editor!)).toEqual([KEY])
+  })
+
+  it('keeps a person with no key, who has nothing to carry urgently', () => {
+    expect(filterPeople(PEOPLE, 'BE')).toEqual([PEOPLE[1]])
+    expect(filterPeople(PEOPLE, '')).toHaveLength(6)
+  })
+})
+
+describe('[', () => {
+  it('lists the last six references and inserts the app-named chip with its uri', async () => {
+    render(<Composer />)
+    await type('[')
+    expect(screen.getByRole('listbox', { name: 'Things' })).toBeTruthy()
+    expect(options()).toEqual(['Ada: line 2', 'Ada: line 3', 'Ada: line 4', 'Ada: line 5', 'Ada: line 6', 'Bea: line 7'])
+    await press('Enter')
+    expect(nodes()).toEqual([{ type: 'messageMention', attrs: { id: ITEMS[2].id, label: 'Ada', snippet: 'line 2', uri: ITEMS[2].uri } }])
+    expect(editor!.getHTML()).toContain('data-message-mention="true"')
+  })
+
+  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])
+  })
+})
+
+describe('a chip through HTML (copy and paste)', () => {
+  it('keeps who it names and what it points at, and takes no key or uri from a crafted attribute', async () => {
+    render(<Composer />)
+    await act(async () => {
+      editor!.commands.setContent([
+        {
+          type: 'paragraph',
+          content: [
+            { type: 'mention', attrs: { id: 'ada', label: 'Ada Lovelace', pubkey: KEY } },
+            { type: 'messageMention', attrs: { id: ITEMS[0].id, label: 'Ada', snippet: 'line 0', uri: ITEMS[0].uri } },
+          ],
+        },
+      ])
+    })
+    const html = editor!.getHTML()
+    await act(async () => {
+      editor!.commands.setContent(html)
+    })
+    expect(nodes()).toEqual([
+      { type: 'mention', attrs: { id: 'ada', label: 'Ada Lovelace', pubkey: KEY } },
+      { type: 'messageMention', attrs: { id: ITEMS[0].id, label: 'Ada', snippet: 'line 0', uri: ITEMS[0].uri } },
+    ])
+    await act(async () => {
+      editor!.commands.setContent(
+        '<p><span data-urgent-mention="true" data-id="x" data-label="Ada" data-pubkey="not-a-key">@Ada</span>' +
+          '<span data-message-mention="true" data-id="y" data-label="Ada" data-uri="javascript:alert(1)">Ada</span></p>',
+      )
+    })
+    const [person, reference] = nodes()
+    expect([person.type, person.attrs.label, person.attrs.pubkey]).toEqual(['urgentMention', 'Ada', null])
+    expect([reference.type, reference.attrs.uri]).toEqual(['messageMention', null])
+  })
+})
+
+describe('/', () => {
+  it('opens Format first, then the app’s sections, and runs the chosen row', async () => {
+    render(<Composer />)
+    await type('/')
+    expect(screen.getByRole('listbox', { name: 'Commands' })).toBeTruthy()
+    expect(options()).toEqual(['Text', 'Heading#', 'Subheading##', 'Quote>', 'Code`', 'Bulleted list-', 'Numbered list1.', 'Mention@'])
+    await type('head')
+    await press('Enter')
+    expect(editor!.getJSON().content?.[0]).toEqual({ type: 'heading', attrs: { level: 1 } })
+  })
+
+  it('narrows on a label, an id or a keyword, and keeps an emptied section', () => {
+    const sections = [formatSection(), APP_SECTION]
+    const labels = (q: string) => filterSlashSections(sections, q).map((s) => s.commands.map((c) => c.row.label))
+    expect(labels('list')).toEqual([['Bulleted list', 'Numbered list'], []])
+    expect(labels('mention a person')).toEqual([[], ['Mention']])
+    expect(labels('HEAD')).toEqual([['Heading', 'Subheading'], []])
+  })
+
+  it('makes code a block when the app asks for one', async () => {
+    render(<Composer />)
+    const code = formatSection('block').commands.find((c) => c.key === 'format-code')!
+    await act(async () => code.run(editor!))
+    expect(editor!.getJSON().content?.[0].type).toBe('codeBlock')
+  })
+})