@brightlocal/ui-components 1.1.1 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (122) hide show
  1. package/AI_USAGE.md +390 -0
  2. package/README.md +45 -10
  3. package/component-meta.json +1488 -0
  4. package/dist/blocks/input-list.cjs +2 -0
  5. package/dist/blocks/input-list.d.ts +93 -0
  6. package/dist/blocks/input-list.d.ts.map +1 -0
  7. package/dist/blocks/input-list.js +215 -0
  8. package/dist/blocks/sidebar.d.ts.map +1 -1
  9. package/dist/breadcrumb.cjs +1 -1
  10. package/dist/breadcrumb.d.ts.map +1 -1
  11. package/dist/breadcrumb.js +17 -14
  12. package/dist/button.cjs +1 -1
  13. package/dist/button.d.ts.map +1 -1
  14. package/dist/button.js +9 -8
  15. package/dist/calendar.cjs +1 -1
  16. package/dist/calendar.js +1 -1
  17. package/dist/card.cjs +1 -1
  18. package/dist/card.d.ts.map +1 -1
  19. package/dist/card.js +20 -16
  20. package/dist/centred-layout.cjs +1 -1
  21. package/dist/centred-layout.js +1 -1
  22. package/dist/checkbox.cjs +1 -1
  23. package/dist/checkbox.d.ts.map +1 -1
  24. package/dist/checkbox.js +8 -10
  25. package/dist/combobox.cjs +1 -1
  26. package/dist/combobox.d.ts +12 -1
  27. package/dist/combobox.d.ts.map +1 -1
  28. package/dist/combobox.js +87 -79
  29. package/dist/command.cjs +1 -1
  30. package/dist/command.d.ts.map +1 -1
  31. package/dist/command.js +60 -50
  32. package/dist/date-picker.cjs +1 -1
  33. package/dist/date-picker.d.ts.map +1 -1
  34. package/dist/date-picker.js +66 -57
  35. package/dist/field.cjs +1 -1
  36. package/dist/field.d.ts.map +1 -1
  37. package/dist/field.js +2 -2
  38. package/dist/header.cjs +1 -1
  39. package/dist/header.d.ts +4 -0
  40. package/dist/header.d.ts.map +1 -1
  41. package/dist/header.js +33 -13
  42. package/dist/index.cjs +1 -1
  43. package/dist/index.d.ts +2 -0
  44. package/dist/index.d.ts.map +1 -1
  45. package/dist/index.js +281 -268
  46. package/dist/input-chip.cjs +1 -1
  47. package/dist/input-chip.js +2 -2
  48. package/dist/input-group.cjs +1 -1
  49. package/dist/input-group.js +17 -17
  50. package/dist/input-otp.cjs +1 -1
  51. package/dist/input-otp.d.ts.map +1 -1
  52. package/dist/input-otp.js +20 -20
  53. package/dist/input-password.cjs +1 -1
  54. package/dist/input-password.d.ts.map +1 -1
  55. package/dist/input-password.js +33 -25
  56. package/dist/input.cjs +1 -1
  57. package/dist/input.js +15 -15
  58. package/dist/label.d.ts.map +1 -1
  59. package/dist/link.cjs +1 -1
  60. package/dist/link.d.ts.map +1 -1
  61. package/dist/link.js +24 -25
  62. package/dist/list.cjs +1 -0
  63. package/dist/list.d.ts +104 -0
  64. package/dist/list.d.ts.map +1 -0
  65. package/dist/list.js +145 -0
  66. package/dist/navigation-menu.cjs +1 -1
  67. package/dist/navigation-menu.d.ts.map +1 -1
  68. package/dist/navigation-menu.js +6 -5
  69. package/dist/radio-group.cjs +1 -1
  70. package/dist/radio-group.js +20 -20
  71. package/dist/select.cjs +1 -1
  72. package/dist/select.js +1 -1
  73. package/dist/sheet.d.ts.map +1 -1
  74. package/dist/sonner.cjs +1 -1
  75. package/dist/sonner.d.ts +10 -4
  76. package/dist/sonner.d.ts.map +1 -1
  77. package/dist/sonner.js +69 -56
  78. package/dist/split-layout.cjs +1 -1
  79. package/dist/split-layout.d.ts +66 -15
  80. package/dist/split-layout.d.ts.map +1 -1
  81. package/dist/split-layout.js +100 -96
  82. package/dist/switch.cjs +1 -1
  83. package/dist/switch.d.ts.map +1 -1
  84. package/dist/switch.js +2 -2
  85. package/dist/textarea.cjs +1 -1
  86. package/dist/textarea.js +1 -1
  87. package/dist/tooltip.cjs +1 -1
  88. package/dist/tooltip.d.ts.map +1 -1
  89. package/dist/tooltip.js +40 -38
  90. package/package.json +5 -1
  91. package/src/blocks/input-list.tsx +366 -0
  92. package/src/blocks/sidebar.tsx +7 -7
  93. package/src/components/breadcrumb.tsx +4 -1
  94. package/src/components/button.tsx +1 -0
  95. package/src/components/calendar.tsx +1 -1
  96. package/src/components/card.tsx +8 -4
  97. package/src/components/centred-layout.tsx +1 -1
  98. package/src/components/checkbox.tsx +2 -4
  99. package/src/components/combobox.tsx +21 -2
  100. package/src/components/command.tsx +25 -9
  101. package/src/components/date-picker.tsx +15 -5
  102. package/src/components/dropdown-menu.tsx +3 -3
  103. package/src/components/field.tsx +5 -3
  104. package/src/components/header.tsx +28 -2
  105. package/src/components/input-chip.tsx +2 -2
  106. package/src/components/input-group.tsx +4 -4
  107. package/src/components/input-otp.tsx +7 -3
  108. package/src/components/input-password.tsx +8 -2
  109. package/src/components/input.tsx +1 -1
  110. package/src/components/label.tsx +1 -4
  111. package/src/components/link.tsx +3 -4
  112. package/src/components/list.tsx +290 -0
  113. package/src/components/navigation-menu.tsx +1 -0
  114. package/src/components/radio-group.tsx +2 -2
  115. package/src/components/select.tsx +3 -3
  116. package/src/components/sheet.tsx +2 -2
  117. package/src/components/sonner.tsx +65 -38
  118. package/src/components/split-layout.tsx +200 -79
  119. package/src/components/switch.tsx +6 -4
  120. package/src/components/textarea.tsx +1 -1
  121. package/src/components/tooltip.tsx +4 -2
  122. package/src/index.ts +2 -0
package/AI_USAGE.md ADDED
@@ -0,0 +1,390 @@
1
+ # AI Usage Guide — @brightlocal/ui-components
2
+
3
+ This document provides rules and patterns for AI assistants generating code with the BrightLocal Design System. Following these rules ensures output that is consistent, accessible, and on-system.
4
+
5
+ ## Quick Rules
6
+
7
+ 1. **Import per-file, never barrel** — `import { Button } from "@brightlocal/ui-components/button"`
8
+ 2. **Provide `dataHook` on interactive components** — Required on user-interactive roots (Button, Input, Select, etc.); optional on layout/structural components (Separator, Skeleton, ScrollArea, etc.)
9
+ 3. **Use semantic tokens first; fall back to Tailwind utilities, never raw hex** — prefer `text-primary`, use `text-blue-600` when no semantic token fits, never `#000000`
10
+ 4. **Use DS components, not raw HTML** — `<Button>` not `<button>`, `<Input>` not `<input>`
11
+ 5. **Compose with compound components** — Use the provided sub-component pattern, don't rebuild from primitives
12
+
13
+ ---
14
+
15
+ ## The `dataHook` Prop
16
+
17
+ Most components in this library accept a `dataHook` prop, and it is **required** on all user-interactive components. This is the single most important convention to follow.
18
+
19
+ ### What is it?
20
+
21
+ `dataHook` renders as a `data-hook` HTML attribute used for automated testing and QA selectors. It is **required** on interactive component roots (Button, Input, Select, Dialog, Tabs, etc.) and **optional** on layout/structural components (Separator, Skeleton, ScrollArea, Collapsible, etc.). Check `component-meta.json` for per-component `dataHookRequired` values.
22
+
23
+ ### Naming Convention
24
+
25
+ Use **kebab-case** descriptive names that reflect the component's role in the UI:
26
+
27
+ ```
28
+ {context}-{componentType}
29
+ ```
30
+
31
+ **Examples:**
32
+
33
+ ```tsx
34
+ <Button dataHook="settings-save-button">Save</Button>
35
+ <Input dataHook="login-email-input" />
36
+ <Dialog>
37
+ <DialogTrigger dataHook="delete-confirm-trigger">Delete</DialogTrigger>
38
+ <DialogContent dataHook="delete-confirm-dialog">
39
+ <DialogTitle>Confirm deletion</DialogTitle>
40
+ </DialogContent>
41
+ </Dialog>
42
+ <Card dataHook="user-profile-card">...</Card>
43
+ <Tabs dataHook="dashboard-tabs">...</Tabs>
44
+ ```
45
+
46
+ ### Rules
47
+
48
+ - Use the page/section name as prefix: `login-`, `settings-`, `dashboard-`
49
+ - Use the component type as suffix: `-button`, `-input`, `-dialog`, `-card`
50
+ - For lists, include the item identifier: `user-{id}-row`, `task-{index}-card`
51
+ - Sub-components of compound components inherit context from the parent — only the root or key interactive sub-components need `dataHook`
52
+ - Never use generic names like `hook-1` or `test-button`
53
+
54
+ ---
55
+
56
+ ## Import Conventions
57
+
58
+ ### Correct — Per-file imports
59
+
60
+ ```tsx
61
+ import { Button } from "@brightlocal/ui-components/button";
62
+ import { Input } from "@brightlocal/ui-components/input";
63
+ import { Dialog, DialogContent, DialogTrigger, DialogTitle } from "@brightlocal/ui-components/dialog";
64
+ import { Card, CardHeader, CardContent } from "@brightlocal/ui-components/card";
65
+ import { cn } from "@brightlocal/ui-components/lib/utils";
66
+ import { DataTable } from "@brightlocal/ui-components/blocks/data-table";
67
+ ```
68
+
69
+ ### Wrong — Barrel imports
70
+
71
+ ```tsx
72
+ // NEVER do this — causes large bundle size
73
+ import { Button, Input, Dialog } from "@brightlocal/ui-components";
74
+ ```
75
+
76
+ ### Icons
77
+
78
+ Icons come from a separate package:
79
+
80
+ ```tsx
81
+ import { SearchIcon, ChevronDownIcon, XIcon } from "@brightlocal/icons";
82
+ ```
83
+
84
+ Icons render at 16px by default. Do not pass `size` or `strokeWidth` unless you need a different size.
85
+
86
+ ---
87
+
88
+ ## Styling Rules
89
+
90
+ ### Color Usage
91
+
92
+ **Priority order:** semantic tokens → Tailwind color utilities → never raw hex values.
93
+
94
+ ```tsx
95
+ // BEST — semantic tokens (use whenever a matching token exists)
96
+ <div className="bg-background text-foreground" />
97
+ <div className="bg-primary text-primary-foreground" />
98
+ <div className="bg-muted text-muted-foreground" />
99
+ <div className="border-destructive text-destructive" />
100
+
101
+ // OK — Tailwind color utilities (when no semantic token fits)
102
+ <div className="bg-blue-600 text-white" />
103
+ <div className="bg-gray-100 text-gray-500" />
104
+
105
+ // WRONG — raw hex/rgb values (never use these)
106
+ <div className="bg-[#1e40af] text-[#ffffff]" />
107
+ <div style={{ color: "#000000" }} />
108
+ ```
109
+
110
+ **Available semantic tokens:** `primary`, `secondary`, `destructive`, `muted`, `accent`, `background`, `foreground`, `card`, `popover`, `border`, `input`, `ring`, `warning`, `success`, `info`.
111
+
112
+ ### Spacing
113
+
114
+ Use Tailwind spacing utilities. Prefer consistent spacing:
115
+ - Between form fields: `gap-4` or `space-y-4`
116
+ - Card padding: `p-4` or `p-6`
117
+ - Section spacing: `gap-6` or `gap-8`
118
+
119
+ ### Transitions
120
+
121
+ Always specify the property — never use `transition-all`:
122
+
123
+ ```tsx
124
+ // CORRECT
125
+ <div className="transition-colors duration-200 ease-out" />
126
+ <div className="transition-opacity duration-150 ease-out" />
127
+
128
+ // WRONG
129
+ <div className="transition-all duration-200" />
130
+ ```
131
+
132
+ ### Focus States
133
+
134
+ Always use `focus-visible`, never bare `focus`:
135
+
136
+ ```tsx
137
+ // CORRECT
138
+ <div className="outline-none focus-visible:shadow-default" />
139
+
140
+ // WRONG
141
+ <div className="focus:ring-2 focus:ring-blue-500" />
142
+ ```
143
+
144
+ ### Dark Mode
145
+
146
+ Semantic token classes (e.g., `bg-background`, `text-foreground`, `border-border`) adapt to dark mode automatically via CSS custom properties — no `dark:` prefix needed.
147
+
148
+ Use the `dark:` modifier only for non-token utilities:
149
+
150
+ ```tsx
151
+ <div className="bg-white dark:bg-gray-900" />
152
+ ```
153
+
154
+ ---
155
+
156
+ ## Component Patterns
157
+
158
+ ### Simple Components
159
+
160
+ ```tsx
161
+ <Button dataHook="save-button" variant="default" size="default">
162
+ Save Changes
163
+ </Button>
164
+
165
+ <Input dataHook="search-input" placeholder="Search..." />
166
+
167
+ <Badge dataHook="status-badge" variant="secondary">Active</Badge>
168
+ ```
169
+
170
+ ### Compound Components
171
+
172
+ Many components use a compound pattern with multiple sub-components. Always use the provided sub-components:
173
+
174
+ ```tsx
175
+ // CORRECT — use compound sub-components
176
+ <Card dataHook="profile-card">
177
+ <CardHeader>
178
+ <CardTitle>Profile</CardTitle>
179
+ <CardDescription>Manage your profile settings</CardDescription>
180
+ </CardHeader>
181
+ <CardContent>
182
+ {/* content */}
183
+ </CardContent>
184
+ <CardFooter>
185
+ <Button dataHook="profile-save-button">Save</Button>
186
+ </CardFooter>
187
+ </Card>
188
+
189
+ // WRONG — reconstructing structure with divs
190
+ <Card dataHook="profile-card">
191
+ <div className="p-4 border-b">
192
+ <h3>Profile</h3>
193
+ </div>
194
+ <div className="p-4">{/* content */}</div>
195
+ </Card>
196
+ ```
197
+
198
+ ### Form Fields
199
+
200
+ Always wrap form inputs with `Field` for labels, descriptions, and error states:
201
+
202
+ ```tsx
203
+ <Field>
204
+ <FieldLabel htmlFor="email">Email Address</FieldLabel>
205
+ <Input dataHook="email-input" id="email" type="email" />
206
+ <FieldDescription>We'll never share your email.</FieldDescription>
207
+ <FieldError>Please enter a valid email.</FieldError>
208
+ </Field>
209
+ ```
210
+
211
+ For groups of related fields:
212
+
213
+ ```tsx
214
+ <FieldSet>
215
+ <FieldLegend>Contact Information</FieldLegend>
216
+ <FieldGroup orientation="vertical">
217
+ <Field>
218
+ <FieldLabel htmlFor="name">Name</FieldLabel>
219
+ <Input dataHook="name-input" id="name" />
220
+ </Field>
221
+ <Field>
222
+ <FieldLabel htmlFor="email">Email</FieldLabel>
223
+ <Input dataHook="email-input" id="email" type="email" />
224
+ </Field>
225
+ </FieldGroup>
226
+ </FieldSet>
227
+ ```
228
+
229
+ ### Overlays (Dialogs, Sheets, Drawers)
230
+
231
+ All overlay components follow the same pattern:
232
+
233
+ ```tsx
234
+ <Dialog>
235
+ <DialogTrigger asChild>
236
+ <Button dataHook="open-dialog-button">Open</Button>
237
+ </DialogTrigger>
238
+ <DialogContent dataHook="my-dialog">
239
+ <DialogHeader>
240
+ <DialogTitle>Dialog Title</DialogTitle>
241
+ <DialogDescription>Description of the dialog purpose.</DialogDescription>
242
+ </DialogHeader>
243
+ {/* Dialog body content */}
244
+ <DialogFooter>
245
+ <DialogClose asChild>
246
+ <Button dataHook="dialog-cancel-button" variant="outline">Cancel</Button>
247
+ </DialogClose>
248
+ <Button dataHook="dialog-confirm-button">Confirm</Button>
249
+ </DialogFooter>
250
+ </DialogContent>
251
+ </Dialog>
252
+ ```
253
+
254
+ ### Select / Combobox
255
+
256
+ For simple selection, use `Select`. For searchable/filterable selection, use `Combobox`:
257
+
258
+ ```tsx
259
+ {/* Simple select */}
260
+ <Select value={value} onValueChange={setValue}>
261
+ <SelectTrigger dataHook="country-select">
262
+ <SelectValue placeholder="Select country" />
263
+ </SelectTrigger>
264
+ <SelectContent>
265
+ <SelectItem value="us">United States</SelectItem>
266
+ <SelectItem value="uk">United Kingdom</SelectItem>
267
+ </SelectContent>
268
+ </Select>
269
+
270
+ {/* Searchable combobox */}
271
+ <Combobox value={value} onValueChange={setValue}>
272
+ <ComboboxTrigger dataHook="user-combobox">
273
+ <ComboboxValue placeholder="Select user" />
274
+ </ComboboxTrigger>
275
+ <ComboboxContent>
276
+ <ComboboxInput placeholder="Search users..." />
277
+ <ComboboxEmpty>No users found.</ComboboxEmpty>
278
+ <ComboboxGroup>
279
+ <ComboboxItem value="alice">Alice</ComboboxItem>
280
+ <ComboboxItem value="bob">Bob</ComboboxItem>
281
+ </ComboboxGroup>
282
+ </ComboboxContent>
283
+ </Combobox>
284
+ ```
285
+
286
+ ### Tables
287
+
288
+ For simple tables, use `Table`. For complex data tables with sorting/filtering/pagination, use the `DataTable` block:
289
+
290
+ ```tsx
291
+ {/* Simple table */}
292
+ <Table dataHook="users-table">
293
+ <TableHeader>
294
+ <TableRow>
295
+ <TableHead>Name</TableHead>
296
+ <TableHead>Email</TableHead>
297
+ </TableRow>
298
+ </TableHeader>
299
+ <TableBody>
300
+ <TableRow>
301
+ <TableCell>Alice</TableCell>
302
+ <TableCell>alice@example.com</TableCell>
303
+ </TableRow>
304
+ </TableBody>
305
+ </Table>
306
+ ```
307
+
308
+ ### Notifications (Sonner)
309
+
310
+ Mount `<Sonner />` once at the app root, then call `sonner()` anywhere to show toasts:
311
+
312
+ ```tsx
313
+ import { sonner, Sonner } from "@brightlocal/ui-components/sonner";
314
+
315
+ // Mount once in your app root (e.g., App.tsx or layout.tsx)
316
+ <Sonner />
317
+
318
+ // Trigger toasts anywhere
319
+ sonner({ title: "Changes saved", icon: "success" });
320
+ sonner({ title: "Error occurred", description: "Please try again.", icon: "error" });
321
+
322
+ // Custom duration (default is 4000ms)
323
+ sonner({ title: "Heads up!", icon: "info" }, { duration: 10000 });
324
+
325
+ // Persistent toast — stays visible until dismissed
326
+ sonner(
327
+ { title: "Redirecting…", icon: "loading" },
328
+ { duration: Infinity, id: "redirect-toast" },
329
+ );
330
+
331
+ // Dismiss programmatically
332
+ sonner.dismiss("redirect-toast");
333
+ ```
334
+
335
+ - **Icons:** `"info"` | `"success"` | `"warning"` | `"error"` | `"loading"` | `null`
336
+ - **Color schemas:** `"default"` | `"success"`
337
+ - **Duration:** `number` in ms (default 4000). Use `Infinity` to keep the toast visible until the user closes it or you call `sonner.dismiss(id)`
338
+ - **`dataHook` is not required** — Sonner is a global provider, not a per-instance component
339
+
340
+ ---
341
+
342
+ ## Do's and Don'ts
343
+
344
+ ### Do
345
+
346
+ - Use `Field` + `FieldLabel` for all form inputs
347
+ - Use `asChild` on triggers to render your own button: `<DialogTrigger asChild><Button>...</Button></DialogTrigger>`
348
+ - Use `cn()` from `@brightlocal/ui-components/lib/utils` to merge classNames
349
+ - Use `variant` and `size` props instead of custom className overrides
350
+ - Provide `aria-label` on icon-only buttons (`iconOnly` prop)
351
+ - Use `Typography` components (`H1`–`H4`, `P`, `Small`, `Muted`, `Lead`) for text
352
+ - Use `Separator` between content sections, not `<hr>` or border utilities
353
+
354
+ ### Don't
355
+
356
+ - Don't use raw HTML elements when a DS component exists (`<button>`, `<input>`, `<select>`, `<table>`, `<hr>`)
357
+ - Don't use raw hex/rgb colors (`#000000`, `rgb(0,0,0)`, `bg-[#1e40af]`) — use semantic tokens first (`text-primary`, `bg-muted`), or Tailwind utilities (`text-blue-600`) when no token fits
358
+ - Don't use `transition-all` — always specify the property (`transition-colors`, `transition-opacity`)
359
+ - Don't use bare `focus:` — always use `focus-visible:`
360
+ - Don't import from the barrel `"@brightlocal/ui-components"` — use per-file imports
361
+ - Don't create wrapper `<div>`s for layout when `Card`, `Field`, or layout components exist
362
+ - Don't skip `dataHook` on interactive components — check `component-meta.json` if unsure whether it's required
363
+ - Don't use `size` prop on icons unless overriding the 16px default
364
+
365
+ ---
366
+
367
+ ## Accessibility Checklist
368
+
369
+ When composing UI with these components:
370
+
371
+ 1. Every form input has a visible `<FieldLabel>` or `aria-label`
372
+ 2. Error states use `aria-invalid` (handled by the `error` prop on most inputs)
373
+ 3. Dialogs have `DialogTitle` and `DialogDescription`
374
+ 4. Icon-only buttons have `aria-label` or `ariaLabel` prop
375
+ 5. Images and avatars have `alt` text
376
+ 6. Interactive elements are keyboard-navigable (built-in for all DS components)
377
+ 7. Color is not the only indicator of state (icons, text, borders supplement color)
378
+
379
+ ---
380
+
381
+ ## Component Reference
382
+
383
+ For a machine-readable registry of all components with their categories, props, variants, and relationships, see [`component-meta.json`](./component-meta.json).
384
+
385
+ For TypeScript prop definitions, use the types exported alongside each component:
386
+
387
+ ```tsx
388
+ import type { ButtonProps } from "@brightlocal/ui-components/button";
389
+ import type { InputProps } from "@brightlocal/ui-components/input";
390
+ ```
package/README.md CHANGED
@@ -5,20 +5,26 @@ BrightLocal Design System UI Components package containing low-level React compo
5
5
  ## Installation
6
6
 
7
7
  ```bash
8
- npm install @brightlocal/ui-components
8
+ pnpm add @brightlocal/ui-components
9
9
  ```
10
10
 
11
11
  ## Peer Dependencies
12
12
 
13
- This package requires React 18 or 19:
13
+ This package requires React 18 or 19 and Tailwind CSS v4:
14
14
 
15
15
  ```bash
16
- npm install react react-dom
16
+ pnpm add react react-dom tailwindcss @tailwindcss/vite
17
+ ```
18
+
19
+ You also need the BrightLocal design tokens for theming:
20
+
21
+ ```bash
22
+ pnpm add @brightlocal/tokens
17
23
  ```
18
24
 
19
25
  ## Components
20
26
 
21
- This package includes 57 components built on Radix UI primitives and other React libraries. All components are fully typed with TypeScript and follow BrightLocal's design system patterns.
27
+ This package includes 61 components built on Radix UI primitives and other React libraries. All components are fully typed with TypeScript and follow BrightLocal's design system patterns.
22
28
 
23
29
  ### Layout Components
24
30
 
@@ -316,17 +322,46 @@ When using these components:
316
322
 
317
323
  ## Available Exports
318
324
 
319
- - `@brightlocal/ui-components/collapsible` - Collapsible components
320
- - `@brightlocal/ui-components/scroll-area` - ScrollArea components
321
- - `@brightlocal/ui-components/hooks/use-mobile` - Mobile detection hook
322
- - `@brightlocal/ui-components/lib/utils` - Utility functions
325
+ Components are exported per-file (not barrel imports). Use the component name in kebab-case:
326
+
327
+ ```tsx
328
+ import { Button } from "@brightlocal/ui-components/button";
329
+ import { Dialog, DialogContent, DialogTrigger } from "@brightlocal/ui-components/dialog";
330
+ import { DataTable } from "@brightlocal/ui-components/blocks/data-table";
331
+ import { useIsMobile } from "@brightlocal/ui-components/hooks/use-mobile";
332
+ import { cn } from "@brightlocal/ui-components/lib/utils";
333
+ ```
334
+
335
+ | Path pattern | Example |
336
+ |---|---|
337
+ | `@brightlocal/ui-components/{component}` | `/button`, `/input`, `/dialog`, `/select` |
338
+ | `@brightlocal/ui-components/blocks/{block}` | `/blocks/data-table`, `/blocks/sidebar` |
339
+ | `@brightlocal/ui-components/hooks/{hook}` | `/hooks/use-mobile` |
340
+ | `@brightlocal/ui-components/lib/{util}` | `/lib/utils` |
323
341
 
324
342
  ## Dependencies
325
343
 
326
344
  This package builds on:
327
345
 
328
- - **@radix-ui/react-collapsible** - Collapsible primitive
329
- - **@radix-ui/react-scroll-area** - ScrollArea primitive
346
+ - **Radix UI** - Accessible primitives (Dialog, Select, Tabs, Tooltip, etc.)
347
+ - **Class Variance Authority** - Component variant management
348
+ - **Tailwind Merge** - Intelligent class merging via `cn()` utility
349
+ - **Framer Motion** - Animation and transitions
350
+ - **TanStack Table** - Headless table utilities (DataTable block)
351
+ - **Recharts** - Chart visualizations (Chart component)
352
+ - **react-day-picker** - Calendar and date picking
353
+ - **Embla Carousel** - Carousel functionality
354
+ - **Sonner** - Toast notifications
355
+ - **Vaul** - Drawer component
356
+
357
+ ## AI Integration
358
+
359
+ This package ships with AI-friendly documentation:
360
+
361
+ - **[AI_USAGE.md](./AI_USAGE.md)** — Rules, patterns, do's/don'ts, and composition examples for AI code generation
362
+ - **[component-meta.json](./component-meta.json)** — Machine-readable registry of all components with categories, variants, props, and relationships
363
+
364
+ These files help AI assistants generate code that follows BrightLocal Design System conventions out of the box.
330
365
 
331
366
  ## Development
332
367