@estiva-app/ui 0.98.0 → 0.99.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 (193) hide show
  1. package/README.md +1 -1
  2. package/dist/AppProvider.d.ts +6 -3
  3. package/dist/AppProvider.d.ts.map +1 -1
  4. package/dist/ArchiveDialog.d.ts +35 -0
  5. package/dist/ArchiveDialog.d.ts.map +1 -0
  6. package/dist/AttachedCard.d.ts +13 -2
  7. package/dist/AttachedCard.d.ts.map +1 -1
  8. package/dist/Card.d.ts +6 -1
  9. package/dist/Card.d.ts.map +1 -1
  10. package/dist/ChipInput.d.ts +3 -1
  11. package/dist/ChipInput.d.ts.map +1 -1
  12. package/dist/CollapsibleSection.d.ts +27 -2
  13. package/dist/CollapsibleSection.d.ts.map +1 -1
  14. package/dist/CommentBox.d.ts +2 -2
  15. package/dist/CommentBox.d.ts.map +1 -1
  16. package/dist/ConfirmDialog.d.ts +15 -2
  17. package/dist/ConfirmDialog.d.ts.map +1 -1
  18. package/dist/ConversationCard.d.ts +6 -1
  19. package/dist/ConversationCard.d.ts.map +1 -1
  20. package/dist/ConversationLayout.d.ts +19 -4
  21. package/dist/ConversationLayout.d.ts.map +1 -1
  22. package/dist/ConversationPlace.d.ts +17 -0
  23. package/dist/ConversationPlace.d.ts.map +1 -0
  24. package/dist/DocumentEditor.d.ts +38 -0
  25. package/dist/DocumentEditor.d.ts.map +1 -1
  26. package/dist/DocumentField.d.ts +50 -0
  27. package/dist/DocumentField.d.ts.map +1 -0
  28. package/dist/EditableText.d.ts +38 -4
  29. package/dist/EditableText.d.ts.map +1 -1
  30. package/dist/EmptyState.d.ts +10 -5
  31. package/dist/EmptyState.d.ts.map +1 -1
  32. package/dist/FormDialog.d.ts +38 -0
  33. package/dist/FormDialog.d.ts.map +1 -0
  34. package/dist/InlineText.d.ts.map +1 -1
  35. package/dist/MoveDialog.d.ts +61 -0
  36. package/dist/MoveDialog.d.ts.map +1 -0
  37. package/dist/NavItem.d.ts +9 -2
  38. package/dist/NavItem.d.ts.map +1 -1
  39. package/dist/NavTree.d.ts +16 -3
  40. package/dist/NavTree.d.ts.map +1 -1
  41. package/dist/PinnedComment.d.ts +3 -1
  42. package/dist/PinnedComment.d.ts.map +1 -1
  43. package/dist/ReactionHorizon.d.ts +5 -1
  44. package/dist/ReactionHorizon.d.ts.map +1 -1
  45. package/dist/ResolveDialog.d.ts +3 -1
  46. package/dist/ResolveDialog.d.ts.map +1 -1
  47. package/dist/SelectionToolbar.d.ts +2 -2
  48. package/dist/Thread.d.ts +6 -3
  49. package/dist/Thread.d.ts.map +1 -1
  50. package/dist/commentBoxFrame.d.ts.map +1 -1
  51. package/dist/conversation.examples.d.ts +4 -1
  52. package/dist/conversation.examples.d.ts.map +1 -1
  53. package/dist/conversationScroll.d.ts +80 -0
  54. package/dist/conversationScroll.d.ts.map +1 -0
  55. package/dist/editor.d.ts +1 -0
  56. package/dist/editor.d.ts.map +1 -1
  57. package/dist/editor.js +228 -69
  58. package/dist/editor.js.map +4 -4
  59. package/dist/eslint/index.js +2 -2
  60. package/dist/eslint/index.js.map +2 -2
  61. package/dist/eslint/no-field-outside-a-form.d.ts +2 -2
  62. package/dist/eslint/no-field-outside-a-form.d.ts.map +1 -1
  63. package/dist/eslint/no-native-title.d.ts +1 -1
  64. package/dist/eslint/no-native-title.d.ts.map +1 -1
  65. package/dist/formBusy.d.ts +5 -2
  66. package/dist/formBusy.d.ts.map +1 -1
  67. package/dist/index.d.ts +14 -6
  68. package/dist/index.d.ts.map +1 -1
  69. package/dist/index.js +2210 -1458
  70. package/dist/index.js.map +4 -4
  71. package/dist/looks.d.ts +8 -0
  72. package/dist/looks.d.ts.map +1 -1
  73. package/dist/seenOnScreen.d.ts +27 -0
  74. package/dist/seenOnScreen.d.ts.map +1 -0
  75. package/dist/showInConversation.d.ts +31 -0
  76. package/dist/showInConversation.d.ts.map +1 -0
  77. package/dist/threadCard.d.ts +13 -0
  78. package/dist/threadCard.d.ts.map +1 -1
  79. package/package.json +1 -1
  80. package/registry.json +904 -139
  81. package/src/AppProvider.mdx +4 -0
  82. package/src/AppProvider.test.tsx +34 -2
  83. package/src/AppProvider.tsx +17 -6
  84. package/src/ArchiveDialog.mdx +70 -0
  85. package/src/ArchiveDialog.stories.tsx +64 -0
  86. package/src/ArchiveDialog.test.tsx +90 -0
  87. package/src/ArchiveDialog.tsx +70 -0
  88. package/src/AttachedCard.mdx +6 -0
  89. package/src/AttachedCard.stories.tsx +9 -1
  90. package/src/AttachedCard.test.tsx +111 -2
  91. package/src/AttachedCard.tsx +77 -7
  92. package/src/Card.mdx +20 -1
  93. package/src/Card.stories.tsx +20 -0
  94. package/src/Card.test.tsx +87 -1
  95. package/src/Card.tsx +51 -3
  96. package/src/ChipInput.mdx +7 -1
  97. package/src/ChipInput.stories.tsx +9 -0
  98. package/src/ChipInput.test.tsx +42 -0
  99. package/src/ChipInput.tsx +7 -3
  100. package/src/CollapsibleSection.mdx +20 -1
  101. package/src/CollapsibleSection.stories.tsx +19 -1
  102. package/src/CollapsibleSection.test.tsx +85 -2
  103. package/src/CollapsibleSection.tsx +54 -15
  104. package/src/CommentBox.mdx +2 -1
  105. package/src/CommentBox.test.tsx +81 -1
  106. package/src/CommentBox.tsx +32 -11
  107. package/src/ConfirmDialog.mdx +25 -3
  108. package/src/ConfirmDialog.stories.tsx +27 -0
  109. package/src/ConfirmDialog.test.tsx +87 -1
  110. package/src/ConfirmDialog.tsx +39 -8
  111. package/src/ConversationCard.mdx +4 -0
  112. package/src/ConversationCard.stories.tsx +11 -1
  113. package/src/ConversationCard.test.tsx +116 -0
  114. package/src/ConversationCard.tsx +53 -36
  115. package/src/ConversationLayout.mdx +30 -4
  116. package/src/ConversationLayout.scroll.test.tsx +411 -0
  117. package/src/ConversationLayout.stories.tsx +79 -1
  118. package/src/ConversationLayout.test.tsx +79 -0
  119. package/src/ConversationLayout.tsx +136 -15
  120. package/src/ConversationPlace.mdx +53 -0
  121. package/src/ConversationPlace.stories.tsx +48 -0
  122. package/src/ConversationPlace.test.tsx +51 -0
  123. package/src/ConversationPlace.tsx +30 -0
  124. package/src/DocumentEditor.mdx +2 -1
  125. package/src/DocumentEditor.tsx +118 -64
  126. package/src/DocumentField.mdx +83 -0
  127. package/src/DocumentField.stories.tsx +110 -0
  128. package/src/DocumentField.test.tsx +281 -0
  129. package/src/DocumentField.tsx +199 -0
  130. package/src/EditableText.buttons.test.tsx +318 -0
  131. package/src/EditableText.mdx +50 -2
  132. package/src/EditableText.stories.tsx +96 -2
  133. package/src/EditableText.tsx +189 -5
  134. package/src/EmptyState.mdx +33 -8
  135. package/src/EmptyState.stories.tsx +26 -1
  136. package/src/EmptyState.test.tsx +63 -2
  137. package/src/EmptyState.tsx +28 -6
  138. package/src/Form.mdx +3 -1
  139. package/src/FormDialog.mdx +78 -0
  140. package/src/FormDialog.stories.tsx +90 -0
  141. package/src/FormDialog.test.tsx +183 -0
  142. package/src/FormDialog.tsx +93 -0
  143. package/src/InlineText.mdx +1 -0
  144. package/src/InlineText.tsx +2 -1
  145. package/src/MoveDialog.mdx +74 -0
  146. package/src/MoveDialog.stories.tsx +121 -0
  147. package/src/MoveDialog.test.tsx +203 -0
  148. package/src/MoveDialog.tsx +183 -0
  149. package/src/NavItem.mdx +15 -0
  150. package/src/NavItem.stories.tsx +15 -0
  151. package/src/NavItem.test.tsx +64 -1
  152. package/src/NavItem.tsx +10 -2
  153. package/src/NavTree.mdx +26 -4
  154. package/src/NavTree.stories.tsx +59 -0
  155. package/src/NavTree.test.tsx +232 -2
  156. package/src/NavTree.tsx +93 -43
  157. package/src/PinnedComment.mdx +6 -1
  158. package/src/PinnedComment.stories.tsx +11 -1
  159. package/src/PinnedComment.tsx +15 -2
  160. package/src/ReactionHorizon.mdx +3 -0
  161. package/src/ReactionHorizon.stories.tsx +3 -0
  162. package/src/ReactionHorizon.test.tsx +55 -0
  163. package/src/ReactionHorizon.tsx +30 -11
  164. package/src/ReplyCard.mdx +3 -0
  165. package/src/ReplyCard.stories.tsx +19 -1
  166. package/src/ResolveDialog.mdx +2 -0
  167. package/src/ResolveDialog.test.tsx +21 -0
  168. package/src/ResolveDialog.tsx +11 -39
  169. package/src/SelectionToolbar.tsx +2 -2
  170. package/src/Textarea.mdx +1 -0
  171. package/src/Thread.mdx +18 -1
  172. package/src/Thread.stories.tsx +55 -3
  173. package/src/Thread.test.tsx +11 -0
  174. package/src/Thread.tsx +53 -11
  175. package/src/commentBoxFrame.tsx +2 -2
  176. package/src/conversation.examples.tsx +10 -2
  177. package/src/conversationScroll.ts +155 -0
  178. package/src/editor.ts +1 -0
  179. package/src/editorSelection.test.tsx +53 -0
  180. package/src/eslint/no-field-outside-a-form.test.ts +4 -0
  181. package/src/eslint/no-field-outside-a-form.ts +2 -2
  182. package/src/eslint/no-native-title.ts +1 -1
  183. package/src/formBusy.ts +5 -2
  184. package/src/index.ts +16 -6
  185. package/src/looks.ts +10 -0
  186. package/src/registry/registry.test.ts +12 -6
  187. package/src/seenOnScreen.test.tsx +182 -0
  188. package/src/seenOnScreen.ts +146 -0
  189. package/src/showInConversation.test.tsx +168 -0
  190. package/src/showInConversation.ts +93 -0
  191. package/src/threadCard.ts +16 -0
  192. package/stories/Choosing.mdx +7 -2
  193. package/tailwind-preset.js +7 -0
@@ -7,6 +7,7 @@ import { IconMessagePlus } from '@tabler/icons-react'
7
7
  import type { HandleBlock } from './BlockHandle'
8
8
  import { AttachmentNode, BlockId, Callout, Checklist, ReferenceNode, UnknownBlock, isChecklistTick, type AttachmentViewProps, type ReferenceViewProps } from './BlockNodes'
9
9
  import { Button } from './Button'
10
+ import { cn } from './cn'
10
11
  import { CodeBlockColours } from './CodeBlockColours'
11
12
  import { CommentHighlights, anchorOfSelection, type SelectionAnchor } from './CommentHighlights'
12
13
  import { PersonReference, ReferenceTrigger, SlashCommands, formatSection, typeTrigger, type MentionPerson, type ReferenceSection, type SlashCommand, type SlashSection } from './ComposerTriggers'
@@ -19,6 +20,7 @@ import { BareLinks, DocumentKit, LINK_MARK_ATTRIBUTES, PasteOverWords } from './
19
20
  import { PastedImages } from './PastedImages'
20
21
  import { PastedMarkdown } from './PastedMarkdown'
21
22
  import { LinkPlaces } from './LinkPlaces'
23
+ import { EDITOR_SELECTION_CLASSES } from './looks'
22
24
  import { ReferenceMenu, ReferenceMenuView, isReferenceMenuOpen } from './ReferenceMenu'
23
25
  import { richTextClassName } from './RichText'
24
26
  import { KeptSelection, SelectionToolbar } from './SelectionToolbar'
@@ -345,69 +347,21 @@ export function DocumentEditor({
345
347
 
346
348
  const editor = useEditor(
347
349
  {
348
- extensions: [
349
- DocumentKit.configure({
350
- strike: false,
351
- heading: { levels: [1, 2, 3] },
352
- dropcursor: blockDropCursor,
353
- codeBlock: false,
354
- // 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
355
- // address does — through `BareLinks`, which opens only a followable address and never hands the tab this window;
356
- // Tiptap's own click opens without that. A bare address stays text: a link made on it by typing would change what is saved.
357
- link: { openOnClick: false, shouldAutoLink: () => false, HTMLAttributes: LINK_MARK_ATTRIBUTES },
358
- }),
359
- PasteOverWords,
360
- KeptSelection,
361
- BareLinks,
362
- CodeBlockColours,
363
- TableKit.configure({ table: { resizable: false } }),
364
- BlockId,
365
- Checklist,
366
- Callout,
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 }),
369
- // A link's chip in a sentence, its row alone on its line, its card in the row's place (SPEC §13.3).
370
- LinkPlaces,
371
- // A click on a link offers Open, and alone on its line Show as Row or Card.
372
- ReferenceMenu,
373
- UnknownBlock,
374
- AttachmentNode.configure({ view: attachmentView ?? null }),
375
- SlashCommands.configure({ sections: slashSections({ table, upload: !!upload, pickFile }) }),
376
- ...(references
377
- ? [
378
- ReferenceTrigger.configure({
379
- items: () => [],
380
- sections: (query) => latest.current.references?.sections(query) ?? [],
381
- subscribe: (listener) => latest.current.references?.subscribe?.(listener) ?? (() => {}),
382
- nodeName: 'reference',
383
- ariaLabel: references.ariaLabel,
384
- sectionLabel: references.sectionLabel,
385
- icon: references.icon ?? null,
386
- }),
387
- ]
388
- : []),
389
- ...(mentions
390
- ? [PersonReference.configure({ people: () => latest.current.mentions?.people() ?? [], uriOf: (person) => latest.current.mentions?.uriOf(person) ?? null })]
391
- : []),
392
- ...(linkChips ? [LinkChips.configure(linkChips)] : []),
393
- ...(upload
394
- ? [
395
- // A pasted picture is placed as `/` File places one; text on the clipboard stays text.
396
- PastedImages.configure({
397
- onImages: (pasted) => {
398
- if (!latest.current.upload) return false
399
- void attachTo.current(pasted)
400
- return true
401
- },
402
- }),
403
- ]
404
- : []),
405
- // Markdown pasted as plain text lands as the blocks it spells, tables included.
406
- ...(readMarkdown ? [PastedMarkdown.configure({ read: (text) => latest.current.readMarkdown?.(text) })] : []),
407
- // Where each comment is, drawn as a decoration, so a save never carries it.
408
- ...(onCommentOnSelection ? [CommentHighlights] : []),
409
- ...extensions,
410
- ],
350
+ extensions: documentExtensions({
351
+ latest,
352
+ references,
353
+ mentions,
354
+ linkChips,
355
+ table,
356
+ upload: !!upload,
357
+ readMarkdown: !!readMarkdown,
358
+ comments: !!onCommentOnSelection,
359
+ referenceView,
360
+ attachmentView,
361
+ pickFile,
362
+ attach: attachTo,
363
+ extensions,
364
+ }),
411
365
  // Made once. A value coming back must not rebuild the editor under the caret; see the effect below.
412
366
  content: held ?? codec.read(value, format),
413
367
  editable: !readOnly,
@@ -420,7 +374,7 @@ export function DocumentEditor({
420
374
  tabindex: '0',
421
375
  // A row or a card is its whole line (`LinkPlaces`), drawn on that line: a block inside it would push the
422
376
  // separator and trailing break ProseMirror puts beside it onto empty lines of their own (code review).
423
- class: richTextClassName('default', 'outline-none [&_[data-link-place]]:inline-block [&_[data-link-place]]:w-full [&_[data-link-place]]:align-top'),
377
+ class: richTextClassName('default', cn('outline-none [&_[data-link-place]]:inline-block [&_[data-link-place]]:w-full [&_[data-link-place]]:align-top', EDITOR_SELECTION_CLASSES)),
424
378
  },
425
379
  handleKeyDown: (view, event) => {
426
380
  if (event.key !== 'Escape') return false
@@ -562,6 +516,106 @@ export function DocumentEditor({
562
516
  return <>{wrap ? wrap(drawn, editor) : drawn}</>
563
517
  }
564
518
 
519
+ /** What a document's editor is built from: the app's parts, and its latest handlers, read through `latest` (the editor is made once). */
520
+ export interface DocumentGrammar {
521
+ latest: {
522
+ current: {
523
+ references?: DocumentReferences
524
+ mentions?: DocumentMentions
525
+ upload?: unknown
526
+ readMarkdown?: (text: string) => JSONContent | undefined
527
+ }
528
+ }
529
+ references?: DocumentReferences
530
+ mentions?: DocumentMentions
531
+ linkChips?: LinkChipsOptions
532
+ /** `/` → Table. */
533
+ table: boolean
534
+ /** `/` → Upload, and a pasted picture placed. */
535
+ upload: boolean
536
+ /** Markdown pasted as plain text lands as blocks. */
537
+ readMarkdown: boolean
538
+ /** The comment highlights. */
539
+ comments: boolean
540
+ referenceView?: ComponentType<ReferenceViewProps>
541
+ attachmentView?: ComponentType<AttachmentViewProps>
542
+ /** Opens the file dialog, for `/` → Upload. */
543
+ pickFile: { current: () => void }
544
+ /** Uploads and places pasted pictures. */
545
+ attach: { current: (files: File[]) => Promise<void> }
546
+ extensions: readonly AnyExtension[]
547
+ }
548
+
549
+ /**
550
+ * A document's grammar, one list for every editor of a document (`DocumentEditor`, `DocumentField`): the blocks, the
551
+ * marks, links where they sit, `/`, and `[` and `@` when the app gives them.
552
+ */
553
+ export function documentExtensions({ latest, references, mentions, linkChips, table, upload, readMarkdown, comments, referenceView, attachmentView, pickFile, attach, extensions }: DocumentGrammar): AnyExtension[] {
554
+ return [
555
+ DocumentKit.configure({
556
+ strike: false,
557
+ heading: { levels: [1, 2, 3] },
558
+ dropcursor: blockDropCursor,
559
+ codeBlock: false,
560
+ // 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
561
+ // address does — through `BareLinks`, which opens only a followable address and never hands the tab this window;
562
+ // Tiptap's own click opens without that. A bare address stays text: a link made on it by typing would change what is saved.
563
+ link: { openOnClick: false, shouldAutoLink: () => false, HTMLAttributes: LINK_MARK_ATTRIBUTES },
564
+ }),
565
+ PasteOverWords,
566
+ KeptSelection,
567
+ BareLinks,
568
+ CodeBlockColours,
569
+ TableKit.configure({ table: { resizable: false } }),
570
+ BlockId,
571
+ Checklist,
572
+ Callout,
573
+ // A link is being edited only while the caret is on its line: anywhere else on the page it previews on hover.
574
+ ReferenceNode.configure({ view: referenceView ?? null, editingLine: true }),
575
+ // A link's chip in a sentence, its row alone on its line, its card in the row's place (SPEC §13.3).
576
+ LinkPlaces,
577
+ // A click on a link offers Open, and alone on its line Show as Row or Card.
578
+ ReferenceMenu,
579
+ UnknownBlock,
580
+ AttachmentNode.configure({ view: attachmentView ?? null }),
581
+ SlashCommands.configure({ sections: slashSections({ table, upload, pickFile }) }),
582
+ ...(references
583
+ ? [
584
+ ReferenceTrigger.configure({
585
+ items: () => [],
586
+ sections: (query) => latest.current.references?.sections(query) ?? [],
587
+ subscribe: (listener) => latest.current.references?.subscribe?.(listener) ?? (() => {}),
588
+ nodeName: 'reference',
589
+ ariaLabel: references.ariaLabel,
590
+ sectionLabel: references.sectionLabel,
591
+ icon: references.icon ?? null,
592
+ }),
593
+ ]
594
+ : []),
595
+ ...(mentions
596
+ ? [PersonReference.configure({ people: () => latest.current.mentions?.people() ?? [], uriOf: (person) => latest.current.mentions?.uriOf(person) ?? null })]
597
+ : []),
598
+ ...(linkChips ? [LinkChips.configure(linkChips)] : []),
599
+ ...(upload
600
+ ? [
601
+ // A pasted picture is placed as `/` File places one; text on the clipboard stays text.
602
+ PastedImages.configure({
603
+ onImages: (pasted) => {
604
+ if (!latest.current.upload) return false
605
+ void attach.current(pasted)
606
+ return true
607
+ },
608
+ }),
609
+ ]
610
+ : []),
611
+ // Markdown pasted as plain text lands as the blocks it spells, tables included.
612
+ ...(readMarkdown ? [PastedMarkdown.configure({ read: (text) => latest.current.readMarkdown?.(text) })] : []),
613
+ // Where each comment is, drawn as a decoration, so a save never carries it.
614
+ ...(comments ? [CommentHighlights] : []),
615
+ ...extensions,
616
+ ]
617
+ }
618
+
565
619
  /**
566
620
  * `/`: the shared Format section with a document's checklist and callouts,
567
621
  * then Insert with what this editor can do. File and Mention type `[` and `@`,
@@ -0,0 +1,83 @@
1
+ import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
2
+ import * as Stories from './DocumentField.stories'
3
+
4
+ <Meta of={Stories} />
5
+
6
+ # DocumentField
7
+
8
+ A form's field that holds a document: the document editor's blocks, marks, `[`, `@` and `/`, in a field's box.
9
+
10
+ <Canvas of={Stories.InAForm} />
11
+
12
+ ## When
13
+
14
+ - A form asks for longer text that is a document where it lands: a description written in the form that files it.
15
+ - Its box is a field's, as a **Textarea**'s beside it: the same fill, edge, corners, hover and focus.
16
+ - `references` for `[` and `/` → File, `mentions` for `@` and `/` → Mention, as in **DocumentEditor**.
17
+
18
+ <Canvas of={Stories.Written} />
19
+
20
+ <Canvas of={Stories.WithReferencesAndMentions} />
21
+
22
+ ## When not
23
+
24
+ - Plain text, one paragraph, no formatting → **Textarea**. One line → **TextInput**.
25
+ - A document on its own page, saved when you leave it → **DocumentEditor**.
26
+ - A comment, a reply, a chat line → **CommentBox**.
27
+
28
+ ## How
29
+
30
+ ```tsx
31
+ import { Field, Form } from '@estiva-app/ui'
32
+ import { DocumentField } from '@estiva-app/ui/editor'
33
+
34
+ <Form onSubmit={file}>
35
+ <Field label="Description" required>
36
+ <DocumentField
37
+ value={draft.value}
38
+ format={draft.format}
39
+ codec={codec}
40
+ label="Description"
41
+ placeholder="What happened?"
42
+ references={references}
43
+ mentions={mentions}
44
+ onChange={(value, contentFormat) => setDraft({ value, format: contentFormat ? 'blocks' : 'marker' })}
45
+ />
46
+ </Field>
47
+ </Form>
48
+ ```
49
+
50
+ - It is the form's, controlled: every edit goes to `onChange` as it is typed, with the format it is in, and `''` once it is emptied or holds only spaces and blank lines, so a required field is missing again. Nothing is saved on leaving: the form sends.
51
+ - `codec` and `format` are **DocumentEditor**'s: how your text and the editor's document turn into each other.
52
+ - A new `value` from outside (a prefill, the form coming back) loads into it as the document it is. Its own edits coming back, late or not, are never loaded over newer typing.
53
+ - Ctrl/Cmd+Enter sends the form around it; Enter is a new paragraph and Shift+Enter a line break.
54
+ - Escape is the form's: the field does not take it, except to close an open list.
55
+ - No `/` → Table and no upload in a field.
56
+ - The `Field` around it names it for a screen reader through `label`, and a required `Field` marks it required.
57
+
58
+ ## What it owns
59
+
60
+ It does these by itself. Write none of them around it.
61
+
62
+ | It does | So you never write |
63
+ |---|---|
64
+ | Every edit handed back as it is typed; `''` when emptied, or only spaces and blank lines | an update listener, a serializer call, an empty check |
65
+ | A value from outside loaded; its own edits, however late, never loaded over newer typing | a queue of edits in flight, a compare |
66
+ | The field's box and its hover and focus, as a Textarea's | a box of your own around an editor |
67
+ | The placeholder while it is empty | an overlay |
68
+ | `[`, `@` and `/`, their lists and chips; the strip over picked words; a link's menu | the triggers, a toolbar |
69
+ | Ctrl/Cmd+Enter reaching the form; Shift+Enter a line break | key handlers |
70
+ | Selected words painted in the selected colour | a `::selection` rule |
71
+
72
+ ## Keys
73
+
74
+ | Key | Does |
75
+ |---|---|
76
+ | Ctrl/Cmd+Enter | Sends the form around it |
77
+ | Enter | A new paragraph; in an open list, picks |
78
+ | Shift+Enter | A line break |
79
+ | Escape | Closes an open list; otherwise the form's |
80
+
81
+ ## Props
82
+
83
+ <Controls />
@@ -0,0 +1,110 @@
1
+ import type { Meta, StoryObj } from '@storybook/react-vite'
2
+ import { useState } from 'react'
3
+ import type { JSONContent } from '@tiptap/react'
4
+ import { documentForEditing, encodeNpub, publishableFromEditor, toEditorDocument, type ContentFormat, type EditorDocument } from '@estiva-app/protocol'
5
+ import { Button } from './Button'
6
+ import type { MentionPerson, ReferenceSection } from './ComposerTriggers'
7
+ import type { DocumentCodec } from './DocumentEditor'
8
+ import { DocumentField, type DocumentFieldProps } from './DocumentField'
9
+ import { Field } from './Field'
10
+ import { Form } from './Form'
11
+ import { Textarea } from './Textarea'
12
+ import { TextInput } from './TextInput'
13
+
14
+ /**
15
+ * A form's field that holds a document. Every story is live: type, open `/`, `[` or `@`, pick words for the strip.
16
+ * The line under it is what the form holds now: every edit goes there as it is typed. Pick the theme in the toolbar.
17
+ */
18
+ const meta = {
19
+ title: 'Writing/DocumentField',
20
+ component: DocumentField,
21
+ parameters: { layout: 'padded' },
22
+ } satisfies Meta<typeof DocumentField>
23
+
24
+ export default meta
25
+ type Story = StoryObj
26
+
27
+ // ─── The app's side, played by @estiva-app/protocol ───
28
+
29
+ const codec: DocumentCodec = {
30
+ read: (value, format) => toEditorDocument(documentForEditing(value, format as ContentFormat), { links: true }) as JSONContent,
31
+ write: (doc) => publishableFromEditor(doc as EditorDocument),
32
+ }
33
+ const PEOPLE: MentionPerson[] = ['one', 'two'].map((n, i) => ({ id: n, name: `Person ${n}`, pubkey: String.fromCharCode(98 + i).repeat(64) }))
34
+ const mentions = { people: () => PEOPLE, uriOf: (person: MentionPerson) => (person.pubkey ? `nostr:${encodeNpub(person.pubkey)}` : null) }
35
+ const SECTIONS: ReferenceSection[] = [{ label: 'Group one', items: [{ id: 'item-one', label: 'Item one', snippet: '', uri: 'nostr:naddr1itemone' }] }]
36
+ const references = { sections: () => SECTIONS, ariaLabel: 'Items', sectionLabel: 'Items' }
37
+
38
+ /** Written before: a line with bold words, then a list. */
39
+ const WRITTEN = JSON.stringify({
40
+ type: 'doc',
41
+ content: [
42
+ { type: 'paragraph', id: 'b1', content: [{ type: 'text', text: 'A line with ' }, { type: 'text', text: 'bold words', marks: [{ type: 'bold' }] }, { type: 'text', text: ', then a list.' }] },
43
+ { type: 'bulletList', id: 'b2', content: [{ type: 'listItem', content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Item one' }] }] }, { type: 'listItem', content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Item two' }] }] }] },
44
+ ],
45
+ })
46
+
47
+ /** The field as a form holds it: the value and its format, each edit back as it is typed. */
48
+ function Held({ start = '', ...props }: Partial<DocumentFieldProps> & { start?: string }) {
49
+ const [held, setHeld] = useState({ value: start, format: 'blocks' })
50
+ return (
51
+ <div className="flex w-96 flex-col gap-3">
52
+ <Field label="Label">
53
+ <DocumentField
54
+ value={held.value}
55
+ format={held.format}
56
+ codec={codec}
57
+ label="Label"
58
+ onChange={(value, contentFormat) => setHeld({ value, format: contentFormat ? 'blocks' : 'marker' })}
59
+ {...props}
60
+ />
61
+ </Field>
62
+ <p className="text-caption text-text-muted">{held.value ? `Held: ${held.value.length} characters of a document.` : 'Held: nothing.'}</p>
63
+ </div>
64
+ )
65
+ }
66
+
67
+ /** Empty, with its placeholder. */
68
+ export const Empty: Story = { render: () => <Held placeholder="Write something…" /> }
69
+
70
+ /** Written before: what it holds loads as the document it is. */
71
+ export const Written: Story = { render: () => <Held start={WRITTEN} placeholder="Write something…" /> }
72
+
73
+ /** `[` lists what the app offers, `@` its people. */
74
+ export const WithReferencesAndMentions: Story = { render: () => <Held placeholder="Type [ or @" references={references} mentions={mentions} /> }
75
+
76
+ /** In a form, beside its other fields: the same box as a Textarea's. Ctrl+Enter sends the form from it. */
77
+ export const InAForm: Story = {
78
+ render: () => {
79
+ const [sent, setSent] = useState(0)
80
+ const [title, setTitle] = useState('')
81
+ const [notes, setNotes] = useState('')
82
+ const [body, setBody] = useState({ value: '', format: 'blocks' })
83
+ return (
84
+ <Form onSubmit={() => setSent((n) => n + 1)} className="w-96">
85
+ <Field label="Label">
86
+ <TextInput value={title} onChange={(event) => setTitle(event.target.value)} placeholder="One line" />
87
+ </Field>
88
+ <Field label="Label two">
89
+ <Textarea value={notes} onChange={(event) => setNotes(event.target.value)} placeholder="Plain text" rows={3} />
90
+ </Field>
91
+ <Field label="Label three">
92
+ <DocumentField
93
+ value={body.value}
94
+ format={body.format}
95
+ codec={codec}
96
+ label="Label three"
97
+ placeholder="A document"
98
+ onChange={(value, contentFormat) => setBody({ value, format: contentFormat ? 'blocks' : 'marker' })}
99
+ />
100
+ </Field>
101
+ <div className="flex items-center gap-3">
102
+ <Button type="submit" variant="primary">
103
+ Send
104
+ </Button>
105
+ <span className="text-caption text-text-muted">{sent ? `Sent ${sent} times.` : 'Not sent yet.'}</span>
106
+ </div>
107
+ </Form>
108
+ )
109
+ },
110
+ }