@estiva-app/ui 0.98.1 → 0.100.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 (212) hide show
  1. package/README.md +4 -2
  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 +12 -1
  19. package/dist/ConversationCard.d.ts.map +1 -1
  20. package/dist/ConversationLayout.d.ts +20 -5
  21. package/dist/ConversationLayout.d.ts.map +1 -1
  22. package/dist/ConversationMenu.d.ts +5 -1
  23. package/dist/ConversationMenu.d.ts.map +1 -1
  24. package/dist/ConversationPlace.d.ts +17 -0
  25. package/dist/ConversationPlace.d.ts.map +1 -0
  26. package/dist/DocumentEditor.d.ts +38 -0
  27. package/dist/DocumentEditor.d.ts.map +1 -1
  28. package/dist/DocumentField.d.ts +50 -0
  29. package/dist/DocumentField.d.ts.map +1 -0
  30. package/dist/EditableText.d.ts +38 -4
  31. package/dist/EditableText.d.ts.map +1 -1
  32. package/dist/EmptyState.d.ts +10 -5
  33. package/dist/EmptyState.d.ts.map +1 -1
  34. package/dist/FormDialog.d.ts +38 -0
  35. package/dist/FormDialog.d.ts.map +1 -0
  36. package/dist/InlineText.d.ts.map +1 -1
  37. package/dist/Menu.d.ts +11 -3
  38. package/dist/Menu.d.ts.map +1 -1
  39. package/dist/MoveDialog.d.ts +64 -0
  40. package/dist/MoveDialog.d.ts.map +1 -0
  41. package/dist/NavItem.d.ts +9 -2
  42. package/dist/NavItem.d.ts.map +1 -1
  43. package/dist/NavTree.d.ts +16 -3
  44. package/dist/NavTree.d.ts.map +1 -1
  45. package/dist/PinnedComment.d.ts +3 -1
  46. package/dist/PinnedComment.d.ts.map +1 -1
  47. package/dist/ReactionHorizon.d.ts +3 -1
  48. package/dist/ReactionHorizon.d.ts.map +1 -1
  49. package/dist/RepliesRow.d.ts +5 -3
  50. package/dist/RepliesRow.d.ts.map +1 -1
  51. package/dist/ResolveDialog.d.ts +3 -1
  52. package/dist/ResolveDialog.d.ts.map +1 -1
  53. package/dist/SelectionToolbar.d.ts +2 -2
  54. package/dist/Thread.d.ts +6 -3
  55. package/dist/Thread.d.ts.map +1 -1
  56. package/dist/commentBoxFrame.d.ts.map +1 -1
  57. package/dist/conversation.examples.d.ts +4 -1
  58. package/dist/conversation.examples.d.ts.map +1 -1
  59. package/dist/conversationScroll.d.ts +80 -0
  60. package/dist/conversationScroll.d.ts.map +1 -0
  61. package/dist/editor.d.ts +1 -0
  62. package/dist/editor.d.ts.map +1 -1
  63. package/dist/editor.js +228 -69
  64. package/dist/editor.js.map +4 -4
  65. package/dist/eslint/index.js +2 -2
  66. package/dist/eslint/index.js.map +2 -2
  67. package/dist/eslint/no-field-outside-a-form.d.ts +2 -2
  68. package/dist/eslint/no-field-outside-a-form.d.ts.map +1 -1
  69. package/dist/eslint/no-native-title.d.ts +1 -1
  70. package/dist/eslint/no-native-title.d.ts.map +1 -1
  71. package/dist/formBusy.d.ts +5 -2
  72. package/dist/formBusy.d.ts.map +1 -1
  73. package/dist/index.d.ts +14 -6
  74. package/dist/index.d.ts.map +1 -1
  75. package/dist/index.js +2242 -1471
  76. package/dist/index.js.map +4 -4
  77. package/dist/looks.d.ts +8 -0
  78. package/dist/looks.d.ts.map +1 -1
  79. package/dist/seenOnScreen.d.ts +27 -0
  80. package/dist/seenOnScreen.d.ts.map +1 -0
  81. package/dist/showInConversation.d.ts +31 -0
  82. package/dist/showInConversation.d.ts.map +1 -0
  83. package/dist/threadCard.d.ts +13 -0
  84. package/dist/threadCard.d.ts.map +1 -1
  85. package/package.json +1 -1
  86. package/registry.json +953 -126
  87. package/src/AppProvider.mdx +4 -0
  88. package/src/AppProvider.test.tsx +34 -2
  89. package/src/AppProvider.tsx +17 -6
  90. package/src/ArchiveDialog.mdx +70 -0
  91. package/src/ArchiveDialog.stories.tsx +64 -0
  92. package/src/ArchiveDialog.test.tsx +90 -0
  93. package/src/ArchiveDialog.tsx +70 -0
  94. package/src/AttachedCard.mdx +6 -0
  95. package/src/AttachedCard.stories.tsx +9 -1
  96. package/src/AttachedCard.test.tsx +111 -2
  97. package/src/AttachedCard.tsx +77 -7
  98. package/src/Card.mdx +20 -1
  99. package/src/Card.stories.tsx +20 -0
  100. package/src/Card.test.tsx +87 -1
  101. package/src/Card.tsx +51 -3
  102. package/src/ChipInput.mdx +7 -1
  103. package/src/ChipInput.stories.tsx +9 -0
  104. package/src/ChipInput.test.tsx +42 -0
  105. package/src/ChipInput.tsx +7 -3
  106. package/src/CollapsibleSection.mdx +20 -1
  107. package/src/CollapsibleSection.stories.tsx +19 -1
  108. package/src/CollapsibleSection.test.tsx +85 -2
  109. package/src/CollapsibleSection.tsx +54 -15
  110. package/src/CommentBox.mdx +2 -1
  111. package/src/CommentBox.test.tsx +81 -1
  112. package/src/CommentBox.tsx +32 -11
  113. package/src/ConfirmDialog.mdx +25 -3
  114. package/src/ConfirmDialog.stories.tsx +27 -0
  115. package/src/ConfirmDialog.test.tsx +87 -1
  116. package/src/ConfirmDialog.tsx +39 -8
  117. package/src/ConversationCard.mdx +7 -0
  118. package/src/ConversationCard.states.test.tsx +67 -0
  119. package/src/ConversationCard.stories.tsx +27 -1
  120. package/src/ConversationCard.test.tsx +76 -0
  121. package/src/ConversationCard.tsx +65 -53
  122. package/src/ConversationLayout.mdx +34 -4
  123. package/src/ConversationLayout.scroll.test.tsx +411 -0
  124. package/src/ConversationLayout.stories.tsx +107 -1
  125. package/src/ConversationLayout.test.tsx +133 -0
  126. package/src/ConversationLayout.tsx +141 -16
  127. package/src/ConversationMenu.mdx +3 -0
  128. package/src/ConversationMenu.stories.tsx +12 -0
  129. package/src/ConversationMenu.test.tsx +17 -0
  130. package/src/ConversationMenu.tsx +7 -3
  131. package/src/ConversationPlace.mdx +53 -0
  132. package/src/ConversationPlace.stories.tsx +48 -0
  133. package/src/ConversationPlace.test.tsx +51 -0
  134. package/src/ConversationPlace.tsx +30 -0
  135. package/src/DocumentEditor.mdx +2 -1
  136. package/src/DocumentEditor.tsx +118 -64
  137. package/src/DocumentField.mdx +83 -0
  138. package/src/DocumentField.stories.tsx +110 -0
  139. package/src/DocumentField.test.tsx +281 -0
  140. package/src/DocumentField.tsx +199 -0
  141. package/src/EditableText.buttons.test.tsx +318 -0
  142. package/src/EditableText.mdx +50 -2
  143. package/src/EditableText.stories.tsx +96 -2
  144. package/src/EditableText.tsx +189 -5
  145. package/src/EmptyState.mdx +33 -8
  146. package/src/EmptyState.stories.tsx +26 -1
  147. package/src/EmptyState.test.tsx +63 -2
  148. package/src/EmptyState.tsx +28 -6
  149. package/src/Form.mdx +3 -1
  150. package/src/FormDialog.mdx +78 -0
  151. package/src/FormDialog.stories.tsx +90 -0
  152. package/src/FormDialog.test.tsx +183 -0
  153. package/src/FormDialog.tsx +93 -0
  154. package/src/InlineText.mdx +1 -0
  155. package/src/InlineText.tsx +2 -1
  156. package/src/Menu.test.tsx +80 -0
  157. package/src/Menu.tsx +35 -14
  158. package/src/MenuItem.mdx +12 -0
  159. package/src/MenuItem.stories.tsx +39 -1
  160. package/src/MoveDialog.mdx +85 -0
  161. package/src/MoveDialog.stories.tsx +134 -0
  162. package/src/MoveDialog.test.tsx +239 -0
  163. package/src/MoveDialog.tsx +186 -0
  164. package/src/NavItem.mdx +15 -0
  165. package/src/NavItem.stories.tsx +15 -0
  166. package/src/NavItem.test.tsx +64 -1
  167. package/src/NavItem.tsx +10 -2
  168. package/src/NavTree.mdx +26 -4
  169. package/src/NavTree.stories.tsx +59 -0
  170. package/src/NavTree.test.tsx +232 -2
  171. package/src/NavTree.tsx +93 -43
  172. package/src/PinnedComment.mdx +6 -1
  173. package/src/PinnedComment.stories.tsx +11 -1
  174. package/src/PinnedComment.tsx +15 -2
  175. package/src/ReactionHorizon.mdx +2 -0
  176. package/src/ReactionHorizon.stories.tsx +3 -0
  177. package/src/ReactionHorizon.test.tsx +32 -0
  178. package/src/ReactionHorizon.tsx +28 -11
  179. package/src/RepliesRow.mdx +6 -3
  180. package/src/RepliesRow.stories.tsx +3 -0
  181. package/src/RepliesRow.test.tsx +24 -0
  182. package/src/RepliesRow.tsx +12 -6
  183. package/src/ReplyCard.mdx +8 -0
  184. package/src/ReplyCard.stories.tsx +45 -1
  185. package/src/ResolveDialog.mdx +2 -0
  186. package/src/ResolveDialog.test.tsx +21 -0
  187. package/src/ResolveDialog.tsx +11 -39
  188. package/src/SelectionToolbar.tsx +2 -2
  189. package/src/Textarea.mdx +1 -0
  190. package/src/Thread.mdx +20 -1
  191. package/src/Thread.stories.tsx +94 -3
  192. package/src/Thread.test.tsx +11 -0
  193. package/src/Thread.tsx +56 -12
  194. package/src/commentBoxFrame.tsx +2 -2
  195. package/src/conversation.examples.tsx +10 -2
  196. package/src/conversationScroll.ts +155 -0
  197. package/src/editor.ts +1 -0
  198. package/src/editorSelection.test.tsx +53 -0
  199. package/src/eslint/no-field-outside-a-form.test.ts +4 -0
  200. package/src/eslint/no-field-outside-a-form.ts +2 -2
  201. package/src/eslint/no-native-title.ts +1 -1
  202. package/src/formBusy.ts +5 -2
  203. package/src/index.ts +16 -6
  204. package/src/looks.ts +10 -0
  205. package/src/registry/registry.test.ts +12 -6
  206. package/src/seenOnScreen.test.tsx +241 -0
  207. package/src/seenOnScreen.ts +146 -0
  208. package/src/showInConversation.test.tsx +168 -0
  209. package/src/showInConversation.ts +93 -0
  210. package/src/threadCard.ts +16 -0
  211. package/stories/Choosing.mdx +8 -3
  212. package/tailwind-preset.js +7 -0
@@ -338,3 +338,136 @@ describe('ConversationLayout, two columns, what an app with its own list keeps (
338
338
  expect(screen.queryByText('No comments yet.')).toBeNull()
339
339
  })
340
340
  })
341
+
342
+ /**
343
+ * The right column holds what the page shows beside its comments when no thread is open (B1 of the audit of 2 November):
344
+ * Peek's Overview, which Peek drew in a 380px column of its own, with the thread put in it by hand. Now the layout's
345
+ * 384px column holds both.
346
+ */
347
+ describe('ConversationLayout, two columns, the right column', () => {
348
+ const column = () => document.querySelector('.border-l') as HTMLElement | null
349
+
350
+ it('shows the app’s aside while no thread is open, and the thread in its place while one is', () => {
351
+ function Page() {
352
+ const [open, setOpen] = useState<string | undefined>()
353
+ return <ConversationLayout threads="beside" items={items('beside')} open={open} onOpenChange={setOpen} aside={<p>The overview</p>} />
354
+ }
355
+ render(<Page />)
356
+ expect(column()?.textContent).toBe('The overview')
357
+ expect(column()?.className).toContain('w-[384px]')
358
+ fireEvent.click(screen.getByText('With replies'))
359
+ expect(screen.queryByText('The overview')).toBeNull()
360
+ expect(column()?.textContent).toContain('A reply')
361
+ })
362
+
363
+ it('a thread the app draws only while it is open (a function) opens from its card, and is drawn only then', () => {
364
+ const drawn = vi.fn((words: string) => <Thread start={{ author: ONE, time: '11:08 AM', words }}><p>Replies to {words}</p></Thread>)
365
+ function Page() {
366
+ const [open, setOpen] = useState<string | undefined>()
367
+ const list: ConversationItem[] = ['First', 'Second'].map((words) => ({
368
+ id: words,
369
+ card: <ConversationCard author={ONE} time="11:08 AM">{words}</ConversationCard>,
370
+ thread: () => drawn(words),
371
+ }))
372
+ return <ConversationLayout threads="beside" items={list} open={open} onOpenChange={setOpen} />
373
+ }
374
+ render(<Page />)
375
+ expect(drawn).not.toHaveBeenCalled()
376
+ fireEvent.click(screen.getByText('Second'))
377
+ expect(screen.getByText('Replies to Second')).toBeTruthy()
378
+ expect(drawn.mock.calls.every(([words]) => words === 'Second')).toBe(true)
379
+ })
380
+
381
+ it('keeps the comments when what is in the column throws: the column says so in its place', () => {
382
+ const quiet = vi.spyOn(console, 'error').mockImplementation(() => {})
383
+ function Throws(): never {
384
+ throw new Error('an aside that throws')
385
+ }
386
+ render(<ConversationLayout threads="beside" items={items('beside')} aside={<Throws />} />)
387
+ expect(screen.getByText('With replies')).toBeTruthy()
388
+ expect(column()?.textContent).toContain('Something went wrong in the thread panel.')
389
+ quiet.mockRestore()
390
+ })
391
+
392
+ it('lets a thread that threw go: closing it draws the aside again, and another thread draws itself', () => {
393
+ const quiet = vi.spyOn(console, 'error').mockImplementation(() => {})
394
+ function Throws(): never {
395
+ throw new Error('a thread that throws')
396
+ }
397
+ const list: ConversationItem[] = [
398
+ { id: 'c1', card: <ConversationCard author={ONE} time="11:08 AM">First</ConversationCard>, thread: <Throws /> },
399
+ { id: 'c2', card: <ConversationCard author={ONE} time="11:08 AM">Second</ConversationCard>, thread: <p>Thread two</p> },
400
+ ]
401
+ try {
402
+ const { rerender } = render(<ConversationLayout threads="beside" items={list} open="c1" aside={<p>The overview</p>} />)
403
+ expect(column()?.textContent).toContain('Something went wrong in the thread panel.')
404
+ rerender(<ConversationLayout threads="beside" items={list} aside={<p>The overview</p>} />)
405
+ expect(column()?.textContent).toBe('The overview')
406
+ rerender(<ConversationLayout threads="beside" items={list} open="c1" aside={<p>The overview</p>} />)
407
+ expect(column()?.textContent).toContain('Something went wrong in the thread panel.')
408
+ rerender(<ConversationLayout threads="beside" items={list} open="c2" aside={<p>The overview</p>} />)
409
+ expect(column()?.textContent).toBe('Thread two')
410
+ } finally {
411
+ quiet.mockRestore()
412
+ }
413
+ })
414
+
415
+ it('draws no column with no aside and no thread open', () => {
416
+ render(<ConversationLayout threads="beside" items={items('beside')} />)
417
+ expect(column()).toBeNull()
418
+ })
419
+ })
420
+
421
+ describe('ConversationLayout, one column, under the comments (below; Ship, 2 November)', () => {
422
+ it('draws `below` under the comments, the groups too, inside the column that scrolls and above the box', () => {
423
+ const resolved: ConversationItem = {
424
+ id: 'r',
425
+ resolved: true,
426
+ card: (
427
+ <ConversationCard author={ONE} time="12:15 PM">
428
+ Resolved one
429
+ </ConversationCard>
430
+ ),
431
+ }
432
+ render(<ConversationLayout threads="under" items={[...items('under'), resolved]} below={<p>Reactions note</p>} box={<p>The box</p>} />)
433
+ const note = screen.getByText('Reactions note')
434
+ const follows = (a: Node, b: Node) => !!(a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING)
435
+ expect(follows(screen.getByText('No replies yet'), note)).toBe(true)
436
+ expect(follows(screen.getByRole('button', { name: /Resolved/ }), note)).toBe(true)
437
+ expect(follows(note, screen.getByText('The box'))).toBe(true)
438
+ // In the comments' own box, the one that scrolls: not in the footer with the box.
439
+ expect(note.closest('[data-conversation-item]')).toBeNull()
440
+ expect(screen.getByText('The box').parentElement?.contains(note)).toBe(false)
441
+ })
442
+
443
+ it('under the empty line too, and not while the comments are read', () => {
444
+ render(<ConversationLayout threads="under" items={[]} below={<p>Reactions note</p>} />)
445
+ expect(screen.getByText('Reactions note')).toBeTruthy()
446
+ cleanup()
447
+ render(<ConversationLayout threads="under" items={[]} loading below={<p>Reactions note</p>} />)
448
+ expect(screen.queryByText('Reactions note')).toBeNull()
449
+ })
450
+ })
451
+
452
+ describe('ConversationLayout, one column, the note sits on the box (Katerina, 2 November: as in Peek)', () => {
453
+ it('pushes `below` to the foot of a column at least as tall as its room, the comments staying at the top', () => {
454
+ render(<ConversationLayout threads="under" items={items('under')} below={<p>Reactions note</p>} box={<p>The box</p>} />)
455
+ const pushed = screen.getByText('Reactions note').closest('.mt-auto')
456
+ expect(pushed).not.toBeNull()
457
+ const body = pushed!.parentElement!
458
+ // The scrolling box's content is at least the column's height, so the room a short conversation leaves is above the note.
459
+ expect(body.className.split(/\s+/)).toContain('min-h-full')
460
+ // Only the note moves: the comments are the body's first children, and none is pushed.
461
+ const first = document.querySelector('[data-conversation-item="a"]')!
462
+ expect(body.firstElementChild).toBe(first)
463
+ expect(document.querySelectorAll('[data-conversation-item].mt-auto, [data-conversation-item] .mt-auto').length).toBe(0)
464
+ })
465
+
466
+ it('pushes nothing while the comments are read, and with no note', () => {
467
+ const { container } = render(<ConversationLayout threads="under" items={[]} loading below={<p>Reactions note</p>} />)
468
+ expect(container.querySelector('.mt-auto')).toBeNull()
469
+ cleanup()
470
+ const again = render(<ConversationLayout threads="under" items={items('under')} />)
471
+ expect(again.container.querySelector('.mt-auto')).toBeNull()
472
+ })
473
+ })
@@ -1,24 +1,30 @@
1
- import { Fragment, useEffect, useLayoutEffect, useRef, useState, type ReactNode, type Ref, type UIEventHandler } from 'react'
1
+ import { Fragment, useCallback, useEffect, useLayoutEffect, useRef, useState, type ReactNode, type Ref, type UIEvent, type UIEventHandler } from 'react'
2
2
  import { Card } from './Card'
3
3
  import { Chip } from './Chip'
4
4
  import { CollapsibleSection } from './CollapsibleSection'
5
5
  import { cn } from './cn'
6
6
  import { ContainerHeader } from './ContainerHeader'
7
+ import { anchorIn, cardIn, isNearBottom, places, sendsInLayout, useSteadyScroll } from './conversationScroll'
7
8
  import { Divider } from './Divider'
8
9
  import { EmptyState } from './EmptyState'
9
10
  import { ErrorBoundary } from './ErrorBoundary'
10
11
  import { Panel } from './Panel'
11
12
  import { ScrollArea } from './ScrollArea'
13
+ import { useWatchSeen, type SeenOnScreen } from './seenOnScreen'
12
14
  import { SkeletonConversation } from './Skeleton'
13
- import { caretOnOpen, InConversationItem, InThreadCard, LineByLayout, useFaceLine, type ConversationItemState } from './threadCard'
15
+ import { caretOnOpen, InConversationItem, InThreadCard, LineByLayout, SHOWN_CLASSES, useFaceLine, type ConversationItemState } from './threadCard'
14
16
 
15
17
  /** One comment in the list, and its thread when it is open. */
16
18
  export interface ConversationItem {
17
19
  id: string
18
20
  /** The comment: a `ConversationCard`. */
19
21
  card: ReactNode
20
- /** Its thread: a `Thread` with the same `place` as the layout's `threads`, drawn while it is the open one. Give every comment one, even with no replies yet: a card without one cannot be opened. */
21
- thread?: ReactNode
22
+ /**
23
+ * Its thread: a `Thread` with the same `place` as the layout's `threads`, drawn while it is the open one. Give every
24
+ * comment one, even with no replies yet: a card without one cannot be opened. Or a function that draws it, called
25
+ * only while it is the open one: for an app that builds only the open thread.
26
+ */
27
+ thread?: ReactNode | (() => ReactNode)
22
28
  /** Resolved. In one column it waits under "Resolved", closed, at the end; in two columns it stays in its place. */
23
29
  resolved?: boolean
24
30
  /** What it was on was deleted from the page. In one column it waits under "On deleted blocks", closed, before "Resolved"; a resolved one is under "Resolved". */
@@ -35,6 +41,8 @@ export interface ConversationLayoutProps {
35
41
  items: readonly ConversationItem[]
36
42
  /** The id of the comment whose thread is open. */
37
43
  open?: string
44
+ /** Two columns: what the 384px column holds while no thread is open, the page's own panel beside its comments (an overview). Nothing: no column. */
45
+ aside?: ReactNode
38
46
  /**
39
47
  * A comment asks to open or close its thread: a press anywhere on its card, its replies row, or Reply. In one column
40
48
  * a second press closes it. The layout draws it open in place, with no jump, and puts the caret in its box; the app
@@ -45,7 +53,7 @@ export interface ConversationLayoutProps {
45
53
  box?: ReactNode
46
54
  /** Above the comments, inside their list: placeholders while older comments are read, a note. */
47
55
  above?: ReactNode
48
- /** Two columns: under the comments, inside their list, or under the empty line: a `ReactionHorizon`. Not while the comments are read. */
56
+ /** Under the comments, inside their list, or under the empty line: a `ReactionHorizon`, or the app's own note. One column: after "Resolved" too, at the column's foot, so with few comments it sits on the box. Not while the comments are read. */
49
57
  below?: ReactNode
50
58
  /** Two columns: at the top of the column however few the comments are, over the room a short conversation leaves: an `ArchivedNotice`. */
51
59
  top?: ReactNode
@@ -53,10 +61,18 @@ export interface ConversationLayoutProps {
53
61
  loading?: boolean
54
62
  /** What an empty conversation says: words, or the app's own `EmptyState` (a read that failed says so). `null`: nothing. */
55
63
  empty?: ReactNode
56
- /** Two columns: the comments' scrolling box, for an app that keeps its own place in it (where it was left, its "New" line, following what arrives). */
64
+ /**
65
+ * Two columns: the conversation's own name in the app (its address). Where the reader left it is remembered by it in
66
+ * this tab, and going back to it lands there: at the newest if it was left there, else on the same comment. Without
67
+ * it, it opens at the newest each time it is drawn. `useLeftAt` with the same name says when it was left, for a "New" line.
68
+ */
69
+ rememberAs?: string
70
+ /** Two columns: the comments' scrolling box. Where it scrolls is the layout's: an app reads it, and keeps no place of its own in it. */
57
71
  bodyRef?: Ref<HTMLDivElement>
58
72
  /** Two columns: the comments' box scrolled. */
59
73
  onBodyScroll?: UIEventHandler<HTMLDivElement>
74
+ /** What `useSeenOnScreen` made for this conversation: the layout watches its comments, and says in it which were seen. */
75
+ seen?: SeenOnScreen
60
76
  /** Two columns: the comments' own header, a `PageHeader`, over their column only, so the thread beside them runs the page's full height (Peek's way). */
61
77
  header?: ReactNode
62
78
  /** Its name: one column's, in its header. Two columns, said with the message if the column breaks (the page's own bar is `header`). */
@@ -80,6 +96,9 @@ interface ListProps {
80
96
  caret: number
81
97
  }
82
98
 
99
+ /** An item's thread as it is drawn: the app's element, or what its function draws, asked only while it is open. */
100
+ const threadOf = (item: ConversationItem | undefined): ReactNode => (typeof item?.thread === 'function' ? item.thread() : item?.thread)
101
+
83
102
  /** The list's own room: placeholders, the empty line, or the comments 8px apart. */
84
103
  function List({ items, open, under, above, loading, empty, change, caret }: ListProps) {
85
104
  if (loading) return <SkeletonConversation />
@@ -99,7 +118,7 @@ function List({ items, open, under, above, loading, empty, change, caret }: List
99
118
  return (
100
119
  <Fragment key={item.id}>
101
120
  {item.before}
102
- <div data-conversation-item={item.id} className="flex flex-col">
121
+ <div data-conversation-item={item.id} className={cn('flex flex-col', SHOWN_CLASSES)}>
103
122
  <InConversationItem.Provider value={stateOf(item)}>{item.card}</InConversationItem.Provider>
104
123
  </div>
105
124
  </Fragment>
@@ -189,14 +208,14 @@ function UnderItem({ item, isOpen, state, caret }: { item: ConversationItem; isO
189
208
  hover="hairline"
190
209
  hovered={isOpen}
191
210
  quietUntilHover={!isOpen}
192
- className={cn('relative flex flex-col', isOpen && 'pb-2')}
211
+ className={cn('relative flex flex-col', isOpen && 'pb-2', SHOWN_CLASSES)}
193
212
  >
194
213
  <InConversationItem.Provider value={state}>
195
214
  <InThreadCard.Provider value={isOpen}>
196
215
  <LineByLayout.Provider value>
197
216
  {/* Over this card's edge, 1px out each way: the comment keeps its place and width, open or closed. */}
198
217
  <div className="-m-px flex flex-col">{item.card}</div>
199
- {isOpen && <caretOnOpen.Provider value={caret}>{item.thread}</caretOnOpen.Provider>}
218
+ {isOpen && <caretOnOpen.Provider value={caret}>{threadOf(item)}</caretOnOpen.Provider>}
200
219
  </LineByLayout.Provider>
201
220
  </InThreadCard.Provider>
202
221
  </InConversationItem.Provider>
@@ -209,6 +228,9 @@ function UnderItem({ item, isOpen, state, caret }: { item: ConversationItem; isO
209
228
  )
210
229
  }
211
230
 
231
+ /** The place of a conversation with no name: placed once each time it is drawn, and not remembered. */
232
+ const FRESH: object = {}
233
+
212
234
  /**
213
235
  * Where a conversation's cards sit, in one of two ways every app picks from (where it sits is the app's, the record
214
236
  * says). Two columns: the comments fill the page and an open thread stands beside them, 384px. One column: the
@@ -219,6 +241,7 @@ export function ConversationLayout({
219
241
  threads,
220
242
  items,
221
243
  open,
244
+ aside,
222
245
  onOpenChange,
223
246
  box,
224
247
  above,
@@ -229,14 +252,28 @@ export function ConversationLayout({
229
252
  header,
230
253
  title = 'Comments',
231
254
  actions,
255
+ rememberAs,
232
256
  bodyRef,
233
257
  onBodyScroll,
258
+ seen,
234
259
  className,
235
260
  }: ConversationLayoutProps) {
261
+ const beside = threads === 'beside'
236
262
  // One column: the pressed comment stays where it was on screen. Opening one thread closes the other, and when that
237
263
  // one stood above it, everything under it would rise by its height (Katerina, 31 October). Where it was is noted at
238
264
  // the press; once the change is drawn, before it is painted, the column scrolls by however far it went.
239
265
  const body = useRef<HTMLDivElement>(null)
266
+ // The comments' box is the layout's, and lent to the app as `bodyRef`.
267
+ const setBody = useCallback(
268
+ (el: HTMLDivElement | null) => {
269
+ body.current = el
270
+ if (typeof bodyRef === 'function') bodyRef(el)
271
+ else if (bodyRef) bodyRef.current = el
272
+ },
273
+ [bodyRef],
274
+ )
275
+ // A comment is read by being seen (Peek's way, Katerina, 30 October): each one in the list is watched.
276
+ useWatchSeen(seen, body, 'data-conversation-item')
240
277
  const pressed = useRef<{ id: string; top: number } | null>(null)
241
278
  const itemAt = (id: string) => body.current?.querySelector<HTMLElement>(`[data-conversation-item="${CSS.escape(id)}"]`) ?? null
242
279
  // A thread that opens puts the caret in its box (Katerina, 31 October); the one open when the page is drawn does not.
@@ -266,14 +303,93 @@ export function ConversationLayout({
266
303
  if (open !== undefined && open !== was.current) setCaret((n) => n + 1)
267
304
  was.current = open
268
305
  }, [open])
306
+
307
+ /*
308
+ Two columns: where the comments scroll, Peek's way (C1 of the audit of 2 November). Was the reader at the live edge
309
+ when something arrived? Only then does it follow: a comment that arrives follows only a reader already at the bottom.
310
+ */
311
+ const nearBottom = useRef(true)
312
+ // The conversation placed last: once per name (once per drawing, without one), and once its comments are read;
313
+ // none while they are being read. Where the reader is is recorded only while it is placed.
314
+ const placedFor = useRef<string | object | null>(null)
315
+ const placeKey = rememberAs ?? FRESH
316
+ const scrolled = (event: UIEvent<HTMLDivElement>) => {
317
+ const el = body.current
318
+ if (beside && el) {
319
+ nearBottom.current = isNearBottom(el)
320
+ if (rememberAs && placedFor.current === rememberAs) places.set(rememberAs, { atBottom: nearBottom.current, offset: el.scrollTop, anchor: anchorIn(el), leftAt: Date.now() })
321
+ }
322
+ onBodyScroll?.(event)
323
+ }
324
+ // Opening lands at the newest, before the paint. Going back to one lands where it was left (Peek's OPT-3): at the
325
+ // newest if it was left there, so what arrived meanwhile is in view; else on the comment that was at the top.
326
+ useLayoutEffect(() => {
327
+ if (!beside) return
328
+ if (loading) {
329
+ // Its placeholders stand in its comments' place: once they are read it is placed again, and meanwhile nothing
330
+ // is recorded, so the offset the shorter placeholders pull it to is never taken for where the reader left it.
331
+ placedFor.current = null
332
+ return
333
+ }
334
+ if (placedFor.current === placeKey) return
335
+ const el = body.current
336
+ if (!el) return
337
+ const left = rememberAs ? places.get(rememberAs) : undefined
338
+ if (left && !left.atBottom) {
339
+ // That comment back at the same height, not the same offset: what is above it can change height while the
340
+ // reader is away (a "new reply" mark cleared once read, a reactions line).
341
+ el.scrollTop = left.offset
342
+ const card = left.anchor && cardIn(el, left.anchor.id)
343
+ if (card && left.anchor) el.scrollTop += card.getBoundingClientRect().top - el.getBoundingClientRect().top - left.anchor.top
344
+ nearBottom.current = false
345
+ } else {
346
+ el.scrollTop = el.scrollHeight
347
+ nearBottom.current = true
348
+ if (rememberAs) places.set(rememberAs, { atBottom: true, offset: el.scrollTop, leftAt: Date.now() })
349
+ }
350
+ placedFor.current = placeKey
351
+ }, [beside, placeKey, rememberAs, loading])
352
+ // From there, it stays where the reader is while its cards, chips and pictures fill in (Peek's OPT-10).
353
+ const placed = useCallback(() => placedFor.current === placeKey, [placeKey])
354
+ useSteadyScroll(body, nearBottom, placed, loading, beside)
355
+ // Leaving: the moment it was left is when "New" starts on the way back.
356
+ useEffect(() => {
357
+ if (!beside || !rememberAs) return
358
+ return () => {
359
+ const left = places.get(rememberAs)
360
+ if (left) places.set(rememberAs, { ...left, leftAt: Date.now() })
361
+ }
362
+ }, [beside, rememberAs])
363
+ // A comment arrives: follow only a reader who was watching the live edge.
364
+ useLayoutEffect(() => {
365
+ if (!beside || loading || !nearBottom.current) return
366
+ const el = body.current
367
+ if (el) el.scrollTop = el.scrollHeight
368
+ }, [beside, items.length, loading])
369
+ // The reader's own comment, sent from the box, brings them down to it as it is drawn (Peek's OPT-6); a refusal leaves
370
+ // where they actually are to decide what follows next.
371
+ const [sends] = useState(() => ({
372
+ sending: () => {
373
+ nearBottom.current = true
374
+ },
375
+ refused: () => {
376
+ if (body.current) nearBottom.current = isNearBottom(body.current)
377
+ },
378
+ }))
269
379
  if (threads === 'under') {
270
380
  return (
271
- <Panel className={cn('w-[384px] flex-none', className)} title={title} actions={actions} bodyRef={body} bodyClassName="flex flex-col gap-2 p-3" footer={box && <div className="p-3">{box}</div>}>
381
+ // The body at least the column's height: the comments start at its top, and the note under them (`below`) is pushed
382
+ // to its foot, so with few comments it sits on the box, as a short conversation's last line does in Peek's two
383
+ // columns (Katerina, 2 November); with many it comes after them, and scrolls with them.
384
+ <Panel className={cn('w-[384px] flex-none', className)} title={title} actions={actions} bodyRef={setBody} bodyClassName="flex min-h-full flex-col gap-2 p-3" footer={box && <div className="p-3">{box}</div>}>
272
385
  <List items={items} open={open} under above={above} loading={loading} empty={empty} change={change} caret={caret} />
386
+ {!loading && below != null && below !== false && below !== '' && <div className="mt-auto flex flex-col gap-2">{below}</div>}
273
387
  </Panel>
274
388
  )
275
389
  }
276
- const opened = items.find((item) => item.id === open)?.thread
390
+ const opened = threadOf(items.find((item) => item.id === open))
391
+ // The column: the open thread, or while none is, the page's own panel (Peek's Overview); neither, no column.
392
+ const side = opened || aside
277
393
  return (
278
394
  <div className={cn('flex min-h-0 min-w-0 flex-1', className)}>
279
395
  {/* If the column throws, its name stays with the message, as a Panel's does; the thread beside it stays. */}
@@ -288,7 +404,7 @@ export function ConversationLayout({
288
404
  >
289
405
  <div className="flex min-h-0 min-w-0 flex-1 flex-col">
290
406
  {header}
291
- <ScrollArea className="min-h-0 flex-1" viewportRef={bodyRef} onScroll={onBodyScroll} contentClassName="flex min-h-full flex-col">
407
+ <ScrollArea className="min-h-0 flex-1" viewportRef={setBody} onScroll={scrolled} contentClassName="flex min-h-full flex-col">
292
408
  {top != null && top !== false && top !== '' && <div className="shrink-0 px-4 pt-4">{top}</div>}
293
409
  {/* A short conversation sits on its box, as a chat does: the newest comment by the box (Peek's way). */}
294
410
  <div className="min-h-0 flex-1" />
@@ -298,12 +414,21 @@ export function ConversationLayout({
298
414
  </div>
299
415
  </ScrollArea>
300
416
  {/* Peek's composer room: 12px all round (useFileConversationView's `p-3`), under the list's 16px. */}
301
- {box && <div className="shrink-0 p-3">{box}</div>}
417
+ {box && (
418
+ <div className="shrink-0 p-3">
419
+ <sendsInLayout.Provider value={sends}>{box}</sendsInLayout.Provider>
420
+ </div>
421
+ )}
302
422
  </div>
303
423
  </ErrorBoundary>
304
- {opened && (
305
- <div className="flex w-[384px] shrink-0 flex-col border-l border-border-subtle">
306
- <caretOnOpen.Provider value={caret}>{opened}</caretOnOpen.Provider>
424
+ {side && (
425
+ // Its own catch, as Peek's column had: a thread or a panel that throws says so in the column, and the comments stay.
426
+ // One catch per thread, and one for the aside: a thread that threw is let go once it is closed or another opens,
427
+ // as Peek's column, drawn only while a thread was open, let it go on closing. Each thread is drawn afresh.
428
+ <div className="flex w-[384px] shrink-0 flex-col overflow-hidden border-l border-border-subtle">
429
+ <ErrorBoundary key={opened ? `thread:${open}` : 'aside'} label="thread panel">
430
+ {opened ? <caretOnOpen.Provider value={caret}>{opened}</caretOnOpen.Provider> : aside}
431
+ </ErrorBoundary>
307
432
  </div>
308
433
  )}
309
434
  </div>
@@ -14,9 +14,12 @@ The ⋯ menu of a comment or a reply: Resolve or Reopen and the app's own rows;
14
14
  - Inside **ConversationCard** and **ReplyCard**, which draw it for you.
15
15
  - Its `children` are the app's own rows, after Resolve; `after`, its rows after Edit.
16
16
  - In the app's own words: `label` heads the first rows, `resolveHint` stands beside Resolve, `editLabel` is Edit's word. Peek's menu reads as it did with them (Katerina, 1 November).
17
+ - `deleteLabel` is Delete's words ("Delete message"), and `moreLabel` names its own ⋯ button, its tooltip too, when no `trigger` is given ("More actions" by default; "Message actions"). Ship's menu reads as it did with them (2 November).
17
18
 
18
19
  <Canvas of={Stories.InAnAppsWords} />
19
20
 
21
+ <Canvas of={Stories.OwnButtonInAnAppsWords} />
22
+
20
23
  <Canvas of={Stories.Theirs} />
21
24
 
22
25
  <Canvas of={Stories.MoreRows} />
@@ -41,6 +41,18 @@ export const MoreRows: Story = {
41
41
  args: { onResolve: () => {}, onEdit: () => {}, onDelete: () => {}, children: <MenuItem label="Item one" onClick={() => {}} /> },
42
42
  }
43
43
 
44
+ /**
45
+ * Its own ⋯ button and its Delete row in an app's own words: the button named "Message actions", its tooltip too, and
46
+ * "Delete message". With no `trigger`, the menu draws its own ⋯; the story presses it.
47
+ */
48
+ export const OwnButtonInAnAppsWords: Story = {
49
+ name: "Its own button, in an app's words",
50
+ args: { trigger: undefined, moreLabel: 'Message actions', onEdit: () => {}, editLabel: 'Edit message', onDelete: () => {}, deleteLabel: 'Delete message' },
51
+ play: async ({ canvasElement }) => {
52
+ await userEvent.click(within(canvasElement).getByRole('button', { name: 'Message actions' }))
53
+ },
54
+ }
55
+
44
56
  /**
45
57
  * In an app's own words, as Peek's menu reads (Katerina, 1 November): a heading over the first rows, the key that
46
58
  * resolves from its box beside Resolve, its word for Edit, and a row of its own after Edit. Delete stays apart.
@@ -1,6 +1,7 @@
1
1
  // @vitest-environment jsdom
2
2
  import { afterEach, describe, expect, it, vi } from 'vitest'
3
3
  import { cleanup, fireEvent, render, screen } from '@testing-library/react'
4
+ import userEvent from '@testing-library/user-event'
4
5
  import { ConversationMenu } from './ConversationMenu'
5
6
  import { MenuItem } from './Menu'
6
7
 
@@ -58,3 +59,19 @@ describe('ConversationMenu', () => {
58
59
  expect(screen.getAllByRole('separator').length).toBe(2)
59
60
  })
60
61
  })
62
+
63
+ describe('ConversationMenu, in an app’s words (Ship, 2 November)', () => {
64
+ it('says Delete in the app’s words, and names its own ⋯ button so, its tooltip too', async () => {
65
+ const user = userEvent.setup()
66
+ const onDelete = vi.fn()
67
+ render(<ConversationMenu onEdit={() => {}} editLabel="Edit message" onDelete={onDelete} deleteLabel="Delete message" moreLabel="Message actions" />)
68
+ const more = screen.getByRole('button', { name: 'Message actions' })
69
+ await user.hover(more)
70
+ expect((await screen.findByRole('tooltip')).textContent).toBe('Message actions')
71
+ fireEvent.click(more)
72
+ await screen.findByRole('menu')
73
+ expect(names()).toEqual(['Edit message', 'Delete message'])
74
+ fireEvent.click(screen.getByRole('menuitem', { name: 'Delete message' }))
75
+ expect(onDelete).toHaveBeenCalledOnce()
76
+ })
77
+ })
@@ -22,6 +22,10 @@ export interface ConversationMenuProps {
22
22
  after?: ReactNode
23
23
  /** Offered on your own only; the card asks before it deletes. */
24
24
  onDelete?: () => void
25
+ /** Delete's words: "Delete" by default; Ship's "Delete message". */
26
+ deleteLabel?: string
27
+ /** Its own ⋯ button's name and tooltip, with no `trigger`: "More actions" by default; Ship's "Message actions". */
28
+ moreLabel?: string
25
29
  open?: boolean
26
30
  onOpenChange?: (open: boolean) => void
27
31
  /** The button that opens it: a `ToolbarButton` inside `ConversationActions`. Absent: an `IconButton`. */
@@ -34,7 +38,7 @@ export interface ConversationMenuProps {
34
38
  * row to show. Peek's, moved with the conversation; what is Peek's own (its heading, its hint, its words, its rows)
35
39
  * Peek passes in, so its menu reads as it did (Katerina, 1 November).
36
40
  */
37
- export function ConversationMenu({ resolved = false, onResolve, onReopen, resolveHint, children, label, onEdit, editLabel = 'Edit', after, onDelete, open, onOpenChange, trigger }: ConversationMenuProps) {
41
+ export function ConversationMenu({ resolved = false, onResolve, onReopen, resolveHint, children, label, onEdit, editLabel = 'Edit', after, onDelete, deleteLabel = 'Delete', moreLabel = 'More actions', open, onOpenChange, trigger }: ConversationMenuProps) {
38
42
  const resolves = resolved ? onReopen : onResolve
39
43
  const first = (resolves || children) && (
40
44
  <>
@@ -57,7 +61,7 @@ export function ConversationMenu({ resolved = false, onResolve, onReopen, resolv
57
61
  <Menu
58
62
  trigger={
59
63
  trigger ?? (
60
- <IconButton tooltip="More actions" aria-label="More actions">
64
+ <IconButton tooltip={moreLabel} aria-label={moreLabel}>
61
65
  <IconDotsVertical size={16} stroke={1.5} />
62
66
  </IconButton>
63
67
  )
@@ -72,7 +76,7 @@ export function ConversationMenu({ resolved = false, onResolve, onReopen, resolv
72
76
  {first && middle && <MenuSeparator />}
73
77
  {middle}
74
78
  {onDelete && (first || middle) && <MenuSeparator />}
75
- {onDelete && <MenuItem label="Delete" destructive onClick={onDelete} />}
79
+ {onDelete && <MenuItem label={deleteLabel} destructive onClick={onDelete} />}
76
80
  </Menu>
77
81
  )
78
82
  }
@@ -0,0 +1,53 @@
1
+ import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
2
+ import * as Stories from './ConversationPlace.stories'
3
+
4
+ <Meta of={Stories} />
5
+
6
+ # ConversationPlace
7
+
8
+ Above a conversation shown away from where it was said: how it is related, and where it was said.
9
+
10
+ <Canvas of={Stories.MentionedIn} />
11
+
12
+ ## When
13
+
14
+ - A list of conversations from elsewhere on a page's Activity: each card under the line saying how it is related to the page (`relation`, "Mentioned in") and the place's name (`place`).
15
+ - Another relation, in your words: the same line, the same look.
16
+
17
+ <Canvas of={Stories.OnAnItemUnderIt} />
18
+
19
+ - The place's name has not come yet: leave `place` out. The relation is drawn alone, never a placeholder: "Loading…" beside a real comment reads worse than a line that has not said where it is from yet.
20
+
21
+ <Canvas of={Stories.PlaceNotNamedYet} />
22
+
23
+ <Canvas of={Stories.LongPlace} />
24
+
25
+ ## When not
26
+
27
+ - The conversation is on this page: its card alone → **ConversationCard**.
28
+ - A comment on a part of the page: what it is on goes inside the card, in its `about` → **QuotedLine**.
29
+
30
+ ## How
31
+
32
+ ```tsx
33
+ import { ConversationCard, ConversationPlace } from '@estiva-app/ui'
34
+
35
+ <ConversationPlace relation="Mentioned in" place={nameOf(address)} data-relation="mention">
36
+ <ConversationCard author={author} time={time} readOnly onClick={openWhereSaid}>
37
+ {words}
38
+ </ConversationCard>
39
+ </ConversationPlace>
40
+ ```
41
+
42
+ - The words are yours: `relation` is how the conversation is related, `place` the name your app gives the place.
43
+ - The card is yours too: it goes in as `children`, under the line, 4px below it.
44
+ - The place's name is cut to the column.
45
+ - Anything else you pass (a `data-…` mark) lands on the row, so you can find it.
46
+
47
+ ## What it owns
48
+
49
+ Nothing. It only draws. Clicks and keys are yours.
50
+
51
+ ## Props
52
+
53
+ <Controls />
@@ -0,0 +1,48 @@
1
+ import type { Meta, StoryObj } from '@storybook/react-vite'
2
+ import { ConversationCard } from './ConversationCard'
3
+ import { Column, ONE, TWO, WORDS } from './conversation.examples'
4
+ import { ConversationPlace } from './ConversationPlace'
5
+
6
+ /**
7
+ * Where a conversation shown away from its place was said, above its card: how it is related, and the place's name.
8
+ * The words are the app's; these are the ones the specification uses (SPEC §6.4).
9
+ */
10
+ const meta = {
11
+ title: 'Conversation/ConversationPlace',
12
+ component: ConversationPlace,
13
+ parameters: { layout: 'padded' },
14
+ args: { relation: 'Mentioned in', place: 'Item one' },
15
+ argTypes: { children: { control: false } },
16
+ decorators: [(Story) => <Column>{Story()}</Column>],
17
+ render: (args) => (
18
+ <ConversationPlace {...args}>
19
+ <ConversationCard author={ONE} time="11:08 AM" readOnly onClick={() => {}}>
20
+ {WORDS}
21
+ </ConversationCard>
22
+ </ConversationPlace>
23
+ ),
24
+ } satisfies Meta<typeof ConversationPlace>
25
+
26
+ export default meta
27
+ type Story = StoryObj<typeof meta>
28
+
29
+ /** Said somewhere else, naming this page: the relation and where it was said. */
30
+ export const MentionedIn: Story = {}
31
+
32
+ /** The conversation of something under this page: another relation, in the app's words. */
33
+ export const OnAnItemUnderIt: Story = {
34
+ args: { relation: 'On an item', place: 'Item two' },
35
+ render: (args) => (
36
+ <ConversationPlace {...args}>
37
+ <ConversationCard author={TWO} time="Yesterday" onClick={() => {}}>
38
+ {WORDS}
39
+ </ConversationCard>
40
+ </ConversationPlace>
41
+ ),
42
+ }
43
+
44
+ /** The place's name has not come yet: the relation alone, never a placeholder. */
45
+ export const PlaceNotNamedYet: Story = { args: { place: undefined } }
46
+
47
+ /** A long name is cut to the column. */
48
+ export const LongPlace: Story = { args: { place: 'Item one, with a name long enough to be cut short at the column’s edge' } }