@estiva-app/ui 0.82.0 → 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,13 +1,16 @@
1
1
  /**
2
- * What a chip in a document offers its writer — Open, and its card: none,
3
- * compact or detailed (SPEC §13.3, "A reference's card").
2
+ * What a link in a document offers its writer: Open, and — alone on its line —
3
+ * Show as Row or Card (SPEC §13.3, "A reference's card"). Card puts its card in
4
+ * the row's place (`embed` `detailed`); Row puts the row back (no `embed`).
5
+ * Nothing writes `compact`. A chip in a sentence, and a person or a Folder alone
6
+ * on its line (which stay chips), offer Open only (`linkPlaceAt`).
4
7
  *
5
- * **Where it opens** (Miky, 14 Oct): a click on a chip while editing opens the
6
- * menu instead of following the chip, and a chip just put in — pasted, picked
7
- * with `[`, or a pasted URL becoming its chip (`LinkChips`) — opens it by
8
- * itself, so the card can be chosen at once. That menu takes no focus: the
9
- * person is still writing, and typing on closes it with no card. Enter on a
10
- * selected chip opens it from the keyboard.
8
+ * **Where it opens**: a click on a link while editing opens the menu instead
9
+ * of following it, and a lone-line link just put in — pasted, picked with `[`,
10
+ * or a pasted URL becoming its chip (`LinkChips`) — opens it by itself, so the
11
+ * card can be chosen at once. That menu takes no focus: the person is still
12
+ * writing, and typing on closes it with no card. Enter on a selected link opens
13
+ * it from the keyboard.
11
14
  *
12
15
  * **Keys while it is open**, handed over by the editor as the `/` menu's are:
13
16
  * ↓ and ↑ move through the rows (nothing is highlighted until they do, so
@@ -20,12 +23,7 @@
20
23
  *
21
24
  * Two parts: the extension `ReferenceMenu` holds which chip the menu is open
22
25
  * on, and `ReferenceMenuView` draws it beside `EditorContent`. Pair them with
23
- * `ReferenceNode` and `ReferenceCards`.
24
- *
25
- * Not yet what the record below says: it replaced the Card sizes with Show as
26
- * Row or Card for a lone link, and Open only for a chip in a sentence. The
27
- * shared editor's chip menu is changed to it next (WBD-4); until then this
28
- * menu is the 14 October one.
26
+ * `ReferenceNode` and `LinkPlaces`.
29
27
  *
30
28
  * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-lone-links-chip-menu-offers-row-or-card.md
31
29
  */
@@ -35,11 +33,12 @@ import { useEditorState } from '@tiptap/react'
35
33
  import { NodeSelection, Plugin, PluginKey, TextSelection, type EditorState, type Transaction } from '@tiptap/pm/state'
36
34
  import { ReplaceStep } from '@tiptap/pm/transform'
37
35
  import type { EditorView } from '@tiptap/pm/view'
38
- import { IconCheck } from '@tabler/icons-react'
36
+ import { IconCheck, IconExternalLink } from '@tabler/icons-react'
39
37
  import { CHIPS_MADE } from './LinkChips'
38
+ import { linkPlaceAt } from './LinkPlaces'
40
39
  import { MenuItem, MenuSection, MenuSeparator } from './Menu'
41
40
  import { Popover } from './Popover'
42
- import { setReferenceCardAt, type ReferenceCardLayout } from './ReferenceCards'
41
+ import { setReferenceCardAt } from './ReferenceCards'
43
42
 
44
43
  interface MenuState {
45
44
  /** The chip's position. */
@@ -50,14 +49,16 @@ interface MenuState {
50
49
 
51
50
  const key = new PluginKey<MenuState | null>('referenceMenu')
52
51
 
53
- const LAYOUTS: { layout: ReferenceCardLayout; label: string }[] = [
54
- { layout: 'none', label: 'None' },
55
- { layout: 'compact', label: 'Compact' },
56
- { layout: 'detailed', label: 'Detailed' },
52
+ /** How a lone-line link can show. */
53
+ type ShowAs = 'row' | 'card'
54
+
55
+ const SHOW_AS: { as: ShowAs; label: string }[] = [
56
+ { as: 'row', label: 'Row' },
57
+ { as: 'card', label: 'Card' },
57
58
  ]
58
59
 
59
- /** A row: Open, or a card. */
60
- type Row = 'open' | ReferenceCardLayout
60
+ /** A row of the menu: Open, or a way to show the link. */
61
+ type Row = 'open' | ShowAs
61
62
 
62
63
  /** The chip's own control to click, or null. */
63
64
  function chipTarget(view: EditorView, pos: number): HTMLElement | null {
@@ -72,12 +73,15 @@ function webHref(view: EditorView, pos: number): string {
72
73
  }
73
74
 
74
75
  /**
75
- * The menu's rows: Open when there is something to open — the chip's own
76
- * control, or its URL — and the cards when the chip names something.
76
+ * The menu's rows: Open when there is something to open — the link's own
77
+ * control, or its URL — and Row and Card when it is alone on its line and is
78
+ * neither a person nor a Folder (`linkPlaceAt`).
77
79
  */
78
80
  function rowsOf(view: EditorView, pos: number): Row[] {
79
- const open: Row[] = chipTarget(view, pos) || webHref(view, pos) ? ['open'] : []
80
- return view.state.doc.nodeAt(pos)?.attrs.uri ? [...open, ...LAYOUTS.map((card) => card.layout)] : open
81
+ // A link the app draws has its own control even before React has drawn it, as right after a `[` pick.
82
+ const drawn = !!view.state.doc.nodeAt(pos)?.attrs.uri && !!view.someProp('nodeViews', (views) => views?.reference)
83
+ const open: Row[] = drawn || chipTarget(view, pos) || webHref(view, pos) ? ['open'] : []
84
+ return linkPlaceAt(view.state.doc, pos) === 'chip' ? open : [...open, ...SHOW_AS.map((show) => show.as)]
81
85
  }
82
86
 
83
87
  /** A chip node, or null. */
@@ -114,6 +118,8 @@ function justPlaced(tr: Transaction, state: EditorState): number | null {
114
118
  // The same chip as before the step — a key pressed after it, a card set on it — is not new. One put in just before
115
119
  // an identical chip pushes that chip along, so it no longer maps onto `pos` (code review).
116
120
  if (was && was.type.name === 'reference' && was.attrs.uri === before.attrs.uri && tr.mapping.map(old, 1) === pos) return null
121
+ // Only a link alone on its line has a card to choose; in a sentence the menu would offer Open alone.
122
+ if (linkPlaceAt(state.doc, pos) === 'chip') return null
117
123
  return pos
118
124
  }
119
125
 
@@ -144,7 +150,7 @@ function openChip(view: EditorView, pos: number): void {
144
150
  function choose(editor: Editor, pos: number, row: Row | undefined): void {
145
151
  dispatchMenu(editor.view, null)
146
152
  if (row === 'open') openChip(editor.view, pos)
147
- else if (row) setReferenceCardAt(editor, pos, row)
153
+ else if (row) setReferenceCardAt(editor, pos, row === 'card' ? 'detailed' : 'none')
148
154
  }
149
155
 
150
156
  /** Whether the menu is open, for an editor's own Escape: while it is, Escape closes it rather than leaving. */
@@ -248,12 +254,11 @@ export const ReferenceMenu = Extension.create({
248
254
  },
249
255
  })
250
256
 
251
- /** What the panel draws: the chip the menu is open on, and its card. */
257
+ /** What the panel draws: the link the menu is open on, and how it shows. */
252
258
  interface Shown {
253
259
  pos: number
254
260
  active: number
255
- named: boolean
256
- layout: ReferenceCardLayout
261
+ shownAs: ShowAs
257
262
  }
258
263
 
259
264
  export interface ReferenceMenuViewProps {
@@ -268,12 +273,9 @@ export function ReferenceMenuView({ editor }: ReferenceMenuViewProps) {
268
273
  if (!ed || ed.isDestroyed) return null
269
274
  const open = key.getState(ed.state)
270
275
  if (!open) return null
271
- const node = chipAt(ed.state, open.pos)
272
- if (!node) return null
273
- const embed = node.attrs.embed
274
- // An unknown layout draws compact (§13.3), so it reads as compact here.
275
- const layout: ReferenceCardLayout = embed === 'detailed' ? 'detailed' : typeof embed === 'string' && embed !== '' && embed !== 'none' ? 'compact' : 'none'
276
- return { pos: open.pos, active: open.active, named: !!node.attrs.uri, layout }
276
+ if (!chipAt(ed.state, open.pos)) return null
277
+ // `compact` and a value this version does not know draw the row (§13.3), so they read as Row here.
278
+ return { pos: open.pos, active: open.active, shownAs: linkPlaceAt(ed.state.doc, open.pos) === 'card' ? 'card' : 'row' }
277
279
  },
278
280
  })
279
281
  // A press anywhere in the panel keeps focus in the text, as a row's does: the editor saves and ends its menus when it loses focus.
@@ -290,6 +292,7 @@ export function ReferenceMenuView({ editor }: ReferenceMenuViewProps) {
290
292
  const anchor = dom instanceof HTMLElement ? dom : null
291
293
  const rows = live && shown ? rowsOf(live.view, shown.pos) : []
292
294
  const opens = rows[0] === 'open'
295
+ const showAs = rows.includes('card')
293
296
  const run = (row: Row) => {
294
297
  if (editor && shown) choose(editor, shown.pos, row)
295
298
  }
@@ -315,6 +318,7 @@ export function ReferenceMenuView({ editor }: ReferenceMenuViewProps) {
315
318
  role="menuitem"
316
319
  tabIndex={-1}
317
320
  label="Open"
321
+ leading={<IconExternalLink size={16} />}
318
322
  selected={shown.active === 0}
319
323
  onMouseDown={(event) => {
320
324
  event.preventDefault()
@@ -322,23 +326,23 @@ export function ReferenceMenuView({ editor }: ReferenceMenuViewProps) {
322
326
  }}
323
327
  />
324
328
  )}
325
- {shown.named && (
329
+ {showAs && (
326
330
  <>
327
331
  {opens && <MenuSeparator />}
328
- <div role="group" aria-label="Card">
329
- <MenuSection label="Card">
330
- {LAYOUTS.map(({ layout, label }, i) => (
332
+ <div role="group" aria-label="Show as">
333
+ <MenuSection label="Show as">
334
+ {SHOW_AS.map(({ as, label }, i) => (
331
335
  <MenuItem
332
- key={layout}
336
+ key={as}
333
337
  role="menuitemradio"
334
- aria-checked={shown.layout === layout}
338
+ aria-checked={shown.shownAs === as}
335
339
  tabIndex={-1}
336
340
  label={label}
337
341
  selected={shown.active === i + (opens ? 1 : 0)}
338
- trailing={shown.layout === layout ? <IconCheck size={16} aria-hidden /> : undefined}
342
+ trailing={shown.shownAs === as ? <IconCheck size={16} aria-hidden /> : undefined}
339
343
  onMouseDown={(event) => {
340
344
  event.preventDefault()
341
- run(layout)
345
+ run(as)
342
346
  }}
343
347
  />
344
348
  ))}
package/src/editor.ts CHANGED
@@ -113,6 +113,7 @@ export {
113
113
  type ReferenceCardSlot,
114
114
  } from './ReferenceCards'
115
115
  export { LinkChips, findLinkChips, refreshLinkChips, type LinkChipsOptions, type PastedRange } from './LinkChips'
116
+ export { LinkPlaces, linkPlaceAt, staysChip, type LinkPlace } from './LinkPlaces'
116
117
  export { ReferenceMenu, ReferenceMenuView, isReferenceMenuOpen, referenceMenuClick, type ReferenceMenuViewProps } from './ReferenceMenu'
117
118
  export {
118
119
  DocumentEditor,
@@ -60,9 +60,10 @@ export const GROUP: Linked = {
60
60
  done: { done: 2, total: 5 },
61
61
  conversation: { count: 2, href: '#group-conversation' },
62
62
  children: [
63
- { id: 'example:c1', title: 'Item one', href: '#c1', key: 'ABC-1', status: { label: 'Done', colour: 'green' }, owner: { name: 'Person one' } },
64
- { id: 'example:c2', title: 'Item two', href: '#c2', key: 'ABC-2', status: { label: 'In progress', colour: 'blue' }, owner: { name: 'Person two' } },
65
- { id: 'example:c3', title: 'Item three', href: '#c3', key: 'ABC-3', status: { label: 'Todo', colour: 'neutral' } },
63
+ // The same keys as `ITEM` and `ITEM_NO_SUMMARY`, so a story showing the group beside its items reads as one set.
64
+ { id: 'example:c1', title: 'Item one', href: '#c1', key: 'ABC-2', status: { label: 'Done', colour: 'green' }, owner: { name: 'Person one' } },
65
+ { id: 'example:c2', title: 'Item two', href: '#c2', key: 'ABC-3', status: { label: 'In progress', colour: 'blue' }, owner: { name: 'Person two' } },
66
+ { id: 'example:c3', title: 'Item three', href: '#c3', key: 'ABC-4', status: { label: 'Todo', colour: 'neutral' } },
66
67
  ],
67
68
  }
68
69
 
package/src/pages.test.ts CHANGED
@@ -44,8 +44,8 @@ const HOLDS_ONLY: Record<string, string> = {
44
44
  PastedMarkdown: 'Nothing. It draws nothing; it hands pasted text to the app\'s reader and puts back what that reads.',
45
45
  CodeBlockColours: 'Nothing. It names each word of a code block; the RichText class list colours them.',
46
46
  LinkChips: 'Nothing. It draws nothing; it turns the URLs the app recognises into chips.',
47
- // Its box is the Popover's, which owns what a box does; it holds which chip the menu is on.
48
- ReferenceMenu: 'Nothing. Its box is the Popover; it holds which chip the menu is open on, and its keys.',
47
+ // Its box is the Popover's, which owns what a box does; it holds which link the menu is on.
48
+ ReferenceMenu: 'Nothing. Its box is the Popover; it holds which link the menu is open on, and its keys.',
49
49
  }
50
50
 
51
51
  const dir = new URL('.', import.meta.url)
@@ -26,7 +26,7 @@ import { SCHEMA_VERSION, validateRegistry, type Registry, type RegistryEntry } f
26
26
  const root = process.cwd()
27
27
  const registry = buildRegistry({ root })
28
28
  /** Editor extensions: named like components by the catalogue, and not React components. */
29
- const EDITOR_EXTENSIONS = ['KeptSelection', 'BlockId', 'UnknownBlock', 'ReferenceNode', 'AttachmentNode', 'PersonMention', 'UrgentPersonMention', 'PersonReference', 'CaptionedReference', 'ReferenceTrigger', 'SlashCommands', 'PastedImages', 'PastedMarkdown', 'CodeBlockColours', 'Checklist', 'Callout', 'ReferenceCards', 'LinkChips', 'ReferenceMenu', 'CommentHighlights', 'ComposeKeys']
29
+ const EDITOR_EXTENSIONS = ['KeptSelection', 'BlockId', 'UnknownBlock', 'ReferenceNode', 'AttachmentNode', 'PersonMention', 'UrgentPersonMention', 'PersonReference', 'CaptionedReference', 'ReferenceTrigger', 'SlashCommands', 'PastedImages', 'PastedMarkdown', 'CodeBlockColours', 'Checklist', 'Callout', 'ReferenceCards', 'LinkChips', 'LinkPlaces', 'ReferenceMenu', 'CommentHighlights', 'ComposeKeys']
30
30
  const entry = (name: string): RegistryEntry => {
31
31
  const found = registry.entries.find((candidate) => candidate.name === name)
32
32
  if (!found) throw new Error(`no entry for ${name}`)
@@ -48,20 +48,20 @@ describe('the registry builds', () => {
48
48
  expect(registry.entries.map((one) => one.name).sort()).toEqual(values.map((one) => one.name).sort())
49
49
  })
50
50
 
51
- it('counts 206 names over 96 files: 140 components, 63 helpers and 3 hooks (DocumentEditor, one document editor for every app, and PersonReference, `@` in a document (WBD-3), on 20 October; toggleTableHeaderRow, a table’s header row on and off (LEAF-12), on 19 October;EntryShell, the screen while nobody is signed in, moved from Peek (AUT-3), on 17 October; CommentBox with commentBoxRows, and ReactionRow with AddReactionButton and whoReacted, the shared comment box and reaction row (COMM-2), on 17 October; the link widgets — LinkChip, LinkRow, LinkCard, CardUnder, PartCard, LinkPreview and their parts, with useCanHover, chosenOf, loadingShapeOf and unavailableMemory — from the Widgets 2 prototype, on 16 October; InlineText, a title or the line under it edited where it stands (SUM-4), on 16 October; ComposeBox with ComposeKeys and its classes, CommentHighlights with its five helpers, and keepSelection and releaseSelection, from the Leaf prototype (LEAF-4), on 16 October;NavTree, NavTreeSection, the composer triggers and UnreadDot joined on 2 October; BlockHandle and EditorBlockHandle (RIC-18) on 2 October, moveBlock and blockDropCursor, the drop in the gutter, on 5 October, MembersPill and MembersDialog, moved from Peek (SHI-31), on 6 October, ShowMore on 7 October, AppProvider on 8 October, and KindIcon, thingKindOf and PastedImages with its two helpers, moved from Peek, on 8 October; CodeBlockColours, the coloured code block of the editor, on 9 October; Checklist, Callout, isChecklistTick and calloutLook (RIC-19) on 13 October; EditorTableControls and its four actions (RIC-21) on 13 October; ReferenceCards, useReferenceCards and its three helpers, the card a chip in a document asks for, on 14 October; LinkChips and its two helpers, a URL in a document read as its chip, on 14 October; ReferenceMenu, ReferenceMenuView and three helpers, the menu of a chip while writing, on 14 October; PastedMarkdown, markdown pasted as the blocks it spells (LEAF-10), on 15 October; turnIntoRows, turnListInto and turnQuoteInto, the block menu’s Turn into for a list and a quote (LEAF-11), on 15 October)', () => {
51
+ it('counts 209 names over 97 files: 141 components, 65 helpers and 3 hooks (LinkPlaces with linkPlaceAt and staysChip, a link in a document drawn where it sits (WBD-4), on 20 October; DocumentEditor, one document editor for every app, and PersonReference, `@` in a document (WBD-3), on 20 October; toggleTableHeaderRow, a table’s header row on and off (LEAF-12), on 19 October;EntryShell, the screen while nobody is signed in, moved from Peek (AUT-3), on 17 October; CommentBox with commentBoxRows, and ReactionRow with AddReactionButton and whoReacted, the shared comment box and reaction row (COMM-2), on 17 October; the link widgets — LinkChip, LinkRow, LinkCard, CardUnder, PartCard, LinkPreview and their parts, with useCanHover, chosenOf, loadingShapeOf and unavailableMemory — from the Widgets 2 prototype, on 16 October; InlineText, a title or the line under it edited where it stands (SUM-4), on 16 October; ComposeBox with ComposeKeys and its classes, CommentHighlights with its five helpers, and keepSelection and releaseSelection, from the Leaf prototype (LEAF-4), on 16 October;NavTree, NavTreeSection, the composer triggers and UnreadDot joined on 2 October; BlockHandle and EditorBlockHandle (RIC-18) on 2 October, moveBlock and blockDropCursor, the drop in the gutter, on 5 October, MembersPill and MembersDialog, moved from Peek (SHI-31), on 6 October, ShowMore on 7 October, AppProvider on 8 October, and KindIcon, thingKindOf and PastedImages with its two helpers, moved from Peek, on 8 October; CodeBlockColours, the coloured code block of the editor, on 9 October; Checklist, Callout, isChecklistTick and calloutLook (RIC-19) on 13 October; EditorTableControls and its four actions (RIC-21) on 13 October; ReferenceCards, useReferenceCards and its three helpers, the card a chip in a document asks for, on 14 October; LinkChips and its two helpers, a URL in a document read as its chip, on 14 October; ReferenceMenu, ReferenceMenuView and three helpers, the menu of a chip while writing, on 14 October; PastedMarkdown, markdown pasted as the blocks it spells (LEAF-10), on 15 October; turnIntoRows, turnListInto and turnQuoteInto, the block menu’s Turn into for a list and a quote (LEAF-11), on 15 October)', () => {
52
52
  // The reconciliation GATES.md §24 explains. If this changes, that changes.
53
53
  // The `EDITOR_EXTENSIONS` count as components by their names; they are
54
54
  // editor extensions, documented on SelectionToolbar's, BlockNodes' and
55
55
  // ComposerTriggers' pages.
56
56
  const kinds = registry.entries.reduce<Record<string, number>>((all, one) => ({ ...all, [one.kind]: (all[one.kind] ?? 0) + 1 }), {})
57
- expect(kinds).toEqual({ component: 140, helper: 63, hook: 3 })
58
- expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(96)
57
+ expect(kinds).toEqual({ component: 141, helper: 65, hook: 3 })
58
+ expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(97)
59
59
  })
60
60
 
61
61
  it('gives every entry a purpose, from its own page or from the comment above it', () => {
62
62
  expect(registry.entries.filter((one) => one.purpose.trim() === '')).toEqual([])
63
- expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(90)
64
- expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(116)
63
+ expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(91)
64
+ expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(118)
65
65
  })
66
66
 
67
67
  it('takes a name with a page of its own from the page, and a name without one from the code', () => {
@@ -105,9 +105,10 @@ fork freely, owe nothing back, mention it on the package's ticket.
105
105
  | A document or an image attached to something, posted or waiting to be sent | **AttachmentCard** — the file decides the shape; `pending` in a composer |
106
106
  | A picture pasted into an editor, attached rather than pasted | **PastedImages** — from `@estiva-app/ui/editor`; the app hands it its upload |
107
107
  | Markdown pasted as plain text, landing as the headings, lists and tables it spells | **PastedMarkdown** — from `@estiva-app/ui/editor`, in an editor that saves a block document; the app hands it the protocol's reader |
108
- | A card a chip in a document asks for, drawn after its line | **ReferenceCards** — from `@estiva-app/ui/editor`, beside `ReferenceNode`; the app draws its card into each slot |
108
+ | A link in a document drawn where it sits: chip in a sentence, row alone on its line, card in the row's place | **LinkPlaces** — from `@estiva-app/ui/editor`, beside `ReferenceNode`; the app's view draws what `place` says. **DocumentEditor** has it |
109
+ | A card a chip in a document asks for, drawn after its line (an editor not yet on the line rule) | **ReferenceCards** — from `@estiva-app/ui/editor`, beside `ReferenceNode`; the app draws its card into each slot |
109
110
  | A URL in a document that reads as the chip of what it points at | **LinkChips** — from `@estiva-app/ui/editor`, beside `ReferenceNode`; the app says what each URL names |
110
- | Open a chip in a document, or choose its card, while writing | **ReferenceMenu** — from `@estiva-app/ui/editor`, beside `ReferenceCards`; a click on the chip, or putting one in, opens it |
111
+ | Open a link in a document, or show a lone one as its row or card, while writing | **ReferenceMenu** — from `@estiva-app/ui/editor`, beside `LinkPlaces`; a click on the link, or putting one alone on a line, opens it |
111
112
  | A code block in an editor, coloured by its language as you type | **CodeBlockColours** — from `@estiva-app/ui/editor`, in place of the starter kit's code block |
112
113
  | A link to something an app looked up, in a sentence | **LinkChip** — hover shows its card; loading and "not available" drawn for you. **LinkChips** (editor) turns a URL in a document into one |
113
114
  | A link alone on its line | **LinkRow** — one 36px line for every kind; **LinkUnavailable** when it cannot be read |