@estiva-app/ui 0.115.1 → 0.116.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/NavItem.d.ts +12 -2
- package/dist/NavItem.d.ts.map +1 -1
- package/dist/PreviewCard.d.ts +9 -1
- package/dist/PreviewCard.d.ts.map +1 -1
- package/dist/UnreadDot.d.ts +12 -1
- package/dist/UnreadDot.d.ts.map +1 -1
- package/dist/eslint/index.js +3 -2
- package/dist/eslint/index.js.map +2 -2
- package/dist/eslint/no-restyled-part.d.ts.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +42 -27
- package/dist/index.js.map +3 -3
- package/package.json +1 -1
- package/registry.json +35 -3
- package/src/NavItem.mdx +14 -2
- package/src/NavItem.stories.tsx +23 -0
- package/src/NavItem.test.tsx +46 -1
- package/src/NavItem.tsx +15 -4
- package/src/PreviewCard.mdx +7 -3
- package/src/PreviewCard.test.tsx +107 -0
- package/src/PreviewCard.tsx +22 -2
- package/src/UnreadDot.mdx +7 -1
- package/src/UnreadDot.stories.tsx +3 -0
- package/src/UnreadDot.test.tsx +16 -9
- package/src/UnreadDot.tsx +23 -3
- package/src/eslint/no-restyled-part.ts +2 -1
- package/src/index.ts +1 -1
- package/stories/Choosing.mdx +2 -2
package/package.json
CHANGED
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.
|
|
7
|
+
"packageVersion": "0.116.0",
|
|
8
8
|
"exports": 253,
|
|
9
|
-
"typeExports":
|
|
9
|
+
"typeExports": 264,
|
|
10
10
|
"files": null
|
|
11
11
|
},
|
|
12
12
|
"storybook": {
|
|
@@ -7660,12 +7660,24 @@
|
|
|
7660
7660
|
"required": false,
|
|
7661
7661
|
"note": "With `unread`: the warning badge in the dot's place."
|
|
7662
7662
|
},
|
|
7663
|
+
{
|
|
7664
|
+
"name": "unreadTone",
|
|
7665
|
+
"takes": "UnreadDotTone",
|
|
7666
|
+
"required": false,
|
|
7667
|
+
"note": "With `unread`: which kind of new the dot is, `UnreadDot`'s `tone`."
|
|
7668
|
+
},
|
|
7663
7669
|
{
|
|
7664
7670
|
"name": "preview",
|
|
7665
7671
|
"takes": "anything",
|
|
7666
7672
|
"required": false,
|
|
7667
7673
|
"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
7674
|
},
|
|
7675
|
+
{
|
|
7676
|
+
"name": "onPreviewOpenChange",
|
|
7677
|
+
"takes": "a handler",
|
|
7678
|
+
"required": false,
|
|
7679
|
+
"note": "With `preview`: told each time the card opens (`true`) and closes (`false`), once each — `PreviewCard`'s `onOpenChange`."
|
|
7680
|
+
},
|
|
7669
7681
|
{
|
|
7670
7682
|
"name": "children",
|
|
7671
7683
|
"takes": "anything",
|
|
@@ -8738,6 +8750,12 @@
|
|
|
8738
8750
|
"takes": "true/false",
|
|
8739
8751
|
"required": false,
|
|
8740
8752
|
"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)."
|
|
8753
|
+
},
|
|
8754
|
+
{
|
|
8755
|
+
"name": "onOpenChange",
|
|
8756
|
+
"takes": "a handler",
|
|
8757
|
+
"required": false,
|
|
8758
|
+
"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
8759
|
}
|
|
8742
8760
|
],
|
|
8743
8761
|
"variants": [
|
|
@@ -12373,9 +12391,23 @@
|
|
|
12373
12391
|
"takes": "true/false",
|
|
12374
12392
|
"required": false,
|
|
12375
12393
|
"note": null
|
|
12394
|
+
},
|
|
12395
|
+
{
|
|
12396
|
+
"name": "tone",
|
|
12397
|
+
"takes": "blue | reaction",
|
|
12398
|
+
"required": false,
|
|
12399
|
+
"note": null
|
|
12400
|
+
}
|
|
12401
|
+
],
|
|
12402
|
+
"variants": [
|
|
12403
|
+
{
|
|
12404
|
+
"prop": "tone",
|
|
12405
|
+
"values": [
|
|
12406
|
+
"blue",
|
|
12407
|
+
"reaction"
|
|
12408
|
+
]
|
|
12376
12409
|
}
|
|
12377
12410
|
],
|
|
12378
|
-
"variants": [],
|
|
12379
12411
|
"ownsBehaviours": [],
|
|
12380
12412
|
"status": "stable",
|
|
12381
12413
|
"migrationStage": null,
|
package/src/NavItem.mdx
CHANGED
|
@@ -63,7 +63,10 @@ count — a muted mono number whose tooltip says what it counts.
|
|
|
63
63
|
`preview`: it opens the **PreviewCard** while the row itself is pointed at,
|
|
64
64
|
the ⋮ included, and never while a row under it is. Unlike `tooltip`, the
|
|
65
65
|
pointer can move into it. A screen with no hover never shows it either, so
|
|
66
|
-
the row must still make sense without it.
|
|
66
|
+
the row must still make sense without it. `onPreviewOpenChange` is told
|
|
67
|
+
once each time the card opens (`true`) and closes (`false`). For an app
|
|
68
|
+
that counts what the card listed as seen, the seen moment is the `false`
|
|
69
|
+
that follows a `true`: leaving the card after it was open, never the `true`.
|
|
67
70
|
|
|
68
71
|
<Canvas of={NavItemStories.RowPreview} />
|
|
69
72
|
|
|
@@ -74,6 +77,15 @@ count — a muted mono number whose tooltip says what it counts.
|
|
|
74
77
|
|
|
75
78
|
<Canvas of={NavItemStories.Unread} />
|
|
76
79
|
|
|
80
|
+
- `unreadTone="reaction"` draws the dot for a reaction to you, in the
|
|
81
|
+
warning colour; `urgent` still draws the badge instead. A row with both
|
|
82
|
+
something new and a reaction passes blue: one blue dot, and the card lists
|
|
83
|
+
both.
|
|
84
|
+
|
|
85
|
+
<Canvas of={NavItemStories.UnreadReaction} />
|
|
86
|
+
|
|
87
|
+
<Canvas of={NavItemStories.UnreadBlueAndReaction} />
|
|
88
|
+
|
|
77
89
|
- A row the app opens its own way, with what it already knows — beside the
|
|
78
90
|
list, in place — is `onPlainClick`: it runs on a plain click only, and the
|
|
79
91
|
link is not followed. Ctrl, Cmd, Shift, Alt and the middle button are still
|
|
@@ -143,7 +155,7 @@ It does these by itself. Write none of them around it.
|
|
|
143
155
|
| 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
156
|
| Tells assistive technology whether its rows are open | `aria-expanded`, `aria-controls` | |
|
|
145
157
|
| 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 | |
|
|
158
|
+
| 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
159
|
| 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
160
|
|
|
149
161
|
## Keys
|
package/src/NavItem.stories.tsx
CHANGED
|
@@ -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 },
|
package/src/NavItem.test.tsx
CHANGED
|
@@ -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)
|
|
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
|
)
|
package/src/PreviewCard.mdx
CHANGED
|
@@ -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
|
|
18
|
-
pointer never
|
|
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 |
|
package/src/PreviewCard.test.tsx
CHANGED
|
@@ -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(
|
package/src/PreviewCard.tsx
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { useRef, useState, type PointerEvent, type ReactNode } from 'react'
|
|
1
|
+
import { useEffect, useRef, useState, type PointerEvent, type ReactNode } from 'react'
|
|
2
2
|
import { PreviewCard as BasePreviewCard } from '@base-ui/react/preview-card'
|
|
3
3
|
import { cn } from './cn'
|
|
4
4
|
import { ScrollArea } from './ScrollArea'
|
|
@@ -53,6 +53,14 @@ export interface PreviewCardProps {
|
|
|
53
53
|
* hover-only, because a tap on a row opens the row.
|
|
54
54
|
*/
|
|
55
55
|
openOnTap?: boolean
|
|
56
|
+
/**
|
|
57
|
+
* Called once each time the card opens (`true`) and once each time it closes (`false`), however it got there: a
|
|
58
|
+
* pointer resting, keyboard focus, a tap with `openOnTap`, Escape, a press outside, or the card unmounted while
|
|
59
|
+
* open. Never twice in a row with the same value, and never on a render. For a caller that counts what the card
|
|
60
|
+
* held as seen, the seen moment is the `false` that follows a `true` — leaving the card after it was open — never
|
|
61
|
+
* the `true`.
|
|
62
|
+
*/
|
|
63
|
+
onOpenChange?: (open: boolean) => void
|
|
56
64
|
}
|
|
57
65
|
|
|
58
66
|
/** The card's own numbers: 12px from the trigger, 8px clear of every screen
|
|
@@ -72,10 +80,22 @@ const OPEN_DELAY = 350
|
|
|
72
80
|
* here the card can be reached, so it can. */
|
|
73
81
|
const CLOSE_DELAY = 200
|
|
74
82
|
|
|
75
|
-
export function PreviewCard({ content, children, side = 'right', delay = OPEN_DELAY, closeDelay = CLOSE_DELAY, className, contentClassName, wrapperClassName, openOnTap = false }: PreviewCardProps) {
|
|
83
|
+
export function PreviewCard({ content, children, side = 'right', delay = OPEN_DELAY, closeDelay = CLOSE_DELAY, className, contentClassName, wrapperClassName, openOnTap = false, onOpenChange: onOpenChangeProp }: PreviewCardProps) {
|
|
76
84
|
// Held here always, so turning `openOnTap` on or off never switches the card between controlled and not; without it
|
|
77
85
|
// every change is Base UI's own (hover, focus, Escape, a press outside), as before.
|
|
78
86
|
const [open, setOpen] = useState(false)
|
|
87
|
+
// The caller hears the open state itself change, never a report of it: Base UI may report open again when focus
|
|
88
|
+
// lands in a card the pointer opened, and a tap may set what is already there, and neither changes `open`. The
|
|
89
|
+
// cleanup is the close, and it runs once whether the card closes or is unmounted while open.
|
|
90
|
+
const tell = useRef(onOpenChangeProp)
|
|
91
|
+
useEffect(() => {
|
|
92
|
+
tell.current = onOpenChangeProp
|
|
93
|
+
})
|
|
94
|
+
useEffect(() => {
|
|
95
|
+
if (!open) return
|
|
96
|
+
tell.current?.(true)
|
|
97
|
+
return () => tell.current?.(false)
|
|
98
|
+
}, [open])
|
|
79
99
|
// The press the next click belongs to: its pointer type, and whether the card was open when it went down. A tap
|
|
80
100
|
// focuses a button inside, and focus may open the card before the click, so the click sets the opposite of what was
|
|
81
101
|
// there before the press, not of what focus just did. The click uses it up.
|
package/src/UnreadDot.mdx
CHANGED
|
@@ -19,6 +19,11 @@ when one replaces the other.
|
|
|
19
19
|
The 24px slot keeps the two the same size.
|
|
20
20
|
- In a sidebar row, pass **NavItem** `unread` rather than placing it: the row
|
|
21
21
|
draws it, and brightens its words.
|
|
22
|
+
- `tone="reaction"` for a reaction to you. A row with both something new and
|
|
23
|
+
a reaction draws one blue dot, never two: the reaction's dot only when
|
|
24
|
+
nothing blue is there. Choosing the tone is yours.
|
|
25
|
+
|
|
26
|
+
<Canvas of={UnreadDotStories.Reaction} />
|
|
22
27
|
|
|
23
28
|
## When not
|
|
24
29
|
|
|
@@ -52,9 +57,10 @@ It does these by itself. Write none of them around it.
|
|
|
52
57
|
| It does | So you never write | Refused when written by hand |
|
|
53
58
|
|---|---|---|
|
|
54
59
|
| The 6px disc in a 24px slot | a sized box around a round div | |
|
|
55
|
-
| `data-unread`, the attribute tests and photo runs select on | a marker of your own | |
|
|
60
|
+
| `data-unread`, the attribute tests and photo runs select on, and `data-tone` (`blue` or `reaction`) beside it | a marker of your own | |
|
|
56
61
|
| Keeps its size in a tight row | `shrink-0` | |
|
|
57
62
|
| `quiet`: the same 6px as a ring, not marked `data-unread`, for a dot that is always there and has nothing new | a bordered div of your own | |
|
|
63
|
+
| `tone="reaction"`: a reaction to you, in the warning colour | a colour class on the dot | |
|
|
58
64
|
|
|
59
65
|
## Props
|
|
60
66
|
|
|
@@ -11,6 +11,9 @@ type Story = StoryObj<typeof meta>
|
|
|
11
11
|
|
|
12
12
|
export const Default: Story = {}
|
|
13
13
|
|
|
14
|
+
/** `tone="reaction"`: a reaction to you, drawn in the warning colour. */
|
|
15
|
+
export const Reaction: Story = { args: { tone: 'reaction' } }
|
|
16
|
+
|
|
14
17
|
/** Nothing new: the ring a dot that is always there draws, so the slot does not empty. */
|
|
15
18
|
export const Quiet: Story = { args: { quiet: true } }
|
|
16
19
|
|
package/src/UnreadDot.test.tsx
CHANGED
|
@@ -1,22 +1,29 @@
|
|
|
1
1
|
// @vitest-environment jsdom
|
|
2
|
-
/** What the page claims: the
|
|
2
|
+
/** What the page claims: the dot is marked for tests and photo runs, `data-unread` and its `data-tone`. */
|
|
3
3
|
import { afterEach, describe, expect, it } from 'vitest'
|
|
4
4
|
import { cleanup, render } from '@testing-library/react'
|
|
5
5
|
import { UnreadDot } from './UnreadDot'
|
|
6
6
|
|
|
7
7
|
afterEach(cleanup)
|
|
8
8
|
|
|
9
|
+
const slotOf = (container: HTMLElement) => container.firstElementChild as HTMLElement
|
|
10
|
+
|
|
9
11
|
describe('UnreadDot', () => {
|
|
10
|
-
it('is
|
|
11
|
-
const
|
|
12
|
-
|
|
12
|
+
it('is marked data-unread, and blue by default: data-tone="blue"', () => {
|
|
13
|
+
const slot = slotOf(render(<UnreadDot />).container)
|
|
14
|
+
expect(slot.hasAttribute('data-unread')).toBe(true)
|
|
15
|
+
expect(slot.getAttribute('data-tone')).toBe('blue')
|
|
16
|
+
})
|
|
17
|
+
|
|
18
|
+
it('a reaction is still unread, and says so in data-tone="reaction"', () => {
|
|
19
|
+
const slot = slotOf(render(<UnreadDot tone="reaction" />).container)
|
|
13
20
|
expect(slot.hasAttribute('data-unread')).toBe(true)
|
|
14
|
-
expect(slot.
|
|
15
|
-
expect((slot.firstElementChild as HTMLElement).className).toContain('w-1.5')
|
|
21
|
+
expect(slot.getAttribute('data-tone')).toBe('reaction')
|
|
16
22
|
})
|
|
17
23
|
|
|
18
|
-
it('a quiet dot, with nothing new, is not marked data-unread, so nothing reads it as unread', () => {
|
|
19
|
-
const
|
|
20
|
-
expect(
|
|
24
|
+
it('a quiet dot, with nothing new, is not marked data-unread nor given a tone, so nothing reads it as unread', () => {
|
|
25
|
+
const slot = slotOf(render(<UnreadDot quiet tone="reaction" />).container)
|
|
26
|
+
expect(slot.hasAttribute('data-unread')).toBe(false)
|
|
27
|
+
expect(slot.hasAttribute('data-tone')).toBe(false)
|
|
21
28
|
})
|
|
22
29
|
})
|
package/src/UnreadDot.tsx
CHANGED
|
@@ -1,5 +1,20 @@
|
|
|
1
1
|
import { cn } from './cn'
|
|
2
2
|
|
|
3
|
+
/**
|
|
4
|
+
* What kind of new a dot says, named for what it is, not its colour: `blue`, the accent, for something new;
|
|
5
|
+
* `reaction` for a reaction to you.
|
|
6
|
+
*/
|
|
7
|
+
export type UnreadDotTone = 'blue' | 'reaction'
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* The disc's fill per tone, in one place. A reaction is drawn in the warning family, the urgent mark's colour (ACT-7);
|
|
11
|
+
* if Katerina gives it a colour or a token of its own, only this line changes.
|
|
12
|
+
*/
|
|
13
|
+
const TONE_FILL: Record<UnreadDotTone, string> = {
|
|
14
|
+
blue: 'bg-accent-primary',
|
|
15
|
+
reaction: 'bg-warning-default',
|
|
16
|
+
}
|
|
17
|
+
|
|
3
18
|
/**
|
|
4
19
|
* The accent dot that says "something new here": a 6px disc centred in a
|
|
5
20
|
* 24px slot, so it sits where a control would and the row does not shift when
|
|
@@ -12,11 +27,16 @@ import { cn } from './cn'
|
|
|
12
27
|
* page's title, which is always there because it opens the page's list
|
|
13
28
|
* (ACT-4; the activity indicator prototype Miky approved, 10 November). A
|
|
14
29
|
* quiet dot is not marked `data-unread`.
|
|
30
|
+
*
|
|
31
|
+
* `tone="reaction"` draws a reaction to you, in the warning colour (ACT-7; the
|
|
32
|
+
* same prototype). A dot that is not quiet says its tone in `data-tone`,
|
|
33
|
+
* `blue` or `reaction`, beside `data-unread`. Which tone a row shows is the
|
|
34
|
+
* caller's: a row with both kinds of new draws one blue dot.
|
|
15
35
|
*/
|
|
16
|
-
export function UnreadDot({ className, quiet = false }: { className?: string; quiet?: boolean }) {
|
|
36
|
+
export function UnreadDot({ className, quiet = false, tone = 'blue' }: { className?: string; quiet?: boolean; tone?: UnreadDotTone }) {
|
|
17
37
|
return (
|
|
18
|
-
<div className={cn('flex h-6 w-6 shrink-0 items-center justify-center', className)} {...(quiet ? {} : { 'data-unread': '' })}>
|
|
19
|
-
<div className={cn('h-1.5 w-1.5 rounded-full', quiet ? 'border border-border-strong' :
|
|
38
|
+
<div className={cn('flex h-6 w-6 shrink-0 items-center justify-center', className)} {...(quiet ? {} : { 'data-unread': '', 'data-tone': tone })}>
|
|
39
|
+
<div className={cn('h-1.5 w-1.5 rounded-full', quiet ? 'border border-border-strong' : TONE_FILL[tone])} />
|
|
20
40
|
</div>
|
|
21
41
|
)
|
|
22
42
|
}
|
|
@@ -149,7 +149,7 @@ export const PART_LOOK_PROPS: Record<string, string[]> = {
|
|
|
149
149
|
MenuItem: ['size', 'selected', 'destructive'],
|
|
150
150
|
MenuSub: ['selected'],
|
|
151
151
|
MetaText: ['size'],
|
|
152
|
-
NavItem: ['active'],
|
|
152
|
+
NavItem: ['active', 'unreadTone'],
|
|
153
153
|
Person: ['size'],
|
|
154
154
|
ProgressBar: ['variant'],
|
|
155
155
|
Property: ['layout'],
|
|
@@ -167,6 +167,7 @@ export const PART_LOOK_PROPS: Record<string, string[]> = {
|
|
|
167
167
|
Toolbar: ['surface'],
|
|
168
168
|
ToolbarButton: ['variant', 'pressed', 'glow'],
|
|
169
169
|
TopBar: ['variant'],
|
|
170
|
+
UnreadDot: ['tone'],
|
|
170
171
|
}
|
|
171
172
|
|
|
172
173
|
/** The class props of a part: `className`, and the ones for an inner box. */
|
package/src/index.ts
CHANGED
|
@@ -82,7 +82,7 @@ export { SkeletonBar, SkeletonConversation, SkeletonList, SkeletonRow } from './
|
|
|
82
82
|
export { Breadcrumb, type BreadcrumbProps, type Crumb } from './Breadcrumb'
|
|
83
83
|
export { EnterHint, Menu, MenuItem, MenuPanel, MenuRow, MenuSection, MenuSeparator, MenuSub, type MenuItemProps, type MenuPanelProps, type MenuProps, type MenuSubProps } from './Menu'
|
|
84
84
|
export { NavItem, type NavItemProps } from './NavItem'
|
|
85
|
-
export { UnreadDot } from './UnreadDot'
|
|
85
|
+
export { UnreadDot, type UnreadDotTone } from './UnreadDot'
|
|
86
86
|
export { NAV_TREE_PENDING_MS, NavTree, NavTreeSection, type NavTreeGroup, type NavTreeNode, type NavTreeProps, type NavTreeSectionProps } from './NavTree'
|
|
87
87
|
export { Popover, type PopoverProps } from './Popover'
|
|
88
88
|
export { SuggestionMenu, type SuggestionMenuHandle, type SuggestionMenuProps, type SuggestionMenuRow, type SuggestionMenuSection } from './SuggestionMenu'
|
package/stories/Choosing.mdx
CHANGED
|
@@ -66,7 +66,7 @@ fork freely, owe nothing back, mention it on the package's ticket.
|
|
|
66
66
|
|---|---|
|
|
67
67
|
| A list of verbs from a trigger | **Menu** — Escape, outside-click and the arrow keys come with it |
|
|
68
68
|
| A panel of *content* from a trigger — a field, a toolbar, a small form | **Popover** — the menu's surface without a menu's keyboard |
|
|
69
|
-
| More of a thing on hover | **PreviewCard** — unlike a tooltip, you can point at it; on a sidebar row, **NavItem** `preview` opens it; `openOnTap` when nothing else on the trigger answers a tap |
|
|
69
|
+
| More of a thing on hover | **PreviewCard** — unlike a tooltip, you can point at it; on a sidebar row, **NavItem** `preview` opens it; `openOnTap` when nothing else on the trigger answers a tap; `onOpenChange` to hear it open and close |
|
|
70
70
|
| A hint on hover or on keyboard focus | **Tooltip** / **WithTooltip** — one `TooltipProvider` at the app root shares the delay |
|
|
71
71
|
| A strip of controls that act on one thing | **Toolbar** — one Tab stop for the row, arrow keys along it |
|
|
72
72
|
| Reactions to choose from | **ReactionPicker** — the row; **Reaction** is the pill it produces |
|
|
@@ -120,7 +120,7 @@ The same conversation in every app; only its colours are each app's.
|
|
|
120
120
|
| A box that can hold more than fits — a list that grows with its data counts, even when today's data fits | **ScrollArea** — its bar is drawn over the content and takes no width |
|
|
121
121
|
| Text that can run long above things the reader needs, cut behind a fade | **ShowMore** — measures; what fits has no button |
|
|
122
122
|
| A status, a count or a category, in a small pill | **Chip** — six colour types; the colour is the message, the label makes it legible |
|
|
123
|
-
| Something new on a row or a card, no count | **UnreadDot** — the 6px dot in a 24px slot; in a sidebar row, **NavItem** `unread` draws it; `quiet` for a dot that is always there with nothing new |
|
|
123
|
+
| Something new on a row or a card, no count | **UnreadDot** — the 6px dot in a 24px slot; in a sidebar row, **NavItem** `unread` draws it; `quiet` for a dot that is always there with nothing new; `tone="reaction"` for a reaction to you (NavItem `unreadTone`) |
|
|
124
124
|
| One thing — a conversation, a project, an object — as a box you can pick | **Card** — the fill by what it sits on; `href` for a link, `hover="fill"` in a feed, `onPress` when a press opens it |
|
|
125
125
|
| A section heading, chevron, hover actions, a count beside the title | **SectionHeader** |
|
|
126
126
|
| A group of rows that opens and closes, and stays how you left it | **CollapsibleSection** — `storageKey` remembers |
|