@estiva-app/ui 0.115.1 → 0.117.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 (48) hide show
  1. package/dist/MembersDialog.d.ts +1 -0
  2. package/dist/MembersDialog.d.ts.map +1 -1
  3. package/dist/Menu.d.ts +9 -2
  4. package/dist/Menu.d.ts.map +1 -1
  5. package/dist/NavItem.d.ts +12 -2
  6. package/dist/NavItem.d.ts.map +1 -1
  7. package/dist/PreviewCard.d.ts +9 -1
  8. package/dist/PreviewCard.d.ts.map +1 -1
  9. package/dist/SectionHeader.d.ts.map +1 -1
  10. package/dist/UnreadDot.d.ts +12 -1
  11. package/dist/UnreadDot.d.ts.map +1 -1
  12. package/dist/WhoFollowsDialog.d.ts +12 -2
  13. package/dist/WhoFollowsDialog.d.ts.map +1 -1
  14. package/dist/eslint/index.js +3 -2
  15. package/dist/eslint/index.js.map +2 -2
  16. package/dist/eslint/no-restyled-part.d.ts.map +1 -1
  17. package/dist/index.d.ts +1 -1
  18. package/dist/index.d.ts.map +1 -1
  19. package/dist/index.js +434 -378
  20. package/dist/index.js.map +4 -4
  21. package/package.json +1 -1
  22. package/registry.json +54 -3
  23. package/src/FollowSwitch.test.tsx +6 -4
  24. package/src/MembersDialog.tsx +1 -1
  25. package/src/Menu.mdx +3 -0
  26. package/src/Menu.stories.tsx +23 -0
  27. package/src/Menu.tsx +13 -3
  28. package/src/NavItem.mdx +16 -2
  29. package/src/NavItem.stories.tsx +23 -0
  30. package/src/NavItem.test.tsx +46 -1
  31. package/src/NavItem.tsx +20 -5
  32. package/src/PreviewCard.mdx +7 -3
  33. package/src/PreviewCard.test.tsx +107 -0
  34. package/src/PreviewCard.tsx +22 -2
  35. package/src/SectionHeader.mdx +2 -0
  36. package/src/SectionHeader.test.tsx +16 -0
  37. package/src/SectionHeader.tsx +4 -2
  38. package/src/UnreadDot.mdx +7 -1
  39. package/src/UnreadDot.stories.tsx +3 -0
  40. package/src/UnreadDot.test.tsx +16 -9
  41. package/src/UnreadDot.tsx +23 -3
  42. package/src/WhoFollowsDialog.mdx +2 -0
  43. package/src/WhoFollowsDialog.stories.tsx +19 -0
  44. package/src/WhoFollowsDialog.test.tsx +40 -0
  45. package/src/WhoFollowsDialog.tsx +66 -10
  46. package/src/eslint/no-restyled-part.ts +2 -1
  47. package/src/index.ts +1 -1
  48. package/stories/Choosing.mdx +2 -2
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@estiva-app/ui",
3
- "version": "0.115.1",
3
+ "version": "0.117.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,9 +4,9 @@
4
4
  "kind": "package",
5
5
  "repo": "estiva-ui",
6
6
  "package": "@estiva-app/ui",
7
- "packageVersion": "0.115.1",
7
+ "packageVersion": "0.117.0",
8
8
  "exports": 253,
9
- "typeExports": 263,
9
+ "typeExports": 264,
10
10
  "files": null
11
11
  },
12
12
  "storybook": {
@@ -7079,6 +7079,12 @@
7079
7079
  "required": false,
7080
7080
  "note": "Before the label: a 16px icon (stroke 1.5, secondary), or an Avatar, for rows led by a face."
7081
7081
  },
7082
+ {
7083
+ "name": "leadingAt",
7084
+ "takes": "center | top",
7085
+ "required": false,
7086
+ "note": "Where `leading` sits on a row of two lines: beside the first line, or centred on the whole row."
7087
+ },
7082
7088
  {
7083
7089
  "name": "trailing",
7084
7090
  "takes": "anything",
@@ -7129,6 +7135,13 @@
7129
7135
  "default",
7130
7136
  "tall"
7131
7137
  ]
7138
+ },
7139
+ {
7140
+ "prop": "leadingAt",
7141
+ "values": [
7142
+ "center",
7143
+ "top"
7144
+ ]
7132
7145
  }
7133
7146
  ],
7134
7147
  "ownsBehaviours": [
@@ -7660,12 +7673,24 @@
7660
7673
  "required": false,
7661
7674
  "note": "With `unread`: the warning badge in the dot's place."
7662
7675
  },
7676
+ {
7677
+ "name": "unreadTone",
7678
+ "takes": "UnreadDotTone",
7679
+ "required": false,
7680
+ "note": "With `unread`: which kind of new the dot is, `UnreadDot`'s `tone`."
7681
+ },
7663
7682
  {
7664
7683
  "name": "preview",
7665
7684
  "takes": "anything",
7666
7685
  "required": false,
7667
7686
  "note": "More about the row, in the package's `PreviewCard` while the row itself is pointed at — never the rows under it — such as a short list of what is new there."
7668
7687
  },
7688
+ {
7689
+ "name": "onPreviewOpenChange",
7690
+ "takes": "a handler",
7691
+ "required": false,
7692
+ "note": "With `preview`: told each time the card opens (`true`) and closes (`false`), once each — `PreviewCard`'s `onOpenChange`."
7693
+ },
7669
7694
  {
7670
7695
  "name": "children",
7671
7696
  "takes": "anything",
@@ -8738,6 +8763,12 @@
8738
8763
  "takes": "true/false",
8739
8764
  "required": false,
8740
8765
  "note": "A tap on the trigger opens the card, and a second tap closes it, for a touch screen, where nothing hovers (ACT-4: the dot beside a page's title)."
8766
+ },
8767
+ {
8768
+ "name": "onOpenChange",
8769
+ "takes": "a handler",
8770
+ "required": false,
8771
+ "note": "Called once each time the card opens (`true`) and once each time it closes (`false`), however it got there: a pointer resting, keyboard focus, a tap with `openOnTap`, Escape, a press outside, or the card unmounted while open."
8741
8772
  }
8742
8773
  ],
8743
8774
  "variants": [
@@ -12373,9 +12404,23 @@
12373
12404
  "takes": "true/false",
12374
12405
  "required": false,
12375
12406
  "note": null
12407
+ },
12408
+ {
12409
+ "name": "tone",
12410
+ "takes": "blue | reaction",
12411
+ "required": false,
12412
+ "note": null
12413
+ }
12414
+ ],
12415
+ "variants": [
12416
+ {
12417
+ "prop": "tone",
12418
+ "values": [
12419
+ "blue",
12420
+ "reaction"
12421
+ ]
12376
12422
  }
12377
12423
  ],
12378
- "variants": [],
12379
12424
  "ownsBehaviours": [],
12380
12425
  "status": "stable",
12381
12426
  "migrationStage": null,
@@ -12659,6 +12704,12 @@
12659
12704
  "required": false,
12660
12705
  "note": "Adds the people chosen. With it, the \"Add someone\" row shows and opens the same add layer as `MembersDialog`'s."
12661
12706
  },
12707
+ {
12708
+ "name": "self",
12709
+ "takes": "a handler",
12710
+ "required": false,
12711
+ "note": "The viewer's own Join or Leave, as `MembersDialog`'s: Leave on their own row, which comes first in its group; with no row of their own (not in it, or in it at no level shown here), Join or Leave on top, beside \"Add someone\"."
12712
+ },
12662
12713
  {
12663
12714
  "name": "initialView",
12664
12715
  "takes": "list | add",
@@ -112,13 +112,15 @@ describe('WhoFollowsDialog', () => {
112
112
  it('lists All then Important with their counts, and Nobody for an empty group', async () => {
113
113
  const { rerender } = render(<WhoFollowsDialog title="Item one" all={all} important={important} onClose={() => {}} />)
114
114
  const dialog = await screen.findByRole('dialog', { name: 'Who follows Item one' })
115
+ // Each group is a SectionHeader: its title, then its count beside it (no "·" between them in the text).
115
116
  const text = dialog.textContent!
116
- expect(text.indexOf('All · 1')).toBeLessThan(text.indexOf('Ana Duarte'))
117
- expect(text.indexOf('Ana Duarte')).toBeLessThan(text.indexOf('Important · 1'))
118
- expect(text.indexOf('Important · 1')).toBeLessThan(text.indexOf('Ravi Mehta'))
117
+ expect(text.indexOf('All1')).toBeGreaterThan(-1)
118
+ expect(text.indexOf('All1')).toBeLessThan(text.indexOf('Ana Duarte'))
119
+ expect(text.indexOf('Ana Duarte')).toBeLessThan(text.indexOf('Important1'))
120
+ expect(text.indexOf('Important1')).toBeLessThan(text.indexOf('Ravi Mehta'))
119
121
  expect(text).toContain('Added by Ana Duarte')
120
122
  rerender(<WhoFollowsDialog title="Item one" all={[]} important={important} onClose={() => {}} />)
121
- expect((await screen.findByRole('dialog')).textContent).toContain('All · 0Nobody')
123
+ expect((await screen.findByRole('dialog')).textContent).toContain('All0Nobody')
122
124
  })
123
125
 
124
126
  it('offers Add someone only with onAdd, and leaves everyone listed out of the picker', async () => {
@@ -65,7 +65,7 @@ export interface MembersDialogProps {
65
65
  }
66
66
 
67
67
  // The icon in the accent as text: Ship's button blue read at 2.7:1 on its grey square (Katerina, 8 October).
68
- const LEADING_CLASSES = 'size-8 rounded-md bg-accent-muted flex items-center justify-center shrink-0 text-accent-text'
68
+ export const LEADING_CLASSES = 'size-8 rounded-md bg-accent-muted flex items-center justify-center shrink-0 text-accent-text'
69
69
 
70
70
  /** One person in a roster: a face, a name, a second line, and an optional control at the end. Shared with `WhoFollowsDialog`. */
71
71
  export function RosterRow({ member, trailing }: { member: MembersDialogMember; trailing?: ReactNode }) {
package/src/Menu.mdx CHANGED
@@ -28,6 +28,9 @@ definition either way.
28
28
  - A picker fed by typing: rows are `MenuItem size="tall"` — content height
29
29
  with a 40px floor, room for a 32px face via `leading` and a `description`
30
30
  line — with an `EnterHint` on the highlighted row.
31
+ - A row of two lines (a `description`) has its icon beside the first line, not centred
32
+ between the two; a tall row's face stays centred (`leadingAt` says either).
33
+ <Canvas of={MenuStories.TwoLines} />
31
34
  - Grouped choices where one is current: `MenuSection` over rows, `selected`
32
35
  on the chosen one.
33
36
 
@@ -46,6 +46,29 @@ export const Items: Story = {
46
46
  ),
47
47
  }
48
48
 
49
+ /** Rows of two lines: the icon beside the first line, a row with a `description` by default (Katerina, 16 November);
50
+ * `leadingAt="center"` keeps it centred on the whole row, and a row whose `children` run to two lines passes
51
+ * `leadingAt="top"`. */
52
+ export const TwoLines: Story = {
53
+ parameters: { controls: { disable: true } },
54
+ render: () => (
55
+ <MenuPanel className="w-80">
56
+ <MenuSection label="Section">
57
+ <MenuItem label="Item one" description="A second line that says more about it" leading={icon(IconSquareRounded)} onClick={() => {}} />
58
+ <MenuItem label="Item two" description="A second line that says more about it" leading={icon(IconSquareRounded)} selected onClick={() => {}} />
59
+ <MenuItem label="Item three" description="leadingAt center: the icon centred on both lines" leading={icon(IconSquareRounded)} leadingAt="center" onClick={() => {}} />
60
+ </MenuSection>
61
+ <MenuSeparator />
62
+ <MenuItem leading={icon(IconSquareRounded)} leadingAt="top" onClick={() => {}}>
63
+ <span className="flex min-w-0 flex-1 flex-col">
64
+ <span className="truncate text-body-2 text-text-primary">Item four</span>
65
+ <span className="truncate text-caption text-text-secondary">Its children run to a second line</span>
66
+ </span>
67
+ </MenuItem>
68
+ </MenuPanel>
69
+ ),
70
+ }
71
+
49
72
  /** Groups under headings, with a divider between them. The divider runs the
50
73
  * width of the rows it separates, not the width of the panel's text. */
51
74
  export const Sections: Story = {
package/src/Menu.tsx CHANGED
@@ -359,6 +359,13 @@ export interface MenuItemProps extends Omit<ComponentPropsWithRef<'button'>, 'ch
359
359
  aside?: string
360
360
  /** Before the label: a 16px icon (stroke 1.5, secondary), or an Avatar, for rows led by a face. */
361
361
  leading?: ReactNode
362
+ /**
363
+ * Where `leading` sits on a row of two lines: beside the first line, or centred on the whole row. Default: beside the
364
+ * first line on a default-size row with a `description` (Katerina, 16 November: an icon centred between two lines
365
+ * belongs to neither); centred otherwise, as a tall row's face is. A row whose `children` run to two lines passes
366
+ * `top`.
367
+ */
368
+ leadingAt?: 'center' | 'top'
362
369
  /** At the right edge: a hint, a value — anything. Wins over `shortcut` and `submenu`. */
363
370
  trailing?: ReactNode
364
371
  /**
@@ -442,9 +449,10 @@ export function menuItemClassName({ size, selected, shut = false, className }: {
442
449
  /** Everything inside the row — written once, for the same reason. Shared
443
450
  * inside the package like `menuItemClassName`: `CommandPalette` draws it
444
451
  * inside Base UI's `Autocomplete.Item`. Not exported from the index. */
445
- export function MenuItemBody({ label, children, size = 'default', description, aside, leading, trailing, hint, shortcut, submenu, destructive, selected, shut = false }: Pick<MenuItemProps, 'label' | 'children' | 'size' | 'description' | 'aside' | 'leading' | 'trailing' | 'hint' | 'shortcut' | 'submenu' | 'destructive' | 'selected'> & { shut?: boolean }) {
452
+ export function MenuItemBody({ label, children, size = 'default', description, aside, leading, leadingAt, trailing, hint, shortcut, submenu, destructive, selected, shut = false }: Pick<MenuItemProps, 'label' | 'children' | 'size' | 'description' | 'aside' | 'leading' | 'leadingAt' | 'trailing' | 'hint' | 'shortcut' | 'submenu' | 'destructive' | 'selected'> & { shut?: boolean }) {
446
453
  // Shut, its words in the disabled colour, a destructive one's too.
447
454
  const labelColour = shut ? 'text-text-disabled' : destructive ? 'text-error-default' : 'text-text-primary'
455
+ const firstLine = (leadingAt ?? (size === 'default' && description ? 'top' : 'center')) === 'top'
448
456
  const edge =
449
457
  trailing ??
450
458
  (shortcut ? (
@@ -454,7 +462,8 @@ export function MenuItemBody({ label, children, size = 'default', description, a
454
462
  ) : null)
455
463
  return (
456
464
  <>
457
- {leading && <span className="flex shrink-0 items-center">{leading}</span>}
465
+ {/* Beside the first line: the 20px of a body-2 line, from the row's top, so a 16px icon is centred on that line. */}
466
+ {leading && <span className={cn('flex shrink-0 items-center', firstLine && 'h-5 self-start')}>{leading}</span>}
458
467
  {/* Sizes are arbitrary values (the body-2 and caption tokens): these
459
468
  lists merge with a colour, and tw-merge drops a token size beside a
460
469
  colour. Ship's copy said `text-sm`, which was never the ramp. */}
@@ -495,7 +504,7 @@ export function MenuItemBody({ label, children, size = 'default', description, a
495
504
  )
496
505
  }
497
506
 
498
- export function MenuItem({ label, children, size = 'default', description, aside, leading, trailing, hint, shortcut, submenu, destructive, selected, disabledReason, className, ...props }: MenuItemProps) {
507
+ export function MenuItem({ label, children, size = 'default', description, aside, leading, leadingAt, trailing, hint, shortcut, submenu, destructive, selected, disabledReason, className, ...props }: MenuItemProps) {
499
508
  const shut = !!disabledReason
500
509
  const body = (
501
510
  <MenuItemBody
@@ -504,6 +513,7 @@ export function MenuItem({ label, children, size = 'default', description, aside
504
513
  description={description}
505
514
  aside={aside}
506
515
  leading={leading}
516
+ {...(leadingAt ? { leadingAt } : {})}
507
517
  trailing={trailing}
508
518
  hint={hint}
509
519
  shortcut={shortcut}
package/src/NavItem.mdx CHANGED
@@ -27,6 +27,8 @@ count — a muted mono number whose tooltip says what it counts.
27
27
  is pointed at or keyboard-focused, and moves the count aside for it. On a
28
28
  screen with no hover the ⋮ always shows, and the count or dot under it
29
29
  stays aside: the row reads as it does under a pointer.
30
+ Its menu opens toward the page: its left edge under the ⋮, spreading
31
+ right over what the column sits beside, not back over the list.
30
32
 
31
33
  <Canvas of={NavItemStories.WithMenu} />
32
34
 
@@ -63,7 +65,10 @@ count — a muted mono number whose tooltip says what it counts.
63
65
  `preview`: it opens the **PreviewCard** while the row itself is pointed at,
64
66
  the ⋮ included, and never while a row under it is. Unlike `tooltip`, the
65
67
  pointer can move into it. A screen with no hover never shows it either, so
66
- the row must still make sense without it.
68
+ the row must still make sense without it. `onPreviewOpenChange` is told
69
+ once each time the card opens (`true`) and closes (`false`). For an app
70
+ that counts what the card listed as seen, the seen moment is the `false`
71
+ that follows a `true`: leaving the card after it was open, never the `true`.
67
72
 
68
73
  <Canvas of={NavItemStories.RowPreview} />
69
74
 
@@ -74,6 +79,15 @@ count — a muted mono number whose tooltip says what it counts.
74
79
 
75
80
  <Canvas of={NavItemStories.Unread} />
76
81
 
82
+ - `unreadTone="reaction"` draws the dot for a reaction to you, in the
83
+ warning colour; `urgent` still draws the badge instead. A row with both
84
+ something new and a reaction passes blue: one blue dot, and the card lists
85
+ both.
86
+
87
+ <Canvas of={NavItemStories.UnreadReaction} />
88
+
89
+ <Canvas of={NavItemStories.UnreadBlueAndReaction} />
90
+
77
91
  - A row the app opens its own way, with what it already knows — beside the
78
92
  list, in place — is `onPlainClick`: it runs on a plain click only, and the
79
93
  link is not followed. Ctrl, Cmd, Shift, Alt and the middle button are still
@@ -143,7 +157,7 @@ It does these by itself. Write none of them around it.
143
157
  | Turns its icon into the arrow that folds `children` while pointed at or focused, and slides them | a positioned `IconButton` over the icon, open state, `group-hover` reveals, an indented box | |
144
158
  | Tells assistive technology whether its rows are open | `aria-expanded`, `aria-controls` | |
145
159
  | Shows `hint` only while pointed at or focused, and makes the label give way | a positioned chip over the row, `group-hover` reveals | |
146
- | Draws the dot or the badge for `unread` and `urgent`, and brightens the row | an **UnreadDot** placed by hand, a weight or colour passed in | |
160
+ | Draws the dot or the badge for `unread` and `urgent`, in the colour `unreadTone` names, and brightens the row | an **UnreadDot** placed by hand, a weight or colour passed in | |
147
161
  | Tells a plain click from one for a new tab, for `onPlainClick` | `event.button`, `event.metaKey`, `event.ctrlKey`… read by hand in an `onClick` | |
148
162
 
149
163
  ## Keys
@@ -101,6 +101,29 @@ export const Unread: Story = {
101
101
  args: { icon: placeholder, unread: true },
102
102
  }
103
103
 
104
+ /** `unreadTone="reaction"`: the dot for a reaction to you, in the warning colour. */
105
+ export const UnreadReaction: Story = {
106
+ args: { icon: placeholder, unread: true, unreadTone: 'reaction' },
107
+ }
108
+
109
+ /**
110
+ * Something new and a reaction on one row: it draws one blue dot, never two, and the reaction's dot only when nothing
111
+ * blue is there. The caller picks the tone; the card can still list both.
112
+ */
113
+ export const UnreadBlueAndReaction: Story = {
114
+ args: {
115
+ icon: placeholder,
116
+ unread: true,
117
+ unreadTone: 'blue',
118
+ preview: (
119
+ <div className="flex flex-col gap-1 p-2 text-caption text-text-secondary">
120
+ <span>Line one: the blue kind of new.</span>
121
+ <span>Line two: a reaction to you.</span>
122
+ </div>
123
+ ),
124
+ },
125
+ }
126
+
104
127
  /** Urgent and unread: the warning badge in the dot's place. */
105
128
  export const UnreadUrgent: Story = {
106
129
  args: { icon: placeholder, unread: true, urgent: true },
@@ -6,7 +6,7 @@
6
6
  * The reveal on hover and the slide are Chrome's to show.
7
7
  */
8
8
  import { afterEach, describe, expect, it, vi } from 'vitest'
9
- import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
9
+ import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
10
10
  import userEvent from '@testing-library/user-event'
11
11
  import { AppProvider } from './AppProvider'
12
12
  import { NavItem } from './NavItem'
@@ -43,6 +43,32 @@ describe('NavItem with a preview', () => {
43
43
  expect(screen.queryByText('About item one')).toBeNull()
44
44
  })
45
45
 
46
+ it('onPreviewOpenChange hears the card open while the row is pointed at, and close when the pointer leaves', () => {
47
+ vi.useFakeTimers()
48
+ try {
49
+ const heard: boolean[] = []
50
+ const { container } = render(<NavItem href="#one" label="Item one" unread preview={<span>What is new</span>} onPreviewOpenChange={(open) => heard.push(open)} />)
51
+ // The card's trigger wraps the row; Base UI listens on it for the mouse. Fired by hand under fake timers (the
52
+ // tests above use real ones), so the 350ms and 200ms are stepped rather than waited for.
53
+ const trigger = container.firstElementChild as HTMLElement
54
+ fireEvent.pointerEnter(trigger, { pointerType: 'mouse' })
55
+ fireEvent.mouseEnter(trigger)
56
+ act(() => {
57
+ vi.advanceTimersByTime(400)
58
+ })
59
+ expect(screen.getByText('What is new')).toBeTruthy()
60
+ expect(heard).toEqual([true])
61
+ fireEvent.mouseLeave(trigger)
62
+ act(() => {
63
+ vi.advanceTimersByTime(300)
64
+ })
65
+ expect(screen.queryByText('What is new')).toBeNull()
66
+ expect(heard).toEqual([true, false])
67
+ } finally {
68
+ vi.useRealTimers()
69
+ }
70
+ })
71
+
46
72
  it('a plain row with a preview opens it too', async () => {
47
73
  const user = userEvent.setup()
48
74
  render(<NavItem href="#one" label="Item one" preview={<span>What is new</span>} />)
@@ -143,6 +169,25 @@ describe('NavItem unread', () => {
143
169
  expect(container.querySelector('[data-urgent]')!.parentElement!.className.split(' ')).toContain('-mr-1')
144
170
  })
145
171
 
172
+ it('unreadTone reaction draws the reaction’s dot; the default stays blue', () => {
173
+ const { container } = render(
174
+ <>
175
+ <NavItem href="#" label="Item one" unread />
176
+ <NavItem href="#" label="Item two" unread unreadTone="reaction" />
177
+ </>,
178
+ )
179
+ const dots = container.querySelectorAll('[data-unread]')
180
+ expect(dots.length).toBe(2)
181
+ expect(dots[0].getAttribute('data-tone')).toBe('blue')
182
+ expect(dots[1].getAttribute('data-tone')).toBe('reaction')
183
+ })
184
+
185
+ it('urgent still wins over a reaction’s dot: the badge, and no dot', () => {
186
+ const { container } = render(<NavItem href="#" label="Item one" unread urgent unreadTone="reaction" />)
187
+ expect(container.querySelector('[data-urgent]')).not.toBeNull()
188
+ expect(container.querySelector('[data-unread]')).toBeNull()
189
+ })
190
+
146
191
  it('urgent without unread draws nothing', () => {
147
192
  const { container } = render(<NavItem href="#" label="Item one" urgent />)
148
193
  expect(container.querySelector('[data-urgent], [data-unread]')).toBeNull()
package/src/NavItem.tsx CHANGED
@@ -10,7 +10,7 @@ import { IconButton } from './IconButton'
10
10
  import { Menu } from './Menu'
11
11
  import { PreviewCard } from './PreviewCard'
12
12
  import type { SectionAction } from './SectionHeader'
13
- import { UnreadDot } from './UnreadDot'
13
+ import { UnreadDot, type UnreadDotTone } from './UnreadDot'
14
14
  import { WithTooltip } from './Tooltip'
15
15
 
16
16
  /**
@@ -50,7 +50,8 @@ import { WithTooltip } from './Tooltip'
50
50
  *
51
51
  * `unread` brightens the row's words and icon, sets the label in medium, and
52
52
  * draws the `UnreadDot` at the right; `urgent` with it draws the warning badge
53
- * in the dot's place (Katerina, 2 October: Peek's row, moved in). The ⋮ lands
53
+ * in the dot's place (Katerina, 2 October: Peek's row, moved in); `unreadTone`
54
+ * says which kind of new the dot is, `reaction` for a reaction to you (ACT-7). The ⋮ lands
54
55
  * on whatever is in that place, and with nothing there it takes no room until
55
56
  * the row is pointed at, so a label at rest keeps the row's whole width.
56
57
  *
@@ -81,6 +82,8 @@ export interface NavItemProps extends Omit<ComponentPropsWithoutRef<'a'>, 'href'
81
82
  unread?: boolean
82
83
  /** With `unread`: the warning badge in the dot's place. */
83
84
  urgent?: boolean
85
+ /** With `unread`: which kind of new the dot is, `UnreadDot`'s `tone`. Default blue; `urgent` still draws the badge instead. */
86
+ unreadTone?: UnreadDotTone
84
87
  /**
85
88
  * More about the row, in the package's `PreviewCard` while the row itself is pointed at — never the rows under it —
86
89
  * such as a short list of what is new there. Unlike `tooltip`, it holds content the pointer can move into. The card
@@ -88,6 +91,12 @@ export interface NavItemProps extends Omit<ComponentPropsWithoutRef<'a'>, 'href'
88
91
  * preview the label draws no `tooltip`: one surface per hover. Absent, no card.
89
92
  */
90
93
  preview?: ReactNode
94
+ /**
95
+ * With `preview`: told each time the card opens (`true`) and closes (`false`), once each — `PreviewCard`'s
96
+ * `onOpenChange`. The moment the card's content counts as seen is the `false` that follows a `true`: leaving the
97
+ * card after it was open, never the `true`.
98
+ */
99
+ onPreviewOpenChange?: (open: boolean) => void
91
100
  /** Rows under this one, folding under it: `NavItem`s. While the row is pointed at or focused, its icon becomes the arrow. */
92
101
  children?: ReactNode
93
102
  /** With `children`: open unless told otherwise. */
@@ -125,7 +134,9 @@ export function NavItem({
125
134
  tooltip,
126
135
  unread = false,
127
136
  urgent = false,
137
+ unreadTone = 'blue',
128
138
  preview,
139
+ onPreviewOpenChange,
129
140
  children,
130
141
  defaultOpen = true,
131
142
  open: openProp,
@@ -151,7 +162,7 @@ export function NavItem({
151
162
  const buttons = (menu != null ? 1 : 0) + (action ? 1 : 0)
152
163
  const besides = buttons > 0 || hasRows
153
164
  // What sits at the right at rest, after the count: the dot, or the badge.
154
- const mark = unread ? (urgent ? <UrgentMark /> : <UnreadDot />) : null
165
+ const mark = unread ? (urgent ? <UrgentMark /> : <UnreadDot tone={unreadTone} />) : null
155
166
  // Under the ⋮ while it shows: the count and the mark step aside for it.
156
167
  // "While it shows" is the pointer on the row or the keyboard in it
157
168
  // (`:focus-visible`), never any focus: a clicked row keeps its focus, and
@@ -249,7 +260,7 @@ export function NavItem({
249
260
  // The card's lines are rows with their own padding, so the card keeps only a 4px edge (the content's rhythm is the caller's).
250
261
  const card = (trigger: ReactNode) =>
251
262
  preview == null ? trigger : (
252
- <PreviewCard content={preview} contentClassName="gap-0.5 p-1" wrapperClassName="block w-full shrink-0">
263
+ <PreviewCard content={preview} contentClassName="gap-0.5 p-1" wrapperClassName="block w-full shrink-0" onOpenChange={onPreviewOpenChange}>
253
264
  {trigger}
254
265
  </PreviewCard>
255
266
  )
@@ -289,8 +300,12 @@ export function NavItem({
289
300
  </IconButton>
290
301
  )}
291
302
  {menu != null && (
303
+ /*
304
+ Toward the page: the menu's left edge under the ⋮, spreading right over what the column sits beside,
305
+ not back over the list and the rail (Katerina, 16 November). At the screen's edge Base UI shifts it in.
306
+ */
292
307
  <Menu
293
- align="right"
308
+ align="left"
294
309
  trigger={
295
310
  <IconButton tooltip="More options" aria-label={name}>
296
311
  <IconDotsVertical size={16} stroke={1.5} />
@@ -14,8 +14,8 @@ and — unlike a tooltip — you can move into it, so what it holds can be long,
14
14
  can scroll, and can be read at your own pace.
15
15
 
16
16
  It is a **read**, not a control. Nothing in a preview card may be the only way
17
- to reach anything: there is no keyboard trigger, so a person who does not use a
18
- pointer never sees it.
17
+ to reach anything: there is no keyboard trigger of its own, so a person who does
18
+ not use a pointer may never see it.
19
19
 
20
20
  <Canvas of={PreviewCardStories.Default} />
21
21
 
@@ -96,14 +96,18 @@ It does these by itself. Write none of them around it.
96
96
  | Closes on a press outside | a click listener on the page | ✓ |
97
97
  | Opens after the pointer rests, and stays up while the pointer moves into it | a hover timer | |
98
98
  | Closes on Escape | a key handler | |
99
+ | Tells `onOpenChange` once per open (`true`) and once per close (`false`), whatever opened it (pointer, focus, a tap), and `false` once if it is unmounted while open. "Seen" is the `false` after a `true`, never the `true` | open state of your own, or a listener on the trigger | |
99
100
 
100
101
  ## Keys
101
102
 
102
- There is no keyboard trigger, by design — see above.
103
+ There is no keyboard trigger of its own, by design — see above. Focus that
104
+ lands on something focusable inside the trigger, such as a row's link, does
105
+ open it after the same delay.
103
106
 
104
107
  | Input | What happens |
105
108
  |---|---|
106
109
  | pointer rests on the trigger | opens after 350ms |
110
+ | focus on a link or button inside the trigger | opens after 350ms |
107
111
  | pointer moves into the card | it stays up, and can be scrolled |
108
112
  | pointer leaves both | closes after 200ms |
109
113
  | Escape | closes |
@@ -43,6 +43,113 @@ describe('PreviewCard', () => {
43
43
  expect(screen.queryByText('The rest of it')).toBeNull()
44
44
  })
45
45
 
46
+ it('onOpenChange hears a hover open once and the close once, not on each render while it is open', () => {
47
+ vi.useFakeTimers()
48
+ const heard: boolean[] = []
49
+ const { rerender } = render(
50
+ <PreviewCard content={<span>The rest of it</span>} onOpenChange={(open) => heard.push(open)}>
51
+ <span>A row</span>
52
+ </PreviewCard>,
53
+ )
54
+ // The trigger is the wrapper, and Base UI listens there for the mouse arriving and leaving. Fired by hand, because
55
+ // user-event waits on a clock this test fakes.
56
+ const trigger = screen.getByText('A row').parentElement as HTMLElement
57
+ fireEvent.pointerEnter(trigger, { pointerType: 'mouse' })
58
+ fireEvent.mouseEnter(trigger)
59
+ act(() => {
60
+ vi.advanceTimersByTime(400)
61
+ })
62
+ expect(screen.getByText('The rest of it')).toBeTruthy()
63
+ rerender(
64
+ <PreviewCard content={<span>The rest of it, again</span>} onOpenChange={(open) => heard.push(open)}>
65
+ <span>A row</span>
66
+ </PreviewCard>,
67
+ )
68
+ expect(heard).toEqual([true])
69
+ fireEvent.mouseLeave(trigger)
70
+ act(() => {
71
+ vi.advanceTimersByTime(300)
72
+ })
73
+ expect(screen.queryByText('The rest of it, again')).toBeNull()
74
+ expect(heard).toEqual([true, false])
75
+ })
76
+
77
+ it('onOpenChange hears a card opened by keyboard focus on what the trigger holds', () => {
78
+ vi.useFakeTimers()
79
+ const heard: boolean[] = []
80
+ render(
81
+ <PreviewCard content={<span>The rest of it</span>} onOpenChange={(open) => heard.push(open)}>
82
+ <a href="#one">A row</a>
83
+ </PreviewCard>,
84
+ )
85
+ act(() => screen.getByRole('link', { name: 'A row' }).focus())
86
+ act(() => {
87
+ vi.advanceTimersByTime(400)
88
+ })
89
+ expect(screen.getByText('The rest of it')).toBeTruthy()
90
+ expect(heard).toEqual([true])
91
+ })
92
+
93
+ it('onOpenChange hears one open when the card opened by the pointer is then focused into', () => {
94
+ vi.useFakeTimers()
95
+ const heard: boolean[] = []
96
+ render(
97
+ <PreviewCard content={<span>The rest of it</span>} onOpenChange={(open) => heard.push(open)}>
98
+ <a href="#one">A row</a>
99
+ </PreviewCard>,
100
+ )
101
+ const link = screen.getByRole('link', { name: 'A row' })
102
+ const trigger = link.parentElement as HTMLElement
103
+ fireEvent.pointerEnter(trigger, { pointerType: 'mouse' })
104
+ fireEvent.mouseEnter(trigger)
105
+ act(() => {
106
+ vi.advanceTimersByTime(400)
107
+ })
108
+ act(() => link.focus())
109
+ act(() => {
110
+ vi.advanceTimersByTime(400)
111
+ })
112
+ expect(screen.getByText('The rest of it')).toBeTruthy()
113
+ expect(heard).toEqual([true])
114
+ })
115
+
116
+ it('onOpenChange hears the close once when the card is unmounted while open, so an open is never left unanswered', () => {
117
+ const heard: boolean[] = []
118
+ const { unmount } = render(
119
+ <PreviewCard content={<span>The rest of it</span>} openOnTap onOpenChange={(open) => heard.push(open)}>
120
+ <button type="button">A dot</button>
121
+ </PreviewCard>,
122
+ )
123
+ fireEvent.click(screen.getByRole('button', { name: 'A dot' }))
124
+ expect(screen.getByText('The rest of it')).toBeTruthy()
125
+ unmount()
126
+ expect(heard).toEqual([true, false])
127
+ })
128
+
129
+ it('onOpenChange hears nothing when a card that never opened is unmounted', () => {
130
+ const heard: boolean[] = []
131
+ const { unmount } = render(
132
+ <PreviewCard content={<span>The rest of it</span>} onOpenChange={(open) => heard.push(open)}>
133
+ <span>A row</span>
134
+ </PreviewCard>,
135
+ )
136
+ unmount()
137
+ expect(heard).toEqual([])
138
+ })
139
+
140
+ it('with openOnTap, onOpenChange hears each tap: open, then closed', () => {
141
+ const heard: boolean[] = []
142
+ render(
143
+ <PreviewCard content={<span>The rest of it</span>} openOnTap onOpenChange={(open) => heard.push(open)}>
144
+ <button type="button">A dot</button>
145
+ </PreviewCard>,
146
+ )
147
+ const dot = screen.getByRole('button', { name: 'A dot' })
148
+ fireEvent.click(dot)
149
+ fireEvent.click(dot)
150
+ expect(heard).toEqual([true, false])
151
+ })
152
+
46
153
  it('with openOnTap, a tap on a touch screen opens the card and a second tap closes it', async () => {
47
154
  const user = userEvent.setup()
48
155
  render(