@duskmoon-dev/core 0.1.0 → 1.0.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 (51) hide show
  1. package/README.md +366 -78
  2. package/dist/components/accordion.css +244 -0
  3. package/dist/components/alert.css +199 -0
  4. package/dist/components/appbar.css +308 -0
  5. package/dist/components/autocomplete.css +269 -0
  6. package/dist/components/avatar.css +167 -0
  7. package/dist/components/badge.css +178 -0
  8. package/dist/components/bottom-navigation.css +263 -0
  9. package/dist/components/bottomsheet.css +334 -0
  10. package/dist/components/button.css +474 -0
  11. package/dist/components/card.css +220 -0
  12. package/dist/components/chip.css +211 -0
  13. package/dist/components/collapse.css +254 -0
  14. package/dist/components/datepicker.css +347 -0
  15. package/dist/components/dialog.css +173 -0
  16. package/dist/components/divider.css +284 -0
  17. package/dist/components/drawer.css +371 -0
  18. package/dist/components/file-upload.css +321 -0
  19. package/dist/components/form.css +441 -0
  20. package/dist/components/index.css +9994 -0
  21. package/dist/components/input.css +240 -0
  22. package/dist/components/list.css +188 -0
  23. package/dist/components/markdown-body.css +405 -0
  24. package/dist/components/modal.css +291 -0
  25. package/dist/components/navigation.css +392 -0
  26. package/dist/components/popover.css +326 -0
  27. package/dist/components/progress.css +238 -0
  28. package/dist/components/rating.css +230 -0
  29. package/dist/components/skeleton.css +216 -0
  30. package/dist/components/slider.css +327 -0
  31. package/dist/components/snackbar.css +311 -0
  32. package/dist/components/stepper.css +313 -0
  33. package/dist/components/switch.css +277 -0
  34. package/dist/components/table.css +199 -0
  35. package/dist/components/timeline.css +353 -0
  36. package/dist/components/toast.css +251 -0
  37. package/dist/components/tooltip.css +284 -0
  38. package/dist/index.css +10699 -0
  39. package/dist/themes/moonlight.css +168 -0
  40. package/dist/themes/sunshine.css +166 -0
  41. package/dist/types/index.d.ts +14 -0
  42. package/dist/types/index.d.ts.map +1 -0
  43. package/dist/types/plugin.d.ts +69 -0
  44. package/dist/types/plugin.d.ts.map +1 -0
  45. package/dist/types/theme.d.ts +202 -0
  46. package/dist/types/theme.d.ts.map +1 -0
  47. package/package.json +137 -18
  48. package/dist/index.cjs +0 -243
  49. package/dist/index.cjs.map +0 -15
  50. package/dist/index.js +0 -211
  51. package/dist/index.js.map +0 -15
package/README.md CHANGED
@@ -1,124 +1,365 @@
1
1
  # @duskmoon-dev/core
2
2
 
3
- > DuskMoonUI - A Tailwind CSS component library with extended color system
3
+ > DuskMoonUI - A Tailwind CSS v4 plugin with Material Design 3 color system and 42 component styles
4
+
5
+ [![npm version](https://img.shields.io/npm/v/@duskmoon-dev/core.svg)](https://www.npmjs.com/package/@duskmoon-dev/core)
6
+ [![npm downloads](https://img.shields.io/npm/dm/@duskmoon-dev/core.svg)](https://www.npmjs.com/package/@duskmoon-dev/core)
7
+ [![bundle size](https://img.shields.io/bundlephobia/minzip/@duskmoon-dev/core)](https://bundlephobia.com/package/@duskmoon-dev/core)
8
+ [![license](https://img.shields.io/npm/l/@duskmoon-dev/core.svg)](https://github.com/duskmoon-dev/duskmoonui/blob/main/LICENSE)
4
9
 
5
10
  ## Features
6
11
 
7
- - 🎨 Extended color system with tertiary colors
8
- - 🌓 Built-in Sunshine and Moonlight themes
9
- - 📦 65+ Material Design 3 color tokens
10
- - ⚡ JavaScript-based CSS generation
11
- - 🚀 Optimized for Bun runtime
12
- - 🎯 Full TypeScript support
12
+ - 🎨 **Three-color system** - Primary, secondary, and tertiary brand colors with automatic content colors
13
+ - 🌓 **Built-in themes** - Sunshine (light) and Moonlight (dark) themes ready to use
14
+ - 📦 **55+ Material Design 3 color tokens** - Full MD3 color system with OKLCH format
15
+ - 🧩 **42 UI components** - Complete component library with consistent styling
16
+ - 🚀 **Zero runtime JS** - Pure CSS with CSS custom properties for theme switching
17
+ - ♿ **Accessible by default** - WCAG AA compliant contrast ratios (4.5:1 minimum)
18
+ - 🎯 **Tailwind v4 native** - Pure CSS using `@import`, no JavaScript configuration
19
+ - 📦 **Tiny bundle** - Under 7KB gzipped
13
20
 
14
21
  ## Installation
15
22
 
16
23
  ```bash
17
24
  # Using Bun (recommended)
18
- bun add @duskmoon-dev/core tailwindcss
25
+ bun add @duskmoon-dev/core tailwindcss@^4.0.0
19
26
 
20
27
  # Using npm
21
- npm install @duskmoon-dev/core tailwindcss
28
+ npm install @duskmoon-dev/core tailwindcss@^4.0.0
22
29
 
23
30
  # Using pnpm
24
- pnpm add @duskmoon-dev/core tailwindcss
31
+ pnpm add @duskmoon-dev/core tailwindcss@^4.0.0
25
32
  ```
26
33
 
27
34
  ## Quick Start
28
35
 
29
- Add the plugin to your `tailwind.config.js`:
30
-
31
- ```js
32
- import duskmoonui from '@duskmoon-dev/core';
36
+ ### 1. Import the plugin in your CSS
33
37
 
34
- export default {
35
- content: ['./src/**/*.{html,js,jsx,ts,tsx}'],
36
- plugins: [
37
- duskmoonui({
38
- themes: ['sunshine', 'moonlight'],
39
- darkTheme: 'moonlight',
40
- }),
41
- ],
42
- };
38
+ ```css
39
+ /* src/styles.css */
40
+ @import "tailwindcss";
41
+ @import "@duskmoon-dev/core";
43
42
  ```
44
43
 
45
- Then set the theme in your HTML:
44
+ ### 2. Add the theme attribute to your HTML
46
45
 
47
46
  ```html
48
47
  <html data-theme="sunshine">
49
- <!-- Your app -->
48
+ <body>
49
+ <button class="btn btn-primary">Click me</button>
50
+ </body>
50
51
  </html>
51
52
  ```
52
53
 
53
- ## Usage
54
+ ### 3. Use the color utilities
55
+
56
+ ```html
57
+ <!-- Brand colors -->
58
+ <div class="bg-primary text-primary-content">Primary</div>
59
+ <div class="bg-secondary text-secondary-content">Secondary</div>
60
+ <div class="bg-tertiary text-tertiary-content">Tertiary</div>
61
+
62
+ <!-- Surface colors -->
63
+ <div class="bg-surface text-on-surface">Surface</div>
64
+ <div class="bg-surface-container">Container</div>
65
+
66
+ <!-- Semantic colors -->
67
+ <div class="bg-success text-success-content">Success</div>
68
+ <div class="bg-error text-error-content">Error</div>
69
+ ```
70
+
71
+ ## Theme Switching
72
+
73
+ Switch themes by changing the `data-theme` attribute - no JavaScript required:
74
+
75
+ ```html
76
+ <!-- Light theme -->
77
+ <html data-theme="sunshine">
78
+
79
+ <!-- Dark theme -->
80
+ <html data-theme="moonlight">
81
+ ```
82
+
83
+ Theme switching is instant and uses pure CSS custom properties.
84
+
85
+ ## Components
86
+
87
+ @duskmoon-dev/core includes **42 components** organized into 7 categories:
88
+
89
+ ### Core Components (6)
90
+
91
+ | Component | Classes | Description |
92
+ |-----------|---------|-------------|
93
+ | Button | `.btn`, `.btn-primary`, `.btn-secondary`, `.btn-outline`, `.btn-ghost` | Buttons with variants, sizes, and states |
94
+ | Card | `.card`, `.card-body`, `.card-title`, `.card-bordered` | Content containers with headers and actions |
95
+ | Input | `.input`, `.input-bordered`, `.input-primary` | Text inputs with sizes and states |
96
+ | Form | `.form-control`, `.label`, `.checkbox`, `.radio`, `.toggle`, `.select`, `.textarea` | Form elements and layouts |
97
+ | Navigation | `.navbar`, `.menu`, `.breadcrumbs`, `.tabs`, `.pagination`, `.dropdown` | Navigation patterns |
98
+ | Modal | `.modal`, `.modal-box`, `.modal-action` | Dialog overlays |
99
+
100
+ ### Data Display (5)
101
+
102
+ | Component | Classes | Description |
103
+ |-----------|---------|-------------|
104
+ | Avatar | `.avatar`, `.avatar-sm`, `.avatar-lg`, `.avatar-group` | User avatars with sizes and groups |
105
+ | Badge | `.badge`, `.badge-primary`, `.badge-outline`, `.badge-dot` | Status indicators and labels |
106
+ | Chip | `.chip`, `.chip-primary`, `.chip-outlined`, `.chip-closeable` | Interactive tags |
107
+ | List | `.list`, `.list-item`, `.list-bordered`, `.list-hoverable` | Vertical item lists |
108
+ | Table | `.table`, `.table-zebra`, `.table-hover`, `.table-bordered` | Data tables |
109
+
110
+ ### Data Entry (6)
111
+
112
+ | Component | Classes | Description |
113
+ |-----------|---------|-------------|
114
+ | Autocomplete | `.autocomplete`, `.autocomplete-dropdown`, `.autocomplete-option` | Searchable dropdowns |
115
+ | Datepicker | `.datepicker`, `.datepicker-dropdown`, `.datepicker-day` | Date selection |
116
+ | File Upload | `.file-upload`, `.file-upload-dropzone`, `.file-upload-item` | File uploads with drag-drop |
117
+ | Rating | `.rating`, `.rating-item`, `.rating-half` | Star ratings |
118
+ | Slider | `.slider`, `.slider-thumb`, `.slider-track` | Range inputs |
119
+ | Switch | `.switch`, `.switch-track`, `.switch-thumb` | Toggle switches |
120
+
121
+ ### Feedback (7)
122
+
123
+ | Component | Classes | Description |
124
+ |-----------|---------|-------------|
125
+ | Alert | `.alert`, `.alert-info`, `.alert-success`, `.alert-warning`, `.alert-error` | Alert messages |
126
+ | Dialog | `.dialog`, `.dialog-header`, `.dialog-body`, `.dialog-footer` | Confirmation dialogs |
127
+ | Progress | `.progress`, `.progress-bar`, `.progress-circular` | Progress indicators |
128
+ | Skeleton | `.skeleton`, `.skeleton-text`, `.skeleton-circle`, `.skeleton-wave` | Loading placeholders |
129
+ | Snackbar | `.snackbar`, `.snackbar-message`, `.snackbar-action` | Brief notifications |
130
+ | Toast | `.toast`, `.toast-container`, `.toast-info`, `.toast-success` | Toast notifications |
131
+ | Tooltip | `.tooltip`, `.tooltip-content`, `.tooltip-top`, `.tooltip-bottom` | Hover tooltips |
132
+
133
+ ### Layout (2)
134
+
135
+ | Component | Classes | Description |
136
+ |-----------|---------|-------------|
137
+ | App Bar | `.appbar`, `.appbar-title`, `.appbar-nav`, `.appbar-actions` | Top app bars |
138
+ | Divider | `.divider`, `.divider-vertical`, `.divider-text` | Content separators |
139
+
140
+ ### Navigation (3)
141
+
142
+ | Component | Classes | Description |
143
+ |-----------|---------|-------------|
144
+ | Bottom Navigation | `.bottom-nav`, `.bottom-nav-item`, `.bottom-nav-indicator` | Mobile navigation |
145
+ | Drawer | `.drawer`, `.drawer-content`, `.drawer-nav-item` | Side navigation |
146
+ | Stepper | `.stepper`, `.stepper-step`, `.stepper-indicator` | Multi-step processes |
147
+
148
+ ### Surfaces (4)
149
+
150
+ | Component | Classes | Description |
151
+ |-----------|---------|-------------|
152
+ | Accordion | `.accordion`, `.accordion-item`, `.accordion-header`, `.accordion-content` | Expandable panels |
153
+ | Bottom Sheet | `.bottomsheet`, `.bottomsheet-handle`, `.bottomsheet-content` | Mobile sheets |
154
+ | Collapse | `.collapse`, `.collapse-content`, `.collapse-toggle` | Collapsible content |
155
+ | Popover | `.popover`, `.popover-content`, `.popover-arrow` | Floating content |
156
+
157
+ ### Misc (1)
158
+
159
+ | Component | Classes | Description |
160
+ |-----------|---------|-------------|
161
+ | Timeline | `.timeline`, `.timeline-item`, `.timeline-marker` | Event timelines |
162
+
163
+ ## Component Examples
164
+
165
+ ### Button
166
+ ```html
167
+ <button class="btn">Default</button>
168
+ <button class="btn btn-primary">Primary</button>
169
+ <button class="btn btn-secondary">Secondary</button>
170
+ <button class="btn btn-tertiary">Tertiary</button>
171
+ <button class="btn btn-outline">Outline</button>
172
+ <button class="btn btn-ghost">Ghost</button>
173
+
174
+ <!-- Sizes -->
175
+ <button class="btn btn-xs">Extra small</button>
176
+ <button class="btn btn-sm">Small</button>
177
+ <button class="btn btn-lg">Large</button>
178
+ ```
179
+
180
+ ### Card
181
+ ```html
182
+ <div class="card">
183
+ <div class="card-body">
184
+ <h2 class="card-title">Card title</h2>
185
+ <p>Card content goes here.</p>
186
+ <div class="card-actions">
187
+ <button class="btn btn-primary">Action</button>
188
+ </div>
189
+ </div>
190
+ </div>
191
+ ```
192
+
193
+ ### Avatar
194
+ ```html
195
+ <div class="avatar">
196
+ <img src="user.jpg" alt="User" />
197
+ </div>
198
+ <div class="avatar avatar-lg avatar-rounded">
199
+ <img src="user.jpg" alt="User" />
200
+ </div>
201
+ <div class="avatar-group">
202
+ <div class="avatar"><img src="user1.jpg" /></div>
203
+ <div class="avatar"><img src="user2.jpg" /></div>
204
+ <div class="avatar"><img src="user3.jpg" /></div>
205
+ </div>
206
+ ```
54
207
 
55
- ### Using Theme Colors
208
+ ### Alert
209
+ ```html
210
+ <div class="alert alert-info">
211
+ <span class="alert-icon">ℹ</span>
212
+ <span class="alert-message">Information message</span>
213
+ </div>
214
+ <div class="alert alert-success">Success!</div>
215
+ <div class="alert alert-warning">Warning!</div>
216
+ <div class="alert alert-error">Error!</div>
217
+ ```
56
218
 
57
- ```jsx
58
- <div className="bg-primary text-primary-content">
59
- Primary button
219
+ ### Progress
220
+ ```html
221
+ <!-- Linear -->
222
+ <div class="progress">
223
+ <div class="progress-bar" style="width: 60%"></div>
60
224
  </div>
61
225
 
62
- <div className="bg-secondary text-secondary-content">
63
- Secondary button
226
+ <!-- Indeterminate -->
227
+ <div class="progress progress-indeterminate">
228
+ <div class="progress-bar"></div>
64
229
  </div>
65
230
 
66
- <div className="bg-tertiary text-tertiary-content">
67
- Tertiary button (NEW!)
231
+ <!-- Circular -->
232
+ <div class="progress-circular">
233
+ <svg><circle class="progress-circular-track" /><circle class="progress-circular-bar" /></svg>
68
234
  </div>
69
235
  ```
70
236
 
71
- ### Custom Themes
237
+ ### Toast
238
+ ```html
239
+ <div class="toast-container toast-container-top-right">
240
+ <div class="toast toast-success show">
241
+ <span class="toast-icon">✓</span>
242
+ <div class="toast-content">
243
+ <span class="toast-title">Success</span>
244
+ <span class="toast-message">Your changes have been saved.</span>
245
+ </div>
246
+ <button class="toast-close">×</button>
247
+ </div>
248
+ </div>
249
+ ```
72
250
 
73
- ```js
74
- duskmoonui({
75
- themes: [
76
- 'sunshine',
77
- 'moonlight',
78
- {
79
- mytheme: {
80
- primary: '200 100% 50%',
81
- secondary: '280 100% 50%',
82
- tertiary: '340 100% 50%',
83
- // ... other colors
84
- },
85
- },
86
- ],
87
- });
251
+ ### Stepper
252
+ ```html
253
+ <div class="stepper">
254
+ <div class="stepper-step completed">
255
+ <div class="stepper-indicator">1</div>
256
+ <span class="stepper-title">Step 1</span>
257
+ </div>
258
+ <div class="stepper-step active">
259
+ <div class="stepper-indicator">2</div>
260
+ <span class="stepper-title">Step 2</span>
261
+ </div>
262
+ <div class="stepper-step">
263
+ <div class="stepper-indicator">3</div>
264
+ <span class="stepper-title">Step 3</span>
265
+ </div>
266
+ </div>
88
267
  ```
89
268
 
90
269
  ## Color System
91
270
 
92
- DuskMoonUI extends the standard Tailwind color system with:
93
-
94
- - **Tertiary colors** - A third brand color for more design flexibility
95
- - **Surface containers** - Material Design 3 surface elevation system
96
- - **On-color variants** - Guaranteed accessible text colors
97
- - **Container colors** - Tinted backgrounds for components
98
-
99
- ### Available Color Tokens
100
-
101
- - Primary: `primary`, `primary-focus`, `primary-content`, `primary-container`, `on-primary-container`
102
- - Secondary: `secondary`, `secondary-focus`, `secondary-content`, `secondary-container`, `on-secondary-container`
103
- - Tertiary: `tertiary`, `tertiary-focus`, `tertiary-content`, `tertiary-container`, `on-tertiary-container`
104
- - Surface: `surface`, `surface-dim`, `surface-bright`, `surface-container-{lowest|low|default|high|highest}`
105
- - Semantic: `info`, `success`, `warning`, `error` (with `-content` variants)
106
-
107
- ## Plugin Options
108
-
109
- ```typescript
110
- interface DuskMoonUIOptions {
111
- themes?: ThemeConfig[]; // Themes to include
112
- darkTheme?: string; // Default dark theme name
113
- prefix?: string; // Component prefix
114
- components?: string[] | 'all'; // Components to include
115
- utilities?: boolean; // Enable utility classes
116
- rtl?: boolean; // RTL support
117
- styled?: boolean; // Generate component styles
118
- base?: boolean; // Include base styles
271
+ DuskMoonUI v2.0 uses the OKLCH color format for perceptually uniform color manipulation.
272
+
273
+ ### Brand Colors (12 tokens)
274
+ - `primary`, `primary-content`, `primary-container`, `on-primary-container`
275
+ - `secondary`, `secondary-content`, `secondary-container`, `on-secondary-container`
276
+ - `tertiary`, `tertiary-content`, `tertiary-container`, `on-tertiary-container`
277
+
278
+ > **Note**: `-focus` tokens are removed in v2.0. Use `color-mix()` instead:
279
+ > ```css
280
+ > .btn:hover {
281
+ > background-color: color-mix(in oklch, var(--color-primary), black 10%);
282
+ > }
283
+ > ```
284
+
285
+ ### Surface Colors (10 tokens)
286
+ - `surface`, `surface-dim`, `surface-bright`
287
+ - `surface-container-lowest`, `surface-container-low`, `surface-container`, `surface-container-high`, `surface-container-highest`
288
+ - `on-surface`, `on-surface-variant`
289
+
290
+ ### Semantic Colors (12 tokens)
291
+ - `info`, `info-content`, `info-container`, `on-info-container`
292
+ - `success`, `success-content`, `success-container`, `on-success-container`
293
+ - `warning`, `warning-content`, `warning-container`, `on-warning-container`
294
+ - `error`, `error-content`, `error-container`, `on-error-container`
295
+
296
+ ### Neutral Colors (10 tokens)
297
+ - `base-100` through `base-900`
298
+ - `base-content`
299
+
300
+ ### Outline Colors (2 tokens)
301
+ - `outline`, `outline-variant`
302
+
303
+ ## Custom Themes
304
+
305
+ Define custom themes using OKLCH format:
306
+
307
+ ```css
308
+ [data-theme="custom"] {
309
+ color-scheme: light;
310
+
311
+ /* OKLCH format: oklch(L% C H) */
312
+ /* L = Lightness (0-100%), C = Chroma (0-0.4), H = Hue (0-360) */
313
+ --color-primary: oklch(65% 0.18 255);
314
+ --color-primary-content: oklch(100% 0 0);
315
+ --color-secondary: oklch(60% 0.18 300);
316
+ --color-secondary-content: oklch(100% 0 0);
317
+ --color-tertiary: oklch(70% 0.15 80);
318
+ --color-tertiary-content: oklch(20% 0 0);
319
+
320
+ /* Base colors */
321
+ --color-base-100: oklch(100% 0 0);
322
+ --color-base-200: oklch(98% 0.01 85);
323
+ --color-base-300: oklch(96% 0.01 85);
324
+ --color-base-content: oklch(27% 0.02 260);
325
+
326
+ /* Add remaining tokens... */
119
327
  }
120
328
  ```
121
329
 
330
+ ### OKLCH Color Values
331
+
332
+ | Hue | Color |
333
+ |-----|-------|
334
+ | 0/360 | Pink |
335
+ | 30 | Red |
336
+ | 55 | Orange |
337
+ | 80 | Yellow |
338
+ | 145 | Green |
339
+ | 185 | Teal |
340
+ | 235 | Blue |
341
+ | 255 | Indigo |
342
+ | 300 | Purple |
343
+
344
+ ## Accessibility
345
+
346
+ All components include:
347
+
348
+ - **Keyboard navigation** - Full keyboard support with focus indicators
349
+ - **Screen reader support** - Proper ARIA attributes and semantic HTML
350
+ - **Color contrast** - WCAG AA compliant (4.5:1 minimum)
351
+ - **Reduced motion** - Respects `prefers-reduced-motion` preference
352
+
353
+ ## Requirements
354
+
355
+ - Tailwind CSS v4.0.0 or later
356
+ - Modern browsers with OKLCH and `color-mix()` support:
357
+ - Chrome 111+ (March 2023)
358
+ - Safari 15.4+ (March 2022)
359
+ - Firefox 113+ (May 2023)
360
+ - Edge 111+ (March 2023)
361
+ - Global browser support: ~92%
362
+
122
363
  ## Development
123
364
 
124
365
  ```bash
@@ -135,9 +376,56 @@ bun run dev
135
376
  bun run typecheck
136
377
 
137
378
  # Run tests
138
- bun test
379
+ bun run test
380
+ bun run test:visual
381
+ bun run test:integration
382
+ bun run test:a11y
383
+ ```
384
+
385
+ ## Migration from v1.x
386
+
387
+ v2.0.0 introduces OKLCH color format (breaking change):
388
+
389
+ ### Color Format Change
390
+
391
+ **Before (v1.x - HSL)**:
392
+ ```css
393
+ /* Theme values stored as HSL components */
394
+ --color-primary: 30 90% 55%;
395
+ background-color: hsl(var(--color-primary));
139
396
  ```
140
397
 
398
+ **After (v2.0 - OKLCH)**:
399
+ ```css
400
+ /* Theme values stored as full OKLCH */
401
+ --color-primary: oklch(72% 0.18 55);
402
+ background-color: var(--color-primary);
403
+ ```
404
+
405
+ ### Removed Tokens
406
+
407
+ The `-focus` tokens are removed. Use `color-mix()` instead:
408
+
409
+ ```css
410
+ /* Before */
411
+ background-color: hsl(var(--color-primary-focus));
412
+
413
+ /* After */
414
+ background-color: color-mix(in oklch, var(--color-primary), black 10%);
415
+ ```
416
+
417
+ ### Transparency
418
+
419
+ ```css
420
+ /* Before */
421
+ background-color: rgba(var(--color-primary-rgb), 0.5);
422
+
423
+ /* After */
424
+ background-color: color-mix(in oklch, var(--color-primary) 50%, transparent);
425
+ ```
426
+
427
+ See [specs/004-oklch-color-system/quickstart.md](./specs/004-oklch-color-system/quickstart.md) for detailed migration guide.
428
+
141
429
  ## License
142
430
 
143
431
  MIT