@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.
@@ -0,0 +1,41 @@
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
+ /** For tests: every list forgets where it was. */
24
+ export declare function forgetListPlaces(): void;
25
+ /** How long a list drawn again keeps trying to reach where it was left, while its rows are still being drawn. */
26
+ export declare const RESTORE_MS = 2000;
27
+ /** A named list's place, for the reveal inside it: its name, and whether it is still going back to where it was. */
28
+ export interface ListPlace {
29
+ name?: string;
30
+ restoring: RefObject<boolean>;
31
+ }
32
+ /** The list a row is revealed in: a `ListColumn` gives its name to the tree inside it, which reveals nothing itself. */
33
+ export declare const ListPlaceContext: import("react").Context<ListPlace | null>;
34
+ /**
35
+ * Goes back to where the named list was left, and keeps note of where the reader leaves it. Its rows may still be
36
+ * drawing (a skeleton, a fold that reads its own rows): it tries again as the list grows, until it is there, the reader
37
+ * scrolls, something else moves it (a row brought into sight), or `RESTORE_MS` has passed.
38
+ */
39
+ export declare function useListPlace(box: RefObject<HTMLElement | null>, name: string | undefined): ListPlace;
40
+ export declare function useRevealCurrentRow(box: RefObject<HTMLElement | null>, current?: string, place?: ListPlace): void;
41
+ //# sourceMappingURL=revealCurrentRow.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"revealCurrentRow.d.ts","sourceRoot":"","sources":["../src/revealCurrentRow.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0E,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAE9G;;;;;;;;;;;GAWG;AAEH,qGAAqG;AACrG,eAAO,MAAM,SAAS,MAAM,CAAA;AAE5B;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,WAAW,QAK3C;AAyBD,kDAAkD;AAClD,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAED,iHAAiH;AACjH,eAAO,MAAM,UAAU,OAAO,CAAA;AAE9B,oHAAoH;AACpH,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,SAAS,CAAC,OAAO,CAAC,CAAA;CAC9B;AAED,wHAAwH;AACxH,eAAO,MAAM,gBAAgB,2CAAwC,CAAA;AAErE;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAwDpG;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI,CA0CjH"}
@@ -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.120.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.120.0",
8
8
  "exports": 256,
9
9
  "typeExports": 270,
10
10
  "files": null
@@ -6709,6 +6709,12 @@
6709
6709
  "required": true,
6710
6710
  "note": "The rows, 2px apart. Groups are headed by a `CollapsibleSection` or a `SectionHeader`."
6711
6711
  },
6712
+ {
6713
+ "name": "rememberAs",
6714
+ "takes": "text",
6715
+ "required": false,
6716
+ "note": "The list's name in the app (`teams`, `dms`): where it was scrolled is remembered by it in this tab, and the same column drawn again (on another page) goes back there, its open row still brought into sight when it is a new one."
6717
+ },
6712
6718
  {
6713
6719
  "name": "className",
6714
6720
  "takes": "text",
@@ -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)
@@ -65,6 +65,11 @@ import { ListColumn, Toolbar, ToolbarButton } from '@estiva-app/ui'
65
65
  side.
66
66
  - The rows are yours. It scrolls them, so a list that grows with its data is
67
67
  never cut off at the fold, even when today's data fits.
68
+ - Give the column its name in the app, `rememberAs` (`teams`, `dms`): where it
69
+ was scrolled is remembered by it in this tab, and the same column drawn again
70
+ on another page opens where the reader left it, not at the top. An open row it
71
+ already brought into sight is not brought back; a new one is. Without a name,
72
+ it opens at the top each time it is drawn.
68
73
  - **Planned:** dragging its edge to resize it, with `SplitLayout` in
69
74
  `@estiva-app/ui/layout` (migration stage 8). The 380px column beside a
70
75
  conversation gets the same treatment then.
@@ -86,6 +91,7 @@ It does these by itself. Write none of them around it.
86
91
  |---|---|---|
87
92
  | 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
93
  | 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 | |
94
+ | 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
95
  | Closes with the rail when `collapsed`: narrows to nothing and fades | a width transition of your own | |
90
96
  | Keeps its 290px beside a main area that grows | `shrink-0` | |
91
97
  | 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,83 @@ 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
+ // Each its own address, as an app's rows are: a list knows its open row by it.
136
+ href={`#item-${i + 1}`}
137
+ label={`Item ${i + 1}`}
138
+ icon={icon}
139
+ active={i === open}
140
+ onClick={(event) => {
141
+ event.preventDefault()
142
+ setOpen(i)
143
+ }}
144
+ />
145
+ ))}
146
+ </>
147
+ )
148
+ }
149
+
150
+ /**
151
+ * Arriving on a page whose row is far down the list (a link, a card, another app): the column shows where it lives,
152
+ * bringing Item 62 into sight. Scroll away and it stays where you put it; open another row and that one is in sight.
153
+ */
154
+ export const OpenRowFarDown: Story = {
155
+ args: { title: 'Items' },
156
+ render: (args) => (
157
+ <ListColumn {...args}>
158
+ <OpenRows open={61} />
159
+ </ListColumn>
160
+ ),
161
+ }
162
+
163
+ /** 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. */
164
+ export const OpenRowDrawnLate: Story = {
165
+ args: { title: 'Items' },
166
+ render: (args) => (
167
+ <ListColumn {...args}>
168
+ <OpenRows open={61} late />
169
+ </ListColumn>
170
+ ),
171
+ }
172
+
173
+ /**
174
+ * Drawn again where it was left (`rememberAs`): scroll down, then "Another page" draws the column anew, as an app does
175
+ * when it moves to another page that shows the same column. It opens where you left it, not at the top, and its open
176
+ * row, already brought into sight once, is not brought back.
177
+ */
178
+ export const DrawnAgainWhereItWasLeft: Story = {
179
+ args: { title: 'Items' },
180
+ render: function Render(args) {
181
+ const [page, setPage] = useState(0)
182
+ return (
183
+ <div className="flex h-full">
184
+ <ListColumn key={page} {...args} rememberAs="story-items">
185
+ <OpenRows open={5} />
186
+ </ListColumn>
187
+ <div className="p-4">
188
+ <Button size="small" onClick={() => setPage((n) => n + 1)}>
189
+ Another page
190
+ </Button>
191
+ </div>
192
+ </div>
193
+ )
194
+ },
195
+ }
196
+
120
197
  /** While the list is on its way: a skeleton shaped like the rows. */
121
198
  export const Loading: Story = {
122
199
  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 { ListPlaceContext, useListPlace, 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.
@@ -45,11 +51,20 @@ export interface ListColumnProps {
45
51
  collapsed?: boolean
46
52
  /** The rows, 2px apart. Groups are headed by a `CollapsibleSection` or a `SectionHeader`. */
47
53
  children: ReactNode
54
+ /**
55
+ * The list's name in the app (`teams`, `dms`): where it was scrolled is remembered by it in this tab, and the same
56
+ * column drawn again (on another page) goes back there, its open row still brought into sight when it is a new one.
57
+ * Without it, it opens at the top each time it is drawn.
58
+ */
59
+ rememberAs?: string
48
60
  /** Placement only. */
49
61
  className?: string
50
62
  }
51
63
 
52
- function Column({ title, chevron = false, titleMenu, actions, above, collapsed = false, children, className, broken = false }: ListColumnProps & { broken?: boolean }) {
64
+ function Column({ title, chevron = false, titleMenu, actions, above, collapsed = false, children, rememberAs, className, broken = false }: ListColumnProps & { broken?: boolean }) {
65
+ const rows = useRef<HTMLDivElement>(null)
66
+ const place = useListPlace(rows, broken ? undefined : rememberAs)
67
+ useRevealCurrentRow(rows, undefined, place)
53
68
  return (
54
69
  <div
55
70
  className={cn(
@@ -69,8 +84,9 @@ function Column({ title, chevron = false, titleMenu, actions, above, collapsed =
69
84
  // The message takes the room the list had and centres itself in it (Katerina, 19 September).
70
85
  <div className="flex min-h-0 flex-1 flex-col px-3">{children}</div>
71
86
  ) : (
72
- <ScrollArea className="flex-1" contentClassName="flex flex-col gap-0.5 px-3 pt-4 pb-3">
73
- {children}
87
+ <ScrollArea className="flex-1" viewportRef={rows} contentClassName="flex flex-col gap-0.5 px-3 pt-4 pb-3">
88
+ {/* A tree in it leaves bringing its open row into sight to the column, which knows where it was left. */}
89
+ <ListPlaceContext.Provider value={place}>{children}</ListPlaceContext.Provider>
74
90
  </ScrollArea>
75
91
  )}
76
92
  </div>
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 },