@estiva-app/ui 0.80.0 → 0.82.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/dist/BlockNodes.d.ts.map +1 -1
  2. package/dist/CardUnder.d.ts +24 -3
  3. package/dist/CardUnder.d.ts.map +1 -1
  4. package/dist/CommentBox.d.ts +39 -5
  5. package/dist/CommentBox.d.ts.map +1 -1
  6. package/dist/ComposerTriggers.d.ts +24 -0
  7. package/dist/ComposerTriggers.d.ts.map +1 -1
  8. package/dist/DocumentEditor.d.ts +138 -0
  9. package/dist/DocumentEditor.d.ts.map +1 -0
  10. package/dist/ReferenceMenu.d.ts.map +1 -1
  11. package/dist/SelectionToolbar.d.ts.map +1 -1
  12. package/dist/editor.d.ts +3 -2
  13. package/dist/editor.d.ts.map +1 -1
  14. package/dist/editor.js +565 -46
  15. package/dist/editor.js.map +4 -4
  16. package/dist/index.js +2 -2
  17. package/dist/index.js.map +2 -2
  18. package/dist/links.d.ts +28 -0
  19. package/dist/links.d.ts.map +1 -0
  20. package/package.json +7 -1
  21. package/registry.json +199 -10
  22. package/src/BlockNodes.tsx +3 -1
  23. package/src/CardUnder.mdx +1 -0
  24. package/src/CardUnder.tsx +10 -6
  25. package/src/CommentBox.mdx +8 -0
  26. package/src/CommentBox.stories.tsx +62 -2
  27. package/src/CommentBox.test.tsx +169 -1
  28. package/src/CommentBox.tsx +110 -17
  29. package/src/ComposerTriggers.tsx +65 -0
  30. package/src/DocumentEditor.mdx +106 -0
  31. package/src/DocumentEditor.stories.tsx +305 -0
  32. package/src/DocumentEditor.test.tsx +528 -0
  33. package/src/DocumentEditor.tsx +568 -0
  34. package/src/ReferenceMenu.tsx +6 -1
  35. package/src/SelectionToolbar.tsx +2 -1
  36. package/src/editor.ts +13 -0
  37. package/src/gates/create-app.test.ts +3 -1
  38. package/src/links.ts +151 -0
  39. package/src/registry/registry.test.ts +6 -6
  40. package/stories/Choosing.mdx +1 -0
@@ -0,0 +1,568 @@
1
+ import { useCallback, useEffect, useRef, useState, type ComponentType, type ReactNode } from 'react'
2
+ import type { AnyExtension } from '@tiptap/core'
3
+ import { TextSelection } from '@tiptap/pm/state'
4
+ import { EditorContent, useEditor, useEditorState, type Editor, type JSONContent } from '@tiptap/react'
5
+ import { TableKit } from '@tiptap/extension-table'
6
+ import { IconMessagePlus } from '@tabler/icons-react'
7
+ import type { HandleBlock } from './BlockHandle'
8
+ import { AttachmentNode, BlockId, Callout, Checklist, ReferenceNode, UnknownBlock, isChecklistTick, type AttachmentViewProps, type ReferenceViewProps } from './BlockNodes'
9
+ import { Button } from './Button'
10
+ import { CodeBlockColours } from './CodeBlockColours'
11
+ import { CommentHighlights, anchorOfSelection, type SelectionAnchor } from './CommentHighlights'
12
+ import { PersonReference, ReferenceTrigger, SlashCommands, formatSection, typeTrigger, type MentionPerson, type ReferenceSection, type SlashCommand, type SlashSection } from './ComposerTriggers'
13
+ import { EditorBlockHandle, blockDropCursor } from './EditorBlockHandle'
14
+ import { EditorTableControls } from './EditorTableControls'
15
+ import { FieldLine } from './Field'
16
+ import { FilePicker } from './FilePicker'
17
+ import { LinkChips, type LinkChipsOptions } from './LinkChips'
18
+ import { BareLinks, DocumentKit, LINK_MARK_ATTRIBUTES, PasteOverWords } from './links'
19
+ import { PastedImages } from './PastedImages'
20
+ import { PastedMarkdown } from './PastedMarkdown'
21
+ import { ReferenceCards } from './ReferenceCards'
22
+ import { ReferenceMenu, ReferenceMenuView, isReferenceMenuOpen } from './ReferenceMenu'
23
+ import { richTextClassName } from './RichText'
24
+ import { KeptSelection, SelectionToolbar } from './SelectionToolbar'
25
+ import { isSuggestionOpen } from './suggestionPopup'
26
+
27
+ /**
28
+ * How the app's saved text and the editor's document turn into each other. The
29
+ * package speaks only the editor's document; the translation is
30
+ * `@estiva-app/protocol`'s, which the package does not depend on (the record
31
+ * below):
32
+ *
33
+ * { read: (value, format) => toEditorDocument(documentForEditing(value, format), { links: true }),
34
+ * write: (doc) => publishableFromEditor(doc) }
35
+ */
36
+ export interface DocumentCodec {
37
+ /** The saved text, in its format, as the editor's document. */
38
+ read: (value: string, format: string) => JSONContent
39
+ /** The editor's document as the text to save, and the format it is in. */
40
+ write: (doc: JSONContent) => { value: string; contentFormat?: string }
41
+ }
42
+
43
+ /**
44
+ * Where text typed when the sign-in ends is kept through the passkey trip, and
45
+ * put back, unsaved, after it. The app's own store, by key.
46
+ */
47
+ export interface HeldTyping {
48
+ /** What is held for `key` from the last ending, or `undefined`. */
49
+ text: (key: string) => string | undefined
50
+ /** Forget what is held for `key`: it was saved. */
51
+ release: (key: string) => void
52
+ /** While the editor is open, let an ending read its unsaved text. Returns what stops that, as the editor closes. */
53
+ register: (key: string, read: () => string | undefined) => () => void
54
+ /** Whether the sign-in has ended: nothing is saved then, and the text is held instead. */
55
+ ended: () => boolean
56
+ }
57
+
58
+ /** What `[` lists, and how. Without it `[` is a bracket. */
59
+ export interface DocumentReferences {
60
+ /** The sections for what was typed after `[`, already narrowed and in the app's order. */
61
+ sections: (query: string) => readonly ReferenceSection[]
62
+ /** Called with a listener while the list is open; call it when `sections` would answer differently (a search landed). */
63
+ subscribe?: (listener: () => void) => () => void
64
+ /** Names the list. */
65
+ ariaLabel: string
66
+ /** The heading of rows that bring no section of their own. */
67
+ sectionLabel: string
68
+ /** A row's 16px icon, unless the row brings its own. Default none. */
69
+ icon?: ReactNode
70
+ }
71
+
72
+ /** Whom `@` offers. Without it `@` is an at sign. */
73
+ export interface DocumentMentions {
74
+ /** Everyone `@` can offer, asked as the query changes. */
75
+ people: () => readonly MentionPerson[]
76
+ /** The `nostr:npub…` a person is written as; `null` for someone without one, who is not offered. */
77
+ uriOf: (person: MentionPerson) => string | null
78
+ }
79
+
80
+ export interface DocumentEditorProps {
81
+ /** The saved text. A new value while the editor is open is somebody else's save, or your own coming back. */
82
+ value: string
83
+ /** The format `value` is in, handed to `codec.read`. */
84
+ format: string
85
+ codec: DocumentCodec
86
+ /**
87
+ * Save. Called when you leave, never while typing, with the text, its format,
88
+ * and the saved text this edit started from — so the app can tell whom the
89
+ * save names anew. Answer whether it was saved.
90
+ */
91
+ onCommit: (value: string, contentFormat: string | undefined, editedFrom: string) => Promise<boolean> | boolean
92
+ /** The editor's accessible name. */
93
+ label: string
94
+ /** Muted words over an empty editor. */
95
+ placeholder?: ReactNode
96
+ /** For reading: nothing is typed or saved; chips open, and comments on a selection work when on. */
97
+ readOnly?: boolean
98
+ /** Who saved the text last, when it was not you: named in "… saved a newer version". */
99
+ changedBy?: { name: string } | null
100
+ /** A save refused after the editor closed, with nothing left on screen to say it. */
101
+ onLeftUnsaved?: () => void
102
+ /** Where text typed when the sign-in ends is held, under `holdKey`. */
103
+ hold?: HeldTyping
104
+ holdKey?: string
105
+ /** `[` and `/` → *Link to a file*. */
106
+ references?: DocumentReferences
107
+ /** `@`. */
108
+ mentions?: DocumentMentions
109
+ /** A pasted app URL drawn as the chip of what it names (`LinkChips`). */
110
+ linkChips?: LinkChipsOptions
111
+ /** `/` → File, and a pasted picture: upload one file and answer the attachment's attributes (its `imeta` fields). */
112
+ upload?: (file: File) => Promise<Record<string, unknown>>
113
+ /** Plain text pasted as the blocks it spells: the app's reader of markdown, as the editor's document. */
114
+ readMarkdown?: (text: string) => JSONContent | undefined
115
+ /** `/` → Table. Default on. */
116
+ table?: boolean
117
+ /** Comment on what is selected: the selection strip's Comment, and the comment highlights. Without it, neither. */
118
+ onCommentOnSelection?: (anchor: SelectionAnchor) => void
119
+ /** The app's rows in a block's handle menu, after the editing ones: Copy link, Comment. */
120
+ blockRows?: (block: HandleBlock) => ReactNode
121
+ /** Draws a chip: the app's own, which resolves what it names. */
122
+ referenceView?: ComponentType<ReferenceViewProps>
123
+ /** Draws a placed file: the app's own card. */
124
+ 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
+ /** Around everything the editor draws: the app's providers, which may read the editor. */
128
+ wrap?: (children: ReactNode, editor: Editor | null) => ReactNode
129
+ /** The editor, once it is there, and `null` as it goes. */
130
+ onEditor?: (editor: Editor | null) => void
131
+ /** More of the app's own extensions. */
132
+ extensions?: readonly AnyExtension[]
133
+ }
134
+
135
+ /** The editor's own document held for this place when the sign-in ended, block ids and all; `null` when none. */
136
+ function heldDocument(hold: HeldTyping | undefined, key: string | undefined): JSONContent | null {
137
+ const text = hold && key ? hold.text(key) : undefined
138
+ if (!text) return null
139
+ try {
140
+ const doc = JSON.parse(text) as JSONContent
141
+ return doc?.type === 'doc' ? doc : null
142
+ } catch {
143
+ return null
144
+ }
145
+ }
146
+
147
+ /**
148
+ * One document's text as one surface that is always an editor — Leaf's page,
149
+ * Ship's description and Peek's panel, which each had their own until this.
150
+ * Every app's document can do the same things, wherever it is written.
151
+ *
152
+ * - **Saves when you leave:** on blur, on unmount and on a checklist tick.
153
+ * Never while typing. Escape leaves and keeps the text. A refused save keeps
154
+ * the text and says so; one refused after the editor closed goes to
155
+ * `onLeftUnsaved`.
156
+ * - **Someone else's save arrives** while you are not in it: it is loaded.
157
+ * While you are in it, it waits, and a line says who saved a newer version,
158
+ * with "Load it"; leaving with a change saves yours over it — the later save
159
+ * wins (Miky, LEAF-3's kickoff and 13 October). Your own save coming back is
160
+ * never mistaken for someone else's.
161
+ * - **The sign-in ending** holds what was typed (`hold`), and the editor opens
162
+ * with it, unsaved, after the passkey tap.
163
+ *
164
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/every-app-edits-a-document-with-one-shared-editor.md
165
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/the-block-editor-kit-lives-in-protocol-and-ui.md
166
+ */
167
+ export function DocumentEditor({
168
+ value,
169
+ format,
170
+ codec,
171
+ onCommit,
172
+ label,
173
+ placeholder,
174
+ readOnly = false,
175
+ changedBy = null,
176
+ onLeftUnsaved,
177
+ hold,
178
+ holdKey,
179
+ references,
180
+ mentions,
181
+ linkChips,
182
+ upload,
183
+ readMarkdown,
184
+ table = true,
185
+ onCommentOnSelection,
186
+ blockRows,
187
+ referenceView,
188
+ attachmentView,
189
+ cards,
190
+ wrap,
191
+ onEditor,
192
+ extensions = [],
193
+ }: DocumentEditorProps) {
194
+ const [failed, setFailed] = useState(false)
195
+ const [focused, setFocused] = useState(false)
196
+ const [uploadError, setUploadError] = useState<string | null>(null)
197
+ // The latest props, for the editor's callbacks, which are made once.
198
+ const latest = useRef({ value, format, codec, hold, references, mentions, upload, readMarkdown, onLeftUnsaved })
199
+ useEffect(() => {
200
+ latest.current = { value, format, codec, hold, references, mentions, upload, readMarkdown, onLeftUnsaved }
201
+ })
202
+ const ended = () => latest.current.hold?.ended() ?? false
203
+ /*
204
+ The text the editor holds as saved or loaded. A value that differs is
205
+ someone else's save: loaded at once while you are not in it, waiting with a
206
+ line while you are. `saved` is the same, for the editor's callbacks.
207
+ */
208
+ const [base, setBase] = useState(value)
209
+ const saved = useRef(value)
210
+ // The value your own save replaced: until your save comes back, the value still holds it, and it is not someone else's.
211
+ const [superseded, setSuperseded] = useState<string | null>(null)
212
+ // Every text your own saves wrote since someone else's last loaded: an echo of an earlier one can arrive after a later save.
213
+ const own = useRef(new Set<string>())
214
+ // A save out: nothing is loaded over the text it carries until it is answered.
215
+ const [saving, setSaving] = useState(false)
216
+ const committing = useRef(false)
217
+ // What was typed here when the sign-in last ended, back after the passkey tap and not yet saved.
218
+ // Not when it is what the value already holds (a save out as the sign-in ended went through), or nothing would
219
+ // ever take later changes: only a save clears `restored`, and a save of what is saved sends nothing.
220
+ const [held] = useState(() => {
221
+ const doc = heldDocument(hold, holdKey)
222
+ // A held document the codec cannot write (another version's, or cut short) is not text anyone can keep.
223
+ try {
224
+ return doc && codec.write(doc).value !== value ? doc : null
225
+ } catch {
226
+ return null
227
+ }
228
+ })
229
+ // Until it is saved it is your unsaved text: someone else's save waits behind it, as behind a refused one.
230
+ const [restored, setRestored] = useState(held !== null)
231
+ // The text as last typed. Saving on the way out reads this, not the editor, which may already be torn down.
232
+ const typed = useRef<JSONContent | null>(held)
233
+ const again = useRef(false)
234
+ const left = useRef(false)
235
+ /*
236
+ True from the moment the file dialog is asked for until the window has focus
237
+ again: the dialog takes focus, and that blur must not save and leave.
238
+ */
239
+ const picking = useRef(false)
240
+ const picker = useRef<HTMLInputElement>(null)
241
+
242
+ const save = useCallback(
243
+ async (doc: JSONContent | null) => {
244
+ // Read only: a box ticked in a node view is not a save. After an ending the text is held, and a save would be refused.
245
+ if (!doc || readOnly || ended()) return
246
+ // A change made while a save is out goes next, not nowhere.
247
+ if (committing.current) {
248
+ again.current = true
249
+ return
250
+ }
251
+ const next = latest.current.codec.write(doc)
252
+ if (next.value === saved.current) return
253
+ committing.current = true
254
+ setSaving(true)
255
+ // The later save wins: whatever the value holds as you save is replaced by yours.
256
+ const replaced = latest.current.value
257
+ const editedFrom = saved.current
258
+ try {
259
+ const ok = await onCommit(next.value, next.contentFormat, editedFrom)
260
+ if (ok) {
261
+ // The editor already shows it, and may hold more typed since: `shown` keeps the effect below from setting it.
262
+ saved.current = next.value
263
+ shown.current = next.value
264
+ own.current.add(next.value)
265
+ setSuperseded(replaced)
266
+ setBase(next.value)
267
+ setRestored(false)
268
+ // A save out as the sign-in ended: what was held then may hold more than this, typed since.
269
+ const store = latest.current.hold
270
+ if (store && holdKey && !store.ended()) store.release(holdKey)
271
+ }
272
+ if (left.current) {
273
+ // Refused because the sign-in ended: the text is held for after the tap, not lost.
274
+ if (!ok && !ended()) latest.current.onLeftUnsaved?.()
275
+ } else setFailed(!ok)
276
+ } catch {
277
+ // A save that throws is a refusal: the text stays, and says so.
278
+ if (left.current) {
279
+ if (!ended()) latest.current.onLeftUnsaved?.()
280
+ } else setFailed(true)
281
+ } finally {
282
+ committing.current = false
283
+ setSaving(false)
284
+ if (again.current) {
285
+ again.current = false
286
+ // After an ending it is held for after the tap, and a save would only be refused.
287
+ if (!ended()) void latestSave.current(typed.current)
288
+ }
289
+ }
290
+ },
291
+ [onCommit, holdKey, readOnly],
292
+ )
293
+
294
+ // While open, an ending reads the unsaved text. Keyed on the key and on there being a store, not on the store object:
295
+ // a new `hold` each render must not unregister, since the app's unregister forgets what was held unless an ending is under way.
296
+ const holds = !!hold
297
+ useEffect(() => {
298
+ const store = latest.current.hold
299
+ if (!holds || !store || !holdKey) return
300
+ return store.register(holdKey, () => {
301
+ const doc = typed.current
302
+ return doc && latest.current.codec.write(doc).value !== saved.current ? JSON.stringify(doc) : undefined
303
+ })
304
+ }, [holdKey, holds])
305
+
306
+ // The latest `save`, for the editor's `onBlur` (made once) and the unmount below.
307
+ const latestSave = useRef(save)
308
+ useEffect(() => {
309
+ latestSave.current = save
310
+ }, [save])
311
+ // The text the editor was last set to, so a `base` it already shows is not set again under the caret.
312
+ const shown = useRef(value)
313
+
314
+ const openPicker = () => {
315
+ picking.current = true
316
+ const released = () => {
317
+ picking.current = false
318
+ window.removeEventListener('focus', released)
319
+ }
320
+ window.addEventListener('focus', released)
321
+ picker.current?.click()
322
+ }
323
+ const pickFile = useRef(openPicker)
324
+ pickFile.current = openPicker
325
+
326
+ /* `/` File and a pasted picture: the upload first, then the block — its attributes are the upload's answer. */
327
+ const attach = async (chosen: File[]) => {
328
+ const uploadOne = latest.current.upload
329
+ if (!uploadOne) return
330
+ setUploadError(null)
331
+ try {
332
+ for (const file of chosen) {
333
+ const attrs = await uploadOne(file)
334
+ if (!editor || editor.isDestroyed) return
335
+ editor.chain().focus().insertContent({ type: 'attachment', attrs }).run()
336
+ }
337
+ } catch (error) {
338
+ setUploadError(error instanceof Error ? error.message : String(error))
339
+ }
340
+ }
341
+ const attachTo = useRef(attach)
342
+ attachTo.current = attach
343
+
344
+ const editor = useEditor(
345
+ {
346
+ extensions: [
347
+ DocumentKit.configure({
348
+ strike: false,
349
+ heading: { levels: [1, 2, 3] },
350
+ dropcursor: blockDropCursor,
351
+ codeBlock: false,
352
+ // A link on words is made by pasting a URL over them or by the strip's Link, and opens on a click, as a bare
353
+ // address does — through `BareLinks`, which opens only a followable address and never hands the tab this window;
354
+ // Tiptap's own click opens without that. A bare address stays text: a link made on it by typing would change what is saved.
355
+ link: { openOnClick: false, shouldAutoLink: () => false, HTMLAttributes: LINK_MARK_ATTRIBUTES },
356
+ }),
357
+ PasteOverWords,
358
+ KeptSelection,
359
+ BareLinks,
360
+ CodeBlockColours,
361
+ TableKit.configure({ table: { resizable: false } }),
362
+ BlockId,
363
+ Checklist,
364
+ Callout,
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.
369
+ ReferenceMenu,
370
+ UnknownBlock,
371
+ AttachmentNode.configure({ view: attachmentView ?? null }),
372
+ SlashCommands.configure({ sections: slashSections({ table, file: !!upload, link: !!references, pickFile }) }),
373
+ ...(references
374
+ ? [
375
+ ReferenceTrigger.configure({
376
+ items: () => [],
377
+ sections: (query) => latest.current.references?.sections(query) ?? [],
378
+ subscribe: (listener) => latest.current.references?.subscribe?.(listener) ?? (() => {}),
379
+ nodeName: 'reference',
380
+ ariaLabel: references.ariaLabel,
381
+ sectionLabel: references.sectionLabel,
382
+ icon: references.icon ?? null,
383
+ }),
384
+ ]
385
+ : []),
386
+ ...(mentions
387
+ ? [PersonReference.configure({ people: () => latest.current.mentions?.people() ?? [], uriOf: (person) => latest.current.mentions?.uriOf(person) ?? null })]
388
+ : []),
389
+ ...(linkChips ? [LinkChips.configure(linkChips)] : []),
390
+ ...(upload
391
+ ? [
392
+ // A pasted picture is placed as `/` File places one; text on the clipboard stays text.
393
+ PastedImages.configure({
394
+ onImages: (pasted) => {
395
+ if (!latest.current.upload) return false
396
+ void attachTo.current(pasted)
397
+ return true
398
+ },
399
+ }),
400
+ ]
401
+ : []),
402
+ // Markdown pasted as plain text lands as the blocks it spells, tables included.
403
+ ...(readMarkdown ? [PastedMarkdown.configure({ read: (text) => latest.current.readMarkdown?.(text) })] : []),
404
+ // Where each comment is, drawn as a decoration, so a save never carries it.
405
+ ...(onCommentOnSelection ? [CommentHighlights] : []),
406
+ ...extensions,
407
+ ],
408
+ // Made once. A value coming back must not rebuild the editor under the caret; see the effect below.
409
+ content: held ?? codec.read(value, format),
410
+ editable: !readOnly,
411
+ editorProps: {
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') },
414
+ handleKeyDown: (view, event) => {
415
+ if (event.key !== 'Escape') return false
416
+ // An open list or chip menu closes first; the next Escape leaves.
417
+ if (isSuggestionOpen() || isReferenceMenuOpen(view.state)) return false
418
+ const { selection, tr } = view.state
419
+ // Words selected: the first Escape lets go of them, which also closes the strip.
420
+ if (!selection.empty) {
421
+ view.dispatch(tr.setSelection(TextSelection.create(tr.doc, selection.to)))
422
+ return true
423
+ }
424
+ view.dom.blur()
425
+ return true
426
+ },
427
+ },
428
+ onUpdate: ({ editor: e, transaction }) => {
429
+ typed.current = e.getJSON()
430
+ // A click on a box does not focus the field, so no blur will save it.
431
+ if (isChecklistTick(transaction)) void latestSave.current(typed.current)
432
+ },
433
+ onFocus: () => setFocused(true),
434
+ onBlur: () => {
435
+ setFocused(false)
436
+ // The file dialog took focus: the person has not left.
437
+ if (picking.current) return
438
+ // Yours, if you changed anything: it replaces what waited. If not, what waited is loaded as you leave (below).
439
+ void latestSave.current(typed.current)
440
+ },
441
+ },
442
+ [],
443
+ )
444
+
445
+ /*
446
+ Someone else's save. Not in the editor: theirs is the text now. In it, or
447
+ with your own text unsaved after a refusal or an ending: it waits, and the
448
+ line below says so. Never over a save that is still out.
449
+ */
450
+ const arrived = value !== base && value !== superseded && !own.current.has(value)
451
+ // Read only, there is nothing of yours to keep: theirs loads even while you select words to comment on.
452
+ if (arrived && (readOnly || (!focused && !saving && !failed && !restored))) {
453
+ own.current.clear()
454
+ setBase(value)
455
+ }
456
+ const waiting = arrived && !readOnly && (focused || failed || restored)
457
+
458
+ // The text the editor should hold, set into it when it changes — never under your own typing, which `shown` already holds.
459
+ useEffect(() => {
460
+ saved.current = base
461
+ if (!editor || editor.isDestroyed || base === shown.current) return
462
+ editor.commands.setContent(latest.current.codec.read(base, latest.current.format), { emitUpdate: false })
463
+ shown.current = base
464
+ typed.current = null
465
+ }, [editor, base])
466
+
467
+ // Made read only or editable while open: the editor follows, without being made again.
468
+ useEffect(() => {
469
+ if (editor && !editor.isDestroyed && editor.isEditable === readOnly) editor.setEditable(!readOnly, false)
470
+ }, [editor, readOnly])
471
+
472
+ const empty = useEditorState({ editor, selector: ({ editor: ed }) => !ed || ed.isEmpty })
473
+
474
+ // "Load it": theirs replaces what you have not saved.
475
+ const load = () => {
476
+ setBase(latest.current.value)
477
+ setFailed(false)
478
+ setRestored(false)
479
+ }
480
+
481
+ // Closing saves on the way out. Not when the sign-in ended: the save would be refused and reported as lost over
482
+ // the passkey screen, and the text is held on the device instead.
483
+ useEffect(
484
+ () => () => {
485
+ left.current = true
486
+ if (!ended()) void latestSave.current(typed.current)
487
+ },
488
+ [],
489
+ )
490
+
491
+ useEffect(() => {
492
+ onEditor?.(editor)
493
+ return () => onEditor?.(null)
494
+ }, [editor, onEditor])
495
+
496
+ const who = changedBy?.name ?? 'Someone'
497
+ const drawn = (
498
+ <div className="flex flex-col gap-1">
499
+ <EditorBlockHandle editor={editor} actions={blockRows}>
500
+ {/* A table's handles and ➕ bars while you point at it; the block handle stays the table's. */}
501
+ <EditorTableControls editor={editor}>
502
+ <EditorContent editor={editor} className="-mx-2 cursor-text px-2 py-1" data-document-editor="" />
503
+ </EditorTableControls>
504
+ {empty && !readOnly && placeholder && (
505
+ <span aria-hidden className="pointer-events-none absolute left-0 top-1 text-body-2 text-text-muted">
506
+ {placeholder}
507
+ </span>
508
+ )}
509
+ </EditorBlockHandle>
510
+ {cards?.(editor)}
511
+ {/* Read only with comments off, the strip would have nothing in it: no strip. */}
512
+ {(!readOnly || onCommentOnSelection) && <SelectionToolbar
513
+ editor={editor}
514
+ marks={readOnly ? [] : ['bold', 'italic', 'underline', 'code']}
515
+ link={!readOnly}
516
+ actions={
517
+ onCommentOnSelection
518
+ ? [
519
+ {
520
+ label: 'Comment',
521
+ icon: <IconMessagePlus size={16} stroke={1.5} />,
522
+ run: (ed) => {
523
+ const anchor = anchorOfSelection(ed)
524
+ if (!anchor) return
525
+ // The draft's highlight keeps what is selected marked; the selection itself can go.
526
+ ed.commands.setTextSelection(ed.state.selection.to)
527
+ onCommentOnSelection(anchor)
528
+ },
529
+ },
530
+ ]
531
+ : []
532
+ }
533
+ />}
534
+ <ReferenceMenuView editor={editor} />
535
+ {/* Always there, so `/` → File, made as the editor opened, has a dialog to open even if `upload` came and went. */}
536
+ <FilePicker ref={picker} multiple onPick={(files) => void attach(files)} />
537
+ {waiting && (
538
+ <FieldLine tone="helper">
539
+ {`${who} saved a newer version.`}{' '}
540
+ {/* Pressing it must not take focus from the editor: that blur would save yours over theirs first. */}
541
+ <Button variant="muted" size="small" onMouseDown={(event) => event.preventDefault()} onClick={load}>
542
+ Load it
543
+ </Button>{' '}
544
+ {/* What Load it costs, said where it is pressed (Miky, WBD-3's /land, 20 October). */}
545
+ (replaces your changes)
546
+ </FieldLine>
547
+ )}
548
+ {uploadError && <FieldLine tone="error">{uploadError}</FieldLine>}
549
+ {failed && <FieldLine tone="error">Could not save. Your text is still here.</FieldLine>}
550
+ </div>
551
+ )
552
+ return <>{wrap ? wrap(drawn, editor) : drawn}</>
553
+ }
554
+
555
+ /**
556
+ * `/`: the shared Format section with a document's checklist and callouts,
557
+ * then Insert with what this editor can do. *Link to a file* types `[`, so its
558
+ * list opens (Miky's QA note, 15 October).
559
+ */
560
+ function slashSections({ table, file, link, pickFile }: { table: boolean; file: boolean; link: boolean; pickFile: { current: () => void } }): SlashSection[] {
561
+ const insert: SlashCommand[] = [
562
+ // Three by three with a header row, as every app's Insert → Table makes it.
563
+ ...(table ? [{ key: 'insert-table', row: { label: 'Table' }, run: (editor: Editor) => void editor.chain().focus().insertTable({ rows: 3, cols: 3, withHeaderRow: true }).run() }] : []),
564
+ ...(file ? [{ key: 'insert-file', row: { label: 'File' }, keywords: ['attach', 'upload'], run: () => pickFile.current() }] : []),
565
+ ...(link ? [{ key: 'insert-link', row: { label: 'Link to a file', shortcut: '[' }, keywords: ['[', 'link', 'reference'], run: typeTrigger('[') }] : []),
566
+ ]
567
+ return [formatSection('block'), ...(insert.length > 0 ? [{ label: 'Insert', commands: insert }] : [])]
568
+ }
@@ -22,7 +22,12 @@
22
22
  * on, and `ReferenceMenuView` draws it beside `EditorContent`. Pair them with
23
23
  * `ReferenceNode` and `ReferenceCards`.
24
24
  *
25
- * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/clicking-a-chip-while-editing-opens-a-menu.md
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.
29
+ *
30
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-lone-links-chip-menu-offers-row-or-card.md
26
31
  */
27
32
  import { useCallback } from 'react'
28
33
  import { Extension, type Editor } from '@tiptap/core'
@@ -505,7 +505,8 @@ export function SelectionToolbar({ editor, marks = ['bold', 'italic', 'underline
505
505
  </ToolbarButton>
506
506
  )}
507
507
  {children}
508
- {actions.length > 0 && <ToolbarSeparator />}
508
+ {/* Between the marks and the app's buttons: with no mark or Link before them (read only), nothing to part. */}
509
+ {actions.length > 0 && (marks.length > 0 || link || children) && <ToolbarSeparator />}
509
510
  {actions.map((action) => (
510
511
  <ToolbarButton
511
512
  key={action.label}
package/src/editor.ts CHANGED
@@ -17,6 +17,9 @@ export {
17
17
  type CommentBoxEdit,
18
18
  type BoxFile,
19
19
  type BoxFileState,
20
+ type BoxUnder,
21
+ type BoxUnderRead,
22
+ type BoxSentUnder,
20
23
  type SendAnswer,
21
24
  type UploadAnswer,
22
25
  } from './CommentBox'
@@ -57,6 +60,7 @@ export { EditorTableControls, appendTableRow, appendTableColumn, deleteTableRow,
57
60
  export {
58
61
  PersonMention,
59
62
  UrgentPersonMention,
63
+ PersonReference,
60
64
  CaptionedReference,
61
65
  ReferenceTrigger,
62
66
  SlashCommands,
@@ -72,6 +76,7 @@ export {
72
76
  FORMATS,
73
77
  type MentionPerson,
74
78
  type PersonMentionOptions,
79
+ type PersonReferenceOptions,
75
80
  type CaptionedItem,
76
81
  type CaptionedReferenceOptions,
77
82
  type ReferenceTriggerOptions,
@@ -109,3 +114,11 @@ export {
109
114
  } from './ReferenceCards'
110
115
  export { LinkChips, findLinkChips, refreshLinkChips, type LinkChipsOptions, type PastedRange } from './LinkChips'
111
116
  export { ReferenceMenu, ReferenceMenuView, isReferenceMenuOpen, referenceMenuClick, type ReferenceMenuViewProps } from './ReferenceMenu'
117
+ export {
118
+ DocumentEditor,
119
+ type DocumentEditorProps,
120
+ type DocumentCodec,
121
+ type DocumentReferences,
122
+ type DocumentMentions,
123
+ type HeldTyping,
124
+ } from './DocumentEditor'
@@ -107,8 +107,10 @@ describe('create-estiva-app', () => {
107
107
  })
108
108
 
109
109
  it('bakes in protocol, platform and interop', () => {
110
+ const own = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'))
110
111
  const made = JSON.parse(files['package.json'])
111
- expect(made.dependencies['@estiva-app/protocol']).toBe('^0.21.0')
112
+ // Protocol is this package's own (its document editor's stories and tests), so its range is the one made apps get.
113
+ expect(made.dependencies['@estiva-app/protocol']).toBe(own.devDependencies['@estiva-app/protocol'])
112
114
  expect(made.dependencies['@estiva-app/platform']).toBe('^0.1.0')
113
115
  expect(made.dependencies['@estiva-app/interop']).toBe('^0.23.0')
114
116
  })