@melodicdev/components 1.0.1 → 1.0.3

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 (10) hide show
  1. package/README.md +126 -48
  2. package/assets/melodic-components.css +671 -0
  3. package/assets/melodic-components.js +21082 -0
  4. package/assets/melodic-components.js.map +1 -0
  5. package/assets/melodic-components.min.css +21 -0
  6. package/assets/melodic-components.min.js +19382 -0
  7. package/lib/bundle.d.ts +59 -0
  8. package/lib/bundle.d.ts.map +1 -0
  9. package/lib/bundle.js +68 -0
  10. package/package.json +6 -2
package/README.md CHANGED
@@ -10,69 +10,105 @@ npm install @melodicdev/components @melodicdev/core
10
10
 
11
11
  `@melodicdev/core` is a peer dependency.
12
12
 
13
- ## Usage
13
+ ---
14
14
 
15
- Import a component module to register its custom element, then use it in HTML:
15
+ ## Quick Start
16
16
 
17
- ```ts
18
- import '@melodicdev/components/button';
17
+ ### 1. Add the stylesheet
18
+
19
+ Add a single `<link>` tag to your HTML. It includes design tokens (light + dark themes) and the Phosphor icon fonts — everything the components need to render correctly:
19
20
 
20
- document.body.innerHTML = `<ml-button>Click me</ml-button>`;
21
+ ```html
22
+ <link melodic-styles rel="stylesheet"
23
+ href="https://unpkg.com/@melodicdev/components/assets/melodic-components.css">
21
24
  ```
22
25
 
23
- ## Documentation
26
+ > **Production tip:** Pin to a specific version and use the minified build to avoid unexpected changes:
27
+ > ```html
28
+ > <link melodic-styles rel="stylesheet"
29
+ > href="https://unpkg.com/@melodicdev/components@1.0.3/assets/melodic-components.min.css">
30
+ > ```
24
31
 
25
- ### Components
26
- - [**Theming**](./docs/theming.md) — Token system, applying themes, creating custom themes, overriding styles
27
- - [**Forms**](./docs/components/forms.md) — button, button-group, input, textarea, checkbox, radio, radio-card-group, toggle, select, slider, date-picker, form-field
28
- - [**Foundation**](./docs/components/foundation.md) — card, divider, stack, container
29
- - [**Feedback**](./docs/components/feedback.md) — spinner, alert, progress, toast
30
- - [**Data Display**](./docs/components/data-display.md) — avatar, badge, badge-group, tag, list, activity-feed, table, data-grid, calendar-view
31
- - [**Navigation**](./docs/components/navigation.md) — tabs, breadcrumb, pagination, sidebar, steps
32
- - [**Overlays**](./docs/components/overlays.md) — dialog, drawer, popover, dropdown, tooltip
33
- - [**Sections**](./docs/components/sections.md) — app-shell, page-header, hero-section
32
+ The `melodic-styles` attribute has no special browser meaning — it's just a convenient selector if you ever need to find or replace the element from JavaScript:
34
33
 
35
- ### Utilities & Helpers
36
- - [**Utilities**](./docs/utilities.md) — positioning, accessibility (focus trap, live regions), virtual scrolling, style utilities
37
- - [**Directives & Functions**](./docs/directives-and-functions.md) — clickOutside, newID, theme functions, design token objects
34
+ ```ts
35
+ document.querySelector('link[melodic-styles]').href = '...new-url...';
36
+ ```
38
37
 
39
- ---
38
+ ### 2. Apply a theme
40
39
 
41
- ## Naming Conventions
40
+ Set `data-theme` on `<html>` to activate light or dark mode:
42
41
 
43
- ### Elements
42
+ ```html
43
+ <html data-theme="light">
44
+ ```
44
45
 
45
- All components use kebab-case with the `ml-` prefix:
46
+ Or use the JS theme API to apply and switch themes dynamically (including system/OS preference):
46
47
 
47
- ```
48
- ml-button, ml-input, ml-select, ml-checkbox, ml-data-grid, etc.
48
+ ```ts
49
+ import { applyTheme, toggleTheme } from '@melodicdev/components/theme';
50
+
51
+ applyTheme('light'); // data-theme="light"
52
+ applyTheme('dark'); // data-theme="dark"
53
+ applyTheme('system'); // follows OS preference, auto-updates
54
+ toggleTheme(); // flip between light and dark
49
55
  ```
50
56
 
51
- ### Events
57
+ ### 3. Import and use components
52
58
 
53
- All custom events use the `ml:` namespace prefix:
59
+ ```ts
60
+ import '@melodicdev/components/button';
61
+ import '@melodicdev/components/input';
62
+ // etc.
63
+ ```
54
64
 
65
+ ```html
66
+ <ml-button>Save</ml-button>
67
+ <ml-input placeholder="Search..."></ml-input>
55
68
  ```
56
- ml:click, ml:change, ml:input, ml:open, ml:close, ml:select, ml:sort, etc.
69
+
70
+ That's it. No additional setup needed for icons or fonts — they're bundled in `melodic-components.css`.
71
+
72
+ ---
73
+
74
+ ## CDN / No-Build Usage
75
+
76
+ If you're not using a bundler, you can load everything — styles, fonts, and all components — with just two tags. No npm, no build step required:
77
+
78
+ ```html
79
+ <!doctype html>
80
+ <html data-theme="light">
81
+ <head>
82
+ <link melodic-styles rel="stylesheet"
83
+ href="https://unpkg.com/@melodicdev/components@1.0.3/assets/melodic-components.min.css">
84
+ <script type="module"
85
+ src="https://unpkg.com/@melodicdev/components@1.0.3/assets/melodic-components.min.js"></script>
86
+ </head>
87
+ <body>
88
+ <ml-button>Hello</ml-button>
89
+ <ml-icon icon="star"></ml-icon>
90
+ </body>
91
+ </html>
57
92
  ```
58
93
 
59
- Listening in a Melodic template:
94
+ The JS bundle includes the full Melodic framework (core, forms, routing, HTTP, dependency injection, and state management) — no separate script needed. All components register themselves automatically when the script loads.
95
+
96
+ The theme API is available as a named export from the module:
60
97
 
61
98
  ```html
62
- <ml-button @ml:click=${this.handleClick}>Save</ml-button>
63
- <ml-input @ml:change=${this.handleChange}></ml-input>
64
- <ml-select @ml:open=${this.onOpen} @ml:close=${this.onClose}></ml-select>
99
+ <script type="module">
100
+ import { applyTheme } from 'https://unpkg.com/@melodicdev/components@1.0.3/assets/melodic-components.min.js';
101
+ applyTheme('dark');
102
+ </script>
65
103
  ```
66
104
 
67
105
  ---
68
106
 
69
- ## Icons
70
-
71
- The `ml-icon` component displays icons using [Phosphor Icons](https://phosphoricons.com/) via font ligatures.
107
+ ## Bundler / Framework Setup
72
108
 
73
- ### Setup
109
+ If you'd rather serve fonts locally (for offline use, CSP restrictions, etc.) instead of using the CDN, copy the assets from the package:
74
110
 
75
- Copy the font assets to your public directory. With Vite, use `vite-plugin-static-copy`:
111
+ **Vite:**
76
112
 
77
113
  ```bash
78
114
  npm install -D vite-plugin-static-copy
@@ -86,20 +122,24 @@ export default defineConfig({
86
122
  plugins: [
87
123
  viteStaticCopy({
88
124
  targets: [
89
- { src: 'node_modules/@melodicdev/components/assets/*', dest: 'public' }
125
+ { src: 'node_modules/@melodicdev/components/assets', dest: '.' }
90
126
  ]
91
127
  })
92
128
  ]
93
129
  });
94
130
  ```
95
131
 
96
- Add the font stylesheet to your HTML:
132
+ Then reference the local copy in your HTML:
97
133
 
98
134
  ```html
99
- <link rel="stylesheet" href="/public/fonts/phosphor/phosphor.css" />
135
+ <link melodic-styles rel="stylesheet" href="/assets/melodic-components.css">
100
136
  ```
101
137
 
102
- ### Usage
138
+ ---
139
+
140
+ ## Icons
141
+
142
+ The `ml-icon` component uses [Phosphor Icons](https://phosphoricons.com/) via font ligatures. The fonts are included in `melodic-components.css` — no separate setup needed if you're using the stylesheet above.
103
143
 
104
144
  ```ts
105
145
  import '@melodicdev/components/icon';
@@ -129,6 +169,52 @@ ml-icon {
129
169
 
130
170
  ---
131
171
 
172
+ ## Documentation
173
+
174
+ ### Components
175
+ - [**Theming**](./docs/theming.md) — Token system, applying themes, creating custom themes, overriding styles
176
+ - [**Forms**](./docs/components/forms.md) — button, button-group, input, textarea, checkbox, radio, radio-card-group, toggle, select, slider, date-picker, form-field
177
+ - [**Foundation**](./docs/components/foundation.md) — card, divider, stack, container
178
+ - [**Feedback**](./docs/components/feedback.md) — spinner, alert, progress, toast
179
+ - [**Data Display**](./docs/components/data-display.md) — avatar, badge, badge-group, tag, list, activity-feed, table, data-grid, calendar-view
180
+ - [**Navigation**](./docs/components/navigation.md) — tabs, breadcrumb, pagination, sidebar, steps
181
+ - [**Overlays**](./docs/components/overlays.md) — dialog, drawer, popover, dropdown, tooltip
182
+ - [**Sections**](./docs/components/sections.md) — app-shell, page-header, hero-section
183
+
184
+ ### Utilities & Helpers
185
+ - [**Utilities**](./docs/utilities.md) — positioning, accessibility (focus trap, live regions), virtual scrolling, style utilities
186
+ - [**Directives & Functions**](./docs/directives-and-functions.md) — clickOutside, newID, theme functions, design token objects
187
+
188
+ ---
189
+
190
+ ## Naming Conventions
191
+
192
+ ### Elements
193
+
194
+ All components use kebab-case with the `ml-` prefix:
195
+
196
+ ```
197
+ ml-button, ml-input, ml-select, ml-checkbox, ml-data-grid, etc.
198
+ ```
199
+
200
+ ### Events
201
+
202
+ All custom events use the `ml:` namespace prefix:
203
+
204
+ ```
205
+ ml:click, ml:change, ml:input, ml:open, ml:close, ml:select, ml:sort, etc.
206
+ ```
207
+
208
+ Listening in a Melodic template:
209
+
210
+ ```html
211
+ <ml-button @ml:click=${this.handleClick}>Save</ml-button>
212
+ <ml-input @ml:change=${this.handleChange}></ml-input>
213
+ <ml-select @ml:open=${this.onOpen} @ml:close=${this.onClose}></ml-select>
214
+ ```
215
+
216
+ ---
217
+
132
218
  ## Common Types
133
219
 
134
220
  ```ts
@@ -147,14 +233,6 @@ type ThemeMode = 'light' | 'dark' | 'system';
147
233
 
148
234
  ## Theme System
149
235
 
150
- Apply a built-in theme:
151
-
152
- ```ts
153
- import { applyTheme } from '@melodicdev/components/theme';
154
-
155
- applyTheme('light'); // or 'dark' or 'system'
156
- ```
157
-
158
236
  Override tokens globally via CSS:
159
237
 
160
238
  ```css