@estiva-app/ui 0.93.0 → 0.94.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@estiva-app/ui",
3
- "version": "0.93.0",
3
+ "version": "0.94.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.93.0",
7
+ "packageVersion": "0.94.0",
8
8
  "exports": 210,
9
9
  "typeExports": 213,
10
10
  "files": null
@@ -1555,6 +1555,12 @@
1555
1555
  "required": false,
1556
1556
  "note": "Remember open or closed in this browser, under this key."
1557
1557
  },
1558
+ {
1559
+ "name": "openFor",
1560
+ "takes": "text",
1561
+ "required": false,
1562
+ "note": "The current item, when it sits in here: the section opens each time this names a new one, as a click would — remembered under `storageKey`, told to `onOpenChange`."
1563
+ },
1558
1564
  {
1559
1565
  "name": "icon",
1560
1566
  "takes": "anything",
@@ -5942,6 +5948,12 @@
5942
5948
  "required": false,
5943
5949
  "note": null
5944
5950
  },
5951
+ {
5952
+ "name": "openFor",
5953
+ "takes": "text",
5954
+ "required": false,
5955
+ "note": "With `children`: the current item, when it sits under this row."
5956
+ },
5945
5957
  {
5946
5958
  "name": "className",
5947
5959
  "takes": "text",
@@ -6008,7 +6020,13 @@
6008
6020
  "name": "selected",
6009
6021
  "takes": "text",
6010
6022
  "required": false,
6011
- "note": "The row that is current: `active`, and its group starts open."
6023
+ "note": "The row that is current: `active`. Each time it names a new row, its group and every row above it open, closing nothing — a group closed by hand too — and the column scrolls to it once they have slid open."
6024
+ },
6025
+ {
6026
+ "name": "selectedParent",
6027
+ "takes": "text",
6028
+ "required": false,
6029
+ "note": "The row the current one sits under, while the tree does not draw the current one: its rows are not read yet, or it is not a row here."
6012
6030
  },
6013
6031
  {
6014
6032
  "name": "onSelect",
@@ -6132,6 +6150,12 @@
6132
6150
  "required": false,
6133
6151
  "note": "Remember it open or closed in this browser, under this key."
6134
6152
  },
6153
+ {
6154
+ "name": "openFor",
6155
+ "takes": "text",
6156
+ "required": false,
6157
+ "note": "The current item, when it sits in this group: the group opens each time this names a new one — `CollapsibleSection`'s."
6158
+ },
6135
6159
  {
6136
6160
  "name": "children",
6137
6161
  "takes": "anything",
@@ -1,4 +1,4 @@
1
- import { useState, type ReactNode } from 'react'
1
+ import { useEffect, useRef, useState, type ReactNode } from 'react'
2
2
  import { Collapsible } from '@base-ui/react/collapsible'
3
3
  import { cn } from './cn'
4
4
  import { SectionHeader, type SectionAction } from './SectionHeader'
@@ -21,7 +21,10 @@ import { COLLAPSIBLE_PANEL_CLASSES } from './looks'
21
21
  * - `open` + `onOpenChange`: the caller owns it.
22
22
  *
23
23
  * A closed section stays closed whatever is selected inside it (her
24
- * ruling, 2026-09-09) — the reader closed it.
24
+ * ruling, 2026-09-09) — the reader closed it — until `openFor` names a new
25
+ * current item inside it: opening a file shows where it lives, even in a
26
+ * section closed by hand (Katerina, 30 October). Once per item, so closed
27
+ * again it stays closed until another opens.
25
28
  */
26
29
  export interface CollapsibleSectionProps {
27
30
  title: string
@@ -41,6 +44,13 @@ export interface CollapsibleSectionProps {
41
44
  pending?: boolean
42
45
  /** Remember open or closed in this browser, under this key. The app prefixes it. */
43
46
  storageKey?: string
47
+ /**
48
+ * The current item, when it sits in here: the section opens each time this
49
+ * names a new one, as a click would — remembered under `storageKey`, told to
50
+ * `onOpenChange`. Closed again by hand, it stays closed until another item
51
+ * opens. `NavTree` passes it.
52
+ */
53
+ openFor?: string
44
54
  /** 16px, before the title; the arrow takes its place on hover — `SectionHeader`'s. */
45
55
  icon?: ReactNode
46
56
  /** Beside the title and always visible, before the actions — a count. `SectionHeader`'s. */
@@ -75,6 +85,22 @@ export interface CollapsibleSectionProps {
75
85
  const OPEN = 'open'
76
86
  const CLOSED = 'closed'
77
87
 
88
+ /**
89
+ * `openFor`, for a section and a row with rows under it: open, as a click
90
+ * would, each time it names a new item. An effect, not a render: opening tells
91
+ * the caller (`onOpenChange`), and a parent is never set while a child draws.
92
+ * Gone and back — the item opened, another elsewhere, then it again — is new.
93
+ */
94
+ export function useOpenFor(openFor: string | undefined, open: boolean, setOpen: (open: boolean) => void) {
95
+ const seen = useRef<string | undefined>(undefined)
96
+ useEffect(() => {
97
+ if (openFor === seen.current) return
98
+ seen.current = openFor
99
+ if (openFor !== undefined && !open) setOpen(true)
100
+ // Only a new item opens it: the reader's own toggles in between are theirs.
101
+ }, [openFor])
102
+ }
103
+
78
104
  function readStored(key: string | undefined): boolean | undefined {
79
105
  if (!key) return undefined
80
106
  try {
@@ -94,7 +120,7 @@ function writeStored(key: string | undefined, open: boolean) {
94
120
  }
95
121
  }
96
122
 
97
- export function CollapsibleSection({ title, defaultOpen = true, open: openProp, onOpenChange, pending = false, storageKey, icon, trailing, actions, menu, menuLabel, showActions, look = 'heading', indent = false, children, className, contentClassName }: CollapsibleSectionProps) {
123
+ export function CollapsibleSection({ title, defaultOpen = true, open: openProp, onOpenChange, pending = false, storageKey, openFor, icon, trailing, actions, menu, menuLabel, showActions, look = 'heading', indent = false, children, className, contentClassName }: CollapsibleSectionProps) {
98
124
  const [openState, setOpenState] = useState(() => readStored(storageKey) ?? defaultOpen)
99
125
  const open = openProp ?? openState
100
126
  const setOpen = (next: boolean) => {
@@ -102,6 +128,7 @@ export function CollapsibleSection({ title, defaultOpen = true, open: openProp,
102
128
  writeStored(storageKey, next)
103
129
  onOpenChange?.(next)
104
130
  }
131
+ useOpenFor(openFor, open, setOpen)
105
132
  // Pending, Base UI holds the panel shut and so would open it on a click: the click is the title's, and the title says open.
106
133
  // Only a click: find-in-page reaching into the shut panel asks to open it, and it is open.
107
134
  const shown = open && !pending
package/src/NavItem.tsx CHANGED
@@ -3,6 +3,7 @@ import { Collapsible } from '@base-ui/react/collapsible'
3
3
  import { IconAlertSquareRounded, IconChevronRight, IconDotsVertical } from '@tabler/icons-react'
4
4
  import { useInAppClick } from './AppProvider'
5
5
  import { cn } from './cn'
6
+ import { useOpenFor } from './CollapsibleSection'
6
7
  import { COLLAPSIBLE_PANEL_CLASSES, COUNT_TEXT_CLASSES, SIDEBAR_ROW_CLASSES, SIDEBAR_ROW_TEXT_CLASSES } from './looks'
7
8
  import { IconButton } from './IconButton'
8
9
  import { Menu } from './Menu'
@@ -85,6 +86,12 @@ export interface NavItemProps extends Omit<ComponentPropsWithoutRef<'a'>, 'href'
85
86
  /** With `children`: the caller owns the state. */
86
87
  open?: boolean
87
88
  onOpenChange?: (open: boolean) => void
89
+ /**
90
+ * With `children`: the current item, when it sits under this row. The row
91
+ * opens each time this names a new one, as a click would; closed again by
92
+ * hand, it stays closed until another opens. `NavTree` passes it.
93
+ */
94
+ openFor?: string
88
95
  className?: string
89
96
  }
90
97
 
@@ -106,6 +113,7 @@ export function NavItem({
106
113
  defaultOpen = true,
107
114
  open: openProp,
108
115
  onOpenChange,
116
+ openFor,
109
117
  className,
110
118
  onClick,
111
119
  ...props
@@ -119,6 +127,7 @@ export function NavItem({
119
127
  setOpenState(next)
120
128
  onOpenChange?.(next)
121
129
  }
130
+ useOpenFor(hasRows ? openFor : undefined, open, setOpen)
122
131
  // The row draws beside it — the ⋮, the arrow — so the pointer can leave the
123
132
  // link for them while the row still reads as the one it is on.
124
133
  const buttons = (menu != null ? 1 : 0) + (action ? 1 : 0)
package/src/NavTree.mdx CHANGED
@@ -20,6 +20,30 @@ rows to any depth.
20
20
 
21
21
  <Canvas of={NavTreeStories.CurrentDeep} />
22
22
 
23
+ - Each time `selected` names a new row, the row shows where it lives: its
24
+ group and every row above it open — a group closed by hand too — and the
25
+ column scrolls to it. Once per row: closed again, they stay closed until
26
+ another row opens. Nothing is closed for it.
27
+
28
+ <Canvas of={NavTreeStories.OpensOntoTheCurrentRow} />
29
+
30
+ - In a new tab, where nothing is open yet, the same: the row is in sight
31
+ when the tree is drawn.
32
+
33
+ <Canvas of={NavTreeStories.InANewTab} />
34
+
35
+ - `selectedParent` is the row the current one sits under, while the tree
36
+ does not draw the current one. Its rows are read only when it opens: the
37
+ tree opens onto it and opens it, and marks the current row once it is in.
38
+
39
+ <Canvas of={NavTreeStories.UnderARowNotReadYet} />
40
+
41
+ - The current item is not a row here at all — a sidebar listing places, not
42
+ everything in them: the place it is listed in stays marked, and
43
+ `selectedParent` opens the group holding the row it is under, unmarked.
44
+
45
+ <Canvas of={NavTreeStories.NotARowHere} />
46
+
23
47
  - A row's `hint` (a neutral **Chip**), `count` and `menu` are **NavItem**'s,
24
48
  passed through.
25
49
  - `groups={null}` while the first read is on its way draws a skeleton;
@@ -99,7 +123,12 @@ import { NavTree, Sidebar } from '@estiva-app/ui'
99
123
  does: through **AppProvider**'s `navigate`, or `onSelect` preventing the
100
124
  default and navigating.
101
125
  - `storageKey` remembers each group open or closed in this browser, under
102
- the key and the group's id. The rows under a row are not remembered yet.
126
+ the key and the group's id — a group opened for the current row is
127
+ remembered open, as a click would be. The rows under a row are not
128
+ remembered yet.
129
+ - Groups the app draws itself open for the current row through `openFor` on
130
+ each **NavTreeSection** and **NavItem** that holds it; the scroll is the
131
+ tree's either way, given `selected`.
103
132
  - The words in `emptyMessage` are the caller's.
104
133
 
105
134
  ## What it owns
@@ -109,7 +138,7 @@ It does these by itself. Write none of them around it.
109
138
  | It does | So you never write | Refused when written by hand |
110
139
  |---|---|---|
111
140
  | Draws every level from one list, rows under rows | a recursive render of **NavItem**s and **CollapsibleSection**s | |
112
- | Opens the group that holds the current row | a search through the list for the current row | |
141
+ | 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 | |
113
142
  | Says it is loading, or empty, in the rows' place | a skeleton or an **EmptyState** placed by hand | |
114
143
  | Says when the pointer rests on a group, 150ms, and not while it sweeps past | a timer on pointer enter and leave | |
115
144
 
@@ -1,12 +1,13 @@
1
1
  import type { Meta, StoryObj } from '@storybook/react-vite'
2
2
  import { IconSquareRounded } from '@tabler/icons-react'
3
- import { useState } from 'react'
3
+ import { useState, type ReactNode } from 'react'
4
4
  import { IconArrowUpRight, IconFolder, IconPlus } from '@tabler/icons-react'
5
+ import { Button } from './Button'
5
6
  import { Chip } from './Chip'
6
7
  import { UnreadDot } from './UnreadDot'
7
8
  import { MenuItem, MenuSeparator } from './Menu'
8
9
  import { NavItem } from './NavItem'
9
- import { NavTree, NavTreeSection, type NavTreeGroup } from './NavTree'
10
+ import { NavTree, NavTreeSection, type NavTreeGroup, type NavTreeNode } from './NavTree'
10
11
  import { Sidebar } from './Sidebar'
11
12
 
12
13
  const placeholder = <IconSquareRounded size={16} stroke={1.5} />
@@ -185,3 +186,140 @@ export const AppDrawnGroups: Story = {
185
186
  )
186
187
  },
187
188
  }
189
+
190
+ /*
191
+ Opening a row shows where it lives (Katerina, 30 October): its group and the
192
+ rows above it open, the row is marked, and the column scrolls to it.
193
+ */
194
+ function item(n: number, children?: NavTreeNode[]): NavTreeNode {
195
+ return { id: `i${n}`, label: `Item ${n}`, href: '#', icon: placeholder, ...(children ? { children, defaultOpen: false } : {}) }
196
+ }
197
+
198
+ const WORDS = ['one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight']
199
+
200
+ /** Eight shut groups, enough for the column to scroll; in the last, Item 31 is two levels in, under Item 29 and Item 30. */
201
+ const SHUT_GROUPS: NavTreeGroup[] = WORDS.map((word, g) => ({
202
+ id: `s${g + 1}`,
203
+ title: `Group ${word}`,
204
+ defaultOpen: false,
205
+ nodes: g === 7 ? [item(28), item(29, [item(30, [item(31)])]), item(32)] : [1, 2, 3, 4].map((r) => item(g * 4 + r)),
206
+ }))
207
+
208
+ /** The page beside the column: what opens a row from outside it — a link, a search. */
209
+ function Page({ children }: { children: ReactNode }) {
210
+ return <div className="flex flex-1 flex-col items-start gap-2 p-6">{children}</div>
211
+ }
212
+
213
+ /** Every group starts shut. Open a row from the page: its group and the rows above it open, and the column scrolls to it. Close that group by hand: it stays closed until another row in it opens. */
214
+ export const OpensOntoTheCurrentRow: Story = {
215
+ args: { groups: SHUT_GROUPS, selected: undefined },
216
+ render: function Render(args) {
217
+ const [selected, setSelected] = useState<string | undefined>(undefined)
218
+ return (
219
+ <div className="flex h-screen bg-bg-base">
220
+ <Sidebar>
221
+ <NavTree
222
+ {...args}
223
+ selected={selected}
224
+ onSelect={(node, event) => {
225
+ event.preventDefault()
226
+ setSelected(node.id)
227
+ }}
228
+ />
229
+ </Sidebar>
230
+ <Page>
231
+ <Button variant="outlined" size="small" onClick={() => setSelected('i31')}>Open Item 31</Button>
232
+ <Button variant="outlined" size="small" onClick={() => setSelected('i10')}>Open Item 10</Button>
233
+ <Button variant="outlined" size="small" onClick={() => setSelected('i2')}>Open Item 2</Button>
234
+ </Page>
235
+ </div>
236
+ )
237
+ },
238
+ }
239
+
240
+ /** A new tab, where nothing is open yet: each button starts the column again, every group shut, and opens onto its row. */
241
+ export const InANewTab: Story = {
242
+ args: { groups: SHUT_GROUPS, selected: undefined },
243
+ render: function Render(args) {
244
+ const [tab, setTab] = useState<{ n: number; selected?: string }>({ n: 0 })
245
+ const open = (id: string) => setTab((now) => ({ n: now.n + 1, selected: id }))
246
+ return (
247
+ <div className="flex h-screen bg-bg-base">
248
+ <Sidebar key={tab.n}>
249
+ <NavTree
250
+ {...args}
251
+ selected={tab.selected}
252
+ onSelect={(node, event) => {
253
+ event.preventDefault()
254
+ setTab((now) => ({ ...now, selected: node.id }))
255
+ }}
256
+ />
257
+ </Sidebar>
258
+ <Page>
259
+ <Button variant="outlined" size="small" onClick={() => open('i31')}>Open Item 31 in a new tab</Button>
260
+ <Button variant="outlined" size="small" onClick={() => open('i14')}>Open Item 14 in a new tab</Button>
261
+ </Page>
262
+ </div>
263
+ )
264
+ },
265
+ }
266
+
267
+ /** The current row sits under a row whose rows are read only when it opens: `selectedParent` opens onto that row and opens it; once its rows are read, the current one is marked. */
268
+ export const UnderARowNotReadYet: Story = {
269
+ args: { selected: undefined },
270
+ render: function Render(args) {
271
+ const [selected, setSelected] = useState<string | undefined>(undefined)
272
+ const [open, setOpen] = useState(false)
273
+ const [read, setRead] = useState<NavTreeNode[] | null | undefined>(undefined)
274
+ const openRow = (next: boolean) => {
275
+ setOpen(next)
276
+ if (!next || read !== undefined) return
277
+ setRead(null)
278
+ setTimeout(() => setRead([item(4), item(5), item(6)]), 800)
279
+ }
280
+ const groups: NavTreeGroup[] = [
281
+ { id: 'n1', title: 'Group one', defaultOpen: false, nodes: [item(7), item(8)] },
282
+ { id: 'n2', title: 'Group two', defaultOpen: false, nodes: [item(1), { ...item(2), hasChildren: true, children: read, open, onOpenChange: openRow }, item(3)] },
283
+ ]
284
+ return (
285
+ <div className="flex h-screen bg-bg-base">
286
+ <Sidebar>
287
+ <NavTree
288
+ {...args}
289
+ groups={groups}
290
+ selected={selected}
291
+ selectedParent={selected === 'i5' ? 'i2' : undefined}
292
+ onSelect={(node, event) => {
293
+ event.preventDefault()
294
+ setSelected(node.id)
295
+ }}
296
+ />
297
+ </Sidebar>
298
+ <Page>
299
+ <Button variant="outlined" size="small" onClick={() => setSelected('i5')}>Open Item 5, under Item 2</Button>
300
+ </Page>
301
+ </div>
302
+ )
303
+ },
304
+ }
305
+
306
+ /** The current item is not a row in the tree: the place it is listed in stays marked, and `selectedParent` opens the group holding the row it is under — that row is not marked. */
307
+ export const NotARowHere: Story = {
308
+ args: { groups: SHUT_GROUPS.slice(0, 5), selected: undefined },
309
+ render: function Render(args) {
310
+ const [under, setUnder] = useState<string | undefined>(undefined)
311
+ return (
312
+ <div className="flex h-screen bg-bg-base">
313
+ <Sidebar>
314
+ <NavItem href="#" label="Item list" icon={placeholder} active />
315
+ <NavItem href="#" label="Another list" icon={placeholder} />
316
+ <NavTree {...args} selected={under && `item under ${under}`} selectedParent={under} />
317
+ </Sidebar>
318
+ <Page>
319
+ <Button variant="outlined" size="small" onClick={() => setUnder('i18')}>Open an item under Item 18</Button>
320
+ <Button variant="outlined" size="small" onClick={() => setUnder('i6')}>Open an item under Item 6</Button>
321
+ </Page>
322
+ </div>
323
+ )
324
+ },
325
+ }
@@ -167,3 +167,78 @@ describe('NavTree with no groups and no words', () => {
167
167
  expect(container.textContent).toBe('')
168
168
  })
169
169
  })
170
+
171
+ /** Group two's rows start shut here, so a row two levels in is reached only by opening the rows above it. */
172
+ const SHUT: NavTreeGroup[] = [
173
+ { id: 'g1', title: 'Group one', nodes: [{ id: 'a', label: 'Item a', href: '#a' }] },
174
+ {
175
+ id: 'g2',
176
+ title: 'Group two',
177
+ nodes: [
178
+ { id: 'b', label: 'Item b', href: '#b', defaultOpen: false, children: [{ id: 'c', label: 'Item c', href: '#c', defaultOpen: false, children: [{ id: 'd', label: 'Item d', href: '#d' }] }] },
179
+ { id: 'e', label: 'Item e', href: '#e' },
180
+ ],
181
+ },
182
+ ]
183
+
184
+ describe('NavTree opens onto the current row (Katerina, 30 October)', () => {
185
+ it('a row that becomes current shows: its shut group and the rows above it open', () => {
186
+ const { rerender } = render(<NavTree groups={SHUT} selected="a" />)
187
+ expect(hidden('Item d')).toBe(true)
188
+ rerender(<NavTree groups={SHUT} selected="d" />)
189
+ expect(hidden('Item d')).toBe(false)
190
+ expect(screen.getByRole('link', { name: 'Item d' }).getAttribute('aria-current')).toBe('page')
191
+ })
192
+
193
+ it('a group closed by hand opens for a new current row in it, and stays closed while that row stays current', async () => {
194
+ const { rerender } = render(<NavTree groups={SHUT} selected="e" />)
195
+ await userEvent.click(screen.getByRole('button', { name: 'Group two' }))
196
+ expect(hidden('Item e')).toBe(true)
197
+ rerender(<NavTree groups={SHUT} selected="d" />)
198
+ expect(hidden('Item e')).toBe(false)
199
+ await userEvent.click(screen.getByRole('button', { name: 'Group two' }))
200
+ rerender(<NavTree groups={SHUT} selected="d" />)
201
+ expect(hidden('Item e')).toBe(true)
202
+ })
203
+
204
+ it('a row current again after another opens its group again', async () => {
205
+ const { rerender } = render(<NavTree groups={SHUT} selected="e" />)
206
+ await userEvent.click(screen.getByRole('button', { name: 'Group two' }))
207
+ rerender(<NavTree groups={SHUT} selected="a" />)
208
+ rerender(<NavTree groups={SHUT} selected="e" />)
209
+ expect(hidden('Item e')).toBe(false)
210
+ })
211
+
212
+ it('a group this browser remembers closed opens for a current row in it, and is remembered open', () => {
213
+ window.localStorage.setItem('test.tree.g2', 'closed')
214
+ render(<NavTree groups={SHUT} selected="e" storageKey="test.tree" />)
215
+ expect(hidden('Item e')).toBe(false)
216
+ expect(window.localStorage.getItem('test.tree.g2')).toBe('open')
217
+ window.localStorage.removeItem('test.tree.g2')
218
+ })
219
+
220
+ it('a group the caller owns is told to open', () => {
221
+ const onOpenChange = vi.fn()
222
+ render(<NavTree groups={[SHUT[0], { ...SHUT[1], open: false, onOpenChange }]} selected="e" />)
223
+ expect(onOpenChange).toHaveBeenCalledWith(true)
224
+ })
225
+
226
+ it('selectedParent: the row the current one is under opens, so its rows are read, and nothing is marked', () => {
227
+ const onOpenChange = vi.fn()
228
+ const groups: NavTreeGroup[] = [
229
+ SHUT[0],
230
+ { id: 'g2', title: 'Group two', nodes: [{ id: 'p', label: 'Item p', href: '#p', hasChildren: true, open: false, onOpenChange }] },
231
+ ]
232
+ render(<NavTree groups={groups} selected="q" selectedParent="p" />)
233
+ expect(hidden('Item p')).toBe(false)
234
+ expect(onOpenChange).toHaveBeenCalledWith(true)
235
+ expect(screen.getByRole('link', { name: 'Item p' }).getAttribute('aria-current')).toBeNull()
236
+ })
237
+
238
+ it('a NavTreeSection the app draws opens for openFor', () => {
239
+ const { rerender } = render(<NavTreeSection title="Group a" defaultOpen={false}><a href="#a">Item a</a></NavTreeSection>)
240
+ expect(hidden('Item a')).toBe(true)
241
+ rerender(<NavTreeSection title="Group a" defaultOpen={false} openFor="a"><a href="#a">Item a</a></NavTreeSection>)
242
+ expect(hidden('Item a')).toBe(false)
243
+ })
244
+ })
package/src/NavTree.tsx CHANGED
@@ -84,8 +84,19 @@ export interface NavTreeProps {
84
84
  * is absent.
85
85
  */
86
86
  children?: ReactNode
87
- /** The row that is current: `active`, and its group starts open. */
87
+ /**
88
+ * The row that is current: `active`. Each time it names a new row, its
89
+ * group and every row above it open, closing nothing — a group closed by
90
+ * hand too — and the column scrolls to it once they have slid open.
91
+ */
88
92
  selected?: string
93
+ /**
94
+ * The row the current one sits under, while the tree does not draw the
95
+ * current one: its rows are not read yet, or it is not a row here. The tree
96
+ * opens onto that row the same way, opens the row itself so its rows are
97
+ * read, and marks nothing for it.
98
+ */
99
+ selectedParent?: string
89
100
  /** A row was clicked. A router app prevents the default and navigates. */
90
101
  onSelect?: (node: NavTreeNode, event: MouseEvent<HTMLAnchorElement>) => void
91
102
  /** What to say when `groups` is empty. The words are the caller's; absent, nothing is said. */
@@ -97,10 +108,58 @@ export interface NavTreeProps {
97
108
  /** How long the pointer rests on a group before `onIntent` (Peek's FolderTree, 150ms). */
98
109
  export const NAV_TREE_INTENT_MS = 150
99
110
 
111
+ /** How long the column waits to scroll to the current row: the rows above it slide open in 150ms. */
112
+ export const NAV_TREE_REVEAL_MS = 200
113
+
100
114
  function holds(nodes: NavTreeNode[] | null, id: string | undefined): boolean {
101
115
  return !!nodes && id !== undefined && nodes.some((node) => node.id === id || holds(node.children ?? null, id))
102
116
  }
103
117
 
118
+ /** The rows above the row `id`, outermost first; `null` when no row here is `id`. */
119
+ function rowsAbove(nodes: NavTreeNode[] | null | undefined, id: string): string[] | null {
120
+ for (const node of nodes ?? []) {
121
+ if (node.id === id) return []
122
+ const inner = rowsAbove(node.children, id)
123
+ if (inner) return [node.id, ...inner]
124
+ }
125
+ return null
126
+ }
127
+
128
+ /** What opens so the current row shows: its group and the rows above it — or above `selectedParent`, and that row, until the current one is drawn. */
129
+ interface Opening {
130
+ /** The current item, for `openFor`: a new one opens them again. */
131
+ item: string
132
+ group: string
133
+ rows: ReadonlySet<string>
134
+ }
135
+
136
+ function openingFor(groups: NavTreeGroup[], selected: string | undefined, selectedParent: string | undefined): Opening | null {
137
+ const item = selected ?? selectedParent
138
+ if (item === undefined) return null
139
+ for (const [target, andItself] of [[selected, false], [selectedParent, true]] as const) {
140
+ if (target === undefined) continue
141
+ for (const group of groups) {
142
+ const above = rowsAbove(group.nodes, target)
143
+ if (above) return { item, group: group.id, rows: new Set(andItself ? [...above, target] : above) }
144
+ }
145
+ }
146
+ return null
147
+ }
148
+
149
+ /**
150
+ * Scroll the column the row is in, and only that box — never the page, nor a
151
+ * drawer that is shut — so the row is in sight. A row in sight stays put.
152
+ */
153
+ function scrollToRow(row: HTMLElement) {
154
+ let box = row.parentElement
155
+ while (box && !(/(auto|scroll)/.test(getComputedStyle(box).overflowY) && box.scrollHeight > box.clientHeight)) box = box.parentElement
156
+ if (!box || box === document.documentElement || box === document.body) return
157
+ const at = row.getBoundingClientRect()
158
+ const view = box.getBoundingClientRect()
159
+ if (at.top < view.top) box.scrollTop -= view.top - at.top
160
+ else if (at.bottom > view.bottom) box.scrollTop += at.bottom - view.bottom
161
+ }
162
+
104
163
  /** A line in the rows' place: level with the rows, which pad themselves (Katerina, 14 September). */
105
164
  function Line({ message }: { message: string }) {
106
165
  return (
@@ -110,12 +169,14 @@ function Line({ message }: { message: string }) {
110
169
  )
111
170
  }
112
171
 
113
- function Row({ node, selected, onSelect }: { node: NavTreeNode } & Pick<NavTreeProps, 'selected' | 'onSelect'>) {
172
+ type Drawn = Pick<NavTreeProps, 'selected' | 'onSelect'> & { opening: Opening | null }
173
+
174
+ function Row({ node, selected, onSelect, opening }: { node: NavTreeNode } & Drawn) {
114
175
  const under =
115
176
  node.childrenMessage !== undefined ? (
116
177
  <Line message={node.childrenMessage} />
117
178
  ) : node.children?.length ? (
118
- node.children.map((child) => <Row key={child.id} node={child} selected={selected} onSelect={onSelect} />)
179
+ node.children.map((child) => <Row key={child.id} node={child} selected={selected} onSelect={onSelect} opening={opening} />)
119
180
  ) : node.children === null || (node.hasChildren && node.children === undefined) ? (
120
181
  <SkeletonList rows={2} />
121
182
  ) : undefined
@@ -134,6 +195,7 @@ function Row({ node, selected, onSelect }: { node: NavTreeNode } & Pick<NavTreeP
134
195
  defaultOpen={node.defaultOpen ?? true}
135
196
  open={node.open}
136
197
  onOpenChange={node.onOpenChange}
198
+ openFor={opening?.rows.has(node.id) ? opening.item : undefined}
137
199
  onClick={onSelect ? (event) => onSelect(node, event) : undefined}
138
200
  >
139
201
  {under}
@@ -141,7 +203,7 @@ function Row({ node, selected, onSelect }: { node: NavTreeNode } & Pick<NavTreeP
141
203
  )
142
204
  }
143
205
 
144
- function Group({ group, selected, onSelect, storageKey }: { group: NavTreeGroup } & Pick<NavTreeProps, 'selected' | 'onSelect' | 'storageKey'>) {
206
+ function Group({ group, selected, onSelect, opening, storageKey }: { group: NavTreeGroup } & Drawn & Pick<NavTreeProps, 'storageKey'>) {
145
207
  return (
146
208
  <NavTreeSection
147
209
  id={group.id}
@@ -156,9 +218,10 @@ function Group({ group, selected, onSelect, storageKey }: { group: NavTreeGroup
156
218
  open={group.open}
157
219
  onOpenChange={group.onOpenChange}
158
220
  storageKey={storageKey ? `${storageKey}.${group.id}` : undefined}
221
+ openFor={opening?.group === group.id ? opening.item : undefined}
159
222
  onIntent={group.onIntent}
160
223
  >
161
- {group.nodes?.map((node) => <Row key={node.id} node={node} selected={selected} onSelect={onSelect} />)}
224
+ {group.nodes?.map((node) => <Row key={node.id} node={node} selected={selected} onSelect={onSelect} opening={opening} />)}
162
225
  </NavTreeSection>
163
226
  )
164
227
  }
@@ -194,6 +257,8 @@ export interface NavTreeSectionProps {
194
257
  pending?: boolean
195
258
  /** Remember it open or closed in this browser, under this key. */
196
259
  storageKey?: string
260
+ /** The current item, when it sits in this group: the group opens each time this names a new one — `CollapsibleSection`'s. */
261
+ openFor?: string
197
262
  /** The rows: `NavItem`s. */
198
263
  children?: ReactNode
199
264
  }
@@ -205,7 +270,7 @@ export interface NavTreeSectionProps {
205
270
  * `groups`; an app whose groups each read their own data draws them itself,
206
271
  * as `NavTree`'s children.
207
272
  */
208
- export function NavTreeSection({ id, title, message, loading = false, pending, trailing, actions, menu, icon, defaultOpen = true, open, onOpenChange, storageKey, onIntent, children }: NavTreeSectionProps) {
273
+ export function NavTreeSection({ id, title, message, loading = false, pending, trailing, actions, menu, icon, defaultOpen = true, open, onOpenChange, storageKey, openFor, onIntent, children }: NavTreeSectionProps) {
209
274
  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
210
275
  useEffect(() => () => clearTimeout(timer.current), [])
211
276
  const intent = onIntent
@@ -233,6 +298,7 @@ export function NavTreeSection({ id, title, message, loading = false, pending, t
233
298
  onOpenChange={onOpenChange}
234
299
  pending={pending}
235
300
  storageKey={storageKey}
301
+ openFor={openFor}
236
302
  trailing={trailing}
237
303
  actions={actions}
238
304
  menu={menu}
@@ -255,10 +321,36 @@ export function NavTreeSection({ id, title, message, loading = false, pending, t
255
321
  * arrow that folds what is under it. Groups and rows can be read when they
256
322
  * open. Only the group that holds the current row starts open, unless the
257
323
  * caller owns it.
324
+ *
325
+ * Opening a row shows where it lives (Katerina, 30 October: a file opened
326
+ * from another app's card, in a new tab, sat marked inside a shut Folder):
327
+ * each new current row opens its group and the rows above it, even those
328
+ * closed by hand, once — closed again, they stay closed until another opens —
329
+ * and the column scrolls to it. Groups the app draws itself take `openFor`
330
+ * for that; the scroll is the tree's either way.
258
331
  */
259
- export function NavTree({ title, titleActions, groups, children, selected, onSelect, emptyMessage = '', storageKey }: NavTreeProps) {
332
+ export function NavTree({ title, titleActions, groups, children, selected, selectedParent, onSelect, emptyMessage = '', storageKey }: NavTreeProps) {
333
+ const opening = groups ? openingFor(groups, selected, selectedParent) : null
334
+ // 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.
335
+ const box = useRef<HTMLDivElement>(null)
336
+ const scrolled = useRef<string | undefined>(undefined)
337
+ const waiting = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
338
+ const latest = useRef(selected)
339
+ latest.current = selected
340
+ useEffect(() => {
341
+ if (selected === undefined || scrolled.current === selected || waiting.current !== undefined) return
342
+ waiting.current = setTimeout(() => {
343
+ waiting.current = undefined
344
+ const row = box.current?.querySelector<HTMLElement>('[aria-current="page"]')
345
+ if (!row || row.getBoundingClientRect().height === 0) return
346
+ scrolled.current = latest.current
347
+ scrollToRow(row)
348
+ }, NAV_TREE_REVEAL_MS)
349
+ })
350
+ useEffect(() => () => clearTimeout(waiting.current), [])
260
351
  return (
261
- <>
352
+ // `contents`: a box to find the current row in, that lays nothing out — the groups stay the column's own.
353
+ <div ref={box} className="contents">
262
354
  {title && <SectionHeader title={title} look="quiet" showActions="always" actions={titleActions} className="mt-4 shrink-0" />}
263
355
  {groups === undefined ? (
264
356
  children
@@ -268,8 +360,8 @@ export function NavTree({ title, titleActions, groups, children, selected, onSel
268
360
  // No words, no line: an app that says nothing when it has no groups.
269
361
  emptyMessage ? <Line message={emptyMessage} /> : null
270
362
  ) : (
271
- groups.map((group) => <Group key={group.id} group={group} selected={selected} onSelect={onSelect} storageKey={storageKey} />)
363
+ groups.map((group) => <Group key={group.id} group={group} selected={selected} onSelect={onSelect} opening={opening} storageKey={storageKey} />)
272
364
  )}
273
- </>
365
+ </div>
274
366
  )
275
367
  }