@estiva-app/ui 0.92.1 → 0.94.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/src/NavTree.tsx CHANGED
@@ -84,8 +84,19 @@ export interface NavTreeProps {
84
84
  * is absent.
85
85
  */
86
86
  children?: ReactNode
87
- /** The row that is current: `active`, and its group starts open. */
87
+ /**
88
+ * The row that is current: `active`. Each time it names a new row, its
89
+ * group and every row above it open, closing nothing — a group closed by
90
+ * hand too — and the column scrolls to it once they have slid open.
91
+ */
88
92
  selected?: string
93
+ /**
94
+ * The row the current one sits under, while the tree does not draw the
95
+ * current one: its rows are not read yet, or it is not a row here. The tree
96
+ * opens onto that row the same way, opens the row itself so its rows are
97
+ * read, and marks nothing for it.
98
+ */
99
+ selectedParent?: string
89
100
  /** A row was clicked. A router app prevents the default and navigates. */
90
101
  onSelect?: (node: NavTreeNode, event: MouseEvent<HTMLAnchorElement>) => void
91
102
  /** What to say when `groups` is empty. The words are the caller's; absent, nothing is said. */
@@ -97,10 +108,58 @@ export interface NavTreeProps {
97
108
  /** How long the pointer rests on a group before `onIntent` (Peek's FolderTree, 150ms). */
98
109
  export const NAV_TREE_INTENT_MS = 150
99
110
 
111
+ /** How long the column waits to scroll to the current row: the rows above it slide open in 150ms. */
112
+ export const NAV_TREE_REVEAL_MS = 200
113
+
100
114
  function holds(nodes: NavTreeNode[] | null, id: string | undefined): boolean {
101
115
  return !!nodes && id !== undefined && nodes.some((node) => node.id === id || holds(node.children ?? null, id))
102
116
  }
103
117
 
118
+ /** The rows above the row `id`, outermost first; `null` when no row here is `id`. */
119
+ function rowsAbove(nodes: NavTreeNode[] | null | undefined, id: string): string[] | null {
120
+ for (const node of nodes ?? []) {
121
+ if (node.id === id) return []
122
+ const inner = rowsAbove(node.children, id)
123
+ if (inner) return [node.id, ...inner]
124
+ }
125
+ return null
126
+ }
127
+
128
+ /** What opens so the current row shows: its group and the rows above it — or above `selectedParent`, and that row, until the current one is drawn. */
129
+ interface Opening {
130
+ /** The current item, for `openFor`: a new one opens them again. */
131
+ item: string
132
+ group: string
133
+ rows: ReadonlySet<string>
134
+ }
135
+
136
+ function openingFor(groups: NavTreeGroup[], selected: string | undefined, selectedParent: string | undefined): Opening | null {
137
+ const item = selected ?? selectedParent
138
+ if (item === undefined) return null
139
+ for (const [target, andItself] of [[selected, false], [selectedParent, true]] as const) {
140
+ if (target === undefined) continue
141
+ for (const group of groups) {
142
+ const above = rowsAbove(group.nodes, target)
143
+ if (above) return { item, group: group.id, rows: new Set(andItself ? [...above, target] : above) }
144
+ }
145
+ }
146
+ return null
147
+ }
148
+
149
+ /**
150
+ * Scroll the column the row is in, and only that box — never the page, nor a
151
+ * drawer that is shut — so the row is in sight. A row in sight stays put.
152
+ */
153
+ function scrollToRow(row: HTMLElement) {
154
+ let box = row.parentElement
155
+ while (box && !(/(auto|scroll)/.test(getComputedStyle(box).overflowY) && box.scrollHeight > box.clientHeight)) box = box.parentElement
156
+ if (!box || box === document.documentElement || box === document.body) return
157
+ const at = row.getBoundingClientRect()
158
+ const view = box.getBoundingClientRect()
159
+ if (at.top < view.top) box.scrollTop -= view.top - at.top
160
+ else if (at.bottom > view.bottom) box.scrollTop += at.bottom - view.bottom
161
+ }
162
+
104
163
  /** A line in the rows' place: level with the rows, which pad themselves (Katerina, 14 September). */
105
164
  function Line({ message }: { message: string }) {
106
165
  return (
@@ -110,12 +169,14 @@ function Line({ message }: { message: string }) {
110
169
  )
111
170
  }
112
171
 
113
- function Row({ node, selected, onSelect }: { node: NavTreeNode } & Pick<NavTreeProps, 'selected' | 'onSelect'>) {
172
+ type Drawn = Pick<NavTreeProps, 'selected' | 'onSelect'> & { opening: Opening | null }
173
+
174
+ function Row({ node, selected, onSelect, opening }: { node: NavTreeNode } & Drawn) {
114
175
  const under =
115
176
  node.childrenMessage !== undefined ? (
116
177
  <Line message={node.childrenMessage} />
117
178
  ) : node.children?.length ? (
118
- node.children.map((child) => <Row key={child.id} node={child} selected={selected} onSelect={onSelect} />)
179
+ node.children.map((child) => <Row key={child.id} node={child} selected={selected} onSelect={onSelect} opening={opening} />)
119
180
  ) : node.children === null || (node.hasChildren && node.children === undefined) ? (
120
181
  <SkeletonList rows={2} />
121
182
  ) : undefined
@@ -134,6 +195,7 @@ function Row({ node, selected, onSelect }: { node: NavTreeNode } & Pick<NavTreeP
134
195
  defaultOpen={node.defaultOpen ?? true}
135
196
  open={node.open}
136
197
  onOpenChange={node.onOpenChange}
198
+ openFor={opening?.rows.has(node.id) ? opening.item : undefined}
137
199
  onClick={onSelect ? (event) => onSelect(node, event) : undefined}
138
200
  >
139
201
  {under}
@@ -141,7 +203,7 @@ function Row({ node, selected, onSelect }: { node: NavTreeNode } & Pick<NavTreeP
141
203
  )
142
204
  }
143
205
 
144
- function Group({ group, selected, onSelect, storageKey }: { group: NavTreeGroup } & Pick<NavTreeProps, 'selected' | 'onSelect' | 'storageKey'>) {
206
+ function Group({ group, selected, onSelect, opening, storageKey }: { group: NavTreeGroup } & Drawn & Pick<NavTreeProps, 'storageKey'>) {
145
207
  return (
146
208
  <NavTreeSection
147
209
  id={group.id}
@@ -156,9 +218,10 @@ function Group({ group, selected, onSelect, storageKey }: { group: NavTreeGroup
156
218
  open={group.open}
157
219
  onOpenChange={group.onOpenChange}
158
220
  storageKey={storageKey ? `${storageKey}.${group.id}` : undefined}
221
+ openFor={opening?.group === group.id ? opening.item : undefined}
159
222
  onIntent={group.onIntent}
160
223
  >
161
- {group.nodes?.map((node) => <Row key={node.id} node={node} selected={selected} onSelect={onSelect} />)}
224
+ {group.nodes?.map((node) => <Row key={node.id} node={node} selected={selected} onSelect={onSelect} opening={opening} />)}
162
225
  </NavTreeSection>
163
226
  )
164
227
  }
@@ -194,6 +257,8 @@ export interface NavTreeSectionProps {
194
257
  pending?: boolean
195
258
  /** Remember it open or closed in this browser, under this key. */
196
259
  storageKey?: string
260
+ /** The current item, when it sits in this group: the group opens each time this names a new one — `CollapsibleSection`'s. */
261
+ openFor?: string
197
262
  /** The rows: `NavItem`s. */
198
263
  children?: ReactNode
199
264
  }
@@ -205,7 +270,7 @@ export interface NavTreeSectionProps {
205
270
  * `groups`; an app whose groups each read their own data draws them itself,
206
271
  * as `NavTree`'s children.
207
272
  */
208
- export function NavTreeSection({ id, title, message, loading = false, pending, trailing, actions, menu, icon, defaultOpen = true, open, onOpenChange, storageKey, onIntent, children }: NavTreeSectionProps) {
273
+ export function NavTreeSection({ id, title, message, loading = false, pending, trailing, actions, menu, icon, defaultOpen = true, open, onOpenChange, storageKey, openFor, onIntent, children }: NavTreeSectionProps) {
209
274
  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
210
275
  useEffect(() => () => clearTimeout(timer.current), [])
211
276
  const intent = onIntent
@@ -233,6 +298,7 @@ export function NavTreeSection({ id, title, message, loading = false, pending, t
233
298
  onOpenChange={onOpenChange}
234
299
  pending={pending}
235
300
  storageKey={storageKey}
301
+ openFor={openFor}
236
302
  trailing={trailing}
237
303
  actions={actions}
238
304
  menu={menu}
@@ -255,10 +321,36 @@ export function NavTreeSection({ id, title, message, loading = false, pending, t
255
321
  * arrow that folds what is under it. Groups and rows can be read when they
256
322
  * open. Only the group that holds the current row starts open, unless the
257
323
  * caller owns it.
324
+ *
325
+ * Opening a row shows where it lives (Katerina, 30 October: a file opened
326
+ * from another app's card, in a new tab, sat marked inside a shut Folder):
327
+ * each new current row opens its group and the rows above it, even those
328
+ * closed by hand, once — closed again, they stay closed until another opens —
329
+ * and the column scrolls to it. Groups the app draws itself take `openFor`
330
+ * for that; the scroll is the tree's either way.
258
331
  */
259
- export function NavTree({ title, titleActions, groups, children, selected, onSelect, emptyMessage = '', storageKey }: NavTreeProps) {
332
+ export function NavTree({ title, titleActions, groups, children, selected, selectedParent, onSelect, emptyMessage = '', storageKey }: NavTreeProps) {
333
+ const opening = groups ? openingFor(groups, selected, selectedParent) : null
334
+ // Once per current row, when it is drawn and shown: a later draw, or a read landing, does not pull the column back to it.
335
+ const box = useRef<HTMLDivElement>(null)
336
+ const scrolled = useRef<string | undefined>(undefined)
337
+ const waiting = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
338
+ const latest = useRef(selected)
339
+ latest.current = selected
340
+ useEffect(() => {
341
+ if (selected === undefined || scrolled.current === selected || waiting.current !== undefined) return
342
+ waiting.current = setTimeout(() => {
343
+ waiting.current = undefined
344
+ const row = box.current?.querySelector<HTMLElement>('[aria-current="page"]')
345
+ if (!row || row.getBoundingClientRect().height === 0) return
346
+ scrolled.current = latest.current
347
+ scrollToRow(row)
348
+ }, NAV_TREE_REVEAL_MS)
349
+ })
350
+ useEffect(() => () => clearTimeout(waiting.current), [])
260
351
  return (
261
- <>
352
+ // `contents`: a box to find the current row in, that lays nothing out — the groups stay the column's own.
353
+ <div ref={box} className="contents">
262
354
  {title && <SectionHeader title={title} look="quiet" showActions="always" actions={titleActions} className="mt-4 shrink-0" />}
263
355
  {groups === undefined ? (
264
356
  children
@@ -268,8 +360,8 @@ export function NavTree({ title, titleActions, groups, children, selected, onSel
268
360
  // No words, no line: an app that says nothing when it has no groups.
269
361
  emptyMessage ? <Line message={emptyMessage} /> : null
270
362
  ) : (
271
- groups.map((group) => <Group key={group.id} group={group} selected={selected} onSelect={onSelect} storageKey={storageKey} />)
363
+ groups.map((group) => <Group key={group.id} group={group} selected={selected} onSelect={onSelect} opening={opening} storageKey={storageKey} />)
272
364
  )}
273
- </>
365
+ </div>
274
366
  )
275
367
  }
@@ -25,6 +25,8 @@ title the toggle — that is where a section folds.
25
25
 
26
26
  <Canvas of={SectionHeaderStories.PersistentActions} />
27
27
 
28
+ - An action with `menu` in place of `onClick` opens those items: a Sort or a
29
+ filter, where the choice is the action. The row stays lit while it is open.
28
30
  - `menu` gives the section a "More options" ⋮ after its actions, with what
29
31
  acts on the whole section — a folder's Rename, Archive. It is **NavItem**'s
30
32
  ⋮, revealed with the actions, and stays while its menu is open.
@@ -35,12 +35,18 @@ import { SectionLabel } from './SectionLabel'
35
35
  * old shape yet: the two hard-wired action slots (add, sort) became
36
36
  * `actions` — the caller brings the icon, the tooltip and the handler.
37
37
  */
38
- export interface SectionAction {
38
+ export type SectionAction = {
39
39
  /** 16px, stroke 1.5. */
40
40
  icon: ReactNode
41
41
  tooltip: string
42
- onClick: () => void
43
- }
42
+ } & (
43
+ | { onClick: () => void; menu?: undefined }
44
+ /**
45
+ * The button opens a menu of these items instead: a choice that is the
46
+ * action, a sort or a filter (Katerina, 30 October: Open work's Sort).
47
+ */
48
+ | { menu: ReactNode; onClick?: undefined }
49
+ )
44
50
 
45
51
  export interface SectionHeaderProps {
46
52
  title: string
@@ -225,11 +231,27 @@ export function SectionHeader({ title, chevron = false, icon, isExpanded = true,
225
231
  className="-mr-1 flex shrink-0 items-center"
226
232
  >
227
233
  <div className={cn('flex items-center gap-1', reveal)}>
228
- {actions?.map((action) => (
229
- <IconButton key={action.tooltip} tooltip={action.tooltip} aria-label={action.tooltip} onClick={action.onClick}>
230
- {action.icon}
231
- </IconButton>
232
- ))}
234
+ {actions?.map((action) =>
235
+ action.menu != null ? (
236
+ // `data-section-menu`, as the ⋮ has: the row stays lit while its menu is open.
237
+ <div key={action.tooltip} data-section-menu className="flex items-center">
238
+ <Menu
239
+ align="right"
240
+ trigger={
241
+ <IconButton tooltip={action.tooltip} aria-label={action.tooltip}>
242
+ {action.icon}
243
+ </IconButton>
244
+ }
245
+ >
246
+ {action.menu}
247
+ </Menu>
248
+ </div>
249
+ ) : (
250
+ <IconButton key={action.tooltip} tooltip={action.tooltip} aria-label={action.tooltip} onClick={action.onClick}>
251
+ {action.icon}
252
+ </IconButton>
253
+ ),
254
+ )}
233
255
  {menu != null && (
234
256
  <div data-section-menu className="flex items-center">
235
257
  <Menu
package/src/Toast.mdx CHANGED
@@ -57,6 +57,9 @@ showToast({ label: 'Link copied', type: 'success' })
57
57
  - **The action closes its own toast.** Pressing it runs `onAction`, if you
58
58
  gave one, then closes that toast and no other. A Dismiss is just
59
59
  `actionLabel: 'Dismiss'`.
60
+ - `onClose` is told once when the toast closes, however it closes. An Undo
61
+ that is a wait — the write held until the toast goes — writes there, so the
62
+ toast's own timer, which pauses while it is pointed at, is the only one.
60
63
  - `showToast` returns the toast's id. `dismissToast(id)` closes that toast;
61
64
  `dismissToast()` with no id closes **every** toast on screen.
62
65
  - A toast can be swiped away towards its corner — left or down.
package/src/Toast.tsx CHANGED
@@ -133,6 +133,12 @@ export interface ToastOptions {
133
133
  leadingIcon?: boolean
134
134
  /** Auto-dismiss after this many ms. Defaults to 5000. Pass 0 to disable. */
135
135
  durationMs?: number
136
+ /**
137
+ * Told once when the toast closes, however it closes: its own timer, its
138
+ * action, a swipe, Escape or `dismissToast`. For an action whose Undo is a
139
+ * wait — the write happens here, unless the Undo was pressed first.
140
+ */
141
+ onClose?: () => void
136
142
  }
137
143
 
138
144
  interface ToastValue {
@@ -163,11 +169,12 @@ export function ToastProvider({ children }: { children: ReactNode }) {
163
169
  const manager = useMemo(() => BaseToast.createToastManager<ToastData>(), [])
164
170
  const value = useMemo<ToastValue>(
165
171
  () => ({
166
- showToast: ({ label, type = 'neutral', leadingIcon = true, actionLabel, onAction, durationMs = 5000 }) =>
172
+ showToast: ({ label, type = 'neutral', leadingIcon = true, actionLabel, onAction, durationMs = 5000, onClose }) =>
167
173
  manager.add({
168
174
  title: label,
169
175
  type,
170
176
  timeout: durationMs,
177
+ onClose,
171
178
  // A failure interrupts; everything else waits for a pause.
172
179
  priority: type === 'error' ? 'high' : 'low',
173
180
  data: { leadingIcon, actionLabel, onAction },