@estiva-app/ui 0.82.1 → 0.83.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.
@@ -1 +1 @@
1
- {"version":3,"file":"linked.examples.d.ts","sourceRoot":"","sources":["../src/linked.examples.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,MAAM,EAAgB,SAAS,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAI7E,eAAO,MAAM,cAAc,EAAE,YAAY,EAKxC,CAAA;AAED,eAAO,MAAM,MAAM,EAAE,YAAY,EAIhC,CAAA;AAMD,8FAA8F;AAC9F,eAAO,MAAM,IAAI,EAAE,MAYlB,CAAA;AAED,wDAAwD;AACxD,eAAO,MAAM,cAAc,EAAE,MAAuG,CAAA;AAEpI,oFAAoF;AACpF,eAAO,MAAM,WAAW,EAAE,MAA0F,CAAA;AAEpH,+DAA+D;AAC/D,eAAO,MAAM,eAAe,EAAE,MAAiI,CAAA;AAE/J,0EAA0E;AAC1E,eAAO,MAAM,KAAK,EAAE,MAgBnB,CAAA;AAED,yFAAyF;AACzF,eAAO,MAAM,KAAK,EAAE,MAUnB,CAAA;AAED,8DAA8D;AAC9D,eAAO,MAAM,IAAI,EAAE,MASlB,CAAA;AAED,kDAAkD;AAClD,eAAO,MAAM,IAAI,EAAE,MAQlB,CAAA;AAED,eAAO,MAAM,KAAK,GAAI,QAAQ,MAAM,KAAG,SAAyC,CAAA;AAChF,eAAO,MAAM,OAAO,EAAE,SAA+C,CAAA;AACrE,eAAO,MAAM,WAAW,EAAE,SAAiH,CAAA"}
1
+ {"version":3,"file":"linked.examples.d.ts","sourceRoot":"","sources":["../src/linked.examples.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,MAAM,EAAgB,SAAS,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAI7E,eAAO,MAAM,cAAc,EAAE,YAAY,EAKxC,CAAA;AAED,eAAO,MAAM,MAAM,EAAE,YAAY,EAIhC,CAAA;AAMD,8FAA8F;AAC9F,eAAO,MAAM,IAAI,EAAE,MAYlB,CAAA;AAED,wDAAwD;AACxD,eAAO,MAAM,cAAc,EAAE,MAAuG,CAAA;AAEpI,oFAAoF;AACpF,eAAO,MAAM,WAAW,EAAE,MAA0F,CAAA;AAEpH,+DAA+D;AAC/D,eAAO,MAAM,eAAe,EAAE,MAAiI,CAAA;AAE/J,0EAA0E;AAC1E,eAAO,MAAM,KAAK,EAAE,MAiBnB,CAAA;AAED,yFAAyF;AACzF,eAAO,MAAM,KAAK,EAAE,MAUnB,CAAA;AAED,8DAA8D;AAC9D,eAAO,MAAM,IAAI,EAAE,MASlB,CAAA;AAED,kDAAkD;AAClD,eAAO,MAAM,IAAI,EAAE,MAQlB,CAAA;AAED,eAAO,MAAM,KAAK,GAAI,QAAQ,MAAM,KAAG,SAAyC,CAAA;AAChF,eAAO,MAAM,OAAO,EAAE,SAA+C,CAAA;AACrE,eAAO,MAAM,WAAW,EAAE,SAAiH,CAAA"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@estiva-app/ui",
3
- "version": "0.82.1",
3
+ "version": "0.83.0",
4
4
  "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
5
5
  "type": "module",
6
6
  "license": "MIT",
package/registry.json CHANGED
@@ -4,9 +4,9 @@
4
4
  "kind": "package",
5
5
  "repo": "estiva-ui",
6
6
  "package": "@estiva-app/ui",
7
- "packageVersion": "0.82.1",
8
- "exports": 206,
9
- "typeExports": 206,
7
+ "packageVersion": "0.83.0",
8
+ "exports": 209,
9
+ "typeExports": 207,
10
10
  "files": null
11
11
  },
12
12
  "storybook": {
@@ -2860,7 +2860,7 @@
2860
2860
  "name": "referenceView",
2861
2861
  "takes": "ComponentType<ReferenceViewProps>",
2862
2862
  "required": false,
2863
- "note": "Draws a chip: the app's own, which resolves what it names."
2863
+ "note": "Draws a link: the app's own, which resolves what it names — its chip, its row or its card in the row's place, as `place` says (§13.3)."
2864
2864
  },
2865
2865
  {
2866
2866
  "name": "attachmentView",
@@ -2868,12 +2868,6 @@
2868
2868
  "required": false,
2869
2869
  "note": "Draws a placed file: the app's own card."
2870
2870
  },
2871
- {
2872
- "name": "cards",
2873
- "takes": "a handler",
2874
- "required": false,
2875
- "note": "Drawn after the text: the cards chips ask for, as the app draws them."
2876
- },
2877
2871
  {
2878
2872
  "name": "wrap",
2879
2873
  "takes": "a handler",
@@ -4805,6 +4799,44 @@
4805
4799
  "app": null,
4806
4800
  "looks": []
4807
4801
  },
4802
+ {
4803
+ "name": "linkPlaceAt",
4804
+ "repo": "estiva-ui",
4805
+ "kind": "helper",
4806
+ "importPath": "@estiva-app/ui/editor",
4807
+ "sourceFile": "src/LinkPlaces.ts",
4808
+ "purpose": "How the reference node at `pos` draws. Anything that is not a reference with a `uri` draws as a chip.",
4809
+ "purposeFrom": "comment",
4810
+ "props": [],
4811
+ "variants": [],
4812
+ "ownsBehaviours": [],
4813
+ "status": "stable",
4814
+ "migrationStage": null,
4815
+ "docsId": "primitives-linkplaces--docs",
4816
+ "storyId": "primitives-linkplaces--in-an-editor",
4817
+ "docPage": null,
4818
+ "app": null,
4819
+ "looks": []
4820
+ },
4821
+ {
4822
+ "name": "LinkPlaces",
4823
+ "repo": "estiva-ui",
4824
+ "kind": "component",
4825
+ "importPath": "@estiva-app/ui/editor",
4826
+ "sourceFile": "src/LinkPlaces.ts",
4827
+ "purpose": "Where a link in a document sits decides how it draws: its chip in a sentence, its row alone on its line, and its card in the row's place when its writer chose one (`embed` `detailed`).",
4828
+ "purposeFrom": "page",
4829
+ "props": [],
4830
+ "variants": [],
4831
+ "ownsBehaviours": [],
4832
+ "status": "stable",
4833
+ "migrationStage": null,
4834
+ "docsId": "primitives-linkplaces--docs",
4835
+ "storyId": "primitives-linkplaces--in-an-editor",
4836
+ "docPage": "src/LinkPlaces.mdx",
4837
+ "app": null,
4838
+ "looks": []
4839
+ },
4808
4840
  {
4809
4841
  "name": "LinkPreview",
4810
4842
  "repo": "estiva-ui",
@@ -7257,7 +7289,7 @@
7257
7289
  "kind": "component",
7258
7290
  "importPath": "@estiva-app/ui/editor",
7259
7291
  "sourceFile": "src/ReferenceMenu.tsx",
7260
- "purpose": "What a chip in a document offers whoever is writing it: Open, and its Card — none, compact or detailed.",
7292
+ "purpose": "What a link in a document offers whoever is writing it: Open, and — when it is alone on its line — Show as Row or Card.",
7261
7293
  "purposeFrom": "page",
7262
7294
  "props": [],
7263
7295
  "variants": [],
@@ -8399,6 +8431,25 @@
8399
8431
  "app": null,
8400
8432
  "looks": []
8401
8433
  },
8434
+ {
8435
+ "name": "staysChip",
8436
+ "repo": "estiva-ui",
8437
+ "kind": "helper",
8438
+ "importPath": "@estiva-app/ui/editor",
8439
+ "sourceFile": "src/LinkPlaces.ts",
8440
+ "purpose": "Whether what `uri` names stays a chip alone on its line: a person (`npub`, `nprofile`) or a Folder (an `naddr` of kind 39000).",
8441
+ "purposeFrom": "comment",
8442
+ "props": [],
8443
+ "variants": [],
8444
+ "ownsBehaviours": [],
8445
+ "status": "stable",
8446
+ "migrationStage": null,
8447
+ "docsId": "primitives-linkplaces--docs",
8448
+ "storyId": "primitives-linkplaces--in-an-editor",
8449
+ "docPage": null,
8450
+ "app": null,
8451
+ "looks": []
8452
+ },
8402
8453
  {
8403
8454
  "name": "SuggestionMenu",
8404
8455
  "repo": "estiva-ui",
@@ -7,6 +7,7 @@ import type { EditorView, NodeView } from '@tiptap/pm/view'
7
7
  import { NodeViewWrapper, ReactNodeViewRenderer, ReactRenderer, type ReactNodeViewProps } from '@tiptap/react'
8
8
  import { Checkbox, type CheckboxProps } from './Checkbox'
9
9
  import { calloutLook } from './RichText'
10
+ import { placeOf, type LinkPlace } from './LinkPlaces'
10
11
  import { referenceMenuClick } from './ReferenceMenu'
11
12
 
12
13
  /*
@@ -372,6 +373,14 @@ const webUrl = (raw: string | null): string | null => (raw && /^https?:\/\/\S+$/
372
373
  export interface ReferenceViewProps {
373
374
  uri: string
374
375
  href?: string
376
+ /**
377
+ * Where it sits, so how it draws: `chip` in a sentence, `row` alone on its
378
+ * line, `card` in the row's place (`LinkPlaces`, §13.3). Always `chip` in an
379
+ * editor without `LinkPlaces`.
380
+ */
381
+ place?: LinkPlace
382
+ /** Being edited: a click opens its menu rather than it, so a row or card shows no hover preview. */
383
+ editing?: boolean
375
384
  }
376
385
 
377
386
  export interface ReferenceNodeOptions {
@@ -390,11 +399,13 @@ export interface ReferenceNodeOptions {
390
399
  * is also how deleting one works. `marks` carries the run's other marks, so a
391
400
  * bold reference comes back bold.
392
401
  *
393
- * `embed` is the card its writer chose to draw after its block — `compact`,
394
- * `detailed`, or null for none (SPEC §13.3, "A reference's card") — and `extra`
395
- * every key of the mark this version does not know. Both are declared so that
396
- * ProseMirror keeps them: an undeclared attribute is dropped when the node is
397
- * made, and the card with it. `ReferenceCards` draws the cards.
402
+ * `embed` is the card its writer chose — `detailed`, drawn in the row's place
403
+ * when the reference is alone on its line, or null for its row (SPEC §13.3, "A
404
+ * reference's card"; older writers wrote `compact`, which draws the row) — and
405
+ * `extra` every key of the mark this version does not know. Both are declared
406
+ * so that ProseMirror keeps them: an undeclared attribute is dropped when the
407
+ * node is made, and the card with it. With `LinkPlaces`, the view is told where
408
+ * the reference sits (`place`) and draws its chip, row or card.
398
409
  *
399
410
  * `href` makes it a **URL chip**: an app URL that reads as the chip of what it
400
411
  * names, and is that URL on the wire (§13.3). `uri` is what it names, filled in
@@ -440,25 +451,41 @@ export const ReferenceNode = Node.create<ReferenceNodeOptions>({
440
451
  addNodeView() {
441
452
  const View = this.options.view
442
453
  if (!View) return null
443
- return ReactNodeViewRenderer(({ node, editor, getPos }: ReactNodeViewProps) => {
454
+ return ReactNodeViewRenderer(({ node, editor, getPos, decorations }: ReactNodeViewProps) => {
444
455
  const uri = String(node.attrs.uri ?? '')
445
456
  const href = typeof node.attrs.href === 'string' && node.attrs.href ? node.attrs.href : undefined
457
+ const place = placeOf(decorations)
446
458
  return (
447
459
  <NodeViewWrapper
448
460
  as="span"
449
- className="inline"
461
+ // A row or a card is the whole line.
462
+ className={place === 'chip' ? 'inline' : 'block w-full'}
450
463
  // While editing, a click opens the chip's menu (`ReferenceMenu`) rather than following the chip.
451
464
  onClickCapture={(event: MouseEvent) => {
465
+ // A click in something the view portals out — a picker's list, a hover card — reaches here through React's
466
+ // tree, not the page's: it is that thing's, not a click on the link.
452
467
  const pos = getPos()
453
- if (typeof pos !== 'number' || !referenceMenuClick(editor, pos)) return
468
+ if (typeof pos !== 'number') return
469
+ // (`Node` here is Tiptap's; a click's target is an Element.)
470
+ const own = editor.view.nodeDOM(pos)
471
+ if (!(event.target instanceof Element) || !own || !own.contains(event.target)) return
472
+ // A card's own controls — its status, its owner — change it from the card, while editing too.
473
+ if (place === 'card' && event.target.closest('button, input, select, [role="combobox"]')) return
474
+ if (!referenceMenuClick(editor, pos)) return
454
475
  event.preventDefault()
455
476
  event.stopPropagation()
456
477
  }}
457
478
  >
458
479
  {/* A URL chip not resolved yet reads as the URL it was written as. */}
459
- {uri ? <View uri={uri} {...(href ? { href } : {})} /> : <span>{href}</span>}
480
+ {uri ? <View uri={uri} {...(href ? { href } : {})} place={place} editing={editor.isEditable} /> : <span>{href}</span>}
460
481
  </NodeViewWrapper>
461
482
  )
483
+ }, {
484
+ // Words typed beside a link leave its node as it was, and Tiptap then skips the redraw; its place has changed (code review).
485
+ update: ({ oldNode, newNode, oldDecorations, newDecorations, updateProps }) => {
486
+ if (oldNode !== newNode || placeOf(oldDecorations) !== placeOf(newDecorations)) updateProps()
487
+ return true
488
+ },
462
489
  })
463
490
  },
464
491
  })
@@ -17,6 +17,9 @@ One document's text as one surface that is always an editor, the same in every a
17
17
  - `onCommentOnSelection` to offer Comment on what is selected, and draw where comments are. Without it, neither.
18
18
  - `blockRows` for the app's rows in a block's menu: Copy link, Comment on the block.
19
19
  - `readOnly` for reading: the same drawing, nothing typed or saved. Chips open, and Comment on a selection stays where it is on.
20
+ - `referenceView` for links: the app's chip, row or card, by `place`.
21
+
22
+ <Canvas of={DocumentEditorStories.Links} />
20
23
 
21
24
  <Canvas of={DocumentEditorStories.WithFiles} />
22
25
 
@@ -53,7 +56,7 @@ const codec: DocumentCodec = {
53
56
  references={{ sections: sectionsFor, ariaLabel: 'Items', sectionLabel: 'Items' }}
54
57
  mentions={{ people: () => people, uriOf: (person) => `nostr:${encodeNpub(person.pubkey)}` }}
55
58
  upload={uploadOne}
56
- referenceView={chipView}
59
+ referenceView={linkView}
57
60
  attachmentView={fileView}
58
61
  onCommit={async (value, contentFormat, editedFrom) => {
59
62
  const adds = mentionAddsFor(me, Date.now(), {
@@ -73,7 +76,8 @@ const codec: DocumentCodec = {
73
76
  - **`label` is required**: the editor's accessible name.
74
77
  - **Give the editor a `key` per document.** The editor and which of `[`, `@`, File, comments and markdown it has are made once, as it opens; the lists, the upload and the people are read as they are each time.
75
78
  - **`hold` is the app's held-typing store.** `register` must not forget what is held when it is called again for the same key during an ending; the editor registers once per `holdKey`.
76
- - **The cards a chip asks for** are drawn by the app's `cards`, after the text, until the kit has its own.
79
+ - **A link draws where it sits** (**LinkPlaces**): `referenceView` is handed `place` — `chip` in a sentence, `row` alone on its line, `card` in the row's place — and draws the kit's **LinkChip**, **LinkRow** or **LinkCard** for what it names. While `editing`, give the chip and row no hover preview: a click opens the link's menu. A person or a Folder alone on its line is a `chip`.
80
+ - **A link's menu** (**ReferenceMenu**) offers Open, and alone on its line Show as Row or Card; it opens by itself after a paste or a `[` pick on a line of its own.
77
81
 
78
82
  ## What it owns
79
83
 
@@ -90,6 +94,7 @@ It does these by itself. Write none of them around it.
90
94
  | A URL pasted over plain words links them; typing after linked words is not linked; a link keeps the keys this version does not know | a paste handler, a link schema |
91
95
  | A bare address drawn as a link, opened by a click, and saved as the text it is | a link decoration |
92
96
  | Each block's id through editing, so what is anchored to it stays on it | an id plugin |
97
+ | Where each link sits — chip, row, or card in the row's place — kept current as you type, and its menu: Open, Show as Row or Card | a line rule, a card slot, a link menu |
93
98
  | A pasted picture uploaded and placed; the file dialog's blur is not leaving | an upload state |
94
99
  | Read only: no caret, no `/`, `[` or `@`, no format buttons; still focusable, so a selection's Comment shows | a reading view |
95
100
 
@@ -1,9 +1,9 @@
1
1
  import type { Meta, StoryObj } from '@storybook/react-vite'
2
- import { useEffect, useRef, useState } from 'react'
2
+ import { useEffect, useRef, useState, useSyncExternalStore } from 'react'
3
3
  import type { Editor } from '@tiptap/react'
4
4
  import type { JSONContent } from '@tiptap/react'
5
5
  import { IconSquareRounded } from '@tabler/icons-react'
6
- import { descriptionTextToBlockDocument, documentForEditing, encodeNpub, publishableFromEditor, toEditorDocument, type ContentFormat, type EditorDocument } from '@estiva-app/protocol'
6
+ import { descriptionTextToBlockDocument, documentForEditing, encodeNaddr, encodeNpub, publishableFromEditor, toEditorDocument, type ContentFormat, type EditorDocument } from '@estiva-app/protocol'
7
7
  import { newlyNamedPeople } from '@estiva-app/conversation'
8
8
  import { AttachmentCard } from './AttachmentCard'
9
9
  import type { HandleBlock } from './BlockHandle'
@@ -13,6 +13,11 @@ import { setCommentAnchors, type CommentAnchor, type SelectionAnchor } from './C
13
13
  import type { CaptionedItem, MentionPerson, ReferenceSection } from './ComposerTriggers'
14
14
  import { DocumentEditor, type DocumentCodec, type DocumentEditorProps, type HeldTyping } from './DocumentEditor'
15
15
  import { InlineChip } from './InlineChip'
16
+ import { LinkCard } from './LinkCard'
17
+ import { LinkChip } from './LinkChip'
18
+ import { LinkRow } from './LinkRow'
19
+ import type { Linked } from './linked'
20
+ import { GROUP, ITEM, ITEM_NO_SUMMARY, ready } from './linked.examples'
16
21
  import { MenuItem } from './Menu'
17
22
 
18
23
  /**
@@ -45,23 +50,73 @@ const npubOf = (person: MentionPerson) => (person.pubkey ? `nostr:${encodeNpub(p
45
50
  const nameOfKey = (key: string) => PEOPLE.find((person) => person.pubkey === key)?.name ?? 'Someone'
46
51
 
47
52
  const APP_LINK = 'https://app.example/item/one'
48
- const ITEMS: CaptionedItem[] = ['one', 'two', 'three'].map((n) => ({ id: `item-${n}`, label: `Item ${n}`, snippet: '', uri: `nostr:naddr1item${n}` }))
53
+ const APP_GROUP_LINK = 'https://app.example/group/one'
54
+ const naddr = (kind: number, identifier: string) => `nostr:${encodeNaddr({ kind, pubkey: 'a'.repeat(64), identifier, relays: [] })}`
55
+ /** What the app resolves each address to: the link kit's placeholder items and a group with a key. */
56
+ const LINKED: { uri: string; linked: Linked }[] = [
57
+ { uri: naddr(30851, 'item-one'), linked: { ...ITEM, title: 'Item one' } },
58
+ { uri: naddr(30851, 'item-two'), linked: ITEM_NO_SUMMARY },
59
+ { uri: naddr(30850, 'group-one'), linked: { ...GROUP, key: 'ABC' } },
60
+ ]
61
+ /** A place that holds items: alone on its line it stays a chip. */
62
+ const PLACE_URI = naddr(39000, 'place-one')
63
+ const ITEMS: CaptionedItem[] = LINKED.map(({ uri, linked }) => ({ id: linked.id, label: linked.title, snippet: '', uri }))
49
64
  const sections = (query: string): ReferenceSection[] => [{ label: 'Items', items: ITEMS.filter((item) => item.label.toLowerCase().includes(query.toLowerCase())) }]
50
- const linkChips = { referenceOf: (url: string) => (url === APP_LINK ? ITEMS[0].uri : undefined), ask: null, limit: 24 }
65
+ const APP_LINKS = new Map([
66
+ [APP_LINK, LINKED[0].uri],
67
+ [APP_GROUP_LINK, LINKED[2].uri],
68
+ ])
69
+ const linkChips = { referenceOf: (url: string) => APP_LINKS.get(url), ask: null, limit: 24 }
51
70
 
52
71
  const SQUARE = <IconSquareRounded size={14} stroke={1.5} />
53
72
  const ROW_ICON = <IconSquareRounded size={16} stroke={1.5} className="text-text-secondary" />
54
73
 
55
- /** A chip as the app draws it: a person by name, an item by its label; it opens where it leads. */
56
- function Chip({ uri, href }: ReferenceViewProps) {
74
+ /** The app's side of a card's status and owner: a change from the card is kept here, and every drawing of it reads it back. */
75
+ const picked = new Map<string, { status?: string; owner?: string }>()
76
+ const pickListeners = new Set<() => void>()
77
+ let pickVersion = 0
78
+ function pick(uri: string, change: { status?: string; owner?: string }) {
79
+ picked.set(uri, { ...picked.get(uri), ...change })
80
+ pickVersion++
81
+ for (const listener of pickListeners) listener()
82
+ }
83
+ const subscribePicks = (listener: () => void) => {
84
+ pickListeners.add(listener)
85
+ return () => void pickListeners.delete(listener)
86
+ }
87
+
88
+ /** What `uri` names, with its status and owner as last picked; undefined for what the app does not know. */
89
+ function useLinked(uri: string): Linked | undefined {
90
+ useSyncExternalStore(subscribePicks, () => pickVersion)
91
+ const found = LINKED.find((one) => one.uri === uri)?.linked
92
+ if (!found) return undefined
93
+ const now = picked.get(uri)
94
+ return {
95
+ ...found,
96
+ ...(found.status && { status: { ...found.status, value: now?.status ?? found.status.value, onChange: (status: string) => pick(uri, { status }) } }),
97
+ ...(found.owner && { owner: { ...found.owner, value: now?.owner ?? found.owner.value, onChange: (owner: string) => pick(uri, { owner }) } }),
98
+ }
99
+ }
100
+
101
+ /**
102
+ * A link as the app draws it, where it sits: a person by name; an item as the
103
+ * link kit's chip, row or card. While editing, a click is the menu's, so a
104
+ * chip or row shows no hover card.
105
+ */
106
+ function Chip({ uri, href, place = 'chip', editing = false }: ReferenceViewProps) {
107
+ const linked = useLinked(uri)
57
108
  const person = PEOPLE.find((one) => npubOf(one) === uri)
58
- if (person) return <InlineChip tone="person">{`@${person.name}`}</InlineChip>
59
- const item = ITEMS.find((one) => one.uri === uri)
60
- return (
61
- <InlineChip icon={SQUARE} href={href ?? 'https://example.com/item'} target="_blank" rel="noreferrer">
62
- {item?.label ?? 'Item'}
63
- </InlineChip>
64
- )
109
+ if (person) return <InlineChip tone="person" href={`#${person.id}`}>{`@${person.name}`}</InlineChip>
110
+ if (!linked) {
111
+ return (
112
+ <InlineChip icon={SQUARE} href={href ?? 'https://example.com/item'} target="_blank" rel="noreferrer">
113
+ {uri === PLACE_URI ? 'Place one' : 'Item'}
114
+ </InlineChip>
115
+ )
116
+ }
117
+ if (place === 'card') return <LinkCard link={ready(linked)} />
118
+ if (place === 'row') return <LinkRow link={ready(linked)} preview={!editing} />
119
+ return <LinkChip link={ready(linked)} preview={!editing} />
65
120
  }
66
121
 
67
122
  function PlacedFile({ attrs }: AttachmentViewProps) {
@@ -99,6 +154,24 @@ const START = JSON.stringify({
99
154
  ],
100
155
  })
101
156
 
157
+ const reference = (uri: string, embed?: string) => ({ type: 'text', text: uri, marks: [{ type: 'reference', attrs: { uri, ...(embed ? { embed } : {}) } }] })
158
+ const lone = (id: string, uri: string, embed?: string) => ({ type: 'paragraph', id, content: [reference(uri, embed)] })
159
+
160
+ /** Links where they sit: in a sentence, alone on a line, alone with its card chosen, and a person and a place alone. */
161
+ const LINKS_START = JSON.stringify({
162
+ type: 'doc',
163
+ content: [
164
+ { type: 'paragraph', id: 'l1', content: [{ type: 'text', text: 'A sentence that names ' }, reference(LINKED[0].uri), { type: 'text', text: ' in passing.' }] },
165
+ lone('l2', LINKED[2].uri),
166
+ lone('l3', LINKED[0].uri, 'detailed'),
167
+ lone('l4', LINKED[1].uri),
168
+ lone('l5', `nostr:${encodeNpub(PEOPLE[0].pubkey!)}`),
169
+ lone('l6', PLACE_URI),
170
+ { type: 'paragraph', id: 'l7', content: [{ type: 'text', text: `On an empty line, paste ${APP_GROUP_LINK} or type [.` }] },
171
+ { type: 'paragraph', id: 'l8', content: [] },
172
+ ],
173
+ })
174
+
102
175
  /** An app's held-typing store: what each open editor holds is read when the sign-in ends. */
103
176
  function heldStore() {
104
177
  const held = new Map<string, string>()
@@ -156,11 +229,13 @@ type Bench = Pick<DocumentEditorProps, 'readOnly' | 'upload' | 'linkChips' | 're
156
229
  comments?: boolean
157
230
  /** The block handle's rows: Copy link, and Comment on the block. */
158
231
  rows?: boolean
232
+ /** The saved document it opens on. */
233
+ start?: string
159
234
  }
160
235
 
161
236
  /** The editor and the app around it. */
162
- function Workbench({ lists = true, comments = false, rows = false, readOnly = false, ...rest }: Bench) {
163
- const [value, setValue] = useState(START)
237
+ function Workbench({ lists = true, comments = false, rows = false, readOnly = false, start = START, ...rest }: Bench) {
238
+ const [value, setValue] = useState(start)
164
239
  const [changedBy, setChangedBy] = useState<{ name: string } | null>(null)
165
240
  const [opened, setOpened] = useState(0)
166
241
  const [signedIn, setSignedIn] = useState(true)
@@ -289,6 +364,17 @@ export const WithFiles: Story = {
289
364
  render: () => <Workbench rows upload={upload} linkChips={linkChips} readMarkdown={readMarkdown} />,
290
365
  }
291
366
 
367
+ /**
368
+ * Links where they sit: a chip in a sentence, a row alone on its line, and the
369
+ * card in the row's place. Click a link for its menu: Open, and alone on its
370
+ * line Show as Row or Card. A person or a place alone stays a chip, and its
371
+ * menu has Open only. On an empty line, a pasted link or a `[` pick opens the
372
+ * menu by itself. A card's status and owner change from the card.
373
+ */
374
+ export const Links: Story = {
375
+ render: () => <Workbench start={LINKS_START} linkChips={linkChips} />,
376
+ }
377
+
292
378
  /** Nothing of the app's but its chips: no `[`, no `@`, no rows, no comments. */
293
379
  export const Plain: Story = {
294
380
  render: () => <Workbench lists={false} linkChips={linkChips} />,
@@ -501,6 +501,55 @@ describe('blocks', () => {
501
501
  })
502
502
  })
503
503
 
504
+ describe('a link, by where it sits', () => {
505
+ const run = (uri: string, embed?: string) => ({ type: 'text', text: uri, marks: [{ type: 'reference', attrs: { uri, ...(embed ? { embed } : {}) } }] })
506
+ /** The app's drawing of a link: says where it sits. */
507
+ const Placed = ({ uri, place }: { uri: string; place?: string }) => (
508
+ <a href={`/o/${uri}`} data-place={place ?? 'none'} onClick={(event) => event.preventDefault()}>
509
+ Item
510
+ </a>
511
+ )
512
+ const places = () => [...document.querySelectorAll('[data-place]')].map((el) => el.getAttribute('data-place'))
513
+
514
+ it('draws as its row alone on its line, its chip in a sentence, and its card in the row\'s place once chosen', async () => {
515
+ const value = doc(
516
+ { type: 'paragraph', id: 'a1', content: [run(ITEM_URI)] },
517
+ { type: 'paragraph', id: 'a2', content: [{ type: 'text', text: 'See ' }, run(ITEM_URI)] },
518
+ { type: 'paragraph', id: 'a3', content: [run(ITEM_URI, 'detailed')] },
519
+ )
520
+ render(<Doc value={value} referenceView={Placed} />)
521
+ await screen.findAllByRole('link', { name: 'Item' })
522
+ expect(places()).toEqual(['row', 'chip', 'card'])
523
+ })
524
+
525
+ it('turns from its row into its chip as words are typed before it, and back when they are taken away', async () => {
526
+ render(<Doc value={doc({ type: 'paragraph', id: 'a1', content: [run(ITEM_URI)] })} referenceView={Placed} />)
527
+ await screen.findByRole('link', { name: 'Item' })
528
+ expect(places()).toEqual(['row'])
529
+ await act(async () => editorOf().chain().focus().insertContentAt(1, 'See ').run())
530
+ expect(places()).toEqual(['chip'])
531
+ await act(async () => editorOf().chain().focus().deleteRange({ from: 1, to: 5 }).run())
532
+ expect(places()).toEqual(['row'])
533
+ })
534
+
535
+ it('Show as Card on a lone link saves its card, and Show as Row saves it without one', async () => {
536
+ const onCommit = vi.fn<DocumentEditorProps['onCommit']>(async () => true)
537
+ render(<Doc value={doc({ type: 'paragraph', id: 'a1', content: [run(ITEM_URI)] })} referenceView={Placed} onCommit={onCommit} />)
538
+ const choose = async (label: 'Row' | 'Card') => {
539
+ await act(async () => editorOf().view.focus())
540
+ fireEvent.click(await screen.findByRole('link', { name: 'Item' }))
541
+ fireEvent.mouseDown(await screen.findByRole('menuitemradio', { name: label }))
542
+ await leave()
543
+ }
544
+ await choose('Card')
545
+ expect(places()).toEqual(['card'])
546
+ expect(saved(onCommit.mock.calls[0][0])[0].runs[0].marks).toEqual([{ type: 'reference', attrs: { uri: ITEM_URI, embed: 'detailed' } }])
547
+ await choose('Row')
548
+ expect(places()).toEqual(['row'])
549
+ expect(saved(onCommit.mock.calls[1][0])[0].runs[0].marks).toEqual([{ type: 'reference', attrs: { uri: ITEM_URI } }])
550
+ })
551
+ })
552
+
504
553
  describe('reading', () => {
505
554
  it('read only, nothing can be typed or saved, and the text is drawn the same', async () => {
506
555
  const onCommit = vi.fn(async () => true)
@@ -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.