@estiva-app/ui 0.118.0 → 0.120.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/NavTree.tsx CHANGED
@@ -4,6 +4,7 @@ import { EmptyState } from './EmptyState'
4
4
  import { NavItem } from './NavItem'
5
5
  import { SectionHeader, type SectionAction } from './SectionHeader'
6
6
  import { SkeletonList } from './Skeleton'
7
+ import { REVEAL_MS, scrollToRow, useRevealCurrentRow } from './revealCurrentRow'
7
8
 
8
9
  /** One row of the tree, and the rows under it. */
9
10
  export interface NavTreeNode {
@@ -123,7 +124,7 @@ export interface NavTreeProps {
123
124
  export const NAV_TREE_INTENT_MS = 150
124
125
 
125
126
  /** How long the column waits to scroll to the current row: the rows above it slide open in 150ms. */
126
- export const NAV_TREE_REVEAL_MS = 200
127
+ export const NAV_TREE_REVEAL_MS = REVEAL_MS
127
128
 
128
129
  /** How long a `pending` group waits shut for its rows before it opens on the skeleton (Peek's Folders, OPT-11: a cold read is ~0.9s). */
129
130
  export const NAV_TREE_PENDING_MS = 2000
@@ -163,22 +164,6 @@ function openingFor(groups: NavTreeGroup[], selected: string | undefined, select
163
164
  return null
164
165
  }
165
166
 
166
- /**
167
- * Scroll the column the row is in, and only that box — never the page, nor a
168
- * drawer that is shut — so the row is in sight. A row in sight stays put.
169
- * A group taller than the column keeps its top in sight, as the browser's
170
- * `block: 'nearest'` does (a row is never that tall).
171
- */
172
- function scrollToRow(row: HTMLElement) {
173
- let box = row.parentElement
174
- while (box && !(/(auto|scroll)/.test(getComputedStyle(box).overflowY) && box.scrollHeight > box.clientHeight)) box = box.parentElement
175
- if (!box || box === document.documentElement || box === document.body) return
176
- const at = row.getBoundingClientRect()
177
- const view = box.getBoundingClientRect()
178
- if (at.top < view.top) box.scrollTop -= view.top - at.top
179
- else if (at.bottom > view.bottom) box.scrollTop += Math.min(at.bottom - view.bottom, at.top - view.top)
180
- }
181
-
182
167
  /** A line in the rows' place: level with the rows, which pad themselves (Katerina, 14 September) — `EmptyState`'s `rows`, as an app draws it under its own rows. */
183
168
  function Line({ message }: { message: string }) {
184
169
  return <EmptyState scope="rows" message={message} />
@@ -381,23 +366,12 @@ export function NavTreeSection({ id, title, message, loading = false, pending =
381
366
  */
382
367
  export function NavTree({ title, titleActions, groups, children, selected, selectedParent, selectedGroup, onSelect, emptyMessage = '', storageKey }: NavTreeProps) {
383
368
  const opening = groups ? openingFor(groups, selected, selectedParent) : null
384
- // Once per current row, when it is drawn and shown: a later draw, or a read landing, does not pull the column back to it.
369
+ /*
370
+ Once per current row, when it is drawn and shown, however late: a row a part inside the tree draws itself (a fold
371
+ that reads its rows once it opens) is seen too. A later draw, or a read landing, does not pull the column back to it.
372
+ */
385
373
  const box = useRef<HTMLDivElement>(null)
386
- const scrolled = useRef<string | undefined>(undefined)
387
- const waiting = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
388
- const latest = useRef(selected)
389
- latest.current = selected
390
- useEffect(() => {
391
- if (selected === undefined || scrolled.current === selected || waiting.current !== undefined) return
392
- waiting.current = setTimeout(() => {
393
- waiting.current = undefined
394
- const row = box.current?.querySelector<HTMLElement>('[aria-current="page"]')
395
- if (!row || row.getBoundingClientRect().height === 0) return
396
- scrolled.current = latest.current
397
- scrollToRow(row)
398
- }, NAV_TREE_REVEAL_MS)
399
- })
400
- useEffect(() => () => clearTimeout(waiting.current), [])
374
+ useRevealCurrentRow(box, selected)
401
375
  // Once per arrival, as soon as the group is drawn: its heading does not move as it opens, so nothing is waited for.
402
376
  const groupScrolled = useRef<string | undefined>(undefined)
403
377
  useEffect(() => {
@@ -20,6 +20,17 @@ export function isNearBottom(el: HTMLElement): boolean {
20
20
  return el.scrollHeight - el.scrollTop - el.clientHeight <= NEAR_BOTTOM_PX
21
21
  }
22
22
 
23
+ /**
24
+ * Puts one comment in the middle of the comments' box: where two columns land when a conversation opens at a thread, or
25
+ * is asked to show one from outside (Katerina, 17 November: "generalize it so that it works in every similar case").
26
+ * Measured against the box, which is what scrolls.
27
+ */
28
+ export function landOn(el: HTMLElement, item: HTMLElement): void {
29
+ const box = el.getBoundingClientRect()
30
+ const at = item.getBoundingClientRect()
31
+ el.scrollTop += at.top - box.top - (el.clientHeight - at.height) / 2
32
+ }
33
+
23
34
  /**
24
35
  * 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
36
  * to the reader, whatever above it changed height.
@@ -0,0 +1,284 @@
1
+ // @vitest-environment jsdom
2
+ /**
3
+ * What the page claims (Katerina, 17 November): a list shows where the open page lives. Its current row is brought into
4
+ * the column's sight once it is drawn and shown, however late — a row a part inside the tree draws itself once its read
5
+ * lands (a team's Files fold), a plain list column's row (DMs, the Desk) — once per new current row, and never pulled
6
+ * back after the reader scrolls away.
7
+ */
8
+ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
9
+ import { act, cleanup, fireEvent, render } from '@testing-library/react'
10
+ import { useEffect, useState } from 'react'
11
+ import { ListColumn } from './ListColumn'
12
+ import { NavItem } from './NavItem'
13
+ import { NavTree } from './NavTree'
14
+ import { forgetListPlaces, REVEAL_MS } from './revealCurrentRow'
15
+
16
+ afterEach(cleanup)
17
+ beforeEach(() => vi.useFakeTimers())
18
+ afterEach(() => vi.useRealTimers())
19
+
20
+ /**
21
+ * Lays out a 100px column that scrolls 1000px, with every row 32px tall, each `at` px down its list, and the rest at its
22
+ * top. `shut` rows are in a fold that is closed: 0px tall.
23
+ */
24
+ function lay(column: HTMLElement, at: Record<string, number>, shut: Set<string> = new Set()) {
25
+ let top = 0
26
+ Object.defineProperty(column, 'scrollHeight', { configurable: true, get: () => 1000 })
27
+ Object.defineProperty(column, 'clientHeight', { configurable: true, get: () => 100 })
28
+ Object.defineProperty(column, 'scrollTop', { configurable: true, get: () => top, set: (next: number) => (top = next) })
29
+ column.style.overflowY = 'auto'
30
+ const box = (y: number, height: number) => ({ top: y, bottom: y + height, height, left: 0, right: 0, width: 0, x: 0, y, toJSON: () => ({}) }) as DOMRect
31
+ const rect = vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function (this: HTMLElement) {
32
+ if (this === column) return box(0, 100)
33
+ const label = this.textContent?.trim() ?? ''
34
+ if (shut.has(label)) return box(0, 0)
35
+ return label in at ? box(at[label]! - top, 32) : box(0, 32)
36
+ })
37
+ return { scrolled: () => top, scroll: (to: number) => (top = to), restore: () => rect.mockRestore() }
38
+ }
39
+
40
+ /** Its rows a moment after it is drawn, as a fold that reads them once it opens: the tree is not drawn again for them. */
41
+ function LateRows({ open }: { open: string }) {
42
+ const [rows, setRows] = useState<string[] | null>(null)
43
+ useEffect(() => {
44
+ const timer = setTimeout(() => setRows(['Project 1', 'Project 2', 'Project 9']), 600)
45
+ return () => clearTimeout(timer)
46
+ }, [])
47
+ return <>{rows?.map((row) => <NavItem key={row} href={`#${row}`} label={row} active={row === open} />)}</>
48
+ }
49
+
50
+ describe('a tree brings its current row into sight', () => {
51
+ it('when a part inside it draws the row late, after its read lands (a team’s Files fold)', async () => {
52
+ const { getByTestId } = render(
53
+ <div data-testid="column">
54
+ <NavTree selected="p9">
55
+ <NavItem href="#team" label="Team" />
56
+ <LateRows open="Project 9" />
57
+ </NavTree>
58
+ </div>,
59
+ )
60
+ const layout = lay(getByTestId('column'), { 'Project 9': 900 })
61
+ try {
62
+ await act(async () => vi.advanceTimersByTime(REVEAL_MS + 10))
63
+ expect(layout.scrolled()).toBe(0)
64
+ // The read lands: its rows are drawn, the tree is not.
65
+ await act(async () => vi.advanceTimersByTime(600))
66
+ await act(async () => vi.advanceTimersByTime(REVEAL_MS + 10))
67
+ // Its bottom edge at the column's: 900 + 32 − 100.
68
+ expect(layout.scrolled()).toBe(832)
69
+ } finally {
70
+ layout.restore()
71
+ }
72
+ })
73
+
74
+ it('once: scrolled away from, it is not brought back while it stays the current row', async () => {
75
+ const { getByTestId, rerender } = render(
76
+ <div data-testid="column">
77
+ <NavTree selected="b">
78
+ <NavItem href="#a" label="Item a" />
79
+ <NavItem href="#b" label="Item b" active />
80
+ </NavTree>
81
+ </div>,
82
+ )
83
+ const layout = lay(getByTestId('column'), { 'Item b': 500 })
84
+ try {
85
+ await act(async () => vi.advanceTimersByTime(REVEAL_MS + 10))
86
+ expect(layout.scrolled()).toBe(432)
87
+ layout.scroll(0)
88
+ rerender(
89
+ <div data-testid="column">
90
+ <NavTree selected="b">
91
+ <NavItem href="#a" label="Item a (2)" />
92
+ <NavItem href="#b" label="Item b" active />
93
+ </NavTree>
94
+ </div>,
95
+ )
96
+ await act(async () => {})
97
+ await act(async () => vi.advanceTimersByTime(REVEAL_MS + 10))
98
+ expect(layout.scrolled()).toBe(0)
99
+ } finally {
100
+ layout.restore()
101
+ }
102
+ })
103
+
104
+ it('a row in a shut fold waits for the fold to open', async () => {
105
+ const shut = new Set(['Item b'])
106
+ const { getByTestId } = render(
107
+ <div data-testid="column">
108
+ <NavTree selected="b">
109
+ <NavItem href="#b" label="Item b" active />
110
+ </NavTree>
111
+ </div>,
112
+ )
113
+ const layout = lay(getByTestId('column'), { 'Item b': 500 }, shut)
114
+ try {
115
+ await act(async () => vi.advanceTimersByTime(REVEAL_MS + 10))
116
+ expect(layout.scrolled()).toBe(0)
117
+ // The fold opens: its content is shown, which changes the list.
118
+ shut.clear()
119
+ await act(async () => getByTestId('column').querySelector('a')!.setAttribute('hidden', ''))
120
+ await act(async () => getByTestId('column').querySelector('a')!.removeAttribute('hidden'))
121
+ await act(async () => vi.advanceTimersByTime(REVEAL_MS + 10))
122
+ expect(layout.scrolled()).toBe(432)
123
+ } finally {
124
+ layout.restore()
125
+ }
126
+ })
127
+ })
128
+
129
+ describe('a list column brings its current row into sight (DMs, the Desk)', () => {
130
+ function People({ open }: { open: string }) {
131
+ return (
132
+ <ListColumn title="DMs">
133
+ {Array.from({ length: 30 }, (_, i) => `Person ${i}`).map((name) => (
134
+ <NavItem key={name} href={`#${name}`} label={name} active={name === open} />
135
+ ))}
136
+ </ListColumn>
137
+ )
138
+ }
139
+ const viewport = () => document.querySelector<HTMLElement>('[data-id$="-viewport"]') ?? document.querySelector<HTMLElement>('[style*="overflow"]')!
140
+
141
+ it('its open row below the fold, and each new open row after it', async () => {
142
+ const { rerender } = render(<People open="Person 25" />)
143
+ const layout = lay(viewport(), { 'Person 25': 800, 'Person 2': 64 })
144
+ try {
145
+ await act(async () => vi.advanceTimersByTime(REVEAL_MS + 10))
146
+ expect(layout.scrolled()).toBe(732)
147
+ // Another opens, above: the column goes up to it.
148
+ rerender(<People open="Person 2" />)
149
+ // What changed in the list is heard first, then the look a moment later.
150
+ await act(async () => {})
151
+ await act(async () => vi.advanceTimersByTime(REVEAL_MS + 10))
152
+ expect(layout.scrolled()).toBe(64)
153
+ } finally {
154
+ layout.restore()
155
+ }
156
+ })
157
+
158
+ it('a row already in sight stays put', async () => {
159
+ render(<People open="Person 1" />)
160
+ const layout = lay(viewport(), { 'Person 1': 32 })
161
+ try {
162
+ await act(async () => vi.advanceTimersByTime(REVEAL_MS + 10))
163
+ expect(layout.scrolled()).toBe(0)
164
+ } finally {
165
+ layout.restore()
166
+ }
167
+ })
168
+ })
169
+
170
+ /*
171
+ The same column drawn again on another page (Peek's Teams column on a team's page, then on a topic's): it goes back
172
+ to where the reader left it, by the name the app gives it, and a row it already brought into sight is not brought
173
+ back (Katerina, 17 November: "I have scrolled down a little and then click on something and it scrolls up back to
174
+ top"). A new open row still comes into sight.
175
+ */
176
+ describe('a list column drawn again goes back to where it was left (rememberAs)', () => {
177
+ afterEach(() => forgetListPlaces())
178
+ function Named({ open, name }: { open: string; name?: string }) {
179
+ return (
180
+ <ListColumn title="DMs" {...(name ? { rememberAs: name } : {})}>
181
+ {Array.from({ length: 30 }, (_, i) => `Person ${i}`).map((person) => (
182
+ <NavItem key={person} href={`#${person}`} label={person} active={person === open} />
183
+ ))}
184
+ </ListColumn>
185
+ )
186
+ }
187
+ const viewport = () => document.querySelector<HTMLElement>('[data-id$="-viewport"]') ?? document.querySelector<HTMLElement>('[style*="overflow"]')!
188
+
189
+ /** Draws it, lets it bring its open row into sight, and the reader scrolls to `to`; then it is taken away. */
190
+ async function leaveAt(to: number, open = 'Person 25', name = 'dms') {
191
+ const first = render(<Named open={open} name={name} />)
192
+ const layout = lay(viewport(), { 'Person 25': 800, 'Person 2': 64 })
193
+ await act(async () => vi.advanceTimersByTime(REVEAL_MS + 10))
194
+ layout.scroll(to)
195
+ fireEvent.scroll(viewport())
196
+ first.unmount()
197
+ layout.restore()
198
+ }
199
+
200
+ it('drawn again under the same name, it opens where the reader left it, and does not pull them back to its open row', async () => {
201
+ await leaveAt(300)
202
+ render(<Named open="Person 25" name="dms" />)
203
+ expect(viewport().scrollTop).toBe(300)
204
+ const layout = lay(viewport(), { 'Person 25': 800, 'Person 2': 64 })
205
+ layout.scroll(300)
206
+ try {
207
+ await act(async () => vi.advanceTimersByTime(REVEAL_MS + 10))
208
+ expect(layout.scrolled()).toBe(300)
209
+ } finally {
210
+ layout.restore()
211
+ }
212
+ })
213
+
214
+ it('a new open row still comes into sight', async () => {
215
+ await leaveAt(300)
216
+ render(<Named open="Person 2" name="dms" />)
217
+ const layout = lay(viewport(), { 'Person 25': 800, 'Person 2': 64 })
218
+ layout.scroll(300)
219
+ try {
220
+ await act(async () => vi.advanceTimersByTime(REVEAL_MS + 10))
221
+ expect(layout.scrolled()).toBe(64)
222
+ } finally {
223
+ layout.restore()
224
+ }
225
+ })
226
+
227
+ it('a new open row is brought into sight at once, even when the place it was left at can no longer be reached', async () => {
228
+ await leaveAt(900)
229
+ // The list is shorter now (a fold that was open is shut): it scrolls no further than 300.
230
+ const tops = new WeakMap<HTMLElement, number>()
231
+ Object.defineProperty(HTMLElement.prototype, 'scrollTop', {
232
+ configurable: true,
233
+ get(this: HTMLElement) {
234
+ return tops.get(this) ?? 0
235
+ },
236
+ set(this: HTMLElement, next: number) {
237
+ tops.set(this, Math.max(0, Math.min(next, 300)))
238
+ },
239
+ })
240
+ try {
241
+ render(<Named open="Person 2" name="dms" />)
242
+ expect(viewport().scrollTop).toBe(300)
243
+ const layout = lay(viewport(), { 'Person 25': 800, 'Person 2': 64 })
244
+ layout.scroll(300)
245
+ try {
246
+ // At the reveal's moment, not once going back gives up (RESTORE_MS).
247
+ await act(async () => vi.advanceTimersByTime(REVEAL_MS + 10))
248
+ expect(layout.scrolled()).toBe(64)
249
+ } finally {
250
+ layout.restore()
251
+ }
252
+ } finally {
253
+ delete (HTMLElement.prototype as { scrollTop?: number }).scrollTop
254
+ }
255
+ })
256
+
257
+ // Smooth (Katerina, 17 November, "lets smooth it"): no stop at the old place first, then a move 200ms later.
258
+ it('drawn again with a new open row already drawn, it is at its one place as soon as it is drawn', async () => {
259
+ await leaveAt(300)
260
+ // Laid out before it is drawn: the box 100px tall at the page's top; Person 2 64px down the list, the rest at its top.
261
+ const box = (y: number, height: number) => ({ top: y, bottom: y + height, height, left: 0, right: 0, width: 0, x: 0, y, toJSON: () => ({}) }) as DOMRect
262
+ const rect = vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function (this: HTMLElement) {
263
+ const scroller = viewport()
264
+ if (this === scroller) return box(0, 100)
265
+ return this.textContent?.trim() === 'Person 2' ? box(64 - (scroller?.scrollTop ?? 0), 32) : box(0, 32)
266
+ })
267
+ try {
268
+ render(<Named open="Person 2" name="dms" />)
269
+ // Back at 300, the row is above the view: the least move shows it, before any timer has run.
270
+ expect(viewport().scrollTop).toBe(64)
271
+ } finally {
272
+ rect.mockRestore()
273
+ }
274
+ })
275
+
276
+ it('without a name, or under another, it opens at the top', async () => {
277
+ await leaveAt(300)
278
+ const unnamed = render(<Named open="Person 1" />)
279
+ expect(viewport().scrollTop).toBe(0)
280
+ unnamed.unmount()
281
+ render(<Named open="Person 1" name="desk" />)
282
+ expect(viewport().scrollTop).toBe(0)
283
+ })
284
+ })
@@ -0,0 +1,177 @@
1
+ import { createContext, useContext, useEffect, useLayoutEffect, useMemo, useRef, type RefObject } from 'react'
2
+
3
+ /**
4
+ * Showing where the open page lives in a list: its row (`aria-current="page"`, what `NavItem`'s `active` sets) brought
5
+ * into the column's sight, once for each new current row, whenever it is drawn and shown (Katerina, 17 November: "the
6
+ * selected [row] could be somewhere above or below the fold … a general problem we need to fix").
7
+ *
8
+ * However late: a row a fold reads only once it opens, a group sliding open, rows that arrive with a read. The list is
9
+ * watched for what changes in it, not for its own draws, so a row drawn by a part inside it is seen too (a team's Files
10
+ * fold, which reads its files itself, never drew the tree again: its open file stayed below the fold).
11
+ *
12
+ * Once: a row brought into sight is not brought back after the reader scrolls away, while it stays the current one;
13
+ * a new current row is.
14
+ */
15
+
16
+ /** How long it waits to look, after the list changes: a group above the row slides open in 150ms. */
17
+ export const REVEAL_MS = 200
18
+
19
+ /**
20
+ * Scroll the column the row is in, and only that box — never the page, nor a
21
+ * drawer that is shut — so the row is in sight. A row in sight stays put.
22
+ * A group taller than the column keeps its top in sight, as the browser's
23
+ * `block: 'nearest'` does (a row is never that tall).
24
+ */
25
+ export function scrollToRow(row: HTMLElement) {
26
+ let box = row.parentElement
27
+ while (box && !(/(auto|scroll)/.test(getComputedStyle(box).overflowY) && box.scrollHeight > box.clientHeight)) box = box.parentElement
28
+ if (!box || box === document.documentElement || box === document.body) return
29
+ scrollRowInto(box, row)
30
+ }
31
+
32
+ /** Brings a row into a box's sight by the least move: to its top edge from above, to its bottom edge from below. */
33
+ function scrollRowInto(box: HTMLElement, row: HTMLElement) {
34
+ const at = row.getBoundingClientRect()
35
+ const view = box.getBoundingClientRect()
36
+ if (at.top < view.top) box.scrollTop -= view.top - at.top
37
+ else if (at.bottom > view.bottom) box.scrollTop += Math.min(at.bottom - view.bottom, at.top - view.top)
38
+ }
39
+
40
+ /** The key a list's open row is known by, from one drawing to the next: what a reveal compares. */
41
+ const keyOf = (row: HTMLElement, current?: string) => current ?? row.getAttribute('href') ?? row.textContent ?? ''
42
+
43
+ /**
44
+ * Brings the current row inside `box` into sight, once per current row. `current` names it when the caller knows it
45
+ * (`NavTree`'s `selected`); without it, the row is known by its link.
46
+ */
47
+ /**
48
+ * Where each named list was left, in this tab: how far it was scrolled, and the open row it last brought into sight. A
49
+ * list drawn again under the same name (the same column on another page) goes back there, and does not show again a
50
+ * row it already showed (Katerina, 17 November: "I have scrolled down a little and then click on something and it
51
+ * scrolls up back to top").
52
+ */
53
+ const places = new Map<string, { top?: number; shown?: string }>()
54
+
55
+ /** For tests: every list forgets where it was. */
56
+ export function forgetListPlaces(): void {
57
+ places.clear()
58
+ }
59
+
60
+ /** How long a list drawn again keeps trying to reach where it was left, while its rows are still being drawn. */
61
+ export const RESTORE_MS = 2000
62
+
63
+ /** A named list's place, for the reveal inside it: its name, and whether it is still going back to where it was. */
64
+ export interface ListPlace {
65
+ name?: string
66
+ restoring: RefObject<boolean>
67
+ }
68
+
69
+ /** The list a row is revealed in: a `ListColumn` gives its name to the tree inside it, which reveals nothing itself. */
70
+ export const ListPlaceContext = createContext<ListPlace | null>(null)
71
+
72
+ /**
73
+ * Goes back to where the named list was left, and keeps note of where the reader leaves it. Its rows may still be
74
+ * drawing (a skeleton, a fold that reads its own rows): it tries again as the list grows, until it is there, the reader
75
+ * scrolls, something else moves it (a row brought into sight), or `RESTORE_MS` has passed.
76
+ */
77
+ export function useListPlace(box: RefObject<HTMLElement | null>, name: string | undefined): ListPlace {
78
+ const restoring = useRef(false)
79
+ useLayoutEffect(() => {
80
+ const el = box.current
81
+ if (!el || !name) return
82
+ const want = places.get(name)?.top ?? 0
83
+ restoring.current = want > 0
84
+ let set = el.scrollTop
85
+ const keep = () => places.set(name, { ...places.get(name), top: el.scrollTop })
86
+ const finish = () => {
87
+ restoring.current = false
88
+ }
89
+ const restore = () => {
90
+ if (!restoring.current) return
91
+ el.scrollTop = want
92
+ set = el.scrollTop
93
+ if (Math.abs(el.scrollTop - want) < 1) finish()
94
+ }
95
+ restore()
96
+ /*
97
+ A new open row already drawn is brought into sight in the same moment, before the column is painted, so the reader
98
+ sees one place: where they left it, or the least move from it that shows the row (Katerina, 17 November: "lets
99
+ smooth it"). The row it showed last stays where they put it; one drawn later is the reveal's.
100
+ */
101
+ const open = el.querySelector<HTMLElement>('[aria-current="page"]')
102
+ const key = open && open.getBoundingClientRect().height > 0 ? keyOf(open) : undefined
103
+ if (open && key !== undefined && key !== places.get(name)?.shown) {
104
+ finish()
105
+ places.set(name, { ...places.get(name), shown: key })
106
+ scrollRowInto(el, open)
107
+ set = el.scrollTop
108
+ }
109
+ const grows = typeof ResizeObserver === 'undefined' ? undefined : new ResizeObserver(restore)
110
+ if (el.firstElementChild) grows?.observe(el.firstElementChild)
111
+ const until = setTimeout(finish, RESTORE_MS)
112
+ // The reader takes over.
113
+ const took = () => finish()
114
+ const scrolled = () => {
115
+ // Moved by anything but the restore: what moved it stands.
116
+ if (restoring.current && Math.abs(el.scrollTop - set) > 1) finish()
117
+ if (!restoring.current) keep()
118
+ }
119
+ const takes = ['wheel', 'touchstart', 'pointerdown', 'keydown'] as const
120
+ el.addEventListener('scroll', scrolled, { passive: true })
121
+ for (const type of takes) el.addEventListener(type, took, { passive: true })
122
+ return () => {
123
+ el.removeEventListener('scroll', scrolled)
124
+ for (const type of takes) el.removeEventListener(type, took)
125
+ grows?.disconnect()
126
+ clearTimeout(until)
127
+ if (!restoring.current) keep()
128
+ restoring.current = false
129
+ }
130
+ }, [box, name])
131
+ // One object per name: the reveal and the tree inside take it, and look again only when the name changes.
132
+ return useMemo(() => ({ name, restoring }), [name])
133
+ }
134
+
135
+ export function useRevealCurrentRow(box: RefObject<HTMLElement | null>, current?: string, place?: ListPlace): void {
136
+ const shown = useRef<string | undefined>(undefined)
137
+ // Inside a `ListColumn`, the column brings its rows into sight: a tree in it reveals nothing itself.
138
+ const within = useContext(ListPlaceContext)
139
+ const deferred = !place && within !== null
140
+ useEffect(() => {
141
+ const root = box.current
142
+ if (!root || deferred) return
143
+ // The open row it last showed: the named list's, which outlives the column being drawn again; else this one's.
144
+ const was = () => (place?.name ? places.get(place.name)?.shown : shown.current)
145
+ const showing = (key: string) => {
146
+ if (place?.name) places.set(place.name, { ...places.get(place.name), shown: key })
147
+ else shown.current = key
148
+ }
149
+ let timer: ReturnType<typeof setTimeout> | undefined
150
+ const look = () => {
151
+ timer = undefined
152
+ const row = root.querySelector<HTMLElement>('[aria-current="page"]')
153
+ if (!row) return
154
+ const key = keyOf(row, current)
155
+ // The row it showed last: the list goes back to where it was left, and the row stays where the reader put it.
156
+ if (was() === key) return
157
+ // Not drawn yet, or inside a fold that is shut: whatever opens it changes the list, and it is looked for again.
158
+ if (row.getBoundingClientRect().height === 0) return
159
+ // A new open row wins at once, the reader asked for it: going back to where the list was left stops here, even
160
+ // when that place can no longer be reached (a fold that was open is shut).
161
+ if (place) place.restoring.current = false
162
+ showing(key)
163
+ scrollToRow(row)
164
+ }
165
+ // One look a moment after the list changes, however often it does: a live list changes all the time.
166
+ const soon = () => {
167
+ if (timer === undefined) timer = setTimeout(look, REVEAL_MS)
168
+ }
169
+ const watch = typeof MutationObserver === 'undefined' ? undefined : new MutationObserver(soon)
170
+ watch?.observe(root, { subtree: true, childList: true, attributes: true, attributeFilter: ['aria-current', 'hidden'] })
171
+ soon()
172
+ return () => {
173
+ watch?.disconnect()
174
+ if (timer !== undefined) clearTimeout(timer)
175
+ }
176
+ }, [box, current, place, deferred])
177
+ }
@@ -59,6 +59,15 @@ function show(id: string, options: ShowOptions): boolean {
59
59
  const el = find(id, options)
60
60
  if (!el) return false
61
61
  el.scrollIntoView({ behavior: 'smooth', block: 'center' })
62
+ markShown(el)
63
+ return true
64
+ }
65
+
66
+ /**
67
+ * Marks one drawn comment or reply a moment (`data-shown`, the kit's flash): a show's mark, and the one a
68
+ * `ConversationLayout` gives the comment it lands on when it opens at a thread. The package's own, not exported.
69
+ */
70
+ export function markShown(el: HTMLElement): void {
62
71
  const previous = owed.get(el)
63
72
  if (previous !== undefined) window.clearTimeout(previous)
64
73
  el.dataset.shown = 'true'
@@ -69,7 +78,6 @@ function show(id: string, options: ShowOptions): boolean {
69
78
  owed.delete(el)
70
79
  }, SHOWN_MS),
71
80
  )
72
- return true
73
81
  }
74
82
 
75
83
  /**