@whity/ui 0.5.0 → 1.0.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 (205) hide show
  1. package/README.md +107 -107
  2. package/package.json +221 -192
  3. package/src/access-denied.stories.tsx +179 -179
  4. package/src/access-denied.tsx +305 -305
  5. package/src/action-proposal.tsx +338 -302
  6. package/src/actor-chip.tsx +71 -71
  7. package/src/agent-activity.tsx +163 -163
  8. package/src/agent-collaboration.stories.tsx +156 -156
  9. package/src/agent-run-status.tsx +196 -196
  10. package/src/alert-dialog.stories.tsx +45 -45
  11. package/src/alert-dialog.tsx +147 -147
  12. package/src/alert.stories.tsx +91 -91
  13. package/src/alert.tsx +89 -89
  14. package/src/app-sidebar.stories.tsx +195 -195
  15. package/src/app-sidebar.tsx +604 -500
  16. package/src/approval-queue.tsx +109 -108
  17. package/src/audience-group-picker.stories.tsx +198 -198
  18. package/src/audience-group-picker.tsx +362 -362
  19. package/src/audience-people-picker.stories.tsx +102 -102
  20. package/src/audience-people-picker.tsx +279 -279
  21. package/src/avatar-pattern.ts +138 -0
  22. package/src/avatar.tsx +125 -83
  23. package/src/badge.stories.tsx +105 -105
  24. package/src/badge.tsx +68 -68
  25. package/src/beta-warning.stories.tsx +79 -79
  26. package/src/beta-warning.tsx +189 -189
  27. package/src/bilingual-input.stories.tsx +82 -82
  28. package/src/bilingual-input.tsx +188 -183
  29. package/src/board.tsx +216 -0
  30. package/src/breadcrumb.stories.tsx +51 -51
  31. package/src/breadcrumb.tsx +90 -90
  32. package/src/built-on-whity.tsx +52 -0
  33. package/src/button.stories.tsx +87 -87
  34. package/src/button.tsx +123 -118
  35. package/src/card.stories.tsx +423 -423
  36. package/src/card.tsx +180 -180
  37. package/src/chart.stories.tsx +66 -66
  38. package/src/chart.tsx +228 -228
  39. package/src/checkbox.stories.tsx +62 -62
  40. package/src/checkbox.tsx +54 -54
  41. package/src/collapsible.stories.tsx +48 -48
  42. package/src/collapsible.tsx +34 -34
  43. package/src/color-card.stories.tsx +61 -61
  44. package/src/color-card.tsx +270 -270
  45. package/src/color-picker.stories.tsx +65 -65
  46. package/src/color-picker.tsx +425 -425
  47. package/src/column-matcher.tsx +84 -0
  48. package/src/command-palette.tsx +398 -306
  49. package/src/confirm-action.tsx +98 -0
  50. package/src/copy-block.stories.tsx +38 -38
  51. package/src/copy-block.tsx +85 -85
  52. package/src/data-table.stories.tsx +200 -200
  53. package/src/data-table.tsx +1686 -1106
  54. package/src/date-picker.stories.tsx +61 -61
  55. package/src/date-picker.tsx +456 -422
  56. package/src/design-cards.stories.tsx +551 -458
  57. package/src/dialog.stories.tsx +48 -48
  58. package/src/dialog.tsx +179 -166
  59. package/src/display-preferences.tsx +50 -0
  60. package/src/documents/barcode-svg.stories.tsx +72 -72
  61. package/src/documents/barcode-svg.tsx +79 -79
  62. package/src/dropdown-menu.stories.tsx +77 -77
  63. package/src/dropdown-menu.tsx +271 -271
  64. package/src/editor/agent-panel.tsx +222 -0
  65. package/src/editor/agents.stories.tsx +81 -0
  66. package/src/editor/agents.ts +55 -0
  67. package/src/editor/behaviour.ts +279 -279
  68. package/src/editor/block-ids.ts +44 -44
  69. package/src/editor/block-list.tsx +104 -101
  70. package/src/editor/block-toolbar.tsx +490 -477
  71. package/src/editor/bubble.tsx +119 -93
  72. package/src/editor/catalogue.ts +169 -103
  73. package/src/editor/collab-rail.tsx +746 -746
  74. package/src/editor/collab.stories.tsx +207 -207
  75. package/src/editor/collab.ts +87 -87
  76. package/src/editor/contract.ts +476 -408
  77. package/src/editor/convert.ts +414 -362
  78. package/src/editor/doc-editor.stories.tsx +98 -98
  79. package/src/editor/doc-editor.tsx +1492 -1287
  80. package/src/editor/editor.css +636 -536
  81. package/src/editor/extensions.ts +86 -86
  82. package/src/editor/field-bar.tsx +154 -0
  83. package/src/editor/field-picker.tsx +109 -107
  84. package/src/editor/fields.ts +100 -100
  85. package/src/editor/gutter.tsx +443 -367
  86. package/src/editor/index.ts +23 -22
  87. package/src/editor/label-sheet.tsx +289 -289
  88. package/src/editor/labels.ts +394 -310
  89. package/src/editor/link-tools.tsx +141 -141
  90. package/src/editor/node-views.tsx +461 -450
  91. package/src/editor/page-view.tsx +372 -353
  92. package/src/editor/phone.tsx +310 -0
  93. package/src/editor/plugin-block-view.tsx +230 -0
  94. package/src/editor/plugin-blocks.stories.tsx +96 -0
  95. package/src/editor/plugin-blocks.ts +52 -0
  96. package/src/editor/publish-check.tsx +201 -182
  97. package/src/editor/rich-blocks.stories.tsx +146 -146
  98. package/src/editor/sample.ts +40 -40
  99. package/src/editor/save-block-dialog.tsx +141 -0
  100. package/src/editor/saved-block-view.tsx +205 -0
  101. package/src/editor/saved-blocks.stories.tsx +105 -0
  102. package/src/editor/saved-parts.ts +192 -0
  103. package/src/editor/schema-rich.ts +156 -150
  104. package/src/editor/schema.ts +368 -315
  105. package/src/editor/services.tsx +205 -127
  106. package/src/editor/slash.ts +64 -64
  107. package/src/editor/suggesting.ts +372 -372
  108. package/src/editor/suggestions.ts +763 -763
  109. package/src/editor/table-keys.ts +66 -66
  110. package/src/editor/templates.stories.tsx +324 -324
  111. package/src/editor/toolbar.tsx +364 -358
  112. package/src/empty-state.stories.tsx +51 -51
  113. package/src/empty-state.tsx +126 -100
  114. package/src/empty-state.usage-notes.md +30 -30
  115. package/src/form.stories.tsx +112 -112
  116. package/src/form.tsx +176 -176
  117. package/src/globals.css +20 -20
  118. package/src/icon-button.tsx +85 -85
  119. package/src/icon-map.ts +335 -244
  120. package/src/icon.tsx +41 -41
  121. package/src/index.ts +90 -67
  122. package/src/input.stories.tsx +157 -157
  123. package/src/input.tsx +768 -759
  124. package/src/kpi-strip.tsx +47 -0
  125. package/src/localized-text.ts +76 -0
  126. package/src/locked-screen.stories.tsx +29 -29
  127. package/src/locked-screen.tsx +75 -61
  128. package/src/lockup.tsx +42 -0
  129. package/src/lottie.tsx +441 -0
  130. package/src/mark.tsx +62 -62
  131. package/src/math-text.stories.tsx +33 -33
  132. package/src/math-text.tsx +43 -43
  133. package/src/menu-bar.stories.tsx +198 -198
  134. package/src/menu-bar.tsx +373 -373
  135. package/src/message-thread.tsx +181 -0
  136. package/src/money/currency.ts +244 -230
  137. package/src/money/money-input.tsx +131 -0
  138. package/src/money/money.tsx +33 -0
  139. package/src/open-on-computer.tsx +150 -0
  140. package/src/otp-input.tsx +161 -0
  141. package/src/page-header.stories.tsx +95 -95
  142. package/src/page-header.tsx +122 -122
  143. package/src/page-shell.stories.tsx +42 -42
  144. package/src/page-shell.tsx +32 -32
  145. package/src/page-states.tsx +277 -0
  146. package/src/pagination.stories.tsx +45 -45
  147. package/src/pagination.tsx +98 -98
  148. package/src/paper-sheet.stories.tsx +88 -0
  149. package/src/paper-sheet.tsx +85 -0
  150. package/src/phone-tab-bar.tsx +152 -0
  151. package/src/plugin-card.stories.tsx +208 -180
  152. package/src/plugin-card.tsx +931 -848
  153. package/src/popover.stories.tsx +48 -48
  154. package/src/popover.tsx +55 -55
  155. package/src/radio-group.stories.tsx +26 -26
  156. package/src/radio-group.tsx +44 -44
  157. package/src/route-flow/editor.tsx +1087 -1014
  158. package/src/route-flow/model.ts +771 -716
  159. package/src/save-bar.tsx +94 -0
  160. package/src/scope-grant.tsx +139 -139
  161. package/src/screen-too-small.stories.tsx +61 -61
  162. package/src/screen-too-small.tsx +104 -104
  163. package/src/search-field.tsx +65 -0
  164. package/src/select.stories.tsx +44 -44
  165. package/src/select.tsx +197 -197
  166. package/src/separator.stories.tsx +34 -34
  167. package/src/separator.tsx +34 -34
  168. package/src/sheet.stories.tsx +49 -49
  169. package/src/sheet.tsx +168 -168
  170. package/src/skeleton.stories.tsx +28 -28
  171. package/src/skeleton.tsx +19 -19
  172. package/src/slider.stories.tsx +78 -78
  173. package/src/slider.tsx +300 -300
  174. package/src/spinner.stories.tsx +33 -33
  175. package/src/spinner.tsx +55 -55
  176. package/src/stepper.tsx +85 -0
  177. package/src/switch.stories.tsx +42 -42
  178. package/src/switch.tsx +41 -41
  179. package/src/switcher.stories.tsx +111 -111
  180. package/src/switcher.tsx +131 -131
  181. package/src/system-state.tsx +55 -0
  182. package/src/table.stories.tsx +48 -48
  183. package/src/table.tsx +121 -121
  184. package/src/tabs.stories.tsx +74 -74
  185. package/src/tabs.tsx +90 -90
  186. package/src/tag-input.stories.tsx +67 -67
  187. package/src/tag-input.tsx +117 -117
  188. package/src/tenant-logo.tsx +63 -63
  189. package/src/tenant-switcher.stories.tsx +38 -38
  190. package/src/tenant-switcher.tsx +164 -164
  191. package/src/textarea.stories.tsx +27 -27
  192. package/src/textarea.tsx +18 -18
  193. package/src/theme-mode.ts +52 -52
  194. package/src/time-grid.tsx +163 -0
  195. package/src/time-picker.stories.tsx +62 -62
  196. package/src/time-picker.tsx +615 -615
  197. package/src/toggle-group.tsx +138 -138
  198. package/src/tooltip.stories.tsx +43 -43
  199. package/src/tooltip.tsx +73 -73
  200. package/src/top-nav.stories.tsx +58 -58
  201. package/src/top-nav.tsx +324 -324
  202. package/src/undo-bar.tsx +107 -107
  203. package/src/utils.ts +45 -45
  204. package/src/view-toggle.stories.tsx +84 -84
  205. package/src/view-toggle.tsx +110 -110
@@ -1,362 +1,362 @@
1
- "use client"
2
-
3
- import { cn } from "./utils"
4
- import { Badge } from "./badge"
5
- import { Button } from "./button"
6
- import {
7
- Select,
8
- SelectContent,
9
- SelectItem,
10
- SelectTrigger,
11
- SelectValue,
12
- } from "./select"
13
-
14
- /**
15
- * Naming ONE user group, and seeing who it currently means (#1015, over #999's
16
- * engine).
17
- *
18
- * WHY THIS IS A KIT PRIMITIVE AND NOT A SCREEN COMPONENT
19
- * -----------------------------------------------------
20
- * A route step that says "everyone in Instructors" is authored in at least two
21
- * places — the linear route composer and the node-based route template editor —
22
- * and both need the identical control for the identical reason. Authored inside
23
- * one client, the second surface either imports across an app boundary or grows
24
- * a copy, and the copy is where the two drift. `sidebar.tsx` is the cautionary
25
- * case in this repo: 427 lines of hand-rolled duplicate that cost nothing until
26
- * a capability had to be added twice.
27
- *
28
- * THE PREVIEW IS A SNAPSHOT, NOT A MEMBERSHIP LIST
29
- * -----------------------------------------------
30
- * There is deliberately no `user_group_members` table. A group is a RULE, and it
31
- * is re-resolved against the organisation every time it is reached — which is
32
- * the whole reason groups exist: the instructor hired next week is in
33
- * "Instructors" without anybody editing anything, and the one who left is not.
34
- *
35
- * That makes the preview a fact with a timestamp attached, and this component
36
- * has to say so or it teaches the wrong model. Three things do that work
37
- * together and none of them is decoration:
38
- *
39
- * 1. the heading is phrased in the present tense — "reaches N people right now",
40
- * never "has N members";
41
- * 2. {@link AudienceGroupPickerProps.previewDynamicNote} states the rule
42
- * outright, and is rendered with every preview rather than behind a
43
- * disclosure, because a caveat nobody opens is a caveat nobody reads;
44
- * 3. the sample is labelled as a sample whenever it is one, from the server's
45
- * own `truncated` flag rather than from `total > members.length` — a client
46
- * that re-derived that and got it wrong would present ten people as the
47
- * whole group, which is the single misreading this shape exists to prevent.
48
- *
49
- * IT FETCHES NOTHING, LIKE EVERY OTHER `@whity/ui` INPUT
50
- * ----------------------------------------------------------
51
- * Groups and the preview arrive as props. That is the kit's standing convention
52
- * ({@see TagInput}), and here it is also forced: the preview endpoint is
53
- * `GET /api/v1/user-groups/{id}/preview`, three clients reach it three different
54
- * ways, and a primitive that knew the URL could be reused by exactly one of
55
- * them. The consumer owns the request; this owns everything about presenting the
56
- * answer that is easy to get subtly wrong.
57
- *
58
- * NO TRANSLATOR IMPORT. Every user-visible string is a prop with an English
59
- * default — the kit ships to clients with three different i18n stacks, and one
60
- * of them has no runtime translator at all.
61
- */
62
-
63
- /** One group a step may name. */
64
- export interface AudienceGroupOption {
65
- id: number
66
- name: string
67
- /** The group's own one-line description, when it has one. */
68
- description?: string | null
69
- }
70
-
71
- /**
72
- * One person in a preview sample.
73
- *
74
- * `displayName` is nullable rather than optional-and-absent because the server
75
- * sends it that way on purpose: reading a person's NAME needs `users:read`,
76
- * which reading a group's DEFINITION does not imply, so a caller without it gets
77
- * the same payload shape with nulls where the names would be. One shape means a
78
- * client renders an id instead of branching on which flavour it received.
79
- */
80
- export interface AudienceGroupPreviewMember {
81
- profileId: number
82
- displayName?: string | null
83
- }
84
-
85
- /** What a group resolves to at the moment it was asked. */
86
- export interface AudienceGroupPreview {
87
- /** Exact, not an estimate: the server counts what the rule actually answered. */
88
- total: number
89
- /** The server's own flag. Never re-derive it — see the file docblock. */
90
- truncated: boolean
91
- /** The ceiling that produced the sample, so "that is everybody" is tellable. */
92
- sampleSize: number
93
- members: AudienceGroupPreviewMember[]
94
- }
95
-
96
- export type AudienceGroupPreviewStatus = "idle" | "loading" | "ready" | "error"
97
-
98
- export interface AudienceGroupPickerProps {
99
- /** Id for the select, so a caller's own `<label htmlFor>` can address it. */
100
- id?: string
101
- /** The groups to choose from, already fetched by the caller. */
102
- groups: AudienceGroupOption[]
103
- /** The chosen group's id, or null when nothing is chosen yet. */
104
- value: number | null
105
- onChange: (groupId: number | null) => void
106
- /**
107
- * Why there is no list to show — a 403 on the group catalogue, a failed
108
- * request. Rendered as an explanation IN PLACE OF the select, never as an
109
- * empty dropdown: an empty picker reads as "this tenant has no groups", which
110
- * is a different and wrong statement.
111
- */
112
- unavailableReason?: string | null
113
- /**
114
- * Why the list, though populated, may not be all of them — a truncated
115
- * pagination walk. Rendered BESIDE the select, because the author can still
116
- * work; they just must not conclude a missing group does not exist.
117
- */
118
- incompleteReason?: string | null
119
- /** The chosen group's membership snapshot. */
120
- preview?: AudienceGroupPreview | null
121
- previewStatus?: AudienceGroupPreviewStatus
122
- /** The server's refusal, verbatim. */
123
- previewError?: string | null
124
- /** Rendered as a retry control only when supplied. */
125
- onRetryPreview?: () => void
126
- disabled?: boolean
127
- className?: string
128
-
129
- // -- labels, English by default ------------------------------------------
130
-
131
- /** Placeholder on the trigger before a group is chosen. */
132
- placeholder?: string
133
- /** Shown when the caller could read the catalogue and it is genuinely empty. */
134
- emptyLabel?: string
135
- /** While the preview request is in flight. */
136
- previewLoadingLabel?: string
137
- /**
138
- * The count sentence. A function, not a string: the number sits INSIDE the
139
- * phrase, languages put it in different places, and the caller is the only
140
- * party that knows how to format a number for its locale.
141
- */
142
- previewCountLabel?: (total: number) => string
143
- /** When the rule resolves to nobody at all — a fact, not an error. */
144
- previewEmptyLabel?: string
145
- /** Introduces the sample when it is only a sample. */
146
- previewSampleLabel?: (shown: number, total: number) => string
147
- /** Introduces the sample when the sample IS everybody. */
148
- previewAllLabel?: string
149
- /** The "a group is a rule, not a list" sentence. Always rendered. */
150
- previewDynamicNote?: string
151
- /** For a sample row whose name the reader may not see. */
152
- unnamedMemberLabel?: (profileId: number) => string
153
- previewRetryLabel?: string
154
- /**
155
- * For a `value` that names a group the caller's list does not contain.
156
- *
157
- * A function, because the id sits inside the sentence and languages put it in
158
- * different places.
159
- */
160
- unknownGroupLabel?: (groupId: number) => string
161
- }
162
-
163
- /**
164
- * A group chooser with the membership snapshot attached.
165
- *
166
- * Controlled. `value` is the group id; `null` means nothing chosen, which is the
167
- * state a caller must treat as "this step is not configured yet".
168
- */
169
- export function AudienceGroupPicker({
170
- id,
171
- groups,
172
- value,
173
- onChange,
174
- unavailableReason = null,
175
- incompleteReason = null,
176
- preview = null,
177
- previewStatus = "idle",
178
- previewError = null,
179
- onRetryPreview,
180
- disabled = false,
181
- className,
182
- placeholder = "Choose a user group",
183
- emptyLabel = "No user groups have been defined in this workspace yet.",
184
- previewLoadingLabel = "Working out who this group reaches…",
185
- previewCountLabel = (total: number) =>
186
- total === 1
187
- ? "Reaches 1 person right now."
188
- : `Reaches ${total} people right now.`,
189
- previewEmptyLabel =
190
- "This group resolves to nobody right now. A step naming it would reach no one.",
191
- previewSampleLabel = (shown: number, total: number) =>
192
- `Showing ${shown} of the ${total} — a sample, not the whole set:`,
193
- previewAllLabel = "That is everybody:",
194
- previewDynamicNote = "A group is a rule, not a saved list of people. Who it reaches is worked out again every time the document moves, so this is what it means right now — not a set that has been fixed in place.",
195
- unnamedMemberLabel = (profileId: number) => `Profile #${profileId}`,
196
- previewRetryLabel = "Try again",
197
- unknownGroupLabel = (groupId: number) =>
198
- `This step names user group #${groupId}, which is not in the list you can see — it may have been deleted, or you may not be able to read it. Choosing another group here would replace it.`,
199
- }: AudienceGroupPickerProps) {
200
- // An explanation instead of an empty dropdown (#756). The caller's sentence is
201
- // rendered verbatim: it is the only party that knows WHY, and the server's own
202
- // 403 names the permission slug that is missing.
203
- if (unavailableReason !== null && unavailableReason !== "") {
204
- return (
205
- <p
206
- data-slot="audience-group-picker-unavailable"
207
- className={cn("text-xs text-muted-foreground", className)}
208
- >
209
- {unavailableReason}
210
- </p>
211
- )
212
- }
213
-
214
- if (groups.length === 0) {
215
- return (
216
- <p
217
- data-slot="audience-group-picker-empty"
218
- className={cn("text-xs text-muted-foreground", className)}
219
- >
220
- {emptyLabel}
221
- </p>
222
- )
223
- }
224
-
225
- const selected = groups.find((group) => group.id === value) ?? null
226
-
227
- // A configured step whose group is NOT in the list. Radix renders the
228
- // placeholder for a value it has no item for, so without this the step would
229
- // read as "nothing chosen" — and an author would overwrite a perfectly good
230
- // `group_id` believing they were filling in a blank.
231
- //
232
- // Unreachable from a composer that only ever starts steps empty, and squarely
233
- // reachable from an editor that loads a SAVED step (a deleted group, or one
234
- // past the pages the caller managed to load). #756: an empty state, never
235
- // invented content — and never a silent one.
236
- const namesMissingGroup = value !== null && selected === null
237
-
238
- return (
239
- <div
240
- data-slot="audience-group-picker"
241
- className={cn("space-y-2", className)}
242
- >
243
- <Select
244
- value={value === null ? undefined : String(value)}
245
- disabled={disabled}
246
- onValueChange={(next) => {
247
- const parsed = Number(next)
248
- onChange(Number.isInteger(parsed) && parsed > 0 ? parsed : null)
249
- }}
250
- >
251
- <SelectTrigger id={id} className="w-full">
252
- <SelectValue placeholder={placeholder} />
253
- </SelectTrigger>
254
- <SelectContent>
255
- {groups.map((group) => (
256
- <SelectItem key={group.id} value={String(group.id)}>
257
- {group.name}
258
- </SelectItem>
259
- ))}
260
- </SelectContent>
261
- </Select>
262
-
263
- {incompleteReason !== null && incompleteReason !== "" && (
264
- <p
265
- data-slot="audience-group-picker-incomplete"
266
- className="text-xs text-muted-foreground"
267
- >
268
- {incompleteReason}
269
- </p>
270
- )}
271
-
272
- {namesMissingGroup && (
273
- <p
274
- data-slot="audience-group-picker-unknown"
275
- className="text-xs text-destructive"
276
- >
277
- {unknownGroupLabel(value)}
278
- </p>
279
- )}
280
-
281
- {selected?.description !== undefined &&
282
- selected.description !== null &&
283
- selected.description !== "" && (
284
- <p
285
- data-slot="audience-group-picker-description"
286
- className="text-xs text-muted-foreground"
287
- >
288
- {selected.description}
289
- </p>
290
- )}
291
-
292
- {selected !== null && (
293
- <div
294
- data-slot="audience-group-picker-preview"
295
- // `text-start`, not `text-left`: the kit ships into Arabic UIs and a
296
- // physical direction would pin this block to the wrong edge there.
297
- className="rounded-md border border-border bg-muted/40 p-2 text-start"
298
- // Announced as it changes: choosing a group is the act, and the count
299
- // arriving afterwards is the answer to it.
300
- aria-live="polite"
301
- >
302
- {previewStatus === "loading" && (
303
- <p className="text-xs text-muted-foreground">
304
- {previewLoadingLabel}
305
- </p>
306
- )}
307
-
308
- {previewStatus === "error" && (
309
- <div className="flex flex-wrap items-center gap-2">
310
- <p className="text-xs text-destructive">{previewError}</p>
311
- {onRetryPreview !== undefined && (
312
- <Button variant="outline" size="sm" onClick={onRetryPreview}>
313
- {previewRetryLabel}
314
- </Button>
315
- )}
316
- </div>
317
- )}
318
-
319
- {previewStatus === "ready" && preview !== null && (
320
- <div className="space-y-1">
321
- <p className="text-xs font-medium text-foreground">
322
- {preview.total === 0
323
- ? previewEmptyLabel
324
- : previewCountLabel(preview.total)}
325
- </p>
326
-
327
- {preview.total > 0 && (
328
- <>
329
- <p className="text-xs text-muted-foreground">
330
- {preview.truncated
331
- ? previewSampleLabel(preview.members.length, preview.total)
332
- : previewAllLabel}
333
- </p>
334
- <ul className="flex flex-wrap gap-1">
335
- {preview.members.map((member) => (
336
- <li key={member.profileId}>
337
- <Badge variant="secondary">
338
- {member.displayName !== undefined &&
339
- member.displayName !== null &&
340
- member.displayName !== ""
341
- ? member.displayName
342
- : unnamedMemberLabel(member.profileId)}
343
- </Badge>
344
- </li>
345
- ))}
346
- </ul>
347
- </>
348
- )}
349
-
350
- <p
351
- data-slot="audience-group-picker-dynamic-note"
352
- className="text-xs text-muted-foreground"
353
- >
354
- {previewDynamicNote}
355
- </p>
356
- </div>
357
- )}
358
- </div>
359
- )}
360
- </div>
361
- )
362
- }
1
+ "use client"
2
+
3
+ import { cn } from "./utils"
4
+ import { Badge } from "./badge"
5
+ import { Button } from "./button"
6
+ import {
7
+ Select,
8
+ SelectContent,
9
+ SelectItem,
10
+ SelectTrigger,
11
+ SelectValue,
12
+ } from "./select"
13
+
14
+ /**
15
+ * Naming ONE user group, and seeing who it currently means (#1015, over #999's
16
+ * engine).
17
+ *
18
+ * WHY THIS IS A KIT PRIMITIVE AND NOT A SCREEN COMPONENT
19
+ * -----------------------------------------------------
20
+ * A route step that says "everyone in Instructors" is authored in at least two
21
+ * places — the linear route composer and the node-based route template editor —
22
+ * and both need the identical control for the identical reason. Authored inside
23
+ * one client, the second surface either imports across an app boundary or grows
24
+ * a copy, and the copy is where the two drift. `sidebar.tsx` is the cautionary
25
+ * case in this repo: 427 lines of hand-rolled duplicate that cost nothing until
26
+ * a capability had to be added twice.
27
+ *
28
+ * THE PREVIEW IS A SNAPSHOT, NOT A MEMBERSHIP LIST
29
+ * -----------------------------------------------
30
+ * There is deliberately no `user_group_members` table. A group is a RULE, and it
31
+ * is re-resolved against the organisation every time it is reached — which is
32
+ * the whole reason groups exist: the instructor hired next week is in
33
+ * "Instructors" without anybody editing anything, and the one who left is not.
34
+ *
35
+ * That makes the preview a fact with a timestamp attached, and this component
36
+ * has to say so or it teaches the wrong model. Three things do that work
37
+ * together and none of them is decoration:
38
+ *
39
+ * 1. the heading is phrased in the present tense — "reaches N people right now",
40
+ * never "has N members";
41
+ * 2. {@link AudienceGroupPickerProps.previewDynamicNote} states the rule
42
+ * outright, and is rendered with every preview rather than behind a
43
+ * disclosure, because a caveat nobody opens is a caveat nobody reads;
44
+ * 3. the sample is labelled as a sample whenever it is one, from the server's
45
+ * own `truncated` flag rather than from `total > members.length` — a client
46
+ * that re-derived that and got it wrong would present ten people as the
47
+ * whole group, which is the single misreading this shape exists to prevent.
48
+ *
49
+ * IT FETCHES NOTHING, LIKE EVERY OTHER `@whity/ui` INPUT
50
+ * ----------------------------------------------------------
51
+ * Groups and the preview arrive as props. That is the kit's standing convention
52
+ * ({@see TagInput}), and here it is also forced: the preview endpoint is
53
+ * `GET /api/v1/user-groups/{id}/preview`, three clients reach it three different
54
+ * ways, and a primitive that knew the URL could be reused by exactly one of
55
+ * them. The consumer owns the request; this owns everything about presenting the
56
+ * answer that is easy to get subtly wrong.
57
+ *
58
+ * NO TRANSLATOR IMPORT. Every user-visible string is a prop with an English
59
+ * default — the kit ships to clients with three different i18n stacks, and one
60
+ * of them has no runtime translator at all.
61
+ */
62
+
63
+ /** One group a step may name. */
64
+ export interface AudienceGroupOption {
65
+ id: number
66
+ name: string
67
+ /** The group's own one-line description, when it has one. */
68
+ description?: string | null
69
+ }
70
+
71
+ /**
72
+ * One person in a preview sample.
73
+ *
74
+ * `displayName` is nullable rather than optional-and-absent because the server
75
+ * sends it that way on purpose: reading a person's NAME needs `users:read`,
76
+ * which reading a group's DEFINITION does not imply, so a caller without it gets
77
+ * the same payload shape with nulls where the names would be. One shape means a
78
+ * client renders an id instead of branching on which flavour it received.
79
+ */
80
+ export interface AudienceGroupPreviewMember {
81
+ profileId: number
82
+ displayName?: string | null
83
+ }
84
+
85
+ /** What a group resolves to at the moment it was asked. */
86
+ export interface AudienceGroupPreview {
87
+ /** Exact, not an estimate: the server counts what the rule actually answered. */
88
+ total: number
89
+ /** The server's own flag. Never re-derive it — see the file docblock. */
90
+ truncated: boolean
91
+ /** The ceiling that produced the sample, so "that is everybody" is tellable. */
92
+ sampleSize: number
93
+ members: AudienceGroupPreviewMember[]
94
+ }
95
+
96
+ export type AudienceGroupPreviewStatus = "idle" | "loading" | "ready" | "error"
97
+
98
+ export interface AudienceGroupPickerProps {
99
+ /** Id for the select, so a caller's own `<label htmlFor>` can address it. */
100
+ id?: string
101
+ /** The groups to choose from, already fetched by the caller. */
102
+ groups: AudienceGroupOption[]
103
+ /** The chosen group's id, or null when nothing is chosen yet. */
104
+ value: number | null
105
+ onChange: (groupId: number | null) => void
106
+ /**
107
+ * Why there is no list to show — a 403 on the group catalogue, a failed
108
+ * request. Rendered as an explanation IN PLACE OF the select, never as an
109
+ * empty dropdown: an empty picker reads as "this tenant has no groups", which
110
+ * is a different and wrong statement.
111
+ */
112
+ unavailableReason?: string | null
113
+ /**
114
+ * Why the list, though populated, may not be all of them — a truncated
115
+ * pagination walk. Rendered BESIDE the select, because the author can still
116
+ * work; they just must not conclude a missing group does not exist.
117
+ */
118
+ incompleteReason?: string | null
119
+ /** The chosen group's membership snapshot. */
120
+ preview?: AudienceGroupPreview | null
121
+ previewStatus?: AudienceGroupPreviewStatus
122
+ /** The server's refusal, verbatim. */
123
+ previewError?: string | null
124
+ /** Rendered as a retry control only when supplied. */
125
+ onRetryPreview?: () => void
126
+ disabled?: boolean
127
+ className?: string
128
+
129
+ // -- labels, English by default ------------------------------------------
130
+
131
+ /** Placeholder on the trigger before a group is chosen. */
132
+ placeholder?: string
133
+ /** Shown when the caller could read the catalogue and it is genuinely empty. */
134
+ emptyLabel?: string
135
+ /** While the preview request is in flight. */
136
+ previewLoadingLabel?: string
137
+ /**
138
+ * The count sentence. A function, not a string: the number sits INSIDE the
139
+ * phrase, languages put it in different places, and the caller is the only
140
+ * party that knows how to format a number for its locale.
141
+ */
142
+ previewCountLabel?: (total: number) => string
143
+ /** When the rule resolves to nobody at all — a fact, not an error. */
144
+ previewEmptyLabel?: string
145
+ /** Introduces the sample when it is only a sample. */
146
+ previewSampleLabel?: (shown: number, total: number) => string
147
+ /** Introduces the sample when the sample IS everybody. */
148
+ previewAllLabel?: string
149
+ /** The "a group is a rule, not a list" sentence. Always rendered. */
150
+ previewDynamicNote?: string
151
+ /** For a sample row whose name the reader may not see. */
152
+ unnamedMemberLabel?: (profileId: number) => string
153
+ previewRetryLabel?: string
154
+ /**
155
+ * For a `value` that names a group the caller's list does not contain.
156
+ *
157
+ * A function, because the id sits inside the sentence and languages put it in
158
+ * different places.
159
+ */
160
+ unknownGroupLabel?: (groupId: number) => string
161
+ }
162
+
163
+ /**
164
+ * A group chooser with the membership snapshot attached.
165
+ *
166
+ * Controlled. `value` is the group id; `null` means nothing chosen, which is the
167
+ * state a caller must treat as "this step is not configured yet".
168
+ */
169
+ export function AudienceGroupPicker({
170
+ id,
171
+ groups,
172
+ value,
173
+ onChange,
174
+ unavailableReason = null,
175
+ incompleteReason = null,
176
+ preview = null,
177
+ previewStatus = "idle",
178
+ previewError = null,
179
+ onRetryPreview,
180
+ disabled = false,
181
+ className,
182
+ placeholder = "Choose a user group",
183
+ emptyLabel = "No user groups have been defined in this workspace yet.",
184
+ previewLoadingLabel = "Working out who this group reaches…",
185
+ previewCountLabel = (total: number) =>
186
+ total === 1
187
+ ? "Reaches 1 person right now."
188
+ : `Reaches ${total} people right now.`,
189
+ previewEmptyLabel =
190
+ "This group resolves to nobody right now. A step naming it would reach no one.",
191
+ previewSampleLabel = (shown: number, total: number) =>
192
+ `Showing ${shown} of the ${total} — a sample, not the whole set:`,
193
+ previewAllLabel = "That is everybody:",
194
+ previewDynamicNote = "A group is a rule, not a saved list of people. Who it reaches is worked out again every time the document moves, so this is what it means right now — not a set that has been fixed in place.",
195
+ unnamedMemberLabel = (profileId: number) => `Profile #${profileId}`,
196
+ previewRetryLabel = "Try again",
197
+ unknownGroupLabel = (groupId: number) =>
198
+ `This step names user group #${groupId}, which is not in the list you can see — it may have been deleted, or you may not be able to read it. Choosing another group here would replace it.`,
199
+ }: AudienceGroupPickerProps) {
200
+ // An explanation instead of an empty dropdown (#756). The caller's sentence is
201
+ // rendered verbatim: it is the only party that knows WHY, and the server's own
202
+ // 403 names the permission slug that is missing.
203
+ if (unavailableReason !== null && unavailableReason !== "") {
204
+ return (
205
+ <p
206
+ data-slot="audience-group-picker-unavailable"
207
+ className={cn("text-xs text-muted-foreground", className)}
208
+ >
209
+ {unavailableReason}
210
+ </p>
211
+ )
212
+ }
213
+
214
+ if (groups.length === 0) {
215
+ return (
216
+ <p
217
+ data-slot="audience-group-picker-empty"
218
+ className={cn("text-xs text-muted-foreground", className)}
219
+ >
220
+ {emptyLabel}
221
+ </p>
222
+ )
223
+ }
224
+
225
+ const selected = groups.find((group) => group.id === value) ?? null
226
+
227
+ // A configured step whose group is NOT in the list. Radix renders the
228
+ // placeholder for a value it has no item for, so without this the step would
229
+ // read as "nothing chosen" — and an author would overwrite a perfectly good
230
+ // `group_id` believing they were filling in a blank.
231
+ //
232
+ // Unreachable from a composer that only ever starts steps empty, and squarely
233
+ // reachable from an editor that loads a SAVED step (a deleted group, or one
234
+ // past the pages the caller managed to load). #756: an empty state, never
235
+ // invented content — and never a silent one.
236
+ const namesMissingGroup = value !== null && selected === null
237
+
238
+ return (
239
+ <div
240
+ data-slot="audience-group-picker"
241
+ className={cn("space-y-2", className)}
242
+ >
243
+ <Select
244
+ value={value === null ? undefined : String(value)}
245
+ disabled={disabled}
246
+ onValueChange={(next) => {
247
+ const parsed = Number(next)
248
+ onChange(Number.isInteger(parsed) && parsed > 0 ? parsed : null)
249
+ }}
250
+ >
251
+ <SelectTrigger id={id} className="w-full">
252
+ <SelectValue placeholder={placeholder} />
253
+ </SelectTrigger>
254
+ <SelectContent>
255
+ {groups.map((group) => (
256
+ <SelectItem key={group.id} value={String(group.id)}>
257
+ {group.name}
258
+ </SelectItem>
259
+ ))}
260
+ </SelectContent>
261
+ </Select>
262
+
263
+ {incompleteReason !== null && incompleteReason !== "" && (
264
+ <p
265
+ data-slot="audience-group-picker-incomplete"
266
+ className="text-xs text-muted-foreground"
267
+ >
268
+ {incompleteReason}
269
+ </p>
270
+ )}
271
+
272
+ {namesMissingGroup && (
273
+ <p
274
+ data-slot="audience-group-picker-unknown"
275
+ className="text-xs text-destructive"
276
+ >
277
+ {unknownGroupLabel(value)}
278
+ </p>
279
+ )}
280
+
281
+ {selected?.description !== undefined &&
282
+ selected.description !== null &&
283
+ selected.description !== "" && (
284
+ <p
285
+ data-slot="audience-group-picker-description"
286
+ className="text-xs text-muted-foreground"
287
+ >
288
+ {selected.description}
289
+ </p>
290
+ )}
291
+
292
+ {selected !== null && (
293
+ <div
294
+ data-slot="audience-group-picker-preview"
295
+ // `text-start`, not `text-left`: the kit ships into Arabic UIs and a
296
+ // physical direction would pin this block to the wrong edge there.
297
+ className="rounded-md border border-border bg-muted/40 p-2 text-start"
298
+ // Announced as it changes: choosing a group is the act, and the count
299
+ // arriving afterwards is the answer to it.
300
+ aria-live="polite"
301
+ >
302
+ {previewStatus === "loading" && (
303
+ <p className="text-xs text-muted-foreground">
304
+ {previewLoadingLabel}
305
+ </p>
306
+ )}
307
+
308
+ {previewStatus === "error" && (
309
+ <div className="flex flex-wrap items-center gap-2">
310
+ <p className="text-xs text-destructive">{previewError}</p>
311
+ {onRetryPreview !== undefined && (
312
+ <Button variant="outline" size="sm" onClick={onRetryPreview}>
313
+ {previewRetryLabel}
314
+ </Button>
315
+ )}
316
+ </div>
317
+ )}
318
+
319
+ {previewStatus === "ready" && preview !== null && (
320
+ <div className="space-y-1">
321
+ <p className="text-xs font-medium text-foreground">
322
+ {preview.total === 0
323
+ ? previewEmptyLabel
324
+ : previewCountLabel(preview.total)}
325
+ </p>
326
+
327
+ {preview.total > 0 && (
328
+ <>
329
+ <p className="text-xs text-muted-foreground">
330
+ {preview.truncated
331
+ ? previewSampleLabel(preview.members.length, preview.total)
332
+ : previewAllLabel}
333
+ </p>
334
+ <ul className="flex flex-wrap gap-1">
335
+ {preview.members.map((member) => (
336
+ <li key={member.profileId}>
337
+ <Badge variant="secondary">
338
+ {member.displayName !== undefined &&
339
+ member.displayName !== null &&
340
+ member.displayName !== ""
341
+ ? member.displayName
342
+ : unnamedMemberLabel(member.profileId)}
343
+ </Badge>
344
+ </li>
345
+ ))}
346
+ </ul>
347
+ </>
348
+ )}
349
+
350
+ <p
351
+ data-slot="audience-group-picker-dynamic-note"
352
+ className="text-xs text-muted-foreground"
353
+ >
354
+ {previewDynamicNote}
355
+ </p>
356
+ </div>
357
+ )}
358
+ </div>
359
+ )}
360
+ </div>
361
+ )
362
+ }