@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
@@ -46,6 +46,17 @@ describe('CollapsibleSection', () => {
46
46
  expect(title().getAttribute('aria-expanded')).toBe('true')
47
47
  })
48
48
 
49
+ it('shows its count beside the title, shut as well as open, in the count style rather than the title', () => {
50
+ render(
51
+ <CollapsibleSection title="Section" count={2} defaultOpen={false}>
52
+ {rows}
53
+ </CollapsibleSection>,
54
+ )
55
+ const count = screen.getByText('2')
56
+ expect(screen.getByText('Section').textContent).toBe('Section')
57
+ expect(count.className).not.toBe(screen.getByText('Section').className)
58
+ })
59
+
49
60
  it('starts closed with defaultOpen false', () => {
50
61
  render(<CollapsibleSection title="Section" defaultOpen={false}>{rows}</CollapsibleSection>)
51
62
  expect(title().getAttribute('aria-expanded')).toBe('false')
@@ -56,6 +56,11 @@ export interface CollapsibleSectionProps {
56
56
  icon?: ReactNode
57
57
  /** Beside the title and always visible, before the actions — a count. `SectionHeader`'s. */
58
58
  trailing?: ReactNode
59
+ /**
60
+ * How many rows it holds, 8px after the title, shown open or shut — `SectionHeader`'s. Written into the title by
61
+ * hand ("Other teams · 2"), the number took the heading's own type (Katerina, 16 November).
62
+ */
63
+ count?: number
59
64
  /** Beside the title, revealed while the row is hovered or keyboard-focused — `SectionHeader`'s. */
60
65
  actions?: SectionAction[]
61
66
  /** Beside the actions, revealed with them: the section's "More options" menu, `MenuItem`s — `SectionHeader`'s. */
@@ -158,7 +163,7 @@ export function useRememberedOpen(storageKey: string | undefined, fallback: bool
158
163
  return [choice ?? fallback, setOpen]
159
164
  }
160
165
 
161
- 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) {
166
+ export function CollapsibleSection({ title, defaultOpen = true, open: openProp, onOpenChange, pending = false, storageKey, openFor, icon, trailing, count, actions, menu, menuLabel, showActions, look = 'heading', indent = false, children, className, contentClassName }: CollapsibleSectionProps) {
162
167
  // The section's default is the one it was drawn with: a later `defaultOpen` does not move it.
163
168
  const [initial] = useState(defaultOpen)
164
169
  const [openState, remember] = useRememberedOpen(storageKey, initial)
@@ -173,7 +178,7 @@ export function CollapsibleSection({ title, defaultOpen = true, open: openProp,
173
178
  const shown = open && !pending
174
179
  return (
175
180
  <Collapsible.Root open={shown} onOpenChange={(next, details) => setOpen(pending && details.reason === 'trigger-press' ? !open : next)} className={cn('flex flex-col', className)}>
176
- <SectionHeader title={title} chevron icon={icon} isExpanded={open} trailing={trailing} actions={actions} menu={menu} menuLabel={menuLabel} showActions={showActions} look={look} className="shrink-0" render={<Collapsible.Trigger aria-expanded={open} aria-busy={pending && open ? true : undefined} />} />
181
+ <SectionHeader title={title} chevron icon={icon} isExpanded={open} trailing={trailing} {...(count != null ? { count } : {})} actions={actions} menu={menu} menuLabel={menuLabel} showActions={showActions} look={look} className="shrink-0" render={<Collapsible.Trigger aria-expanded={open} aria-busy={pending && open ? true : undefined} />} />
177
182
  {/* The slide: Base UI measures the panel and writes its height to a
178
183
  variable — `auto` again once the slide ends, so rows that arrive
179
184
  later are not clipped — and the panel is 0 high on its opening frame
@@ -22,6 +22,13 @@ with a hairline under it.
22
22
 
23
23
  <Canvas of={ContainerHeaderStories.WithTitleMenu} />
24
24
 
25
+ - `back`: a way back to the layer before — an arrow before the title, 8px
26
+ from it. The bar gives it its room (12px in), so its fill and its ring
27
+ stay whole: never pull a button of your own out of the bar with a
28
+ negative margin, where the bar cuts it off.
29
+
30
+ <Canvas of={ContainerHeaderStories.WithBack} />
31
+
25
32
  ## When not
26
33
 
27
34
  - One section inside a column → **SectionHeader**, the 32px row with a
@@ -35,6 +35,9 @@ export const WithTitleMenu: Story = {
35
35
  /** A string title, one line, alone. */
36
36
  export const Default: Story = {}
37
37
 
38
+ /** A way back to the layer before: an arrow before the title, 8px from it, the bar giving it its room. */
39
+ export const WithBack: Story = { args: { title: 'Add items', back: { label: 'Back to items', onClick: () => {} } } }
40
+
38
41
  /** A chevron after the title, for a title that opens something. */
39
42
  export const WithChevron: Story = { args: { title: 'All items', chevron: true } }
40
43
 
@@ -5,7 +5,7 @@
5
5
  * buttons sit at the right edge. The pixels are proved against Peek's own
6
6
  * (docs/GATES.md, UIG-13: A).
7
7
  */
8
- import { afterEach, describe, expect, it } from 'vitest'
8
+ import { afterEach, describe, expect, it, vi } from 'vitest'
9
9
  import { cleanup, render, screen } from '@testing-library/react'
10
10
  import userEvent from '@testing-library/user-event'
11
11
  import { MenuItem } from './Menu'
@@ -14,6 +14,17 @@ import { ContainerHeader } from './ContainerHeader'
14
14
  afterEach(cleanup)
15
15
 
16
16
  describe('ContainerHeader', () => {
17
+ it('draws its way back before the title, outside the title’s clipping box, with no negative margin', async () => {
18
+ const onClick = vi.fn()
19
+ render(<ContainerHeader title="Add items" back={{ label: 'Back to items', onClick }} />)
20
+ const button = screen.getByRole('button', { name: 'Back to items' })
21
+ // Its fill and ring were cut off when it sat inside the box that clips the title, pulled out by -ml-2 (16 November).
22
+ expect(button.closest('.overflow-hidden')?.className).toContain('h-12')
23
+ expect(button.className).not.toMatch(/-m[lx]-/)
24
+ await userEvent.click(button)
25
+ expect(onClick).toHaveBeenCalledOnce()
26
+ })
27
+
17
28
  it('is the 48px bar with a hairline under it', () => {
18
29
  const { container } = render(<ContainerHeader title="Items" />)
19
30
  const bar = container.firstElementChild!.className.split(' ')
@@ -1,7 +1,8 @@
1
1
  import type { ReactNode } from 'react'
2
- import { IconChevronDown } from '@tabler/icons-react'
2
+ import { IconArrowLeft, IconChevronDown } from '@tabler/icons-react'
3
3
  import { Button as BaseButton } from '@base-ui/react/button'
4
4
  import { cn } from './cn'
5
+ import { IconButton } from './IconButton'
5
6
  import { MENU_TRIGGER_CLASSES } from './looks'
6
7
  import { Menu } from './Menu'
7
8
 
@@ -31,10 +32,16 @@ export interface ContainerHeaderProps {
31
32
  titleMenu?: ReactNode
32
33
  /** The column's own buttons, at the right edge: IconButtons with tooltips, 4px apart. */
33
34
  actions?: ReactNode
35
+ /**
36
+ * A way back to the layer before, an arrow before the title, 8px from it — a dialog's Add members back to its list.
37
+ * The bar gives the button its room (12px in, so the arrow sits 16px in, where a title would) rather than the button
38
+ * reaching out of it with a negative margin, which cut its fill and its ring off (Katerina, 16 November).
39
+ */
40
+ back?: { label: string; onClick: () => void }
34
41
  className?: string
35
42
  }
36
43
 
37
- export function ContainerHeader({ title, chevron = false, titleMenu, actions, className }: ContainerHeaderProps) {
44
+ export function ContainerHeader({ title, chevron = false, titleMenu, actions, back, className }: ContainerHeaderProps) {
38
45
  const text = typeof title === 'string'
39
46
  const name = (
40
47
  <div className={cn('flex items-center gap-1', text ? 'shrink-0' : 'min-w-0 flex-1')}>
@@ -42,6 +49,23 @@ export function ContainerHeader({ title, chevron = false, titleMenu, actions, cl
42
49
  {(chevron || titleMenu != null) && <IconChevronDown size={12} stroke={1.5} className="shrink-0 text-text-secondary" />}
43
50
  </div>
44
51
  )
52
+ const titleBox = (
53
+ <div className={cn('flex items-center gap-2 overflow-hidden', text && !back ? 'shrink-0' : 'min-w-0 flex-1')}>
54
+ {titleMenu != null ? (
55
+ <Menu
56
+ trigger={
57
+ <BaseButton type="button" className={cn('flex min-w-0 items-center px-1.5 py-1', MENU_TRIGGER_CLASSES)}>
58
+ {name}
59
+ </BaseButton>
60
+ }
61
+ >
62
+ {titleMenu}
63
+ </Menu>
64
+ ) : (
65
+ name
66
+ )}
67
+ </div>
68
+ )
45
69
  return (
46
70
  // The title 16px in, where the column's content starts (Katerina, 7 October; it was 20px).
47
71
  // With a title menu the bar gives the button 6px of its left padding
@@ -50,22 +74,18 @@ export function ContainerHeader({ title, chevron = false, titleMenu, actions, cl
50
74
  // (Katerina, 5 October).
51
75
  // 12px between the title and the buttons, as between the right group's own parts: a cut title, and a button
52
76
  // after it, ran right up to them (Leaf's adoption review, 4 November). A bar whose title fits does not move.
53
- <div className={cn('flex h-12 shrink-0 items-center justify-between gap-3 overflow-hidden border-b border-border-subtle py-2 pr-4', titleMenu != null ? 'pl-2.5' : 'pl-4', className)}>
54
- <div className={cn('flex items-center gap-2 overflow-hidden', text ? 'shrink-0' : 'min-w-0 flex-1')}>
55
- {titleMenu != null ? (
56
- <Menu
57
- trigger={
58
- <BaseButton type="button" className={cn('flex min-w-0 items-center px-1.5 py-1', MENU_TRIGGER_CLASSES)}>
59
- {name}
60
- </BaseButton>
61
- }
62
- >
63
- {titleMenu}
64
- </Menu>
65
- ) : (
66
- name
67
- )}
68
- </div>
77
+ <div className={cn('flex h-12 shrink-0 items-center justify-between gap-3 overflow-hidden border-b border-border-subtle py-2 pr-4', back ? 'pl-3' : titleMenu != null ? 'pl-2.5' : 'pl-4', className)}>
78
+ {back ? (
79
+ // The arrow outside the title's box, which clips: its fill and its ring stay whole; 8px to the title.
80
+ <div className="flex min-w-0 flex-1 items-center gap-2">
81
+ <IconButton tooltip={back.label} aria-label={back.label} onClick={back.onClick}>
82
+ <IconArrowLeft size={16} stroke={1.5} />
83
+ </IconButton>
84
+ {titleBox}
85
+ </div>
86
+ ) : (
87
+ titleBox
88
+ )}
69
89
  {actions && (
70
90
  <div className="flex shrink-0 items-center justify-end gap-3">
71
91
  <div className="flex shrink-0 items-center gap-1">{actions}</div>
@@ -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)
@@ -16,8 +16,14 @@ footer for the buttons. A dialog is just what goes in the three slots.
16
16
  - Anything with a title, a body, and buttons: a form, a picker, a roster.
17
17
  - `footer` absent removes the footer row entirely — a list that simply
18
18
  ends keeps the card's own bottom edge.
19
- - `headerContent` replaces the title text — a back button beside the
20
- title, a count chip after it. The close button stays.
19
+ - `headerContent` replaces the title text — a count chip after the
20
+ title. The close button stays.
21
+ - `back`: a second layer's way back to its first (Add members back to the
22
+ list) — an arrow before the title, the bar's own. Never a button of your
23
+ own in `headerContent`: pulled out of the bar's box, its fill and ring
24
+ were cut off.
25
+
26
+ <Canvas of={DialogShellStories.WithBack} />
21
27
 
22
28
  ## When not
23
29
 
@@ -1,10 +1,8 @@
1
1
  import type { Meta, StoryObj } from '@storybook/react-vite'
2
2
  import { useState } from 'react'
3
- import { IconArrowLeft } from '@tabler/icons-react'
4
3
  import { Button } from './Button'
5
4
  import { Chip } from './Chip'
6
5
  import { DialogShell } from './DialogShell'
7
- import { IconButton } from './IconButton'
8
6
  import { Field } from './Field'
9
7
  import { Form } from './Form'
10
8
  import { TextInput } from './TextInput'
@@ -72,8 +70,8 @@ export const ALongTitle: Story = {
72
70
  }
73
71
 
74
72
  /**
75
- * **`headerContent` replaces the title text** — a back button beside it, a
76
- * count after it — and the ✕ stays. The dialog is then named by its `title`
73
+ * **`headerContent` replaces the title text** — a count after it — and the
74
+ * ✕ stays. The dialog is then named by its `title`
77
75
  * anyway, since there is no longer a heading to point at.
78
76
  *
79
77
  * There used to be a `Confirmation` story here. It hand-built what
@@ -88,9 +86,6 @@ export const WithHeaderContent: Story = {
88
86
  args: {
89
87
  headerContent: (
90
88
  <div className="flex items-center gap-2">
91
- <IconButton aria-label="Back" tooltip="Back">
92
- <IconArrowLeft size={16} stroke={1.5} />
93
- </IconButton>
94
89
  <span className="text-h4 text-text-primary">Item one</span>
95
90
  <Chip label="3" />
96
91
  </div>
@@ -105,6 +100,24 @@ export const WithHeaderContent: Story = {
105
100
  },
106
101
  }
107
102
 
103
+ /**
104
+ * **A way back**, a second layer to its first: the bar's own arrow before the title, 16px in, its fill and ring whole.
105
+ * Point at it.
106
+ */
107
+ export const WithBack: Story = {
108
+ args: {
109
+ title: 'Add items',
110
+ back: { label: 'Back to items', onClick: () => {} },
111
+ footer: (
112
+ <>
113
+ <Button variant="muted">Cancel</Button>
114
+ <Button variant="primary">Add</Button>
115
+ </>
116
+ ),
117
+ children: <p className="text-body-2 text-text-primary">The layer under the first one.</p>,
118
+ },
119
+ }
120
+
108
121
  /**
109
122
  * **No footer.** The body keeps the card's own bottom edge — a roster, a list,
110
123
  * anything that simply ends rather than asking a question. There is no divider
@@ -36,9 +36,14 @@ export interface DialogShellProps {
36
36
  * unless `headerContent` replaces it. */
37
37
  title: string
38
38
  onClose: () => void
39
- /** Replaces the title text in the header — a back button beside the title,
40
- * a count chip after it. The close button stays. */
39
+ /** Replaces the title text in the header — a count chip after it. The
40
+ * close button stays. A way back is `back`, never drawn in here. */
41
41
  headerContent?: ReactNode
42
+ /**
43
+ * A way back to the layer before — an Add layer back to its list: an arrow before the title, the bar's own, whole
44
+ * (it was the dialog's own button pulled 8px out of the bar's box, its fill and ring cut off; Katerina, 16 November).
45
+ */
46
+ back?: { label: string; onClick: () => void }
42
47
  /** Absent: no footer row, and the body keeps the card's own bottom edge
43
48
  * (a roster that simply ends). */
44
49
  footer?: ReactNode
@@ -67,7 +72,7 @@ export interface DialogShellProps {
67
72
  alert?: boolean
68
73
  }
69
74
 
70
- export function DialogShell({ title, onClose, headerContent, footer, children, bodyClassName, bodyMaxHeight, width = 502, alert = false }: DialogShellProps) {
75
+ export function DialogShell({ title, onClose, back, headerContent, footer, children, bodyClassName, bodyMaxHeight, width = 502, alert = false }: DialogShellProps) {
71
76
  // The two families are the same parts with different dismiss rules, so the
72
77
  // chrome below is written once. AlertDialog re-exports Dialog's Backdrop,
73
78
  // Popup, Portal and Title types, which is why this substitutes cleanly.
@@ -119,8 +124,9 @@ export function DialogShell({ title, onClose, headerContent, footer, children, b
119
124
  The title keeps to its one line and ends in "…": a long name wrapped to
120
125
  two lines in the 48px bar and lost its top (Katerina, 1 October). */}
121
126
  {/* `pl-5`: a dialog's title stays 20px in, over its body and footer, which are. */}
127
+ {/* With a way back, the bar's own: the arrow 16px in, the title 8px after it (ContainerHeader's `back`). */}
122
128
  <ContainerHeader
123
- className="pl-5"
129
+ {...(back ? { back } : { className: 'pl-5' })}
124
130
  title={
125
131
  headerContent ?? (
126
132
  <Parts.Title className="block truncate text-h4 text-text-primary" render={<span />}>
@@ -86,6 +86,7 @@ It does these by itself. Write none of them around it.
86
86
  |---|---|---|
87
87
  | Draws the column: 290px, a line on its right, and a ContainerHeader on top | a width, a border and a header row of your own | |
88
88
  | Scrolls its rows in a ScrollArea, 16px under the header, 12px in from each side | `overflow-auto`, or padding of your own around the rows | |
89
+ | Brings the open page's row (a **NavItem** that is `active`) into sight once it is drawn, however late, once for each new open page, and never pulls it back after the reader scrolls away | an effect that finds the active row and scrolls it into view | |
89
90
  | Closes with the rail when `collapsed`: narrows to nothing and fades | a width transition of your own | |
90
91
  | Keeps its 290px beside a main area that grows | `shrink-0` | |
91
92
  | Keeps a crash inside itself: its title stays, the message and Try again sit in the middle of the room the list had | an error boundary of your own around it | |
@@ -1,6 +1,6 @@
1
1
  import type { Meta, StoryObj } from '@storybook/react-vite'
2
2
  import { IconSortDescending, IconSquareRounded } from '@tabler/icons-react'
3
- import { useState } from 'react'
3
+ import { useEffect, useState } from 'react'
4
4
  import { Button } from './Button'
5
5
  import { CollapsibleSection } from './CollapsibleSection'
6
6
  import { Divider } from './Divider'
@@ -117,6 +117,58 @@ export const ManyRows: Story = {
117
117
  render: (args) => <ListColumn {...args}>{rows(80)}</ListColumn>,
118
118
  }
119
119
 
120
+ /** 80 rows, the open one at `open`: a click on a row opens it instead. */
121
+ function OpenRows({ open: first, late = false }: { open: number; late?: boolean }) {
122
+ const [open, setOpen] = useState(first)
123
+ const [drawn, setDrawn] = useState(!late)
124
+ useEffect(() => {
125
+ if (!late) return
126
+ const timer = setTimeout(() => setDrawn(true), 1200)
127
+ return () => clearTimeout(timer)
128
+ }, [late])
129
+ if (!drawn) return <SkeletonList rows={8} />
130
+ return (
131
+ <>
132
+ {Array.from({ length: 80 }, (_, i) => (
133
+ <NavItem
134
+ key={i}
135
+ href="#"
136
+ label={`Item ${i + 1}`}
137
+ icon={icon}
138
+ active={i === open}
139
+ onClick={(event) => {
140
+ event.preventDefault()
141
+ setOpen(i)
142
+ }}
143
+ />
144
+ ))}
145
+ </>
146
+ )
147
+ }
148
+
149
+ /**
150
+ * Arriving on a page whose row is far down the list (a link, a card, another app): the column shows where it lives,
151
+ * bringing Item 62 into sight. Scroll away and it stays where you put it; open another row and that one is in sight.
152
+ */
153
+ export const OpenRowFarDown: Story = {
154
+ args: { title: 'Items' },
155
+ render: (args) => (
156
+ <ListColumn {...args}>
157
+ <OpenRows open={61} />
158
+ </ListColumn>
159
+ ),
160
+ }
161
+
162
+ /** The same, its rows read a moment after the column is drawn, as a list whose read is still out: Item 62 is brought into sight once it is drawn. */
163
+ export const OpenRowDrawnLate: Story = {
164
+ args: { title: 'Items' },
165
+ render: (args) => (
166
+ <ListColumn {...args}>
167
+ <OpenRows open={61} late />
168
+ </ListColumn>
169
+ ),
170
+ }
171
+
120
172
  /** While the list is on its way: a skeleton shaped like the rows. */
121
173
  export const Loading: Story = {
122
174
  args: { title: 'Items' },
@@ -1,5 +1,6 @@
1
- import type { ReactNode } from 'react'
1
+ import { useRef, type ReactNode } from 'react'
2
2
  import { cn } from './cn'
3
+ import { useRevealCurrentRow } from './revealCurrentRow'
3
4
  import { ContainerHeader } from './ContainerHeader'
4
5
  import { ErrorBoundary } from './ErrorBoundary'
5
6
  import { FOLDED_CLASSES, FOLD_MOTION_CLASSES, UNFOLDED_CLASSES } from './looks'
@@ -21,6 +22,11 @@ import { ScrollArea } from './ScrollArea'
21
22
  * eight mistakes on the page that led to UIG-15: the frame's card clips, so a
22
23
  * list that grew past the fold was simply cut off, with nothing to scroll.
23
24
  *
25
+ * It shows where the open page lives: its row (a `NavItem` that is `active`)
26
+ * is brought into sight once it is drawn, however late, once for each new open
27
+ * page, and never pulled back after the reader scrolls away (Katerina, 17
28
+ * November: the selected row "could be somewhere above or below the fold").
29
+ *
24
30
  * It keeps a crash inside itself (D1, D3): if its rows, its actions or the row
25
31
  * above break, the column keeps its title and shows `ErrorBoundary`'s message
26
32
  * in the middle of the room the list had, and the rest of the page keeps working.
@@ -50,6 +56,8 @@ export interface ListColumnProps {
50
56
  }
51
57
 
52
58
  function Column({ title, chevron = false, titleMenu, actions, above, collapsed = false, children, className, broken = false }: ListColumnProps & { broken?: boolean }) {
59
+ const rows = useRef<HTMLDivElement>(null)
60
+ useRevealCurrentRow(rows)
53
61
  return (
54
62
  <div
55
63
  className={cn(
@@ -69,7 +77,7 @@ function Column({ title, chevron = false, titleMenu, actions, above, collapsed =
69
77
  // The message takes the room the list had and centres itself in it (Katerina, 19 September).
70
78
  <div className="flex min-h-0 flex-1 flex-col px-3">{children}</div>
71
79
  ) : (
72
- <ScrollArea className="flex-1" contentClassName="flex flex-col gap-0.5 px-3 pt-4 pb-3">
80
+ <ScrollArea className="flex-1" viewportRef={rows} contentClassName="flex flex-col gap-0.5 px-3 pt-4 pb-3">
73
81
  {children}
74
82
  </ScrollArea>
75
83
  )}