@estiva-app/ui 0.118.0 → 0.119.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.
@@ -0,0 +1,28 @@
1
+ import { type RefObject } from 'react';
2
+ /**
3
+ * Showing where the open page lives in a list: its row (`aria-current="page"`, what `NavItem`'s `active` sets) brought
4
+ * into the column's sight, once for each new current row, whenever it is drawn and shown (Katerina, 17 November: "the
5
+ * selected [row] could be somewhere above or below the fold … a general problem we need to fix").
6
+ *
7
+ * However late: a row a fold reads only once it opens, a group sliding open, rows that arrive with a read. The list is
8
+ * 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
9
+ * fold, which reads its files itself, never drew the tree again: its open file stayed below the fold).
10
+ *
11
+ * Once: a row brought into sight is not brought back after the reader scrolls away, while it stays the current one;
12
+ * a new current row is.
13
+ */
14
+ /** How long it waits to look, after the list changes: a group above the row slides open in 150ms. */
15
+ export declare const REVEAL_MS = 200;
16
+ /**
17
+ * Scroll the column the row is in, and only that box — never the page, nor a
18
+ * drawer that is shut — so the row is in sight. A row in sight stays put.
19
+ * A group taller than the column keeps its top in sight, as the browser's
20
+ * `block: 'nearest'` does (a row is never that tall).
21
+ */
22
+ export declare function scrollToRow(row: HTMLElement): void;
23
+ /**
24
+ * Brings the current row inside `box` into sight, once per current row. `current` names it when the caller knows it
25
+ * (`NavTree`'s `selected`); without it, the row is known by its link.
26
+ */
27
+ export declare function useRevealCurrentRow(box: RefObject<HTMLElement | null>, current?: string): void;
28
+ //# sourceMappingURL=revealCurrentRow.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"revealCurrentRow.d.ts","sourceRoot":"","sources":["../src/revealCurrentRow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAEzD;;;;;;;;;;;GAWG;AAEH,qGAAqG;AACrG,eAAO,MAAM,SAAS,MAAM,CAAA;AAE5B;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,WAAW,QAQ3C;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CA6B9F"}
@@ -21,6 +21,11 @@ export interface ShowWhenDrawnOptions extends ShowOptions {
21
21
  * nothing, so the caller says it, or opens its thread and waits with `showInConversationWhenDrawn`.
22
22
  */
23
23
  export declare function showInConversation(id: string, options?: ShowOptions): boolean;
24
+ /**
25
+ * Marks one drawn comment or reply a moment (`data-shown`, the kit's flash): a show's mark, and the one a
26
+ * `ConversationLayout` gives the comment it lands on when it opens at a thread. The package's own, not exported.
27
+ */
28
+ export declare function markShown(el: HTMLElement): void;
24
29
  /**
25
30
  * The same, for one that may not be drawn yet: its thread was just asked to open, and the page draws it a moment
26
31
  * later. Looks every 50ms, for 3 seconds (`wait`), and answers whether it was shown: `false` must be said, since
@@ -1 +1 @@
1
- {"version":3,"file":"showInConversation.d.ts","sourceRoot":"","sources":["../src/showInConversation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAoBH,MAAM,WAAW,WAAW;IAC1B,8GAA8G;IAC9G,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,oBAAqB,SAAQ,WAAW;IACvD,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAUD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAGjF;AAoBD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,IAAc,EAAE,GAAG,OAAO,EAAE,GAAE,oBAAyB,GAAG,OAAO,CAAC,OAAO,CAAC,CAYnI"}
1
+ {"version":3,"file":"showInConversation.d.ts","sourceRoot":"","sources":["../src/showInConversation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAoBH,MAAM,WAAW,WAAW;IAC1B,8GAA8G;IAC9G,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,oBAAqB,SAAQ,WAAW;IACvD,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAUD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAGjF;AAWD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,CAW/C;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,IAAc,EAAE,GAAG,OAAO,EAAE,GAAE,oBAAyB,GAAG,OAAO,CAAC,OAAO,CAAC,CAYnI"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@estiva-app/ui",
3
- "version": "0.118.0",
3
+ "version": "0.119.0",
4
4
  "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
5
5
  "type": "module",
6
6
  "license": "MIT",
package/registry.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "kind": "package",
5
5
  "repo": "estiva-ui",
6
6
  "package": "@estiva-app/ui",
7
- "packageVersion": "0.118.0",
7
+ "packageVersion": "0.119.0",
8
8
  "exports": 256,
9
9
  "typeExports": 270,
10
10
  "files": null
@@ -58,7 +58,10 @@ import { ConversationLayout } from '@estiva-app/ui'
58
58
  - Write nothing on the cards for opening: no `onClick`, `selected`, `onReply`, or the replies row's `onOpen` and
59
59
  `open`. The layout gives each **ConversationCard** its place, and the card opens its thread from it. What a card is
60
60
  given still wins.
61
- - Two columns, where the comments scroll is the layout's, the same in every app: they open at the newest; they
61
+ - Two columns, where the comments scroll is the layout's, the same in every app: they open at the newest, or on the
62
+ open thread's comment when they open at one (a link to it, a line naming it), in the middle and marked a moment; a
63
+ thread opened from outside while they are open lands on its comment too, and one opened by pressing its comment stays
64
+ where it is; they
62
65
  follow what arrives only while the reader is at the bottom (within 80px); the reader's own comment, sent from `box`,
63
66
  brings them down to it as it is drawn, and a refusal leaves them where they are; and they hold still while cards and
64
67
  pictures fill in. Give the conversation its name, `rememberAs` (its address), and going back to it lands where it was
@@ -97,7 +100,7 @@ import { ConversationLayout } from '@estiva-app/ui'
97
100
  | Opens and closes in place: the comment is never redrawn and does not move, open or closed | a wrapper that changes when it opens | |
98
101
  | One column: resolved comments and comments on deleted blocks closed under their names at the end, opened for the thread open in them | the groups, their counts, opening one | |
99
102
  | Puts the caret in the box of a thread that opens, without scrolling | a focus call | |
100
- | Two columns: opens at the newest, comes back to where it was left, follows only a reader at the bottom, goes down to the reader's own comment, holds still while cards load | a scroll policy, a place per conversation, a ResizeObserver | |
103
+ | Two columns: opens at the newest, or lands on the open thread's comment (marked) when it opens at one or one is opened from outside; comes back to where it was left, follows only a reader at the bottom, goes down to the reader's own comment, holds still while cards load | a scroll policy, a place per conversation, a ResizeObserver | |
101
104
  | Placeholders while reading, and a line when there are none | a loading and an empty state | |
102
105
  | Says which comments have been on screen a moment, with `seen` | an IntersectionObserver and a timer per card | |
103
106
  | The right column at 384px, in every app: the open thread, or the page's `aside` | a width, a column, its error boundary | |
@@ -6,7 +6,7 @@
6
6
  * down to the reader's own comment as it is sent. A thread opens at its newest reply and goes to each new one. jsdom
7
7
  * has no layout: every box here says the same heights, and only the scrolling box's offset is read.
8
8
  */
9
- import { useContext, type ReactNode } from 'react'
9
+ import { useContext, useState, type ReactNode } from 'react'
10
10
  import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
11
11
  import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
12
12
  import { ConversationCard, ReplyCard } from './ConversationCard'
@@ -194,6 +194,67 @@ describe('ConversationLayout, two columns, where it scrolls', () => {
194
194
  })
195
195
  })
196
196
 
197
+ /*
198
+ Opened at a thread — a link to it, a line in a list that names it — two columns land on its comment, in the middle and
199
+ marked a moment, not at the newest (Katerina, 17 November: "the selected message could be somewhere above or below the
200
+ fold. It's a general problem we need to fix"). jsdom has no layout, so the box and the comment say where they are.
201
+ */
202
+ describe('ConversationLayout, two columns, opened at a thread', () => {
203
+ /** The box sits 100px down the page, 400px tall; comment c3 is 900px down, 100px tall, when the box is at the top. */
204
+ const where = (box: { current: HTMLDivElement | null }) =>
205
+ vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function (this: HTMLElement) {
206
+ const top = this === box.current ? 100 : this.getAttribute('data-conversation-item') === 'c3' ? 900 - (box.current?.scrollTop ?? 0) : 0
207
+ const height = this === box.current ? 400 : 100
208
+ return { top, height, bottom: top + height, left: 0, right: 0, width: 0, x: 0, y: top, toJSON: () => ({}) } as DOMRect
209
+ })
210
+ afterEach(() => vi.restoreAllMocks())
211
+ const comment = (id: string) => document.querySelector<HTMLElement>(`[data-conversation-item="${id}"]`)!
212
+
213
+ it('opens on the open thread’s comment, in the middle and marked, not at the newest', () => {
214
+ // A long conversation: the comment lands far from its newest, where following what arrives does not move it.
215
+ heights.scroll = 3000
216
+ const box = { current: null as HTMLDivElement | null }
217
+ where(box)
218
+ const { rerender } = render(<ConversationLayout threads="beside" items={[]} loading open="c3" bodyRef={box} />)
219
+ rerender(<ConversationLayout threads="beside" items={many(8)} open="c3" bodyRef={box} />)
220
+ // 900 down the page, less the box's 100, less what centres a 100px comment in 400px: 650.
221
+ expect(box.current!.scrollTop).toBe(650)
222
+ expect(comment('c3').dataset.shown).toBe('true')
223
+ })
224
+
225
+ it('a thread opened from outside while it is open lands on its comment too', () => {
226
+ heights.scroll = 3000
227
+ const box = { current: null as HTMLDivElement | null }
228
+ const { rerender } = render(<ConversationLayout threads="beside" items={many(8)} bodyRef={box} />)
229
+ expect(box.current!.scrollTop).toBe(3000)
230
+ scrollTo(box.current!, 0)
231
+ where(box)
232
+ rerender(<ConversationLayout threads="beside" items={many(8)} open="c3" bodyRef={box} />)
233
+ expect(box.current!.scrollTop).toBe(650)
234
+ expect(comment('c3').dataset.shown).toBe('true')
235
+ })
236
+
237
+ it('a press on a comment opens its thread where it is: nothing moves, nothing is marked', () => {
238
+ const box = { current: null as HTMLDivElement | null }
239
+ function Pressed() {
240
+ const [open, setOpen] = useState<string | undefined>(undefined)
241
+ return <ConversationLayout threads="beside" items={many(8)} open={open} onOpenChange={setOpen} bodyRef={box} />
242
+ }
243
+ render(<Pressed />)
244
+ scrollTo(box.current!, 300)
245
+ where(box)
246
+ fireEvent.click(screen.getByText('Comment c3'))
247
+ expect(box.current!.scrollTop).toBe(300)
248
+ expect(comment('c3').dataset.shown).toBeUndefined()
249
+ })
250
+
251
+ it('a thread whose comment is not drawn (older than what is read) opens at the newest, as before', () => {
252
+ const box = { current: null as HTMLDivElement | null }
253
+ render(<ConversationLayout threads="beside" items={many(8)} open="not-read" bodyRef={box} />)
254
+ expect(box.current!.scrollTop).toBe(1000)
255
+ })
256
+ })
257
+
197
258
  describe('useLeftAt: when the reader left a conversation, for its "New" line', () => {
198
259
  function LeftAt({ at, boxRef, items }: { at: string; boxRef: { current: HTMLDivElement | null }; items: ConversationItem[] }) {
199
260
  const left = useLeftAt(at)
@@ -12,6 +12,7 @@ import { QuotedLine } from './QuotedLine'
12
12
  import { SkeletonBar } from './Skeleton'
13
13
  import { useSeenOnScreen } from './seenOnScreen'
14
14
  import { Thread } from './Thread'
15
+ import { Toolbar, ToolbarButton } from './Toolbar'
15
16
 
16
17
  /**
17
18
  * Where the cards sit. Two columns: the comments fill the page and an open thread stands beside them. One column:
@@ -188,6 +189,49 @@ export const TwoColumnsLong: Story = {
188
189
  },
189
190
  }
190
191
 
192
+ /**
193
+ * Two columns opened at a thread (Katerina, 17 November): a link to it, or a line in a list that names it, opens the
194
+ * conversation on that comment, in the middle and marked a moment, not at the newest, so the reader sees what they
195
+ * asked for. A thread opened from outside while it is open (the buttons above stand for those lines) lands on its
196
+ * comment too; a press on a comment opens its thread where it is, and nothing moves.
197
+ */
198
+ export const TwoColumnsOpenedAtThread: Story = {
199
+ name: 'Two columns, opened at a thread',
200
+ render: function Render() {
201
+ const [open, setOpen] = useState<string | undefined>('t2')
202
+ const said = Array.from({ length: 14 }, (_, i) => ({ id: `t${i}`, who: [ONE, TWO, THREE][i % 3], words: i % 4 === 0 ? WORDS : `Comment ${i + 1} of a long conversation.` }))
203
+ const items: ConversationItem[] = said.map((c, i) => ({
204
+ id: c.id,
205
+ day: i < 7 ? 'Monday' : 'Today',
206
+ card: (
207
+ <ConversationCard author={c.who} time={`${8 + (i % 4)}:${i % 2 ? '30' : '05'} AM`}>
208
+ {c.words}
209
+ </ConversationCard>
210
+ ),
211
+ thread: <Thread start={{ author: c.who, time: '9:05 AM', words: c.words }} onClose={() => setOpen(undefined)} box={<WriteBox />} />,
212
+ }))
213
+ return (
214
+ <ConversationLayout
215
+ threads="beside"
216
+ items={items}
217
+ open={open}
218
+ onOpenChange={setOpen}
219
+ header={
220
+ <Toolbar aria-label="Open a thread from outside">
221
+ <ToolbarButton tooltip="Open comment 3's thread, as a line naming it does" aria-label="Open comment 3's thread" onClick={() => setOpen('t2')}>
222
+ 3
223
+ </ToolbarButton>
224
+ <ToolbarButton tooltip="Open comment 12's thread, as a line naming it does" aria-label="Open comment 12's thread" onClick={() => setOpen('t11')}>
225
+ 12
226
+ </ToolbarButton>
227
+ </Toolbar>
228
+ }
229
+ box={<WriteBox label="Comment" />}
230
+ />
231
+ )
232
+ },
233
+ }
234
+
191
235
  /**
192
236
  * Two columns, read by being seen: each comment new to the reader keeps its dot until it has been on screen a moment
193
237
  * (`useSeenOnScreen`, handed to `seen`). Scroll, and the ones that show lose it after 1.5 seconds.
@@ -4,12 +4,13 @@ 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
+ import { anchorIn, cardIn, isNearBottom, landOn, places, sendsInLayout, useSteadyScroll } from './conversationScroll'
8
8
  import { Divider } from './Divider'
9
9
  import { EmptyState } from './EmptyState'
10
10
  import { ErrorBoundary } from './ErrorBoundary'
11
11
  import { Panel } from './Panel'
12
12
  import { ScrollArea } from './ScrollArea'
13
+ import { markShown } from './showInConversation'
13
14
  import { useWatchSeen, type SeenOnScreen } from './seenOnScreen'
14
15
  import { SkeletonConversation } from './Skeleton'
15
16
  import { caretOnOpen, InConversationItem, InThreadCard, LineByLayout, SHOWN_CLASSES, useFaceLine, type ConversationItemState } from './threadCard'
@@ -278,6 +279,9 @@ export function ConversationLayout({
278
279
  // A comment is read by being seen (Peek's way, Katerina, 30 October): each one in the list is watched.
279
280
  useWatchSeen(seen, body, 'data-conversation-item')
280
281
  const pressed = useRef<{ id: string; top: number } | null>(null)
282
+ // The thread was opened by a press on its comment, which is in view: it stays where it is. Any other opening came from
283
+ // outside (a link, a line naming it) and lands on it.
284
+ const byPress = useRef(false)
281
285
  const itemAt = (id: string) => body.current?.querySelector<HTMLElement>(`[data-conversation-item="${CSS.escape(id)}"]`) ?? null
282
286
  // A thread that opens puts the caret in its box (Katerina, 31 October); the one open when the page is drawn does not.
283
287
  const [caret, setCaret] = useState(0)
@@ -290,6 +294,7 @@ export function ConversationLayout({
290
294
  }
291
295
  const item = threads === 'under' ? itemAt(id) : null
292
296
  pressed.current = item ? { id, top: item.getBoundingClientRect().top } : null
297
+ byPress.current = true
293
298
  onOpenChange(next)
294
299
  }
295
300
  : undefined
@@ -338,7 +343,19 @@ export function ConversationLayout({
338
343
  const el = body.current
339
344
  if (!el) return
340
345
  const left = rememberAs ? places.get(rememberAs) : undefined
341
- if (left && !left.atBottom) {
346
+ /*
347
+ Opened at a thread — a link to it, a line in a list that names it — it lands on that comment, in the middle and
348
+ marked a moment, not at the newest, so the reader sees what they asked for (Katerina, 17 November: "if the
349
+ conversation is not visible, I don't see anything selected … generalize it so that it works in every similar
350
+ case"). A comment not drawn (older than what is read) leaves it to land as before.
351
+ */
352
+ const opened = open !== undefined ? itemAt(open) : null
353
+ if (opened) {
354
+ landOn(el, opened)
355
+ markShown(opened)
356
+ nearBottom.current = isNearBottom(el)
357
+ if (rememberAs) places.set(rememberAs, { atBottom: nearBottom.current, offset: el.scrollTop, anchor: anchorIn(el), leftAt: Date.now() })
358
+ } else if (left && !left.atBottom) {
342
359
  // That comment back at the same height, not the same offset: what is above it can change height while the
343
360
  // reader is away (a "new reply" mark cleared once read, a reactions line).
344
361
  el.scrollTop = left.offset
@@ -351,7 +368,21 @@ export function ConversationLayout({
351
368
  if (rememberAs) places.set(rememberAs, { atBottom: true, offset: el.scrollTop, leftAt: Date.now() })
352
369
  }
353
370
  placedFor.current = placeKey
371
+ // `open` is read as it is when it places; once placed, a change is the landing below.
354
372
  }, [beside, placeKey, rememberAs, loading])
373
+ // A thread opened from outside once it is placed (a line naming it, while the conversation is already open): two
374
+ // columns land on its comment too. A press on a comment leaves it where it is: it is in view.
375
+ useLayoutEffect(() => {
376
+ const pressedIt = byPress.current
377
+ byPress.current = false
378
+ if (!beside || pressedIt || open === undefined || placedFor.current !== placeKey) return
379
+ const el = body.current
380
+ const item = itemAt(open)
381
+ if (!el || !item) return
382
+ landOn(el, item)
383
+ markShown(item)
384
+ nearBottom.current = isNearBottom(el)
385
+ }, [open])
355
386
  // From there, it stays where the reader is while its cards, chips and pictures fill in (Peek's OPT-10).
356
387
  const placed = useCallback(() => placedFor.current === placeKey, [placeKey])
357
388
  useSteadyScroll(body, nearBottom, placed, loading, beside)
@@ -86,6 +86,7 @@ It does these by itself. Write none of them around it.
86
86
  |---|---|---|
87
87
  | Draws the column: 290px, a line on its right, and a ContainerHeader on top | a width, a border and a header row of your own | |
88
88
  | Scrolls its rows in a ScrollArea, 16px under the header, 12px in from each side | `overflow-auto`, or padding of your own around the rows | |
89
+ | Brings the open page's row (a **NavItem** that is `active`) into sight once it is drawn, however late, once for each new open page, and never pulls it back after the reader scrolls away | an effect that finds the active row and scrolls it into view | |
89
90
  | Closes with the rail when `collapsed`: narrows to nothing and fades | a width transition of your own | |
90
91
  | Keeps its 290px beside a main area that grows | `shrink-0` | |
91
92
  | Keeps a crash inside itself: its title stays, the message and Try again sit in the middle of the room the list had | an error boundary of your own around it | |
@@ -1,6 +1,6 @@
1
1
  import type { Meta, StoryObj } from '@storybook/react-vite'
2
2
  import { IconSortDescending, IconSquareRounded } from '@tabler/icons-react'
3
- import { useState } from 'react'
3
+ import { useEffect, useState } from 'react'
4
4
  import { Button } from './Button'
5
5
  import { CollapsibleSection } from './CollapsibleSection'
6
6
  import { Divider } from './Divider'
@@ -117,6 +117,58 @@ export const ManyRows: Story = {
117
117
  render: (args) => <ListColumn {...args}>{rows(80)}</ListColumn>,
118
118
  }
119
119
 
120
+ /** 80 rows, the open one at `open`: a click on a row opens it instead. */
121
+ function OpenRows({ open: first, late = false }: { open: number; late?: boolean }) {
122
+ const [open, setOpen] = useState(first)
123
+ const [drawn, setDrawn] = useState(!late)
124
+ useEffect(() => {
125
+ if (!late) return
126
+ const timer = setTimeout(() => setDrawn(true), 1200)
127
+ return () => clearTimeout(timer)
128
+ }, [late])
129
+ if (!drawn) return <SkeletonList rows={8} />
130
+ return (
131
+ <>
132
+ {Array.from({ length: 80 }, (_, i) => (
133
+ <NavItem
134
+ key={i}
135
+ href="#"
136
+ label={`Item ${i + 1}`}
137
+ icon={icon}
138
+ active={i === open}
139
+ onClick={(event) => {
140
+ event.preventDefault()
141
+ setOpen(i)
142
+ }}
143
+ />
144
+ ))}
145
+ </>
146
+ )
147
+ }
148
+
149
+ /**
150
+ * Arriving on a page whose row is far down the list (a link, a card, another app): the column shows where it lives,
151
+ * bringing Item 62 into sight. Scroll away and it stays where you put it; open another row and that one is in sight.
152
+ */
153
+ export const OpenRowFarDown: Story = {
154
+ args: { title: 'Items' },
155
+ render: (args) => (
156
+ <ListColumn {...args}>
157
+ <OpenRows open={61} />
158
+ </ListColumn>
159
+ ),
160
+ }
161
+
162
+ /** The same, its rows read a moment after the column is drawn, as a list whose read is still out: Item 62 is brought into sight once it is drawn. */
163
+ export const OpenRowDrawnLate: Story = {
164
+ args: { title: 'Items' },
165
+ render: (args) => (
166
+ <ListColumn {...args}>
167
+ <OpenRows open={61} late />
168
+ </ListColumn>
169
+ ),
170
+ }
171
+
120
172
  /** While the list is on its way: a skeleton shaped like the rows. */
121
173
  export const Loading: Story = {
122
174
  args: { title: 'Items' },
@@ -1,5 +1,6 @@
1
- import type { ReactNode } from 'react'
1
+ import { useRef, type ReactNode } from 'react'
2
2
  import { cn } from './cn'
3
+ import { useRevealCurrentRow } from './revealCurrentRow'
3
4
  import { ContainerHeader } from './ContainerHeader'
4
5
  import { ErrorBoundary } from './ErrorBoundary'
5
6
  import { FOLDED_CLASSES, FOLD_MOTION_CLASSES, UNFOLDED_CLASSES } from './looks'
@@ -21,6 +22,11 @@ import { ScrollArea } from './ScrollArea'
21
22
  * eight mistakes on the page that led to UIG-15: the frame's card clips, so a
22
23
  * list that grew past the fold was simply cut off, with nothing to scroll.
23
24
  *
25
+ * It shows where the open page lives: its row (a `NavItem` that is `active`)
26
+ * is brought into sight once it is drawn, however late, once for each new open
27
+ * page, and never pulled back after the reader scrolls away (Katerina, 17
28
+ * November: the selected row "could be somewhere above or below the fold").
29
+ *
24
30
  * It keeps a crash inside itself (D1, D3): if its rows, its actions or the row
25
31
  * above break, the column keeps its title and shows `ErrorBoundary`'s message
26
32
  * in the middle of the room the list had, and the rest of the page keeps working.
@@ -50,6 +56,8 @@ export interface ListColumnProps {
50
56
  }
51
57
 
52
58
  function Column({ title, chevron = false, titleMenu, actions, above, collapsed = false, children, className, broken = false }: ListColumnProps & { broken?: boolean }) {
59
+ const rows = useRef<HTMLDivElement>(null)
60
+ useRevealCurrentRow(rows)
53
61
  return (
54
62
  <div
55
63
  className={cn(
@@ -69,7 +77,7 @@ function Column({ title, chevron = false, titleMenu, actions, above, collapsed =
69
77
  // The message takes the room the list had and centres itself in it (Katerina, 19 September).
70
78
  <div className="flex min-h-0 flex-1 flex-col px-3">{children}</div>
71
79
  ) : (
72
- <ScrollArea className="flex-1" contentClassName="flex flex-col gap-0.5 px-3 pt-4 pb-3">
80
+ <ScrollArea className="flex-1" viewportRef={rows} contentClassName="flex flex-col gap-0.5 px-3 pt-4 pb-3">
73
81
  {children}
74
82
  </ScrollArea>
75
83
  )}
package/src/NavTree.mdx CHANGED
@@ -164,7 +164,7 @@ It does these by itself. Write none of them around it.
164
164
  | It does | So you never write | Refused when written by hand |
165
165
  |---|---|---|
166
166
  | Draws every level from one list, rows under rows | a recursive render of **NavItem**s and **CollapsibleSection**s | |
167
- | Opens the group and the rows above the current row, once per row, and scrolls to it | a search through the list for the current row, an effect that opens it, a scroll into view | |
167
+ | Opens the group and the rows above the current row, once per row, and scrolls to it, however late it is drawn — by a fold that reads its rows once it opens, too | a search through the list for the current row, an effect that opens it, a scroll into view | |
168
168
  | Opens the group a link led to, once per arrival, and scrolls to it | an effect that opens it, a `querySelector` and a scroll into view | |
169
169
  | Says it is loading, or empty, in the rows' place | a skeleton or an **EmptyState** placed by hand | |
170
170
  | Says when the pointer rests on a group, 150ms, and not while it sweeps past | a timer on pointer enter and leave | |
@@ -1,6 +1,6 @@
1
1
  import type { Meta, StoryObj } from '@storybook/react-vite'
2
2
  import { IconSquareRounded } from '@tabler/icons-react'
3
- import { useState, type ReactNode } from 'react'
3
+ import { useEffect, useState, type ReactNode } from 'react'
4
4
  import { IconArrowUpRight, IconFolder, IconPlus } from '@tabler/icons-react'
5
5
  import { Button } from './Button'
6
6
  import { Chip } from './Chip'
@@ -286,6 +286,66 @@ export const OpensOntoTheCurrentRow: Story = {
286
286
  },
287
287
  }
288
288
 
289
+ /** A fold that reads its own rows once it opens, a moment later (a team's Files in Peek): its rows are drawn by it, not by the tree. */
290
+ function FilesFold({ selected, onOpen }: { selected?: string; onOpen: (id: string) => void }) {
291
+ const [open, setOpen] = useState(false)
292
+ const [rows, setRows] = useState<string[] | null>(null)
293
+ useEffect(() => {
294
+ if (!open || rows) return
295
+ const timer = setTimeout(() => setRows(Array.from({ length: 12 }, (_, i) => `f${i + 1}`)), 1000)
296
+ return () => clearTimeout(timer)
297
+ }, [open, rows])
298
+ const holds = selected?.startsWith('f') === true
299
+ return (
300
+ <NavTreeSection title="Files" icon={folder} open={open} onOpenChange={setOpen} loading={open && !rows} {...(holds && selected ? { openFor: selected } : {})}>
301
+ {rows?.map((id) => (
302
+ <NavItem
303
+ key={id}
304
+ href="#"
305
+ label={`Project ${id.slice(1)}`}
306
+ icon={placeholder}
307
+ active={id === selected}
308
+ onClick={(event) => {
309
+ event.preventDefault()
310
+ onOpen(id)
311
+ }}
312
+ />
313
+ ))}
314
+ </NavTreeSection>
315
+ )
316
+ }
317
+
318
+ /**
319
+ * The current row is in a fold at the bottom that reads its rows only once it opens. Open Project 9 from the page: the
320
+ * fold opens, reads for a second, and the column scrolls to the row once the fold has drawn it (Katerina, 17 November:
321
+ * it stayed below the fold). Scroll away: it stays where you put it.
322
+ */
323
+ export const CurrentRowDrawnLateByAFold: Story = {
324
+ render: function Render(args) {
325
+ const [selected, setSelected] = useState<string | undefined>(undefined)
326
+ return (
327
+ <div className="flex h-screen bg-bg-base">
328
+ <Sidebar>
329
+ <NavTree title={args.title} selected={selected}>
330
+ {Array.from({ length: 6 }, (_, g) => (
331
+ <NavTreeSection key={g} title={`Group ${g + 1}`} icon={folder} defaultOpen>
332
+ {Array.from({ length: 5 }, (_, i) => (
333
+ <NavItem key={i} href="#" label={`Item ${g * 5 + i + 1}`} icon={placeholder} />
334
+ ))}
335
+ </NavTreeSection>
336
+ ))}
337
+ <FilesFold selected={selected} onOpen={setSelected} />
338
+ </NavTree>
339
+ </Sidebar>
340
+ <Page>
341
+ <Button variant="outlined" size="small" onClick={() => setSelected('f9')}>Open Project 9, in Files</Button>
342
+ <Button variant="outlined" size="small" onClick={() => setSelected(undefined)}>Close it</Button>
343
+ </Page>
344
+ </div>
345
+ )
346
+ },
347
+ }
348
+
289
349
  /** A link to a group — a folder's own: it opens, closed by hand too, and the column scrolls to it at once. Close it: it stays closed until a link leads to it again. Nothing is marked. */
290
350
  export const OpensOntoAGroup: Story = {
291
351
  args: { groups: SHUT_GROUPS, selected: undefined },
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.