@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
@@ -0,0 +1,155 @@
1
+ import { createContext, useEffect, useState, type RefObject } from 'react'
2
+
3
+ /**
4
+ * Where a conversation scrolls, Peek's way, moved into the kit (C1 of the audit of 2 November): it opens at the newest
5
+ * comment, comes back to where the reader left it, follows what arrives only while the reader is at the bottom, goes
6
+ * down to the reader's own comment as it is sent, and holds still while cards and pictures fill in. ConversationLayout
7
+ * and Thread use it; nothing here is for an app to call but `useLeftAt`.
8
+ */
9
+
10
+ /**
11
+ * How close to the bottom still counts as at the bottom. Not zero: `scrollHeight - scrollTop - clientHeight` is rarely
12
+ * exactly zero (display scaling, zoom and fractional pixel ratios leave a fraction while the last comment is squarely
13
+ * in view), and a strict check would make following work on one machine and not another. 80px is about one comment,
14
+ * so a glance at the line above still counts as watching. Peek's NEAR_BOTTOM_PX.
15
+ */
16
+ export const NEAR_BOTTOM_PX = 80
17
+
18
+ /** Whether the box is close enough to the bottom to follow what arrives. */
19
+ export function isNearBottom(el: HTMLElement): boolean {
20
+ return el.scrollHeight - el.scrollTop - el.clientHeight <= NEAR_BOTTOM_PX
21
+ }
22
+
23
+ /**
24
+ * The comment at the top of a conversation's view, and how far below the view's top it is: what "the same spot" means
25
+ * to the reader, whatever above it changed height.
26
+ */
27
+ export function anchorIn(el: HTMLElement): { id: string; top: number } | undefined {
28
+ // jsdom has no layout: no anchor, and the restore keeps the plain offset.
29
+ if (typeof document.elementFromPoint !== 'function') return undefined
30
+ const box = el.getBoundingClientRect()
31
+ // A gap between cards, or a day line, is passed over a few pixels at a time.
32
+ for (let y = box.top + 1; y < box.top + 96; y += 8) {
33
+ const marker = document.elementFromPoint(box.left + box.width / 2, y)?.closest<HTMLElement>('[data-conversation-item]')
34
+ const card = marker?.firstElementChild
35
+ if (marker?.dataset.conversationItem && card) return { id: marker.dataset.conversationItem, top: card.getBoundingClientRect().top - box.top }
36
+ }
37
+ return undefined
38
+ }
39
+
40
+ /** The card of the comment `id` in `el`: the first child of its `data-conversation-item`. */
41
+ export const cardIn = (el: HTMLElement, id: string) => el.querySelector(`[data-conversation-item="${CSS.escape(id)}"]`)?.firstElementChild ?? null
42
+
43
+ /**
44
+ * Keeps a conversation where the reader is while what is in it changes size: a card, a chip or a picture filling in, a
45
+ * card shown or hidden (Peek's OPT-10).
46
+ *
47
+ * At the bottom (`atBottom`, the view's own judgement), it stays the same distance from the bottom, so the newest
48
+ * comments stay in view as a card above them loads. Anywhere else, the comment at the top of the view stays at the same
49
+ * height. Browsers that anchor scrolling themselves (Chromium, Firefox) do the second only for what changes above the
50
+ * view, and only roughly; Safari does neither, and a conversation there was pushed thousands of pixels off its bottom
51
+ * by one card.
52
+ *
53
+ * Only once `ready()` says the conversation has been placed: before that, where it lands is the view's to decide.
54
+ * Without `atBottom` (a thread), "at the bottom" is where the last scroll left it. `rebase()` takes it again from where
55
+ * the box is now, at the bottom: a thread that just went down to a new reply.
56
+ */
57
+ export function useSteadyScroll(
58
+ scrollRef: RefObject<HTMLElement | null>,
59
+ atBottom: RefObject<boolean> | undefined,
60
+ ready: () => boolean,
61
+ key: unknown,
62
+ enabled: boolean,
63
+ ): { rebase: () => void } {
64
+ const [handle] = useState(() => ({ rebase: () => {} }))
65
+ useEffect(() => {
66
+ const el = scrollRef.current
67
+ if (!enabled || !el || typeof ResizeObserver === 'undefined') return
68
+ let fromBottom = 0
69
+ let lastTop = 0
70
+ let anchor: ReturnType<typeof anchorIn>
71
+ let scrolledToBottom = true
72
+ const bottom = () => (atBottom ? atBottom.current : scrolledToBottom)
73
+ const remember = () => {
74
+ fromBottom = el.scrollHeight - el.scrollTop - el.clientHeight
75
+ lastTop = el.scrollTop
76
+ anchor = bottom() ? undefined : anchorIn(el)
77
+ }
78
+ remember()
79
+ handle.rebase = () => {
80
+ scrolledToBottom = true
81
+ remember()
82
+ }
83
+ const onScroll = () => {
84
+ scrolledToBottom = isNearBottom(el)
85
+ remember()
86
+ }
87
+ const keep = () => {
88
+ if (!ready()) return remember()
89
+ if (bottom()) {
90
+ // The distance it was left at, unless the view was moved down to the live edge since (a new comment followed,
91
+ // before its scroll event): that move stands, rather than being put back.
92
+ const now = el.scrollHeight - el.scrollTop - el.clientHeight
93
+ const keepAt = el.scrollTop > lastTop && now < fromBottom ? now : fromBottom
94
+ const top = el.scrollHeight - el.clientHeight - Math.max(0, keepAt)
95
+ if (Math.abs(el.scrollTop - top) >= 1) el.scrollTop = top
96
+ } else if (anchor) {
97
+ const card = cardIn(el, anchor.id)
98
+ if (card) {
99
+ const moved = card.getBoundingClientRect().top - el.getBoundingClientRect().top - anchor.top
100
+ if (Math.abs(moved) >= 1) el.scrollTop += moved
101
+ }
102
+ }
103
+ remember()
104
+ }
105
+ el.addEventListener('scroll', onScroll, { passive: true })
106
+ // The scroller for its own height (the box under it grows), its content for everything in it.
107
+ const observer = new ResizeObserver(keep)
108
+ observer.observe(el)
109
+ for (const child of el.children) observer.observe(child)
110
+ return () => {
111
+ handle.rebase = () => {}
112
+ el.removeEventListener('scroll', onScroll)
113
+ observer.disconnect()
114
+ }
115
+ }, [scrollRef, atBottom, ready, key, enabled, handle])
116
+ return handle
117
+ }
118
+
119
+ /**
120
+ * Where each conversation was left in this tab (Peek's OPT-3), by the name the app gave it (`rememberAs`): at the
121
+ * bottom or at an offset, the comment at the top of the view and how far down it sat, and when (ms). Not per reader:
122
+ * it holds no words.
123
+ */
124
+ export const places = new Map<string, { atBottom: boolean; offset: number; anchor?: { id: string; top: number }; leftAt: number }>()
125
+
126
+ /**
127
+ * When the reader last left the conversation `key` (a `ConversationLayout`'s `rememberAs`) away from its newest
128
+ * comment, in ms since 1970: what an app draws its "New" line from, over the first comment written since. `null` when
129
+ * it was left at the newest, or not opened before in this tab. Taken once per visit, as the conversation opens: later
130
+ * scrolling moves the record, not the line.
131
+ */
132
+ export function useLeftAt(key: string | null | undefined): number | null {
133
+ const [taken, setTaken] = useState<{ key: string; at: number | null }>()
134
+ // Nothing shown: the visit is over, and the next one, to the same conversation too, takes it again.
135
+ if (!key && taken) setTaken(undefined)
136
+ if (key && taken?.key !== key) {
137
+ const left = places.get(key)
138
+ const at = left && !left.atBottom ? left.leftAt : null
139
+ setTaken({ key, at })
140
+ return at
141
+ }
142
+ return key && taken?.key === key ? taken.at : null
143
+ }
144
+
145
+ /**
146
+ * Set by ConversationLayout round its own box, read by CommentBox: the reader's own comment brings them down to it as
147
+ * it is drawn, before the relay has answered (Peek's OPT-6), and a refusal leaves where they actually are to decide.
148
+ */
149
+ export const sendsInLayout = createContext<{ sending: () => void; refused: () => void } | null>(null)
150
+
151
+ /**
152
+ * Set by a Thread round its replies, counted by each ReplyCard as it is first drawn in it: a new reply, or another
153
+ * thread's replies, take the thread to its newest; a reply taken away (a delete) is never counted, and moves nothing.
154
+ */
155
+ export const repliesDrawn = createContext<{ added: number } | null>(null)
package/src/editor.ts CHANGED
@@ -121,3 +121,4 @@ export {
121
121
  type DocumentMentions,
122
122
  type HeldTyping,
123
123
  } from './DocumentEditor'
124
+ export { DocumentField, type DocumentFieldProps } from './DocumentField'
@@ -0,0 +1,53 @@
1
+ // @vitest-environment jsdom
2
+ /**
3
+ * Every editor in the kit paints the words you select in `bg-selected`: the
4
+ * colour the selection strip's kept selection paints them while its link field
5
+ * has the focus (`KeptSelection`), so selected and kept look the same. Peek
6
+ * painted it with a rule of its own over every editor (`.tiptap ::selection`,
7
+ * PEE-19); Ship and Leaf painted nothing, and showed the browser's.
8
+ *
9
+ * jsdom draws no selection, so this pins the class that paints it on each
10
+ * editor's text, as `heights.test.tsx` pins a class jsdom cannot measure. In
11
+ * Chrome the selection's computed background is the token's value (the record).
12
+ */
13
+ import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
14
+ import { cleanup, render, screen } from '@testing-library/react'
15
+ import type { JSONContent } from '@tiptap/react'
16
+ import { CommentBox } from './CommentBox'
17
+ import { DocumentEditor, type DocumentCodec } from './DocumentEditor'
18
+ import { InlineText } from './InlineText'
19
+
20
+ beforeAll(() => {
21
+ Element.prototype.scrollIntoView = vi.fn()
22
+ Element.prototype.getClientRects = () => [] as unknown as DOMRectList
23
+ Range.prototype.getClientRects = () => [] as unknown as DOMRectList
24
+ Range.prototype.getBoundingClientRect = () => new DOMRect()
25
+ })
26
+
27
+ afterEach(cleanup)
28
+
29
+ const PAINTS_SELECTION = 'selection:bg-bg-selected'
30
+ const paints = (name: string) => (screen.getByRole('textbox', { name }).getAttribute('class') ?? '').split(/\s+/).includes(PAINTS_SELECTION)
31
+
32
+ const codec: DocumentCodec = {
33
+ read: (value) => JSON.parse(value) as JSONContent,
34
+ write: (doc) => ({ value: JSON.stringify(doc) }),
35
+ }
36
+ const DOC = JSON.stringify({ type: 'doc', content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Words' }] }] })
37
+
38
+ describe('an editor paints the words you select in the selected colour', () => {
39
+ it('the comment box', () => {
40
+ render(<CommentBox label="Box" placeholder="Write" people={[]} send={async () => ({ accepted: true })} />)
41
+ expect(paints('Box')).toBe(true)
42
+ })
43
+
44
+ it('the document editor', () => {
45
+ render(<DocumentEditor value={DOC} format="blocks" codec={codec} label="Document" onCommit={() => true} />)
46
+ expect(paints('Document')).toBe(true)
47
+ })
48
+
49
+ it('a line of text edited in place', () => {
50
+ render(<InlineText value="Item one" placeholder="Untitled" label="Title" onCommit={() => true} />)
51
+ expect(paints('Title')).toBe(true)
52
+ })
53
+ })
@@ -40,6 +40,10 @@ tester.run('no-field-outside-a-form', noFieldOutsideAForm, {
40
40
  { name: 'a one-line field with its button', code: component('<Form onSubmit={() => {}}><TextInput value={text} onChange={(e) => set(e.target.value)} /></Form>', ui('Form', 'TextInput')) },
41
41
  { name: 'fields drawn from a list, inside the form', code: component("<Form onSubmit={() => {}}>{['a', 'b'].map((k) => <Field key={k} label={k}><TextInput value={text} /></Field>)}</Form>", ui('Form', 'Field', 'TextInput')) },
42
42
  { name: "the palette's form level is a Form (UIG-29)", code: component('<CommandPaletteForm submitLabel="Create" onSubmit={() => {}}><Field label="Title"><TextInput value={text} /></Field></CommandPaletteForm>', ui('CommandPaletteForm', 'Field', 'TextInput')) },
43
+ {
44
+ name: "FormDialog is a Form: Peek's New folder dialog",
45
+ code: component('<FormDialog title="New folder" submitLabel="Create" onClose={() => {}} onSubmit={() => {}}>\n<Field label="Name"><TextInput value={text} onChange={(e) => set(e.target.value)} /></Field>\n</FormDialog>', ui('FormDialog', 'Field', 'TextInput')),
46
+ },
43
47
  { name: 'a field that saves itself as you leave it', code: component('<EditableText value={text} onCommit={set} />', ui('EditableText')) },
44
48
  { name: 'a field that filters a list', code: component('<SearchInput value={text} onChange={set} />', ui('SearchInput')) },
45
49
  {
@@ -9,8 +9,8 @@ import { bindingOfTag, partsOfFile, type Node, type Parser, type PartBinding } f
9
9
  */
10
10
  export const FIELD_PARTS = ['Field', 'TextInput', 'Textarea'] as const
11
11
 
12
- /** The parts that are a `Form`: the package's own, and the palette's form level, which is one (UIG-29). */
13
- export const FORM_PARTS = ['Form', 'CommandPaletteForm'] as const
12
+ /** The parts that are a `Form`: the package's own, the palette's form level (UIG-29), and `FormDialog`, a dialog that draws one. */
13
+ export const FORM_PARTS = ['Form', 'CommandPaletteForm', 'FormDialog'] as const
14
14
 
15
15
  const child = (node: Node, key: string) => node[key] as Node | null | undefined
16
16
  const nameOf = (node: Node | null | undefined): string | undefined =>
@@ -8,7 +8,7 @@ import { bindingOfTag, partsOfFile, type Node, type Parser, type PartBinding } f
8
8
  * the browser shows it as its tooltip. `no-native-title.test.ts` holds this
9
9
  * list to the catalogue: a part that gains a `title` of its own joins it.
10
10
  */
11
- export const PARTS_WITH_A_TITLE = ['CollapsibleSection', 'ConfirmDialog', 'ContainerHeader', 'ConversationLayout', 'DialogShell', 'ListColumn', 'NavTree', 'NavTreeSection', 'PageHeader', 'Panel', 'SectionHeader', 'Thread'] as const
11
+ export const PARTS_WITH_A_TITLE = ['ArchiveDialog', 'CollapsibleSection', 'ConfirmDialog', 'ContainerHeader', 'ConversationLayout', 'DialogShell', 'FormDialog', 'ListColumn', 'MoveDialog', 'NavTree', 'NavTreeSection', 'PageHeader', 'Panel', 'SectionHeader', 'Thread'] as const
12
12
 
13
13
  const child = (node: Node, key: string) => node[key] as Node | null | undefined
14
14
  const nameOf = (node: Node | null | undefined): string | undefined =>
package/src/formBusy.ts CHANGED
@@ -9,11 +9,14 @@ import { createContext, useContext } from 'react'
9
9
  * told, so it kept its normal look while it could not be pressed, and a
10
10
  * Checkbox, which is a `<span>`, could still be ticked (Katerina saw the busy
11
11
  * story's button unchanged, 16 September). Those parts read this and switch
12
- * off the way their own `disabled` does. Not exported: it is the package's
13
- * wiring between Form and its parts.
12
+ * off the way their own `disabled` does; so does the editor's DocumentField,
13
+ * whose box no fieldset reaches. Not for an app: it is the package's wiring
14
+ * between Form and its parts, exported from the main entry only because the
15
+ * editor's bundle reads it from there (one context, as `caretOnOpen`).
14
16
  */
15
17
  export const FormBusyContext = createContext(false)
16
18
 
19
+ /** Whether a `Form` around this is sending: its fields and buttons wait. The kit's parts read it; an app has no need to. */
17
20
  export function useFormBusy(): boolean {
18
21
  return useContext(FormBusyContext)
19
22
  }
package/src/index.ts CHANGED
@@ -9,12 +9,13 @@
9
9
  * `src/` still ships in the tarball, so stepping into a component lands on the
10
10
  * TypeScript that produced it.
11
11
  */
12
- export { AppProvider, type AppProviderProps } from './AppProvider'
12
+ export { AppProvider, isPlainClick, type AppProviderProps } from './AppProvider'
13
13
  export { AppShell, useSidebarFold, type AppShellProps, type SidebarFoldOptions } from './AppShell'
14
14
  export { AttachmentCard, type AttachmentCardProps, type AttachmentCardState } from './AttachmentCard'
15
15
  export { Avatar, hueFor, initialsFor, type AvatarProps } from './Avatar'
16
16
  export { AvatarGroup, type AvatarGroupMember, type AvatarGroupProps } from './AvatarGroup'
17
17
  export { MembersPill, type MembersPillProps } from './MembersPill'
18
+ export { MoveDialog, type MoveChoice, type MoveDialogProps, type MoveFolder, type MovePlace } from './MoveDialog'
18
19
  export { MembersDialog, type MembersDialogCandidate, type MembersDialogMember, type MembersDialogProps, type MembersDialogSelfAction } from './MembersDialog'
19
20
  export { Banner, type BannerProps, type BannerTone } from './Banner'
20
21
  export { BlockHandle, blockAtY, type BlockHandleProps, type BlockHandleEditing, type HandleBlock } from './BlockHandle'
@@ -61,13 +62,16 @@ export { Tooltip, TooltipProvider, WithTooltip, type TooltipProps, type TooltipP
61
62
  export { Field, FieldLine, type FieldLineProps, type FieldLineTone, type FieldProps } from './Field'
62
63
  export { FilePicker, type FilePickerProps } from './FilePicker'
63
64
  export { Form, type FormProps } from './Form'
65
+ // Whether a Form around it is sending: the kit's own wiring, read by the editor's DocumentField from this entry (one context).
66
+ export { useFormBusy } from './formBusy'
67
+ export { FormDialog, type FormDialogProps } from './FormDialog'
64
68
  export { Select, type SelectOption, type SelectProps } from './Select'
65
69
  export { TextInput, type TextInputProps } from './TextInput'
66
70
  export { Textarea, type TextareaProps } from './Textarea'
67
- export { ConfirmDialog, type ConfirmDialogProps } from './ConfirmDialog'
71
+ export { ConfirmDialog, type ConfirmDialogAlternative, type ConfirmDialogProps } from './ConfirmDialog'
68
72
  export { DialogShell, type DialogShellProps } from './DialogShell'
69
73
  export { Divider, type DividerProps } from './Divider'
70
- export { EditableText, type EditableTextProps } from './EditableText'
74
+ export { EditableText, type EditableTextAnswer, type EditableTextOutcome, type EditableTextProps } from './EditableText'
71
75
  export { EmptyState, type EmptyStateProps } from './EmptyState'
72
76
  export { EntryShell, type EntryShellProps } from './EntryShell'
73
77
  export { ErrorBoundary, type ErrorBoundaryProps } from './ErrorBoundary'
@@ -77,7 +81,7 @@ export { Breadcrumb, type BreadcrumbProps, type Crumb } from './Breadcrumb'
77
81
  export { EnterHint, Menu, MenuItem, MenuPanel, MenuRow, MenuSection, MenuSeparator, MenuSub, type MenuItemProps, type MenuPanelProps, type MenuProps, type MenuSubProps } from './Menu'
78
82
  export { NavItem, type NavItemProps } from './NavItem'
79
83
  export { UnreadDot } from './UnreadDot'
80
- export { NavTree, NavTreeSection, type NavTreeGroup, type NavTreeNode, type NavTreeProps, type NavTreeSectionProps } from './NavTree'
84
+ export { NAV_TREE_PENDING_MS, NavTree, NavTreeSection, type NavTreeGroup, type NavTreeNode, type NavTreeProps, type NavTreeSectionProps } from './NavTree'
81
85
  export { Popover, type PopoverProps } from './Popover'
82
86
  export { SuggestionMenu, type SuggestionMenuHandle, type SuggestionMenuProps, type SuggestionMenuRow, type SuggestionMenuSection } from './SuggestionMenu'
83
87
  export { ScrollArea, type ScrollAreaProps } from './ScrollArea'
@@ -122,7 +126,7 @@ export { LinkChip, type LinkChipProps } from './LinkChip'
122
126
  export { LinkRow, LinkUnavailable, type LinkRowProps, type LinkUnavailableProps } from './LinkRow'
123
127
  export { LinkCard, LinkCardLoading, type LinkCardProps, type LinkCardLoadingProps } from './LinkCard'
124
128
  export { LinkPreview, LinkPreviewOpen, useCanHover, type LinkPreviewProps } from './LinkPreview'
125
- export { AttachedCard, type AttachedCardProps } from './AttachedCard'
129
+ export { AttachedCard, type AttachedCardMemory, type AttachedCardProps } from './AttachedCard'
126
130
  export { PartCard, type PartCardProps, type PartCardState } from './PartCard'
127
131
  export { Person, type PersonProps } from './Person'
128
132
  export { Rail, type RailProps } from './Rail'
@@ -137,7 +141,10 @@ export { ConversationCard, ReplyCard, type ConversationCardProps, type Conversat
137
141
  export { ConversationLayout, type ConversationItem, type ConversationLayoutProps } from './ConversationLayout'
138
142
  // The box at a thread's foot takes the caret when a ConversationLayout opens it: one context, shared with the editor's CommentBox.
139
143
  export { caretOnOpen } from './threadCard'
144
+ // Where a two-column conversation was left, for the app's "New" line; and the layout's word to its box that the reader's own comment is on its way (CommentBox reads it, from the editor's bundle).
145
+ export { useLeftAt, sendsInLayout } from './conversationScroll'
140
146
  export { ConversationMenu, type ConversationMenuProps } from './ConversationMenu'
147
+ export { ConversationPlace, type ConversationPlaceProps } from './ConversationPlace'
141
148
  export { EditedMarker, type EditedMarkerProps } from './EditedMarker'
142
149
  export { MetaText, type MetaTextProps } from './MetaText'
143
150
  export { QuotedLine, type QuotedLineProps } from './QuotedLine'
@@ -145,8 +152,11 @@ export { ReactionHorizon, type ReactionHorizonProps } from './ReactionHorizon'
145
152
  export { RepliesRow, type RepliesRowProps } from './RepliesRow'
146
153
  export { ResolveDialog, type ResolveDialogProps } from './ResolveDialog'
147
154
  export { PinnedComment, type PinnedCommentProps } from './PinnedComment'
155
+ export { ArchiveDialog, type ArchiveDialogProps } from './ArchiveDialog'
148
156
  export { ArchivedNotice, type ArchivedNoticeProps } from './ArchivedNotice'
149
157
  export { Thread, type ThreadProps, type ThreadStart } from './Thread'
158
+ export { useSeenOnScreen, type SeenOnScreen } from './seenOnScreen'
159
+ export { showInConversation, showInConversationWhenDrawn, type ShowOptions, type ShowWhenDrawnOptions } from './showInConversation'
150
160
  export { UrgentMark } from './UrgentMark'
151
161
  export { ReactionRow, AddReactionButton, whoReacted, type ReactionRowProps, type AddReactionButtonProps, type ReactionCount } from './ReactionRow'
152
162
  export { SearchInput, type SearchInputProps } from './SearchInput'
@@ -155,7 +165,7 @@ export { ContainerHeader, type ContainerHeaderProps } from './ContainerHeader'
155
165
  export { Panel, type PanelProps } from './Panel'
156
166
  export { PageHeader, type PageHeaderMeta, type PageHeaderProps } from './PageHeader'
157
167
  export { ListColumn, type ListColumnProps } from './ListColumn'
158
- export { CollapsibleSection, type CollapsibleSectionProps } from './CollapsibleSection'
168
+ export { CollapsibleSection, useRememberedOpen, type CollapsibleSectionProps } from './CollapsibleSection'
159
169
  export { SectionLabel } from './SectionLabel'
160
170
  export { Tabs, type TabDef, type TabsProps } from './Tabs'
161
171
  export { Toast, ToastProvider, useToast, type ToastOptions, type ToastProps, type ToastType } from './Toast'
package/src/looks.ts CHANGED
@@ -34,6 +34,9 @@ export const FIELD_SIZE_CLASSES = {
34
34
  /** The box around an input that sits inside it, before its focus look: SearchInput and ChipInput. */
35
35
  export const FIELD_SHELL_CLASSES = 'bg-bg-field border border-border-field shadow-field hover:border-border-strong group-hover/field:border-border-strong rounded-lg transition-colors'
36
36
 
37
+ /** That box focused, while what is typed in it has the focus: the focus border, held under the pointer, and Signal's ring. ChipInput and DocumentField. */
38
+ export const FIELD_SHELL_FOCUS_CLASSES = 'focus-within:border-border-focus focus-within:hover:border-border-focus group-hover/field:focus-within:border-border-focus signal:transition-shadow signal:focus-within:shadow-focus-ring'
39
+
37
40
  /** A panel that floats over the page: Menu's panel and Tooltip. */
38
41
  export const FLOATING_SURFACE_CLASSES = 'rounded-lg border border-border-default bg-bg-elevated shadow-lg'
39
42
 
@@ -92,6 +95,13 @@ export const COLLAPSIBLE_PANEL_CLASSES = 'h-[var(--collapsible-panel-height)] ov
92
95
  // A field's fill and edge, as every field has (Katerina, 31 October: the comment box is a field, and every field has its fill).
93
96
  export const WRITING_BOX_CLASSES = 'relative bg-bg-field border border-border-field rounded-lg p-3 flex flex-col gap-4'
94
97
 
98
+ /**
99
+ * Selected words in an editor: the selected thing's fill, the colour the selection strip's kept selection paints
100
+ * while its link field has the focus (`KeptSelection`), so the words look the same selected and kept. Peek's
101
+ * composer rule (PEE-19), moved into every editor: the comment box, the document editor and InlineText.
102
+ */
103
+ export const EDITOR_SELECTION_CLASSES = 'selection:bg-bg-selected'
104
+
95
105
  /** The keys under the send box, in words: "Enter to send · Shift+Enter new line". One line, cut when the room runs out; no key caps. The edit box writes none (Katerina, 1 November). */
96
106
  export const BOX_HINT_CLASSES = 'min-w-0 truncate select-none text-caption text-text-muted signal:font-mono signal:text-menu signal:font-normal signal:tracking-wider'
97
107
 
@@ -48,20 +48,20 @@ describe('the registry builds', () => {
48
48
  expect(registry.entries.map((one) => one.name).sort()).toEqual(values.map((one) => one.name).sort())
49
49
  })
50
50
 
51
- it('counts 229 names over 114 files: 155 components, 71 helpers and 3 hooks (ArchivedNotice, the card on an archived file, from Peek, Ship and Leaf, on 31 October; caretOnOpen, the box at a thread’s foot taking the caret when a ConversationLayout opens it, without scrolling, on 31 October; the conversation from Peek for every app, with PageHeader and PinnedComment, on 31 October, and ResolutionNote and ResolutionHistory gone with the resolved looks not picked, on 1 November; useSidebarFold, a folded sidebar kept folded in every app, on 31 October; cardShapeMemory, a card’s last shape on this device, lifted from Peek and Ship for Leaf, and ReferenceCards and useReferenceCards gone with their deprecated page, in the widget review, on 30 October; inTheBox, a card or part in a box being written in, on the files’ fill and in words, on 29 October; archivedLine, the line on an archived file in every app (PEEKM-2), on 23 October; keepCommentBoxWarm, a box built ahead, exported as 0.84.0 promised (PEEKM-1), on 21 October;linkedFrom and linkStateFrom, one card for a file in every app (5ebf2756), on 21 October; ComposeBox, ComposeKeys and COMPOSE_EDITOR_CLASSES gone into CommentBox’s own frame (one box), on 21 October; LinkPlaces with linkPlaceAt and staysChip, a link in a document drawn where it sits (WBD-4), on 20 October; DocumentEditor, one document editor for every app, and PersonReference, `@` in a document (WBD-3), on 20 October; toggleTableHeaderRow, a table’s header row on and off (LEAF-12), on 19 October;EntryShell, the screen while nobody is signed in, moved from Peek (AUT-3), on 17 October; CommentBox with commentBoxRows, and ReactionRow with AddReactionButton and whoReacted, the shared comment box and reaction row (COMM-2), on 17 October; the link widgets — LinkChip, LinkRow, LinkCard, CardUnder, PartCard, LinkPreview and their parts, with useCanHover, chosenOf, loadingShapeOf and unavailableMemory — from the Widgets 2 prototype, on 16 October; InlineText, a title or the line under it edited where it stands (SUM-4), on 16 October; ComposeBox with ComposeKeys and its classes, CommentHighlights with its five helpers, and keepSelection and releaseSelection, from the Leaf prototype (LEAF-4), on 16 October;NavTree, NavTreeSection, the composer triggers and UnreadDot joined on 2 October; BlockHandle and EditorBlockHandle (RIC-18) on 2 October, moveBlock and blockDropCursor, the drop in the gutter, on 5 October, MembersPill and MembersDialog, moved from Peek (SHI-31), on 6 October, ShowMore on 7 October, AppProvider on 8 October, and KindIcon, thingKindOf and PastedImages with its two helpers, moved from Peek, on 8 October; CodeBlockColours, the coloured code block of the editor, on 9 October; Checklist, Callout, isChecklistTick and calloutLook (RIC-19) on 13 October; EditorTableControls and its four actions (RIC-21) on 13 October; ReferenceCards, useReferenceCards and its three helpers, the card a chip in a document asks for, on 14 October; LinkChips and its two helpers, a URL in a document read as its chip, on 14 October; ReferenceMenu, ReferenceMenuView and three helpers, the menu of a chip while writing, on 14 October; PastedMarkdown, markdown pasted as the blocks it spells (LEAF-10), on 15 October; turnIntoRows, turnListInto and turnQuoteInto, the block menu’s Turn into for a list and a quote (LEAF-11), on 15 October)', () => {
51
+ it('counts 243 names over 123 files: 160 components, 76 helpers and 7 hooks (useFormBusy, whether a Form around it is sending, read by the editor’s DocumentField from the main entry, in the review of 2 November; useLeftAt, sendsInLayout, useSeenOnScreen, showInConversation and showInConversationWhenDrawn, where a conversation scrolls, what was seen and a link landing on a comment, moved from Peek for every app, on 2 November; useRememberedOpen, the fold a section remembers, read by the app, and NAV_TREE_PENDING_MS and isPlainClick, Peek’s Folder timer and plain-click check, moved in, on 2 November; FormDialog, MoveDialog and ArchiveDialog, the dialogs Peek wired by hand, on 2 November; ConversationPlace, the line saying where a comment was said, and DocumentField, a rich-text field of a form, moved from Peek, on 2 November; ArchivedNotice, the card on an archived file, from Peek, Ship and Leaf, on 31 October; caretOnOpen, the box at a thread’s foot taking the caret when a ConversationLayout opens it, without scrolling, on 31 October; the conversation from Peek for every app, with PageHeader and PinnedComment, on 31 October, and ResolutionNote and ResolutionHistory gone with the resolved looks not picked, on 1 November; useSidebarFold, a folded sidebar kept folded in every app, on 31 October; cardShapeMemory, a card’s last shape on this device, lifted from Peek and Ship for Leaf, and ReferenceCards and useReferenceCards gone with their deprecated page, in the widget review, on 30 October; inTheBox, a card or part in a box being written in, on the files’ fill and in words, on 29 October; archivedLine, the line on an archived file in every app (PEEKM-2), on 23 October; keepCommentBoxWarm, a box built ahead, exported as 0.84.0 promised (PEEKM-1), on 21 October;linkedFrom and linkStateFrom, one card for a file in every app (5ebf2756), on 21 October; ComposeBox, ComposeKeys and COMPOSE_EDITOR_CLASSES gone into CommentBox’s own frame (one box), on 21 October; LinkPlaces with linkPlaceAt and staysChip, a link in a document drawn where it sits (WBD-4), on 20 October; DocumentEditor, one document editor for every app, and PersonReference, `@` in a document (WBD-3), on 20 October; toggleTableHeaderRow, a table’s header row on and off (LEAF-12), on 19 October;EntryShell, the screen while nobody is signed in, moved from Peek (AUT-3), on 17 October; CommentBox with commentBoxRows, and ReactionRow with AddReactionButton and whoReacted, the shared comment box and reaction row (COMM-2), on 17 October; the link widgets — LinkChip, LinkRow, LinkCard, CardUnder, PartCard, LinkPreview and their parts, with useCanHover, chosenOf, loadingShapeOf and unavailableMemory — from the Widgets 2 prototype, on 16 October; InlineText, a title or the line under it edited where it stands (SUM-4), on 16 October; ComposeBox with ComposeKeys and its classes, CommentHighlights with its five helpers, and keepSelection and releaseSelection, from the Leaf prototype (LEAF-4), on 16 October;NavTree, NavTreeSection, the composer triggers and UnreadDot joined on 2 October; BlockHandle and EditorBlockHandle (RIC-18) on 2 October, moveBlock and blockDropCursor, the drop in the gutter, on 5 October, MembersPill and MembersDialog, moved from Peek (SHI-31), on 6 October, ShowMore on 7 October, AppProvider on 8 October, and KindIcon, thingKindOf and PastedImages with its two helpers, moved from Peek, on 8 October; CodeBlockColours, the coloured code block of the editor, on 9 October; Checklist, Callout, isChecklistTick and calloutLook (RIC-19) on 13 October; EditorTableControls and its four actions (RIC-21) on 13 October; ReferenceCards, useReferenceCards and its three helpers, the card a chip in a document asks for, on 14 October; LinkChips and its two helpers, a URL in a document read as its chip, on 14 October; ReferenceMenu, ReferenceMenuView and three helpers, the menu of a chip while writing, on 14 October; PastedMarkdown, markdown pasted as the blocks it spells (LEAF-10), on 15 October; turnIntoRows, turnListInto and turnQuoteInto, the block menu’s Turn into for a list and a quote (LEAF-11), on 15 October)', () => {
52
52
  // The reconciliation GATES.md §24 explains. If this changes, that changes.
53
53
  // The `EDITOR_EXTENSIONS` count as components by their names; they are
54
54
  // editor extensions, documented on SelectionToolbar's, BlockNodes' and
55
55
  // ComposerTriggers' pages.
56
56
  const kinds = registry.entries.reduce<Record<string, number>>((all, one) => ({ ...all, [one.kind]: (all[one.kind] ?? 0) + 1 }), {})
57
- expect(kinds).toEqual({ component: 155, helper: 71, hook: 3 })
58
- expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(114)
57
+ expect(kinds).toEqual({ component: 160, helper: 76, hook: 7 })
58
+ expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(123)
59
59
  })
60
60
 
61
61
  it('gives every entry a purpose, from its own page or from the comment above it', () => {
62
62
  expect(registry.entries.filter((one) => one.purpose.trim() === '')).toEqual([])
63
- expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(105)
64
- expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(124)
63
+ expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(110)
64
+ expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(133)
65
65
  })
66
66
 
67
67
  it('takes a name with a page of its own from the page, and a name without one from the code', () => {
@@ -262,7 +262,7 @@ describe('the ids point at something', () => {
262
262
 
263
263
  it('gives every component a page and a story, and only a helper none', () => {
264
264
  const without = registry.entries.filter((one) => one.docsId === null || one.storyId === null)
265
- // The helpers in a file with no page: cn, the shortcut names, the editor's suggestion wiring (documented on SuggestionMenu's page), the link widgets' data helpers (documented on LinkCard's and LinkChip's pages; linkedFrom's and cardShapeMemory's on LinkCard's), a chip's card choice (ReferenceMenu writes it), and the caret a ConversationLayout gives a thread's box (documented on ConversationLayout's page).
265
+ // The helpers in a file with no page: cn, the shortcut names, the editor's suggestion wiring (documented on SuggestionMenu's page), the link widgets' data helpers (documented on LinkCard's and LinkChip's pages; linkedFrom's and cardShapeMemory's on LinkCard's), a chip's card choice (ReferenceMenu writes it), the caret a ConversationLayout gives a thread's box, whether a Form is sending (the kit's own wiring, documented on Form's page), and where a conversation scrolls, what was seen and a link landing on a comment (documented on ConversationLayout's and Thread's pages).
266
266
  expect(without.map((one) => one.name).sort()).toEqual([
267
267
  'archivedLine',
268
268
  'cardShapeMemory',
@@ -278,11 +278,17 @@ describe('the ids point at something', () => {
278
278
  'loadingShapeOf',
279
279
  'referenceAtSelection',
280
280
  'referenceCardPlacements',
281
+ 'sendsInLayout',
281
282
  'setReferenceCard',
282
283
  'setReferenceCardAt',
283
284
  'shortcutLabel',
285
+ 'showInConversation',
286
+ 'showInConversationWhenDrawn',
284
287
  'suggestionPopup',
285
288
  'unavailableMemory',
289
+ 'useFormBusy',
290
+ 'useLeftAt',
291
+ 'useSeenOnScreen',
286
292
  ])
287
293
  expect(without.every((one) => one.kind !== 'component')).toBe(true)
288
294
  })
@@ -0,0 +1,182 @@
1
+ // @vitest-environment jsdom
2
+ /**
3
+ * What reads a comment or a reply (Katerina, 30 October): being on screen for a moment, not being drawn. Peek's own
4
+ * hook and its tests, moved into the kit (C2 of the audit of 2 November): an app says which conversation or thread it
5
+ * is (`useSeenOnScreen(key)`), hands what it returns to the layout or the thread (`seen`), and reads back what was seen.
6
+ * A stand-in IntersectionObserver says what shows.
7
+ */
8
+ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
9
+ import { act, cleanup, render, screen } from '@testing-library/react'
10
+ import { ConversationCard, ReplyCard } from './ConversationCard'
11
+ import { ConversationLayout } from './ConversationLayout'
12
+ import { useSeenOnScreen } from './seenOnScreen'
13
+ import { Thread } from './Thread'
14
+
15
+ /** The moment a comment must stay on screen: Peek's READ_DWELL_MS. */
16
+ const DWELL = 1500
17
+ const ONE = { name: 'Person one' }
18
+
19
+ let observers: { callback: IntersectionObserverCallback; targets: Element[] }[] = []
20
+ class FakeObserver {
21
+ targets: Element[] = []
22
+ callback: IntersectionObserverCallback
23
+ constructor(callback: IntersectionObserverCallback) {
24
+ this.callback = callback
25
+ observers.push(this)
26
+ }
27
+ observe(target: Element) {
28
+ this.targets.push(target)
29
+ }
30
+ disconnect() {
31
+ this.targets = []
32
+ }
33
+ unobserve() {}
34
+ takeRecords() {
35
+ return []
36
+ }
37
+ }
38
+
39
+ /** Says how much of the comment or reply `id` shows: its share of the card and its height on screen. */
40
+ function show(id: string, ratio: number, height = 60 * ratio) {
41
+ const target = document.querySelector(`[data-conversation-item="${id}"], [data-reply-id="${id}"]`)!
42
+ act(() => {
43
+ for (const o of observers) {
44
+ if (!o.targets.includes(target)) continue
45
+ const entry = { target, isIntersecting: ratio > 0, intersectionRatio: ratio, intersectionRect: { height } } as unknown as IntersectionObserverEntry
46
+ o.callback([entry], o as unknown as IntersectionObserver)
47
+ }
48
+ })
49
+ }
50
+
51
+ const wait = (ms: number) => act(() => void vi.advanceTimersByTime(ms))
52
+
53
+ function Comments({ ids, at = 'conversation' }: { ids: string[]; at?: string | null }) {
54
+ const seen = useSeenOnScreen(at)
55
+ return (
56
+ <>
57
+ <ConversationLayout
58
+ threads="beside"
59
+ seen={seen}
60
+ items={ids.map((id) => ({
61
+ id,
62
+ card: (
63
+ <ConversationCard author={ONE} time="11:08 AM">
64
+ {id}
65
+ </ConversationCard>
66
+ ),
67
+ }))}
68
+ />
69
+ <output data-testid="seen">{[...seen.ids].sort().join(',')}</output>
70
+ </>
71
+ )
72
+ }
73
+
74
+ const seenNow = () => screen.getByTestId('seen').textContent
75
+
76
+ beforeEach(() => {
77
+ observers = []
78
+ vi.useFakeTimers()
79
+ vi.stubGlobal('IntersectionObserver', FakeObserver)
80
+ })
81
+ afterEach(() => {
82
+ cleanup()
83
+ vi.useRealTimers()
84
+ vi.unstubAllGlobals()
85
+ })
86
+
87
+ describe('useSeenOnScreen, in a ConversationLayout', () => {
88
+ it('a comment on screen for the dwell is seen; one never shown is not', () => {
89
+ render(<Comments ids={['a', 'b']} />)
90
+ show('a', 1)
91
+ wait(DWELL)
92
+ expect(seenNow()).toBe('a')
93
+ })
94
+
95
+ it('scrolling past before the dwell reads nothing', () => {
96
+ render(<Comments ids={['a']} />)
97
+ show('a', 1)
98
+ wait(DWELL - 100)
99
+ show('a', 0)
100
+ wait(DWELL)
101
+ expect(seenNow()).toBe('')
102
+ })
103
+
104
+ it('a sliver is not enough; half, or enough of a tall card, is', () => {
105
+ render(<Comments ids={['a', 'b', 'c']} />)
106
+ show('a', 0.2)
107
+ show('b', 0.5)
108
+ show('c', 0.3, 300)
109
+ wait(DWELL)
110
+ expect(seenNow()).toBe('b,c')
111
+ })
112
+
113
+ it('a comment drawn later is watched too', () => {
114
+ const { rerender } = render(<Comments ids={['a']} />)
115
+ rerender(<Comments ids={['a', 'b']} />)
116
+ show('b', 1)
117
+ wait(DWELL)
118
+ expect(seenNow()).toBe('b')
119
+ })
120
+
121
+ it('a hidden tab reads nothing until it is shown again', () => {
122
+ render(<Comments ids={['a']} />)
123
+ const hidden = vi.spyOn(document, 'hidden', 'get').mockReturnValue(true)
124
+ show('a', 1)
125
+ wait(DWELL * 2)
126
+ expect(seenNow()).toBe('')
127
+ hidden.mockReturnValue(false)
128
+ act(() => void document.dispatchEvent(new Event('visibilitychange')))
129
+ wait(DWELL)
130
+ expect(seenNow()).toBe('a')
131
+ })
132
+
133
+ it('starts again empty for another conversation, and watches nothing while it has none', () => {
134
+ const { rerender } = render(<Comments ids={['a']} />)
135
+ show('a', 1)
136
+ wait(DWELL)
137
+ expect(seenNow()).toBe('a')
138
+ rerender(<Comments ids={['a']} at="another" />)
139
+ expect(seenNow()).toBe('')
140
+ rerender(<Comments ids={['a']} at={null} />)
141
+ show('a', 1)
142
+ wait(DWELL)
143
+ expect(seenNow()).toBe('')
144
+ })
145
+ })
146
+
147
+ describe('useSeenOnScreen, in a Thread', () => {
148
+ function Replies({ ids }: { ids: string[] }) {
149
+ const seen = useSeenOnScreen('thread')
150
+ return (
151
+ <>
152
+ <Thread start={{ author: ONE, time: '11:08 AM', words: 'The comment' }} seen={seen}>
153
+ {ids.map((id) => (
154
+ <ReplyCard key={id} id={id} author={ONE} time="11:30 AM">
155
+ {id}
156
+ </ReplyCard>
157
+ ))}
158
+ </Thread>
159
+ <output data-testid="seen">{[...seen.ids].sort().join(',')}</output>
160
+ </>
161
+ )
162
+ }
163
+
164
+ it('a reply on screen for the dwell is seen; one never shown is not', () => {
165
+ render(<Replies ids={['r1', 'r2']} />)
166
+ show('r2', 1)
167
+ wait(DWELL)
168
+ expect(seenNow()).toBe('r2')
169
+ })
170
+ })
171
+
172
+ describe('useSeenOnScreen, where there is no IntersectionObserver (a test’s page)', () => {
173
+ it('everything drawn counts as on screen: the dwell alone decides', () => {
174
+ vi.unstubAllGlobals()
175
+ vi.stubGlobal('IntersectionObserver', undefined)
176
+ render(<Comments ids={['a', 'b']} />)
177
+ wait(DWELL - 1)
178
+ expect(seenNow()).toBe('')
179
+ wait(1)
180
+ expect(seenNow()).toBe('a,b')
181
+ })
182
+ })