@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.
- package/dist/BlockNodes.d.ts.map +1 -1
- package/dist/CardUnder.d.ts +24 -3
- package/dist/CardUnder.d.ts.map +1 -1
- package/dist/CommentBox.d.ts +39 -5
- package/dist/CommentBox.d.ts.map +1 -1
- package/dist/ComposerTriggers.d.ts +24 -0
- package/dist/ComposerTriggers.d.ts.map +1 -1
- package/dist/DocumentEditor.d.ts +138 -0
- package/dist/DocumentEditor.d.ts.map +1 -0
- package/dist/ReferenceMenu.d.ts.map +1 -1
- package/dist/SelectionToolbar.d.ts.map +1 -1
- package/dist/editor.d.ts +3 -2
- package/dist/editor.d.ts.map +1 -1
- package/dist/editor.js +565 -46
- package/dist/editor.js.map +4 -4
- package/dist/index.js +2 -2
- package/dist/index.js.map +2 -2
- package/dist/links.d.ts +28 -0
- package/dist/links.d.ts.map +1 -0
- package/package.json +7 -1
- package/registry.json +199 -10
- package/src/BlockNodes.tsx +3 -1
- package/src/CardUnder.mdx +1 -0
- package/src/CardUnder.tsx +10 -6
- package/src/CommentBox.mdx +8 -0
- package/src/CommentBox.stories.tsx +62 -2
- package/src/CommentBox.test.tsx +169 -1
- package/src/CommentBox.tsx +110 -17
- package/src/ComposerTriggers.tsx +65 -0
- package/src/DocumentEditor.mdx +106 -0
- package/src/DocumentEditor.stories.tsx +305 -0
- package/src/DocumentEditor.test.tsx +528 -0
- package/src/DocumentEditor.tsx +568 -0
- package/src/ReferenceMenu.tsx +6 -1
- package/src/SelectionToolbar.tsx +2 -1
- package/src/editor.ts +13 -0
- package/src/gates/create-app.test.ts +3 -1
- package/src/links.ts +151 -0
- package/src/registry/registry.test.ts +6 -6
- package/stories/Choosing.mdx +1 -0
package/src/CommentBox.tsx
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
|
-
import { useCallback, useEffect, useRef, useState, type ComponentType, type DragEvent, type ReactNode } from 'react'
|
|
1
|
+
import { Fragment, useCallback, useEffect, useRef, useState, type ComponentType, type DragEvent, type ReactNode } from 'react'
|
|
2
2
|
import { Extension, type AnyExtension } from '@tiptap/core'
|
|
3
3
|
import { EditorContent, useEditor, type Editor, type JSONContent } from '@tiptap/react'
|
|
4
|
-
import StarterKit from '@tiptap/starter-kit'
|
|
5
4
|
import { IconLock, IconPaperclip, IconSquareRounded } from '@tabler/icons-react'
|
|
6
5
|
import { AttachmentCard } from './AttachmentCard'
|
|
7
6
|
import { ReferenceNode, type ReferenceViewProps } from './BlockNodes'
|
|
8
7
|
import { Button } from './Button'
|
|
9
8
|
import { Card } from './Card'
|
|
9
|
+
import { CardUnder } from './CardUnder'
|
|
10
10
|
import { cn } from './cn'
|
|
11
11
|
import { ComposeBox, ComposeKeys, COMPOSE_EDITOR_CLASSES, isEmptyDoc as isEmpty } from './ComposeBox'
|
|
12
12
|
import {
|
|
@@ -26,6 +26,7 @@ import {
|
|
|
26
26
|
import { FieldLine } from './Field'
|
|
27
27
|
import { FilePicker } from './FilePicker'
|
|
28
28
|
import { Kbd } from './Kbd'
|
|
29
|
+
import { BoxKit, PasteOverWords } from './links'
|
|
29
30
|
import { WRITING_BOX_CLASSES } from './looks'
|
|
30
31
|
import { PastedImages } from './PastedImages'
|
|
31
32
|
import { KeptSelection } from './SelectionToolbar'
|
|
@@ -84,7 +85,36 @@ export interface CommentBoxEdit {
|
|
|
84
85
|
files?: BoxFile[]
|
|
85
86
|
onCancel: () => void
|
|
86
87
|
/** Save; the box holds the words until the answer, and a refusal is said under it. */
|
|
87
|
-
onSave: (body: JSONContent, files: BoxFile[]) => Promise<SendAnswer>
|
|
88
|
+
onSave: (body: JSONContent, files: BoxFile[], under: BoxSentUnder) => Promise<SendAnswer>
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/**
|
|
92
|
+
* What a draft shows under the box, as the app reads it from the box's
|
|
93
|
+
* document — `@estiva-app/conversation`'s `boxReadOf`, which reads it as the
|
|
94
|
+
* message will be sent (why:
|
|
95
|
+
* https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-link-on-words-counts-toward-the-card.md).
|
|
96
|
+
*/
|
|
97
|
+
export interface BoxUnderRead {
|
|
98
|
+
/** The one card, before any ✕: what it names, and the app's own view of it, drawn as it draws a sent one. */
|
|
99
|
+
card?: { value: string; view: ReactNode }
|
|
100
|
+
/** The live parts, drawn as the app draws them under a sent message. An edit carries none, so the edit box shows none. */
|
|
101
|
+
parts?: readonly { key: string; view: ReactNode }[]
|
|
102
|
+
/** Everything the draft names. A ✕ is forgotten once what it took off is no longer named, so a link put back gets its card again. */
|
|
103
|
+
names: readonly string[]
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/** What the box shows under itself while something is written. */
|
|
107
|
+
export interface BoxUnder {
|
|
108
|
+
/** Read on every change, and once more as it is sent. */
|
|
109
|
+
read: (body: JSONContent) => BoxUnderRead
|
|
110
|
+
/** Called with a listener; call it when `read` would answer differently (what a link names came back). */
|
|
111
|
+
changed?: (listener: () => void) => () => void
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/** What was under the box as it was sent or saved. */
|
|
115
|
+
export interface BoxSentUnder {
|
|
116
|
+
/** The card still shown, by what it names: absent when there was none, or ✕ took it off. */
|
|
117
|
+
card?: string
|
|
88
118
|
}
|
|
89
119
|
|
|
90
120
|
export interface CommentBoxProps {
|
|
@@ -100,8 +130,10 @@ export interface CommentBoxProps {
|
|
|
100
130
|
insert?: readonly SlashCommand[]
|
|
101
131
|
/** `/` → Code: a mark inside the line, or a block. */
|
|
102
132
|
code?: CodeFormat
|
|
103
|
-
/** Send what is written, with the files that are ready; resolves with the relay's answer. */
|
|
104
|
-
send: (body: JSONContent, files: BoxFile[]) => Promise<SendAnswer>
|
|
133
|
+
/** Send what is written, with the files that are ready and the card still shown; resolves with the relay's answer. */
|
|
134
|
+
send: (body: JSONContent, files: BoxFile[], under: BoxSentUnder) => Promise<SendAnswer>
|
|
135
|
+
/** The card and parts under the box while something is written, with ✕ on the card. Absent, nothing shows under it. */
|
|
136
|
+
under?: BoxUnder
|
|
105
137
|
/**
|
|
106
138
|
* The app shows a send before the relay answers: the box empties at once,
|
|
107
139
|
* and a refusal puts the words back. Otherwise the box holds the words, shut,
|
|
@@ -128,7 +160,7 @@ export interface CommentBoxProps {
|
|
|
128
160
|
extensions?: readonly AnyExtension[]
|
|
129
161
|
autoFocus?: boolean
|
|
130
162
|
/** Called with what was sent once it went out: at once when `showsAtOnce`, else on the answer. */
|
|
131
|
-
onSent?: (body: JSONContent, files: BoxFile[]) => void
|
|
163
|
+
onSent?: (body: JSONContent, files: BoxFile[], under: BoxSentUnder) => void
|
|
132
164
|
/** Called when a send shown at once was refused, so the app takes it back. */
|
|
133
165
|
onRefused?: () => void
|
|
134
166
|
className?: string
|
|
@@ -165,6 +197,10 @@ const BoxKeys = Extension.create<{ onEscape: () => boolean }>({
|
|
|
165
197
|
},
|
|
166
198
|
})
|
|
167
199
|
|
|
200
|
+
/** What `removed` still holds of what the draft names; the same set when nothing was forgotten. */
|
|
201
|
+
const stillNamed = (removed: ReadonlySet<string>, names: readonly string[]): ReadonlySet<string> =>
|
|
202
|
+
[...removed].every((value) => names.includes(value)) ? removed : new Set([...removed].filter((value) => names.includes(value)))
|
|
203
|
+
|
|
168
204
|
const SQUARE = <IconSquareRounded size={16} stroke={1.5} className="text-text-secondary" />
|
|
169
205
|
const SMALL_SQUARE = <IconSquareRounded size={14} stroke={1.5} />
|
|
170
206
|
|
|
@@ -178,6 +214,7 @@ export function CommentBox({
|
|
|
178
214
|
insert = [],
|
|
179
215
|
code = 'block',
|
|
180
216
|
send,
|
|
217
|
+
under,
|
|
181
218
|
showsAtOnce = false,
|
|
182
219
|
label,
|
|
183
220
|
placeholder,
|
|
@@ -196,11 +233,14 @@ export function CommentBox({
|
|
|
196
233
|
const [files, setFiles] = useState<BoxFile[]>(edit?.files ?? [])
|
|
197
234
|
const [sending, setSending] = useState(false)
|
|
198
235
|
const [refused, setRefused] = useState<string | null>(null)
|
|
236
|
+
// What shows under the box, and what ✕ took off.
|
|
237
|
+
const [reading, setReading] = useState<BoxUnderRead | undefined>(undefined)
|
|
238
|
+
const [removed, setRemoved] = useState<ReadonlySet<string>>(() => new Set())
|
|
199
239
|
const picker = useRef<HTMLInputElement>(null)
|
|
200
240
|
const root = useRef<HTMLDivElement>(null)
|
|
201
241
|
// The latest props, for the editor's callbacks, which are made once.
|
|
202
|
-
const latest = useRef({ edit, people, references, referencesChanged, referenceIcon, upload, draft })
|
|
203
|
-
latest.current = { edit, people, references, referencesChanged, referenceIcon, upload, draft }
|
|
242
|
+
const latest = useRef({ edit, people, references, referencesChanged, referenceIcon, upload, draft, under })
|
|
243
|
+
latest.current = { edit, people, references, referencesChanged, referenceIcon, upload, draft, under }
|
|
204
244
|
const save = useRef<() => boolean>(() => false)
|
|
205
245
|
|
|
206
246
|
const attachFiles = useCallback((picked: File[]): boolean => {
|
|
@@ -231,7 +271,8 @@ export function CommentBox({
|
|
|
231
271
|
|
|
232
272
|
const editor = useEditor({
|
|
233
273
|
extensions: [
|
|
234
|
-
|
|
274
|
+
BoxKit.configure({ link: { openOnClick: false } }),
|
|
275
|
+
PasteOverWords,
|
|
235
276
|
KeptSelection,
|
|
236
277
|
ComposeKeys,
|
|
237
278
|
BoxKeys.configure({
|
|
@@ -285,6 +326,36 @@ export function CommentBox({
|
|
|
285
326
|
}
|
|
286
327
|
}, [editor, edit])
|
|
287
328
|
|
|
329
|
+
// What shows under the box, read on every change and whenever the app's answers change.
|
|
330
|
+
const reads = !!under
|
|
331
|
+
useEffect(() => {
|
|
332
|
+
if (!editor || !reads) {
|
|
333
|
+
setReading(undefined)
|
|
334
|
+
return
|
|
335
|
+
}
|
|
336
|
+
const read = () => {
|
|
337
|
+
const now = latest.current.under?.read(editor.getJSON())
|
|
338
|
+
setReading(now)
|
|
339
|
+
setRemoved((was) => stillNamed(was, now?.names ?? []))
|
|
340
|
+
}
|
|
341
|
+
read()
|
|
342
|
+
editor.on('update', read)
|
|
343
|
+
const unsubscribe = latest.current.under?.changed?.(read)
|
|
344
|
+
return () => {
|
|
345
|
+
editor.off('update', read)
|
|
346
|
+
unsubscribe?.()
|
|
347
|
+
}
|
|
348
|
+
}, [editor, reads])
|
|
349
|
+
|
|
350
|
+
// What goes with a send or a save: read from what is sent, minus what ✕ took off.
|
|
351
|
+
const underOf = useCallback(
|
|
352
|
+
(body: JSONContent): BoxSentUnder => {
|
|
353
|
+
const card = latest.current.under?.read(body).card?.value
|
|
354
|
+
return card && !removed.has(card) ? { card } : {}
|
|
355
|
+
},
|
|
356
|
+
[removed],
|
|
357
|
+
)
|
|
358
|
+
|
|
288
359
|
useEffect(() => {
|
|
289
360
|
editor?.setEditable(!closed && !sending)
|
|
290
361
|
}, [editor, closed, sending])
|
|
@@ -314,14 +385,17 @@ export function CommentBox({
|
|
|
314
385
|
(ed: Editor): boolean => {
|
|
315
386
|
const body = ed.getJSON()
|
|
316
387
|
const sent = files.filter((f) => f.state === 'ready')
|
|
388
|
+
const sentUnder = underOf(body)
|
|
317
389
|
setRefused(null)
|
|
318
390
|
const answered = (answer: Promise<SendAnswer>) => answer.catch((): SendAnswer => ({ accepted: false, reason: 'try again in a moment' }))
|
|
319
391
|
if (showsAtOnce) {
|
|
320
|
-
// Shown at once: the box empties now (ComposeBox clears it); a refusal puts the words back above anything written since
|
|
392
|
+
// Shown at once: the box empties now (ComposeBox clears it); a refusal puts the words back above anything written since,
|
|
393
|
+
// and what ✕ took off with them.
|
|
394
|
+
const took = removed
|
|
321
395
|
setFiles((all) => all.filter((f) => f.state !== 'ready'))
|
|
322
396
|
draft?.clear()
|
|
323
|
-
onSent?.(body, sent)
|
|
324
|
-
void answered(send(body, sent)).then((answer) => {
|
|
397
|
+
onSent?.(body, sent, sentUnder)
|
|
398
|
+
void answered(send(body, sent, sentUnder)).then((answer) => {
|
|
325
399
|
if (answer.accepted) return
|
|
326
400
|
onRefused?.()
|
|
327
401
|
if (ed.isDestroyed) {
|
|
@@ -332,6 +406,7 @@ export function CommentBox({
|
|
|
332
406
|
if (isEmpty(ed)) ed.commands.setContent(body)
|
|
333
407
|
else ed.commands.insertContentAt(0, body.content ?? [])
|
|
334
408
|
ed.commands.focus('end')
|
|
409
|
+
setRemoved((now) => new Set([...now, ...took]))
|
|
335
410
|
setFiles((all) => [...sent, ...all])
|
|
336
411
|
setRefused(answer.reason)
|
|
337
412
|
})
|
|
@@ -339,28 +414,30 @@ export function CommentBox({
|
|
|
339
414
|
}
|
|
340
415
|
// Held: the words stay, shut, until the relay answers.
|
|
341
416
|
setSending(true)
|
|
342
|
-
void answered(send(body, sent)).then((answer) => {
|
|
417
|
+
void answered(send(body, sent, sentUnder)).then((answer) => {
|
|
343
418
|
setSending(false)
|
|
344
419
|
if (!answer.accepted) {
|
|
345
420
|
setRefused(answer.reason)
|
|
346
421
|
return
|
|
347
422
|
}
|
|
348
423
|
if (!ed.isDestroyed) ed.commands.clearContent(true)
|
|
424
|
+
setRemoved(new Set())
|
|
349
425
|
setFiles((all) => all.filter((f) => !sent.includes(f)))
|
|
350
426
|
draft?.clear()
|
|
351
|
-
onSent?.(body, sent)
|
|
427
|
+
onSent?.(body, sent, sentUnder)
|
|
352
428
|
})
|
|
353
429
|
return false
|
|
354
430
|
},
|
|
355
|
-
[files, showsAtOnce, send, draft, onSent, onRefused],
|
|
431
|
+
[files, removed, underOf, showsAtOnce, send, draft, onSent, onRefused],
|
|
356
432
|
)
|
|
357
433
|
|
|
358
434
|
save.current = () => {
|
|
359
435
|
if (!editor || !edit || sending || uploading) return true
|
|
360
436
|
setRefused(null)
|
|
361
437
|
setSending(true)
|
|
438
|
+
const body = editor.getJSON()
|
|
362
439
|
void edit
|
|
363
|
-
.onSave(
|
|
440
|
+
.onSave(body, files, underOf(body))
|
|
364
441
|
.catch((): SendAnswer => ({ accepted: false, reason: 'try again in a moment' }))
|
|
365
442
|
.then((answer) => {
|
|
366
443
|
setSending(false)
|
|
@@ -407,6 +484,19 @@ export function CommentBox({
|
|
|
407
484
|
</>
|
|
408
485
|
) : undefined
|
|
409
486
|
|
|
487
|
+
// Under the box, outside its border: the card with its ✕, then the live parts (none in an edit, which carries none).
|
|
488
|
+
const card = reading?.card && !removed.has(reading.card.value) ? reading.card : undefined
|
|
489
|
+
const parts = edit ? [] : (reading?.parts ?? [])
|
|
490
|
+
const underBox =
|
|
491
|
+
card || parts.length > 0 ? (
|
|
492
|
+
<div data-box-under className="mt-1 flex flex-col gap-2">
|
|
493
|
+
{card && <CardUnder onRemove={() => setRemoved((was) => new Set([...was, card.value]))}>{card.view}</CardUnder>}
|
|
494
|
+
{parts.map((part) => (
|
|
495
|
+
<Fragment key={part.key}>{part.view}</Fragment>
|
|
496
|
+
))}
|
|
497
|
+
</div>
|
|
498
|
+
) : undefined
|
|
499
|
+
|
|
410
500
|
const refusedLine = refused && (
|
|
411
501
|
<FieldLine tone="error">
|
|
412
502
|
{edit ? `Not saved: ${refused}. Your changes are still in the box.` : `Not sent: ${refused}. Your text is back in the box.`}
|
|
@@ -433,7 +523,9 @@ export function CommentBox({
|
|
|
433
523
|
</div>
|
|
434
524
|
</div>
|
|
435
525
|
</div>
|
|
436
|
-
{
|
|
526
|
+
{underBox}
|
|
527
|
+
{sending && <FieldLine>Saving…</FieldLine>}
|
|
528
|
+
{refusedLine}
|
|
437
529
|
</div>
|
|
438
530
|
)
|
|
439
531
|
}
|
|
@@ -464,6 +556,7 @@ export function CommentBox({
|
|
|
464
556
|
selection={{ link: true }}
|
|
465
557
|
className={cn(sending && '[&_[data-composer-editor]]:text-text-muted')}
|
|
466
558
|
/>
|
|
559
|
+
{underBox}
|
|
467
560
|
{upload && <FilePicker ref={picker} multiple accept={accept} onPick={attachFiles} />}
|
|
468
561
|
{sending && <FieldLine>Sending…</FieldLine>}
|
|
469
562
|
{uploading && !sending && <FieldLine>Uploading… Send waits for the file.</FieldLine>}
|
package/src/ComposerTriggers.tsx
CHANGED
|
@@ -216,6 +216,71 @@ export function urgentPubkeys(editor: { state: { doc: Doc } }): string[] | undef
|
|
|
216
216
|
return urgent.length > 0 ? urgent : undefined
|
|
217
217
|
}
|
|
218
218
|
|
|
219
|
+
export interface PersonReferenceOptions {
|
|
220
|
+
/** Everyone `@` can offer, asked each time the query changes. */
|
|
221
|
+
people: () => readonly MentionPerson[]
|
|
222
|
+
/** The `nostr:npub…` a person is written as; `null` for someone without one, who is not offered. */
|
|
223
|
+
uriOf: (person: MentionPerson) => string | null
|
|
224
|
+
/** The node a pick inserts. Default `reference`, `ReferenceNode`'s. */
|
|
225
|
+
nodeName: string
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
/**
|
|
229
|
+
* `@` in a document — a person, written as a reference to them: a
|
|
230
|
+
* `ReferenceNode` whose `uri` is their `nostr:npub…` (SPEC §13.1, §13.3). Not
|
|
231
|
+
* {@link PersonMention}'s chip, which is a message's: a document names people
|
|
232
|
+
* the way it names anything else, and a save that newly names someone is what
|
|
233
|
+
* adds them (`@estiva-app/conversation`'s `mentionAddsFor`, which reads only
|
|
234
|
+
* that uri).
|
|
235
|
+
*
|
|
236
|
+
* PersonReference.configure({ people: () => directory, uriOf: (person) => npubUri(person.pubkey) })
|
|
237
|
+
*
|
|
238
|
+
* The chip carries no name: the app's `ReferenceNode` view resolves the uri,
|
|
239
|
+
* so a rename shows everywhere the person is named.
|
|
240
|
+
*
|
|
241
|
+
* why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-mention-in-a-files-text-adds-the-person-with-no-unread.md
|
|
242
|
+
*/
|
|
243
|
+
export const PersonReference = Extension.create<PersonReferenceOptions>({
|
|
244
|
+
name: 'personReference',
|
|
245
|
+
addOptions() {
|
|
246
|
+
return { people: () => [], uriOf: () => null, nodeName: 'reference' }
|
|
247
|
+
},
|
|
248
|
+
addProseMirrorPlugins() {
|
|
249
|
+
const options = this.options
|
|
250
|
+
return [
|
|
251
|
+
Suggestion<MentionPerson>({
|
|
252
|
+
editor: this.editor,
|
|
253
|
+
char: '@',
|
|
254
|
+
pluginKey: new PluginKey('personReference'),
|
|
255
|
+
...listening('@'),
|
|
256
|
+
// As `[`'s: only where the chip may go.
|
|
257
|
+
allow: ({ state, range }) => {
|
|
258
|
+
const type = state.schema.nodes[options.nodeName]
|
|
259
|
+
return !!type && !!state.doc.resolve(range.from).parent.type.contentMatch.matchType(type)
|
|
260
|
+
},
|
|
261
|
+
items: ({ query }) =>
|
|
262
|
+
filterPeople(
|
|
263
|
+
options.people().filter((person) => options.uriOf(person) !== null),
|
|
264
|
+
query,
|
|
265
|
+
),
|
|
266
|
+
render: suggestionPopup(peopleMenu(false)),
|
|
267
|
+
command: ({ editor, range, props: person }) => {
|
|
268
|
+
const uri = options.uriOf(person)
|
|
269
|
+
if (!uri) return
|
|
270
|
+
editor
|
|
271
|
+
.chain()
|
|
272
|
+
.focus()
|
|
273
|
+
.insertContentAt(range, [
|
|
274
|
+
{ type: options.nodeName, attrs: { uri } },
|
|
275
|
+
{ type: 'text', text: ' ' },
|
|
276
|
+
])
|
|
277
|
+
.run()
|
|
278
|
+
},
|
|
279
|
+
}),
|
|
280
|
+
]
|
|
281
|
+
},
|
|
282
|
+
})
|
|
283
|
+
|
|
219
284
|
// ─── [ ───
|
|
220
285
|
|
|
221
286
|
/** Something `[` offers: a reference drawn as who said it and how it opens. */
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
|
|
2
|
+
import * as DocumentEditorStories from './DocumentEditor.stories'
|
|
3
|
+
|
|
4
|
+
<Meta of={DocumentEditorStories} />
|
|
5
|
+
|
|
6
|
+
# DocumentEditor
|
|
7
|
+
|
|
8
|
+
One document's text as one surface that is always an editor, the same in every app: `/`, `[` and `@`, links on words, files, checklists, callouts and tables, the block handle, saving when you leave, someone else's save arriving, and the text held when the sign-in ends. The app supplies the translation of its saved text, its lists, its upload and its views of a chip and a file.
|
|
9
|
+
|
|
10
|
+
<Canvas of={DocumentEditorStories.WithComments} />
|
|
11
|
+
|
|
12
|
+
## When
|
|
13
|
+
|
|
14
|
+
- **Any document's text**, written where it is read: a page, a description, a panel. The same editor in every app.
|
|
15
|
+
- `references` and `mentions` for `[` and `@`, from the app's own lists. Without them, `[` and `@` are text.
|
|
16
|
+
- `upload` for `/` → File and a pasted picture, uploaded before the file is placed.
|
|
17
|
+
- `onCommentOnSelection` to offer Comment on what is selected, and draw where comments are. Without it, neither.
|
|
18
|
+
- `blockRows` for the app's rows in a block's menu: Copy link, Comment on the block.
|
|
19
|
+
- `readOnly` for reading: the same drawing, nothing typed or saved. Chips open, and Comment on a selection stays where it is on.
|
|
20
|
+
|
|
21
|
+
<Canvas of={DocumentEditorStories.WithFiles} />
|
|
22
|
+
|
|
23
|
+
<Canvas of={DocumentEditorStories.ReadOnly} />
|
|
24
|
+
|
|
25
|
+
## When not
|
|
26
|
+
|
|
27
|
+
- Something sent, a comment or a line in a conversation → **CommentBox**. Nothing is sent from here; it saves.
|
|
28
|
+
- One line, a title or the line under it → **InlineText**.
|
|
29
|
+
- Text in a form → **TextInput** or **Textarea**.
|
|
30
|
+
|
|
31
|
+
## How
|
|
32
|
+
|
|
33
|
+
```tsx
|
|
34
|
+
import { DocumentEditor, type DocumentCodec } from '@estiva-app/ui/editor'
|
|
35
|
+
import { documentForEditing, publishableFromEditor, toEditorDocument, type ContentFormat, type EditorDocument } from '@estiva-app/protocol'
|
|
36
|
+
import { mentionAddsFor } from '@estiva-app/conversation'
|
|
37
|
+
|
|
38
|
+
const codec: DocumentCodec = {
|
|
39
|
+
read: (value, format) => toEditorDocument(documentForEditing(value, format as ContentFormat), { links: true }),
|
|
40
|
+
write: (doc) => publishableFromEditor(doc as EditorDocument),
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
<DocumentEditor
|
|
44
|
+
key={address}
|
|
45
|
+
value={text}
|
|
46
|
+
format={format}
|
|
47
|
+
codec={codec}
|
|
48
|
+
label="Document"
|
|
49
|
+
placeholder="Type / for headings and lists."
|
|
50
|
+
changedBy={lastEditor}
|
|
51
|
+
hold={heldTyping}
|
|
52
|
+
holdKey={address}
|
|
53
|
+
references={{ sections: sectionsFor, ariaLabel: 'Items', sectionLabel: 'Items' }}
|
|
54
|
+
mentions={{ people: () => people, uriOf: (person) => `nostr:${encodeNpub(person.pubkey)}` }}
|
|
55
|
+
upload={uploadOne}
|
|
56
|
+
referenceView={chipView}
|
|
57
|
+
attachmentView={fileView}
|
|
58
|
+
onCommit={async (value, contentFormat, editedFrom) => {
|
|
59
|
+
const adds = mentionAddsFor(me, Date.now(), {
|
|
60
|
+
file: address,
|
|
61
|
+
folder: folderId,
|
|
62
|
+
saved: { content: value, format: contentFormat },
|
|
63
|
+
editedFrom: { content: editedFrom, format: savedFormatTag },
|
|
64
|
+
})
|
|
65
|
+
return save(value, contentFormat, adds)
|
|
66
|
+
}}
|
|
67
|
+
/>
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
- **It speaks the editor's document.** The package does not depend on `@estiva-app/protocol`: the app hands it `codec`, which reads its saved text and writes the editor's document back. Pass `{ links: true }`, or a link on words is lost at the next save.
|
|
71
|
+
- **`onCommit` answers whether it was saved**, and gets the saved text the edit started from: whom a save names anew is the difference between the two (`mentionAddsFor`). A refused or thrown save keeps the text and says so.
|
|
72
|
+
- **`@` writes a reference to the person**, a chip whose `uri` is their `nostr:npub…`, not a message's mention. `uriOf` answers it; someone without one is not offered. The chip carries no name: `referenceView` resolves it.
|
|
73
|
+
- **`label` is required**: the editor's accessible name.
|
|
74
|
+
- **Give the editor a `key` per document.** The editor and which of `[`, `@`, File, comments and markdown it has are made once, as it opens; the lists, the upload and the people are read as they are each time.
|
|
75
|
+
- **`hold` is the app's held-typing store.** `register` must not forget what is held when it is called again for the same key during an ending; the editor registers once per `holdKey`.
|
|
76
|
+
- **The cards a chip asks for** are drawn by the app's `cards`, after the text, until the kit has its own.
|
|
77
|
+
|
|
78
|
+
## What it owns
|
|
79
|
+
|
|
80
|
+
It does these by itself. Write none of them around it.
|
|
81
|
+
|
|
82
|
+
| It does | So you never write |
|
|
83
|
+
|---|---|
|
|
84
|
+
| Saving on blur, on unmount and on a checklist tick; never while typing; Escape leaves | a save button, a timer, a key handler |
|
|
85
|
+
| A refused save: the text kept, and "Could not save. Your text is still here." | a toast, or putting text back |
|
|
86
|
+
| Someone else's save: loaded while you are not in it; while you are, "*Name* saved a newer version. Load it (replaces your changes)", and leaving saves yours over theirs — the later save wins | a merge, a conflict dialog |
|
|
87
|
+
| Your own save coming back is not someone else's | an echo filter |
|
|
88
|
+
| The text held when the sign-in ends, back unsaved after the tap, and nothing saved on the way out | a draft |
|
|
89
|
+
| `/` Format (with checklist, note and warning) and Insert: Table, File, *Link to a file*, which opens `[` | the `/` rows |
|
|
90
|
+
| A URL pasted over plain words links them; typing after linked words is not linked; a link keeps the keys this version does not know | a paste handler, a link schema |
|
|
91
|
+
| A bare address drawn as a link, opened by a click, and saved as the text it is | a link decoration |
|
|
92
|
+
| Each block's id through editing, so what is anchored to it stays on it | an id plugin |
|
|
93
|
+
| A pasted picture uploaded and placed; the file dialog's blur is not leaving | an upload state |
|
|
94
|
+
| Read only: no caret, no `/`, `[` or `@`, no format buttons; still focusable, so a selection's Comment shows | a reading view |
|
|
95
|
+
|
|
96
|
+
## Keys
|
|
97
|
+
|
|
98
|
+
| Key | What it does |
|
|
99
|
+
|---|---|
|
|
100
|
+
| Escape | Lets go of selected words; with nothing selected, leaves the editor, which saves. With a list or a chip's menu open, closes it first. |
|
|
101
|
+
| Enter | With a list open, picks the row. |
|
|
102
|
+
| `/` | Opens Format and Insert. |
|
|
103
|
+
| `[` | Opens the app's list, when it passed one. |
|
|
104
|
+
| `@` | Opens the app's people, when it passed them. |
|
|
105
|
+
|
|
106
|
+
<Controls />
|