@estiva-app/ui 0.98.1 → 0.100.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 (212) hide show
  1. package/README.md +4 -2
  2. package/dist/AppProvider.d.ts +6 -3
  3. package/dist/AppProvider.d.ts.map +1 -1
  4. package/dist/ArchiveDialog.d.ts +35 -0
  5. package/dist/ArchiveDialog.d.ts.map +1 -0
  6. package/dist/AttachedCard.d.ts +13 -2
  7. package/dist/AttachedCard.d.ts.map +1 -1
  8. package/dist/Card.d.ts +6 -1
  9. package/dist/Card.d.ts.map +1 -1
  10. package/dist/ChipInput.d.ts +3 -1
  11. package/dist/ChipInput.d.ts.map +1 -1
  12. package/dist/CollapsibleSection.d.ts +27 -2
  13. package/dist/CollapsibleSection.d.ts.map +1 -1
  14. package/dist/CommentBox.d.ts +2 -2
  15. package/dist/CommentBox.d.ts.map +1 -1
  16. package/dist/ConfirmDialog.d.ts +15 -2
  17. package/dist/ConfirmDialog.d.ts.map +1 -1
  18. package/dist/ConversationCard.d.ts +12 -1
  19. package/dist/ConversationCard.d.ts.map +1 -1
  20. package/dist/ConversationLayout.d.ts +20 -5
  21. package/dist/ConversationLayout.d.ts.map +1 -1
  22. package/dist/ConversationMenu.d.ts +5 -1
  23. package/dist/ConversationMenu.d.ts.map +1 -1
  24. package/dist/ConversationPlace.d.ts +17 -0
  25. package/dist/ConversationPlace.d.ts.map +1 -0
  26. package/dist/DocumentEditor.d.ts +38 -0
  27. package/dist/DocumentEditor.d.ts.map +1 -1
  28. package/dist/DocumentField.d.ts +50 -0
  29. package/dist/DocumentField.d.ts.map +1 -0
  30. package/dist/EditableText.d.ts +38 -4
  31. package/dist/EditableText.d.ts.map +1 -1
  32. package/dist/EmptyState.d.ts +10 -5
  33. package/dist/EmptyState.d.ts.map +1 -1
  34. package/dist/FormDialog.d.ts +38 -0
  35. package/dist/FormDialog.d.ts.map +1 -0
  36. package/dist/InlineText.d.ts.map +1 -1
  37. package/dist/Menu.d.ts +11 -3
  38. package/dist/Menu.d.ts.map +1 -1
  39. package/dist/MoveDialog.d.ts +64 -0
  40. package/dist/MoveDialog.d.ts.map +1 -0
  41. package/dist/NavItem.d.ts +9 -2
  42. package/dist/NavItem.d.ts.map +1 -1
  43. package/dist/NavTree.d.ts +16 -3
  44. package/dist/NavTree.d.ts.map +1 -1
  45. package/dist/PinnedComment.d.ts +3 -1
  46. package/dist/PinnedComment.d.ts.map +1 -1
  47. package/dist/ReactionHorizon.d.ts +3 -1
  48. package/dist/ReactionHorizon.d.ts.map +1 -1
  49. package/dist/RepliesRow.d.ts +5 -3
  50. package/dist/RepliesRow.d.ts.map +1 -1
  51. package/dist/ResolveDialog.d.ts +3 -1
  52. package/dist/ResolveDialog.d.ts.map +1 -1
  53. package/dist/SelectionToolbar.d.ts +2 -2
  54. package/dist/Thread.d.ts +6 -3
  55. package/dist/Thread.d.ts.map +1 -1
  56. package/dist/commentBoxFrame.d.ts.map +1 -1
  57. package/dist/conversation.examples.d.ts +4 -1
  58. package/dist/conversation.examples.d.ts.map +1 -1
  59. package/dist/conversationScroll.d.ts +80 -0
  60. package/dist/conversationScroll.d.ts.map +1 -0
  61. package/dist/editor.d.ts +1 -0
  62. package/dist/editor.d.ts.map +1 -1
  63. package/dist/editor.js +228 -69
  64. package/dist/editor.js.map +4 -4
  65. package/dist/eslint/index.js +2 -2
  66. package/dist/eslint/index.js.map +2 -2
  67. package/dist/eslint/no-field-outside-a-form.d.ts +2 -2
  68. package/dist/eslint/no-field-outside-a-form.d.ts.map +1 -1
  69. package/dist/eslint/no-native-title.d.ts +1 -1
  70. package/dist/eslint/no-native-title.d.ts.map +1 -1
  71. package/dist/formBusy.d.ts +5 -2
  72. package/dist/formBusy.d.ts.map +1 -1
  73. package/dist/index.d.ts +14 -6
  74. package/dist/index.d.ts.map +1 -1
  75. package/dist/index.js +2242 -1471
  76. package/dist/index.js.map +4 -4
  77. package/dist/looks.d.ts +8 -0
  78. package/dist/looks.d.ts.map +1 -1
  79. package/dist/seenOnScreen.d.ts +27 -0
  80. package/dist/seenOnScreen.d.ts.map +1 -0
  81. package/dist/showInConversation.d.ts +31 -0
  82. package/dist/showInConversation.d.ts.map +1 -0
  83. package/dist/threadCard.d.ts +13 -0
  84. package/dist/threadCard.d.ts.map +1 -1
  85. package/package.json +1 -1
  86. package/registry.json +953 -126
  87. package/src/AppProvider.mdx +4 -0
  88. package/src/AppProvider.test.tsx +34 -2
  89. package/src/AppProvider.tsx +17 -6
  90. package/src/ArchiveDialog.mdx +70 -0
  91. package/src/ArchiveDialog.stories.tsx +64 -0
  92. package/src/ArchiveDialog.test.tsx +90 -0
  93. package/src/ArchiveDialog.tsx +70 -0
  94. package/src/AttachedCard.mdx +6 -0
  95. package/src/AttachedCard.stories.tsx +9 -1
  96. package/src/AttachedCard.test.tsx +111 -2
  97. package/src/AttachedCard.tsx +77 -7
  98. package/src/Card.mdx +20 -1
  99. package/src/Card.stories.tsx +20 -0
  100. package/src/Card.test.tsx +87 -1
  101. package/src/Card.tsx +51 -3
  102. package/src/ChipInput.mdx +7 -1
  103. package/src/ChipInput.stories.tsx +9 -0
  104. package/src/ChipInput.test.tsx +42 -0
  105. package/src/ChipInput.tsx +7 -3
  106. package/src/CollapsibleSection.mdx +20 -1
  107. package/src/CollapsibleSection.stories.tsx +19 -1
  108. package/src/CollapsibleSection.test.tsx +85 -2
  109. package/src/CollapsibleSection.tsx +54 -15
  110. package/src/CommentBox.mdx +2 -1
  111. package/src/CommentBox.test.tsx +81 -1
  112. package/src/CommentBox.tsx +32 -11
  113. package/src/ConfirmDialog.mdx +25 -3
  114. package/src/ConfirmDialog.stories.tsx +27 -0
  115. package/src/ConfirmDialog.test.tsx +87 -1
  116. package/src/ConfirmDialog.tsx +39 -8
  117. package/src/ConversationCard.mdx +7 -0
  118. package/src/ConversationCard.states.test.tsx +67 -0
  119. package/src/ConversationCard.stories.tsx +27 -1
  120. package/src/ConversationCard.test.tsx +76 -0
  121. package/src/ConversationCard.tsx +65 -53
  122. package/src/ConversationLayout.mdx +34 -4
  123. package/src/ConversationLayout.scroll.test.tsx +411 -0
  124. package/src/ConversationLayout.stories.tsx +107 -1
  125. package/src/ConversationLayout.test.tsx +133 -0
  126. package/src/ConversationLayout.tsx +141 -16
  127. package/src/ConversationMenu.mdx +3 -0
  128. package/src/ConversationMenu.stories.tsx +12 -0
  129. package/src/ConversationMenu.test.tsx +17 -0
  130. package/src/ConversationMenu.tsx +7 -3
  131. package/src/ConversationPlace.mdx +53 -0
  132. package/src/ConversationPlace.stories.tsx +48 -0
  133. package/src/ConversationPlace.test.tsx +51 -0
  134. package/src/ConversationPlace.tsx +30 -0
  135. package/src/DocumentEditor.mdx +2 -1
  136. package/src/DocumentEditor.tsx +118 -64
  137. package/src/DocumentField.mdx +83 -0
  138. package/src/DocumentField.stories.tsx +110 -0
  139. package/src/DocumentField.test.tsx +281 -0
  140. package/src/DocumentField.tsx +199 -0
  141. package/src/EditableText.buttons.test.tsx +318 -0
  142. package/src/EditableText.mdx +50 -2
  143. package/src/EditableText.stories.tsx +96 -2
  144. package/src/EditableText.tsx +189 -5
  145. package/src/EmptyState.mdx +33 -8
  146. package/src/EmptyState.stories.tsx +26 -1
  147. package/src/EmptyState.test.tsx +63 -2
  148. package/src/EmptyState.tsx +28 -6
  149. package/src/Form.mdx +3 -1
  150. package/src/FormDialog.mdx +78 -0
  151. package/src/FormDialog.stories.tsx +90 -0
  152. package/src/FormDialog.test.tsx +183 -0
  153. package/src/FormDialog.tsx +93 -0
  154. package/src/InlineText.mdx +1 -0
  155. package/src/InlineText.tsx +2 -1
  156. package/src/Menu.test.tsx +80 -0
  157. package/src/Menu.tsx +35 -14
  158. package/src/MenuItem.mdx +12 -0
  159. package/src/MenuItem.stories.tsx +39 -1
  160. package/src/MoveDialog.mdx +85 -0
  161. package/src/MoveDialog.stories.tsx +134 -0
  162. package/src/MoveDialog.test.tsx +239 -0
  163. package/src/MoveDialog.tsx +186 -0
  164. package/src/NavItem.mdx +15 -0
  165. package/src/NavItem.stories.tsx +15 -0
  166. package/src/NavItem.test.tsx +64 -1
  167. package/src/NavItem.tsx +10 -2
  168. package/src/NavTree.mdx +26 -4
  169. package/src/NavTree.stories.tsx +59 -0
  170. package/src/NavTree.test.tsx +232 -2
  171. package/src/NavTree.tsx +93 -43
  172. package/src/PinnedComment.mdx +6 -1
  173. package/src/PinnedComment.stories.tsx +11 -1
  174. package/src/PinnedComment.tsx +15 -2
  175. package/src/ReactionHorizon.mdx +2 -0
  176. package/src/ReactionHorizon.stories.tsx +3 -0
  177. package/src/ReactionHorizon.test.tsx +32 -0
  178. package/src/ReactionHorizon.tsx +28 -11
  179. package/src/RepliesRow.mdx +6 -3
  180. package/src/RepliesRow.stories.tsx +3 -0
  181. package/src/RepliesRow.test.tsx +24 -0
  182. package/src/RepliesRow.tsx +12 -6
  183. package/src/ReplyCard.mdx +8 -0
  184. package/src/ReplyCard.stories.tsx +45 -1
  185. package/src/ResolveDialog.mdx +2 -0
  186. package/src/ResolveDialog.test.tsx +21 -0
  187. package/src/ResolveDialog.tsx +11 -39
  188. package/src/SelectionToolbar.tsx +2 -2
  189. package/src/Textarea.mdx +1 -0
  190. package/src/Thread.mdx +20 -1
  191. package/src/Thread.stories.tsx +94 -3
  192. package/src/Thread.test.tsx +11 -0
  193. package/src/Thread.tsx +56 -12
  194. package/src/commentBoxFrame.tsx +2 -2
  195. package/src/conversation.examples.tsx +10 -2
  196. package/src/conversationScroll.ts +155 -0
  197. package/src/editor.ts +1 -0
  198. package/src/editorSelection.test.tsx +53 -0
  199. package/src/eslint/no-field-outside-a-form.test.ts +4 -0
  200. package/src/eslint/no-field-outside-a-form.ts +2 -2
  201. package/src/eslint/no-native-title.ts +1 -1
  202. package/src/formBusy.ts +5 -2
  203. package/src/index.ts +16 -6
  204. package/src/looks.ts +10 -0
  205. package/src/registry/registry.test.ts +12 -6
  206. package/src/seenOnScreen.test.tsx +241 -0
  207. package/src/seenOnScreen.ts +146 -0
  208. package/src/showInConversation.test.tsx +168 -0
  209. package/src/showInConversation.ts +93 -0
  210. package/src/threadCard.ts +16 -0
  211. package/stories/Choosing.mdx +8 -3
  212. package/tailwind-preset.js +7 -0
@@ -0,0 +1,186 @@
1
+ import { useEffect, useRef, useState } from 'react'
2
+ import { EmptyState } from './EmptyState'
3
+ import { Field } from './Field'
4
+ import { FormDialog } from './FormDialog'
5
+ import { Select } from './Select'
6
+
7
+ const TOP = '__top__'
8
+
9
+ /** A Folder a file may be moved to. */
10
+ export interface MoveFolder {
11
+ id: string
12
+ name: string
13
+ }
14
+
15
+ /** One place a file may be put under, in the Folder the dialog is showing. */
16
+ export interface MovePlace {
17
+ /** What it goes under: that file's address; `''` for the top of the Folder (or, for a file whose parent is one kind, none). */
18
+ id: string
19
+ /** Its breadcrumb, outermost first, ending in its own title; empty for the top. */
20
+ path: readonly string[]
21
+ }
22
+
23
+ /** Where the person put it: the Folder, and, for a file that nests, what it goes under (`''` for the top). */
24
+ export interface MoveChoice {
25
+ folder: string
26
+ parent?: string
27
+ }
28
+
29
+ /**
30
+ * Move a file: to another Folder, under another file there, or both (FOL-45)
31
+ * — Peek's MoveDialog, moved into the kit (C11, 2 November), which Leaf's
32
+ * and Ship's moves copied. The Folder first, then what it goes under there:
33
+ * two `Select`s, the second read from the first when it is picked, never for
34
+ * every Folder up front. Nothing is chosen for the person but the top, and
35
+ * only when asked (`startAtTop`): a preselected destination is a move nobody
36
+ * chose.
37
+ *
38
+ * A file that nests under nothing (no `placesIn`) is asked only for the
39
+ * Folder, and the one it is in is not offered. One that is not in exactly one
40
+ * Folder passes `from` empty, and no Folder is held back: listed in none, or
41
+ * in two after a move that half-worked, where moving into either takes it out
42
+ * of the other and Move again is the retry (Ship's rule). A Folder that could
43
+ * not be read says so as the section's empty line does, with its Try again (B8).
44
+ */
45
+ export interface MoveDialogProps {
46
+ /** The file's name, said above the choice. */
47
+ title: string
48
+ /** The sentence under the name, in the app's words: "Everyone who can read it now still can." */
49
+ description: string
50
+ /** The Folder it is in now, not offered to a file that nests under nothing. `''` when it is not in exactly one: then no Folder is held back. */
51
+ from: string
52
+ /** The Folders it may go to. Undefined while they are still read: the list says "Reading…". */
53
+ folders: readonly MoveFolder[] | undefined
54
+ /** Where it may go in `from`, already read. Absent with `placesIn`, the Folder it opens on is read at once. */
55
+ places?: readonly MovePlace[]
56
+ /** Where it may go in another Folder, read when that Folder is picked; a rejection is said beside a Try again. Absent: it nests under nothing. */
57
+ placesIn?: (folder: string) => Promise<readonly MovePlace[]>
58
+ /** Choose the top for the person when a Folder offers it: where a file that may sit at any Folder's top lands. Off: Move waits for a pick. */
59
+ startAtTop?: boolean
60
+ /** What the place with an empty `id` says. "The top of" the Folder when absent; "None — under none of these" for a file whose parent is one kind. */
61
+ topLabel?: string
62
+ /** The Folder it opens on, when that is not the one it is in. */
63
+ startIn?: string
64
+ /** The dialog's heading. "Move" when absent. */
65
+ heading?: string
66
+ /** The Folder field's label. "Folder" when absent. */
67
+ folderLabel?: string
68
+ /** Said when no Folder is offered. "There is no other folder it can be moved to." when absent. */
69
+ noFolder?: string
70
+ /** Answer `false` to keep the dialog open (you have said why); anything else closes it. */
71
+ onMove: (choice: MoveChoice) => Promise<boolean | void> | boolean | void
72
+ onClose: () => void
73
+ }
74
+
75
+ export function MoveDialog({
76
+ title,
77
+ description,
78
+ from,
79
+ folders,
80
+ places,
81
+ placesIn,
82
+ startAtTop = false,
83
+ topLabel,
84
+ startIn,
85
+ heading = 'Move',
86
+ folderLabel = 'Folder',
87
+ noFolder = 'There is no other folder it can be moved to.',
88
+ onMove,
89
+ onClose,
90
+ }: MoveDialogProps) {
91
+ const nests = !!placesIn
92
+ // Moving a file that nests under nothing into the Folder it is in would do nothing, so that one is not offered.
93
+ const destinations = folders && (nests ? folders : folders.filter((folder) => folder.id !== from))
94
+ const offered = (id: string | undefined): id is string => !!id && !!destinations?.some((candidate) => candidate.id === id)
95
+ const [pickedFolder, setPickedFolder] = useState<string>()
96
+ // Until another is picked, the one it opens on — worked out, not set at open, so Folders read after it opened still land on it.
97
+ const folder = pickedFolder ?? [startIn, from].find(offered) ?? ''
98
+ const [read, setRead] = useState<Record<string, readonly MovePlace[] | 'reading' | 'failed'>>(() => (places ? { [from]: places } : {}))
99
+ const [picked, setPicked] = useState<string>()
100
+
101
+ // The Folders read or being read, known now rather than at the next render: two picks of one Folder before its read lands read it once.
102
+ const requested = useRef(new Set(places ? [from] : []))
103
+ const readPlaces = (id: string) => {
104
+ if (!placesIn || requested.current.has(id)) return
105
+ requested.current.add(id)
106
+ setRead((current) => ({ ...current, [id]: 'reading' }))
107
+ placesIn(id).then(
108
+ (found) => setRead((current) => ({ ...current, [id]: found })),
109
+ () => {
110
+ requested.current.delete(id)
111
+ setRead((current) => ({ ...current, [id]: 'failed' }))
112
+ },
113
+ )
114
+ }
115
+ const readNow = useRef(readPlaces)
116
+ readNow.current = readPlaces
117
+ // The Folder on show is read once, after render: a pick, or the one it opens on when its places were not handed in.
118
+ useEffect(() => {
119
+ if (folder) readNow.current(folder)
120
+ }, [folder])
121
+
122
+ const chooseFolder = (id: string) => {
123
+ setPickedFolder(id)
124
+ setPicked(undefined)
125
+ }
126
+
127
+ const folderName = destinations?.find((candidate) => candidate.id === folder)?.name ?? 'this folder'
128
+ const status = nests && folder ? read[folder] : undefined
129
+ const targets = Array.isArray(status) ? (status as readonly MovePlace[]) : []
130
+ const valueOf = (place: MovePlace) => place.id || TOP
131
+ const parent = picked ?? (startAtTop && targets[0] && !targets[0].id ? TOP : undefined)
132
+ const ready = !!folder && (!nests || !!parent)
133
+
134
+ return (
135
+ <FormDialog
136
+ title={heading}
137
+ submitLabel="Move"
138
+ busyLabel="Moving…"
139
+ ready={ready}
140
+ onSubmit={() => onMove(nests ? { folder, parent: parent === TOP ? '' : parent } : { folder })}
141
+ onClose={onClose}
142
+ >
143
+ {destinations?.length === 0 ? (
144
+ <EmptyState scope="section" message={noFolder} />
145
+ ) : (
146
+ <>
147
+ {/* The name and its sentence are one block, 8px apart; the form puts 24px between it and the fields. */}
148
+ <div className="flex flex-col gap-2">
149
+ <p className="text-body-2-strong text-text-primary">{title}</p>
150
+ <p className="text-body-2 text-text-secondary">{description}</p>
151
+ </div>
152
+ <Field label={folderLabel}>
153
+ <Select
154
+ value={folder}
155
+ onChange={chooseFolder}
156
+ options={(destinations ?? []).map((candidate) => ({ value: candidate.id, label: candidate.name }))}
157
+ placeholder={destinations ? 'Pick a folder' : 'Reading…'}
158
+ ariaLabel={folderLabel}
159
+ />
160
+ </Field>
161
+ {nests &&
162
+ folder &&
163
+ (status === 'failed' ? (
164
+ <EmptyState scope="section" message={`${folderName} could not be read.`} action={{ label: 'Try again', onClick: () => readPlaces(folder) }} />
165
+ ) : Array.isArray(status) && targets.length === 0 ? (
166
+ <EmptyState scope="section" message={`There is nowhere in ${folderName} to put it.`} />
167
+ ) : (
168
+ <Field label="Put it under">
169
+ <Select
170
+ value={parent ?? ''}
171
+ onChange={setPicked}
172
+ options={targets.map((place) => ({
173
+ value: valueOf(place),
174
+ label: place.id ? place.path.join(' › ') : (topLabel ?? `The top of ${folderName}`),
175
+ }))}
176
+ placeholder={Array.isArray(status) ? 'Pick where it goes' : 'Reading…'}
177
+ disabled={!Array.isArray(status)}
178
+ ariaLabel="Put it under"
179
+ />
180
+ </Field>
181
+ ))}
182
+ </>
183
+ )}
184
+ </FormDialog>
185
+ )
186
+ }
package/src/NavItem.mdx CHANGED
@@ -66,11 +66,21 @@ count — a muted mono number whose tooltip says what it counts.
66
66
 
67
67
  <Canvas of={NavItemStories.Unread} />
68
68
 
69
+ - A row the app opens its own way, with what it already knows — beside the
70
+ list, in place — is `onPlainClick`: it runs on a plain click only, and the
71
+ link is not followed. Ctrl, Cmd, Shift, Alt and the middle button are still
72
+ the link's, a new tab, so the row keeps a real `href`.
73
+
74
+ <Canvas of={NavItemStories.OpensInPlace} />
75
+
69
76
  ## When not
70
77
 
71
78
  - An icon rail's tile → **RailItem**.
72
79
  - Switching views inside a page → **Tabs**.
73
80
  - A row in a popover → **MenuItem**.
81
+ - A plain-click check written in the row's `onClick` (`event.button`,
82
+ `metaKey`, `ctrlKey`…) → `onPlainClick`; anywhere else a link's click is
83
+ handled by hand, `isPlainClick(event)` (**AppProvider**'s page).
74
84
 
75
85
  ## How
76
86
 
@@ -105,6 +115,10 @@ import { NavItem } from '@estiva-app/ui'
105
115
  and takes its 24px slot only while it shows.
106
116
  - `active` is `bg-nav-active`, the current row in a sidebar, which each theme
107
117
  sets for itself.
118
+ - `onPlainClick` runs after `onClick`, so a click `onClick` already handled
119
+ (`preventDefault`) is left alone. Under **AppProvider** it takes `navigate`'s
120
+ place for that row; another site's address, a `target` and a `download` stay
121
+ the browser's.
108
122
 
109
123
  - A row is 32px tall, 8px in on each side, 8px between the icon and the label,
110
124
  the label 14px regular (medium when unread), 8px corners as a **MenuItem**'s.
@@ -122,6 +136,7 @@ It does these by itself. Write none of them around it.
122
136
  | Tells assistive technology whether its rows are open | `aria-expanded`, `aria-controls` | |
123
137
  | Shows `hint` only while pointed at or focused, and makes the label give way | a positioned chip over the row, `group-hover` reveals | |
124
138
  | 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 | |
139
+ | Tells a plain click from one for a new tab, for `onPlainClick` | `event.button`, `event.metaKey`, `event.ctrlKey`… read by hand in an `onClick` | |
125
140
 
126
141
  ## Keys
127
142
 
@@ -1,5 +1,6 @@
1
1
  import type { Meta, StoryObj } from '@storybook/react-vite'
2
2
  import { IconSquareRounded, IconX } from '@tabler/icons-react'
3
+ import { useState } from 'react'
3
4
  import { Chip } from './Chip'
4
5
  import { MenuItem } from './Menu'
5
6
  import { NavItem } from './NavItem'
@@ -136,3 +137,17 @@ export const WithActionAndHint: Story = {
136
137
  export const UnreadWithAction: Story = {
137
138
  args: { icon: placeholder, unread: true, action: REMOVE },
138
139
  }
140
+
141
+ /** `onPlainClick`: a plain click opens the row here, the app's own way, and the page does not change; Cmd-click or Ctrl-click is still the link's, a new tab. */
142
+ export const OpensInPlace: Story = {
143
+ render: function Render(args) {
144
+ const [opened, setOpened] = useState<string | null>(null)
145
+ return (
146
+ <>
147
+ <NavItem {...args} label="Item one" href="?opened=one" icon={placeholder} active={opened === 'Item one'} onPlainClick={() => setOpened('Item one')} />
148
+ <NavItem {...args} label="Item two" href="?opened=two" icon={placeholder} active={opened === 'Item two'} onPlainClick={() => setOpened('Item two')} />
149
+ <p className="px-2 pt-2 text-caption text-text-muted">{opened ? `Opened here: ${opened}` : 'Nothing opened here yet.'}</p>
150
+ </>
151
+ )
152
+ },
153
+ }
@@ -6,8 +6,9 @@
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, render, screen, waitFor } from '@testing-library/react'
9
+ import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
10
10
  import userEvent from '@testing-library/user-event'
11
+ import { AppProvider } from './AppProvider'
11
12
  import { NavItem } from './NavItem'
12
13
 
13
14
  afterEach(cleanup)
@@ -216,3 +217,65 @@ describe('NavItem with a tooltip', () => {
216
217
  expect((await screen.findByRole('tooltip')).textContent).toBe('Remove from list')
217
218
  })
218
219
  })
220
+
221
+ /**
222
+ * A row the app opens its own way, with what it knows, in place of following
223
+ * its link — Peek's Desk opens a file or a DM beside the list, its People page
224
+ * selects a person. Only a plain click: Ctrl, Cmd, Shift, Alt or the middle
225
+ * button is still the link's, a new tab. Peek wrote this check by hand on each
226
+ * row (`inPlace`, PersonItem); its tests' cases, moved in.
227
+ */
228
+ describe('NavItem onPlainClick', () => {
229
+ const link = () => screen.getByRole('link', { name: 'Item one' })
230
+
231
+ it('a plain click runs it in place of the link: the page does not go anywhere', () => {
232
+ const open = vi.fn()
233
+ render(<NavItem href="/app/desk?open=x" label="Item one" onPlainClick={open} />)
234
+ const followed = fireEvent.click(link())
235
+ expect(open).toHaveBeenCalledTimes(1)
236
+ expect(followed).toBe(false)
237
+ })
238
+
239
+ it('a click with Ctrl, Cmd, Shift or Alt, or the middle button, is the link’s: nothing runs here', () => {
240
+ const open = vi.fn()
241
+ render(<NavItem href="/app/desk?open=x" label="Item one" onPlainClick={open} />)
242
+ for (const keys of [{ ctrlKey: true }, { metaKey: true }, { shiftKey: true }, { altKey: true }, { button: 1 }]) {
243
+ expect(fireEvent.click(link(), keys)).toBe(true)
244
+ }
245
+ expect(open).not.toHaveBeenCalled()
246
+ })
247
+
248
+ it('under AppProvider’s navigate it takes navigate’s place: the app stays on its page', () => {
249
+ const open = vi.fn()
250
+ const navigate = vi.fn()
251
+ render(
252
+ <AppProvider navigate={navigate}>
253
+ <NavItem href="/app/people/dm-1" label="Item one" onPlainClick={open} />
254
+ </AppProvider>,
255
+ )
256
+ fireEvent.click(link())
257
+ expect(open).toHaveBeenCalledTimes(1)
258
+ expect(navigate).not.toHaveBeenCalled()
259
+ fireEvent.click(link(), { metaKey: true })
260
+ expect(open).toHaveBeenCalledTimes(1)
261
+ expect(navigate).not.toHaveBeenCalled()
262
+ })
263
+
264
+ it('the row’s own onClick runs first, and a click it handled is left alone', () => {
265
+ const open = vi.fn()
266
+ render(<NavItem href="/app/desk" label="Item one" onClick={(event) => event.preventDefault()} onPlainClick={open} />)
267
+ fireEvent.click(link())
268
+ expect(open).not.toHaveBeenCalled()
269
+ })
270
+
271
+ it('another site’s address, a link that opens elsewhere, or one that downloads is not opened here', () => {
272
+ const open = vi.fn()
273
+ const { rerender } = render(<NavItem href="https://elsewhere.test/file" label="Item one" onPlainClick={open} />)
274
+ expect(fireEvent.click(link())).toBe(true)
275
+ rerender(<NavItem href="/app/desk" target="_blank" label="Item one" onPlainClick={open} />)
276
+ expect(fireEvent.click(link())).toBe(true)
277
+ rerender(<NavItem href="/app/file.pdf" download label="Item one" onPlainClick={open} />)
278
+ expect(fireEvent.click(link())).toBe(true)
279
+ expect(open).not.toHaveBeenCalled()
280
+ })
281
+ })
package/src/NavItem.tsx CHANGED
@@ -1,4 +1,4 @@
1
- import { useId, useState, type ComponentPropsWithoutRef, type ReactNode } from 'react'
1
+ import { useId, useState, type ComponentPropsWithoutRef, type MouseEvent, type ReactNode } from 'react'
2
2
  import { Collapsible } from '@base-ui/react/collapsible'
3
3
  import { IconChevronRight, IconDotsVertical } from '@tabler/icons-react'
4
4
  import { UrgentMark } from './UrgentMark'
@@ -93,6 +93,13 @@ export interface NavItemProps extends Omit<ComponentPropsWithoutRef<'a'>, 'href'
93
93
  * hand, it stays closed until another opens. `NavTree` passes it.
94
94
  */
95
95
  openFor?: string
96
+ /**
97
+ * A plain click on the row — the main button, no Ctrl, Cmd, Shift or Alt, to
98
+ * this app's own address: the app opens it its own way, with what it knows,
99
+ * in place of following the link (the row prevents it, and `navigate` is not
100
+ * called). Any other click is still the link's: a new tab. After `onClick`.
101
+ */
102
+ onPlainClick?: (event: MouseEvent<HTMLAnchorElement>) => void
96
103
  className?: string
97
104
  }
98
105
 
@@ -115,11 +122,12 @@ export function NavItem({
115
122
  open: openProp,
116
123
  onOpenChange,
117
124
  openFor,
125
+ onPlainClick,
118
126
  className,
119
127
  onClick,
120
128
  ...props
121
129
  }: NavItemProps) {
122
- const inApp = useInAppClick(href, onClick)
130
+ const inApp = useInAppClick(href, onClick, onPlainClick)
123
131
  const [openState, setOpenState] = useState(defaultOpen)
124
132
  const panelId = useId()
125
133
  const hasRows = children != null && children !== false
package/src/NavTree.mdx CHANGED
@@ -29,9 +29,18 @@ rows to any depth.
29
29
 
30
30
  - In a new tab, where nothing is open yet, the same: the row is in sight
31
31
  when the tree is drawn.
32
+ - `selectedGroup` is the group a link led to — a folder's own link: each
33
+ time it names a new group, the group opens, closed by hand too, and the
34
+ column scrolls to it at once. Once per arrival, and it marks nothing. It is
35
+ remembered open as a click would be, open already or not, so it stays open
36
+ when the reader goes on to a row in another group. A group open only
37
+ because the current row is in it is never written down: it closes again
38
+ once the row goes.
32
39
 
33
40
  <Canvas of={NavTreeStories.InANewTab} />
34
41
 
42
+ <Canvas of={NavTreeStories.OpensOntoAGroup} />
43
+
35
44
  - `selectedParent` is the row the current one sits under, while the tree
36
45
  does not draw the current one. Its rows are read only when it opens: the
37
46
  tree opens onto it and opens it, and marks the current row once it is in.
@@ -80,11 +89,16 @@ rows to any depth.
80
89
  pointer rests on it or the keyboard reached it: read it then, so opening
81
90
  it draws rows. A `NavTreeSection` opened while its read is in flight takes
82
91
  `pending`: its arrow turns and it opens once the rows are in, in one move,
83
- instead of a skeleton the rows then replace; keep `loading` for a read
84
- that turns out slow.
92
+ instead of a skeleton the rows then replace. A read still out after 2
93
+ seconds (`NAV_TREE_PENDING_MS`) is a slow one: the group opens on
94
+ `loading`'s skeleton by itself, until the rows are in — no timer of the
95
+ app's own. Keep `loading` for a group whose rows are being read while it
96
+ is already open.
85
97
 
86
98
  <Canvas of={NavTreeStories.ReadAsItOpens} />
87
99
 
100
+ <Canvas of={NavTreeStories.PendingThenLoading} />
101
+
88
102
  - An app whose groups and rows each read their own data draws the groups
89
103
  itself: leave out `groups` and pass **NavTreeSection**s as children, each
90
104
  with **NavItem** rows. A `NavTreeSection` is one group exactly as `groups`
@@ -125,10 +139,16 @@ import { NavTree, Sidebar } from '@estiva-app/ui'
125
139
  - `storageKey` remembers each group open or closed in this browser, under
126
140
  the key and the group's id — a group opened for the current row is
127
141
  remembered open, as a click would be. The rows under a row are not
128
- remembered yet.
142
+ remembered yet. Groups and rows the app draws itself, whose rows are read
143
+ only once open, take `useRememberedOpen` on their `open` and
144
+ `onOpenChange`: the same memory, known before anything is read
145
+ (**CollapsibleSection**'s page).
129
146
  - Groups the app draws itself open for the current row through `openFor` on
130
147
  each **NavTreeSection** and **NavItem** that holds it; the scroll is the
131
- tree's either way, given `selected`.
148
+ tree's either way, given `selected`. A group a link led to needs nothing
149
+ more than its **NavTreeSection**'s `id`: given `selectedGroup`, the tree
150
+ opens it, remembers it open (through `onOpenChange` when you hold it) and
151
+ scrolls to it.
132
152
  - The words in `emptyMessage` are the caller's.
133
153
 
134
154
  ## What it owns
@@ -139,8 +159,10 @@ It does these by itself. Write none of them around it.
139
159
  |---|---|---|
140
160
  | Draws every level from one list, rows under rows | a recursive render of **NavItem**s and **CollapsibleSection**s | |
141
161
  | Opens the group and the rows above the current row, once per row, and scrolls to it | a search through the list for the current row, an effect that opens it, a scroll into view | |
162
+ | Opens the group a link led to, once per arrival, and scrolls to it | an effect that opens it, a `querySelector` and a scroll into view | |
142
163
  | Says it is loading, or empty, in the rows' place | a skeleton or an **EmptyState** placed by hand | |
143
164
  | Says when the pointer rests on a group, 150ms, and not while it sweeps past | a timer on pointer enter and leave | |
165
+ | Holds a `pending` group shut for 2s, then opens it on the skeleton | a timer from pending to loading, a skeleton of the app's own, a pulsing icon | |
144
166
 
145
167
  ## Keys
146
168
 
@@ -187,6 +187,41 @@ export const AppDrawnGroups: Story = {
187
187
  },
188
188
  }
189
189
 
190
+ /** A group the app draws, its rows read when it opens: pending while the read is out, and once it has taken `NAV_TREE_PENDING_MS` the skeleton. */
191
+ function ReadOnOpen({ title, ms }: { title: string; ms: number }) {
192
+ const [open, setOpen] = useState(false)
193
+ const [rows, setRows] = useState<'out' | 'reading' | 'in'>('out')
194
+ const toggle = (next: boolean) => {
195
+ setOpen(next)
196
+ if (!next || rows !== 'out') return
197
+ setRows('reading')
198
+ setTimeout(() => setRows('in'), ms)
199
+ }
200
+ return (
201
+ <NavTreeSection title={title} icon={folder} open={open} onOpenChange={toggle} pending={open && rows === 'reading'}>
202
+ <NavItem href="#" label="Item one" icon={placeholder} />
203
+ <NavItem href="#" label="Item two" icon={placeholder} />
204
+ </NavTreeSection>
205
+ )
206
+ }
207
+
208
+ /** Open each group: the first's rows take 0.8s, and it opens once with them; the second's take 5s, and after 2s it opens on the skeleton until they are in. Reload to read again. */
209
+ export const PendingThenLoading: Story = {
210
+ args: { groups: undefined },
211
+ render: function Render(args) {
212
+ return (
213
+ <div className="flex h-screen bg-bg-base">
214
+ <Sidebar>
215
+ <NavTree title={args.title}>
216
+ <ReadOnOpen title="A quick read" ms={800} />
217
+ <ReadOnOpen title="A slow read" ms={5000} />
218
+ </NavTree>
219
+ </Sidebar>
220
+ </div>
221
+ )
222
+ },
223
+ }
224
+
190
225
  /*
191
226
  Opening a row shows where it lives (Katerina, 30 October): its group and the
192
227
  rows above it open, the row is marked, and the column scrolls to it.
@@ -237,6 +272,30 @@ export const OpensOntoTheCurrentRow: Story = {
237
272
  },
238
273
  }
239
274
 
275
+ /** A link to a group — a folder's own: it opens, closed by hand too, and the column scrolls to it at once. Close it: it stays closed until a link leads to it again. Nothing is marked. */
276
+ export const OpensOntoAGroup: Story = {
277
+ args: { groups: SHUT_GROUPS, selected: undefined },
278
+ render: function Render(args) {
279
+ const [group, setGroup] = useState<string | undefined>(undefined)
280
+ // Each press is a new arrival, as a link followed again is.
281
+ const follow = (id: string) => {
282
+ setGroup(undefined)
283
+ setTimeout(() => setGroup(id))
284
+ }
285
+ return (
286
+ <div className="flex h-screen bg-bg-base">
287
+ <Sidebar>
288
+ <NavTree {...args} selectedGroup={group} />
289
+ </Sidebar>
290
+ <Page>
291
+ <Button variant="outlined" size="small" onClick={() => follow('s8')}>Follow a link to Group eight</Button>
292
+ <Button variant="outlined" size="small" onClick={() => follow('s2')}>Follow a link to Group two</Button>
293
+ </Page>
294
+ </div>
295
+ )
296
+ },
297
+ }
298
+
240
299
  /** A new tab, where nothing is open yet: each button starts the column again, every group shut, and opens onto its row. */
241
300
  export const InANewTab: Story = {
242
301
  args: { groups: SHUT_GROUPS, selected: undefined },