@estiva-app/ui 0.91.2 → 0.92.1

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 (106) hide show
  1. package/dist/AppProvider.d.ts +7 -3
  2. package/dist/AppProvider.d.ts.map +1 -1
  3. package/dist/AttachedCard.d.ts +5 -1
  4. package/dist/AttachedCard.d.ts.map +1 -1
  5. package/dist/BlockNodes.d.ts +14 -1
  6. package/dist/BlockNodes.d.ts.map +1 -1
  7. package/dist/Button.d.ts +11 -1
  8. package/dist/Button.d.ts.map +1 -1
  9. package/dist/CommentBox.d.ts +9 -2
  10. package/dist/CommentBox.d.ts.map +1 -1
  11. package/dist/ComposerTriggers.d.ts +11 -2
  12. package/dist/ComposerTriggers.d.ts.map +1 -1
  13. package/dist/DocumentEditor.d.ts.map +1 -1
  14. package/dist/LinkCard.d.ts.map +1 -1
  15. package/dist/LinkChip.d.ts.map +1 -1
  16. package/dist/LinkChips.d.ts +2 -1
  17. package/dist/LinkChips.d.ts.map +1 -1
  18. package/dist/LinkParts.d.ts +6 -1
  19. package/dist/LinkParts.d.ts.map +1 -1
  20. package/dist/LinkPlaces.d.ts +7 -0
  21. package/dist/LinkPlaces.d.ts.map +1 -1
  22. package/dist/LinkRow.d.ts +29 -6
  23. package/dist/LinkRow.d.ts.map +1 -1
  24. package/dist/PartCard.d.ts +9 -2
  25. package/dist/PartCard.d.ts.map +1 -1
  26. package/dist/ReferenceCards.d.ts +9 -39
  27. package/dist/ReferenceCards.d.ts.map +1 -1
  28. package/dist/ReferenceMenu.d.ts.map +1 -1
  29. package/dist/editor.d.ts +1 -1
  30. package/dist/editor.d.ts.map +1 -1
  31. package/dist/editor.js +204 -183
  32. package/dist/editor.js.map +3 -3
  33. package/dist/index.d.ts +2 -2
  34. package/dist/index.d.ts.map +1 -1
  35. package/dist/index.js +211 -97
  36. package/dist/index.js.map +3 -3
  37. package/dist/linked.d.ts +48 -3
  38. package/dist/linked.d.ts.map +1 -1
  39. package/dist/linked.examples.d.ts +6 -0
  40. package/dist/linked.examples.d.ts.map +1 -1
  41. package/dist/linkedFrom.d.ts +7 -3
  42. package/dist/linkedFrom.d.ts.map +1 -1
  43. package/package.json +1 -1
  44. package/registry.json +65 -56
  45. package/src/AppProvider.mdx +7 -5
  46. package/src/AppProvider.test.tsx +15 -1
  47. package/src/AppProvider.tsx +13 -4
  48. package/src/AttachedCard.mdx +2 -1
  49. package/src/AttachedCard.test.tsx +28 -0
  50. package/src/AttachedCard.tsx +12 -2
  51. package/src/BlockNodes.mdx +8 -1
  52. package/src/BlockNodes.tsx +98 -11
  53. package/src/Button.mdx +25 -3
  54. package/src/Button.stories.tsx +15 -1
  55. package/src/Button.test.tsx +33 -0
  56. package/src/Button.tsx +65 -49
  57. package/src/CommentBox.mdx +8 -2
  58. package/src/CommentBox.stories.tsx +28 -1
  59. package/src/CommentBox.test.tsx +64 -1
  60. package/src/CommentBox.tsx +44 -5
  61. package/src/ComposerTriggers.mdx +1 -0
  62. package/src/ComposerTriggers.tsx +34 -15
  63. package/src/DocumentEditor.mdx +1 -1
  64. package/src/DocumentEditor.stories.tsx +2 -2
  65. package/src/DocumentEditor.test.tsx +37 -7
  66. package/src/DocumentEditor.tsx +2 -1
  67. package/src/LinkCard.mdx +9 -5
  68. package/src/LinkCard.stories.tsx +17 -2
  69. package/src/LinkCard.test.tsx +21 -0
  70. package/src/LinkCard.tsx +35 -16
  71. package/src/LinkChip.mdx +6 -1
  72. package/src/LinkChip.stories.tsx +7 -1
  73. package/src/LinkChip.test.tsx +12 -0
  74. package/src/LinkChip.tsx +6 -2
  75. package/src/LinkChips.mdx +4 -3
  76. package/src/LinkChips.stories.tsx +2 -2
  77. package/src/LinkChips.test.tsx +1 -2
  78. package/src/LinkChips.ts +2 -1
  79. package/src/LinkParts.mdx +3 -2
  80. package/src/LinkParts.stories.tsx +8 -0
  81. package/src/LinkParts.tsx +40 -6
  82. package/src/LinkPlaces.mdx +3 -0
  83. package/src/LinkPlaces.ts +19 -0
  84. package/src/LinkRow.mdx +8 -2
  85. package/src/LinkRow.stories.tsx +14 -2
  86. package/src/LinkRow.test.tsx +31 -1
  87. package/src/LinkRow.tsx +69 -25
  88. package/src/PartCard.mdx +9 -1
  89. package/src/PartCard.stories.tsx +9 -0
  90. package/src/PartCard.test.tsx +13 -0
  91. package/src/PartCard.tsx +19 -5
  92. package/src/ReferenceCards.test.tsx +4 -35
  93. package/src/ReferenceCards.ts +10 -119
  94. package/src/ReferenceMenu.mdx +6 -4
  95. package/src/ReferenceMenu.test.tsx +67 -5
  96. package/src/ReferenceMenu.tsx +18 -7
  97. package/src/editor.ts +0 -3
  98. package/src/index.ts +4 -1
  99. package/src/linked.examples.ts +6 -0
  100. package/src/linked.test.ts +35 -1
  101. package/src/linked.ts +108 -3
  102. package/src/linkedFrom.test.tsx +42 -2
  103. package/src/linkedFrom.ts +15 -7
  104. package/src/registry/registry.test.ts +25 -6
  105. package/src/ReferenceCards.mdx +0 -86
  106. package/src/ReferenceCards.stories.tsx +0 -66
@@ -1,5 +1,5 @@
1
1
  import { Fragment, useCallback, useEffect, useLayoutEffect, useRef, useState, type ComponentType, type DragEvent, type ReactNode } from 'react'
2
- import { Extension, type AnyExtension, type EditorOptions } from '@tiptap/core'
2
+ import { Extension, nodePasteRule, type AnyExtension, type EditorOptions } from '@tiptap/core'
3
3
  import { Editor, type JSONContent } from '@tiptap/react'
4
4
  import { IconLock, IconPaperclip, IconSquareRounded } from '@tabler/icons-react'
5
5
  import { AttachedCard } from './AttachedCard'
@@ -27,6 +27,8 @@ import { FieldLine } from './Field'
27
27
  import { FilePicker } from './FilePicker'
28
28
  import { Kbd } from './Kbd'
29
29
  import { inTheBox } from './linked'
30
+ import { LinkedIcon } from './LinkParts'
31
+ import { linkedKindOfReference } from './LinkPlaces'
30
32
  import { BoxKit, LINK_MARK_ATTRIBUTES, PasteOverWords } from './links'
31
33
  import { PastedImages } from './PastedImages'
32
34
  import { KeptSelection } from './SelectionToolbar'
@@ -131,7 +133,10 @@ export interface CommentBoxProps {
131
133
  references?: (query: string) => readonly ReferenceSection[]
132
134
  /** Called with a listener while `[` is open; call it when `references` would answer differently (a search landed). */
133
135
  referencesChanged?: (listener: () => void) => () => void
134
- /** A `[` row's and chip's 16px icon from what it points at; absent, a neutral square. */
136
+ /**
137
+ * A `[` row's and chip's 16px icon from what it points at. Absent, the kit's icon for the kind its address names
138
+ * (`LinkedIcon`), and a neutral square for an address that names none.
139
+ */
135
140
  referenceIcon?: (uri: string | null) => ReactNode | undefined
136
141
  /** The app's own `/` Insert rows, after the shared Format section: {@link commentBoxRows} and its own. */
137
142
  insert?: readonly SlashCommand[]
@@ -161,7 +166,11 @@ export interface CommentBoxProps {
161
166
  accept?: string
162
167
  /** The box cannot write here (an archived file, signed out): a line saying why takes its place. */
163
168
  closed?: { reason: ReactNode }
164
- /** How a `nostr:` reference the box holds is drawn — the app's own chip. Absent, as its URI. */
169
+ /**
170
+ * How a link the box holds is drawn — a pasted one, a pasted `nostr:` address, and a `[` pick alike: the app's view
171
+ * of the kit's `LinkChip`, told it is being edited (no preview; a click stays in the draft). Absent, a `nostr:`
172
+ * reference reads as its URI and a `[` pick as its caption.
173
+ */
165
174
  referenceView?: ComponentType<ReferenceViewProps>
166
175
  /** The app's own extra editor extensions: link chips, highlights. */
167
176
  extensions?: readonly AnyExtension[]
@@ -216,6 +225,32 @@ const stillNamed = (removed: ReadonlySet<string>, names: readonly string[]): Rea
216
225
  const SQUARE = <IconSquareRounded size={16} stroke={1.5} className="text-text-secondary" />
217
226
  const SMALL_SQUARE = <IconSquareRounded size={14} stroke={1.5} />
218
227
 
228
+ /** The kit's icon for the kind a `nostr:` address names, at a row's or a chip's size; nothing for one that names none. */
229
+ function kindIconOf(uri: string | null, size: 14 | 16): ReactNode | undefined {
230
+ const kind = uri ? linkedKindOfReference(uri) : undefined
231
+ return kind ? <LinkedIcon kind={kind} size={size} /> : undefined
232
+ }
233
+
234
+ /**
235
+ * A `nostr:` address pasted into the box becomes its link at once, as a pasted app URL does (Katerina, 30 Oct): a file
236
+ * (`naddr`) or a message (`nevent`, `note`), drawn by the app's `referenceView`. A person's (`npub`) stays the text
237
+ * it is; `@` names a person.
238
+ */
239
+ const PastedAddresses = Extension.create({
240
+ name: 'pastedAddresses',
241
+ addPasteRules() {
242
+ const type = this.editor.schema.nodes.reference
243
+ if (!type) return []
244
+ return [
245
+ nodePasteRule({
246
+ find: /nostr:(?:naddr1|nevent1|note1)[023456789acdefghjklmnpqrstuvwxyz]+/g,
247
+ type,
248
+ getAttributes: (match) => ({ uri: match[0] }),
249
+ }),
250
+ ]
251
+ },
252
+ })
253
+
219
254
  /** What the box's editor reads as it runs: the box holding it now, swapped in when a box takes a spare. */
220
255
  interface BoxLive {
221
256
  edit?: CommentBoxEdit
@@ -244,7 +279,9 @@ const sameApp = (a: BoxApp, b: BoxApp) =>
244
279
  a.referenceView === b.referenceView && a.extensions.length === b.extensions.length && a.extensions.every((one, i) => one === b.extensions[i])
245
280
 
246
281
  function boxExtensions(hold: BoxHold, app: BoxApp): AnyExtension[] {
247
- const iconFor = (uri: string | null) => hold.current.referenceIcon?.(uri)
282
+ // The app's icons when it gives them; the kit's for the kind each address names otherwise (Katerina, 30 Oct).
283
+ const own = (uri: string | null, size: 14 | 16) => (hold.current.referenceIcon ? hold.current.referenceIcon(uri) : kindIconOf(uri, size))
284
+ const iconFor = (uri: string | null) => own(uri, 16)
248
285
  return [
249
286
  // A link drawn as one, as in a document: it read as plain words in the box before (Katerina, 29 Oct).
250
287
  BoxKit.configure({ link: { openOnClick: false, HTMLAttributes: LINK_MARK_ATTRIBUTES } }),
@@ -274,7 +311,8 @@ function boxExtensions(hold: BoxHold, app: BoxApp): AnyExtension[] {
274
311
  return { ...parent, suggestion: { ...parent.suggestion, allow: () => !hold.current.edit } }
275
312
  },
276
313
  }).configure({ people: () => hold.current.people }),
277
- CaptionedReference.configure({ icon: SMALL_SQUARE, iconFor }),
314
+ // A `[` pick draws as the app draws every other link in the box (Katerina, 30 Oct: one chip look in every box).
315
+ CaptionedReference.configure({ icon: SMALL_SQUARE, iconFor: (uri) => own(uri, 14), view: app.referenceView }),
278
316
  ReferenceTrigger.configure({
279
317
  items: () => [],
280
318
  sections: (query) => hold.current.references?.(query) ?? [],
@@ -286,6 +324,7 @@ function boxExtensions(hold: BoxHold, app: BoxApp): AnyExtension[] {
286
324
  }),
287
325
  SlashCommands.configure({ sections: hold.sections }),
288
326
  ReferenceNode.configure({ view: app.referenceView }),
327
+ ...(app.referenceView ? [PastedAddresses] : []),
289
328
  PastedImages.configure({ onImages: (files: File[]) => hold.current.attach(files) }),
290
329
  ...app.extensions,
291
330
  ]
@@ -101,6 +101,7 @@ const urgent = editor ? urgentPubkeys(editor) : undefined
101
101
 
102
102
  <Canvas of={ComposerTriggersStories.ReferencesOfSeveralKinds} />
103
103
 
104
+ - **`CaptionedReference`'s `view`** draws a chip with a `uri` as the app draws its other links (a `referenceView`, the kit's **LinkChip**), told it is being edited; a click on it stays in the draft. `CommentBox` passes its `referenceView`, so a `[` pick looks like a pasted link.
104
105
  - **An app's own node name:** `CaptionedReference.extend({ name: 'yourName' })`
105
106
  and `ReferenceTrigger.configure({ nodeName: 'yourName' })`. The chip's HTML
106
107
  attribute follows the name (`data-your-name`).
@@ -1,10 +1,11 @@
1
- import type { ReactNode } from 'react'
1
+ import type { ComponentType, MouseEvent, ReactNode } from 'react'
2
2
  import { Extension, type Editor } from '@tiptap/core'
3
3
  import { PluginKey } from '@tiptap/pm/state'
4
4
  import Mention, { type MentionOptions } from '@tiptap/extension-mention'
5
5
  import Suggestion from '@tiptap/suggestion'
6
6
  import { NodeViewWrapper, ReactNodeViewRenderer, type ReactNodeViewProps } from '@tiptap/react'
7
7
  import { Avatar } from './Avatar'
8
+ import type { ReferenceViewProps } from './BlockNodes'
8
9
  import { EnterHint } from './Menu'
9
10
  import { inlineChipClassName } from './InlineChip'
10
11
  import { WithTooltip } from './Tooltip'
@@ -343,13 +344,26 @@ export interface CaptionedReferenceOptions {
343
344
  * The same answer the list's row gave (Katerina, 7 October).
344
345
  */
345
346
  iconFor?: (uri: string | null) => ReactNode | undefined
347
+ /**
348
+ * Draws the chip as the box's other links are drawn — the app's `referenceView`,
349
+ * the kit's `LinkChip` — told it is being edited, so it shows no preview and a
350
+ * click on it stays in the draft. Absent, or for a chip with no `uri`, the
351
+ * caption with `icon`.
352
+ */
353
+ view?: ComponentType<ReferenceViewProps> | null
354
+ }
355
+
356
+ /** A click on a link inside a chip being written: the draft is not left for it (Katerina, 30 Oct). */
357
+ function stayInDraft(event: MouseEvent) {
358
+ if (event.target instanceof Element && event.target.closest('a[href]')) event.preventDefault()
346
359
  }
347
360
 
348
361
  /**
349
362
  * A reference mid-sentence, drawn as `label: snippet` and written as its `uri`
350
363
  * verbatim (SPEC §13.1). The caption is the snapshot it was picked with — a
351
364
  * caption, never parsed. Inserted by {@link ReferenceTrigger}, a paste or a
352
- * draft; it opens no list of its own.
365
+ * draft; it opens no list of its own. With `view` it draws as the app draws
366
+ * any other link in the box, so a `[` pick and a pasted link look alike.
353
367
  */
354
368
  export const CaptionedReference = Mention.extend<MentionOptions & CaptionedReferenceOptions>({
355
369
  name: 'captionedReference',
@@ -357,7 +371,7 @@ export const CaptionedReference = Mention.extend<MentionOptions & CaptionedRefer
357
371
  inline: true,
358
372
  atom: true,
359
373
  addOptions() {
360
- return { ...this.parent!(), HTMLAttributes: {}, icon: null, iconFor: undefined, suggestion: { char: '\0', items: () => [] } }
374
+ return { ...this.parent!(), HTMLAttributes: {}, icon: null, iconFor: undefined, view: null, suggestion: { char: '\0', items: () => [] } }
361
375
  },
362
376
  addAttributes() {
363
377
  return {
@@ -378,19 +392,24 @@ export const CaptionedReference = Mention.extend<MentionOptions & CaptionedRefer
378
392
  return [{ tag: `span[data-${this.name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}]` }]
379
393
  },
380
394
  addNodeView() {
381
- const { icon, iconFor } = this.options
395
+ const { icon, iconFor, view: View } = this.options
382
396
  return ReactNodeViewRenderer(
383
- ({ node }: ReactNodeViewProps) => (
384
- // The caption is cut at 24ch, so the whole of it is on hover, in the package's tooltip (UIG-14) — as Peek's sent chip has it.
385
- <NodeViewWrapper as="span">
386
- <WithTooltip inline label={captionOf(node.attrs.label, node.attrs.snippet)}>
387
- <span className={inlineChipClassName('neutral', 'max-w-[24ch] cursor-default')}>
388
- <span className="flex items-center justify-center w-4 h-4 shrink-0 text-text-secondary">{iconFor?.(node.attrs.uri ?? null) ?? icon}</span>
389
- <span className="truncate">{captionOf(node.attrs.label, node.attrs.snippet)}</span>
390
- </span>
391
- </WithTooltip>
392
- </NodeViewWrapper>
393
- ),
397
+ ({ node }: ReactNodeViewProps) =>
398
+ View && node.attrs.uri ? (
399
+ <NodeViewWrapper as="span" onClickCapture={stayInDraft}>
400
+ <View uri={String(node.attrs.uri)} place="chip" editing />
401
+ </NodeViewWrapper>
402
+ ) : (
403
+ // The caption is cut at 24ch, so the whole of it is on hover, in the package's tooltip (UIG-14) — as Peek's sent chip has it.
404
+ <NodeViewWrapper as="span">
405
+ <WithTooltip inline label={captionOf(node.attrs.label, node.attrs.snippet)}>
406
+ <span className={inlineChipClassName('neutral', 'max-w-[24ch] cursor-default')}>
407
+ <span className="flex items-center justify-center w-4 h-4 shrink-0 text-text-secondary">{iconFor?.(node.attrs.uri ?? null) ?? icon}</span>
408
+ <span className="truncate">{captionOf(node.attrs.label, node.attrs.snippet)}</span>
409
+ </span>
410
+ </WithTooltip>
411
+ </NodeViewWrapper>
412
+ ),
394
413
  { as: 'span' },
395
414
  )
396
415
  },
@@ -76,7 +76,7 @@ const codec: DocumentCodec = {
76
76
  - **`label` is required**: the editor's accessible name.
77
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.
78
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`.
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`.
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. A link is `editing` only while the caret is on its line: give the chip and row no hover preview then, as a click opens the link's menu; anywhere else on the page they preview on hover. A card keeps its pickers while the text is edited, and its title and count follow a click. A person or a Folder alone on its line is a `chip`.
80
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.
81
81
 
82
82
  ## What it owns
@@ -100,8 +100,8 @@ function useLinked(uri: string): Linked | undefined {
100
100
 
101
101
  /**
102
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.
103
+ * link kit's chip, row or card. On the caret's line a click is the menu's, so
104
+ * a chip or row there shows no hover card; elsewhere on the page it does.
105
105
  */
106
106
  function Chip({ uri, href, place = 'chip', editing = false }: ReferenceViewProps) {
107
107
  const linked = useLinked(uri)
@@ -11,9 +11,11 @@ import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
11
11
  import { cleanup, fireEvent, render, screen, within } from '@testing-library/react'
12
12
  import type { Editor } from '@tiptap/core'
13
13
  import { Fragment, Slice } from '@tiptap/pm/model'
14
+ import { TextSelection } from '@tiptap/pm/state'
14
15
  import type { JSONContent } from '@tiptap/react'
15
16
  import { documentForEditing, encodeNpub, publishableFromEditor, toEditorDocument, type ContentFormat, type EditorDocument } from '@estiva-app/protocol'
16
17
  import { newlyNamedPeople } from '@estiva-app/conversation'
18
+ import type { ReferenceViewProps } from './BlockNodes'
17
19
  import type { MentionPerson, ReferenceSection } from './ComposerTriggers'
18
20
  import { DocumentEditor, type DocumentCodec, type DocumentEditorProps, type HeldTyping } from './DocumentEditor'
19
21
 
@@ -531,13 +533,40 @@ describe('blocks', () => {
531
533
 
532
534
  describe('a link, by where it sits', () => {
533
535
  const run = (uri: string, embed?: string) => ({ type: 'text', text: uri, marks: [{ type: 'reference', attrs: { uri, ...(embed ? { embed } : {}) } }] })
534
- /** The app's drawing of a link: says where it sits. */
535
- const Placed = ({ uri, place }: { uri: string; place?: string }) => (
536
- <a href={`/o/${uri}`} data-place={place ?? 'none'} onClick={(event) => event.preventDefault()}>
537
- Item
538
- </a>
539
- )
536
+ /** The app's drawing of a link: says where it sits, and whether it is being edited; a card has room around its link. */
537
+ const Placed = ({ uri, place, editing }: ReferenceViewProps) => {
538
+ const link = (
539
+ <a href={`/o/${uri}`} data-place={place ?? 'none'} data-editing={String(!!editing)} onClick={(event) => event.preventDefault()}>
540
+ Item
541
+ </a>
542
+ )
543
+ return place === 'card' ? <span data-testid="card">{link} Summary</span> : link
544
+ }
540
545
  const places = () => [...document.querySelectorAll('[data-place]')].map((el) => el.getAttribute('data-place'))
546
+ const editing = () => [...document.querySelectorAll('[data-editing]')].map((el) => el.getAttribute('data-editing'))
547
+
548
+ it('is being edited only while the caret is on its line: elsewhere, and once the editor is left, it can preview', async () => {
549
+ const value = doc(
550
+ { type: 'paragraph', id: 'a1', content: [{ type: 'text', text: 'See ' }, run(ITEM_URI)] },
551
+ { type: 'paragraph', id: 'a2', content: [{ type: 'text', text: 'And ' }, run(ITEM_URI)] },
552
+ )
553
+ render(<Doc value={value} referenceView={Placed} />)
554
+ await screen.findAllByRole('link', { name: 'Item' })
555
+ expect(editing()).toEqual(['false', 'false'])
556
+ // The caret placed at once, focused: Tiptap's own `focus` command focuses a frame later, which could land after `leave`.
557
+ const caretAt = (at: (size: number) => number) =>
558
+ act(async () => {
559
+ const { view, state } = editorOf()
560
+ view.focus()
561
+ view.dispatch(state.tr.setSelection(TextSelection.create(state.doc, at(state.doc.content.size))))
562
+ })
563
+ await caretAt(() => 2)
564
+ expect(editing()).toEqual(['true', 'false'])
565
+ await caretAt((size) => size - 1)
566
+ expect(editing()).toEqual(['false', 'true'])
567
+ await leave()
568
+ expect(editing()).toEqual(['false', 'false'])
569
+ })
541
570
 
542
571
  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 () => {
543
572
  const value = doc(
@@ -565,7 +594,8 @@ describe('a link, by where it sits', () => {
565
594
  render(<Doc value={doc({ type: 'paragraph', id: 'a1', content: [run(ITEM_URI)] })} referenceView={Placed} onCommit={onCommit} />)
566
595
  const choose = async (label: 'Row' | 'Card') => {
567
596
  await act(async () => editorOf().view.focus())
568
- fireEvent.click(await screen.findByRole('link', { name: 'Item' }))
597
+ // A card's own link follows; its empty space opens the menu.
598
+ fireEvent.click(screen.queryByTestId('card') ?? (await screen.findByRole('link', { name: 'Item' })))
569
599
  fireEvent.mouseDown(await screen.findByRole('menuitemradio', { name: label }))
570
600
  await leave()
571
601
  }
@@ -364,7 +364,8 @@ export function DocumentEditor({
364
364
  BlockId,
365
365
  Checklist,
366
366
  Callout,
367
- ReferenceNode.configure({ view: referenceView ?? null }),
367
+ // A link is being edited only while the caret is on its line: anywhere else on the page it previews on hover.
368
+ ReferenceNode.configure({ view: referenceView ?? null, editingLine: true }),
368
369
  // A link's chip in a sentence, its row alone on its line, its card in the row's place (SPEC §13.3).
369
370
  LinkPlaces,
370
371
  // A click on a link offers Open, and alone on its line Show as Row or Card.
package/src/LinkCard.mdx CHANGED
@@ -12,14 +12,17 @@ A link's card: what a row cannot hold, and the changes the reader may make from
12
12
  ## When
13
13
 
14
14
  - **ready** — it starts as its row does: its kind in a file's 36px tile, the title as the link on one line, cut short when long, and under it the key and what it is ("ABC-2 · Issue"); on the title's line, at the right, its ring, its conversation count and its faces, in that order, as a row's. Then its summary, the items inside it in a box of their own, its newest conversation as a quote, and a footer: the pickers, or who wrote it and when. No summary, the title alone.
15
- - **width** — at most 480px, in a message, a document and a box being written in alike; in a box it sits on the files' fill, its values as words until it is sent.
15
+ - **width** — at most 480px, in a message, a document and a box being written in alike; in a box it sits on the files' fill, its values and its links (the title, the count, its items) as words until it is sent, so a click on it never leaves the draft.
16
16
  - **footer** — only when there is something for it: a title and a summary alone end at the summary.
17
17
  - **read only** — a picker the app passed no `onChange` for reads as words in the same place: the reader may not change it. `readOnly` makes every value words, as the hover preview does.
18
18
  - **words a person wrote** — their 24px face, their name, the time beside it as the link (without a time, the name), and the words.
19
- - **loading** — the card it will become in bars, at its own height: `shape` from `loadingShapeOf(linked)` the last time it drew, or the kind's usual card. **LinkCardLoading**, from this file.
20
- - **unavailable** — one row, as **LinkRow** draws it.
19
+ - **loading** — the card it will become in bars, at its own height: `shape` from `loadingShapeOf(linked)` the last time it drew (kept per device by `cardShapeMemory`), or the kind's usual card. **LinkCardLoading**, from this file.
20
+ - **archived** — `linked.archived`: "Archived" in the line under the title, and its values as words.
21
+ - **unavailable** — one row, as **LinkRow** draws it: "Issue not available", or with `deleted` "Issue deleted"; with `url`, the URL as it was written.
21
22
 
22
23
  <Canvas of={LinkCardStories.ReadOnly} />
24
+ <Canvas of={LinkCardStories.InABox} />
25
+ <Canvas of={LinkCardStories.Archived} />
23
26
  <Canvas of={LinkCardStories.Loading} />
24
27
 
25
28
  ## When not
@@ -42,11 +45,12 @@ const linked = {
42
45
  <LinkCard link={{ state: 'ready', linked }} />
43
46
  ```
44
47
 
45
- - **Whether the reader may change it is the app's.** Pass `onChange` only to a reader who may; anyone else sees words.
48
+ - **Any app drawing a card offers the file's shared actions** (the record a-card-changes-what-a-files-app-shares): pass `onChange` (with `linkStateFrom`, its `onAct`) wherever the reader can act on the file, in every app. Words only where the reader can't: an archived file (`linkStateFrom` does that itself), an archived or read-only conversation or page, a signed-out reader, and the hover preview (`readOnly`).
46
49
  - The picker offers only the options it is given: to let the reader set nobody as the owner, include an option for it.
47
50
  - `linked.latest` is drawn whenever it is given: pass it only to a reader who may read it.
51
+ - **A placeholder that never jumps:** keep, per device and under the app's own key, the shape each card last drew at with `cardShapeMemory(key)` — `of(id, kind)` for the placeholder's `shape` (with its `height` as the box's least height), `note(id, { ...loadingShapeOf(linked), height })` once it drew — and that it could not be shown with `unavailableMemory(key)`, so the next open draws the not-available row from the first paint. Clear both at sign-out.
48
52
  - `linked.conversation.unread` only for a member of it.
49
- - **From interop's projection, build it with `linkStateFrom(object, unread, options)`** (or `linkedFrom` for a read object), so every app draws one thing as one card: its key, its 7 most recently changed items, a ring over all of them, and pickers through its own actions when `options.onAct` is passed (words once it is archived). When it last changed (`changedAt`) reads "2h ago", the same words in every app unless the app passes `whenOf`; who made it, the key its address is signed by, shows as a face when the app can name them and nothing else on the card names a person. The app passes `hrefOf(object, top)`, `previewText(body, people)` and, for a link not yet read, its kind and noun.
53
+ - **From interop's projection, build it with `linkStateFrom(object, unread, options)`** (or `linkedFrom` for a read object), so every app draws one thing as one card: its key, its 7 most recently changed items, a ring over all of them, and pickers through its own actions when `options.onAct` is passed (words once it is archived). When it last changed (`changedAt`) reads "2h ago", the same words in every app unless the app passes `whenOf`; who made it, the key its address is signed by, shows as a face when the app can name them and nothing else on the card names a person. The app passes `hrefOf(object, top)`, `previewText(body, people)` and, for a link not yet read, its kind and noun, and with them `deleted` when a trusted deletion names the address (SPEC §13.6.1) and `url` when the link was written as an app URL. A file whose type has no name is called by its app's name.
50
54
 
51
55
  ## What it owns
52
56
 
@@ -1,8 +1,8 @@
1
1
  import type { Meta, StoryObj } from '@storybook/react-vite'
2
2
  import { useState } from 'react'
3
3
  import { LinkCard, LinkCardLoading } from './LinkCard'
4
- import { loadingShapeOf, type Linked } from './linked'
5
- import { GROUP, ITEM, ITEM_NO_SUMMARY, ITEM_READ_ONLY, ITEM_UNREAD, PAGE, PLACE, ready, SAID, UNAVAILABLE } from './linked.examples'
4
+ import { inTheBox, loadingShapeOf, type Linked } from './linked'
5
+ import { DELETED, GROUP, ITEM, ITEM_ARCHIVED, ITEM_NO_SUMMARY, ITEM_READ_ONLY, ITEM_UNREAD, PAGE, PLACE, ready, SAID, UNAVAILABLE } from './linked.examples'
6
6
 
7
7
  const meta = {
8
8
  title: 'Links & references/LinkCard',
@@ -28,6 +28,18 @@ export const Default: Story = {
28
28
  /** To a reader who may not change it: the same two values, as words. */
29
29
  export const ReadOnly: Story = { args: { link: ready(ITEM_READ_ONLY) } }
30
30
 
31
+ /** Archived: "Archived" in the line under its title, its values as words. */
32
+ export const Archived: Story = { args: { link: ready(ITEM_ARCHIVED) } }
33
+
34
+ /** In a box being written in: on the files' fill, its values and its links as words, so a click on it never leaves the draft. */
35
+ export const InABox: Story = {
36
+ render: (args) => (
37
+ <inTheBox.Provider value>
38
+ <LinkCard {...args} />
39
+ </inTheBox.Provider>
40
+ ),
41
+ }
42
+
31
43
  /** Something unread in its conversation, to a member: the count is brighter, with a dot. */
32
44
  export const Unread: Story = { args: { link: ready(ITEM_UNREAD) } }
33
45
 
@@ -69,3 +81,6 @@ export const LoadingByKind: Story = { args: { link: { state: 'loading', kind: 'i
69
81
 
70
82
  /** Deleted, or not this reader's to see: one line. */
71
83
  export const NotAvailable: Story = { args: { link: UNAVAILABLE } }
84
+
85
+ /** Deleted, as a trusted deletion naming it says: the not-available row, its own words, no way out. */
86
+ export const Deleted: Story = { args: { link: DELETED } }
@@ -44,11 +44,32 @@ describe('LinkCard', () => {
44
44
  expect(screen.queryByRole('combobox')).toBeNull()
45
45
  })
46
46
 
47
+ it('draws a file with no address to open as words: no link to nowhere on its title, its count or its items', () => {
48
+ const { container } = render(<LinkCard link={ready({ ...GROUP, href: '', conversation: { count: 1, href: '' }, children: GROUP.children!.map((child) => ({ ...child, href: '' })) })} />)
49
+ expect(container.querySelector('a')).toBeNull()
50
+ expect(screen.getByText(GROUP.title)).toBeTruthy()
51
+ expect(screen.getByText('1 comment')).toBeTruthy()
52
+ })
53
+
47
54
  it('says nobody owns it when nobody does', () => {
48
55
  render(<LinkCard link={ready({ ...ITEM_READ_ONLY, owner: { value: undefined, options: [] } })} />)
49
56
  expect(screen.getByText('Unassigned')).toBeTruthy()
50
57
  })
51
58
 
59
+ it('draws "Unassigned" with the silhouette, never a letter, as words and in the picker alike', async () => {
60
+ const user = userEvent.setup()
61
+ const nobody = { value: '', label: 'Unassigned' }
62
+ render(<LinkCard link={ready({ ...ITEM_READ_ONLY, owner: { value: '', options: [nobody] } })} />)
63
+ expect(screen.getByText('Unassigned')).toBeTruthy()
64
+ expect(screen.queryByText('U')).toBeNull()
65
+ cleanup()
66
+ render(<LinkCard link={ready({ ...ITEM, owner: { ...ITEM.owner!, value: '', options: [nobody, ...ITEM.owner!.options], onChange: () => {} } })} />)
67
+ expect(screen.queryByText('U')).toBeNull()
68
+ await user.click(screen.getByRole('combobox', { name: 'Owner' }))
69
+ await screen.findByRole('option', { name: /Unassigned/ })
70
+ expect(screen.queryByText('U')).toBeNull()
71
+ })
72
+
52
73
  it('shows the title alone when there is no summary', () => {
53
74
  render(<LinkCard link={ready(ITEM_NO_SUMMARY)} />)
54
75
  expect(screen.getByRole('link', { name: 'Item two' })).toBeTruthy()
package/src/LinkCard.tsx CHANGED
@@ -9,11 +9,11 @@
9
9
  *
10
10
  * At most 480px wide, in a message, a document and a box being written in alike
11
11
  * (Katerina, 30 Oct: a card across a wide box did not look good); in a box it
12
- * sits on the files' fill, its values as words until it is sent. While it
13
- * loads it holds the card's own shape, so what is around it does not jump; not
14
- * available is one row.
12
+ * sits on the files' fill, its values and its links as words until it is sent,
13
+ * so a click on it never leaves the draft. While it loads it holds the card's
14
+ * own shape, so what is around it does not jump; not available is one row.
15
15
  */
16
- import { useContext } from 'react'
16
+ import { useContext, type ReactNode } from 'react'
17
17
  import { Avatar } from './Avatar'
18
18
  import { AvatarGroup } from './AvatarGroup'
19
19
  import { Card } from './Card'
@@ -21,7 +21,7 @@ import { cn } from './cn'
21
21
  import { Link } from './Link'
22
22
  import { inTheBox, type Linked, type LinkedKind, type LinkState, type LoadingShape } from './linked'
23
23
  import { CommentCount, LinkedIcon, LinkKey, LinkPickers, LinkTile, ProgressRing, StatusMark } from './LinkParts'
24
- import { linkMetaOf, LinkUnavailable } from './LinkRow'
24
+ import { linkMetaOf, LinkUnavailable, WrittenUrl } from './LinkRow'
25
25
  import { QUOTE_BAR_CLASSES, TIME_CLASSES, TYPE_TILE_CLASSES } from './looks'
26
26
  import { SkeletonBar } from './Skeleton'
27
27
 
@@ -36,11 +36,28 @@ export interface LinkCardProps {
36
36
  /** A card's frame: 12px round it, 12px between what it holds. */
37
37
  const CARD_CLASSES = 'flex flex-col gap-3 p-3'
38
38
 
39
+ /**
40
+ * A link on a card, or its words alone: in a box being written in, where the card under the box follows no click,
41
+ * as the chips in the box do not (Katerina, 30 Oct), and where there is nowhere to open (an empty `href`).
42
+ */
43
+ function CardLink({ href, truncate = false, className, children }: { href: string; truncate?: boolean; className?: string; children: ReactNode }) {
44
+ const boxed = useContext(inTheBox)
45
+ if (boxed || !href) return <span className={cn(truncate && 'truncate', className)}>{children}</span>
46
+ return (
47
+ <Link href={href} variant="quiet" truncate={truncate} className={className}>
48
+ {children}
49
+ </Link>
50
+ )
51
+ }
52
+
39
53
  export function LinkCard({ link, readOnly = false, bare = false }: LinkCardProps) {
40
54
  // In a box being written in: the files' fill, and the values as words until it is sent.
41
55
  const boxed = useContext(inTheBox)
42
56
  if (link.state === 'loading') return <LinkCardLoading kind={link.kind} shape={link.shape} />
43
- if (link.state === 'unavailable') return <LinkUnavailable kind={link.kind} noun={link.noun} openIn={link.openIn} card />
57
+ if (link.state === 'unavailable') {
58
+ if (link.url) return <WrittenUrl url={link.url} block />
59
+ return <LinkUnavailable kind={link.kind} noun={link.noun} openIn={link.openIn} deleted={link.deleted} card />
60
+ }
44
61
  const { linked } = link
45
62
  const body = linked.kind === 'message' && linked.author ? <SaidBody linked={linked} /> : <CardBody linked={linked} readOnly={readOnly || boxed} />
46
63
  if (bare) return <div className={CARD_CLASSES}>{body}</div>
@@ -64,9 +81,9 @@ function CardBody({ linked, readOnly }: { linked: Linked; readOnly: boolean }) {
64
81
  <span className="flex min-w-0 flex-1 flex-col gap-0.5">
65
82
  <span className="block min-w-0 text-body-2-strong text-text-primary">
66
83
  {/* One line, cut short: a long title truncates rather than wrapping (Katerina, 29 Oct). */}
67
- <Link href={linked.href} variant="quiet" truncate className="block">
84
+ <CardLink href={linked.href} truncate className="block">
68
85
  {linked.title}
69
- </Link>
86
+ </CardLink>
70
87
  </span>
71
88
  {meta && <span className="truncate text-caption text-text-secondary">{meta}</span>}
72
89
  </span>
@@ -84,15 +101,19 @@ function CardBody({ linked, readOnly }: { linked: Linked; readOnly: boolean }) {
84
101
  // In a box of their own, a hairline between them, as the card first drew them (Katerina, 29 Oct: "add back the borders").
85
102
  <div className="flex flex-col divide-y divide-border-subtle rounded-md border border-border-subtle leaf:divide-border-strong leaf:border-border-strong">
86
103
  {linked.children.map((child) => (
87
- <div key={child.id} className="relative flex h-8 items-center gap-2 px-2 hover:bg-bg-active">
104
+ <div key={child.id} className={cn('relative flex h-8 items-center gap-2 px-2', !boxed && 'hover:bg-bg-active')}>
88
105
  {/* The status is the row's icon: a list needs no kind icon on every row. */}
89
106
  <StatusMark status={child.status} />
90
107
  {child.key && <LinkKey>{child.key}</LinkKey>}
91
108
  {/* Each opens on its own; the link covers its row. */}
92
109
  <span className="contents text-body-2 text-text-primary">
93
- <Link href={child.href} variant="quiet" cover truncate className="min-w-0 flex-1">
94
- {child.title}
95
- </Link>
110
+ {boxed || !child.href ? (
111
+ <span className="min-w-0 flex-1 truncate">{child.title}</span>
112
+ ) : (
113
+ <Link href={child.href} variant="quiet" cover truncate className="min-w-0 flex-1">
114
+ {child.title}
115
+ </Link>
116
+ )}
96
117
  </span>
97
118
  {child.owner ? <Avatar name={child.owner.name} src={child.owner.picture} size={16} /> : <span className="size-4 shrink-0" aria-hidden />}
98
119
  </div>
@@ -142,13 +163,11 @@ function SaidBody({ linked }: { linked: Linked }) {
142
163
  <Avatar name={author.name} src={author.picture} size={24} />
143
164
  {/* No "Open" in a missing time's place (Katerina, 30 Oct): the name is the link then. */}
144
165
  <span className="text-body-2-strong text-text-primary">
145
- {linked.updated ? author.name : <Link href={linked.href} variant="quiet">{author.name}</Link>}
166
+ {linked.updated ? author.name : <CardLink href={linked.href}>{author.name}</CardLink>}
146
167
  </span>
147
168
  {linked.updated && (
148
169
  <span className={cn('text-caption text-text-muted', TIME_CLASSES)}>
149
- <Link href={linked.href} variant="quiet">
150
- {linked.updated}
151
- </Link>
170
+ <CardLink href={linked.href}>{linked.updated}</CardLink>
152
171
  </span>
153
172
  )}
154
173
  </div>
package/src/LinkChip.mdx CHANGED
@@ -13,10 +13,15 @@ A link in a sentence: its icon, its key, its title cut short, and its status as
13
13
 
14
14
  - **ready** — a link the app has looked up. Hovering it shows its card (**LinkPreview**); a tap or a click opens it.
15
15
  - **loading** — still being looked up: the icon, which the address already says, and a bar.
16
- - **unavailable** — deleted, or not the reader's to see. Both say "Issue not available" in the app's word for it.
16
+ - **unavailable** — not the reader's to see: "Issue not available", in the app's word for it (its type's, else its app's name).
17
+ - **deleted** — `deleted` on the state, when a trusted deletion names it (SPEC §13.6.1): "Issue deleted". A reader tells the two apart; the words never say which a hidden file is.
18
+ - **written as a URL** — `url` on the state: a link written as an app URL that cannot be shown stays that URL, a plain link, deleted or not available alike (SPEC §13.1). The words above are only for a `nostr:` reference.
17
19
  - `preview={false}` — no card on hover, where a card would cover what the reader is choosing from.
20
+ - **no address** — an empty `linked.href` (another app's file with none over https): a label, not a link.
18
21
 
19
22
  <Canvas of={LinkChipStories.EachKind} />
23
+ <Canvas of={LinkChipStories.Deleted} />
24
+ <Canvas of={LinkChipStories.WrittenAsAUrl} />
20
25
 
21
26
  ## When not
22
27
 
@@ -1,6 +1,6 @@
1
1
  import type { Meta, StoryObj } from '@storybook/react-vite'
2
2
  import { LinkChip } from './LinkChip'
3
- import { GROUP, ITEM, LOADING, PAGE, PLACE, ready, SAID, UNAVAILABLE } from './linked.examples'
3
+ import { DELETED, GROUP, ITEM, LOADING, PAGE, PLACE, ready, SAID, UNAVAILABLE, WRITTEN_AS_A_URL } from './linked.examples'
4
4
 
5
5
  const meta = {
6
6
  title: 'Links & references/LinkChip',
@@ -38,3 +38,9 @@ export const NotAvailable: Story = { args: { link: UNAVAILABLE } }
38
38
 
39
39
  /** No card on hover: where a card would cover what the reader is choosing from. */
40
40
  export const WithoutPreview: Story = { args: { preview: false } }
41
+
42
+ /** Deleted, as a trusted deletion naming it says: told apart from not available. */
43
+ export const Deleted: Story = { args: { link: DELETED } }
44
+
45
+ /** Written as a URL that cannot be shown: it stays that URL, a plain link, as a message draws one. */
46
+ export const WrittenAsAUrl: Story = { args: { link: WRITTEN_AS_A_URL } }
@@ -63,6 +63,18 @@ describe('LinkChip', () => {
63
63
  expect(screen.queryByRole('link')).toBeNull()
64
64
  })
65
65
 
66
+ it('is a label, not a link, for a file with no address to open', () => {
67
+ const { container } = render(<LinkChip link={{ state: 'ready', linked: { id: 'x', kind: 'file', title: 'Item one', href: '' } }} preview={false} />)
68
+ expect(container.querySelector('a')).toBeNull()
69
+ expect(screen.getByText('Item one')).toBeTruthy()
70
+ })
71
+
72
+ it('says it was deleted, apart from not available, and leads nowhere', () => {
73
+ render(<LinkChip link={{ state: 'unavailable', kind: 'issue', noun: 'Issue', deleted: true }} />)
74
+ expect(screen.getByText('Issue deleted')).toBeTruthy()
75
+ expect(screen.queryByRole('link')).toBeNull()
76
+ })
77
+
66
78
  it('shows its card, read only, when the pointer rests on it', async () => {
67
79
  screenThatCanHover(true)
68
80
  render(<LinkChip link={ready(ITEM)} />)
package/src/LinkChip.tsx CHANGED
@@ -14,6 +14,7 @@ import type { LinkState } from './linked'
14
14
  import { chosenOf } from './linked'
15
15
  import { LinkedIcon, LinkKey, StatusMark } from './LinkParts'
16
16
  import { LinkPreview } from './LinkPreview'
17
+ import { WrittenUrl } from './LinkRow'
17
18
  import { SkeletonBar } from './Skeleton'
18
19
 
19
20
  export interface LinkChipProps {
@@ -31,9 +32,11 @@ export function LinkChip({ link, preview = true }: LinkChipProps) {
31
32
  )
32
33
  }
33
34
  if (link.state === 'unavailable') {
35
+ // Written as a URL, it stays that URL (SPEC §13.1); only a `nostr:` reference says why it is not shown.
36
+ if (link.url) return <WrittenUrl url={link.url} />
34
37
  return (
35
38
  <InlineChip tone="muted" icon={<LinkedIcon kind={link.kind} size={14} tone="inherit" />}>
36
- {link.noun} not available
39
+ {link.noun} {link.deleted ? 'deleted' : 'not available'}
37
40
  </InlineChip>
38
41
  )
39
42
  }
@@ -43,7 +46,8 @@ export function LinkChip({ link, preview = true }: LinkChipProps) {
43
46
  const chip = (
44
47
  <InlineChip
45
48
  icon={said ? <Avatar name={said.name} src={said.picture} size={14} /> : <LinkedIcon kind={linked.kind} size={14} tone="inherit" />}
46
- href={linked.href}
49
+ // No address to open (another app's file with none over https): a label, not a link to nowhere.
50
+ href={linked.href || undefined}
47
51
  // Never wider than its line. With its hover card, the card's wrapper holds it to the line (max-w-full): a share of the
48
52
  // line on the chip itself made the wrapper as wide as the whole title, and left a gap after the cut-short chip
49
53
  // (Katerina, 29 Oct). Without one, it holds itself, less its own 2px each side.
package/src/LinkChips.mdx CHANGED
@@ -14,8 +14,9 @@ recognise, or has not answered for yet, stays text.
14
14
  ## When
15
15
 
16
16
  - **An editor of a document whose URLs can name things**: pair it with
17
- **ReferenceNode**, which draws the chip, and **ReferenceCards**, which places
18
- the card a chip can ask for.
17
+ **ReferenceNode**, which draws the chip, **LinkPlaces**, which draws a lone
18
+ link as its row or its card, and **ReferenceMenu**, where its writer chooses
19
+ between them. **DocumentEditor** has all of them.
19
20
 
20
21
  ## When not
21
22
 
@@ -29,7 +30,7 @@ recognise, or has not answered for yet, stays text.
29
30
  ## How
30
31
 
31
32
  ```tsx
32
- import { LinkChips, ReferenceCards, ReferenceNode } from '@estiva-app/ui/editor'
33
+ import { LinkChips, LinkPlaces, ReferenceMenu, ReferenceNode } from '@estiva-app/ui/editor'
33
34
 
34
35
  LinkChips.configure({
35
36
  // What the app has resolved so far: the reference a URL names, or undefined.