@estiva-app/ui 0.112.0 → 0.113.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@estiva-app/ui",
3
- "version": "0.112.0",
3
+ "version": "0.113.0",
4
4
  "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
5
5
  "type": "module",
6
6
  "license": "MIT",
package/registry.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "kind": "package",
5
5
  "repo": "estiva-ui",
6
6
  "package": "@estiva-app/ui",
7
- "packageVersion": "0.112.0",
7
+ "packageVersion": "0.113.0",
8
8
  "exports": 253,
9
9
  "typeExports": 263,
10
10
  "files": null
@@ -7660,6 +7660,12 @@
7660
7660
  "required": false,
7661
7661
  "note": "With `unread`: the warning badge in the dot's place."
7662
7662
  },
7663
+ {
7664
+ "name": "preview",
7665
+ "takes": "anything",
7666
+ "required": false,
7667
+ "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
+ },
7663
7669
  {
7664
7670
  "name": "children",
7665
7671
  "takes": "anything",
package/src/NavItem.mdx CHANGED
@@ -59,6 +59,14 @@ count — a muted mono number whose tooltip says what it counts.
59
59
 
60
60
  <Canvas of={NavItemStories.LabelTooltip} />
61
61
 
62
+ - More about the row than a sentence (a short list of what is new there) is
63
+ `preview`: it opens the **PreviewCard** while the row itself is pointed at,
64
+ the ⋮ included, and never while a row under it is. Unlike `tooltip`, the
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.
67
+
68
+ <Canvas of={NavItemStories.RowPreview} />
69
+
62
70
  - Something new on the row is `unread`: its words and icon brighten, the
63
71
  label is set in medium, and the **UnreadDot** sits at the right.
64
72
  `urgent` with it draws the warning badge in the dot's place. Say "unread"
@@ -128,6 +128,21 @@ export const LabelTooltip: Story = {
128
128
  args: { icon: placeholder, action: REMOVE, tooltip: 'One sentence saying what this item is about, shown while its label is pointed at.' },
129
129
  }
130
130
 
131
+ /** `preview`: rest the pointer on the row and a card opens beside it, holding content you can move into; the rows under it open nothing. */
132
+ export const RowPreview: Story = {
133
+ args: {
134
+ icon: placeholder,
135
+ unread: true,
136
+ preview: (
137
+ <div className="flex flex-col gap-1 p-2 text-caption text-text-secondary">
138
+ <span>Line one of what the card holds.</span>
139
+ <span>Line two of what the card holds.</span>
140
+ </div>
141
+ ),
142
+ children: <NavItem href="#two" label="Item two" icon={placeholder} />,
143
+ },
144
+ }
145
+
131
146
  /** A hint and a button: point at it and the chip shows, then the button — a row whose state is a word (here, archived) and which can be taken off the list. */
132
147
  export const WithActionAndHint: Story = {
133
148
  args: { label: 'An item whose label runs much longer than the column has room for', icon: placeholder, action: REMOVE, hint: <Chip type="neutral" label="Archived" /> },
@@ -15,6 +15,43 @@ afterEach(cleanup)
15
15
 
16
16
  const arrow = (name: RegExp) => screen.getByRole('button', { name })
17
17
 
18
+ /*
19
+ Real timers, as PreviewCard's own test: Base UI's hover card never opens under Vitest's fake timers in jsdom. The
20
+ waits are findBy/waitFor polling the screen, not sleeps.
21
+ */
22
+ describe('NavItem with a preview', () => {
23
+ it('opens the card while the row is pointed at, and closes it when the pointer moves to a row under it', async () => {
24
+ const user = userEvent.setup()
25
+ render(
26
+ <NavItem href="#one" label="Item one" unread preview={<span>What is new</span>} menu={<span />}>
27
+ <NavItem href="#two" label="Item two" />
28
+ </NavItem>,
29
+ )
30
+ await user.hover(screen.getByText('Item one'))
31
+ expect(await screen.findByText('What is new')).toBeTruthy()
32
+ await user.unhover(screen.getByText('Item one'))
33
+ await user.hover(screen.getByText('Item two'))
34
+ await waitFor(() => expect(screen.queryByText('What is new')).toBeNull())
35
+ })
36
+
37
+ it('a row with a preview opens the card alone: the label’s tooltip does not stand up beside it', async () => {
38
+ const user = userEvent.setup()
39
+ render(<NavItem href="#one" label="Item one" tooltip="About item one" preview={<span>What is new</span>} />)
40
+ await user.hover(screen.getByText('Item one'))
41
+ // The tooltip's 300ms is shorter than the card's 350ms: had it been drawn, it would be up by now.
42
+ expect(await screen.findByText('What is new')).toBeTruthy()
43
+ expect(screen.queryByText('About item one')).toBeNull()
44
+ })
45
+
46
+ it('a plain row with a preview opens it too', async () => {
47
+ const user = userEvent.setup()
48
+ render(<NavItem href="#one" label="Item one" preview={<span>What is new</span>} />)
49
+ expect(screen.queryByText('What is new')).toBeNull()
50
+ await user.hover(screen.getByText('Item one'))
51
+ expect(await screen.findByText('What is new')).toBeTruthy()
52
+ })
53
+ })
54
+
18
55
  describe('NavItem with rows under it', () => {
19
56
  const tree = (props: Partial<Parameters<typeof NavItem>[0]> = {}) => (
20
57
  <NavItem href="#one" label="Item one" {...props}>
package/src/NavItem.tsx CHANGED
@@ -8,6 +8,7 @@ import { useOpenFor } from './CollapsibleSection'
8
8
  import { COLLAPSIBLE_PANEL_CLASSES, COUNT_TEXT_CLASSES, SIDEBAR_ROW_CLASSES, SIDEBAR_ROW_TEXT_CLASSES } from './looks'
9
9
  import { IconButton } from './IconButton'
10
10
  import { Menu } from './Menu'
11
+ import { PreviewCard } from './PreviewCard'
11
12
  import type { SectionAction } from './SectionHeader'
12
13
  import { UnreadDot } from './UnreadDot'
13
14
  import { WithTooltip } from './Tooltip'
@@ -80,6 +81,13 @@ export interface NavItemProps extends Omit<ComponentPropsWithoutRef<'a'>, 'href'
80
81
  unread?: boolean
81
82
  /** With `unread`: the warning badge in the dot's place. */
82
83
  urgent?: boolean
84
+ /**
85
+ * More about the row, in the package's `PreviewCard` while the row itself is pointed at — never the rows under it —
86
+ * such as a short list of what is new there. Unlike `tooltip`, it holds content the pointer can move into. The card
87
+ * opens on the whole row, the ⋮ included, so a dot the ⋮ steps aside for is not lost as the pointer arrives. With a
88
+ * preview the label draws no `tooltip`: one surface per hover. Absent, no card.
89
+ */
90
+ preview?: ReactNode
83
91
  /** Rows under this one, folding under it: `NavItem`s. While the row is pointed at or focused, its icon becomes the arrow. */
84
92
  children?: ReactNode
85
93
  /** With `children`: open unless told otherwise. */
@@ -117,6 +125,7 @@ export function NavItem({
117
125
  tooltip,
118
126
  unread = false,
119
127
  urgent = false,
128
+ preview,
120
129
  children,
121
130
  defaultOpen = true,
122
131
  open: openProp,
@@ -184,9 +193,10 @@ export function NavItem({
184
193
  {icon}
185
194
  </span>
186
195
  )}
187
- {tooltip?.trim() ? (
196
+ {tooltip?.trim() && preview == null ? (
188
197
  // On the label alone, not the row: the ⋮ and the action keep their
189
- // own tooltips, and the two never stand up at once.
198
+ // own tooltips, and the two never stand up at once. A row with a
199
+ // preview card says more there, so the label has no tooltip beside it.
190
200
  <WithTooltip label={tooltip} inline wrapperClassName="flex min-w-0 flex-1">
191
201
  <span className={cn('flex-1 truncate', unread && 'font-medium')}>{label}</span>
192
202
  </WithTooltip>
@@ -236,7 +246,14 @@ export function NavItem({
236
246
  ) : null}
237
247
  </a>
238
248
  )
239
- if (!besides && hint == null) return row
249
+ // 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
+ const card = (trigger: ReactNode) =>
251
+ preview == null ? trigger : (
252
+ <PreviewCard content={preview} contentClassName="gap-0.5 p-1" wrapperClassName="block w-full shrink-0">
253
+ {trigger}
254
+ </PreviewCard>
255
+ )
256
+ if (!besides && hint == null) return card(row)
240
257
  const name = menuLabel ?? `More options for ${label}`
241
258
  const line = (
242
259
  <div className="group/nav relative shrink-0">
@@ -287,10 +304,10 @@ export function NavItem({
287
304
  )}
288
305
  </div>
289
306
  )
290
- if (!hasRows) return line
307
+ if (!hasRows) return card(line)
291
308
  return (
292
309
  <Collapsible.Root open={open} onOpenChange={setOpen} className="flex shrink-0 flex-col">
293
- {line}
310
+ {card(line)}
294
311
  {/* CollapsibleSection's slide, the same way: Base UI measures the panel
295
312
  and the height transitions, none under prefers-reduced-motion. */}
296
313
  <Collapsible.Panel
@@ -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 |
69
+ | More of a thing on hover | **PreviewCard** — unlike a tooltip, you can point at it; on a sidebar row, **NavItem** `preview` opens it |
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 |