opsfuse-ui 0.1.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 (209) hide show
  1. package/.claude/settings.local.json +8 -0
  2. package/.claude/skills/brief-to-tasks/SKILL.md +74 -0
  3. package/.claude/skills/design-brief/SKILL.md +120 -0
  4. package/.claude/skills/design-flow/SKILL.md +124 -0
  5. package/.claude/skills/design-review/SKILL.md +249 -0
  6. package/.claude/skills/design-tokens/SKILL.md +198 -0
  7. package/.claude/skills/frontend-design/SKILL.md +144 -0
  8. package/.claude/skills/grill-me/SKILL.md +21 -0
  9. package/.claude/skills/information-architecture/SKILL.md +111 -0
  10. package/.claude/skills/opsfuse-color-theme/SKILL.md +251 -0
  11. package/.claude/skills/opsfuse-components/SKILL.md +1439 -0
  12. package/.claude/skills/opsfuse-setup/SKILL.md +548 -0
  13. package/.claude/skills/opsfuse-ui-consistency/SKILL.md +160 -0
  14. package/README.md +356 -0
  15. package/dist/chunk-BdsCSvBP.js +20 -0
  16. package/dist/clsx-D7D_XZ_-.js +16 -0
  17. package/dist/components/logo/LogoMaker.d.ts +43 -0
  18. package/dist/components/logo/LogoMaker.d.ts.map +1 -0
  19. package/dist/components/logo/RecruitSmartly.d.ts +4 -0
  20. package/dist/components/logo/RecruitSmartly.d.ts.map +1 -0
  21. package/dist/components/logo/SkillReady.d.ts +4 -0
  22. package/dist/components/logo/SkillReady.d.ts.map +1 -0
  23. package/dist/components/logo/TalentScan.d.ts +4 -0
  24. package/dist/components/logo/TalentScan.d.ts.map +1 -0
  25. package/dist/components/logo/Verity.d.ts +4 -0
  26. package/dist/components/logo/Verity.d.ts.map +1 -0
  27. package/dist/components/logo/WorkLog.d.ts +4 -0
  28. package/dist/components/logo/WorkLog.d.ts.map +1 -0
  29. package/dist/components/opsfuse-root.d.ts +7 -0
  30. package/dist/components/opsfuse-root.d.ts.map +1 -0
  31. package/dist/components/opsfuse-theme-provider.d.ts +15 -0
  32. package/dist/components/opsfuse-theme-provider.d.ts.map +1 -0
  33. package/dist/components/ui/Header.d.ts +17 -0
  34. package/dist/components/ui/Header.d.ts.map +1 -0
  35. package/dist/components/ui/accordion.d.ts +20 -0
  36. package/dist/components/ui/accordion.d.ts.map +1 -0
  37. package/dist/components/ui/alert-dialog.d.ts +15 -0
  38. package/dist/components/ui/alert-dialog.d.ts.map +1 -0
  39. package/dist/components/ui/alert.d.ts +26 -0
  40. package/dist/components/ui/alert.d.ts.map +1 -0
  41. package/dist/components/ui/aspect-ratio.d.ts +4 -0
  42. package/dist/components/ui/aspect-ratio.d.ts.map +1 -0
  43. package/dist/components/ui/autocomplete.d.ts +24 -0
  44. package/dist/components/ui/autocomplete.d.ts.map +1 -0
  45. package/dist/components/ui/avatar.d.ts +9 -0
  46. package/dist/components/ui/avatar.d.ts.map +1 -0
  47. package/dist/components/ui/badge.d.ts +10 -0
  48. package/dist/components/ui/badge.d.ts.map +1 -0
  49. package/dist/components/ui/breadcrumb.d.ts +12 -0
  50. package/dist/components/ui/breadcrumb.d.ts.map +1 -0
  51. package/dist/components/ui/button-group.d.ts +12 -0
  52. package/dist/components/ui/button-group.d.ts.map +1 -0
  53. package/dist/components/ui/button.d.ts +14 -0
  54. package/dist/components/ui/button.d.ts.map +1 -0
  55. package/dist/components/ui/calendar.d.ts +11 -0
  56. package/dist/components/ui/calendar.d.ts.map +1 -0
  57. package/dist/components/ui/card.d.ts +14 -0
  58. package/dist/components/ui/card.d.ts.map +1 -0
  59. package/dist/components/ui/carousel.d.ts +29 -0
  60. package/dist/components/ui/carousel.d.ts.map +1 -0
  61. package/dist/components/ui/chart.d.ts +45 -0
  62. package/dist/components/ui/chart.d.ts.map +1 -0
  63. package/dist/components/ui/checkbox.d.ts +10 -0
  64. package/dist/components/ui/checkbox.d.ts.map +1 -0
  65. package/dist/components/ui/collapsible.d.ts +6 -0
  66. package/dist/components/ui/collapsible.d.ts.map +1 -0
  67. package/dist/components/ui/combobox.d.ts +40 -0
  68. package/dist/components/ui/combobox.d.ts.map +1 -0
  69. package/dist/components/ui/command.d.ts +19 -0
  70. package/dist/components/ui/command.d.ts.map +1 -0
  71. package/dist/components/ui/context-menu.d.ts +32 -0
  72. package/dist/components/ui/context-menu.d.ts.map +1 -0
  73. package/dist/components/ui/dialog.d.ts +30 -0
  74. package/dist/components/ui/dialog.d.ts.map +1 -0
  75. package/dist/components/ui/direction.d.ts +8 -0
  76. package/dist/components/ui/direction.d.ts.map +1 -0
  77. package/dist/components/ui/drawer.d.ts +14 -0
  78. package/dist/components/ui/drawer.d.ts.map +1 -0
  79. package/dist/components/ui/dropdown-menu.d.ts +30 -0
  80. package/dist/components/ui/dropdown-menu.d.ts.map +1 -0
  81. package/dist/components/ui/empty.d.ts +12 -0
  82. package/dist/components/ui/empty.d.ts.map +1 -0
  83. package/dist/components/ui/field.d.ts +25 -0
  84. package/dist/components/ui/field.d.ts.map +1 -0
  85. package/dist/components/ui/form.d.ts +27 -0
  86. package/dist/components/ui/form.d.ts.map +1 -0
  87. package/dist/components/ui/hover-card.d.ts +7 -0
  88. package/dist/components/ui/hover-card.d.ts.map +1 -0
  89. package/dist/components/ui/input-group.d.ts +18 -0
  90. package/dist/components/ui/input-group.d.ts.map +1 -0
  91. package/dist/components/ui/input-otp.d.ts +12 -0
  92. package/dist/components/ui/input-otp.d.ts.map +1 -0
  93. package/dist/components/ui/input.d.ts +12 -0
  94. package/dist/components/ui/input.d.ts.map +1 -0
  95. package/dist/components/ui/item.d.ts +24 -0
  96. package/dist/components/ui/item.d.ts.map +1 -0
  97. package/dist/components/ui/kbd.d.ts +4 -0
  98. package/dist/components/ui/kbd.d.ts.map +1 -0
  99. package/dist/components/ui/label.d.ts +5 -0
  100. package/dist/components/ui/label.d.ts.map +1 -0
  101. package/dist/components/ui/menubar.d.ts +31 -0
  102. package/dist/components/ui/menubar.d.ts.map +1 -0
  103. package/dist/components/ui/navigation-menu.d.ts +15 -0
  104. package/dist/components/ui/navigation-menu.d.ts.map +1 -0
  105. package/dist/components/ui/pagination.d.ts +15 -0
  106. package/dist/components/ui/pagination.d.ts.map +1 -0
  107. package/dist/components/ui/popover.d.ts +11 -0
  108. package/dist/components/ui/popover.d.ts.map +1 -0
  109. package/dist/components/ui/progress.d.ts +19 -0
  110. package/dist/components/ui/progress.d.ts.map +1 -0
  111. package/dist/components/ui/radio-group.d.ts +11 -0
  112. package/dist/components/ui/radio-group.d.ts.map +1 -0
  113. package/dist/components/ui/resizable.d.ts +8 -0
  114. package/dist/components/ui/resizable.d.ts.map +1 -0
  115. package/dist/components/ui/scroll-area.d.ts +6 -0
  116. package/dist/components/ui/scroll-area.d.ts.map +1 -0
  117. package/dist/components/ui/select.d.ts +27 -0
  118. package/dist/components/ui/select.d.ts.map +1 -0
  119. package/dist/components/ui/separator.d.ts +5 -0
  120. package/dist/components/ui/separator.d.ts.map +1 -0
  121. package/dist/components/ui/shadcn/shadcn-accordion.d.ts +8 -0
  122. package/dist/components/ui/shadcn/shadcn-accordion.d.ts.map +1 -0
  123. package/dist/components/ui/shadcn/shadcn-alert-dialog.d.ts +19 -0
  124. package/dist/components/ui/shadcn/shadcn-alert-dialog.d.ts.map +1 -0
  125. package/dist/components/ui/shadcn/shadcn-avatar.d.ts +12 -0
  126. package/dist/components/ui/shadcn/shadcn-avatar.d.ts.map +1 -0
  127. package/dist/components/ui/shadcn/shadcn-combobox.d.ts +33 -0
  128. package/dist/components/ui/shadcn/shadcn-combobox.d.ts.map +1 -0
  129. package/dist/components/ui/shadcn/shadcn-dropdown-menu.d.ts +30 -0
  130. package/dist/components/ui/shadcn/shadcn-dropdown-menu.d.ts.map +1 -0
  131. package/dist/components/ui/shadcn/shadcn-empty.d.ts +12 -0
  132. package/dist/components/ui/shadcn/shadcn-empty.d.ts.map +1 -0
  133. package/dist/components/ui/shadcn/shadcn-pagination.d.ts +18 -0
  134. package/dist/components/ui/shadcn/shadcn-pagination.d.ts.map +1 -0
  135. package/dist/components/ui/shadcn/shadcn-select.d.ts +24 -0
  136. package/dist/components/ui/shadcn/shadcn-select.d.ts.map +1 -0
  137. package/dist/components/ui/shadcn/shadcn-tabs.d.ts +12 -0
  138. package/dist/components/ui/shadcn/shadcn-tabs.d.ts.map +1 -0
  139. package/dist/components/ui/shadcn/shadcn-tooltip.d.ts +11 -0
  140. package/dist/components/ui/shadcn/shadcn-tooltip.d.ts.map +1 -0
  141. package/dist/components/ui/sheet.d.ts +28 -0
  142. package/dist/components/ui/sheet.d.ts.map +1 -0
  143. package/dist/components/ui/sidebar.d.ts +70 -0
  144. package/dist/components/ui/sidebar.d.ts.map +1 -0
  145. package/dist/components/ui/skeleton.d.ts +3 -0
  146. package/dist/components/ui/skeleton.d.ts.map +1 -0
  147. package/dist/components/ui/slider.d.ts +22 -0
  148. package/dist/components/ui/slider.d.ts.map +1 -0
  149. package/dist/components/ui/sonner.d.ts +5 -0
  150. package/dist/components/ui/sonner.d.ts.map +1 -0
  151. package/dist/components/ui/spinner.d.ts +3 -0
  152. package/dist/components/ui/spinner.d.ts.map +1 -0
  153. package/dist/components/ui/switch.d.ts +12 -0
  154. package/dist/components/ui/switch.d.ts.map +1 -0
  155. package/dist/components/ui/table.d.ts +11 -0
  156. package/dist/components/ui/table.d.ts.map +1 -0
  157. package/dist/components/ui/tabs.d.ts +22 -0
  158. package/dist/components/ui/tabs.d.ts.map +1 -0
  159. package/dist/components/ui/textarea.d.ts +9 -0
  160. package/dist/components/ui/textarea.d.ts.map +1 -0
  161. package/dist/components/ui/toggle-group.d.ts +11 -0
  162. package/dist/components/ui/toggle-group.d.ts.map +1 -0
  163. package/dist/components/ui/toggle.d.ts +10 -0
  164. package/dist/components/ui/toggle.d.ts.map +1 -0
  165. package/dist/components/ui/tooltip.d.ts +15 -0
  166. package/dist/components/ui/tooltip.d.ts.map +1 -0
  167. package/dist/core.d.ts +2 -0
  168. package/dist/core.d.ts.map +1 -0
  169. package/dist/core.js +3 -0
  170. package/dist/es6-D-3xKXBT.js +24045 -0
  171. package/dist/extended.d.ts +2 -0
  172. package/dist/extended.d.ts.map +1 -0
  173. package/dist/extended.js +3 -0
  174. package/dist/hooks/use-mobile.d.ts +2 -0
  175. package/dist/hooks/use-mobile.d.ts.map +1 -0
  176. package/dist/icons.d.ts +2 -0
  177. package/dist/icons.d.ts.map +1 -0
  178. package/dist/icons.js +2 -0
  179. package/dist/index.d.ts +2 -0
  180. package/dist/index.d.ts.map +1 -0
  181. package/dist/index.js +2194 -0
  182. package/dist/input-group-DIfVGMYe.js +5196 -0
  183. package/dist/input-otp-DwLGFwVo.js +11879 -0
  184. package/dist/lib/brand-theme.d.ts +4 -0
  185. package/dist/lib/brand-theme.d.ts.map +1 -0
  186. package/dist/lib/document-dark-mode.d.ts +8 -0
  187. package/dist/lib/document-dark-mode.d.ts.map +1 -0
  188. package/dist/lib/opsfuse-portal-theme.d.ts +21 -0
  189. package/dist/lib/opsfuse-portal-theme.d.ts.map +1 -0
  190. package/dist/lib/theme-scope.d.ts +3 -0
  191. package/dist/lib/theme-scope.d.ts.map +1 -0
  192. package/dist/lib/utils.d.ts +3 -0
  193. package/dist/lib/utils.d.ts.map +1 -0
  194. package/dist/lucide-react-DLVJK_zM.js +38405 -0
  195. package/dist/public-api-core.d.ts +61 -0
  196. package/dist/public-api-core.d.ts.map +1 -0
  197. package/dist/public-api-extended.d.ts +9 -0
  198. package/dist/public-api-extended.d.ts.map +1 -0
  199. package/dist/public-api.d.ts +73 -0
  200. package/dist/public-api.d.ts.map +1 -0
  201. package/dist/recharts.d.ts +2 -0
  202. package/dist/recharts.d.ts.map +1 -0
  203. package/dist/recharts.js +2 -0
  204. package/dist/style.css +3 -0
  205. package/dist/style.layered.css +3 -0
  206. package/dist/toggle-group-D21Ul2kd.js +10171 -0
  207. package/package.json +113 -0
  208. package/scripts/postinstall.mjs +67 -0
  209. package/scripts/unwrap-css-layers.mjs +36 -0
@@ -0,0 +1,1439 @@
1
+ # OpsFuse UI Components Reference
2
+
3
+ You are an expert on the OpsFuse UI component library. When invoked, answer questions about which component to use, its props, variants, and composition patterns. All components are exported from `src/public-api.ts` and importable as named exports.
4
+
5
+ ---
6
+
7
+ ## Import Pattern
8
+
9
+ ```tsx
10
+ import { Button, Card, CardContent, Input, Badge, Recharts } from "opsfuse-ui";
11
+ import { Home, Search, Plus } from "opsfuse-ui/icons";
12
+ // or for performance-sensitive apps:
13
+ import { Button, Badge } from "opsfuse-ui/core";
14
+ import { ChartContainer, Calendar } from "opsfuse-ui/extended";
15
+ // or within the project:
16
+ import { Button } from "@/components/ui/button";
17
+ ```
18
+
19
+ - `opsfuse-ui/icons` — flat Lucide icon re-exports. Write `<Search />` directly. For names that collide with opsfuse components (`Badge`, `Calendar`, `Command`, `Form`, `Sheet`, `Sidebar`, `Table`) either alias on import or use `Lucide.<Icon>` from the main entry.
20
+ - `Recharts` (main entry) — namespace re-export of `recharts`. Write `<Recharts.BarChart />`.
21
+
22
+ Never install `lucide-react` or `recharts` directly in host apps.
23
+
24
+ All components require a `.opsfuse-ui` ancestor class (provided by `OpsfuseThemeProvider`).
25
+
26
+ ---
27
+
28
+ ## Button
29
+
30
+ **File:** `src/components/ui/button.tsx`
31
+ **Export:** `Button`, `buttonVariants`
32
+
33
+ ```tsx
34
+ <Button
35
+ variant="default"
36
+ size="default"
37
+ motion="default"
38
+ loading={false}
39
+ loadingText="Loading..."
40
+ >
41
+ Click me
42
+ </Button>
43
+ ```
44
+
45
+ ### Variants
46
+
47
+ | `variant` | Use |
48
+ | ------------- | -------------------------------------------------- |
49
+ | `default` | Primary action — filled with `--primary` |
50
+ | `outline` | Secondary action — bordered, transparent bg |
51
+ | `secondary` | Neutral action — `--muted` bg (shadcn `secondary`) |
52
+ | `ghost` | Subtle / icon-adjacent — no border, hover bg only |
53
+ | `destructive` | Dangerous actions — red tinted |
54
+ | `link` | Inline hyperlink style |
55
+
56
+ ### Motion (`motion`)
57
+
58
+ Maps to transition utilities in `src/index.css`. Default is `transition-all`; prefer token utilities when matching design-system motion.
59
+
60
+ | `motion` | CSS utility | Use |
61
+ | --------- | ------------------------ | ----------------------------------------- |
62
+ | `default` | (broad `transition-all`) | General buttons |
63
+ | `micro` | `.transition-micro` | Primary presses, hovers, icon toggles |
64
+ | `smooth` | `.transition-smooth` | Panels, dropdowns, slower surfaces |
65
+ | `data` | `.transition-data` | Data-heavy motion (rare on plain buttons) |
66
+
67
+ ### Sizes
68
+
69
+ | `size` | Height | Use |
70
+ | --------- | ------ | ----------------------- |
71
+ | `default` | 36px | Standard buttons |
72
+ | `sm` | 32px | Compact areas |
73
+ | `xs` | 28px | Tight toolbars, tags |
74
+ | `lg` | 40px | Hero CTAs |
75
+ | `icon` | 40px | Icon-only square button |
76
+ | `icon-sm` | 32px | Icon-only compact |
77
+ | `icon-xs` | 28px | Icon-only micro |
78
+
79
+ **Props:** `motion`, `loading` (shows spinner + `loadingText`), `asChild` (renders as child via Slot), standard `<button>` props.
80
+
81
+ **Group:** Wrap in `<ButtonGroup>` for segmented controls — automatically handles shared borders and radius.
82
+
83
+ ---
84
+
85
+ ## Badge
86
+
87
+ **File:** `src/components/ui/badge.tsx`
88
+ **Export:** `Badge`, `badgeVariants`
89
+
90
+ ```tsx
91
+ <Badge variant="default">New</Badge>
92
+ ```
93
+
94
+ ### Variants
95
+
96
+ | `variant` | Use |
97
+ | -------------- | -------------------------------------------------------- |
98
+ | `default` | Primary filled |
99
+ | `secondary` | Neutral / muted |
100
+ | `destructive` | Error/danger state (tinted) |
101
+ | `outline` | Bordered, no fill |
102
+ | `ghost` | Hover-only highlight |
103
+ | `link` | Underlined text |
104
+ | `accent` | Muted pill — maps to `.pill-default` tokens |
105
+ | `primaryMuted` | Primary-tinted pill — maps to `.pill-primary` |
106
+ | `ai` | AI-tinted pill — maps to `.pill-ai` |
107
+ | `success` | Success pill — maps to `.pill-success` |
108
+ | `warning` | Warning pill — maps to `.pill-warning` |
109
+ | `danger` | Danger pill — maps to `.pill-danger` (muted destructive) |
110
+ | `aiLive` | Animated AI strip badge — applies `.badge-ai` class |
111
+
112
+ **Also available as CSS utilities** (for non-React contexts or markup without `<Badge>`):
113
+
114
+ - `.badge-ai` — same look as `<Badge variant="aiLive">`
115
+ - `.pill`, `.pill-default`, `.pill-primary`, `.pill-ai`, `.pill-success`, `.pill-warning`, `.pill-danger` — same palettes as the pill `variant`s above
116
+
117
+ ---
118
+
119
+ ## Card
120
+
121
+ **File:** `src/components/ui/card.tsx`
122
+ **Export:** `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent`, `CardFooter`
123
+
124
+ ```tsx
125
+ <Card size="default" variant="default">
126
+ <CardHeader>
127
+ <CardTitle>Title</CardTitle>
128
+ <CardDescription>Description text</CardDescription>
129
+ <CardAction>
130
+ <Button size="sm">Action</Button>
131
+ </CardAction>
132
+ </CardHeader>
133
+ <CardContent>Body content</CardContent>
134
+ <CardFooter>Footer note</CardFooter>
135
+ </Card>
136
+ ```
137
+
138
+ **`size` prop:** `"default"` | `"sm"` — `sm` uses tighter padding (12px vs 16px).
139
+
140
+ **`variant` prop:** `"default"` | `"surface"` | `"interactive"`.
141
+
142
+ - `default` — ring + shadow elevation (standard shadcn-style card).
143
+ - `surface` — uses `.card-base` from `src/index.css` (border-defined depth, `rounded-lg` / `--radius-lg`).
144
+ - `interactive` — `.card-base` + `.card-interactive` (focus ring, pointer cursor) for clickable shells.
145
+
146
+ `CardFooter` renders with a top border and muted background. `CardAction` positions itself in the top-right of the header grid.
147
+
148
+ **CSS utility alternative:** same as `variant="surface"` / `variant="interactive"` when not using React.
149
+
150
+ ---
151
+
152
+ ## Input
153
+
154
+ **File:** `src/components/ui/input.tsx`
155
+ **Export:** `Input`
156
+
157
+ ```tsx
158
+ <Input
159
+ label="Email"
160
+ placeholder="you@example.com"
161
+ helperText="We'll never share your email"
162
+ error={false}
163
+ startIcon={<MailIcon />}
164
+ endIcon={<SearchIcon />}
165
+ />
166
+ ```
167
+
168
+ **Props:** `label`, `helperText`, `error` (boolean — turns helper text red), `startIcon`, `endIcon`, `appearance`, all standard `<input>` props.
169
+
170
+ **`appearance`:** `"default"` (field styles in the component) | `"themed"` — applies `.input-themed` + `.transition-smooth` from `src/index.css`. When `error={true}` (or `aria-invalid`), themed inputs add `.input-error`.
171
+
172
+ When `error={true}`, the border uses `--destructive` and helperText shows in destructive color.
173
+
174
+ ---
175
+
176
+ ## Select
177
+
178
+ **File:** `src/components/ui/select.tsx`
179
+ **Export:** default `Select` wrapper + named shadcn primitives (`SSelect`, `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem`, `SelectGroup`, `SelectLabel`, `SelectSeparator`, `SelectField`)
180
+
181
+ ```tsx
182
+ import { Select } from "opsfuse-ui";
183
+ import { UserIcon, LogOutIcon } from "lucide-react";
184
+
185
+ <Select
186
+ placeholder="Choose..."
187
+ groupLabel="Options"
188
+ options={[
189
+ { label: "Profile", value: "profile", icon: <UserIcon /> },
190
+ { label: "Logout", value: "logout", icon: <LogOutIcon />, iconPosition: "inline-end", separator: true },
191
+ ]}
192
+ />;
193
+ ```
194
+
195
+ Wrapper props:
196
+
197
+ - `options`: array of `{ label, value, disabled?, separator?, icon?, iconPosition? }`
198
+ - `icon`: optional `React.ReactNode` rendered alongside the label
199
+ - `iconPosition`: `"inline-start"` (default) | `"inline-end"` — mirrors the Button `data-icon` convention
200
+ - `placeholder`, `groupLabel`
201
+ - `placeholderIcon`: optional `React.ReactNode` shown at the start of the trigger, next to the placeholder (inline-start only)
202
+ - `fieldLabel`, `helperText`, `error`
203
+ - `triggerSize`: `"default"` | `"sm"`
204
+ - class hooks: `fieldClassName`, `triggerClassName`, `contentClassName`
205
+
206
+ `src/components/ui/select.tsx` reuses the base primitives from `src/components/ui/shadcn/shadcn-select.tsx`.
207
+
208
+ ---
209
+
210
+ ## Textarea
211
+
212
+ **File:** `src/components/ui/textarea.tsx`
213
+ **Export:** `Textarea`
214
+
215
+ Standard textarea with OpsFuse styling. Use for multi-line text input.
216
+
217
+ ---
218
+
219
+ ## Label
220
+
221
+ **File:** `src/components/ui/label.tsx`
222
+ **Export:** `Label`
223
+
224
+ Accessible label component wrapping Radix Label. Pairs with form fields.
225
+
226
+ ---
227
+
228
+ ## Checkbox
229
+
230
+ **File:** `src/components/ui/checkbox.tsx`
231
+ **Export:** `Checkbox`
232
+
233
+ ---
234
+
235
+ ## Switch
236
+
237
+ **File:** `src/components/ui/switch.tsx`
238
+ **Export:** `Switch`
239
+
240
+ ---
241
+
242
+ ## Radio Group
243
+
244
+ **File:** `src/components/ui/radio-group.tsx`
245
+ **Export:** `RadioGroup`, `RadioGroupItem`
246
+
247
+ ---
248
+
249
+ ## Slider
250
+
251
+ **File:** `src/components/ui/slider.tsx`
252
+ **Export:** `Slider`
253
+
254
+ ---
255
+
256
+ ## Dialog
257
+
258
+ **File:** `src/components/ui/dialog.tsx`
259
+ **Export:** `Dialog`, `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogFooter`, `DialogTitle`, `DialogDescription`, `DialogClose`, `DialogOverlay`
260
+
261
+ ```tsx
262
+ <Dialog>
263
+ <DialogTrigger asChild>
264
+ <Button>Open</Button>
265
+ </DialogTrigger>
266
+ <DialogContent>
267
+ <DialogHeader>
268
+ <DialogTitle>Title</DialogTitle>
269
+ <DialogDescription>Description</DialogDescription>
270
+ </DialogHeader>
271
+ Body content
272
+ <DialogFooter>
273
+ <DialogClose asChild>
274
+ <Button variant="outline">Cancel</Button>
275
+ </DialogClose>
276
+ <Button>Confirm</Button>
277
+ </DialogFooter>
278
+ </DialogContent>
279
+ </Dialog>
280
+ ```
281
+
282
+ Portal target is `.opsfuse-ui` root (via `OPSFUSE_THEME_SCOPE`). Overlay uses `backdrop-blur-xs`.
283
+
284
+ ---
285
+
286
+ ## Alert Dialog
287
+
288
+ **Public module:** `src/components/ui/alert-dialog.tsx`
289
+ **Export:** `confirm`, `ConfirmationDialogProvider`, type `ConfirmationOptions`
290
+
291
+ **Internal primitives** (Radix compound, not re-exported from `alert-dialog.tsx`): `src/components/ui/shadcn/shadcn-alert-dialog.tsx` — used only to render the dialog opened by `confirm()`.
292
+
293
+ `<OpsfuseThemeProvider>` and `<OpsfuseRoot />` mount the full root stack (`ConfirmationDialogProvider`, tooltip/alert/dialog/sheet/slider providers, and `Toaster`), so `confirm()` and other imperative APIs work without duplicating providers in `main.tsx`. For isolated unit tests outside that tree, mount only the providers your component needs (or wrap with `OpsfuseThemeProvider`). Call `confirm({ title, description?, confirmText?, cancelText?, onConfirm?, onCancel? })` for destructive confirmations (delete, reset). `onConfirm` may be async; the dialog closes after the promise settles.
294
+
295
+ **Storybook:** `src/stories/alert-dialog.stories.tsx` documents this API only — no separate story file for `shadcn-alert-dialog.tsx`.
296
+
297
+ ```tsx
298
+ import { confirm, OpsfuseThemeProvider } from "opsfuse-ui";
299
+
300
+ <OpsfuseThemeProvider className="min-h-svh">
301
+ <App />
302
+ </OpsfuseThemeProvider>;
303
+
304
+ confirm({
305
+ title: "Delete item?",
306
+ description: "This cannot be undone.",
307
+ onConfirm: async () => {
308
+ /* … */
309
+ },
310
+ });
311
+ ```
312
+
313
+ ---
314
+
315
+ ## Sheet
316
+
317
+ **File:** `src/components/ui/sheet.tsx`
318
+ **Export:** `Sheet`, `SheetTrigger`, `SheetContent`, `SheetHeader`, `SheetFooter`, `SheetTitle`, `SheetDescription`, `SheetClose`
319
+
320
+ Side drawer panel. `SheetContent` defaults to sliding from the right. Use for settings panels, detail panes, filters.
321
+
322
+ ---
323
+
324
+ ## Drawer
325
+
326
+ **File:** `src/components/ui/drawer.tsx`
327
+ **Export:** `Drawer`, `DrawerTrigger`, `DrawerContent`, `DrawerHeader`, `DrawerFooter`, `DrawerTitle`, `DrawerDescription`, `DrawerClose`
328
+
329
+ Bottom-sheet style drawer (vaul). Mobile-first. Use for mobile action panels.
330
+
331
+ ---
332
+
333
+ ## Tooltip
334
+
335
+ **File:** `src/components/ui/tooltip.tsx`
336
+ **Export:** default `Tooltip`
337
+
338
+ This wrapper uses the shared shadcn tooltip primitives from `src/components/ui/shadcn/shadcn-tooltip.tsx`.
339
+ `TooltipProvider` is mounted inside `OpsfuseThemeProvider` / `OpsfuseRoot` (already done in `main.tsx` when you use that root).
340
+
341
+ ```tsx
342
+ import { Tooltip } from "opsfuse-ui";
343
+ import { Info } from "opsfuse-ui/icons";
344
+
345
+ <Tooltip content={"This is info text"}>
346
+ <Button size="icon">
347
+ <Info />
348
+ </Button>
349
+ </Tooltip>;
350
+ ```
351
+
352
+ Wrapper props:
353
+
354
+ - `content`: string or React node
355
+ - `side`: `top` | `bottom` | `left` | `right` (default `top`)
356
+ - `align`: `start` | `center` | `end` (default `center`)
357
+ - `hidden`: hides tooltip content
358
+ - `className`: style override for `TooltipContent`
359
+
360
+ Visual variants are done via `className` on the wrapper:
361
+
362
+ - default: no extra classes
363
+ - subtle: `border border-border bg-card text-card-foreground shadow-sm`
364
+ - primary: `bg-primary text-primary-foreground`
365
+
366
+ ---
367
+
368
+ ## Popover
369
+
370
+ **File:** `src/components/ui/popover.tsx`
371
+ **Export:** `Popover`, `PopoverTrigger`, `PopoverContent`, `PopoverAnchor`
372
+
373
+ Floating content panel anchored to a trigger. Use for pickers, inline forms, rich tooltips.
374
+
375
+ ---
376
+
377
+ ## Hover Card
378
+
379
+ **File:** `src/components/ui/hover-card.tsx`
380
+ **Export:** `HoverCard`, `HoverCardTrigger`, `HoverCardContent`
381
+
382
+ Preview card on hover. Use for user profile previews, link previews.
383
+
384
+ ---
385
+
386
+ ## Dropdown Menu
387
+
388
+ **File:** `src/components/ui/dropdown-menu.tsx`
389
+ **Export:** default `DropdownMenu`
390
+
391
+ ```tsx
392
+ import { DropdownMenu } from "opsfuse-ui";
393
+ import { MoreHorizontal, User, Settings, LogOut } from "opsfuse-ui/icons";
394
+
395
+ <DropdownMenu
396
+ triggerIcon={<MoreHorizontal />}
397
+ triggerSize="icon"
398
+ triggerVariant="ghost"
399
+ label="My Account"
400
+ options={[
401
+ {
402
+ label: "Profile",
403
+ value: "profile",
404
+ icon: <User />,
405
+ shortcut: "⇧⌘P",
406
+ onClick: (val) => console.log(val),
407
+ },
408
+ { label: "Settings", value: "settings", icon: <Settings /> },
409
+ {
410
+ label: "Log out",
411
+ value: "logout",
412
+ icon: <LogOut />,
413
+ variant: "destructive",
414
+ separator: true,
415
+ },
416
+ ]}
417
+ />;
418
+ ```
419
+
420
+ Wrapper around shadcn dropdown primitives with a simple `options` API. Use for account menus and compact action menus.
421
+
422
+ ### Props
423
+
424
+ - `options`: array of `{ label, value, icon?, variant?, shortcut?, separator?, onClick? }`
425
+ - `onClick`: callback `(value: string) => void` triggered when the item is clicked.
426
+ - Trigger controls: `triggerLabel`, `triggerIcon`, `triggerIconPosition` (`"left" | "right"`, default `"left"`), `triggerVariant`, `triggerSize`, `triggerLoading`, `triggerLoadingText`, `triggerClassName`.
427
+ - `trigger`: optional `ReactNode` for fully custom trigger markup.
428
+ - `label`: optional header text for the menu.
429
+ - `side`: `"top" | "right" | "bottom" | "left"` — preferred side for the content.
430
+ - `align`: `"start" | "center" | "end"` — alignment along the trigger edge.
431
+ - `contentClassName`: style override for the dropdown content.
432
+
433
+ ---
434
+
435
+ ## Context Menu
436
+
437
+ **File:** `src/components/ui/context-menu.tsx`
438
+ **Export:** `ContextMenu`, `ContextMenuTrigger`, `ContextMenuContent`, `ContextMenuItem`, `ContextMenuCheckboxItem`, `ContextMenuRadioItem`, `ContextMenuLabel`, `ContextMenuSeparator`, `ContextMenuSub`, `ContextMenuSubTrigger`, `ContextMenuSubContent`, `ContextMenuShortcut`
439
+
440
+ Right-click context menu. Same API shape as DropdownMenu.
441
+
442
+ ---
443
+
444
+ ## Menubar
445
+
446
+ **File:** `src/components/ui/menubar.tsx`
447
+ **Export:** `Menubar`, `MenubarMenu`, `MenubarTrigger`, `MenubarContent`, `MenubarItem`, `MenubarSeparator`, `MenubarLabel`, `MenubarCheckboxItem`, `MenubarRadioGroup`, `MenubarRadioItem`, `MenubarSub`, `MenubarSubTrigger`, `MenubarSubContent`, `MenubarShortcut`
448
+
449
+ Horizontal app menu bar (File, Edit, View…).
450
+
451
+ ---
452
+
453
+ ## Navigation Menu
454
+
455
+ **File:** `src/components/ui/navigation-menu.tsx`
456
+ **Export:** `NavigationMenu`, `NavigationMenuList`, `NavigationMenuItem`, `NavigationMenuTrigger`, `NavigationMenuContent`, `NavigationMenuLink`, `NavigationMenuIndicator`, `NavigationMenuViewport`
457
+
458
+ Mega-menu style navigation with flyout panels.
459
+
460
+ ---
461
+
462
+ ## Command
463
+
464
+ **File:** `src/components/ui/command.tsx`
465
+ **Export:** `Command`, `CommandDialog`, `CommandInput`, `CommandList`, `CommandEmpty`, `CommandGroup`, `CommandItem`, `CommandSeparator`, `CommandShortcut`
466
+
467
+ Command palette (⌘K style). Use for search + action launchers.
468
+
469
+ ---
470
+
471
+ ## Combobox
472
+
473
+ **File:** `src/components/ui/combobox.tsx`
474
+ **Export:** default `Combobox` wrapper + named base-ui primitives (`CCombobox`, `ComboboxInput`, `ComboboxTrigger`, `ComboboxContent`, `ComboboxList`, `ComboboxCollection`, `ComboboxItem`, `ComboboxGroup`, `ComboboxLabel`, `ComboboxSeparator`, `ComboboxEmpty`, `ComboboxValue`, `ComboboxField`, `ComboboxChips`, `ComboboxChip`, `ComboboxChipsInput`, `useComboboxAnchor`)
475
+
476
+ Searchable select dropdown built on `@base-ui/react` combobox. Use when the option list is long or filterable; supports both single and multi-select.
477
+
478
+ ```tsx
479
+ import { Combobox } from "opsfuse-ui";
480
+ import { AppleIcon, BananaIcon } from "lucide-react";
481
+
482
+ // Single select
483
+ <Combobox
484
+ fieldLabel="Favourite fruit"
485
+ placeholder="Search a fruit"
486
+ options={[
487
+ { label: "Apple", value: "apple", icon: <AppleIcon /> },
488
+ { label: "Banana", value: "banana", icon: <BananaIcon /> },
489
+ { label: "Cherry", value: "cherry", separator: true },
490
+ ]}
491
+ onValueChange={(option) => console.log(option?.value)}
492
+ />;
493
+
494
+ // Multi-select with chips
495
+ <Combobox
496
+ multiple
497
+ fieldLabel="Favourite fruits"
498
+ placeholder="Pick fruits"
499
+ options={fruitOptions}
500
+ onValueChange={(options) => console.log(options.map((o) => o.value))}
501
+ />;
502
+ ```
503
+
504
+ Wrapper props:
505
+
506
+ - `options`: array of `{ label, value, disabled?, separator?, icon?, iconPosition? }`
507
+ - `iconPosition`: `"inline-start"` (default) | `"inline-end"`
508
+ - `multiple`: `boolean` — when `true`, the input renders as a chips field and `value` / `defaultValue` / `onValueChange` use arrays
509
+ - `value` / `defaultValue` — `ComboboxOption | null` (single) or `ComboboxOption[]` (multiple)
510
+ - `onValueChange` — `(value: ComboboxOption | null) => void` (single) or `(value: ComboboxOption[]) => void` (multiple)
511
+ - `placeholder`, `groupLabel`, `emptyMessage` (default `"No results found."`)
512
+ - `placeholderIcon`: optional `React.ReactNode` shown at the start of the input/chips field (inline-start only)
513
+ - `fieldLabel`, `helperText`, `error`
514
+ - `showTrigger` (default `true`), `showClear` (default `false`) — single-select input affordances
515
+ - `disabled`, `name`, `required`, `open`, `onOpenChange`
516
+ - class hooks: `fieldClassName`, `inputClassName`, `contentClassName`
517
+
518
+ For full composition (custom trigger, button-style trigger, custom item rendering), use the named primitives — see `Autocomplete` for a button-trigger example.
519
+
520
+ ---
521
+
522
+ ## Tabs
523
+
524
+ **File:** `src/components/ui/tabs.tsx`
525
+ **Export:** default `Tabs` wrapper + named shadcn primitives (`Tabs` as `STabs`, `TabsList`, `TabsTrigger`, `TabsContent`)
526
+
527
+ ```tsx
528
+ import {
529
+ Tabs,
530
+ TabsList,
531
+ TabsTrigger,
532
+ TabsContent,
533
+ TabsComponent,
534
+ } from "opsfuse-ui";
535
+ import { BarChart2, Settings } from "opsfuse-ui/icons";
536
+
537
+ <TabsComponent
538
+ orientation="horizontal"
539
+ variant="line"
540
+ className="w-96"
541
+ tabs={[
542
+ {
543
+ value: "overview",
544
+ label: "Overview",
545
+ icon: <BarChart2 />,
546
+ content: <p>Overview content.</p>,
547
+ },
548
+ {
549
+ value: "settings",
550
+ label: "Settings",
551
+ icon: <Settings />,
552
+ content: <p>Settings content.</p>,
553
+ disabled: false,
554
+ },
555
+ ]}
556
+ />;
557
+ ```
558
+
559
+ Wrapper props:
560
+
561
+ - `tabs`: array of `{ value, label, content, icon?, disabled? }`
562
+ - `orientation`: `"horizontal"` (default) | `"vertical"`
563
+ - `variant`: `"line"` (default, underline style) | `"default"` (pill bg)
564
+ - `defaultValue`: initially selected tab — defaults to first tab if omitted
565
+ - `value` / `onValueChange`: controlled mode
566
+ - `className`: applied to the root
567
+ - `listClassName`: applied to `TabsList`
568
+ - `contentClassName`: applied to each `TabsContent`
569
+
570
+ For full composition (custom trigger content, badge counts, mixed layouts), use the named primitives:
571
+
572
+ ```tsx
573
+ import { Tabs, TabsList, TabsTrigger, TabsContent } from "opsfuse-ui";
574
+
575
+ <Tabs defaultValue="overview" orientation="horizontal">
576
+ <TabsList variant="line">
577
+ <TabsTrigger value="overview">Overview</TabsTrigger>
578
+ <TabsTrigger value="settings">Settings</TabsTrigger>
579
+ </TabsList>
580
+ <TabsContent value="overview">...</TabsContent>
581
+ <TabsContent value="settings">...</TabsContent>
582
+ </Tabs>;
583
+ ```
584
+
585
+ ### Vertical Sidebar Layout
586
+
587
+ For a premium sidebar navigation (ideal for Settings pages), use `orientation="vertical"` with the `line` variant. The primitives are optimized for this layout:
588
+
589
+ ```tsx
590
+ import { Tabs, TabsList, TabsTrigger, TabsContent } from "opsfuse-ui";
591
+ import { User, Shield, Bell } from "opsfuse-ui/icons";
592
+
593
+ <Tabs defaultValue="profile" orientation="vertical" className="w-full gap-6">
594
+ {/* Sidebar */}
595
+ <TabsList
596
+ variant="line"
597
+ className="w-[250px] shrink-0 flex flex-row md:flex-col h-auto md:h-full justify-start gap-1 bg-muted/10 p-4 overflow-y-auto"
598
+ >
599
+ <TabsTrigger value="profile">
600
+ <User /> Profile
601
+ </TabsTrigger>
602
+ <TabsTrigger value="security">
603
+ <Shield /> Security
604
+ </TabsTrigger>
605
+ <TabsTrigger value="notifications">
606
+ <Bell /> Notifications
607
+ </TabsTrigger>
608
+ </TabsList>
609
+
610
+ {/* Main Content Area */}
611
+ <TabsContent value="profile" className="flex-1">
612
+ Profile Settings Content
613
+ </TabsContent>
614
+ <TabsContent value="security">
615
+ Security Settings Content
616
+ </TabsContent>
617
+ </Tabs>
618
+ ```
619
+
620
+ > [!TIP]
621
+ > The `line` variant automatically applies `rounded-md`, `py-2.5`, and `text-primary` for the active state, making it perfect for sidebar items. Adding `bg-muted/10` to the `TabsList` and `data-[state=active]:bg-primary/10` to triggers (if desired) further enhances the premium feel.
622
+
623
+ ---
624
+
625
+ ## Accordion
626
+
627
+ **File:** `src/components/ui/accordion.tsx`
628
+ **Export:** default `Accordion` wrapper + named shadcn primitives (`Accordion` as `SAccordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`)
629
+
630
+ ```tsx
631
+ import {
632
+ Accordion,
633
+ AccordionItem,
634
+ AccordionTrigger,
635
+ AccordionContent,
636
+ } from "opsfuse-ui";
637
+
638
+ <Accordion
639
+ type="single"
640
+ collapsible
641
+ className="w-96"
642
+ items={[
643
+ {
644
+ value: "item-1",
645
+ trigger: "Is it accessible?",
646
+ content: "Yes. It adheres to the WAI-ARIA design pattern.",
647
+ },
648
+ {
649
+ value: "item-2",
650
+ trigger: "Is it styled?",
651
+ content: "Yes. It comes with default styles.",
652
+ },
653
+ {
654
+ value: "item-3",
655
+ trigger: "Is it animated?",
656
+ content: "Yes. Animated by default.",
657
+ disabled: false,
658
+ },
659
+ ]}
660
+ />;
661
+ ```
662
+
663
+ Wrapper props:
664
+
665
+ - `items`: array of `{ value, trigger, content, disabled? }`
666
+ - `type`: `"single"` (default) | `"multiple"`
667
+ - `collapsible`: boolean (default `true`, applies to `type="single"` only)
668
+ - `defaultValue`: pre-opened item(s) — `string` for single, `string[]` for multiple
669
+ - `value` / `onValueChange`: controlled mode
670
+ - `className`: applied to the root
671
+
672
+ For full composition (custom item structure, nested content), use the named primitives:
673
+
674
+ ```tsx
675
+ import {
676
+ Accordion,
677
+ AccordionItem,
678
+ AccordionTrigger,
679
+ AccordionContent,
680
+ } from "opsfuse-ui";
681
+
682
+ <Accordion type="single" collapsible className="w-96">
683
+ <AccordionItem value="item-1">
684
+ <AccordionTrigger>Is it accessible?</AccordionTrigger>
685
+ <AccordionContent>
686
+ Yes. It adheres to the WAI-ARIA design pattern.
687
+ </AccordionContent>
688
+ </AccordionItem>
689
+ </Accordion>;
690
+ ```
691
+
692
+ ---
693
+
694
+ ## Collapsible
695
+
696
+ **File:** `src/components/ui/collapsible.tsx`
697
+ **Export:** `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent`
698
+
699
+ Single expand/collapse control. Lighter than Accordion.
700
+
701
+ ---
702
+
703
+ ## Alert
704
+
705
+ **File:** `src/components/ui/alert.tsx`
706
+ **Export:** `Alert`, `AlertTitle`, `AlertDescription`
707
+
708
+ ```tsx
709
+ import { Alert, AlertTitle, AlertDescription } from "opsfuse-ui";
710
+ import { AlertCircle } from "opsfuse-ui/icons";
711
+
712
+ <Alert variant="destructive">
713
+ <AlertCircle />
714
+ <AlertTitle>Error</AlertTitle>
715
+ <AlertDescription>Something went wrong.</AlertDescription>
716
+ </Alert>;
717
+ ```
718
+
719
+ `variant`: `"default"` | `"destructive"`. Lead with a Lucide icon as a direct child — it gets auto-positioned.
720
+
721
+ ---
722
+
723
+ ## Autocomplete
724
+
725
+ **File:** `src/components/ui/autocomplete.tsx`
726
+ **Export:** `Autocomplete`, `AutocompleteItem`, `AutocompleteProps`
727
+
728
+ ```tsx
729
+ import { Autocomplete } from "@/components/ui/autocomplete";
730
+
731
+ // Single-select (button trigger)
732
+ <Autocomplete
733
+ items={[
734
+ { value: "react", label: "React" },
735
+ { value: "vue", label: "Vue" },
736
+ { value: "angular", label: "Angular" },
737
+ ]}
738
+ placeholder="Select a framework"
739
+ onValueChange={(value) => console.log(value?.value)}
740
+ />;
741
+
742
+ // Multi-select (renders chips instead of button)
743
+ <Autocomplete
744
+ items={frameworks}
745
+ multiple
746
+ label="Frameworks"
747
+ placeholder="Pick frameworks"
748
+ onValueChange={(values) => console.log(values.map((v) => v.value))}
749
+ />;
750
+ ```
751
+
752
+ Simplified wrapper around `CCombobox` with a button trigger for single-select and chips for multi-select. Use for searchable select dropdowns with a cleaner API than raw Combobox.
753
+
754
+ **Props:**
755
+
756
+ | Prop | Type | Default | Description |
757
+ | --------------- | --------------------------------- | ------------------- | ------------------------------------------------------------ |
758
+ | `items` | `AutocompleteItem[]` | required | Array of `{ value, label, ... }` objects |
759
+ | `multiple` | `boolean` | `false` | Switch to multi-select with chips |
760
+ | `value` | `T \| T[]` | — | Controlled selected value (`T[]` when `multiple`) |
761
+ | `defaultValue` | `T \| T[]` | — | Uncontrolled default value (`T[]` when `multiple`) |
762
+ | `placeholder` | `string` | `"Select..."` | Placeholder text when nothing selected |
763
+ | `emptyMessage` | `string` | `"No items found."` | Message shown when filter returns no results |
764
+ | `disabled` | `boolean` | `false` | Disables the trigger / chips input |
765
+ | `triggerWidth` | `string` | `"w-64"` | Tailwind width class applied to trigger or chips container |
766
+ | `label` | `string` | — | Label rendered above the field |
767
+ | `placeholderIcon` | `React.ReactNode` | — | Icon rendered at the start of the trigger/chips field (inline-start only) |
768
+ | `onValueChange` | `(value: T \| null \| T[]) => void` | — | Callback — `T \| null` for single, `T[]` for multiple |
769
+
770
+ `AutocompleteItem` interface: `{ value: string; label: string; [key: string]: string }` — extend with extra fields as needed.
771
+
772
+ ---
773
+
774
+ ## Avatar
775
+
776
+ **File:** `src/components/ui/avatar.tsx`
777
+ **Export:** default `Avatar` (props for image URL, alt text, fallback label, and size)
778
+
779
+ ```tsx
780
+ import { Avatar } from "opsfuse-ui";
781
+
782
+ <Avatar src="https://..." alt="User" fallback="PB" size="default" />;
783
+ ```
784
+
785
+ **Props:** `src?`, `alt?`, `fallback?`, `size` (`"default"` | `"sm"` | `"lg"`). Omit `src` to show only initials or placeholder text.
786
+
787
+ Overlapping stacks (`AvatarGroup`, `AvatarGroupCount`) and low-level composition (`AvatarImage`, `AvatarFallback` as separate children) live in `src/components/ui/shadcn/shadcn-avatar.tsx`.
788
+
789
+ ---
790
+
791
+ ## Skeleton
792
+
793
+ **File:** `src/components/ui/skeleton.tsx`
794
+ **Export:** `Skeleton`
795
+
796
+ Loading placeholder with shimmer animation. Apply `className` for sizing.
797
+
798
+ ---
799
+
800
+ ## Spinner
801
+
802
+ **File:** `src/components/ui/spinner.tsx`
803
+ **Export:** `Spinner`
804
+
805
+ Circular loading indicator. Used internally by `Button loading`. Use `className="animate-spin"`.
806
+
807
+ ---
808
+
809
+ ## Progress
810
+
811
+ **File:** `src/components/ui/progress.tsx`
812
+ **Export:** `Progress`
813
+
814
+ Linear progress bar. `value` prop (0–100). Root uses `.score-track`; indicator uses `.score-fill` + `.transition-data`.
815
+
816
+ **`tone` prop** (indicator color — aligns with `.score-fill-*` in `src/index.css`):
817
+
818
+ | `tone` | Maps to |
819
+ | --------- | ---------------------------- |
820
+ | `default` | Primary fill (`.score-fill`) |
821
+ | `ai` | `.score-fill-ai` |
822
+ | `success` | `.score-fill-good` |
823
+ | `warning` | `.score-fill-warn` |
824
+ | `danger` | `.score-fill-danger` |
825
+
826
+ **CSS alternative for score bars:**
827
+
828
+ ```html
829
+ <div class="score-track">
830
+ <div
831
+ class="score-fill score-fill-good transition-data"
832
+ style="width: 78%"
833
+ ></div>
834
+ </div>
835
+ ```
836
+
837
+ Fill classes: `.score-fill-good`, `.score-fill-warn`, `.score-fill-danger`, `.score-fill-ai`
838
+
839
+ ---
840
+
841
+ ## Separator
842
+
843
+ **File:** `src/components/ui/separator.tsx`
844
+ **Export:** `Separator`
845
+
846
+ Horizontal or vertical divider. `orientation="horizontal"` (default) | `"vertical"`.
847
+
848
+ ---
849
+
850
+ ## Scroll Area
851
+
852
+ **File:** `src/components/ui/scroll-area.tsx`
853
+ **Export:** `ScrollArea`, `ScrollBar`
854
+
855
+ Custom-styled scrollable container. Wraps content that may overflow.
856
+
857
+ ---
858
+
859
+ ## Table
860
+
861
+ **File:** `src/components/ui/table.tsx`
862
+ **Export:** `Table`, `TableHeader`, `TableBody`, `TableFooter`, `TableRow`, `TableHead`, `TableCell`, `TableCaption`
863
+
864
+ Standard HTML table with OpsFuse styling. No built-in sorting/pagination — compose with external state.
865
+
866
+ ---
867
+
868
+ ## Calendar
869
+
870
+ **File:** `src/components/ui/calendar.tsx`
871
+ **Export:** `Calendar`
872
+
873
+ Date picker calendar. Pairs with `Popover` for inline date pickers.
874
+
875
+ ---
876
+
877
+ ## Sonner (Toast)
878
+
879
+ **File:** `src/components/ui/sonner.tsx`
880
+ **Export:** `Toaster`
881
+
882
+ `Toaster` must be mounted at root (`main.tsx`). Trigger toasts imperatively:
883
+
884
+ ```tsx
885
+ import { toast } from "sonner";
886
+ toast.success("Saved!");
887
+ toast.error("Something went wrong");
888
+ toast("Info message");
889
+ ```
890
+
891
+ ---
892
+
893
+ ## Input OTP
894
+
895
+ **File:** `src/components/ui/input-otp.tsx`
896
+ **Export:** `InputOTP`, `InputOTPGroup`, `InputOTPSlot`, `InputOTPSeparator`
897
+
898
+ 6-digit OTP input with individual character boxes.
899
+
900
+ ---
901
+
902
+ ## Field
903
+
904
+ **File:** `src/components/ui/field.tsx`
905
+ **Export:** `Field` (and related parts)
906
+
907
+ Form field wrapper that handles label + input + error message layout.
908
+
909
+ ---
910
+
911
+ ## Form (TanStack Form)
912
+
913
+ **File:** `src/components/ui/form.tsx`
914
+ **Exports:** `fieldContext`, `formContext`, `useFieldContext`, `useFormContext`, `createFormHook`, `FormItem`, `FormLabel`, `FormControl`, `FormDescription`, `FormMessage`
915
+
916
+ Shadcn-style bridge layer for [`@tanstack/react-form`](https://tanstack.com/form). Provides a shared React context pair and styled UI wrappers that read field state without prop drilling.
917
+
918
+ ### Setup — create a typed form hook (once per app)
919
+
920
+ ```tsx
921
+ import { fieldContext, formContext, createFormHook } from "opsfuse-ui";
922
+ import { TextField } from "@/components/fields/text-field"; // your own components
923
+
924
+ const { useAppForm, withForm } = createFormHook({
925
+ fieldContext,
926
+ formContext,
927
+ fieldComponents: { TextField },
928
+ formComponents: {},
929
+ });
930
+
931
+ export { useAppForm, withForm };
932
+ ```
933
+
934
+ ### Basic usage
935
+
936
+ ```tsx
937
+ import { useAppForm } from "@/lib/form";
938
+ import {
939
+ FormItem,
940
+ FormLabel,
941
+ FormControl,
942
+ FormDescription,
943
+ FormMessage,
944
+ } from "opsfuse-ui";
945
+ import { Input } from "opsfuse-ui";
946
+
947
+ function ProfileForm() {
948
+ const form = useAppForm({
949
+ defaultValues: { email: "", name: "" },
950
+ onSubmit: async ({ value }) => console.log(value),
951
+ });
952
+
953
+ return (
954
+ <form
955
+ onSubmit={(e) => {
956
+ e.preventDefault();
957
+ form.handleSubmit();
958
+ }}
959
+ className="flex flex-col gap-4"
960
+ >
961
+ <form.AppField
962
+ name="email"
963
+ validators={{
964
+ onChange: ({ value }) => (!value ? "Email is required" : undefined),
965
+ }}
966
+ >
967
+ {(field) => (
968
+ <FormItem>
969
+ <FormLabel>Email</FormLabel>
970
+ <FormControl>
971
+ <Input
972
+ id={field.name}
973
+ value={field.state.value}
974
+ onChange={(e) => field.handleChange(e.target.value)}
975
+ onBlur={field.handleBlur}
976
+ />
977
+ </FormControl>
978
+ <FormDescription>We'll never share your email.</FormDescription>
979
+ <FormMessage />
980
+ </FormItem>
981
+ )}
982
+ </form.AppField>
983
+
984
+ <form.Subscribe selector={(s) => s.canSubmit}>
985
+ {(canSubmit) => (
986
+ <Button type="submit" disabled={!canSubmit}>
987
+ Submit
988
+ </Button>
989
+ )}
990
+ </form.Subscribe>
991
+ </form>
992
+ );
993
+ }
994
+ ```
995
+
996
+ ### UI wrapper components
997
+
998
+ | Component | Purpose |
999
+ | ----------------- | ----------------------------------------------------------------------- |
1000
+ | `FormItem` | `<div>` container; `flex-col gap-1.5` |
1001
+ | `FormLabel` | `<Label>` auto-linked to field name; turns `text-destructive` on errors |
1002
+ | `FormControl` | `<div>` passthrough; sets `aria-describedby` + `aria-invalid` |
1003
+ | `FormDescription` | `<p>` muted helper text below the control |
1004
+ | `FormMessage` | `<p role="alert">` showing first validation error (or custom children) |
1005
+
1006
+ All wrappers call `useFieldContext()` internally — they **must** be rendered inside a `form.AppField` (or equivalent `fieldContext.Provider`).
1007
+
1008
+ ### Notes
1009
+
1010
+ - `useFieldContext<T>()` — access the raw `FieldApi` with typed value
1011
+ - `useFormContext()` — access the raw `FormApi`
1012
+ - Validators live on `form.AppField` (`onChange`, `onBlur`, `onSubmit`, `onMount`)
1013
+ - Use `useStore(field.store, selector)` for reactive field-state subscriptions
1014
+ - Does **not** depend on Zod; bring your own validation library
1015
+
1016
+ ---
1017
+
1018
+ ## Input Group
1019
+
1020
+ **File:** `src/components/ui/input-group.tsx`
1021
+ **Export:** `InputGroup` (and related parts)
1022
+
1023
+ Groups input with prefix/suffix addons (e.g. `https://` prefix, `.com` suffix).
1024
+
1025
+ ---
1026
+
1027
+ ## Native Select
1028
+
1029
+ **File:** `src/components/ui/native-select.tsx`
1030
+ **Export:** `NativeSelect`
1031
+
1032
+ Styled `<select>` element. Use when a native OS dropdown is preferred over the custom Select.
1033
+
1034
+ ---
1035
+
1036
+ ## KBD
1037
+
1038
+ **File:** `src/components/ui/kbd.tsx`
1039
+ **Export:** `Kbd`
1040
+
1041
+ Keyboard shortcut display: `<Kbd>⌘K</Kbd>`.
1042
+
1043
+ ---
1044
+
1045
+ ## Item
1046
+
1047
+ **File:** `src/components/ui/item.tsx`
1048
+ **Export:** `Item` (and related parts)
1049
+
1050
+ Versatile list item / row component for menus, lists, and navigation items.
1051
+
1052
+ ---
1053
+
1054
+ ## Empty
1055
+
1056
+ **File:** `src/components/ui/empty.tsx`
1057
+ **Export:** default `Empty` (`import { Empty } from "opsfuse-ui"`)
1058
+
1059
+ Opinionated empty state when a list or page has no data. **Props:** `description` (string, required), optional `title`, `actionLabel`, `onAction` (no-op default), `icon` (e.g. a Lucide icon node), and `children` (extra controls in the content area, shown before the primary button). The root uses `w-80`.
1060
+
1061
+ ```tsx
1062
+ import { Empty } from "opsfuse-ui";
1063
+ import { Inbox } from "opsfuse-ui/icons";
1064
+
1065
+ <Empty
1066
+ title="No messages"
1067
+ description="You don't have any messages yet."
1068
+ icon={<Inbox />}
1069
+ actionLabel="New message"
1070
+ onAction={() => openComposer()}
1071
+ />;
1072
+ ```
1073
+
1074
+ For full composition (custom structure, multiple actions, different widths), use primitives from `src/components/ui/shadcn/shadcn-empty.tsx` (`Empty`, `EmptyHeader`, `EmptyMedia`, `EmptyTitle`, `EmptyDescription`, `EmptyContent`).
1075
+
1076
+ ---
1077
+
1078
+ ## Breadcrumb
1079
+
1080
+ **File:** `src/components/ui/breadcrumb.tsx`
1081
+ **Export:** `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis`
1082
+
1083
+ ---
1084
+
1085
+ ## PageHeader
1086
+
1087
+ **File:** `src/components/ui/Header.tsx`
1088
+ **Export:** `PageHeader`, `PageHeaderProps`
1089
+
1090
+ Stacked page chrome aligned with SkillReady report headers (`design/skillready/pencil-v2.pen` — breadcrumb row, serif `h1`, muted description, optional right actions, bottom border).
1091
+
1092
+ ```tsx
1093
+ import {
1094
+ PageHeader,
1095
+ Breadcrumb,
1096
+ BreadcrumbItem,
1097
+ BreadcrumbLink,
1098
+ BreadcrumbList,
1099
+ BreadcrumbPage,
1100
+ BreadcrumbSeparator,
1101
+ Button,
1102
+ } from "opsfuse-ui";
1103
+
1104
+ <PageHeader
1105
+ title="React Core Fundamentals"
1106
+ description="Comprehensive breakdown of your React core competencies and assessment performance."
1107
+ breadcrumb={
1108
+ <Breadcrumb>
1109
+ <BreadcrumbList>
1110
+ <BreadcrumbItem>
1111
+ <BreadcrumbLink href="/practice">Practice</BreadcrumbLink>
1112
+ </BreadcrumbItem>
1113
+ <BreadcrumbSeparator />
1114
+ <BreadcrumbItem>
1115
+ <BreadcrumbPage>React Core Fundamentals · Report</BreadcrumbPage>
1116
+ </BreadcrumbItem>
1117
+ </BreadcrumbList>
1118
+ </Breadcrumb>
1119
+ }
1120
+ rightContent={
1121
+ <>
1122
+ <Button variant="outline">Download PDF</Button>
1123
+ <Button>Practice Again</Button>
1124
+ </>
1125
+ }
1126
+ />;
1127
+ ```
1128
+
1129
+ | Prop | Type | Purpose |
1130
+ | -------------- | ------------ | ----------------------------------------------------- |
1131
+ | `title` | `string` | Main heading (`h1`, `font-heading` / Noto Serif ramp) |
1132
+ | `description` | `string?` | Subline under the title |
1133
+ | `breadcrumb` | `ReactNode?` | Top row — pass composed `Breadcrumb` |
1134
+ | `rightContent` | `ReactNode?` | Right cluster (buttons, menus); wraps with `gap-3` |
1135
+
1136
+ Root is a `<header>`; native `title` tooltip prop is omitted from the public type in favor of the required `title` string for the visible heading.
1137
+
1138
+ ---
1139
+
1140
+ ## Pagination
1141
+
1142
+ **File:** `src/components/ui/pagination.tsx`
1143
+ **Export:** default `PaginationWrapper` + named primitives (`Pagination`, `PaginationContent`, `PaginationItem`, `PaginationLink`, `PaginationPrevious`, `PaginationNext`, `PaginationEllipsis`)
1144
+
1145
+ ```tsx
1146
+ import PaginationWrapper from "opsfuse-ui";
1147
+ import { useState } from "react";
1148
+
1149
+ const [page, setPage] = useState(1);
1150
+
1151
+ <PaginationWrapper currentPage={page} totalPages={20} onPageChange={setPage} />;
1152
+ ```
1153
+
1154
+ Wrapper props:
1155
+
1156
+ - `currentPage`: active page number (1-based)
1157
+ - `totalPages`: total number of pages
1158
+ - `onPageChange`: callback `(page: number) => void`
1159
+ - `siblingCount`: pages shown on each side of current (default `1`)
1160
+ - `showPrevNext`: show Previous/Next buttons (default `true`)
1161
+ - `showPageLabel`: show a "Page X of Y" label below the pagination (default `false`)
1162
+ - `className`: applied to the root `<nav>`
1163
+
1164
+ Page numbers are auto-computed with ellipsis — always shows first and last page, a window around the current page, and collapses the rest.
1165
+
1166
+ For fully custom layouts (href-based links, custom active state), use the named primitives directly.
1167
+
1168
+ ---
1169
+
1170
+ ## Toggle / Toggle Group
1171
+
1172
+ **File:** `src/components/ui/toggle.tsx`, `toggle-group.tsx`
1173
+ **Export:** `Toggle`, `toggleVariants` / `ToggleGroup`, `ToggleGroupItem`
1174
+
1175
+ `Toggle`: single on/off button. `ToggleGroup`: multi-button selection group (single or multiple selection).
1176
+
1177
+ ---
1178
+
1179
+ ## Carousel
1180
+
1181
+ **File:** `src/components/ui/carousel.tsx`
1182
+ **Export:** `Carousel`, `CarouselContent`, `CarouselItem`, `CarouselPrevious`, `CarouselNext`
1183
+
1184
+ Horizontal scrolling carousel with prev/next controls.
1185
+
1186
+ ---
1187
+
1188
+ ## Resizable
1189
+
1190
+ **File:** `src/components/ui/resizable.tsx`
1191
+ **Export:** `ResizablePanelGroup`, `ResizablePanel`, `ResizableHandle`
1192
+
1193
+ Drag-to-resize panel layout.
1194
+
1195
+ ---
1196
+
1197
+ ## Aspect Ratio
1198
+
1199
+ **File:** `src/components/ui/aspect-ratio.tsx`
1200
+ **Export:** `AspectRatio`
1201
+
1202
+ Constrains child to a fixed aspect ratio: `<AspectRatio ratio={16 / 9}>`.
1203
+
1204
+ ---
1205
+
1206
+ ## Chart
1207
+
1208
+ **File:** `src/components/ui/chart.tsx`
1209
+ **Export:** `ChartContainer`, `ChartTooltip`, `ChartTooltipContent`, `ChartLegend`, `ChartLegendContent`, `ChartStyle`, `type ChartConfig`
1210
+
1211
+ Wraps Recharts with OpsFuse theme tokens (`--chart-1` through `--chart-6`, `--chart-grid`, `--chart-axis`).
1212
+
1213
+ ### Recharts namespace re-export
1214
+
1215
+ The full `recharts` library is re-exported from `opsfuse-ui` as the `Recharts` namespace, so consumers do **not** need to install or import `recharts` directly:
1216
+
1217
+ ```tsx
1218
+ import {
1219
+ Recharts,
1220
+ ChartContainer,
1221
+ ChartTooltip,
1222
+ ChartTooltipContent,
1223
+ ChartLegend,
1224
+ ChartLegendContent,
1225
+ type ChartConfig,
1226
+ } from "opsfuse-ui";
1227
+
1228
+ const data = [
1229
+ { month: "Jan", desktop: 186, mobile: 80 },
1230
+ { month: "Feb", desktop: 305, mobile: 200 },
1231
+ ];
1232
+
1233
+ const config: ChartConfig = {
1234
+ desktop: { label: "Desktop", color: "var(--chart-1)" },
1235
+ mobile: { label: "Mobile", color: "var(--chart-2)" },
1236
+ };
1237
+
1238
+ <ChartContainer config={config} className="h-72 w-full">
1239
+ <Recharts.BarChart data={data}>
1240
+ <Recharts.CartesianGrid vertical={false} stroke="var(--chart-grid)" />
1241
+ <Recharts.XAxis dataKey="month" stroke="var(--chart-axis)" />
1242
+ <ChartTooltip content={<ChartTooltipContent />} />
1243
+ <ChartLegend content={<ChartLegendContent />} />
1244
+ <Recharts.Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
1245
+ <Recharts.Bar dataKey="mobile" fill="var(--color-mobile)" radius={4} />
1246
+ </Recharts.BarChart>
1247
+ </ChartContainer>;
1248
+ ```
1249
+
1250
+ Use `Recharts.<Component>` for every primitive (`BarChart`, `LineChart`, `AreaChart`, `PieChart`, `RadialBarChart`, `RadarChart`, `ScatterChart`, `Bar`, `Line`, `Area`, `Pie`, `Radar`, `Scatter`, `XAxis`, `YAxis`, `CartesianGrid`, `PolarGrid`, `PolarAngleAxis`, etc.).
1251
+
1252
+ ### Color tokens
1253
+
1254
+ Brand chart palette tokens are defined in `src/brands.css` as raw `oklch(...)` values:
1255
+
1256
+ | Token | Use |
1257
+ | ---------------- | ---------------------------- |
1258
+ | `--chart-1`..`6` | Series colors (use in order) |
1259
+ | `--chart-grid` | Cartesian/polar grid stroke |
1260
+ | `--chart-axis` | Axis tick + label color |
1261
+
1262
+ Reference them as `var(--chart-1)` (NOT `hsl(var(--chart-1))` — values are oklch already). Inside `ChartConfig`, mapping `color: "var(--chart-1)"` for a key `desktop` exposes `var(--color-desktop)` as a per-series CSS var on the chart root, which you then pass to `fill` / `stroke` on the Recharts primitives.
1263
+
1264
+ ### ChartConfig shape
1265
+
1266
+ ```ts
1267
+ type ChartConfig = Record<
1268
+ string,
1269
+ {
1270
+ label?: React.ReactNode;
1271
+ icon?: React.ComponentType;
1272
+ } & (
1273
+ | { color?: string; theme?: never }
1274
+ | { color?: never; theme: { light: string; dark: string } }
1275
+ )
1276
+ >;
1277
+ ```
1278
+
1279
+ Use `theme: { light, dark }` instead of `color` when a series needs different colors per mode.
1280
+
1281
+ **Stories:** `src/stories/recharts.stories.tsx` covers Bar / Stacked Bar / Line / Area (gradient) / Pie (donut) / Radial / Radar / Scatter using the `Recharts` namespace. `src/stories/chart.stories.tsx` covers minimal Bar + Line examples using direct `recharts` imports.
1282
+
1283
+ ---
1284
+
1285
+ ## Sidebar
1286
+
1287
+ **File:** `src/components/ui/sidebar.tsx`
1288
+ **Export:** `Sidebar`, `SidebarProvider`, `SidebarTrigger`, `SidebarContent`, `SidebarHeader`, `SidebarFooter`, `SidebarMenu`, `SidebarMenuItem`, `SidebarMenuButton`, `SidebarGroup`, `SidebarGroupLabel`, `SidebarGroupContent`, `SidebarInset`, `SidebarRail`
1289
+
1290
+ Full-featured collapsible sidebar with keyboard nav. Uses `--sidebar`, `--sidebar-foreground`, `--sidebar-accent`, `--sidebar-border`, etc. `SidebarProvider` must wrap the layout.
1291
+
1292
+ ---
1293
+
1294
+ ## Direction
1295
+
1296
+ **File:** `src/components/ui/direction.tsx`
1297
+ **Export:** `Direction`, `DirectionProvider`
1298
+
1299
+ RTL support for Radix primitives.
1300
+
1301
+ ---
1302
+
1303
+ ## Logo Components
1304
+
1305
+ **File:** `src/components/logo/`
1306
+ **Export:** `RecruitSmartly`, `SkillReady`, `TalentScan`, `Verity`, `WorkLog`
1307
+
1308
+ Brand SVG logos. Each accepts standard SVG props. Import from the package root.
1309
+
1310
+ ---
1311
+
1312
+ ## Lucide Icons
1313
+
1314
+ **Subpath:** `opsfuse-ui/icons` (flat re-export of [`lucide-react`](https://lucide.dev/) — 5,800+ icons, fully tree-shakable)
1315
+ **Main entry:** `Lucide` namespace (`import { Lucide } from "opsfuse-ui"`) — only needed for collision cases (see below)
1316
+
1317
+ ### Direct named import (preferred)
1318
+
1319
+ Import any icon from `opsfuse-ui/icons` and render it as a JSX element. Editor autocomplete resolves the entire Lucide catalog from the bundled types — no need to install `lucide-react` directly.
1320
+
1321
+ ```tsx
1322
+ import { Home, Search, Bell, Star, Plus, ChevronDown } from "opsfuse-ui/icons";
1323
+ import { Button } from "opsfuse-ui";
1324
+
1325
+ <Search />
1326
+ <Star size={20} strokeWidth={1.5} className="text-primary" />
1327
+
1328
+ <Button>
1329
+ <Plus />
1330
+ New item
1331
+ </Button>
1332
+ ```
1333
+
1334
+ ### Name collisions with components
1335
+
1336
+ Seven Lucide icon names collide with opsfuse component exports: `Badge`, `Calendar`, `Command`, `Form`, `Sheet`, `Sidebar`, `Table`. Two ways to resolve:
1337
+
1338
+ ```tsx
1339
+ // Option A — alias on import
1340
+ import { Calendar as CalendarIcon, Sidebar as SidebarIcon } from "opsfuse-ui/icons";
1341
+
1342
+ // Option B — use the Lucide namespace from the main entry
1343
+ import { Lucide, Calendar } from "opsfuse-ui";
1344
+
1345
+ <Calendar /> {/* opsfuse Calendar component */}
1346
+ <Lucide.Calendar /> {/* Lucide icon */}
1347
+ ```
1348
+
1349
+ ### Props
1350
+
1351
+ Every icon is a `LucideIcon` (a `ForwardRefExoticComponent` over `<svg>`). Standard props:
1352
+
1353
+ | Prop | Default | Use |
1354
+ | --------------------- | ------- | --------------------------------------------------- |
1355
+ | `size` | `24` | Width/height in px (number or string) |
1356
+ | `strokeWidth` | `2` | Stroke thickness — use `1.5` for a lighter feel |
1357
+ | `absoluteStrokeWidth` | `false` | Keep stroke px-constant when scaling |
1358
+ | `className` | — | Tailwind classes; color inherits via `currentColor` |
1359
+ | `color` | — | Override stroke color directly (prefer `className`) |
1360
+
1361
+ Color comes from `currentColor`, so style icons via the parent's text color or an explicit `text-*` class — never hardcode `#hex`. Use semantic tokens (`text-foreground`, `text-muted-foreground`, `text-primary`, `text-destructive`, etc.) — not arbitrary Tailwind palette classes.
1362
+
1363
+ ### Typing icon-as-prop slots
1364
+
1365
+ When forwarding an icon component as a prop (e.g. `Empty`'s `icon`, `DropdownMenu`'s `triggerIcon`, custom slots), import the `LucideIcon` type from the icons subpath:
1366
+
1367
+ ```tsx
1368
+ import { type LucideIcon, Inbox } from "opsfuse-ui/icons";
1369
+ import { Empty } from "opsfuse-ui";
1370
+
1371
+ const icon: LucideIcon = Inbox;
1372
+
1373
+ <Empty
1374
+ title="No messages"
1375
+ description="You're all caught up."
1376
+ icon={<Inbox />}
1377
+ />;
1378
+ ```
1379
+
1380
+ ### Dynamic lookup
1381
+
1382
+ For data-driven rendering, import the namespace and index by name:
1383
+
1384
+ ```tsx
1385
+ import * as Icons from "opsfuse-ui/icons";
1386
+
1387
+ const Icon = Icons[name as keyof typeof Icons] as Icons.LucideIcon;
1388
+ <Icon size={20} />;
1389
+ ```
1390
+
1391
+ **Stories:** `src/stories/lucide.stories.tsx` covers Basic Usage (size / strokeWidth / color), Inside Components (Button, InputGroup, Badge), a labelled Icon Gallery, and a dynamic-lookup example.
1392
+
1393
+ ---
1394
+
1395
+ ## Provider / Theme
1396
+
1397
+ **Export:** `OpsfuseThemeProvider`, `OpsfuseRoot`, `OPSFUSE_THEME_SCOPE`, `OPSFUSE_BRAND_THEMES`, `DEFAULT_OPSFUSE_BRAND_THEME`
1398
+
1399
+ `OpsfuseThemeProvider` wraps everything — sets the `.opsfuse-ui` scope class, brand class, dark mode sync, and mounts the global providers (`ConfirmationDialogProvider`, tooltips, alerts, dialogs, sheet, slider dialog, `Toaster`). Required as the root wrapper.
1400
+
1401
+ ```tsx
1402
+ <OpsfuseThemeProvider brand="skillready" darkMode={false}>
1403
+ <App />
1404
+ </OpsfuseThemeProvider>
1405
+ ```
1406
+
1407
+ ---
1408
+
1409
+ ## Choosing the Right Component
1410
+
1411
+ | Scenario | Component |
1412
+ | --------------------------------- | ------------------------------------------------------------------------ |
1413
+ | Single primary action | `Button variant="default"` |
1414
+ | Secondary / cancel | `Button variant="outline"` |
1415
+ | Icon-only action | `Button size="icon"` + `variant="ghost"` |
1416
+ | Navigation between views | `Tabs` |
1417
+ | Long filterable option list | `Combobox` |
1418
+ | Short option list (< 10) | `Select` |
1419
+ | Yes/No toggle | `Switch` |
1420
+ | One-of-many selection | `RadioGroup` |
1421
+ | Many independent toggles | `Checkbox` |
1422
+ | Quick action menu | `DropdownMenu` |
1423
+ | Right-click actions | `ContextMenu` |
1424
+ | Dangerous destructive confirm | `confirm()` + `<ConfirmationDialogProvider />` |
1425
+ | Settings / detail panel | `Sheet` |
1426
+ | Mobile action panel | `Drawer` |
1427
+ | Rich hover preview | `HoverCard` |
1428
+ | ⌘K launcher | `Command` |
1429
+ | Inline date selection | `Calendar` + `Popover` |
1430
+ | Toast notification | `toast()` from sonner |
1431
+ | Loading state | `Skeleton` (layout) or `Spinner` (inline) |
1432
+ | Empty list / no data | `Empty` |
1433
+ | Page title + breadcrumb + actions | `PageHeader` + `Breadcrumb` primitives |
1434
+ | Score / progress display | `<Progress tone="success" />` (etc.) or `.score-track` + `.score-fill-*` |
1435
+ | AI response block | `.strip-ai` + `.prose-ai` |
1436
+ | Status tag | `<Badge variant="accent" />` (pill variants) or `.pill-*` |
1437
+ | AI status indicator | `<Badge variant="aiLive" />` or `.badge-ai` |
1438
+ | Any UI icon | Direct import from `opsfuse-ui/icons` (`<Home />`, `<Search />`) |
1439
+ | Charts / data viz | `Recharts.<Primitive>` wrapped in `ChartContainer` |