@estiva-app/ui 0.117.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.
Files changed (74) hide show
  1. package/dist/ActivityLine.d.ts +37 -0
  2. package/dist/ActivityLine.d.ts.map +1 -0
  3. package/dist/CollapsibleSection.d.ts +6 -1
  4. package/dist/CollapsibleSection.d.ts.map +1 -1
  5. package/dist/ContainerHeader.d.ts +10 -1
  6. package/dist/ContainerHeader.d.ts.map +1 -1
  7. package/dist/ConversationLayout.d.ts.map +1 -1
  8. package/dist/DialogShell.d.ts +11 -3
  9. package/dist/DialogShell.d.ts.map +1 -1
  10. package/dist/ListColumn.d.ts +6 -1
  11. package/dist/ListColumn.d.ts.map +1 -1
  12. package/dist/ListTable.d.ts +71 -0
  13. package/dist/ListTable.d.ts.map +1 -0
  14. package/dist/MembersDialog.d.ts.map +1 -1
  15. package/dist/NavTree.d.ts +12 -1
  16. package/dist/NavTree.d.ts.map +1 -1
  17. package/dist/PageHeader.d.ts +11 -2
  18. package/dist/PageHeader.d.ts.map +1 -1
  19. package/dist/conversationScroll.d.ts +6 -0
  20. package/dist/conversationScroll.d.ts.map +1 -1
  21. package/dist/index.d.ts +2 -0
  22. package/dist/index.d.ts.map +1 -1
  23. package/dist/index.js +586 -433
  24. package/dist/index.js.map +4 -4
  25. package/dist/revealCurrentRow.d.ts +28 -0
  26. package/dist/revealCurrentRow.d.ts.map +1 -0
  27. package/dist/showInConversation.d.ts +5 -0
  28. package/dist/showInConversation.d.ts.map +1 -1
  29. package/package.json +1 -1
  30. package/registry.json +253 -5
  31. package/src/ActivityLine.mdx +67 -0
  32. package/src/ActivityLine.stories.tsx +49 -0
  33. package/src/ActivityLine.test.tsx +47 -0
  34. package/src/ActivityLine.tsx +74 -0
  35. package/src/Button.mdx +5 -0
  36. package/src/CollapsibleSection.mdx +6 -0
  37. package/src/CollapsibleSection.stories.tsx +4 -1
  38. package/src/CollapsibleSection.test.tsx +11 -0
  39. package/src/CollapsibleSection.tsx +7 -2
  40. package/src/ContainerHeader.mdx +7 -0
  41. package/src/ContainerHeader.stories.tsx +3 -0
  42. package/src/ContainerHeader.test.tsx +12 -1
  43. package/src/ContainerHeader.tsx +38 -18
  44. package/src/ConversationLayout.mdx +5 -2
  45. package/src/ConversationLayout.scroll.test.tsx +62 -1
  46. package/src/ConversationLayout.stories.tsx +44 -0
  47. package/src/ConversationLayout.tsx +33 -2
  48. package/src/DialogShell.mdx +8 -2
  49. package/src/DialogShell.stories.tsx +20 -7
  50. package/src/DialogShell.tsx +10 -4
  51. package/src/ListColumn.mdx +1 -0
  52. package/src/ListColumn.stories.tsx +53 -1
  53. package/src/ListColumn.tsx +10 -2
  54. package/src/ListTable.mdx +112 -0
  55. package/src/ListTable.stories.tsx +133 -0
  56. package/src/ListTable.test.tsx +81 -0
  57. package/src/ListTable.tsx +178 -0
  58. package/src/MembersDialog.test.tsx +8 -0
  59. package/src/MembersDialog.tsx +2 -10
  60. package/src/NavTree.mdx +7 -1
  61. package/src/NavTree.stories.tsx +75 -1
  62. package/src/NavTree.test.tsx +18 -0
  63. package/src/NavTree.tsx +23 -34
  64. package/src/PageHeader.mdx +13 -2
  65. package/src/PageHeader.stories.tsx +35 -1
  66. package/src/PageHeader.test.tsx +21 -0
  67. package/src/PageHeader.tsx +17 -5
  68. package/src/conversationScroll.ts +11 -0
  69. package/src/index.ts +2 -0
  70. package/src/registry/registry.test.ts +5 -5
  71. package/src/revealCurrentRow.test.tsx +168 -0
  72. package/src/revealCurrentRow.ts +68 -0
  73. package/src/showInConversation.ts +9 -1
  74. package/stories/Choosing.mdx +2 -0
@@ -38,6 +38,24 @@ describe('NavTree', () => {
38
38
  expect(onSelect.mock.calls[0][0].id).toBe('c')
39
39
  })
40
40
 
41
+ it('a group says its count beside its title, and the title stays its own words; an app-drawn group the same', () => {
42
+ render(
43
+ <NavTree groups={[{ id: 'g', title: 'Group one', count: 2, defaultOpen: false, nodes: [{ id: 'a', label: 'Item one', href: '#' }] }]} />,
44
+ )
45
+ expect(screen.getByText('2')).toBeTruthy()
46
+ expect(screen.getByText('Group one').textContent).toBe('Group one')
47
+ cleanup()
48
+ render(
49
+ <NavTree>
50
+ <NavTreeSection title="Group two" count={3} menu={<MenuItem label="Rename" />} menuLabel="More for Group two">
51
+ <a href="#">Item two</a>
52
+ </NavTreeSection>
53
+ </NavTree>,
54
+ )
55
+ expect(screen.getByText('3')).toBeTruthy()
56
+ expect(screen.getByRole('button', { name: 'More for Group two' })).toBeTruthy()
57
+ })
58
+
41
59
  it('draws the quiet label when given one', () => {
42
60
  render(<NavTree title="Groups" groups={GROUPS} emptyMessage="Nothing here yet." />)
43
61
  expect(screen.getByText('Groups')).not.toBeNull()
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 {
@@ -50,10 +51,14 @@ export interface NavTreeGroup {
50
51
  message?: string
51
52
  /** Beside the title, always shown: an `UnreadDot`, typically. */
52
53
  trailing?: ReactNode
54
+ /** How many rows it holds, 8px after the title, shown open or shut — `SectionHeader`'s. */
55
+ count?: number
53
56
  /** Beside the title, shown while the row is hovered or keyboard-focused: "Open", typically. */
54
57
  actions?: SectionAction[]
55
58
  /** The group's "More options" menu, after its actions: `MenuItem`s — a folder's Rename, Archive. */
56
59
  menu?: ReactNode
60
+ /** The ⋮'s accessible name. Default "More options". */
61
+ menuLabel?: string
57
62
  /** 16px, before the title — a folder's; the arrow takes its place on hover. */
58
63
  icon?: ReactNode
59
64
  defaultOpen?: boolean
@@ -119,7 +124,7 @@ export interface NavTreeProps {
119
124
  export const NAV_TREE_INTENT_MS = 150
120
125
 
121
126
  /** How long the column waits to scroll to the current row: the rows above it slide open in 150ms. */
122
- export const NAV_TREE_REVEAL_MS = 200
127
+ export const NAV_TREE_REVEAL_MS = REVEAL_MS
123
128
 
124
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). */
125
130
  export const NAV_TREE_PENDING_MS = 2000
@@ -159,22 +164,6 @@ function openingFor(groups: NavTreeGroup[], selected: string | undefined, select
159
164
  return null
160
165
  }
161
166
 
162
- /**
163
- * Scroll the column the row is in, and only that box — never the page, nor a
164
- * drawer that is shut — so the row is in sight. A row in sight stays put.
165
- * A group taller than the column keeps its top in sight, as the browser's
166
- * `block: 'nearest'` does (a row is never that tall).
167
- */
168
- function scrollToRow(row: HTMLElement) {
169
- let box = row.parentElement
170
- while (box && !(/(auto|scroll)/.test(getComputedStyle(box).overflowY) && box.scrollHeight > box.clientHeight)) box = box.parentElement
171
- if (!box || box === document.documentElement || box === document.body) return
172
- const at = row.getBoundingClientRect()
173
- const view = box.getBoundingClientRect()
174
- if (at.top < view.top) box.scrollTop -= view.top - at.top
175
- else if (at.bottom > view.bottom) box.scrollTop += Math.min(at.bottom - view.bottom, at.top - view.top)
176
- }
177
-
178
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. */
179
168
  function Line({ message }: { message: string }) {
180
169
  return <EmptyState scope="rows" message={message} />
@@ -231,8 +220,10 @@ function Group({ group, selected, onSelect, opening, storageKey }: { group: NavT
231
220
  message={group.message}
232
221
  loading={group.nodes === null}
233
222
  trailing={group.trailing}
223
+ {...(group.count != null ? { count: group.count } : {})}
234
224
  actions={group.actions}
235
225
  menu={group.menu}
226
+ {...(group.menuLabel != null ? { menuLabel: group.menuLabel } : {})}
236
227
  icon={group.icon}
237
228
  defaultOpen={group.defaultOpen ?? holds(group.nodes, selected)}
238
229
  open={group.open}
@@ -254,10 +245,17 @@ export interface NavTreeSectionProps {
254
245
  message?: string
255
246
  /** Beside the title, always shown: an `UnreadDot`, typically. */
256
247
  trailing?: ReactNode
248
+ /**
249
+ * How many rows it holds, 8px after the title, shown open or shut — `SectionHeader`'s. Written into the title by
250
+ * hand ("Other teams · 2"), the number took the heading's own type (Katerina, 16 November).
251
+ */
252
+ count?: number
257
253
  /** Beside the title, shown while the row is hovered or keyboard-focused: "Open", typically. */
258
254
  actions?: SectionAction[]
259
255
  /** The group's "More options" menu, after its actions: `MenuItem`s. */
260
256
  menu?: ReactNode
257
+ /** The ⋮'s accessible name, "More for Group one". Default "More options". */
258
+ menuLabel?: string
261
259
  /** 16px, before the title; the arrow takes its place on hover. */
262
260
  icon?: ReactNode
263
261
  /** Open unless told otherwise. */
@@ -291,7 +289,7 @@ export interface NavTreeSectionProps {
291
289
  * `groups`; an app whose groups each read their own data draws them itself,
292
290
  * as `NavTree`'s children.
293
291
  */
294
- export function NavTreeSection({ id, title, message, loading = false, pending = false, trailing, actions, menu, icon, defaultOpen = true, open, onOpenChange, storageKey, openFor, onIntent, children }: NavTreeSectionProps) {
292
+ export function NavTreeSection({ id, title, message, loading = false, pending = false, trailing, count, actions, menu, menuLabel, icon, defaultOpen = true, open, onOpenChange, storageKey, openFor, onIntent, children }: NavTreeSectionProps) {
295
293
  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
296
294
  useEffect(() => () => clearTimeout(timer.current), [])
297
295
  // Pending for too long: a slow read, drawn as `loading` is (OPT-11). Each new wait starts the time again.
@@ -333,8 +331,10 @@ export function NavTreeSection({ id, title, message, loading = false, pending =
333
331
  storageKey={storageKey}
334
332
  openFor={openFor}
335
333
  trailing={trailing}
334
+ {...(count != null ? { count } : {})}
336
335
  actions={actions}
337
336
  menu={menu}
337
+ {...(menuLabel != null ? { menuLabel } : {})}
338
338
  icon={icon}
339
339
  className="shrink-0"
340
340
  // 2px between rows, as a list column's and a menu's (Katerina, 5 October).
@@ -366,23 +366,12 @@ export function NavTreeSection({ id, title, message, loading = false, pending =
366
366
  */
367
367
  export function NavTree({ title, titleActions, groups, children, selected, selectedParent, selectedGroup, onSelect, emptyMessage = '', storageKey }: NavTreeProps) {
368
368
  const opening = groups ? openingFor(groups, selected, selectedParent) : null
369
- // 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
+ */
370
373
  const box = useRef<HTMLDivElement>(null)
371
- const scrolled = useRef<string | undefined>(undefined)
372
- const waiting = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
373
- const latest = useRef(selected)
374
- latest.current = selected
375
- useEffect(() => {
376
- if (selected === undefined || scrolled.current === selected || waiting.current !== undefined) return
377
- waiting.current = setTimeout(() => {
378
- waiting.current = undefined
379
- const row = box.current?.querySelector<HTMLElement>('[aria-current="page"]')
380
- if (!row || row.getBoundingClientRect().height === 0) return
381
- scrolled.current = latest.current
382
- scrollToRow(row)
383
- }, NAV_TREE_REVEAL_MS)
384
- })
385
- useEffect(() => () => clearTimeout(waiting.current), [])
374
+ useRevealCurrentRow(box, selected)
386
375
  // Once per arrival, as soon as the group is drawn: its heading does not move as it opens, so nothing is waited for.
387
376
  const groupScrolled = useRef<string | undefined>(undefined)
388
377
  useEffect(() => {
@@ -26,10 +26,14 @@ page's buttons, 4px apart.
26
26
 
27
27
  - `private`: a lock before the title, when only its members can open it.
28
28
  - `after`: something that belongs to the title, right after it — a small
29
- `Button` that opens it elsewhere, a `Chip`.
29
+ `Button` that opens it elsewhere, a `Chip`, the places it is listed in as
30
+ **InlineChip**s. Several, given together, sit 8px apart: the bar spaces
31
+ them, so write no box around them.
30
32
 
31
33
  <Canvas of={PageHeaderStories.AfterTheTitle} />
32
34
 
35
+ <Canvas of={PageHeaderStories.SeveralAfterTheTitle} />
36
+
33
37
  - `meta`: quiet counts at the right, a dot between them; `done: true`
34
38
  for words about what is finished.
35
39
 
@@ -47,6 +51,12 @@ page's buttons, 4px apart.
47
51
 
48
52
  <Canvas of={PageHeaderStories.ColumnToggle} />
49
53
 
54
+ - `button`: a button with words, before the page's buttons and 8px clear
55
+ of them — Join, Add to Open work. Two, given together (Follow and Join),
56
+ sit 8px apart. Never a second toolbar beside the first.
57
+
58
+ <Canvas of={PageHeaderStories.AButtonBeforeTheButtons} />
59
+
50
60
  - A **Breadcrumb** in the title's place, for a page reached down a trail.
51
61
 
52
62
  <Canvas of={PageHeaderStories.Breadcrumb} />
@@ -107,6 +117,7 @@ It does these by itself. Write none of them around it.
107
117
  |---|---|---|
108
118
  | Draws ContainerHeader's bar: 48px, the hairline under it, 16px in at each end | a header row of your own | ContainerHeader used on its own in an app |
109
119
  | Keeps the counts, the time and the members 12px apart, and 12px clear of the buttons | `gap-3`, `pr-2` of your own around them | |
120
+ | Sets several things after the title 8px apart, and a button with words 8px before the page's buttons | a `flex gap-2` box of your own around them | |
110
121
  | Cuts a long string title short and keeps everything else whole | `truncate`, `min-w-0`, `shrink-0` | |
111
122
  | Draws the counts in `MetaText`, a dot between them | a dot or a count style of your own | |
112
123
  | Draws the time 12px italic, with the exact time in a tooltip | `text-caption italic` and a `WithTooltip` of your own | |
@@ -116,7 +127,7 @@ It does these by itself. Write none of them around it.
116
127
 
117
128
  | Key | What it does |
118
129
  |---|---|
119
- | Tab | Moves through the bar in reading order: what is after the title, the members, then the buttons |
130
+ | Tab | Moves through the bar in reading order: what is after the title, the members, the button with words, then the buttons |
120
131
  | Arrow keys | Move along the `Toolbar` of buttons, which is one Tab stop — the Toolbar's own keys |
121
132
 
122
133
  ## Props
@@ -1,9 +1,10 @@
1
1
  import { useState } from 'react'
2
2
  import type { Decorator, Meta, StoryObj } from '@storybook/react-vite'
3
- import { IconBox, IconDotsVertical, IconLayoutSidebarRight, IconLayoutSidebarRightFilled, IconSquareRounded } from '@tabler/icons-react'
3
+ import { IconBox, IconDotsVertical, IconLayoutSidebarRight, IconLayoutSidebarRightFilled, IconSquareRounded, IconTarget } from '@tabler/icons-react'
4
4
  import { Avatar } from './Avatar'
5
5
  import { Breadcrumb as Trail } from './Breadcrumb'
6
6
  import { Button } from './Button'
7
+ import { InlineChip } from './InlineChip'
7
8
  import { MembersPill } from './MembersPill'
8
9
  import { Menu, MenuItem } from './Menu'
9
10
  import { PageHeader } from './PageHeader'
@@ -37,6 +38,7 @@ const meta = {
37
38
  argTypes: {
38
39
  leading: { control: false },
39
40
  after: { control: false },
41
+ button: { control: false },
40
42
  members: { control: false },
41
43
  actions: { control: false },
42
44
  },
@@ -93,6 +95,38 @@ export const AfterTheTitle: Story = {
93
95
  },
94
96
  }
95
97
 
98
+ /** Several things after the title, 8px apart, spaced by the bar: the places it is listed in, then a small button. */
99
+ export const SeveralAfterTheTitle: Story = {
100
+ args: {
101
+ after: (
102
+ <>
103
+ <InlineChip href="#" icon={<IconTarget size={14} stroke={1.5} />}>
104
+ Group one
105
+ </InlineChip>
106
+ <InlineChip href="#" icon={<IconTarget size={14} stroke={1.5} />}>
107
+ Group two
108
+ </InlineChip>
109
+ <Button size="small" href="https://example.com" external leadingIcon={<IconSquareRounded size={14} stroke={1.5} />}>
110
+ Open
111
+ </Button>
112
+ </>
113
+ ),
114
+ },
115
+ }
116
+
117
+ /** A button with words before the page's buttons, 8px clear of them. */
118
+ export const AButtonBeforeTheButtons: Story = {
119
+ args: {
120
+ members,
121
+ button: (
122
+ <Button size="small" variant="primary">
123
+ Join
124
+ </Button>
125
+ ),
126
+ actions,
127
+ },
128
+ }
129
+
96
130
  /** Quiet counts at the right, a dot between them; words about what is finished in the success colour. */
97
131
  export const Counts: Story = { args: { leading: icon, meta: ['6 open', { label: '2 done', done: true }] } }
98
132
 
@@ -31,6 +31,27 @@ describe('PageHeader', () => {
31
31
  expect(screen.queryByRole('img', { name: 'Private' })).toBeNull()
32
32
  })
33
33
 
34
+ it('sets several things after the title 8px apart, and a button with words 8px before the page’s buttons', () => {
35
+ render(
36
+ <PageHeader
37
+ title="Item one"
38
+ after={
39
+ <>
40
+ <a href="#">Group one</a>
41
+ <a href="#">Group two</a>
42
+ </>
43
+ }
44
+ button={<button>Join</button>}
45
+ actions={<button>More</button>}
46
+ />,
47
+ )
48
+ expect(screen.getByText('Group one').parentElement?.className).toContain('gap-2')
49
+ const join = screen.getByRole('button', { name: 'Join' }).parentElement as HTMLElement
50
+ expect(join.className).toContain('pr-1')
51
+ // The button comes before the page's buttons, in reading order.
52
+ expect(join.compareDocumentPosition(screen.getByRole('button', { name: 'More' })) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy()
53
+ })
54
+
34
55
  it('a private page has a lock named "Private" before its title', () => {
35
56
  const { container } = render(<PageHeader title="Item one" private />)
36
57
  const lock = screen.getByRole('img', { name: 'Private' })
@@ -37,7 +37,10 @@ export interface PageHeaderProps {
37
37
  leading?: ReactNode
38
38
  /** A lock before the title: only its members can open this page. Named "Private" to assistive technology and in a tooltip. */
39
39
  private?: boolean
40
- /** Right after the title, 8px from it, and never cut short: a small `Button`, a `Chip`. */
40
+ /**
41
+ * Right after the title, 8px from it, and never cut short: a small `Button`, a `Chip`, a `Link`. Several, given
42
+ * together (a fragment), sit 8px apart: the bar spaces them, not a box of your own (Katerina, 16 November).
43
+ */
41
44
  after?: ReactNode
42
45
  /** Quiet words at the right, before the members: counts. A dot between each, each in `MetaText` (in Signal, the mono micro-type). */
43
46
  meta?: (string | PageHeaderMeta)[]
@@ -45,13 +48,19 @@ export interface PageHeaderProps {
45
48
  time?: { label: string; exact: string }
46
49
  /** Who is in it: a `MembersPill`. */
47
50
  members?: ReactNode
51
+ /**
52
+ * A button with words, before the page's buttons and 8px clear of them: Join, Add to Open work. Two, given together
53
+ * (Follow and Join), sit 8px apart. Peek drew them in a box of its own beside the toolbar, for want of this place
54
+ * (Katerina, 16 November).
55
+ */
56
+ button?: ReactNode
48
57
  /** The page's own buttons, at the right edge: a `Toolbar` with `surface={false}` of `ToolbarButton`s, or one `IconButton`. */
49
58
  actions?: ReactNode
50
59
  /** Placement only. */
51
60
  className?: string
52
61
  }
53
62
 
54
- export function PageHeader({ title, leading, private: locked = false, after, meta, time, members, actions, className }: PageHeaderProps) {
63
+ export function PageHeader({ title, leading, private: locked = false, after, meta, time, members, button, actions, className }: PageHeaderProps) {
55
64
  const words = (meta ?? []).map((one) => (typeof one === 'string' ? { label: one } : one))
56
65
  const quiet = words.length > 0 || time != null || members != null
57
66
 
@@ -64,17 +73,18 @@ export function PageHeader({ title, leading, private: locked = false, after, met
64
73
  </WithTooltip>
65
74
  )}
66
75
  {typeof title === 'string' ? <span className="truncate text-body-2-strong text-text-primary">{title}</span> : <div className="flex min-w-0 items-center">{title}</div>}
67
- {after != null && <span className="flex shrink-0 items-center">{after}</span>}
76
+ {after != null && <span className="flex shrink-0 items-center gap-2">{after}</span>}
68
77
  </div>
69
78
  )
70
79
 
80
+ const buttons = actions != null || button != null
71
81
  const right =
72
- quiet || actions != null ? (
82
+ quiet || buttons ? (
73
83
  <>
74
84
  {quiet && (
75
85
  // The quiet group: 12px between its parts, and 12px clear of the buttons — the bar sets
76
86
  // its actions 4px apart, so the group adds the other 8px, as Peek's and Leaf's bars do.
77
- <div className={cn('flex items-center gap-3', actions != null && 'pr-2')}>
87
+ <div className={cn('flex items-center gap-3', buttons && 'pr-2')}>
78
88
  {words.length > 0 && (
79
89
  <div className="flex items-center gap-2">
80
90
  {words.map((one, i) => (
@@ -97,6 +107,8 @@ export function PageHeader({ title, leading, private: locked = false, after, met
97
107
  {members}
98
108
  </div>
99
109
  )}
110
+ {/* The bar sets its parts 4px apart; the other 4px keep the words 8px clear of the icons. */}
111
+ {button != null && <span className={cn('flex shrink-0 items-center gap-2', actions != null && 'pr-1')}>{button}</span>}
100
112
  {actions}
101
113
  </>
102
114
  ) : undefined
@@ -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.
package/src/index.ts CHANGED
@@ -139,6 +139,7 @@ export { TopBar, type TopBarProps } from './TopBar'
139
139
  export { PersonTrigger, type PersonTriggerProps } from './PersonTrigger'
140
140
  export { Property, type PropertyProps } from './Property'
141
141
  export { Reaction, type ReactionProps } from './Reaction'
142
+ export { ActivityLine, type ActivityLineProps } from './ActivityLine'
142
143
  export { ConversationActions, type ConversationActionsProps } from './ConversationActions'
143
144
  export { ConversationCard, ReplyCard, type ConversationCardProps, type ConversationEntryProps, type ConversationPerson, type ReplyCardProps } from './ConversationCard'
144
145
  export { ConversationLayout, type ConversationItem, type ConversationLayoutProps } from './ConversationLayout'
@@ -171,6 +172,7 @@ export { ContainerHeader, type ContainerHeaderProps } from './ContainerHeader'
171
172
  export { Panel, type PanelProps } from './Panel'
172
173
  export { PageHeader, type PageHeaderMeta, type PageHeaderProps } from './PageHeader'
173
174
  export { ListColumn, type ListColumnProps } from './ListColumn'
175
+ export { ListTable, ListTableRow, type ListTableColumn, type ListTableColumnKeep, type ListTableColumnWidth, type ListTableProps, type ListTableRowProps } from './ListTable'
174
176
  export { CollapsibleSection, useRememberedOpen, type CollapsibleSectionProps } from './CollapsibleSection'
175
177
  export { SectionLabel } from './SectionLabel'
176
178
  export { Tabs, type TabDef, type TabsProps } from './Tabs'
@@ -48,20 +48,20 @@ describe('the registry builds', () => {
48
48
  expect(registry.entries.map((one) => one.name).sort()).toEqual(values.map((one) => one.name).sort())
49
49
  })
50
50
 
51
- it('counts 253 names over 129 files: 167 components, 78 helpers and 8 hooks (useShortcut, a key that works from anywhere on the page, for Peek’s Ctrl/Cmd+O to Add to Open work (TOPI-7), on 10 November; CornerMenu, the "…" over a row’s or a card’s corner with Show as and Remove (TOPI-5), on 10 November; ConversationHeading, which place a comment is on in a list mixing several places (TOPI-2), on 9 November; FollowSwitch, LevelIcon and WhoFollowsDialog, how you follow a place and who follows it (TEA-6), on 6 November; goneWords and GONE_CLOSED, what stands in a gone comment’s place and under its thread in every app (ONE-9), on 6 November; DeletedNotice and NoAccessNotice, the cards on a deleted file and on one you cannot open (ALO-4), on 3 November; useFormBusy, whether a Form around it is sending, read by the editor’s DocumentField from the main entry, in the review of 2 November; useLeftAt, sendsInLayout, useSeenOnScreen, showInConversation and showInConversationWhenDrawn, where a conversation scrolls, what was seen and a link landing on a comment, moved from Peek for every app, on 2 November; useRememberedOpen, the fold a section remembers, read by the app, and NAV_TREE_PENDING_MS and isPlainClick, Peek’s Folder timer and plain-click check, moved in, on 2 November; FormDialog, MoveDialog and ArchiveDialog, the dialogs Peek wired by hand, on 2 November; ConversationPlace, the line saying where a comment was said, and DocumentField, a rich-text field of a form, moved from Peek, on 2 November; ArchivedNotice, the card on an archived file, from Peek, Ship and Leaf, on 31 October; caretOnOpen, the box at a thread’s foot taking the caret when a ConversationLayout opens it, without scrolling, on 31 October; the conversation from Peek for every app, with PageHeader and PinnedComment, on 31 October, and ResolutionNote and ResolutionHistory gone with the resolved looks not picked, on 1 November; useSidebarFold, a folded sidebar kept folded in every app, on 31 October; cardShapeMemory, a card’s last shape on this device, lifted from Peek and Ship for Leaf, and ReferenceCards and useReferenceCards gone with their deprecated page, in the widget review, on 30 October; inTheBox, a card or part in a box being written in, on the files’ fill and in words, on 29 October; archivedLine, the line on an archived file in every app (PEEKM-2), on 23 October; keepCommentBoxWarm, a box built ahead, exported as 0.84.0 promised (PEEKM-1), on 21 October;linkedFrom and linkStateFrom, one card for a file in every app (5ebf2756), on 21 October; ComposeBox, ComposeKeys and COMPOSE_EDITOR_CLASSES gone into CommentBox’s own frame (one box), on 21 October; LinkPlaces with linkPlaceAt and staysChip, a link in a document drawn where it sits (WBD-4), on 20 October; DocumentEditor, one document editor for every app, and PersonReference, `@` in a document (WBD-3), on 20 October; toggleTableHeaderRow, a table’s header row on and off (LEAF-12), on 19 October;EntryShell, the screen while nobody is signed in, moved from Peek (AUT-3), on 17 October; CommentBox with commentBoxRows, and ReactionRow with AddReactionButton and whoReacted, the shared comment box and reaction row (COMM-2), on 17 October; the link widgets — LinkChip, LinkRow, LinkCard, CardUnder, PartCard, LinkPreview and their parts, with useCanHover, chosenOf, loadingShapeOf and unavailableMemory — from the Widgets 2 prototype, on 16 October; InlineText, a title or the line under it edited where it stands (SUM-4), on 16 October; ComposeBox with ComposeKeys and its classes, CommentHighlights with its five helpers, and keepSelection and releaseSelection, from the Leaf prototype (LEAF-4), on 16 October;NavTree, NavTreeSection, the composer triggers and UnreadDot joined on 2 October; BlockHandle and EditorBlockHandle (RIC-18) on 2 October, moveBlock and blockDropCursor, the drop in the gutter, on 5 October, MembersPill and MembersDialog, moved from Peek (SHI-31), on 6 October, ShowMore on 7 October, AppProvider on 8 October, and KindIcon, thingKindOf and PastedImages with its two helpers, moved from Peek, on 8 October; CodeBlockColours, the coloured code block of the editor, on 9 October; Checklist, Callout, isChecklistTick and calloutLook (RIC-19) on 13 October; EditorTableControls and its four actions (RIC-21) on 13 October; ReferenceCards, useReferenceCards and its three helpers, the card a chip in a document asks for, on 14 October; LinkChips and its two helpers, a URL in a document read as its chip, on 14 October; ReferenceMenu, ReferenceMenuView and three helpers, the menu of a chip while writing, on 14 October; PastedMarkdown, markdown pasted as the blocks it spells (LEAF-10), on 15 October; turnIntoRows, turnListInto and turnQuoteInto, the block menu’s Turn into for a list and a quote (LEAF-11), on 15 October)', () => {
51
+ it('counts 256 names over 131 files: 170 components, 78 helpers and 8 hooks (ListTable and ListTableRow, a list of things on a page under column headings, and ActivityLine, one thing that happened in a list of what is new, from the navigation prototype, on 16 November; useShortcut, a key that works from anywhere on the page, for Peek’s Ctrl/Cmd+O to Add to Open work (TOPI-7), on 10 November; CornerMenu, the "…" over a row’s or a card’s corner with Show as and Remove (TOPI-5), on 10 November; ConversationHeading, which place a comment is on in a list mixing several places (TOPI-2), on 9 November; FollowSwitch, LevelIcon and WhoFollowsDialog, how you follow a place and who follows it (TEA-6), on 6 November; goneWords and GONE_CLOSED, what stands in a gone comment’s place and under its thread in every app (ONE-9), on 6 November; DeletedNotice and NoAccessNotice, the cards on a deleted file and on one you cannot open (ALO-4), on 3 November; useFormBusy, whether a Form around it is sending, read by the editor’s DocumentField from the main entry, in the review of 2 November; useLeftAt, sendsInLayout, useSeenOnScreen, showInConversation and showInConversationWhenDrawn, where a conversation scrolls, what was seen and a link landing on a comment, moved from Peek for every app, on 2 November; useRememberedOpen, the fold a section remembers, read by the app, and NAV_TREE_PENDING_MS and isPlainClick, Peek’s Folder timer and plain-click check, moved in, on 2 November; FormDialog, MoveDialog and ArchiveDialog, the dialogs Peek wired by hand, on 2 November; ConversationPlace, the line saying where a comment was said, and DocumentField, a rich-text field of a form, moved from Peek, on 2 November; ArchivedNotice, the card on an archived file, from Peek, Ship and Leaf, on 31 October; caretOnOpen, the box at a thread’s foot taking the caret when a ConversationLayout opens it, without scrolling, on 31 October; the conversation from Peek for every app, with PageHeader and PinnedComment, on 31 October, and ResolutionNote and ResolutionHistory gone with the resolved looks not picked, on 1 November; useSidebarFold, a folded sidebar kept folded in every app, on 31 October; cardShapeMemory, a card’s last shape on this device, lifted from Peek and Ship for Leaf, and ReferenceCards and useReferenceCards gone with their deprecated page, in the widget review, on 30 October; inTheBox, a card or part in a box being written in, on the files’ fill and in words, on 29 October; archivedLine, the line on an archived file in every app (PEEKM-2), on 23 October; keepCommentBoxWarm, a box built ahead, exported as 0.84.0 promised (PEEKM-1), on 21 October;linkedFrom and linkStateFrom, one card for a file in every app (5ebf2756), on 21 October; ComposeBox, ComposeKeys and COMPOSE_EDITOR_CLASSES gone into CommentBox’s own frame (one box), on 21 October; LinkPlaces with linkPlaceAt and staysChip, a link in a document drawn where it sits (WBD-4), on 20 October; DocumentEditor, one document editor for every app, and PersonReference, `@` in a document (WBD-3), on 20 October; toggleTableHeaderRow, a table’s header row on and off (LEAF-12), on 19 October;EntryShell, the screen while nobody is signed in, moved from Peek (AUT-3), on 17 October; CommentBox with commentBoxRows, and ReactionRow with AddReactionButton and whoReacted, the shared comment box and reaction row (COMM-2), on 17 October; the link widgets — LinkChip, LinkRow, LinkCard, CardUnder, PartCard, LinkPreview and their parts, with useCanHover, chosenOf, loadingShapeOf and unavailableMemory — from the Widgets 2 prototype, on 16 October; InlineText, a title or the line under it edited where it stands (SUM-4), on 16 October; ComposeBox with ComposeKeys and its classes, CommentHighlights with its five helpers, and keepSelection and releaseSelection, from the Leaf prototype (LEAF-4), on 16 October;NavTree, NavTreeSection, the composer triggers and UnreadDot joined on 2 October; BlockHandle and EditorBlockHandle (RIC-18) on 2 October, moveBlock and blockDropCursor, the drop in the gutter, on 5 October, MembersPill and MembersDialog, moved from Peek (SHI-31), on 6 October, ShowMore on 7 October, AppProvider on 8 October, and KindIcon, thingKindOf and PastedImages with its two helpers, moved from Peek, on 8 October; CodeBlockColours, the coloured code block of the editor, on 9 October; Checklist, Callout, isChecklistTick and calloutLook (RIC-19) on 13 October; EditorTableControls and its four actions (RIC-21) on 13 October; ReferenceCards, useReferenceCards and its three helpers, the card a chip in a document asks for, on 14 October; LinkChips and its two helpers, a URL in a document read as its chip, on 14 October; ReferenceMenu, ReferenceMenuView and three helpers, the menu of a chip while writing, on 14 October; PastedMarkdown, markdown pasted as the blocks it spells (LEAF-10), on 15 October; turnIntoRows, turnListInto and turnQuoteInto, the block menu’s Turn into for a list and a quote (LEAF-11), on 15 October)', () => {
52
52
  // The reconciliation GATES.md §24 explains. If this changes, that changes.
53
53
  // The `EDITOR_EXTENSIONS` count as components by their names; they are
54
54
  // editor extensions, documented on SelectionToolbar's, BlockNodes' and
55
55
  // ComposerTriggers' pages.
56
56
  const kinds = registry.entries.reduce<Record<string, number>>((all, one) => ({ ...all, [one.kind]: (all[one.kind] ?? 0) + 1 }), {})
57
- expect(kinds).toEqual({ component: 167, helper: 78, hook: 8 })
58
- expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(129)
57
+ expect(kinds).toEqual({ component: 170, helper: 78, hook: 8 })
58
+ expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(131)
59
59
  })
60
60
 
61
61
  it('gives every entry a purpose, from its own page or from the comment above it', () => {
62
62
  expect(registry.entries.filter((one) => one.purpose.trim() === '')).toEqual([])
63
- expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(116)
64
- expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(137)
63
+ expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(118)
64
+ expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(138)
65
65
  })
66
66
 
67
67
  it('takes a name with a page of its own from the page, and a name without one from the code', () => {
@@ -0,0 +1,168 @@
1
+ // @vitest-environment jsdom
2
+ /**
3
+ * What the page claims (Katerina, 17 November): a list shows where the open page lives. Its current row is brought into
4
+ * the column's sight once it is drawn and shown, however late — a row a part inside the tree draws itself once its read
5
+ * lands (a team's Files fold), a plain list column's row (DMs, the Desk) — once per new current row, and never pulled
6
+ * back after the reader scrolls away.
7
+ */
8
+ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
9
+ import { act, cleanup, render } from '@testing-library/react'
10
+ import { useEffect, useState } from 'react'
11
+ import { ListColumn } from './ListColumn'
12
+ import { NavItem } from './NavItem'
13
+ import { NavTree } from './NavTree'
14
+ import { REVEAL_MS } from './revealCurrentRow'
15
+
16
+ afterEach(cleanup)
17
+ beforeEach(() => vi.useFakeTimers())
18
+ afterEach(() => vi.useRealTimers())
19
+
20
+ /**
21
+ * Lays out a 100px column that scrolls 1000px, with every row 32px tall, each `at` px down its list, and the rest at its
22
+ * top. `shut` rows are in a fold that is closed: 0px tall.
23
+ */
24
+ function lay(column: HTMLElement, at: Record<string, number>, shut: Set<string> = new Set()) {
25
+ let top = 0
26
+ Object.defineProperty(column, 'scrollHeight', { configurable: true, get: () => 1000 })
27
+ Object.defineProperty(column, 'clientHeight', { configurable: true, get: () => 100 })
28
+ Object.defineProperty(column, 'scrollTop', { configurable: true, get: () => top, set: (next: number) => (top = next) })
29
+ column.style.overflowY = 'auto'
30
+ const box = (y: number, height: number) => ({ top: y, bottom: y + height, height, left: 0, right: 0, width: 0, x: 0, y, toJSON: () => ({}) }) as DOMRect
31
+ const rect = vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function (this: HTMLElement) {
32
+ if (this === column) return box(0, 100)
33
+ const label = this.textContent?.trim() ?? ''
34
+ if (shut.has(label)) return box(0, 0)
35
+ return label in at ? box(at[label]! - top, 32) : box(0, 32)
36
+ })
37
+ return { scrolled: () => top, scroll: (to: number) => (top = to), restore: () => rect.mockRestore() }
38
+ }
39
+
40
+ /** Its rows a moment after it is drawn, as a fold that reads them once it opens: the tree is not drawn again for them. */
41
+ function LateRows({ open }: { open: string }) {
42
+ const [rows, setRows] = useState<string[] | null>(null)
43
+ useEffect(() => {
44
+ const timer = setTimeout(() => setRows(['Project 1', 'Project 2', 'Project 9']), 600)
45
+ return () => clearTimeout(timer)
46
+ }, [])
47
+ return <>{rows?.map((row) => <NavItem key={row} href={`#${row}`} label={row} active={row === open} />)}</>
48
+ }
49
+
50
+ describe('a tree brings its current row into sight', () => {
51
+ it('when a part inside it draws the row late, after its read lands (a team’s Files fold)', async () => {
52
+ const { getByTestId } = render(
53
+ <div data-testid="column">
54
+ <NavTree selected="p9">
55
+ <NavItem href="#team" label="Team" />
56
+ <LateRows open="Project 9" />
57
+ </NavTree>
58
+ </div>,
59
+ )
60
+ const layout = lay(getByTestId('column'), { 'Project 9': 900 })
61
+ try {
62
+ await act(async () => vi.advanceTimersByTime(REVEAL_MS + 10))
63
+ expect(layout.scrolled()).toBe(0)
64
+ // The read lands: its rows are drawn, the tree is not.
65
+ await act(async () => vi.advanceTimersByTime(600))
66
+ await act(async () => vi.advanceTimersByTime(REVEAL_MS + 10))
67
+ // Its bottom edge at the column's: 900 + 32 − 100.
68
+ expect(layout.scrolled()).toBe(832)
69
+ } finally {
70
+ layout.restore()
71
+ }
72
+ })
73
+
74
+ it('once: scrolled away from, it is not brought back while it stays the current row', async () => {
75
+ const { getByTestId, rerender } = render(
76
+ <div data-testid="column">
77
+ <NavTree selected="b">
78
+ <NavItem href="#a" label="Item a" />
79
+ <NavItem href="#b" label="Item b" active />
80
+ </NavTree>
81
+ </div>,
82
+ )
83
+ const layout = lay(getByTestId('column'), { 'Item b': 500 })
84
+ try {
85
+ await act(async () => vi.advanceTimersByTime(REVEAL_MS + 10))
86
+ expect(layout.scrolled()).toBe(432)
87
+ layout.scroll(0)
88
+ rerender(
89
+ <div data-testid="column">
90
+ <NavTree selected="b">
91
+ <NavItem href="#a" label="Item a (2)" />
92
+ <NavItem href="#b" label="Item b" active />
93
+ </NavTree>
94
+ </div>,
95
+ )
96
+ await act(async () => {})
97
+ await act(async () => vi.advanceTimersByTime(REVEAL_MS + 10))
98
+ expect(layout.scrolled()).toBe(0)
99
+ } finally {
100
+ layout.restore()
101
+ }
102
+ })
103
+
104
+ it('a row in a shut fold waits for the fold to open', async () => {
105
+ const shut = new Set(['Item b'])
106
+ const { getByTestId } = render(
107
+ <div data-testid="column">
108
+ <NavTree selected="b">
109
+ <NavItem href="#b" label="Item b" active />
110
+ </NavTree>
111
+ </div>,
112
+ )
113
+ const layout = lay(getByTestId('column'), { 'Item b': 500 }, shut)
114
+ try {
115
+ await act(async () => vi.advanceTimersByTime(REVEAL_MS + 10))
116
+ expect(layout.scrolled()).toBe(0)
117
+ // The fold opens: its content is shown, which changes the list.
118
+ shut.clear()
119
+ await act(async () => getByTestId('column').querySelector('a')!.setAttribute('hidden', ''))
120
+ await act(async () => getByTestId('column').querySelector('a')!.removeAttribute('hidden'))
121
+ await act(async () => vi.advanceTimersByTime(REVEAL_MS + 10))
122
+ expect(layout.scrolled()).toBe(432)
123
+ } finally {
124
+ layout.restore()
125
+ }
126
+ })
127
+ })
128
+
129
+ describe('a list column brings its current row into sight (DMs, the Desk)', () => {
130
+ function People({ open }: { open: string }) {
131
+ return (
132
+ <ListColumn title="DMs">
133
+ {Array.from({ length: 30 }, (_, i) => `Person ${i}`).map((name) => (
134
+ <NavItem key={name} href={`#${name}`} label={name} active={name === open} />
135
+ ))}
136
+ </ListColumn>
137
+ )
138
+ }
139
+ const viewport = () => document.querySelector<HTMLElement>('[data-id$="-viewport"]') ?? document.querySelector<HTMLElement>('[style*="overflow"]')!
140
+
141
+ it('its open row below the fold, and each new open row after it', async () => {
142
+ const { rerender } = render(<People open="Person 25" />)
143
+ const layout = lay(viewport(), { 'Person 25': 800, 'Person 2': 64 })
144
+ try {
145
+ await act(async () => vi.advanceTimersByTime(REVEAL_MS + 10))
146
+ expect(layout.scrolled()).toBe(732)
147
+ // Another opens, above: the column goes up to it.
148
+ rerender(<People open="Person 2" />)
149
+ // What changed in the list is heard first, then the look a moment later.
150
+ await act(async () => {})
151
+ await act(async () => vi.advanceTimersByTime(REVEAL_MS + 10))
152
+ expect(layout.scrolled()).toBe(64)
153
+ } finally {
154
+ layout.restore()
155
+ }
156
+ })
157
+
158
+ it('a row already in sight stays put', async () => {
159
+ render(<People open="Person 1" />)
160
+ const layout = lay(viewport(), { 'Person 1': 32 })
161
+ try {
162
+ await act(async () => vi.advanceTimersByTime(REVEAL_MS + 10))
163
+ expect(layout.scrolled()).toBe(0)
164
+ } finally {
165
+ layout.restore()
166
+ }
167
+ })
168
+ })