@estiva-app/ui 0.82.1 → 0.84.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/dist/BlockNodes.d.ts +16 -5
  2. package/dist/BlockNodes.d.ts.map +1 -1
  3. package/dist/CommentBox.d.ts +11 -2
  4. package/dist/CommentBox.d.ts.map +1 -1
  5. package/dist/ComposeBox.d.ts +17 -0
  6. package/dist/ComposeBox.d.ts.map +1 -1
  7. package/dist/DocumentEditor.d.ts +5 -4
  8. package/dist/DocumentEditor.d.ts.map +1 -1
  9. package/dist/LinkPlaces.d.ts +51 -0
  10. package/dist/LinkPlaces.d.ts.map +1 -0
  11. package/dist/ReferenceMenu.d.ts.map +1 -1
  12. package/dist/editor.d.ts +1 -0
  13. package/dist/editor.d.ts.map +1 -1
  14. package/dist/editor.js +392 -178
  15. package/dist/editor.js.map +4 -4
  16. package/dist/linked.examples.d.ts.map +1 -1
  17. package/dist/links.d.ts.map +1 -1
  18. package/package.json +1 -1
  19. package/registry.json +75 -12
  20. package/src/BlockNodes.tsx +36 -9
  21. package/src/CommentBox.mdx +11 -1
  22. package/src/CommentBox.stories.tsx +75 -2
  23. package/src/CommentBox.test.tsx +170 -3
  24. package/src/CommentBox.tsx +211 -53
  25. package/src/ComposeBox.tsx +19 -2
  26. package/src/DocumentEditor.mdx +7 -2
  27. package/src/DocumentEditor.stories.tsx +101 -15
  28. package/src/DocumentEditor.test.tsx +49 -0
  29. package/src/DocumentEditor.tsx +17 -10
  30. package/src/LinkPlaces.mdx +59 -0
  31. package/src/LinkPlaces.stories.tsx +60 -0
  32. package/src/LinkPlaces.test.ts +134 -0
  33. package/src/LinkPlaces.ts +169 -0
  34. package/src/ReferenceCards.mdx +4 -0
  35. package/src/ReferenceMenu.mdx +32 -24
  36. package/src/ReferenceMenu.stories.tsx +15 -16
  37. package/src/ReferenceMenu.test.tsx +161 -57
  38. package/src/ReferenceMenu.tsx +48 -44
  39. package/src/editor.ts +1 -0
  40. package/src/linked.examples.ts +4 -3
  41. package/src/links.ts +4 -1
  42. package/src/pages.test.ts +2 -2
  43. package/src/registry/registry.test.ts +6 -6
  44. package/stories/Choosing.mdx +3 -2
@@ -18,7 +18,7 @@ import { LinkChips, type LinkChipsOptions } from './LinkChips'
18
18
  import { BareLinks, DocumentKit, LINK_MARK_ATTRIBUTES, PasteOverWords } from './links'
19
19
  import { PastedImages } from './PastedImages'
20
20
  import { PastedMarkdown } from './PastedMarkdown'
21
- import { ReferenceCards } from './ReferenceCards'
21
+ import { LinkPlaces } from './LinkPlaces'
22
22
  import { ReferenceMenu, ReferenceMenuView, isReferenceMenuOpen } from './ReferenceMenu'
23
23
  import { richTextClassName } from './RichText'
24
24
  import { KeptSelection, SelectionToolbar } from './SelectionToolbar'
@@ -118,12 +118,13 @@ export interface DocumentEditorProps {
118
118
  onCommentOnSelection?: (anchor: SelectionAnchor) => void
119
119
  /** The app's rows in a block's handle menu, after the editing ones: Copy link, Comment. */
120
120
  blockRows?: (block: HandleBlock) => ReactNode
121
- /** Draws a chip: the app's own, which resolves what it names. */
121
+ /**
122
+ * Draws a link: the app's own, which resolves what it names — its chip, its
123
+ * row or its card in the row's place, as `place` says (§13.3).
124
+ */
122
125
  referenceView?: ComponentType<ReferenceViewProps>
123
126
  /** Draws a placed file: the app's own card. */
124
127
  attachmentView?: ComponentType<AttachmentViewProps>
125
- /** Drawn after the text: the cards chips ask for, as the app draws them. */
126
- cards?: (editor: Editor | null) => ReactNode
127
128
  /** Around everything the editor draws: the app's providers, which may read the editor. */
128
129
  wrap?: (children: ReactNode, editor: Editor | null) => ReactNode
129
130
  /** The editor, once it is there, and `null` as it goes. */
@@ -186,7 +187,6 @@ export function DocumentEditor({
186
187
  blockRows,
187
188
  referenceView,
188
189
  attachmentView,
189
- cards,
190
190
  wrap,
191
191
  onEditor,
192
192
  extensions = [],
@@ -363,9 +363,9 @@ export function DocumentEditor({
363
363
  Checklist,
364
364
  Callout,
365
365
  ReferenceNode.configure({ view: referenceView ?? null }),
366
- // The card a chip asks for, after its line (SPEC §13.3); drawn by the app's `cards`.
367
- ReferenceCards,
368
- // A click on a chip offers Open and its card.
366
+ // A link's chip in a sentence, its row alone on its line, its card in the row's place (SPEC §13.3).
367
+ LinkPlaces,
368
+ // A click on a link offers Open, and alone on its line Show as Row or Card.
369
369
  ReferenceMenu,
370
370
  UnknownBlock,
371
371
  AttachmentNode.configure({ view: attachmentView ?? null }),
@@ -410,7 +410,15 @@ export function DocumentEditor({
410
410
  editable: !readOnly,
411
411
  editorProps: {
412
412
  // Focusable when read only too: the selection strip, and so Comment on its words, shows only in a focused view.
413
- attributes: { 'aria-label': label, role: 'textbox', 'aria-multiline': 'true', tabindex: '0', class: richTextClassName('default', 'outline-none') },
413
+ attributes: {
414
+ 'aria-label': label,
415
+ role: 'textbox',
416
+ 'aria-multiline': 'true',
417
+ tabindex: '0',
418
+ // A row or a card is its whole line (`LinkPlaces`), drawn on that line: a block inside it would push the
419
+ // separator and trailing break ProseMirror puts beside it onto empty lines of their own (code review).
420
+ class: richTextClassName('default', 'outline-none [&_[data-link-place]]:inline-block [&_[data-link-place]]:w-full [&_[data-link-place]]:align-top'),
421
+ },
414
422
  handleKeyDown: (view, event) => {
415
423
  if (event.key !== 'Escape') return false
416
424
  // An open list or chip menu closes first; the next Escape leaves.
@@ -507,7 +515,6 @@ export function DocumentEditor({
507
515
  </span>
508
516
  )}
509
517
  </EditorBlockHandle>
510
- {cards?.(editor)}
511
518
  {/* Read only with comments off, the strip would have nothing in it: no strip. */}
512
519
  {(!readOnly || onCommentOnSelection) && <SelectionToolbar
513
520
  editor={editor}
@@ -0,0 +1,59 @@
1
+ import { Meta, Canvas } from '@storybook/addon-docs/blocks'
2
+ import * as LinkPlacesStories from './LinkPlaces.stories'
3
+
4
+ <Meta of={LinkPlacesStories} />
5
+
6
+ # LinkPlaces
7
+
8
+ Where a link in a document sits decides how it draws: its chip in a sentence,
9
+ its row alone on its line, and its card in the row's place when its writer
10
+ chose one (`embed` `detailed`). This tells each link's view its place; the
11
+ app's view draws the chip, row or card.
12
+
13
+ <Canvas of={LinkPlacesStories.InAnEditor} />
14
+
15
+ ## When
16
+
17
+ - **An editor of a document**: pair it with **ReferenceNode**, whose view is
18
+ handed `place`, and **ReferenceMenu**, whose Show as Row or Card changes it.
19
+ **DocumentEditor** has both.
20
+
21
+ ## When not
22
+
23
+ - A message's box, where every link is a chip while it is written → leave it
24
+ out: without it every view is told `chip`.
25
+ - A document that is only read, outside an editor → **RichText**, with the
26
+ lines drawn by the protocol's `documentLineDraws`, the same rule.
27
+
28
+ ## How
29
+
30
+ ```tsx
31
+ import { EditorContent, useEditor } from '@tiptap/react'
32
+ import StarterKit from '@tiptap/starter-kit'
33
+ import { LinkCard, LinkChip, LinkRow } from '@estiva-app/ui'
34
+ import { BlockId, LinkPlaces, ReferenceNode, type ReferenceViewProps } from '@estiva-app/ui/editor'
35
+
36
+ function Link({ uri, place = 'chip', editing }: ReferenceViewProps) {
37
+ const link = useResolved(uri) // the app's own lookup
38
+ if (place === 'card') return <LinkCard link={link} />
39
+ if (place === 'row') return <LinkRow link={link} preview={!editing} />
40
+ return <LinkChip link={link} preview={!editing} />
41
+ }
42
+
43
+ const editor = useEditor({ extensions: [StarterKit, BlockId, ReferenceNode.configure({ view: Link }), LinkPlaces] })
44
+ ```
45
+
46
+ - **Alone on its line** is a top-level paragraph's line, or a list item's, up
47
+ to a hard break, holding the link and nothing but spaces. A heading, a quote,
48
+ a callout and a table cell are sentences. So is a link inside a marker
49
+ (bold, italic, code).
50
+ - **A person or a Folder alone on its line stays a chip** (`staysChip`).
51
+ - **Only `detailed` draws the card.** No `embed`, `compact` or a value this
52
+ version does not know draws the row.
53
+ - **The same rule as the protocol's** `documentLineDrawOf`, read off the
54
+ editor's tree on every change; a test holds the two to one answer.
55
+ - **A row or a card is the whole line**: its view's wrapper is a block.
56
+
57
+ ## What it owns
58
+
59
+ Nothing. It only draws. Clicks and keys are yours.
@@ -0,0 +1,60 @@
1
+ import type { Meta, StoryObj } from '@storybook/react-vite'
2
+ import { EditorContent, useEditor } from '@tiptap/react'
3
+ import StarterKit from '@tiptap/starter-kit'
4
+ import { BlockId, ReferenceNode, type ReferenceViewProps } from './BlockNodes'
5
+ import { Card } from './Card'
6
+ import { InlineChip } from './InlineChip'
7
+ import { LinkPlaces } from './LinkPlaces'
8
+ import { richTextClassName } from './RichText'
9
+
10
+ /**
11
+ * Each link in a document is told where it sits, and the app draws it there:
12
+ * its chip in a sentence, its row alone on its line, its card in the row's
13
+ * place. Here the row and card are stand-in boxes naming the place; the real
14
+ * ones are the app's, which knows how to resolve what the link points at.
15
+ */
16
+ const meta = {
17
+ title: 'Primitives/LinkPlaces',
18
+ parameters: { layout: 'padded' },
19
+ } satisfies Meta
20
+
21
+ export default meta
22
+ type Story = StoryObj
23
+
24
+ const ref = (uri: string, embed?: string) => ({ type: 'reference', attrs: { uri, ...(embed ? { embed } : {}) } })
25
+
26
+ /** A stand-in for the app's drawing of a link, by its place. */
27
+ function Placed({ uri, place = 'chip' }: ReferenceViewProps) {
28
+ const name = uri.endsWith('one') ? 'Item one' : uri.endsWith('two') ? 'Item two' : 'Item three'
29
+ if (place === 'chip') return <InlineChip>{name}</InlineChip>
30
+ return (
31
+ <Card fill="inset" className={place === 'card' ? 'flex h-24 items-start p-3' : 'flex h-9 items-center px-3'}>
32
+ <span className="text-body-2 text-text-secondary">
33
+ {name}, its {place}
34
+ </span>
35
+ </Card>
36
+ )
37
+ }
38
+
39
+ function Box() {
40
+ const editor = useEditor({
41
+ extensions: [StarterKit, BlockId, ReferenceNode.configure({ view: Placed }), LinkPlaces],
42
+ content: {
43
+ type: 'doc',
44
+ content: [
45
+ { type: 'paragraph', attrs: { blockId: 'p1' }, content: [{ type: 'text', text: 'A sentence that names ' }, ref('nostr:naddr1one'), { type: 'text', text: ' in passing.' }] },
46
+ { type: 'paragraph', attrs: { blockId: 'p2' }, content: [ref('nostr:naddr1two')] },
47
+ { type: 'paragraph', attrs: { blockId: 'p3' }, content: [ref('nostr:naddr1three', 'detailed')] },
48
+ ],
49
+ },
50
+ editorProps: { attributes: { class: richTextClassName('default', 'outline-none'), 'aria-label': 'Text' } },
51
+ })
52
+ return (
53
+ <Card fill="surface" className="flex w-[520px] flex-col gap-2 p-3">
54
+ <EditorContent editor={editor} />
55
+ </Card>
56
+ )
57
+ }
58
+
59
+ /** A chip in a sentence, a row alone on its line, and a card chosen for the third. Type beside the row: it becomes a chip. */
60
+ export const InAnEditor: Story = { render: () => <Box /> }
@@ -0,0 +1,134 @@
1
+ // @vitest-environment jsdom
2
+ /**
3
+ * Where a link in a document sits decides how it draws (SPEC §13.3, C22): its
4
+ * chip in a sentence, its row alone on its line, its card in the row's place.
5
+ * The editor reads the rule off its own tree; the protocol reads it off the
6
+ * saved document. Both must give the same answer, or a page reads one way
7
+ * while it is written and another once it is saved.
8
+ */
9
+ import { afterEach, describe, expect, it } from 'vitest'
10
+ import { Editor, type JSONContent } from '@tiptap/core'
11
+ import { TableKit } from '@tiptap/extension-table'
12
+ import { documentForEditing, documentLineDraws, encodeNaddr, encodeNpub, publishableFromEditor, toEditorDocument, toRenderTree, type EditorDocument } from '@estiva-app/protocol'
13
+ import { BlockId, Callout, Checklist, ReferenceNode, UnknownBlock } from './BlockNodes'
14
+ import { LinkPlaces, linkPlaceAt, linkPlaces, staysChip, type LinkPlace } from './LinkPlaces'
15
+ import { DocumentKit } from './links'
16
+
17
+ const naddr = (kind: number, identifier: string) => `nostr:${encodeNaddr({ kind, pubkey: 'a'.repeat(64), identifier, relays: [] })}`
18
+ const V = naddr(30851, 'item-one')
19
+ const FOLDER = naddr(39000, 'place-one')
20
+ const PERSON = `nostr:${encodeNpub('b'.repeat(64))}`
21
+
22
+ const ref = (uri: string, attrs: Record<string, unknown> = {}): JSONContent => ({ type: 'reference', attrs: { uri, ...attrs } })
23
+ const text = (t: string): JSONContent => ({ type: 'text', text: t })
24
+ const p = (...content: JSONContent[]): JSONContent => ({ type: 'paragraph', content })
25
+ const doc = (...content: JSONContent[]): JSONContent => ({ type: 'doc', content })
26
+
27
+ let editor: Editor | undefined
28
+ afterEach(() => {
29
+ editor?.destroy()
30
+ editor = undefined
31
+ })
32
+
33
+ const make = (content: JSONContent | string) => {
34
+ editor = new Editor({
35
+ extensions: [DocumentKit.configure({ link: false }), TableKit, BlockId, Checklist, Callout, ReferenceNode, UnknownBlock, LinkPlaces],
36
+ content,
37
+ })
38
+ return editor
39
+ }
40
+
41
+ /** The place of the one reference in `content`. */
42
+ function placeIn(content: JSONContent): LinkPlace {
43
+ const ed = make(content)
44
+ let at = -1
45
+ ed.state.doc.descendants((node, pos) => {
46
+ if (node.type.name === 'reference' && at < 0) at = pos
47
+ })
48
+ return linkPlaceAt(ed.state.doc, at)
49
+ }
50
+
51
+ /** Each case: a document holding one reference, and how it draws. */
52
+ const CASES: [string, JSONContent, LinkPlace][] = [
53
+ ['alone in a paragraph', doc(p(ref(V))), 'row'],
54
+ ['alone with a space after it, as a `[` pick leaves it', doc(p(ref(V), text(' '))), 'row'],
55
+ ['in a sentence', doc(p(text('See '), ref(V), text(' today.'))), 'chip'],
56
+ ['followed by a full stop', doc(p(ref(V), text('.'))), 'chip'],
57
+ ['alone on the second line of a paragraph, after a hard break', doc(p(text('First line'), { type: 'hardBreak' }, ref(V))), 'row'],
58
+ ['in a heading', doc({ type: 'heading', attrs: { level: 2 }, content: [ref(V)] }), 'chip'],
59
+ ['in a quote', doc({ type: 'blockquote', content: [p(ref(V))] }), 'chip'],
60
+ ['in a callout', doc({ type: 'blockquote', attrs: { tone: 'note' }, content: [p(ref(V))] }), 'chip'],
61
+ ['alone in a list item', doc({ type: 'bulletList', content: [{ type: 'listItem', content: [p(ref(V))] }] }), 'row'],
62
+ ['alone in a checklist item', doc({ type: 'bulletList', content: [{ type: 'listItem', attrs: { checked: false }, content: [p(ref(V))] }] }), 'row'],
63
+ ['alone in a numbered list item', doc({ type: 'orderedList', content: [{ type: 'listItem', content: [p(ref(V))] }] }), 'row'],
64
+ ['in a table cell', doc({ type: 'table', content: [{ type: 'tableRow', content: [{ type: 'tableCell', content: [p(ref(V))] }] }] }), 'chip'],
65
+ ['alone with its card chosen', doc(p(ref(V, { embed: 'detailed' }))), 'card'],
66
+ ['alone with an older writer\'s compact card', doc(p(ref(V, { embed: 'compact' }))), 'row'],
67
+ ['alone with a card value this version does not know', doc(p(ref(V, { embed: 'wide' }))), 'row'],
68
+ ['in a sentence with its card chosen', doc(p(text('See '), ref(V, { embed: 'detailed' }))), 'chip'],
69
+ ['alone but bold', doc(p(ref(V, { marks: ['bold'] }))), 'chip'],
70
+ ['a person alone', doc(p(ref(PERSON))), 'chip'],
71
+ ['a Folder alone', doc(p(ref(FOLDER))), 'chip'],
72
+ ['a Folder alone with a card chosen', doc(p(ref(FOLDER, { embed: 'detailed' }))), 'chip'],
73
+ ]
74
+
75
+ describe('linkPlaceAt', () => {
76
+ it.each(CASES)('draws a link %s as its %s', (_name, content, place) => {
77
+ expect(placeIn(content)).toBe(place)
78
+ })
79
+
80
+ it('draws two links on one line as chips', () => {
81
+ const ed = make(doc(p(ref(V), text(' '), ref(naddr(30851, 'item-two')))))
82
+ expect(linkPlaces(ed.state.doc)).toEqual([])
83
+ })
84
+
85
+ it('draws a pasted URL not resolved yet as its URL, a chip, even alone', () => {
86
+ expect(placeIn(doc(p(ref('', { href: 'https://app.example/item/one' }))))).toBe('chip')
87
+ })
88
+
89
+ it('turns a row into a chip as soon as words are typed beside it, and back when they are deleted', () => {
90
+ const ed = make(doc(p(ref(V))))
91
+ expect(linkPlaceAt(ed.state.doc, 1)).toBe('row')
92
+ ed.commands.insertContentAt(2, 'and more')
93
+ expect(linkPlaceAt(ed.state.doc, 1)).toBe('chip')
94
+ ed.commands.deleteRange({ from: 2, to: 2 + 'and more'.length })
95
+ expect(linkPlaceAt(ed.state.doc, 1)).toBe('row')
96
+ })
97
+
98
+ it('tells the view of each lone link its place, through a node decoration', () => {
99
+ const ed = make(doc(p(ref(V)), p(ref(V, { embed: 'detailed' })), p(text('See '), ref(V))))
100
+ const places = [...ed.view.dom.querySelectorAll('[data-reference]')].map((el) => el.closest('[data-link-place]')?.getAttribute('data-link-place') ?? 'chip')
101
+ expect(places).toEqual(['row', 'card', 'chip'])
102
+ })
103
+ })
104
+
105
+ describe('staysChip', () => {
106
+ it('keeps a person and a Folder as chips, and nothing else', () => {
107
+ expect(staysChip(PERSON)).toBe(true)
108
+ expect(staysChip(FOLDER)).toBe(true)
109
+ expect(staysChip(FOLDER.toUpperCase())).toBe(true)
110
+ expect(staysChip(V)).toBe(false)
111
+ expect(staysChip(naddr(30850, 'group-one'))).toBe(false)
112
+ expect(staysChip('nostr:naddr1notbech32')).toBe(false)
113
+ })
114
+ })
115
+
116
+ describe('the editor and the protocol agree', () => {
117
+ /** How the protocol draws the saved document's one link: `row` or `card` where it says so, else its chip. */
118
+ function protocolPlace(value: string): LinkPlace {
119
+ for (const draws of documentLineDraws(toRenderTree(value, 'blocks')).values()) {
120
+ for (const line of draws) if (line.draw === 'row' || line.draw === 'card') return line.draw
121
+ }
122
+ return 'chip'
123
+ }
124
+
125
+ it.each(CASES)('on a link %s, once saved and opened again', (_name, content, place) => {
126
+ const { value } = publishableFromEditor(make(content).getJSON() as EditorDocument)
127
+ editor?.destroy()
128
+ // Opened again as an app opens it: the saved bytes, read back into the editor.
129
+ const reopened = make(toEditorDocument(documentForEditing(value, 'blocks'), { links: true }) as JSONContent)
130
+ const editorPlaces = linkPlaces(reopened.state.doc).map((one) => one.place)
131
+ expect(protocolPlace(value)).toBe(place)
132
+ expect(editorPlaces[0] ?? 'chip').toBe(place)
133
+ })
134
+ })
@@ -0,0 +1,169 @@
1
+ /**
2
+ * Where a reference in a block document sits, and so how it draws — SPEC §13.3,
3
+ * "A reference's card" (C22, C24): its chip in a sentence, its row alone on its
4
+ * line, and its card in the row's place when its writer chose one.
5
+ *
6
+ * The rule is the protocol's (`documentLineDrawOf` in `@estiva-app/protocol`),
7
+ * read here off the editor's own tree so it can be asked on every keystroke
8
+ * without writing the document out. `linkPlaces.test.ts` runs the same
9
+ * documents through both and holds them to one answer.
10
+ *
11
+ * - **Alone on its line**: a top-level paragraph, or a list item's, whose line
12
+ * (up to a hard break) holds this reference and nothing but spaces besides.
13
+ * A heading, a quote, a callout and a table cell are sentences, and so is
14
+ * anything inside a block this rule does not name.
15
+ * - **A marker around it** (bold, italic, code…) makes it a sentence.
16
+ * - **A person or a Folder** alone on its line stays a chip.
17
+ * - **Its card** is `embed` `detailed`; anything else (none, `compact`, a value
18
+ * this version does not know) draws the row.
19
+ *
20
+ * `LinkPlaces` puts each reference's place on a node decoration, which
21
+ * `ReferenceNode`'s view reads and hands to the app's view as `place`.
22
+ *
23
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-link-on-words-counts-toward-the-card.md
24
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-lone-links-chip-menu-offers-row-or-card.md
25
+ */
26
+ import { Extension } from '@tiptap/core'
27
+ import type { Node as PmNode } from '@tiptap/pm/model'
28
+ import { Plugin, PluginKey } from '@tiptap/pm/state'
29
+ import { Decoration, DecorationSet } from '@tiptap/pm/view'
30
+
31
+ /** How a reference draws: its chip, its row, or its card in the row's place. */
32
+ export type LinkPlace = 'chip' | 'row' | 'card'
33
+
34
+ /** The blocks a line may sit inside and still be alone: a list and its items. */
35
+ const CONTAINERS = new Set(['bulletList', 'orderedList', 'listItem'])
36
+
37
+ const BECH32 = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l'
38
+
39
+ /** The 5-bit words of a bech32 string's data part, checksum dropped, or null. */
40
+ function bech32Words(text: string): number[] | null {
41
+ const at = text.lastIndexOf('1')
42
+ if (at < 1 || text.length - at < 7) return null
43
+ const words: number[] = []
44
+ for (const char of text.slice(at + 1, -6)) {
45
+ const word = BECH32.indexOf(char)
46
+ if (word < 0) return null
47
+ words.push(word)
48
+ }
49
+ return words
50
+ }
51
+
52
+ /** An `naddr`'s kind (TLV type 3), or null when it does not hold one. */
53
+ function naddrKind(naddr: string): number | null {
54
+ const words = bech32Words(naddr)
55
+ if (!words) return null
56
+ const bytes: number[] = []
57
+ let acc = 0
58
+ let bits = 0
59
+ for (const word of words) {
60
+ acc = (acc << 5) | word
61
+ bits += 5
62
+ while (bits >= 8) {
63
+ bits -= 8
64
+ bytes.push((acc >> bits) & 0xff)
65
+ }
66
+ }
67
+ for (let i = 0; i + 1 < bytes.length; ) {
68
+ const type = bytes[i]
69
+ const length = bytes[i + 1]
70
+ if (type === 3 && length === 4 && i + 6 <= bytes.length) return ((bytes[i + 2] << 24) | (bytes[i + 3] << 16) | (bytes[i + 4] << 8) | bytes[i + 5]) >>> 0
71
+ i += 2 + length
72
+ }
73
+ return null
74
+ }
75
+
76
+ /** A Folder's kind. */
77
+ const FOLDER = 39000
78
+
79
+ /**
80
+ * Whether what `uri` names stays a chip alone on its line: a person (`npub`,
81
+ * `nprofile`) or a Folder (an `naddr` of kind 39000).
82
+ */
83
+ export function staysChip(uri: string): boolean {
84
+ const bare = uri.toLowerCase().replace(/^nostr:/, '')
85
+ if (bare.startsWith('npub1') || bare.startsWith('nprofile1')) return true
86
+ return bare.startsWith('naddr1') && naddrKind(bare) === FOLDER
87
+ }
88
+
89
+ /** Whether the textblock holding `pos` keeps the line rule: a paragraph at the top, or a list item's. */
90
+ function keepsLineRule(doc: PmNode, pos: number): boolean {
91
+ const $pos = doc.resolve(pos)
92
+ if ($pos.parent.type.name !== 'paragraph' && $pos.parent.type.name !== 'listItem') return false
93
+ for (let depth = 1; depth < $pos.depth; depth++) if (!CONTAINERS.has($pos.node(depth).type.name)) return false
94
+ return true
95
+ }
96
+
97
+ /** Whether the reference at `index` of `block` is alone on its line: only spaces beside it, up to a hard break either side. */
98
+ function aloneOnLine(block: PmNode, index: number): boolean {
99
+ for (const step of [-1, 1]) {
100
+ for (let i = index + step; i >= 0 && i < block.childCount; i += step) {
101
+ const child = block.child(i)
102
+ if (child.type.name === 'hardBreak') break
103
+ if (!child.isText || (child.text ?? '').trim() !== '') return false
104
+ }
105
+ }
106
+ return true
107
+ }
108
+
109
+ /** How the reference node at `pos` draws. Anything that is not a reference with a `uri` draws as a chip. */
110
+ export function linkPlaceAt(doc: PmNode, pos: number): LinkPlace {
111
+ const node = doc.nodeAt(pos)
112
+ if (!node || node.type.name !== 'reference') return 'chip'
113
+ const uri = String(node.attrs.uri ?? '')
114
+ // A URL chip whose URL is not resolved yet names nothing: it reads as the URL.
115
+ if (!uri || staysChip(uri)) return 'chip'
116
+ if (Array.isArray(node.attrs.marks) && node.attrs.marks.length > 0) return 'chip'
117
+ if (!keepsLineRule(doc, pos)) return 'chip'
118
+ const $pos = doc.resolve(pos)
119
+ if (!aloneOnLine($pos.parent, $pos.index())) return 'chip'
120
+ return node.attrs.embed === 'detailed' ? 'card' : 'row'
121
+ }
122
+
123
+ /** Every reference that does not draw as its chip, with its place. */
124
+ export function linkPlaces(doc: PmNode): { pos: number; size: number; place: Exclude<LinkPlace, 'chip'> }[] {
125
+ const out: { pos: number; size: number; place: Exclude<LinkPlace, 'chip'> }[] = []
126
+ doc.descendants((node, pos) => {
127
+ if (node.type.name !== 'reference') return true
128
+ const place = linkPlaceAt(doc, pos)
129
+ if (place !== 'chip') out.push({ pos, size: node.nodeSize, place })
130
+ return false
131
+ })
132
+ return out
133
+ }
134
+
135
+ /** The place a node view's decorations give it; `chip` without one. */
136
+ export function placeOf(decorations: readonly Decoration[] | undefined): LinkPlace {
137
+ for (const decoration of decorations ?? []) {
138
+ const place = (decoration.spec as { linkPlace?: LinkPlace }).linkPlace
139
+ if (place) return place
140
+ }
141
+ return 'chip'
142
+ }
143
+
144
+ const key = new PluginKey<DecorationSet>('linkPlaces')
145
+
146
+ /**
147
+ * Marks each reference that draws as its row or its card, for `ReferenceNode`'s
148
+ * view. Without it every reference is a chip, as in a message's box.
149
+ */
150
+ export const LinkPlaces = Extension.create({
151
+ name: 'linkPlaces',
152
+ addProseMirrorPlugins() {
153
+ const decorate = (doc: PmNode) =>
154
+ DecorationSet.create(
155
+ doc,
156
+ linkPlaces(doc).map(({ pos, size, place }) => Decoration.node(pos, pos + size, { 'data-link-place': place }, { linkPlace: place })),
157
+ )
158
+ return [
159
+ new Plugin<DecorationSet>({
160
+ key,
161
+ state: {
162
+ init: (_, state) => decorate(state.doc),
163
+ apply: (tr, set) => (tr.docChanged ? decorate(tr.doc) : set),
164
+ },
165
+ props: { decorations: (state) => key.getState(state) },
166
+ }),
167
+ ]
168
+ },
169
+ })
@@ -20,6 +20,10 @@ one, and the app draws its own card into it.
20
20
 
21
21
  ## When not
22
22
 
23
+ - A new editor of a document → **LinkPlaces**: since §13.3's line rule, a
24
+ card draws in a lone link's row's place, and a card on a link in a sentence
25
+ draws nothing. **DocumentEditor** uses it; this stays for an editor that has
26
+ not moved yet.
23
27
  - A document that is only read → **RichText**, with each block's cards drawn
24
28
  after it from the text's own description of them.
25
29
  - A text whose cards travel beside it rather than on its chips → the app keeps
@@ -5,32 +5,34 @@ import * as ReferenceMenuStories from './ReferenceMenu.stories'
5
5
 
6
6
  # ReferenceMenu
7
7
 
8
- What a chip in a document offers whoever is writing it: **Open**, and its
9
- **Card** — none, compact or detailed. The card draws after the chip's line.
8
+ What a link in a document offers whoever is writing it: **Open**, and — when
9
+ it is alone on its line — **Show as** Row or Card. Card puts its card in the
10
+ row's place; Row puts the row back. A link in a sentence, and a person or a
11
+ Folder alone on its line (which stay chips), offer Open only.
10
12
 
11
13
  <Canvas of={ReferenceMenuStories.InAnEditor} />
12
14
 
13
15
  ## When
14
16
 
15
- - **An editor of a document whose chips can ask for a card**: pair it with
16
- **ReferenceNode**, which draws the chip, and **ReferenceCards**, which places
17
- the card. With **LinkChips**, a pasted URL that becomes its chip opens the
18
- menu too.
17
+ - **An editor of a document**: pair it with **ReferenceNode**, which draws the
18
+ link, and **LinkPlaces**, which tells it where it sits. With **LinkChips**, a
19
+ pasted URL that becomes its chip opens the menu too. **DocumentEditor** has
20
+ all of them.
19
21
 
20
22
  ## When not
21
23
 
22
- - A document that is only read → **RichText**: a click on a chip follows it.
23
- - An editor whose chips take no card → leave it out, and a click on a chip
24
- follows it as when reading.
24
+ - A document that is only read → **RichText**: a click on a link follows it.
25
+ - A message's box, where every link is a chip and its card goes under the
26
+ message → **CardUnder**; leave this out, and a click on a chip follows it.
25
27
 
26
28
  ## How
27
29
 
28
30
  ```tsx
29
31
  import { EditorContent, useEditor } from '@tiptap/react'
30
- import { ReferenceCards, ReferenceMenu, ReferenceMenuView, ReferenceNode, isReferenceMenuOpen } from '@estiva-app/ui/editor'
32
+ import { LinkPlaces, ReferenceMenu, ReferenceMenuView, ReferenceNode, isReferenceMenuOpen } from '@estiva-app/ui/editor'
31
33
 
32
34
  const editor = useEditor({
33
- extensions: [/* … */ ReferenceNode.configure({ view: Chip }), ReferenceCards, ReferenceMenu],
35
+ extensions: [/* … */ ReferenceNode.configure({ view: Chip }), LinkPlaces, ReferenceMenu],
34
36
  editorProps: {
35
37
  handleKeyDown: (view, event) => {
36
38
  // While the menu is open, Escape is its own: it closes the menu.
@@ -44,29 +46,35 @@ const editor = useEditor({
44
46
  <ReferenceMenuView editor={editor} />
45
47
  ```
46
48
 
47
- - **A click on a chip while editing** opens the menu under it, instead of
48
- following the chip. Not editing, the click follows it.
49
- - **A chip just put in** — pasted, picked with `[`, or a pasted URL becoming its
50
- chip — opens the menu by itself. It takes no focus: typing on closes it, and
51
- the chip keeps no card.
52
- - **Open** does what a click on the chip does when reading: the app's chip gets
53
- the click. A chip with nothing to click opens its URL in a new tab.
54
- - Open is offered only when there is something to open: the chip's own link
55
- or button, or its URL. A chip whose URL names nothing yet offers Open only;
56
- one with neither has no menu, and a click goes on to it.
49
+ - **A click on a link while editing** — its chip, row or card — opens the menu
50
+ under it, instead of following it. Not editing, the click follows it. A
51
+ card's own controls (its status, its owner) take their click while editing
52
+ too.
53
+ - **A link just put in alone on its line** — pasted, picked with `[`, or a
54
+ pasted URL becoming its chip — opens the menu by itself. It takes no focus:
55
+ typing on closes it, and nothing is written. In a sentence it does not open:
56
+ Open would be all it offers.
57
+ - **What it writes:** Card writes `embed` `detailed`; Row removes `embed`.
58
+ Nothing writes `compact`; an older writer's is kept until Row or Card is
59
+ chosen, and draws, and reads in the menu, as Row.
60
+ - **Open** does what a click on the link does when reading: the app's link gets
61
+ the click. A link with nothing to click opens its URL in a new tab.
62
+ - Open is offered only when there is something to open: the link's own
63
+ control, or its URL. A link in a sentence with neither has no menu, and a
64
+ click goes on to it.
57
65
  - The menu closes when the editor loses focus, so a card is never chosen after
58
66
  the editor has saved on leaving.
59
- - Choosing a card is an undo step; the menu closes.
67
+ - Choosing Row or Card is an undo step; the menu closes.
60
68
 
61
69
  ## What it owns
62
70
 
63
- Nothing. Its box is the Popover; it holds which chip the menu is open on, and its keys.
71
+ Nothing. Its box is the Popover; it holds which link the menu is open on, and its keys.
64
72
 
65
73
  ## Keys
66
74
 
67
75
  | Key | Does |
68
76
  | --- | --- |
69
- | Enter, on a selected chip | Opens the menu, its first row highlighted |
77
+ | Enter, on a selected link | Opens the menu, its first row highlighted |
70
78
  | ↓ / ↑ | Moves through the rows; nothing is highlighted until then |
71
79
  | Enter | Chooses the highlighted row; with none, the editor's own Enter |
72
80
  | Escape | Closes the menu |