@whity/ui 0.0.0-stage → 0.5.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 (169) hide show
  1. package/README.md +107 -3
  2. package/package.json +192 -6
  3. package/src/access-denied.stories.tsx +179 -0
  4. package/src/access-denied.tsx +305 -0
  5. package/src/action-proposal.tsx +302 -0
  6. package/src/actor-chip.tsx +71 -0
  7. package/src/agent-activity.tsx +163 -0
  8. package/src/agent-collaboration.stories.tsx +156 -0
  9. package/src/agent-run-status.tsx +196 -0
  10. package/src/alert-dialog.stories.tsx +45 -0
  11. package/src/alert-dialog.tsx +147 -0
  12. package/src/alert.stories.tsx +91 -0
  13. package/src/alert.tsx +89 -0
  14. package/src/app-sidebar.stories.tsx +195 -0
  15. package/src/app-sidebar.tsx +500 -0
  16. package/src/approval-queue.tsx +108 -0
  17. package/src/audience-group-picker.stories.tsx +198 -0
  18. package/src/audience-group-picker.tsx +362 -0
  19. package/src/audience-people-picker.stories.tsx +102 -0
  20. package/src/audience-people-picker.tsx +279 -0
  21. package/src/avatar.tsx +83 -0
  22. package/src/badge.stories.tsx +105 -0
  23. package/src/badge.tsx +68 -0
  24. package/src/beta-warning.stories.tsx +79 -0
  25. package/src/beta-warning.tsx +189 -0
  26. package/src/bilingual-input.stories.tsx +82 -0
  27. package/src/bilingual-input.tsx +183 -0
  28. package/src/breadcrumb.stories.tsx +51 -0
  29. package/src/breadcrumb.tsx +90 -0
  30. package/src/button.stories.tsx +87 -0
  31. package/src/button.tsx +118 -0
  32. package/src/card.stories.tsx +423 -0
  33. package/src/card.tsx +180 -0
  34. package/src/chart.stories.tsx +66 -0
  35. package/src/chart.tsx +228 -0
  36. package/src/checkbox.stories.tsx +62 -0
  37. package/src/checkbox.tsx +54 -0
  38. package/src/collapsible.stories.tsx +48 -0
  39. package/src/collapsible.tsx +34 -0
  40. package/src/color-card.stories.tsx +61 -0
  41. package/src/color-card.tsx +270 -0
  42. package/src/color-picker.stories.tsx +65 -0
  43. package/src/color-picker.tsx +425 -0
  44. package/src/command-palette.tsx +306 -0
  45. package/src/copy-block.stories.tsx +38 -0
  46. package/src/copy-block.tsx +85 -0
  47. package/src/data-table.stories.tsx +200 -0
  48. package/src/data-table.tsx +1106 -0
  49. package/src/date-picker.stories.tsx +61 -0
  50. package/src/date-picker.tsx +422 -0
  51. package/src/design-cards.stories.tsx +458 -0
  52. package/src/dialog.stories.tsx +48 -0
  53. package/src/dialog.tsx +166 -0
  54. package/src/documents/barcode-svg.stories.tsx +72 -0
  55. package/src/documents/barcode-svg.tsx +79 -0
  56. package/src/dropdown-menu.stories.tsx +77 -0
  57. package/src/dropdown-menu.tsx +271 -0
  58. package/src/editor/behaviour.ts +279 -0
  59. package/src/editor/block-ids.ts +44 -0
  60. package/src/editor/block-list.tsx +101 -0
  61. package/src/editor/block-toolbar.tsx +477 -0
  62. package/src/editor/bubble.tsx +93 -0
  63. package/src/editor/catalogue.ts +103 -0
  64. package/src/editor/collab-rail.tsx +746 -0
  65. package/src/editor/collab.stories.tsx +207 -0
  66. package/src/editor/collab.ts +87 -0
  67. package/src/editor/contract.ts +408 -0
  68. package/src/editor/convert.ts +362 -0
  69. package/src/editor/doc-editor.stories.tsx +98 -0
  70. package/src/editor/doc-editor.tsx +1287 -0
  71. package/src/editor/editor.css +536 -0
  72. package/src/editor/extensions.ts +86 -0
  73. package/src/editor/field-picker.tsx +107 -0
  74. package/src/editor/fields.ts +100 -0
  75. package/src/editor/gutter.tsx +367 -0
  76. package/src/editor/index.ts +22 -0
  77. package/src/editor/label-sheet.tsx +289 -0
  78. package/src/editor/labels.ts +310 -0
  79. package/src/editor/link-tools.tsx +141 -0
  80. package/src/editor/node-views.tsx +450 -0
  81. package/src/editor/page-view.tsx +353 -0
  82. package/src/editor/publish-check.tsx +182 -0
  83. package/src/editor/rich-blocks.stories.tsx +146 -0
  84. package/src/editor/sample.ts +40 -0
  85. package/src/editor/schema-rich.ts +150 -0
  86. package/src/editor/schema.ts +315 -0
  87. package/src/editor/services.tsx +127 -0
  88. package/src/editor/slash.ts +64 -0
  89. package/src/editor/suggesting.ts +372 -0
  90. package/src/editor/suggestions.ts +763 -0
  91. package/src/editor/table-keys.ts +66 -0
  92. package/src/editor/templates.stories.tsx +324 -0
  93. package/src/editor/toolbar.tsx +358 -0
  94. package/src/empty-state.stories.tsx +51 -0
  95. package/src/empty-state.tsx +100 -0
  96. package/src/empty-state.usage-notes.md +30 -0
  97. package/src/form.stories.tsx +112 -0
  98. package/src/form.tsx +176 -0
  99. package/src/globals.css +20 -0
  100. package/src/icon-button.tsx +85 -0
  101. package/src/icon-map.ts +244 -0
  102. package/src/icon.tsx +41 -0
  103. package/src/index.ts +67 -0
  104. package/src/input.stories.tsx +157 -0
  105. package/src/input.tsx +759 -0
  106. package/src/locked-screen.stories.tsx +29 -0
  107. package/src/locked-screen.tsx +61 -0
  108. package/src/mark.tsx +62 -0
  109. package/src/math-text.stories.tsx +33 -0
  110. package/src/math-text.tsx +43 -0
  111. package/src/menu-bar.stories.tsx +198 -0
  112. package/src/menu-bar.tsx +373 -0
  113. package/src/money/currency.ts +230 -0
  114. package/src/page-header.stories.tsx +95 -0
  115. package/src/page-header.tsx +122 -0
  116. package/src/page-shell.stories.tsx +42 -0
  117. package/src/page-shell.tsx +32 -0
  118. package/src/pagination.stories.tsx +45 -0
  119. package/src/pagination.tsx +98 -0
  120. package/src/plugin-card.stories.tsx +180 -0
  121. package/src/plugin-card.tsx +848 -0
  122. package/src/popover.stories.tsx +48 -0
  123. package/src/popover.tsx +55 -0
  124. package/src/radio-group.stories.tsx +26 -0
  125. package/src/radio-group.tsx +44 -0
  126. package/src/route-flow/editor.tsx +1014 -0
  127. package/src/route-flow/model.ts +716 -0
  128. package/src/scope-grant.tsx +139 -0
  129. package/src/screen-too-small.stories.tsx +61 -0
  130. package/src/screen-too-small.tsx +104 -0
  131. package/src/select.stories.tsx +44 -0
  132. package/src/select.tsx +197 -0
  133. package/src/separator.stories.tsx +34 -0
  134. package/src/separator.tsx +34 -0
  135. package/src/sheet.stories.tsx +49 -0
  136. package/src/sheet.tsx +168 -0
  137. package/src/skeleton.stories.tsx +28 -0
  138. package/src/skeleton.tsx +19 -0
  139. package/src/slider.stories.tsx +78 -0
  140. package/src/slider.tsx +300 -0
  141. package/src/spinner.stories.tsx +33 -0
  142. package/src/spinner.tsx +55 -0
  143. package/src/switch.stories.tsx +42 -0
  144. package/src/switch.tsx +41 -0
  145. package/src/switcher.stories.tsx +111 -0
  146. package/src/switcher.tsx +131 -0
  147. package/src/table.stories.tsx +48 -0
  148. package/src/table.tsx +121 -0
  149. package/src/tabs.stories.tsx +74 -0
  150. package/src/tabs.tsx +90 -0
  151. package/src/tag-input.stories.tsx +67 -0
  152. package/src/tag-input.tsx +117 -0
  153. package/src/tenant-logo.tsx +63 -0
  154. package/src/tenant-switcher.stories.tsx +38 -0
  155. package/src/tenant-switcher.tsx +164 -0
  156. package/src/textarea.stories.tsx +27 -0
  157. package/src/textarea.tsx +18 -0
  158. package/src/theme-mode.ts +52 -0
  159. package/src/time-picker.stories.tsx +62 -0
  160. package/src/time-picker.tsx +615 -0
  161. package/src/toggle-group.tsx +138 -0
  162. package/src/tooltip.stories.tsx +43 -0
  163. package/src/tooltip.tsx +73 -0
  164. package/src/top-nav.stories.tsx +58 -0
  165. package/src/top-nav.tsx +324 -0
  166. package/src/undo-bar.tsx +107 -0
  167. package/src/utils.ts +45 -0
  168. package/src/view-toggle.stories.tsx +84 -0
  169. package/src/view-toggle.tsx +110 -0
@@ -0,0 +1,198 @@
1
+ import type { Meta, StoryObj } from "@storybook/react-vite"
2
+ import { fn } from "storybook/test"
3
+ import * as React from "react"
4
+
5
+ import {
6
+ AudienceGroupPicker,
7
+ type AudienceGroupOption,
8
+ type AudienceGroupPreview,
9
+ } from "./audience-group-picker"
10
+
11
+ const GROUPS: AudienceGroupOption[] = [
12
+ {
13
+ id: 1,
14
+ name: "Instructors",
15
+ description: "Everyone holding the instructor role, anywhere in the faculty.",
16
+ },
17
+ {
18
+ id: 2,
19
+ name: "Department heads",
20
+ description: "Everyone holding the department-head role.",
21
+ },
22
+ { id: 3, name: "Tender committee", description: null },
23
+ ]
24
+
25
+ const SMALL_PREVIEW: AudienceGroupPreview = {
26
+ total: 3,
27
+ truncated: false,
28
+ sampleSize: 10,
29
+ members: [
30
+ { profileId: 11, displayName: "Aisha Karim" },
31
+ { profileId: 12, displayName: "Omar Haddad" },
32
+ { profileId: 13, displayName: "Lena Farouk" },
33
+ ],
34
+ }
35
+
36
+ const LARGE_PREVIEW: AudienceGroupPreview = {
37
+ total: 1043,
38
+ truncated: true,
39
+ sampleSize: 5,
40
+ members: [
41
+ { profileId: 11, displayName: "Aisha Karim" },
42
+ { profileId: 12, displayName: "Omar Haddad" },
43
+ { profileId: 13, displayName: "Lena Farouk" },
44
+ { profileId: 14, displayName: "Yusuf Nabil" },
45
+ { profileId: 15, displayName: "Rania Saleh" },
46
+ ],
47
+ }
48
+
49
+ const meta = {
50
+ title: "Primitives/AudienceGroupPicker",
51
+ component: AudienceGroupPicker,
52
+ tags: ["autodocs"],
53
+ args: {
54
+ groups: GROUPS,
55
+ value: null,
56
+ onChange: fn(),
57
+ },
58
+ } satisfies Meta<typeof AudienceGroupPicker>
59
+
60
+ export default meta
61
+ type Story = StoryObj<typeof meta>
62
+
63
+ /**
64
+ * The picker is fully controlled, so the interactive stories drive it through
65
+ * this wrapper: the `value` arg seeds local state and `onChange` still fires so
66
+ * the Actions panel logs the choice.
67
+ */
68
+ function ControlledPicker({
69
+ value,
70
+ onChange,
71
+ ...props
72
+ }: React.ComponentProps<typeof AudienceGroupPicker>) {
73
+ const [current, setCurrent] = React.useState<number | null>(value)
74
+
75
+ return (
76
+ <AudienceGroupPicker
77
+ {...props}
78
+ value={current}
79
+ onChange={(next) => {
80
+ setCurrent(next)
81
+ onChange(next)
82
+ }}
83
+ />
84
+ )
85
+ }
86
+
87
+ /** Nothing chosen: a placeholder, and no preview to show yet. */
88
+ export const Unchosen: Story = {
89
+ render: (args) => <ControlledPicker {...args} />,
90
+ }
91
+
92
+ /**
93
+ * A small group where the sample IS the membership — the picker says so, rather
94
+ * than leaving the reader to compare two numbers.
95
+ */
96
+ export const SmallGroup: Story = {
97
+ args: { value: 3, preview: SMALL_PREVIEW, previewStatus: "ready" },
98
+ render: (args) => <ControlledPicker {...args} />,
99
+ }
100
+
101
+ /**
102
+ * The case the whole design exists for: four figures of people, one row. The
103
+ * sample is labelled as a sample, and the dynamic-membership note sits under it.
104
+ */
105
+ export const LargeGroup: Story = {
106
+ args: { value: 1, preview: LARGE_PREVIEW, previewStatus: "ready" },
107
+ render: (args) => <ControlledPicker {...args} />,
108
+ }
109
+
110
+ /**
111
+ * A rule nobody currently matches. Not an error — a fact about the organisation
112
+ * that the author needs before they commit, not after the document reaches
113
+ * nobody.
114
+ */
115
+ export const ResolvesToNobody: Story = {
116
+ args: {
117
+ value: 2,
118
+ preview: { total: 0, truncated: false, sampleSize: 10, members: [] },
119
+ previewStatus: "ready",
120
+ },
121
+ render: (args) => <ControlledPicker {...args} />,
122
+ }
123
+
124
+ /**
125
+ * The reader may see group definitions but not people's names (`groups:read`
126
+ * without `users:read`). Same payload shape, ids where the names would be.
127
+ */
128
+ export const WithoutNames: Story = {
129
+ args: {
130
+ value: 1,
131
+ previewStatus: "ready",
132
+ preview: {
133
+ total: 2,
134
+ truncated: false,
135
+ sampleSize: 10,
136
+ members: [
137
+ { profileId: 11, displayName: null },
138
+ { profileId: 12, displayName: null },
139
+ ],
140
+ },
141
+ },
142
+ render: (args) => <ControlledPicker {...args} />,
143
+ }
144
+
145
+ export const PreviewLoading: Story = {
146
+ args: { value: 1, previewStatus: "loading" },
147
+ render: (args) => <ControlledPicker {...args} />,
148
+ }
149
+
150
+ /** The server's refusal, verbatim, with a way back. */
151
+ export const PreviewFailed: Story = {
152
+ args: {
153
+ value: 1,
154
+ previewStatus: "error",
155
+ previewError: "user group 1 does not exist in this tenant.",
156
+ onRetryPreview: fn(),
157
+ },
158
+ render: (args) => <ControlledPicker {...args} />,
159
+ }
160
+
161
+ /**
162
+ * A reason, never an empty dropdown: the author learns the list is missing
163
+ * because of a permission, not because the workspace has no groups.
164
+ */
165
+ export const Unavailable: Story = {
166
+ args: {
167
+ groups: [],
168
+ unavailableReason:
169
+ "You cannot list user groups here, so a step cannot name one. An administrator would need to grant you groups:read.",
170
+ },
171
+ render: (args) => <ControlledPicker {...args} />,
172
+ }
173
+
174
+ /** The catalogue is genuinely empty — a different statement, said differently. */
175
+ export const NoGroupsDefined: Story = {
176
+ args: { groups: [] },
177
+ render: (args) => <ControlledPicker {...args} />,
178
+ }
179
+
180
+ /**
181
+ * A saved step naming a group the reader's list does not contain — deleted, or
182
+ * past the pages they could load. Said out loud, because Radix would otherwise
183
+ * draw the placeholder and the step would read as unconfigured.
184
+ */
185
+ export const NamesAGroupNotInTheList: Story = {
186
+ args: { value: 404 },
187
+ render: (args) => <ControlledPicker {...args} />,
188
+ }
189
+
190
+ /** Right-to-left: the kit ships into Arabic UIs, so every story must survive it. */
191
+ export const RightToLeft: Story = {
192
+ args: { value: 1, preview: LARGE_PREVIEW, previewStatus: "ready" },
193
+ render: (args) => (
194
+ <div dir="rtl">
195
+ <ControlledPicker {...args} />
196
+ </div>
197
+ ),
198
+ }
@@ -0,0 +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
+ }
@@ -0,0 +1,102 @@
1
+ import type { Meta, StoryObj } from "@storybook/react-vite"
2
+ import { fn } from "storybook/test"
3
+ import * as React from "react"
4
+
5
+ import {
6
+ AudiencePeoplePicker,
7
+ type AudiencePersonOption,
8
+ } from "./audience-people-picker"
9
+
10
+ const PEOPLE: AudiencePersonOption[] = [
11
+ { id: 11, name: "Aisha Karim", secondary: "aisha@demo.example.com" },
12
+ { id: 12, name: "Omar Haddad", secondary: "omar@demo.example.com" },
13
+ { id: 13, name: "Lena Farouk", secondary: "lena@demo.example.com" },
14
+ { id: 14, name: "Yusuf Nabil", secondary: "yusuf@demo.example.com" },
15
+ { id: 15, name: "Rania Saleh", secondary: "rania@demo.example.com" },
16
+ { id: 16, name: "Karim Aziz", secondary: "karim@demo.example.com" },
17
+ { id: 17, name: "Nour Adel", secondary: "nour@demo.example.com" },
18
+ { id: 18, name: "Sami Darwish", secondary: "sami@demo.example.com" },
19
+ { id: 19, name: "Hana Mansour", secondary: "hana@demo.example.com" },
20
+ { id: 20, name: "Tarek Amin", secondary: "tarek@demo.example.com" },
21
+ ]
22
+
23
+ const meta = {
24
+ title: "Primitives/AudiencePeoplePicker",
25
+ component: AudiencePeoplePicker,
26
+ tags: ["autodocs"],
27
+ args: {
28
+ people: PEOPLE,
29
+ value: [],
30
+ onChange: fn(),
31
+ },
32
+ } satisfies Meta<typeof AudiencePeoplePicker>
33
+
34
+ export default meta
35
+ type Story = StoryObj<typeof meta>
36
+
37
+ /** Fully controlled — the wrapper holds the selection so the canvas is usable. */
38
+ function ControlledPeoplePicker({
39
+ value,
40
+ onChange,
41
+ ...props
42
+ }: React.ComponentProps<typeof AudiencePeoplePicker>) {
43
+ const [current, setCurrent] = React.useState<number[]>(value)
44
+
45
+ return (
46
+ <AudiencePeoplePicker
47
+ {...props}
48
+ value={current}
49
+ onChange={(next) => {
50
+ setCurrent(next)
51
+ onChange(next)
52
+ }}
53
+ />
54
+ )
55
+ }
56
+
57
+ /**
58
+ * The opening state: a search box and nothing else. Deliberately not the whole
59
+ * roster — this control is for naming a handful, and listing everybody invites
60
+ * the reading the `explicit` kind exists to avoid.
61
+ */
62
+ export const Empty: Story = {
63
+ render: (args) => <ControlledPeoplePicker {...args} />,
64
+ }
65
+
66
+ /** Three people named: the tender-committee case, which no computed rule expresses. */
67
+ export const WithSelection: Story = {
68
+ args: { value: [11, 12, 13] },
69
+ render: (args) => <ControlledPeoplePicker {...args} />,
70
+ }
71
+
72
+ /** A chosen id the catalogue does not cover — shown by id, never as a blank. */
73
+ export const UnknownPersonChosen: Story = {
74
+ args: { value: [11, 999] },
75
+ render: (args) => <ControlledPeoplePicker {...args} />,
76
+ }
77
+
78
+ /** Read-only: the chips remain legible, the search and remove controls go. */
79
+ export const Disabled: Story = {
80
+ args: { value: [11, 12], disabled: true },
81
+ render: (args) => <ControlledPeoplePicker {...args} />,
82
+ }
83
+
84
+ /** A reason, never an empty search box. */
85
+ export const Unavailable: Story = {
86
+ args: {
87
+ people: [],
88
+ unavailableReason:
89
+ "You cannot list people here, so a step cannot name one. An administrator would need to grant you users:read.",
90
+ },
91
+ render: (args) => <ControlledPeoplePicker {...args} />,
92
+ }
93
+
94
+ /** Right-to-left: chips, the remove control and the result rows all mirror. */
95
+ export const RightToLeft: Story = {
96
+ args: { value: [11, 12] },
97
+ render: (args) => (
98
+ <div dir="rtl">
99
+ <ControlledPeoplePicker {...args} />
100
+ </div>
101
+ ),
102
+ }