@hex-core/components 1.3.1 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (222) hide show
  1. package/README.md +183 -9
  2. package/dist/_tsup-dts-rollup.d.ts +3105 -0
  3. package/dist/accordion.d.ts +4 -0
  4. package/dist/accordion.js +62 -0
  5. package/dist/accordion.js.map +1 -0
  6. package/dist/alert-dialog.d.ts +11 -0
  7. package/dist/alert-dialog.js +125 -0
  8. package/dist/alert-dialog.js.map +1 -0
  9. package/dist/alert.d.ts +4 -0
  10. package/dist/alert.js +54 -0
  11. package/dist/alert.js.map +1 -0
  12. package/dist/aspect-ratio.d.ts +1 -0
  13. package/dist/aspect-ratio.js +8 -0
  14. package/dist/aspect-ratio.js.map +1 -0
  15. package/dist/avatar.d.ts +3 -0
  16. package/dist/avatar.js +44 -0
  17. package/dist/avatar.js.map +1 -0
  18. package/dist/badge.d.ts +3 -0
  19. package/dist/badge.js +36 -0
  20. package/dist/badge.js.map +1 -0
  21. package/dist/breadcrumb.d.ts +7 -0
  22. package/dist/breadcrumb.js +120 -0
  23. package/dist/breadcrumb.js.map +1 -0
  24. package/dist/button.d.ts +3 -0
  25. package/dist/button.js +113 -0
  26. package/dist/button.js.map +1 -0
  27. package/dist/calendar.d.ts +1 -0
  28. package/dist/calendar.js +126 -0
  29. package/dist/calendar.js.map +1 -0
  30. package/dist/card.d.ts +6 -0
  31. package/dist/card.js +68 -0
  32. package/dist/card.js.map +1 -0
  33. package/dist/checkbox.d.ts +2 -0
  34. package/dist/checkbox.js +65 -0
  35. package/dist/checkbox.js.map +1 -0
  36. package/dist/citation.d.ts +2 -0
  37. package/dist/citation.js +70 -0
  38. package/dist/citation.js.map +1 -0
  39. package/dist/cluster.d.ts +3 -0
  40. package/dist/cluster.js +50 -0
  41. package/dist/cluster.js.map +1 -0
  42. package/dist/code-block-copy.d.ts +2 -0
  43. package/dist/code-block-copy.js +108 -0
  44. package/dist/code-block-copy.js.map +1 -0
  45. package/dist/code-block.d.ts +3 -0
  46. package/dist/code-block.js +90 -0
  47. package/dist/code-block.js.map +1 -0
  48. package/dist/collapsible.d.ts +3 -0
  49. package/dist/collapsible.js +10 -0
  50. package/dist/collapsible.js.map +1 -0
  51. package/dist/color-picker.d.ts +2 -0
  52. package/dist/color-picker.js +321 -0
  53. package/dist/color-picker.js.map +1 -0
  54. package/dist/combobox.d.ts +3 -0
  55. package/dist/combobox.js +226 -0
  56. package/dist/combobox.js.map +1 -0
  57. package/dist/command.d.ts +9 -0
  58. package/dist/command.js +232 -0
  59. package/dist/command.js.map +1 -0
  60. package/dist/composer.d.ts +2 -0
  61. package/dist/composer.js +75 -0
  62. package/dist/composer.js.map +1 -0
  63. package/dist/container.d.ts +3 -0
  64. package/dist/container.js +39 -0
  65. package/dist/container.js.map +1 -0
  66. package/dist/context-menu.d.ts +12 -0
  67. package/dist/context-menu.js +130 -0
  68. package/dist/context-menu.js.map +1 -0
  69. package/dist/data-table.d.ts +2 -0
  70. package/dist/data-table.js +103 -0
  71. package/dist/data-table.js.map +1 -0
  72. package/dist/date-picker.d.ts +2 -0
  73. package/dist/date-picker.js +221 -0
  74. package/dist/date-picker.js.map +1 -0
  75. package/dist/dialog.d.ts +11 -0
  76. package/dist/dialog.js +125 -0
  77. package/dist/dialog.js.map +1 -0
  78. package/dist/drawer.d.ts +10 -0
  79. package/dist/drawer.js +82 -0
  80. package/dist/drawer.js.map +1 -0
  81. package/dist/dropdown-menu.d.ts +13 -0
  82. package/dist/dropdown-menu.js +133 -0
  83. package/dist/dropdown-menu.js.map +1 -0
  84. package/dist/dropzone.d.ts +3 -0
  85. package/dist/dropzone.js +194 -0
  86. package/dist/dropzone.js.map +1 -0
  87. package/dist/file-tree.d.ts +3 -0
  88. package/dist/file-tree.js +322 -0
  89. package/dist/file-tree.js.map +1 -0
  90. package/dist/form.d.ts +8 -0
  91. package/dist/form.js +114 -0
  92. package/dist/form.js.map +1 -0
  93. package/dist/grid.d.ts +3 -0
  94. package/dist/grid.js +58 -0
  95. package/dist/grid.js.map +1 -0
  96. package/dist/hover-card.d.ts +3 -0
  97. package/dist/hover-card.js +34 -0
  98. package/dist/hover-card.js.map +1 -0
  99. package/dist/index.d.ts +298 -1652
  100. package/dist/index.js +1157 -5493
  101. package/dist/index.js.map +1 -1
  102. package/dist/input-otp.d.ts +5 -0
  103. package/dist/input-otp.js +71 -0
  104. package/dist/input-otp.js.map +1 -0
  105. package/dist/input.d.ts +2 -0
  106. package/dist/input.js +40 -0
  107. package/dist/input.js.map +1 -0
  108. package/dist/label.d.ts +2 -0
  109. package/dist/label.js +22 -0
  110. package/dist/label.js.map +1 -0
  111. package/dist/loading-indicator.d.ts +3 -0
  112. package/dist/loading-indicator.js +64 -0
  113. package/dist/loading-indicator.js.map +1 -0
  114. package/dist/markdown.d.ts +2 -0
  115. package/dist/markdown.js +28 -0
  116. package/dist/markdown.js.map +1 -0
  117. package/dist/menubar.d.ts +11 -0
  118. package/dist/menubar.js +106 -0
  119. package/dist/menubar.js.map +1 -0
  120. package/dist/message-actions.d.ts +2 -0
  121. package/dist/message-actions.js +28 -0
  122. package/dist/message-actions.js.map +1 -0
  123. package/dist/message-list.d.ts +2 -0
  124. package/dist/message-list.js +49 -0
  125. package/dist/message-list.js.map +1 -0
  126. package/dist/message.d.ts +3 -0
  127. package/dist/message.js +35 -0
  128. package/dist/message.js.map +1 -0
  129. package/dist/multi-combobox.d.ts +3 -0
  130. package/dist/multi-combobox.js +258 -0
  131. package/dist/multi-combobox.js.map +1 -0
  132. package/dist/navigation-menu.d.ts +9 -0
  133. package/dist/navigation-menu.js +108 -0
  134. package/dist/navigation-menu.js.map +1 -0
  135. package/dist/pagination.d.ts +7 -0
  136. package/dist/pagination.js +195 -0
  137. package/dist/pagination.js.map +1 -0
  138. package/dist/popover.d.ts +4 -0
  139. package/dist/popover.js +35 -0
  140. package/dist/popover.js.map +1 -0
  141. package/dist/progress.d.ts +1 -0
  142. package/dist/progress.js +38 -0
  143. package/dist/progress.js.map +1 -0
  144. package/dist/radio-group.d.ts +2 -0
  145. package/dist/radio-group.js +44 -0
  146. package/dist/radio-group.js.map +1 -0
  147. package/dist/reasoning.d.ts +2 -0
  148. package/dist/reasoning.js +90 -0
  149. package/dist/reasoning.js.map +1 -0
  150. package/dist/resizable.d.ts +3 -0
  151. package/dist/resizable.js +66 -0
  152. package/dist/resizable.js.map +1 -0
  153. package/dist/schemas.d.ts +72 -0
  154. package/dist/schemas.js +5491 -0
  155. package/dist/schemas.js.map +1 -0
  156. package/dist/scroll-area.d.ts +3 -0
  157. package/dist/scroll-area.js +55 -0
  158. package/dist/scroll-area.js.map +1 -0
  159. package/dist/select.d.ts +8 -0
  160. package/dist/select.js +136 -0
  161. package/dist/select.js.map +1 -0
  162. package/dist/separator.d.ts +2 -0
  163. package/dist/separator.js +29 -0
  164. package/dist/separator.js.map +1 -0
  165. package/dist/sheet.d.ts +10 -0
  166. package/dist/sheet.js +140 -0
  167. package/dist/sheet.js.map +1 -0
  168. package/dist/sidebar.d.ts +8 -0
  169. package/dist/sidebar.js +201 -0
  170. package/dist/sidebar.js.map +1 -0
  171. package/dist/skeleton.d.ts +1 -0
  172. package/dist/skeleton.js +21 -0
  173. package/dist/skeleton.js.map +1 -0
  174. package/dist/slider.d.ts +2 -0
  175. package/dist/slider.js +55 -0
  176. package/dist/slider.js.map +1 -0
  177. package/dist/sonner.d.ts +2 -0
  178. package/dist/sonner.js +27 -0
  179. package/dist/sonner.js.map +1 -0
  180. package/dist/spacer.d.ts +3 -0
  181. package/dist/spacer.js +43 -0
  182. package/dist/spacer.js.map +1 -0
  183. package/dist/stack.d.ts +3 -0
  184. package/dist/stack.js +49 -0
  185. package/dist/stack.js.map +1 -0
  186. package/dist/stepper.d.ts +4 -0
  187. package/dist/stepper.js +226 -0
  188. package/dist/stepper.js.map +1 -0
  189. package/dist/suggestion.d.ts +2 -0
  190. package/dist/suggestion.js +55 -0
  191. package/dist/suggestion.js.map +1 -0
  192. package/dist/switch.d.ts +2 -0
  193. package/dist/switch.js +47 -0
  194. package/dist/switch.js.map +1 -0
  195. package/dist/table.d.ts +8 -0
  196. package/dist/table.js +85 -0
  197. package/dist/table.js.map +1 -0
  198. package/dist/tabs.d.ts +4 -0
  199. package/dist/tabs.js +57 -0
  200. package/dist/tabs.js.map +1 -0
  201. package/dist/textarea.d.ts +2 -0
  202. package/dist/textarea.js +36 -0
  203. package/dist/textarea.js.map +1 -0
  204. package/dist/time-picker.d.ts +2 -0
  205. package/dist/time-picker.js +50 -0
  206. package/dist/time-picker.js.map +1 -0
  207. package/dist/timeline.d.ts +4 -0
  208. package/dist/timeline.js +84 -0
  209. package/dist/timeline.js.map +1 -0
  210. package/dist/toggle-group.d.ts +2 -0
  211. package/dist/toggle-group.js +83 -0
  212. package/dist/toggle-group.js.map +1 -0
  213. package/dist/toggle.d.ts +2 -0
  214. package/dist/toggle.js +49 -0
  215. package/dist/toggle.js.map +1 -0
  216. package/dist/tool-call.d.ts +2 -0
  217. package/dist/tool-call.js +133 -0
  218. package/dist/tool-call.js.map +1 -0
  219. package/dist/tooltip.d.ts +4 -0
  220. package/dist/tooltip.js +33 -0
  221. package/dist/tooltip.js.map +1 -0
  222. package/package.json +71 -16
package/README.md CHANGED
@@ -29,14 +29,30 @@ pnpm add @hex-core/components
29
29
 
30
30
  Without it, classes like `inset-ring-foreground/[0.06]` (used by Button outline, Input, Card, etc.) appear in the rendered HTML but have no CSS rule, and components render unstyled. Tailwind v4 doesn't auto-scan `node_modules`.
31
31
 
32
+ ## Imports — barrel vs deep (RSC)
33
+
32
34
  ```tsx
33
- import { Button } from "@hex-core/components";
35
+ // Deep import — RSC-safe for visual primitives, tree-shake friendly
36
+ import { Badge } from "@hex-core/components/badge";
37
+ import { Card, CardContent } from "@hex-core/components/card";
38
+ import { Stack } from "@hex-core/components/stack";
34
39
 
35
- export default function Page() {
36
- return <Button>Click me</Button>;
37
- }
40
+ // Barrel import — convenience, but always client-side
41
+ import { Button, Card, Stack } from "@hex-core/components";
38
42
  ```
39
43
 
44
+ Each component file declares its own `"use client"` directive — and only when it needs one. Deep imports of visual primitives (`Badge`, `Card`, `Stack`, …) render directly inside Next.js Server Components without forcing the subtree client-side. Deep imports of stateful components (`Dialog`, `Form`, `Calendar`, …) carry the directive automatically.
45
+
46
+ The barrel re-exports everything together, so it's marked client. Existing barrel imports keep working — but if you want RSC + tree-shake, prefer deep imports.
47
+
48
+ ### RSC-safe components (no `"use client"` needed)
49
+
50
+ `Alert`, `Badge`, `Card`, `Cluster`, `Grid`, `Input`, `Pagination`, `Skeleton`, `Spacer`, `Stack`, `Table`, `Textarea`, `Timeline`.
51
+
52
+ ### Client-only components
53
+
54
+ Everything else — anything backed by Radix portals/triggers, hooks, `react-hook-form`, `cmdk`, `vaul`, `sonner`, `react-day-picker`, `input-otp`, or `react-resizable-panels`. Each of those modules ships with its own `"use client"` so importing it from a Server Component still works (Next.js sees the directive at the import boundary).
55
+
40
56
  ## What's inside
41
57
 
42
58
  47 components across primitives (Button, Input, Checkbox, …) and compounds (Combobox, DataTable, Command, …). Every component ships with:
@@ -47,12 +63,170 @@ export default function Page() {
47
63
  - HSL design tokens — override via CSS vars, no JS config needed
48
64
  - A matching `.schema.ts` with AI hints (`whenToUse`, `whenNotToUse`, `commonMistakes`, `accessibilityNotes`, `tokenBudget`)
49
65
 
50
- ## Peer dependencies
66
+ ## Color utilities
67
+
68
+ Tailwind v4 generates utilities from `@theme {}` automatically. The bundled `tailwind.css` exposes the full semantic palette — use the short class names directly, no `text-[color:var(...)]` workaround required.
69
+
70
+ | Class | Token |
71
+ | --- | --- |
72
+ | `bg-background` / `text-background` | `--color-background` |
73
+ | `bg-foreground` / `text-foreground` | `--color-foreground` |
74
+ | `bg-card` / `text-card-foreground` | `--color-card` / `--color-card-foreground` |
75
+ | `bg-popover` / `text-popover-foreground` | `--color-popover` |
76
+ | `bg-primary` / `text-primary` / `text-primary-foreground` | `--color-primary` |
77
+ | `bg-secondary` / `text-secondary-foreground` | `--color-secondary` |
78
+ | `bg-muted` / `text-muted-foreground` | `--color-muted` |
79
+ | `bg-accent` / `text-accent-foreground` | `--color-accent` |
80
+ | `bg-destructive` / `text-destructive-foreground` | `--color-destructive` |
81
+ | `border-input` / `border-border` / `border-ring` | `--color-input` / `--color-border` / `--color-ring` |
82
+
83
+ Both forms produce identical output:
84
+
85
+ ```tsx
86
+ // Preferred — short and stable
87
+ <p className="text-muted-foreground">Helper</p>
88
+
89
+ // Equivalent — only use this if a class name is dynamically composed
90
+ <p className="text-[color:var(--color-muted-foreground)]">Helper</p>
91
+ ```
92
+
93
+ ## Setup: Toaster
94
+
95
+ ```tsx
96
+ // app/layout.tsx (Server Component is fine — Toaster declares its own "use client")
97
+ import { Toaster } from "@hex-core/components/sonner";
98
+
99
+ export default function RootLayout({ children }: { children: React.ReactNode }) {
100
+ return (
101
+ <html lang="en">
102
+ <body>
103
+ {children}
104
+ <Toaster />
105
+ </body>
106
+ </html>
107
+ );
108
+ }
109
+ ```
110
+
111
+ ```tsx
112
+ // any client component
113
+ "use client";
114
+ import { toast } from "sonner";
115
+
116
+ export function SaveButton() {
117
+ return <button onClick={() => toast.success("Saved!")}>Save</button>;
118
+ }
119
+ ```
120
+
121
+ `sonner` is an optional peer — install it if you use the toaster: `pnpm add sonner`.
122
+
123
+ ## Setup: Form (`react-hook-form` integration)
124
+
125
+ ```tsx
126
+ "use client";
127
+ import { useForm } from "react-hook-form";
128
+ import {
129
+ Form,
130
+ FormField,
131
+ FormItem,
132
+ FormLabel,
133
+ FormControl,
134
+ FormMessage,
135
+ } from "@hex-core/components/form";
136
+ import { Input } from "@hex-core/components/input";
137
+ import { Button } from "@hex-core/components/button";
138
+
139
+ export function ContactForm() {
140
+ const form = useForm<{ email: string }>({ defaultValues: { email: "" } });
141
+ return (
142
+ <Form {...form}>
143
+ <form onSubmit={form.handleSubmit((v) => console.log(v))} className="space-y-4">
144
+ <FormField
145
+ control={form.control}
146
+ name="email"
147
+ render={({ field }) => (
148
+ <FormItem>
149
+ <FormLabel>Email</FormLabel>
150
+ <FormControl>
151
+ <Input type="email" {...field} />
152
+ </FormControl>
153
+ <FormMessage />
154
+ </FormItem>
155
+ )}
156
+ />
157
+ <Button type="submit">Submit</Button>
158
+ </form>
159
+ </Form>
160
+ );
161
+ }
162
+ ```
163
+
164
+ `react-hook-form` is an optional peer — install it if you use `<Form>`: `pnpm add react-hook-form`.
165
+
166
+ ## Layout primitives
167
+
168
+ Don't reach for `<div className="flex …">` — the layout primitives are typed and document their own intent.
169
+
170
+ | Instead of | Use |
171
+ | --- | --- |
172
+ | `<div className="flex flex-col gap-4">` | `<Stack gap="4">` |
173
+ | `<div className="flex items-center gap-2">` | `<Cluster gap="2">` |
174
+ | `<div className="grid grid-cols-3 gap-4">` | `<Grid cols={3} gap="4">` |
175
+ | `<div className="max-w-7xl mx-auto px-6">` | `<Container size="xl">` |
176
+ | `<div className="h-8" />` | `<Spacer size="8">` |
177
+ | `<div className="aspect-video">` | `<AspectRatio ratio={16 / 9}>` |
178
+
179
+ All layout primitives are RSC-safe — pure visual, zero hooks.
180
+
181
+ ## Card composition
182
+
183
+ ```tsx
184
+ import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from "@hex-core/components/card";
185
+
186
+ <Card>
187
+ <CardHeader>
188
+ <CardTitle>Quarterly review</CardTitle>
189
+ <CardDescription>Q3 2025 — North America</CardDescription>
190
+ </CardHeader>
191
+ <CardContent>{/* body */}</CardContent>
192
+ <CardFooter>{/* actions */}</CardFooter>
193
+ </Card>
194
+ ```
195
+
196
+ `Card` and family are RSC-safe.
197
+
198
+ ## Schemas (tooling)
199
+
200
+ If you're building tooling that consumes the component manifest (an MCP server, a docs prop-table renderer, an AI assistant), import schemas from the dedicated subpath:
201
+
202
+ ```ts
203
+ import { buttonSchema, cardSchema } from "@hex-core/components/schemas";
204
+ ```
205
+
206
+ The schemas reference `ComponentSchemaDefinition` from `@hex-core/registry`, so install that as a dev dep alongside:
207
+
208
+ ```bash
209
+ pnpm add -D @hex-core/registry
210
+ ```
211
+
212
+ This entry is intentionally separate from the runtime barrel — `import { Button } from "@hex-core/components"` does NOT pull in registry types.
213
+
214
+ ## Peer dependency matrix
215
+
216
+ `@hex-core/components` keeps its install footprint small by listing optional dependencies as peers. Install only the ones backing the components you actually use.
217
+
218
+ | Component | Optional peer to install |
219
+ | --- | --- |
220
+ | `<Calendar>`, `<DatePicker>` | `react-day-picker`, `date-fns` |
221
+ | `<Toaster>`, `toast()` | `sonner` |
222
+ | `<Combobox>`, `<MultiCombobox>`, `<Command>` | `cmdk` |
223
+ | `<Drawer>` | `vaul` |
224
+ | `<InputOTP>` | `input-otp` |
225
+ | `<ResizableHandle>`, `<ResizablePanel>`, `<ResizablePanelGroup>` | `react-resizable-panels` |
226
+ | `<Form>`, `<FormField>`, `<FormItem>` | `react-hook-form` |
227
+ | `<DataTable>` | `@tanstack/react-table` |
51
228
 
52
- - `react` 18 or 19
53
- - `react-dom` 18 or 19
54
- - `react-hook-form` (only needed by `<Form>` — tree-shaken if unused)
55
- - `@tanstack/react-table` (only needed by `<DataTable>`)
229
+ Hard peers: `react` 18+/19, `react-dom` 18+/19.
56
230
 
57
231
  ## Docs
58
232