opsfuse-ui 0.1.23 → 0.1.25

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