@estiva-app/ui 0.98.0 → 0.99.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 (193) hide show
  1. package/README.md +1 -1
  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 +6 -1
  19. package/dist/ConversationCard.d.ts.map +1 -1
  20. package/dist/ConversationLayout.d.ts +19 -4
  21. package/dist/ConversationLayout.d.ts.map +1 -1
  22. package/dist/ConversationPlace.d.ts +17 -0
  23. package/dist/ConversationPlace.d.ts.map +1 -0
  24. package/dist/DocumentEditor.d.ts +38 -0
  25. package/dist/DocumentEditor.d.ts.map +1 -1
  26. package/dist/DocumentField.d.ts +50 -0
  27. package/dist/DocumentField.d.ts.map +1 -0
  28. package/dist/EditableText.d.ts +38 -4
  29. package/dist/EditableText.d.ts.map +1 -1
  30. package/dist/EmptyState.d.ts +10 -5
  31. package/dist/EmptyState.d.ts.map +1 -1
  32. package/dist/FormDialog.d.ts +38 -0
  33. package/dist/FormDialog.d.ts.map +1 -0
  34. package/dist/InlineText.d.ts.map +1 -1
  35. package/dist/MoveDialog.d.ts +61 -0
  36. package/dist/MoveDialog.d.ts.map +1 -0
  37. package/dist/NavItem.d.ts +9 -2
  38. package/dist/NavItem.d.ts.map +1 -1
  39. package/dist/NavTree.d.ts +16 -3
  40. package/dist/NavTree.d.ts.map +1 -1
  41. package/dist/PinnedComment.d.ts +3 -1
  42. package/dist/PinnedComment.d.ts.map +1 -1
  43. package/dist/ReactionHorizon.d.ts +5 -1
  44. package/dist/ReactionHorizon.d.ts.map +1 -1
  45. package/dist/ResolveDialog.d.ts +3 -1
  46. package/dist/ResolveDialog.d.ts.map +1 -1
  47. package/dist/SelectionToolbar.d.ts +2 -2
  48. package/dist/Thread.d.ts +6 -3
  49. package/dist/Thread.d.ts.map +1 -1
  50. package/dist/commentBoxFrame.d.ts.map +1 -1
  51. package/dist/conversation.examples.d.ts +4 -1
  52. package/dist/conversation.examples.d.ts.map +1 -1
  53. package/dist/conversationScroll.d.ts +80 -0
  54. package/dist/conversationScroll.d.ts.map +1 -0
  55. package/dist/editor.d.ts +1 -0
  56. package/dist/editor.d.ts.map +1 -1
  57. package/dist/editor.js +228 -69
  58. package/dist/editor.js.map +4 -4
  59. package/dist/eslint/index.js +2 -2
  60. package/dist/eslint/index.js.map +2 -2
  61. package/dist/eslint/no-field-outside-a-form.d.ts +2 -2
  62. package/dist/eslint/no-field-outside-a-form.d.ts.map +1 -1
  63. package/dist/eslint/no-native-title.d.ts +1 -1
  64. package/dist/eslint/no-native-title.d.ts.map +1 -1
  65. package/dist/formBusy.d.ts +5 -2
  66. package/dist/formBusy.d.ts.map +1 -1
  67. package/dist/index.d.ts +14 -6
  68. package/dist/index.d.ts.map +1 -1
  69. package/dist/index.js +2210 -1458
  70. package/dist/index.js.map +4 -4
  71. package/dist/looks.d.ts +8 -0
  72. package/dist/looks.d.ts.map +1 -1
  73. package/dist/seenOnScreen.d.ts +27 -0
  74. package/dist/seenOnScreen.d.ts.map +1 -0
  75. package/dist/showInConversation.d.ts +31 -0
  76. package/dist/showInConversation.d.ts.map +1 -0
  77. package/dist/threadCard.d.ts +13 -0
  78. package/dist/threadCard.d.ts.map +1 -1
  79. package/package.json +1 -1
  80. package/registry.json +904 -139
  81. package/src/AppProvider.mdx +4 -0
  82. package/src/AppProvider.test.tsx +34 -2
  83. package/src/AppProvider.tsx +17 -6
  84. package/src/ArchiveDialog.mdx +70 -0
  85. package/src/ArchiveDialog.stories.tsx +64 -0
  86. package/src/ArchiveDialog.test.tsx +90 -0
  87. package/src/ArchiveDialog.tsx +70 -0
  88. package/src/AttachedCard.mdx +6 -0
  89. package/src/AttachedCard.stories.tsx +9 -1
  90. package/src/AttachedCard.test.tsx +111 -2
  91. package/src/AttachedCard.tsx +77 -7
  92. package/src/Card.mdx +20 -1
  93. package/src/Card.stories.tsx +20 -0
  94. package/src/Card.test.tsx +87 -1
  95. package/src/Card.tsx +51 -3
  96. package/src/ChipInput.mdx +7 -1
  97. package/src/ChipInput.stories.tsx +9 -0
  98. package/src/ChipInput.test.tsx +42 -0
  99. package/src/ChipInput.tsx +7 -3
  100. package/src/CollapsibleSection.mdx +20 -1
  101. package/src/CollapsibleSection.stories.tsx +19 -1
  102. package/src/CollapsibleSection.test.tsx +85 -2
  103. package/src/CollapsibleSection.tsx +54 -15
  104. package/src/CommentBox.mdx +2 -1
  105. package/src/CommentBox.test.tsx +81 -1
  106. package/src/CommentBox.tsx +32 -11
  107. package/src/ConfirmDialog.mdx +25 -3
  108. package/src/ConfirmDialog.stories.tsx +27 -0
  109. package/src/ConfirmDialog.test.tsx +87 -1
  110. package/src/ConfirmDialog.tsx +39 -8
  111. package/src/ConversationCard.mdx +4 -0
  112. package/src/ConversationCard.stories.tsx +11 -1
  113. package/src/ConversationCard.test.tsx +116 -0
  114. package/src/ConversationCard.tsx +53 -36
  115. package/src/ConversationLayout.mdx +30 -4
  116. package/src/ConversationLayout.scroll.test.tsx +411 -0
  117. package/src/ConversationLayout.stories.tsx +79 -1
  118. package/src/ConversationLayout.test.tsx +79 -0
  119. package/src/ConversationLayout.tsx +136 -15
  120. package/src/ConversationPlace.mdx +53 -0
  121. package/src/ConversationPlace.stories.tsx +48 -0
  122. package/src/ConversationPlace.test.tsx +51 -0
  123. package/src/ConversationPlace.tsx +30 -0
  124. package/src/DocumentEditor.mdx +2 -1
  125. package/src/DocumentEditor.tsx +118 -64
  126. package/src/DocumentField.mdx +83 -0
  127. package/src/DocumentField.stories.tsx +110 -0
  128. package/src/DocumentField.test.tsx +281 -0
  129. package/src/DocumentField.tsx +199 -0
  130. package/src/EditableText.buttons.test.tsx +318 -0
  131. package/src/EditableText.mdx +50 -2
  132. package/src/EditableText.stories.tsx +96 -2
  133. package/src/EditableText.tsx +189 -5
  134. package/src/EmptyState.mdx +33 -8
  135. package/src/EmptyState.stories.tsx +26 -1
  136. package/src/EmptyState.test.tsx +63 -2
  137. package/src/EmptyState.tsx +28 -6
  138. package/src/Form.mdx +3 -1
  139. package/src/FormDialog.mdx +78 -0
  140. package/src/FormDialog.stories.tsx +90 -0
  141. package/src/FormDialog.test.tsx +183 -0
  142. package/src/FormDialog.tsx +93 -0
  143. package/src/InlineText.mdx +1 -0
  144. package/src/InlineText.tsx +2 -1
  145. package/src/MoveDialog.mdx +74 -0
  146. package/src/MoveDialog.stories.tsx +121 -0
  147. package/src/MoveDialog.test.tsx +203 -0
  148. package/src/MoveDialog.tsx +183 -0
  149. package/src/NavItem.mdx +15 -0
  150. package/src/NavItem.stories.tsx +15 -0
  151. package/src/NavItem.test.tsx +64 -1
  152. package/src/NavItem.tsx +10 -2
  153. package/src/NavTree.mdx +26 -4
  154. package/src/NavTree.stories.tsx +59 -0
  155. package/src/NavTree.test.tsx +232 -2
  156. package/src/NavTree.tsx +93 -43
  157. package/src/PinnedComment.mdx +6 -1
  158. package/src/PinnedComment.stories.tsx +11 -1
  159. package/src/PinnedComment.tsx +15 -2
  160. package/src/ReactionHorizon.mdx +3 -0
  161. package/src/ReactionHorizon.stories.tsx +3 -0
  162. package/src/ReactionHorizon.test.tsx +55 -0
  163. package/src/ReactionHorizon.tsx +30 -11
  164. package/src/ReplyCard.mdx +3 -0
  165. package/src/ReplyCard.stories.tsx +19 -1
  166. package/src/ResolveDialog.mdx +2 -0
  167. package/src/ResolveDialog.test.tsx +21 -0
  168. package/src/ResolveDialog.tsx +11 -39
  169. package/src/SelectionToolbar.tsx +2 -2
  170. package/src/Textarea.mdx +1 -0
  171. package/src/Thread.mdx +18 -1
  172. package/src/Thread.stories.tsx +55 -3
  173. package/src/Thread.test.tsx +11 -0
  174. package/src/Thread.tsx +53 -11
  175. package/src/commentBoxFrame.tsx +2 -2
  176. package/src/conversation.examples.tsx +10 -2
  177. package/src/conversationScroll.ts +155 -0
  178. package/src/editor.ts +1 -0
  179. package/src/editorSelection.test.tsx +53 -0
  180. package/src/eslint/no-field-outside-a-form.test.ts +4 -0
  181. package/src/eslint/no-field-outside-a-form.ts +2 -2
  182. package/src/eslint/no-native-title.ts +1 -1
  183. package/src/formBusy.ts +5 -2
  184. package/src/index.ts +16 -6
  185. package/src/looks.ts +10 -0
  186. package/src/registry/registry.test.ts +12 -6
  187. package/src/seenOnScreen.test.tsx +182 -0
  188. package/src/seenOnScreen.ts +146 -0
  189. package/src/showInConversation.test.tsx +168 -0
  190. package/src/showInConversation.ts +93 -0
  191. package/src/threadCard.ts +16 -0
  192. package/stories/Choosing.mdx +7 -2
  193. package/tailwind-preset.js +7 -0
@@ -1,7 +1,26 @@
1
1
  import { useEffect, useRef, useState, type KeyboardEvent, type ReactNode, type RefObject } from 'react'
2
2
  import { Field as BaseField } from '@base-ui/react/field'
3
3
  import { Input } from '@base-ui/react/input'
4
+ import { IconPencil, IconPlus } from '@tabler/icons-react'
5
+ import { Button } from './Button'
4
6
  import { cn } from './cn'
7
+ import { EmptyState } from './EmptyState'
8
+ import { FieldLine, type FieldLineTone } from './Field'
9
+ import { Form } from './Form'
10
+ import { Textarea } from './Textarea'
11
+ import { TextInput } from './TextInput'
12
+
13
+ /** What happened to a save, to say under it: `error` keeps the field open, `warning` saved. Said in a `FieldLine` of that tone. */
14
+ export interface EditableTextOutcome {
15
+ kind: Exclude<FieldLineTone, 'helper'>
16
+ message: string
17
+ }
18
+
19
+ /** A commit's answer: `true` saved, `false` refused (you have said why), or an outcome to say under it. */
20
+ export type EditableTextAnswer = boolean | EditableTextOutcome
21
+
22
+ /** Saved: `true`, or an outcome that is not a refusal. */
23
+ const saved = (answer: EditableTextAnswer | undefined) => answer === true || (typeof answer === 'object' && answer.kind !== 'error')
5
24
 
6
25
  /**
7
26
  * Text you click to edit — Ship's EditableText (2026-09-01), verbatim. Its
@@ -22,11 +41,16 @@ import { cn } from './cn'
22
41
  */
23
42
  export interface EditableTextProps {
24
43
  value: string
44
+ /** What shows, muted, while the value is empty; in `buttons`, as the kit's empty line for one part of a page (12px). */
25
45
  placeholder: string
26
- /** Resolve `true` when saved; `false` (or throw) keeps the field open with the text. */
27
- onCommit: (value: string) => Promise<boolean> | boolean
46
+ /**
47
+ * Resolve `true` when saved; `false` (or throw) keeps the field open with
48
+ * the text. Or an outcome: `error` keeps it open, `warning` saved; `buttons`
49
+ * says either under it, and a throw's own words as an `error`.
50
+ */
51
+ onCommit: (value: string) => Promise<EditableTextAnswer> | EditableTextAnswer
28
52
  multiline?: boolean
29
- /** Applied to both the text and the field, so they are the same size. */
53
+ /** Applied to both the text and the field, so they are the same size. In `buttons`, placement only: it goes on the whole. */
30
54
  className?: string
31
55
  /** The accessible name of the field — "Title", "Description". */
32
56
  label: string
@@ -61,9 +85,34 @@ export interface EditableTextProps {
61
85
  displayNode?: ReactNode
62
86
  /** Show the value only — no edit affordance. For a reader who cannot write. */
63
87
  readOnly?: boolean
88
+ /**
89
+ * How it is edited. `inline`, the default: the text is the button, and
90
+ * leaving the field saves. `buttons`: the text with a button beside it, a
91
+ * field with Save and Cancel, and what happened said under it — an edit to
92
+ * confirm, in a dialog (Peek's Details, 2 November).
93
+ */
94
+ manner?: 'inline' | 'buttons'
95
+ /** `buttons`: the words on the button that opens the field — "Rename". "Edit" when absent. */
96
+ editLabel?: string
97
+ /** `buttons`: its words while the value is empty, with a plus — "Add a summary". `editLabel` when absent. */
98
+ addLabel?: string
99
+ /** `buttons`: the field's own placeholder, while it is edited. */
100
+ fieldPlaceholder?: string
101
+ /** `buttons`: an empty value cannot be saved, as a name cannot. */
102
+ required?: boolean
103
+ /** `buttons`: what a draft becomes before it is compared and saved — one line, say. Trimmed when absent. */
104
+ clean?: (draft: string) => string
105
+ /** `buttons`: said between the field and its buttons as it is typed — a count past a limit. */
106
+ draftNote?: (draft: string) => ReactNode
107
+ /** `buttons`: opens as the field, holding the value — a menu's Rename. */
108
+ defaultEditing?: boolean
64
109
  }
65
110
 
66
- export function EditableText({ value, display, displayNode, placeholder, onCommit, multiline = false, className, label, readOnly = false }: EditableTextProps) {
111
+ export function EditableText(props: EditableTextProps) {
112
+ return props.manner === 'buttons' ? <WithButtons {...props} /> : <Inline {...props} />
113
+ }
114
+
115
+ function Inline({ value, display, displayNode, placeholder, onCommit, multiline = false, className, label, readOnly = false }: EditableTextProps) {
67
116
  const [editing, setEditing] = useState(false)
68
117
  const [draft, setDraft] = useState(value)
69
118
  const [busy, setBusy] = useState(false)
@@ -96,7 +145,7 @@ export function EditableText({ value, display, displayNode, placeholder, onCommi
96
145
  setBusy(true)
97
146
  try {
98
147
  const ok = await onCommit(next)
99
- if (ok) setEditing(false)
148
+ if (ok && saved(ok)) setEditing(false)
100
149
  } catch {
101
150
  /* the caller has shown why; keep the field open */
102
151
  } finally {
@@ -185,3 +234,138 @@ export function EditableText({ value, display, displayNode, placeholder, onCommi
185
234
  </button>
186
235
  )
187
236
  }
237
+
238
+ /**
239
+ * The `buttons` manner, Peek's Details drawn exactly (C13, 2 November): the
240
+ * text and its button in one row; the field with Save and Cancel beside it on
241
+ * one line, under it when `multiline`; what happened said under the field
242
+ * (8px), or under the text once it closed (12px). Escape in the field abandons
243
+ * the edit and nothing else: the dialog around it stays.
244
+ */
245
+ function WithButtons({
246
+ value,
247
+ display,
248
+ displayNode,
249
+ placeholder,
250
+ onCommit,
251
+ multiline = false,
252
+ className,
253
+ label,
254
+ readOnly = false,
255
+ editLabel = 'Edit',
256
+ addLabel,
257
+ fieldPlaceholder,
258
+ required = false,
259
+ clean = (draft: string) => draft.trim(),
260
+ draftNote,
261
+ defaultEditing = false,
262
+ }: EditableTextProps) {
263
+ const [editing, setEditing] = useState(defaultEditing && !readOnly)
264
+ const [draft, setDraft] = useState(value)
265
+ const [outcome, setOutcome] = useState<EditableTextOutcome | null>(null)
266
+ const [busy, setBusy] = useState(false)
267
+
268
+ const cleaned = clean(draft)
269
+ // A refused text can be sent again as it is: the refusal may have been the moment's, not the text's.
270
+ const canSave = (!required || cleaned !== '') && (cleaned !== clean(value) || outcome?.kind === 'error')
271
+
272
+ const open = () => {
273
+ setDraft(value)
274
+ setEditing(true)
275
+ }
276
+ const cancel = () => {
277
+ setEditing(false)
278
+ setOutcome(null)
279
+ }
280
+ const save = async () => {
281
+ if (!canSave || busy) return
282
+ setBusy(true)
283
+ let answer: EditableTextAnswer
284
+ try {
285
+ answer = await onCommit(cleaned)
286
+ } catch (error) {
287
+ // Nothing may leave this stuck on "Saving…"; a throw with words says them.
288
+ answer = error instanceof Error && error.message ? { kind: 'error', message: error.message } : false
289
+ } finally {
290
+ setBusy(false)
291
+ }
292
+ setOutcome(typeof answer === 'object' ? answer : null)
293
+ // Only a refusal keeps the field open; the draft is kept on one.
294
+ if (saved(answer)) setEditing(false)
295
+ }
296
+ const onKeyDown = (event: KeyboardEvent<HTMLInputElement | HTMLTextAreaElement>) => {
297
+ if (event.key !== 'Escape') return
298
+ // Escape abandons the edit, and only the edit: a dialog around it stays for a second Escape. Enter is the form's, and saves.
299
+ event.preventDefault()
300
+ event.stopPropagation()
301
+ cancel()
302
+ }
303
+ const type = (next: string) => {
304
+ setDraft(next)
305
+ // Changing a refused text is a new attempt: the old reason goes.
306
+ if (outcome?.kind === 'error') setOutcome(null)
307
+ }
308
+ const line = outcome && <FieldLine tone={outcome.kind}>{outcome.message}</FieldLine>
309
+
310
+ if (editing) {
311
+ const buttons = (
312
+ <>
313
+ <Button variant="primary" size="small" type="submit" disabled={!canSave || busy}>
314
+ {busy ? 'Saving…' : 'Save'}
315
+ </Button>
316
+ <Button variant="outlined" size="small" onClick={cancel}>
317
+ Cancel
318
+ </Button>
319
+ </>
320
+ )
321
+ return (
322
+ // The package Form: Enter in the one-line field saves, Ctrl+Enter from the text area; it locks while saving.
323
+ <Form busy={busy} onSubmit={save} layout="free" className={cn('flex flex-col gap-2', className)}>
324
+ {multiline ? (
325
+ <>
326
+ <Textarea autoFocus rows={4} value={draft} onChange={(event) => type(event.target.value)} aria-label={label} placeholder={fieldPlaceholder} onKeyDown={onKeyDown} />
327
+ {draftNote?.(draft)}
328
+ <div className="flex items-center gap-2">{buttons}</div>
329
+ </>
330
+ ) : (
331
+ <>
332
+ <div className="flex items-center gap-2">
333
+ <TextInput autoFocus value={draft} onChange={(event) => type(event.target.value)} aria-label={label} placeholder={fieldPlaceholder} onKeyDown={onKeyDown} />
334
+ {buttons}
335
+ </div>
336
+ {draftNote?.(draft)}
337
+ </>
338
+ )}
339
+ {line}
340
+ </Form>
341
+ )
342
+ }
343
+
344
+ const shown = display ?? value
345
+ return (
346
+ <div className={cn('flex flex-col gap-3', className)}>
347
+ <div className={cn('flex gap-2', multiline ? 'items-start' : 'items-center')}>
348
+ {!shown ? (
349
+ // Nothing yet: the kit's empty line for one part of a page, 12px and muted, as Peek's "No summary yet." (2 November).
350
+ <EmptyState scope="section" message={placeholder} className="min-w-0 flex-1" />
351
+ ) : multiline ? (
352
+ <p className="min-w-0 flex-1 break-words text-body-2 text-text-primary">{displayNode ?? shown}</p>
353
+ ) : (
354
+ <span className="min-w-0 flex-1 truncate text-body-2 text-text-primary">{displayNode ?? shown}</span>
355
+ )}
356
+ {/* Absent, not disabled, for a reader who cannot write. */}
357
+ {!readOnly && (
358
+ <Button
359
+ variant="outlined"
360
+ size="small"
361
+ leadingIcon={value || !addLabel ? <IconPencil size={14} stroke={1.5} /> : <IconPlus size={14} stroke={1.5} />}
362
+ onClick={open}
363
+ >
364
+ {value || !addLabel ? editLabel : addLabel}
365
+ </Button>
366
+ )}
367
+ </div>
368
+ {line}
369
+ </div>
370
+ )
371
+ }
@@ -5,9 +5,10 @@ import * as EmptyStateStories from './EmptyState.stories'
5
5
 
6
6
  # EmptyState
7
7
 
8
- The place where content will be once there is some, in two manners: a
8
+ The place where content will be once there is some, in three manners: a
9
9
  16px icon over a centred line when the whole page is empty, the line
10
- alone and left-aligned when one section of a page is.
10
+ alone and left-aligned when one section of a page is, and that line in a
11
+ row's inset in place of a sidebar's rows.
11
12
 
12
13
  <Canvas of={EmptyStateStories.Page} />
13
14
 
@@ -24,6 +25,14 @@ alone and left-aligned when one section of a page is.
24
25
 
25
26
  <Canvas of={EmptyStateStories.Section} />
26
27
 
28
+ - **`rows`** — a list of rows that pad themselves is empty, or could not be
29
+ read: a sidebar's **NavItem**s in a **CollapsibleSection** or under a row.
30
+ The `section` line in their place, in a row's inset — 8px in, 4px over and
31
+ under — so it starts where a row does. **NavTree** says its own lines this
32
+ way.
33
+
34
+ <Canvas of={EmptyStateStories.Rows} />
35
+
27
36
  The page decides, not the size of the box: a whole page with one short
28
37
  message is still a `page`; a tall section with nothing in it is still a
29
38
  `section`. The message says **what would fill it** — "No comments yet.
@@ -43,6 +52,8 @@ need a height from the caller (`className="h-full"`).
43
52
  - Something went wrong → say what failed, in words. An EmptyState can carry
44
53
  it, in its usual look — never red. An empty state that hides a failure
45
54
  misleads.
55
+ - A box of your own giving a `section` line a row's inset (`px-2 py-1`) →
56
+ `rows`, which is that box.
46
57
 
47
58
  ## How
48
59
 
@@ -54,13 +65,17 @@ import { EmptyState } from '@estiva-app/ui'
54
65
 
55
66
  // one section of a page
56
67
  <EmptyState scope="section" message="No comments yet." />
68
+
69
+ // in place of a sidebar's rows
70
+ <CollapsibleSection title="Starred">
71
+ {starred.length ? starred.map((row) => <NavItem key={row.id} {...row} />) : <EmptyState scope="rows" message="Nothing starred yet." />}
72
+ </CollapsibleSection>
57
73
  ```
58
74
 
59
- **When there is one thing to do about it, give it as `action`.** It is drawn
60
- 16px under the line as the package's Button, outlined — the same look wherever
61
- it appears. Never put a Button beside an EmptyState in a
62
- box of your own: the box places it, and no two boxes place it alike. A `page`
63
- only; a section's line takes no action.
75
+ **When there is one thing to do about it, give it as `action`.** On a `page`
76
+ it is drawn 16px under the line as the package's Button, outlined. Never put a
77
+ Button beside an EmptyState in a box of your own: the box places it, and no two
78
+ boxes place it alike.
64
79
 
65
80
  <Canvas of={EmptyStateStories.WithAction} />
66
81
 
@@ -68,6 +83,16 @@ only; a section's line takes no action.
68
83
  <EmptyState icon={<IconMessagePlus size={16} stroke={1.5} />} message="Nothing here yet." action={{ label: 'Create', onClick: create }} />
69
84
  ```
70
85
 
86
+ On a `section` it sits at the end of the line, the package's Button, muted. A
87
+ part that could not be read says so this way, with its Try again, so it reads
88
+ as the empty line beside it does.
89
+
90
+ <Canvas of={EmptyStateStories.SectionWithAction} />
91
+
92
+ ```tsx
93
+ <EmptyState scope="section" message={`${folder} could not be read.`} action={{ label: 'Try again', onClick: retry }} />
94
+ ```
95
+
71
96
  **Put a section's empty state inside the box its rows live in, and give it no
72
97
  padding.** Write the box once; inside it goes either the rows or the empty
73
98
  state. The box's padding then places both, and the line starts where the first
@@ -96,7 +121,7 @@ It does these by itself. Write none of them around it.
96
121
  |---|---|---|
97
122
  | As a `page`, fills the room it is given and centres itself in it | centring, or padding around it | a box of its own that centres or pads a `page`, and a `page` inside a `ScrollArea`, where it cannot centre (`estiva/no-handmade-empty-state`) |
98
123
  | Says a list is empty, in place of its rows | a paragraph or span of your own saying so | `estiva/no-handmade-empty-state` |
99
- | Draws its one action, an outlined Button, under the line when you pass `action` | a button of your own under the line | |
124
+ | Draws its one action when you pass `action`: an outlined Button under a page's line, a muted one at the end of a section's | a button of your own beside the line | |
100
125
 
101
126
  ## Props
102
127
 
@@ -1,6 +1,8 @@
1
1
  import type { Decorator, Meta, StoryObj } from '@storybook/react-vite'
2
- import { IconLock, IconMessagePlus } from '@tabler/icons-react'
2
+ import { IconLock, IconMessagePlus, IconSquareRounded } from '@tabler/icons-react'
3
+ import { CollapsibleSection } from './CollapsibleSection'
3
4
  import { EmptyState } from './EmptyState'
5
+ import { NavItem } from './NavItem'
4
6
 
5
7
  // A box with a hairline, so where the state sits inside its room can be seen: a page's in the middle both ways, a section's at the top left.
6
8
  const inBox: Decorator = (Story) => <div className="flex h-[280px] w-[480px] flex-col rounded-lg border border-border-default p-4">{Story()}</div>
@@ -23,6 +25,22 @@ const sectionContrastDeferred = { a11y: { config: { rules: [{ id: 'color-contras
23
25
 
24
26
  /** The `section` manner: the words alone, left-aligned, in the quiet caption — one line in a page that has other things on it. */
25
27
  export const Section: Story = { args: { scope: 'section' }, decorators: [inBox], parameters: sectionContrastDeferred }
28
+ /** The `rows` manner: in place of rows that pad themselves — a sidebar's — the section line starts where a row does, 8px in. */
29
+ export const Rows: Story = {
30
+ args: { scope: 'rows', message: 'Nothing in this yet.' },
31
+ parameters: sectionContrastDeferred,
32
+ render: (args) => (
33
+ <div className="flex w-60 flex-col gap-1">
34
+ <CollapsibleSection title="Group one" contentClassName="gap-0.5">
35
+ <NavItem href="#" label="Item one" icon={<IconSquareRounded size={16} stroke={1.5} />} />
36
+ <NavItem href="#" label="Item two" icon={<IconSquareRounded size={16} stroke={1.5} />} />
37
+ </CollapsibleSection>
38
+ <CollapsibleSection title="Group two" contentClassName="gap-0.5">
39
+ <EmptyState {...args} />
40
+ </CollapsibleSection>
41
+ </div>
42
+ ),
43
+ }
26
44
  export const LongerMessage: Story = { args: { message: 'No items yet. Add one from any list.' }, decorators: [inBox] }
27
45
  export const CustomIcon: Story = { args: { icon: <IconLock size={16} stroke={1.5} />, message: 'Nothing you can read here yet.' }, decorators: [inBox] }
28
46
  /** The one thing to do about it, under the line: the package's Button, outlined. */
@@ -31,6 +49,13 @@ export const WithAction: Story = {
31
49
  decorators: [inBox],
32
50
  }
33
51
 
52
+ /** A section that could not be read: the same quiet line, with the one thing to do about it at its end. */
53
+ export const SectionWithAction: Story = {
54
+ args: { scope: 'section', message: 'Steer could not be read.', action: { label: 'Try again', onClick: () => {} } },
55
+ decorators: [inBox],
56
+ parameters: sectionContrastDeferred,
57
+ }
58
+
34
59
  /** One box, written once, holding the rows or the empty state: its padding places both, so the line starts where the first row does. */
35
60
  export const InsideTheRowsBox: Story = {
36
61
  args: { scope: 'section' },
@@ -72,8 +72,69 @@ describe('EmptyState', () => {
72
72
  expect(clicked).toBe(1)
73
73
  })
74
74
 
75
- it('a section takes no action', () => {
76
- render(<EmptyState scope="section" message="Nothing here yet." action={{ label: 'Add', onClick: () => {} }} />)
75
+ it('a section carries its action at the end of its line, as the package Button, muted (Katerina, 2 November)', () => {
76
+ let clicked = 0
77
+ const { container } = render(
78
+ <EmptyState scope="section" message="Steer could not be read." action={{ label: 'Try again', onClick: () => (clicked += 1) }} />,
79
+ )
80
+ const line = screen.getByText('Steer could not be read.')
81
+ const button = screen.getByRole('button', { name: 'Try again' })
82
+ // The line keeps its quiet look, so a failure reads as the empty line beside it does.
83
+ expect(line.className.split(' ')).toEqual(expect.arrayContaining(['text-caption', 'text-text-muted']))
84
+ // One row: the line, then the button at its end, centred on each other.
85
+ const row = container.firstElementChild!
86
+ expect(row.className.split(' ')).toEqual(expect.arrayContaining(['flex', 'items-center', 'justify-between', 'gap-2']))
87
+ expect(line.parentElement).toBe(row)
88
+ expect(line.nextElementSibling).toBe(button)
89
+ // Muted, the default size: the quiet button a section's line sits beside, not a page's outlined one.
90
+ expect(button.className).not.toContain('border-border-default')
91
+ expect(button.className).toContain('h-8')
92
+ fireEvent.click(button)
93
+ expect(clicked).toBe(1)
94
+ })
95
+
96
+ it('a section with an action takes the caller’s placement on its row', () => {
97
+ const { container } = render(<EmptyState scope="section" className="mt-1" message="Steer could not be read." action={{ label: 'Try again', onClick: () => {} }} />)
98
+ expect(container.firstElementChild!.className).toContain('mt-1')
99
+ })
100
+ })
101
+
102
+ /**
103
+ * The line in place of rows that pad themselves — a sidebar's, NavItem's 8px —
104
+ * so it starts where a row does (Katerina, 14 September). NavTree drew it
105
+ * itself and kept it private; Peek copied the box six times (`px-2 py-1`
106
+ * round a section line). `rows` is that box, given by the part.
107
+ */
108
+ describe('EmptyState in place of rows', () => {
109
+ const peeks = (message: string) => (
110
+ <div className="px-2 py-1">
111
+ <EmptyState scope="section" message={message} />
112
+ </div>
113
+ )
114
+
115
+ it('is the section line in a row’s inset: 8px in, 4px over and under', () => {
116
+ const { container } = render(<EmptyState scope="rows" message="Nothing in this yet." />)
117
+ const line = screen.getByText('Nothing in this yet.')
118
+ expect(line.tagName).toBe('P')
119
+ expect(line.className.split(' ')).toEqual(['text-caption', 'text-text-muted'])
120
+ expect(container.firstElementChild!.className.split(' ')).toEqual(['px-2', 'py-1'])
121
+ expect(container.querySelector('svg')).toBeNull()
122
+ })
123
+
124
+ it('draws exactly the box the apps wrote round a section line', () => {
125
+ const drawn = render(<EmptyState scope="rows" message="Nothing of yours here." />).container.innerHTML
126
+ cleanup()
127
+ expect(drawn).toBe(render(peeks('Nothing of yours here.')).container.innerHTML)
128
+ })
129
+
130
+ it('a caller’s class goes on the box, and the line keeps its quiet look', () => {
131
+ const { container } = render(<EmptyState scope="rows" className="mt-1" message="Nothing in this yet." />)
132
+ expect(container.firstElementChild!.className.split(' ')).toEqual(expect.arrayContaining(['px-2', 'py-1', 'mt-1']))
133
+ expect(screen.getByText('Nothing in this yet.').className.split(' ')).toEqual(['text-caption', 'text-text-muted'])
134
+ })
135
+
136
+ it('takes no action', () => {
137
+ render(<EmptyState scope="rows" message="Nothing in this yet." action={{ label: 'Create', onClick: () => {} }} />)
77
138
  expect(screen.queryByRole('button')).toBeNull()
78
139
  })
79
140
  })
@@ -5,7 +5,7 @@ import { cn } from './cn'
5
5
 
6
6
  /**
7
7
  * The place where content will be once there is some, in two manners
8
- * (Katerina, 2026-09-09):
8
+ * (Katerina, 2026-09-09), and the second in a row's inset:
9
9
  *
10
10
  * - `page` — the whole page is empty: a 16px icon over a centred line of
11
11
  * secondary text, **in the middle of its box both ways** (Katerina,
@@ -19,6 +19,10 @@ import { cn } from './cn'
19
19
  * It is the quiet line — caption size in the muted colour, as a Field's
20
20
  * helper line is — so beside rows it reads as "nothing here", not as one
21
21
  * more row (Katerina, 2026-09-15: "not that intense", "smaller font").
22
+ * - `rows` — a list of rows that pad themselves (a sidebar's `NavItem`s) is
23
+ * empty, or could not be read: the `section` line in their place, in a
24
+ * row's inset, 8px in and 4px over and under, so it starts where a row does
25
+ * (Katerina, 2026-09-14). `NavTree`'s own line; the apps wrote its box.
22
26
  *
23
27
  * The message is the caller's — a shared component has no words of its own
24
28
  * for what is missing.
@@ -27,20 +31,38 @@ export interface EmptyStateProps {
27
31
  /** 16px, stroke 1.5. A speech bubble when absent. Drawn for a `page` only. */
28
32
  icon?: ReactNode
29
33
  message: string
30
- /** `page` when the whole page is empty; `section` when one part of it is. */
31
- scope?: 'page' | 'section'
34
+ /** `page` when the whole page is empty; `section` when one part of it is; `rows` in place of rows that pad themselves, a sidebar's. */
35
+ scope?: 'page' | 'section' | 'rows'
32
36
  /**
33
37
  * The one thing to do about it — "New topic", "Try again" — drawn 16px under
34
- * the line as the package's Button, outlined (Katerina, 2026-09-18). A `page`
35
- * only: a section's empty line is one line among others, not a stage.
38
+ * the line as the package's Button, outlined (Katerina, 2026-09-18). A
39
+ * `section` carries it at the end of its line, muted: a failure read as the
40
+ * empty line beside it does, with its Try again (Katerina, 2 November).
36
41
  */
37
42
  action?: ButtonAction
38
43
  className?: string
39
44
  }
40
45
 
41
46
  export function EmptyState({ icon, message, scope = 'page', action, className }: EmptyStateProps) {
47
+ if (scope === 'rows') {
48
+ return (
49
+ <div className={cn('px-2 py-1', className)}>
50
+ <p className="text-caption text-text-muted">{message}</p>
51
+ </div>
52
+ )
53
+ }
42
54
  if (scope === 'section') {
43
- return <p className={cn('text-caption text-text-muted', className)}>{message}</p>
55
+ const line = <p className={cn('text-caption text-text-muted', !action && className)}>{message}</p>
56
+ if (!action) return line
57
+ // One row: the line, and its button at the end, as Peek's Move drew "could not be read" beside Try again.
58
+ return (
59
+ <div className={cn('flex items-center justify-between gap-2', className)}>
60
+ {line}
61
+ <Button variant="muted" onClick={action.onClick}>
62
+ {action.label}
63
+ </Button>
64
+ </div>
65
+ )
44
66
  }
45
67
  return (
46
68
  <div className={cn('flex flex-1 flex-col items-center justify-center gap-2', className)}>
package/src/Form.mdx CHANGED
@@ -47,7 +47,9 @@ import { Button, Field, Form, TextInput } from '@estiva-app/ui'
47
47
  - **`busy` switches off every field and button inside**, so they do not
48
48
  each need `disabled={busy}`. A button outside the form that sends it —
49
49
  a dialog's footer, with `form="<id>"` and the form's `id` — is outside,
50
- and keeps its own `disabled`.
50
+ and keeps its own `disabled`. The kit's parts that are not native controls
51
+ (Button, IconButton, Checkbox, the editor's **DocumentField**) read it with
52
+ `useFormBusy()`, the kit's own wiring: an app never needs it.
51
53
  - **Focus waits on the form while it is busy.** A browser drops focus to the
52
54
  page the moment the focused field is switched off; the form holds it
53
55
  instead. When `busy` ends, focus goes to the first field showing an error,
@@ -0,0 +1,78 @@
1
+ import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
2
+ import * as FormDialogStories from './FormDialog.stories'
3
+
4
+ <Meta of={FormDialogStories} />
5
+
6
+ # FormDialog
7
+
8
+ A dialog that sends a form: the words and fields you give it, then Cancel and
9
+ the button that sends it, waiting together while it sends.
10
+
11
+ <Canvas of={FormDialogStories.NewFolder} />
12
+
13
+ ## When
14
+
15
+ - A dialog that asks for something and then does it: a name, a destination, a
16
+ resolution. New folder, Rename folder, Start a topic, Move, Archive.
17
+ - `ready` says when there is enough to send; until then the button is greyed and
18
+ Enter sends nothing.
19
+ - Nothing to choose from: give a section's **EmptyState** as the only child and
20
+ `ready={false}`, so the dialog still says what it is for.
21
+
22
+ <Canvas of={FormDialogStories.Sending} />
23
+
24
+ ## When not
25
+
26
+ - A question with no fields, before something hard to undo → **ConfirmDialog**.
27
+ - Resolving a comment → **ResolveDialog**, which is this with its words.
28
+ - A dialog with no sending button: a roster, details with Close → **DialogShell**.
29
+ - A form inside the launcher → **CommandPaletteForm**.
30
+
31
+ ## How
32
+
33
+ ```tsx
34
+ import { FormDialog, Field, TextInput } from '@estiva-app/ui'
35
+
36
+ {open && (
37
+ <FormDialog
38
+ title="New folder"
39
+ submitLabel="Create"
40
+ busyLabel="Creating…"
41
+ ready={!!name.trim()}
42
+ onSubmit={() => create(name.trim())}
43
+ onClose={() => setOpen(false)}
44
+ >
45
+ <p className="text-body-2 text-text-secondary">A place for files and conversations.</p>
46
+ <Field label="Folder name">
47
+ <TextInput value={name} onChange={(e) => setName(e.target.value)} autoFocus />
48
+ </Field>
49
+ </FormDialog>
50
+ )}
51
+ ```
52
+
53
+ - `onSubmit` answers `false` to keep the dialog open, once you have said why;
54
+ anything else closes it, through `onClose`. A throw is a refusal too.
55
+ - While it sends, the button shows `busyLabel`, and the fields and **both**
56
+ buttons wait. Cancel waits because nothing can stop a send already under way:
57
+ a Cancel then would close over a write still running. Escape and the ✕ still
58
+ close it, and `onClose` is not called again when that send goes through.
59
+ - The words before the fields go inside it, as one block: the form puts 24px
60
+ between them and the first field.
61
+
62
+ <Canvas of={FormDialogStories.Refused} />
63
+
64
+ <Canvas of={FormDialogStories.NothingToChoose} />
65
+
66
+ <Canvas of={FormDialogStories.ResolveLook} />
67
+
68
+ ## What it owns
69
+
70
+ | It does | So you never write | Refused when written by hand |
71
+ |---|---|---|
72
+ | Sends on Enter in a one-line field, and on Ctrl+Enter anywhere | a key handler, or a `form` id on the button | |
73
+ | Says it is sending on its button, and switches the fields and both buttons off until the answer | a busy state | |
74
+ | Closes when the send went through, and stays when it was refused | an `if (ok) onClose()` | |
75
+
76
+ ## Props
77
+
78
+ <Controls of={FormDialogStories.NewFolder} />