@leitware/composables 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (209) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +387 -0
  3. package/dist/presets/brutalist.css +298 -0
  4. package/dist/presets/default.css +298 -0
  5. package/dist/presets/signal-pop.css +369 -0
  6. package/dist/styles.css +2 -0
  7. package/package.json +216 -0
  8. package/rules/composables.md +244 -0
  9. package/src/_internal/accordion.tsx +93 -0
  10. package/src/_internal/ai-elements/attachments.tsx +385 -0
  11. package/src/_internal/ai-elements/chain-of-thought.tsx +197 -0
  12. package/src/_internal/ai-elements/code-block.tsx +516 -0
  13. package/src/_internal/ai-elements/confirmation.tsx +150 -0
  14. package/src/_internal/ai-elements/conversation.tsx +148 -0
  15. package/src/_internal/ai-elements/inline-citation.tsx +248 -0
  16. package/src/_internal/ai-elements/message.tsx +292 -0
  17. package/src/_internal/ai-elements/plan.tsx +126 -0
  18. package/src/_internal/ai-elements/prompt-input.tsx +1285 -0
  19. package/src/_internal/ai-elements/reasoning.tsx +208 -0
  20. package/src/_internal/ai-elements/shimmer.tsx +72 -0
  21. package/src/_internal/ai-elements/sources.tsx +53 -0
  22. package/src/_internal/ai-elements/suggestion.tsx +48 -0
  23. package/src/_internal/ai-elements/task.tsx +64 -0
  24. package/src/_internal/ai-elements/tool.tsx +156 -0
  25. package/src/_internal/alert-dialog.tsx +159 -0
  26. package/src/_internal/alert.tsx +88 -0
  27. package/src/_internal/aspect-ratio.tsx +23 -0
  28. package/src/_internal/avatar.tsx +58 -0
  29. package/src/_internal/badge.tsx +60 -0
  30. package/src/_internal/breadcrumb.tsx +104 -0
  31. package/src/_internal/bubble.tsx +125 -0
  32. package/src/_internal/button-group.tsx +78 -0
  33. package/src/_internal/button.tsx +62 -0
  34. package/src/_internal/calendar.tsx +179 -0
  35. package/src/_internal/card.tsx +83 -0
  36. package/src/_internal/carousel.tsx +215 -0
  37. package/src/_internal/checkbox.tsx +26 -0
  38. package/src/_internal/code-block.tsx +53 -0
  39. package/src/_internal/collapsible.tsx +15 -0
  40. package/src/_internal/combobox.tsx +264 -0
  41. package/src/_internal/command.tsx +155 -0
  42. package/src/_internal/container.tsx +35 -0
  43. package/src/_internal/dialog.tsx +132 -0
  44. package/src/_internal/direction.tsx +12 -0
  45. package/src/_internal/divider.tsx +162 -0
  46. package/src/_internal/dropdown-menu.tsx +247 -0
  47. package/src/_internal/dropzone.tsx +481 -0
  48. package/src/_internal/empty.tsx +94 -0
  49. package/src/_internal/field.tsx +221 -0
  50. package/src/_internal/grid-overlay.tsx +48 -0
  51. package/src/_internal/grid.tsx +109 -0
  52. package/src/_internal/hover-card.tsx +47 -0
  53. package/src/_internal/icon.tsx +45 -0
  54. package/src/_internal/input-group.tsx +146 -0
  55. package/src/_internal/input.tsx +24 -0
  56. package/src/_internal/item.tsx +187 -0
  57. package/src/_internal/kbd.tsx +28 -0
  58. package/src/_internal/label.tsx +18 -0
  59. package/src/_internal/layout-bento.tsx +386 -0
  60. package/src/_internal/layout.tsx +174 -0
  61. package/src/_internal/marker.tsx +66 -0
  62. package/src/_internal/message.tsx +85 -0
  63. package/src/_internal/native-select.tsx +50 -0
  64. package/src/_internal/pagination.tsx +108 -0
  65. package/src/_internal/popover.tsx +83 -0
  66. package/src/_internal/progress.tsx +59 -0
  67. package/src/_internal/radio-group.tsx +36 -0
  68. package/src/_internal/resizable.tsx +44 -0
  69. package/src/_internal/scroll-area.tsx +48 -0
  70. package/src/_internal/select.tsx +187 -0
  71. package/src/_internal/separator.tsx +19 -0
  72. package/src/_internal/sheet.tsx +122 -0
  73. package/src/_internal/sidebar.tsx +687 -0
  74. package/src/_internal/skeleton.tsx +13 -0
  75. package/src/_internal/slider.tsx +60 -0
  76. package/src/_internal/sonner.tsx +51 -0
  77. package/src/_internal/spacer.tsx +42 -0
  78. package/src/_internal/spinner.tsx +16 -0
  79. package/src/_internal/stack.tsx +78 -0
  80. package/src/_internal/switch.tsx +31 -0
  81. package/src/_internal/table.tsx +84 -0
  82. package/src/_internal/tabs.tsx +74 -0
  83. package/src/_internal/textarea.tsx +19 -0
  84. package/src/_internal/toggle-group.tsx +99 -0
  85. package/src/_internal/toggle.tsx +42 -0
  86. package/src/_internal/tooltip.tsx +55 -0
  87. package/src/_internal/typography.tsx +129 -0
  88. package/src/hooks/use-mobile.ts +19 -0
  89. package/src/hooks/use-numeric-input.ts +119 -0
  90. package/src/index.ts +443 -0
  91. package/src/lib/numeric-input.ts +88 -0
  92. package/src/lib/utils.ts +39 -0
  93. package/src/opinionated/accordion.tsx +92 -0
  94. package/src/opinionated/ai/attachments.tsx +27 -0
  95. package/src/opinionated/ai/chain-of-thought.tsx +16 -0
  96. package/src/opinionated/ai/code-block.tsx +22 -0
  97. package/src/opinionated/ai/confirmation.tsx +16 -0
  98. package/src/opinionated/ai/conversation.tsx +13 -0
  99. package/src/opinionated/ai/index.ts +15 -0
  100. package/src/opinionated/ai/inline-citation.tsx +30 -0
  101. package/src/opinionated/ai/message.tsx +26 -0
  102. package/src/opinionated/ai/plan.tsx +18 -0
  103. package/src/opinionated/ai/prompt-input.tsx +29 -0
  104. package/src/opinionated/ai/reasoning.tsx +9 -0
  105. package/src/opinionated/ai/shimmer.tsx +4 -0
  106. package/src/opinionated/ai/sources.tsx +10 -0
  107. package/src/opinionated/ai/suggestion.tsx +6 -0
  108. package/src/opinionated/ai/task.tsx +12 -0
  109. package/src/opinionated/ai/tool.tsx +14 -0
  110. package/src/opinionated/alert-dialog.tsx +143 -0
  111. package/src/opinionated/alert.tsx +99 -0
  112. package/src/opinionated/aspect-ratio.tsx +12 -0
  113. package/src/opinionated/avatar.tsx +59 -0
  114. package/src/opinionated/badge.tsx +33 -0
  115. package/src/opinionated/breadcrumb.tsx +99 -0
  116. package/src/opinionated/bubble.tsx +9 -0
  117. package/src/opinionated/button.tsx +59 -0
  118. package/src/opinionated/calendar.tsx +20 -0
  119. package/src/opinionated/card.tsx +83 -0
  120. package/src/opinionated/carousel.tsx +99 -0
  121. package/src/opinionated/checkbox.tsx +11 -0
  122. package/src/opinionated/code-block.tsx +12 -0
  123. package/src/opinionated/collapsible.tsx +123 -0
  124. package/src/opinionated/combobox.tsx +123 -0
  125. package/src/opinionated/container.tsx +12 -0
  126. package/src/opinionated/dialog.tsx +124 -0
  127. package/src/opinionated/direction.tsx +6 -0
  128. package/src/opinionated/divider.tsx +13 -0
  129. package/src/opinionated/dropdown-menu.tsx +131 -0
  130. package/src/opinionated/dropzone.tsx +39 -0
  131. package/src/opinionated/empty.tsx +191 -0
  132. package/src/opinionated/field.tsx +26 -0
  133. package/src/opinionated/form-calendar-popover.tsx +138 -0
  134. package/src/opinionated/form-checkbox.tsx +107 -0
  135. package/src/opinionated/form-combobox.tsx +181 -0
  136. package/src/opinionated/form-date-of-birth.tsx +193 -0
  137. package/src/opinionated/form-dropzone.tsx +126 -0
  138. package/src/opinionated/form-input-group.tsx +184 -0
  139. package/src/opinionated/form-input.tsx +118 -0
  140. package/src/opinionated/form-multi-combobox.tsx +213 -0
  141. package/src/opinionated/form-multi-dropzone.tsx +141 -0
  142. package/src/opinionated/form-radiogroup.tsx +116 -0
  143. package/src/opinionated/form-select.tsx +176 -0
  144. package/src/opinionated/form-slider.tsx +100 -0
  145. package/src/opinionated/form-switch.tsx +117 -0
  146. package/src/opinionated/form-textarea.tsx +79 -0
  147. package/src/opinionated/grid-overlay.tsx +11 -0
  148. package/src/opinionated/grid.tsx +14 -0
  149. package/src/opinionated/hover-card.tsx +59 -0
  150. package/src/opinionated/icon.tsx +14 -0
  151. package/src/opinionated/input-group.tsx +20 -0
  152. package/src/opinionated/input.tsx +11 -0
  153. package/src/opinionated/item.tsx +182 -0
  154. package/src/opinionated/kbd.tsx +16 -0
  155. package/src/opinionated/label.tsx +11 -0
  156. package/src/opinionated/layout-bento.tsx +29 -0
  157. package/src/opinionated/layout.tsx +26 -0
  158. package/src/opinionated/list.tsx +94 -0
  159. package/src/opinionated/marker.tsx +7 -0
  160. package/src/opinionated/message.tsx +8 -0
  161. package/src/opinionated/native-select.tsx +51 -0
  162. package/src/opinionated/pagination.tsx +204 -0
  163. package/src/opinionated/popover.tsx +68 -0
  164. package/src/opinionated/progress.tsx +48 -0
  165. package/src/opinionated/radio-group.tsx +13 -0
  166. package/src/opinionated/resizable.tsx +2 -0
  167. package/src/opinionated/scroll-area.tsx +82 -0
  168. package/src/opinionated/select.tsx +101 -0
  169. package/src/opinionated/separator.tsx +11 -0
  170. package/src/opinionated/sheet.tsx +120 -0
  171. package/src/opinionated/sidebar.tsx +68 -0
  172. package/src/opinionated/skeleton.tsx +246 -0
  173. package/src/opinionated/slider.tsx +11 -0
  174. package/src/opinionated/sonner.tsx +15 -0
  175. package/src/opinionated/spacer.tsx +11 -0
  176. package/src/opinionated/stack.tsx +18 -0
  177. package/src/opinionated/switch.tsx +11 -0
  178. package/src/opinionated/table.tsx +11 -0
  179. package/src/opinionated/tabs.tsx +68 -0
  180. package/src/opinionated/textarea.tsx +11 -0
  181. package/src/opinionated/theme-injector.tsx +31 -0
  182. package/src/opinionated/toggle-group.tsx +63 -0
  183. package/src/opinionated/toggle.tsx +75 -0
  184. package/src/opinionated/token-config-panel/color-editor.tsx +85 -0
  185. package/src/opinionated/token-config-panel/helpers.ts +31 -0
  186. package/src/opinionated/token-config-panel/index.tsx +398 -0
  187. package/src/opinionated/token-config-panel/json-import-export.tsx +89 -0
  188. package/src/opinionated/token-config-panel/preset-manager.ts +31 -0
  189. package/src/opinionated/token-config-panel/presets-data.ts +23 -0
  190. package/src/opinionated/token-config-panel/spacing-editor.tsx +325 -0
  191. package/src/opinionated/token-config-panel/types.ts +39 -0
  192. package/src/opinionated/token-config-panel/typography-editor.tsx +145 -0
  193. package/src/opinionated/tooltip.tsx +62 -0
  194. package/src/opinionated/typography.tsx +7 -0
  195. package/src/scripts/lint-no-arbitrary.ts +155 -0
  196. package/src/styles/composable.css +68 -0
  197. package/src/styles/presets/brutalist.css +298 -0
  198. package/src/styles/presets/default.css +298 -0
  199. package/src/styles/presets/signal-pop.css +369 -0
  200. package/src/styles/presets-data/brutalist.ts +325 -0
  201. package/src/styles/presets-data/default.ts +315 -0
  202. package/src/styles/presets-data/index.ts +45 -0
  203. package/src/styles/presets-data/signal-pop.ts +393 -0
  204. package/src/styles/tokens/base.css +71 -0
  205. package/src/styles/tokens/components.css +150 -0
  206. package/src/styles/tokens/palette.css +795 -0
  207. package/src/styles/tokens/registry.ts +324 -0
  208. package/src/styles/tokens/semantic.css +266 -0
  209. package/src/styles/tokens/tailwind-theme.css +247 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Leitware
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,387 @@
1
+ # Composables
2
+
3
+ **An opinionated React component library with a semantic design token system — built on Base UI and Tailwind CSS v4.**
4
+
5
+ [![npm version](https://img.shields.io/npm/v/@leitware/composables)](https://www.npmjs.com/package/@leitware/composables)
6
+ [![CI](https://github.com/rowanhen/composables/actions/workflows/ci.yml/badge.svg)](https://github.com/rowanhen/composables/actions/workflows/ci.yml)
7
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
8
+
9
+ ---
10
+
11
+ ## What is this?
12
+
13
+ Composables is a React component library with ~70 components across forms, layout, data display, feedback, and navigation — all built on [Base UI](https://base-ui.com/) primitives with a CSS custom property token system and 2 built-in design presets.
14
+
15
+ It uses a **two-tier architecture**:
16
+
17
+ - **`opinionated/`** — your API surface. These are the components you import and use day-to-day. They have clean, convenient props and sensible defaults.
18
+ - **`_internal/`** — low-level primitives. These are what the opinionated layer is built on. Lint rules block you from importing from here directly so that internal refactors don't break your app.
19
+
20
+ ---
21
+
22
+ ## Quick Start
23
+
24
+ ```bash
25
+ npm install @leitware/composables
26
+ ```
27
+
28
+ Import the styles in your root CSS file:
29
+
30
+ ```css
31
+ @import '@leitware/composables/styles.css';
32
+
33
+ /* Optional: apply one preset after the base styles */
34
+ @import '@leitware/composables/presets/brutalist.css';
35
+ ```
36
+
37
+ The CSS is pre-compiled — no Tailwind installation or configuration needed downstream.
38
+
39
+ Then import components:
40
+
41
+ ```tsx
42
+ import { Button } from '@leitware/composables'
43
+ import { FormInput } from '@leitware/composables'
44
+ import { Card } from '@leitware/composables'
45
+ ```
46
+
47
+ Optional AI components are exposed from their own entrypoint:
48
+
49
+ ```tsx
50
+ import { AIMessage, AIPromptInput } from '@leitware/composables/ai'
51
+ ```
52
+
53
+ ---
54
+
55
+ ## Optional Dependencies
56
+
57
+ Only the core (layout, forms, typography, feedback) is installed by default. Components that depend on heavier libraries require you to install the relevant package:
58
+
59
+ | Install when using… | Package |
60
+ | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
61
+ | `Calendar`, `FormCalendarPopover` | `react-day-picker` |
62
+ | `Carousel` | `embla-carousel-react` |
63
+ | `Dropzone`, `FormDropzone`, `FormMultiDropzone` | `react-dropzone` |
64
+ | `ResizablePanels` | `react-resizable-panels` |
65
+ | `Sonner` (toasts) | `sonner` |
66
+ | AI elements from `@leitware/composables/ai` | `ai`, `shiki`, `streamdown`, `@streamdown/cjk`, `@streamdown/code`, `@streamdown/math`, `@streamdown/mermaid`, `use-stick-to-bottom`, `nanoid`, `@radix-ui/react-use-controllable-state` |
67
+ | `ThemeInjector` / `TokenConfigPanel` | `react-colorful` |
68
+ | Default preset fonts | `@fontsource-variable/inter` |
69
+ | Brutalist preset fonts | `@fontsource-variable/space-grotesk`, `@fontsource-variable/jetbrains-mono` |
70
+
71
+ If you use a component without its optional dependency installed, you'll get a clear module-not-found error at build time telling you exactly what to add.
72
+
73
+ ---
74
+
75
+ ## Design Tokens
76
+
77
+ The token system is built on CSS custom properties. Everything — colours, spacing, typography, radius, borders, shadows — is expressed as a token that you can override.
78
+
79
+ ### Token Files
80
+
81
+ ```
82
+ styles/
83
+ ├── composable.css ← Main entry point (composes all layers)
84
+ ├── tokens/
85
+ │ ├── palette.css ← Primitive color scales (build-time + runtime)
86
+ │ ├── semantic.css ← Semantic role tokens (:root + .dark)
87
+ │ ├── components.css ← Component-level tunables
88
+ │ ├── tailwind-theme.css ← Tailwind utility registrations (@theme)
89
+ │ └── base.css ← Global base styles
90
+ ├── presets/ ← Generated standalone preset CSS files
91
+ │ ├── default.css
92
+ │ └── brutalist.css
93
+ └── presets-data/ ← Source of truth for preset token values (TS)
94
+ ```
95
+
96
+ Generated CSS ownership:
97
+
98
+ | File | Source of truth | Generated by |
99
+ | --------------------------- | ------------------------------------ | -------------------------------- |
100
+ | `tokens/palette.css` | `scripts/palette.ts` | `bun run generate:palette` |
101
+ | `presets/*.css` | `src/styles/presets-data/index.ts` | `bun run generate:presets` |
102
+ | `rules/composables.md` | `README.md` + package barrel exports | `bun run generate:rules` |
103
+ | `dist/styles.css` | `src/styles/composable.css` + `src` | `bun run build:css` |
104
+ | `dist/presets/*.css` | `src/styles/presets/*.css` | `bun run build:css` |
105
+ | `tokens/semantic.css` | Hand-authored semantic mappings | Checked by `bun run test:tokens` |
106
+ | `tokens/tailwind-theme.css` | Hand-authored Tailwind aliases | Checked by `bun run test:tokens` |
107
+
108
+ ### Customising Tokens
109
+
110
+ Override tokens in your own CSS:
111
+
112
+ ```css
113
+ :root {
114
+ --font-size-base: 15px;
115
+ --radius: 0.75rem;
116
+ --bg-fill-primary: var(--blue-800);
117
+ --font-heading: 'Fraunces Variable', serif;
118
+ }
119
+ ```
120
+
121
+ Key token groups:
122
+
123
+ | Group | Example tokens |
124
+ | -------------- | ------------------------------------------------------------------------------------- |
125
+ | Colour palette | `--neutral-100`, `--blue-800`, `--red-950` |
126
+ | Background | `--bg-default`, `--bg-fill-primary`, `--bg-surface-success` |
127
+ | Text | `--text-default`, `--text-secondary`, `--text-critical` |
128
+ | Border | `--border-default`, `--border-focus`, `--border-brand` |
129
+ | Icon | `--icon-default`, `--icon-success`, `--icon-critical` |
130
+ | Typography | `--font-size-base`, `--leading-base`, `--font-heading` |
131
+ | Spacing | `--spacing` (base unit, used in `calc()`) |
132
+ | Shape | `--radius`, `--radius-sm`, `--radius-lg` |
133
+ | Motion | `--motion-duration-overlay`, `--motion-duration-disclosure`, `--motion-ease-standard` |
134
+
135
+ The entire type scale derives from `--font-size-base` and `--leading-base` — adjust those two tokens to scale all text globally.
136
+
137
+ ### Motion Modes
138
+
139
+ Set a motion mode on `html`, `body`, or any subtree:
140
+
141
+ ```html
142
+ <html data-motion="none"></html>
143
+ ```
144
+
145
+ Supported modes:
146
+
147
+ | Mode | Behaviour |
148
+ | ------- | --------------------------------------------------------------- |
149
+ | `none` | Removes transition and overlay/disclosure animation durations |
150
+ | `color` | Keeps short color transitions, disables movement and overlays |
151
+ | `full` | Enables the default semantic durations even with reduced motion |
152
+
153
+ For custom tuning, override the role tokens after importing styles:
154
+
155
+ ```css
156
+ :root {
157
+ --motion-duration-color: 120ms;
158
+ --motion-duration-disclosure: 180ms;
159
+ --motion-duration-overlay: 120ms;
160
+ }
161
+ ```
162
+
163
+ ### Live Token Editor
164
+
165
+ Use the `ThemeInjector` component for a floating palette button that opens a live token editor:
166
+
167
+ ```tsx
168
+ import { ThemeInjector } from '@leitware/composables'
169
+
170
+ export default function RootLayout({ children }) {
171
+ return (
172
+ <html>
173
+ <body>
174
+ {children}
175
+ <ThemeInjector />
176
+ </body>
177
+ </html>
178
+ )
179
+ }
180
+ ```
181
+
182
+ ---
183
+
184
+ ## Presets
185
+
186
+ Two built-in design presets are available as standalone CSS files you can paste into your `index.css`:
187
+
188
+ | Preset | Vibe | Fonts |
189
+ | ------------- | -------------------------------------- | ------------------------------ |
190
+ | **Default** | Clean neutral system, works everywhere | Inter + Bricolage Grotesque |
191
+ | **Brutalist** | Bold, high-contrast, raw aesthetic | Space Grotesk + JetBrains Mono |
192
+
193
+ ```css
194
+ /* Use exactly one shipped preset by importing it after styles.css */
195
+ @import '@leitware/composables/presets/brutalist.css';
196
+ ```
197
+
198
+ Font imports for non-default presets are commented out at the top of `composable.css` — uncomment the one you need.
199
+
200
+ ### Creating a Preset
201
+
202
+ Add one preset data file, then register it once:
203
+
204
+ 1. Copy `src/styles/presets-data/default.ts` to `src/styles/presets-data/<name>.ts`.
205
+ 2. Export `<name>` and `<name>Dark` records from that file.
206
+ 3. Import those records in `src/styles/presets-data/index.ts` and add one entry to `presetDefinitions`.
207
+ 4. Run `bun run generate:presets`.
208
+ 5. Run `bun run test:tokens`.
209
+
210
+ That single registry entry feeds the generated CSS files, the downstream package export, and the `TokenConfigPanel` preset dropdown. During `bun run build:css`, the preset is copied to `dist/presets/<name>.css`, so downstream apps can switch presets by changing the import:
211
+
212
+ ```css
213
+ @import '@leitware/composables/styles.css';
214
+ @import '@leitware/composables/presets/<name>.css';
215
+ ```
216
+
217
+ App-level overrides should come after the preset import.
218
+
219
+ ### Token System Checks
220
+
221
+ The token system self-regulates through CI checks:
222
+
223
+ - `bun scripts/generate-css.ts --check` verifies generated palette CSS.
224
+ - `bun scripts/generate-preset-css.ts --check` verifies generated preset CSS.
225
+ - `bun scripts/generate-rules.ts --check` verifies generated AI usage rules.
226
+ - `bun run test:tokens` verifies semantic token registry coverage, Tailwind aliases, preset keys, and semantic class usage.
227
+ - `bun run test:css` verifies the compiled downstream CSS contains required tokens and utilities.
228
+
229
+ Install local Git hooks to run the same checks before commits:
230
+
231
+ ```bash
232
+ bun run hooks:install
233
+ ```
234
+
235
+ The repo-owned `.githooks/pre-commit` hook runs linting, formatting, typechecking, generated CSS drift checks, and semantic token checks. `.githooks/commit-msg` enforces Conventional Commits.
236
+
237
+ ---
238
+
239
+ ## Linting
240
+
241
+ The project uses [Oxlint](https://oxc.rs/docs/guide/usage/linter.html) for linting and [Oxc Formatter](https://oxc.rs/docs/guide/usage/formatter.html) for formatting. A custom script checks for arbitrary Tailwind values to enforce design token usage:
242
+
243
+ ```bash
244
+ bun src/scripts/lint-no-arbitrary.ts src showcase/src
245
+ ```
246
+
247
+ ---
248
+
249
+ ## Showcase
250
+
251
+ Live component demo: **[https://rowanhen.github.io/composables/](https://rowanhen.github.io/composables/)**
252
+
253
+ ---
254
+
255
+ ## Components
256
+
257
+ ### Foundation
258
+
259
+ | Component | Description |
260
+ | --------------- | ------------------------------------------------------------- |
261
+ | `utils` | Utility functions for className merging and focus ring styles |
262
+ | `styles` | Base design system CSS styles and theme tokens |
263
+ | `numeric-input` | Numeric input parsing and formatting utilities |
264
+
265
+ ### Hooks
266
+
267
+ | Component | Description |
268
+ | -------------------- | ------------------------------------------------------------- |
269
+ | `use-mobile` | Hook to detect mobile viewport breakpoint |
270
+ | `use-numeric-input` | Hook for numeric input handling with sanitization and parsing |
271
+ | `direction-provider` | Base UI reading-direction provider with `useDirection` |
272
+
273
+ ### Layout
274
+
275
+ | Component | Description |
276
+ | -------------- | ----------------------------------------------------------- |
277
+ | `stack` | Flex-based vertical or horizontal stack layout |
278
+ | `grid` | Responsive CSS grid layout component |
279
+ | `container` | Centered max-width content wrapper |
280
+ | `spacer` | Flexible whitespace component for spacing |
281
+ | `separator` | Visual divider line between content sections |
282
+ | `layout` | Rigid layout primitives: Section, FlexSpacer, NewspaperGrid |
283
+ | `layout-bento` | Bento grid layout with BentoGrid, BentoCell, and composites |
284
+ | `resizable` | Resizable split pane panels |
285
+ | `scroll-area` | Custom scrollbar container with overflow handling |
286
+
287
+ ### Typography & Display
288
+
289
+ | Component | Description |
290
+ | ------------ | ------------------------------------------------------------------- |
291
+ | `typography` | Polymorphic text component with typographic scale variants |
292
+ | `badge` | Small status label with color variants |
293
+ | `avatar` | Circular image element with automatic initials fallback |
294
+ | `icon` | Icon wrapper with size and color variants |
295
+ | `kbd` | Keyboard shortcut key and key group display |
296
+ | `skeleton` | Animated placeholder for loading content |
297
+ | `progress` | Horizontal progress bar indicator |
298
+ | `divider` | Horizontal or vertical divider with solid, dots, and pills variants |
299
+
300
+ ### Feedback & Overlay
301
+
302
+ | Component | Description |
303
+ | -------------- | ---------------------------------------------------------- |
304
+ | `alert` | Contextual feedback messages with type-based icon mapping |
305
+ | `dialog` | Modal dialog overlay with trigger, title, and footer props |
306
+ | `alert-dialog` | Modal dialog for important confirmations |
307
+ | `sheet` | Slide-out panel from screen edge |
308
+ | `popover` | Floating content panel anchored to a trigger |
309
+ | `tooltip` | Informational popup on hover or focus |
310
+ | `hover-card` | Preview card shown on hover |
311
+ | `sonner` | Toast notification system powered by Sonner |
312
+
313
+ ### Navigation
314
+
315
+ | Component | Description |
316
+ | --------------- | ------------------------------------------------------ |
317
+ | `tabs` | Tabbed content navigation with items array API |
318
+ | `breadcrumb` | Navigation trail with items array API |
319
+ | `pagination` | Page navigation with currentPage and totalPages API |
320
+ | `sidebar` | Application sidebar with collapsible navigation groups |
321
+ | `dropdown-menu` | Contextual menu triggered by a button |
322
+
323
+ ### Data Display
324
+
325
+ | Component | Description |
326
+ | ------------- | ---------------------------------------------------------------------------- |
327
+ | `table` | Semantic HTML table with styled rows and cells |
328
+ | `card` | Bordered content container with title, description, action, and footer props |
329
+ | `accordion` | Vertically collapsible content sections with items array API |
330
+ | `collapsible` | Expandable and collapsible content panel with trigger prop |
331
+ | `item` | Flexible list item with title, description, icon, and actions |
332
+ | `message` | Message row primitives for chat, activity, and assistant UIs |
333
+ | `bubble` | Message bubble primitives with semantic variants |
334
+ | `marker` | Inline metadata marker with icon, separator, and border variants |
335
+ | `empty` | Empty state placeholder with icon, title, and description |
336
+ | `carousel` | Horizontally scrollable content slider with items array API |
337
+ | `code-block` | Monospace code display with line numbers |
338
+ | `list` | Variant list renderer: arrow, bullet |
339
+
340
+ ### Form Components
341
+
342
+ | Component | Description |
343
+ | ----------------------- | ------------------------------------------------------------ |
344
+ | `form-input` | Text input field with label, error, and numeric mode support |
345
+ | `form-select` | Select dropdown field with options array API |
346
+ | `native-select` | Native HTML select with the design-system field treatment |
347
+ | `form-combobox` | Searchable select field with options array API |
348
+ | `form-multi-combobox` | Multi-select combobox field with chip display |
349
+ | `form-textarea` | Textarea field with label, description, and error handling |
350
+ | `form-checkbox` | Checkbox field with label, description, and error handling |
351
+ | `form-switch` | Switch toggle field with label and description |
352
+ | `form-radiogroup` | Radio group field with options array API |
353
+ | `form-slider` | Slider field with label, value display, and error handling |
354
+ | `form-input-group` | Input group field with addons, buttons, and numeric support |
355
+ | `form-calendar-popover` | Date picker field with calendar popover |
356
+ | `form-date-of-birth` | Three-field date of birth input with auto-advance |
357
+ | `form-dropzone` | Single file upload field with drag-and-drop |
358
+ | `form-multi-dropzone` | Multi-file upload field with drag-and-drop |
359
+
360
+ ### Interactive
361
+
362
+ | Component | Description |
363
+ | -------------- | ------------------------------------------------------- |
364
+ | `button` | Clickable button with loading spinner support |
365
+ | `toggle` | Pressable toggle button with left and right icon slots |
366
+ | `toggle-group` | Grouped toggle buttons for single or multiple selection |
367
+ | `switch` | Toggle switch for on/off states |
368
+ | `slider` | Draggable range slider input |
369
+ | `checkbox` | Toggle checkbox input with checked state |
370
+ | `radio-group` | Group of mutually exclusive radio options |
371
+ | `combobox` | Searchable select dropdown with autocomplete |
372
+ | `select` | Dropdown select menu with scrollable options |
373
+ | `calendar` | Date picker calendar powered by react-day-picker |
374
+ | `dropzone` | Drag-and-drop file upload area |
375
+
376
+ ### Tooling Components
377
+
378
+ | Component | Description |
379
+ | -------------------- | --------------------------------------------------------------------------------- |
380
+ | `token-config-panel` | Live token editor with color pickers, sliders, font selector, and preset switcher |
381
+ | `theme-injector` | Floating palette button that opens the token editor from any page |
382
+
383
+ ---
384
+
385
+ ## License
386
+
387
+ MIT — see [LICENSE](LICENSE) for details.