@m3e/theme 1.0.0-rc.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 (32) hide show
  1. package/LICENSE +22 -0
  2. package/README.md +92 -0
  3. package/cem.config.mjs +16 -0
  4. package/dist/css-custom-data.json +6 -0
  5. package/dist/custom-elements.json +349 -0
  6. package/dist/html-custom-data.json +48 -0
  7. package/dist/index.js +3711 -0
  8. package/dist/index.js.map +1 -0
  9. package/dist/index.min.js +347 -0
  10. package/dist/index.min.js.map +1 -0
  11. package/dist/src/ColorScheme.d.ts +3 -0
  12. package/dist/src/ColorScheme.d.ts.map +1 -0
  13. package/dist/src/ContrastLevel.d.ts +3 -0
  14. package/dist/src/ContrastLevel.d.ts.map +1 -0
  15. package/dist/src/MotionScheme.d.ts +3 -0
  16. package/dist/src/MotionScheme.d.ts.map +1 -0
  17. package/dist/src/ThemeElement.d.ts +101 -0
  18. package/dist/src/ThemeElement.d.ts.map +1 -0
  19. package/dist/src/ThemeVariant.d.ts +3 -0
  20. package/dist/src/ThemeVariant.d.ts.map +1 -0
  21. package/dist/src/index.d.ts +6 -0
  22. package/dist/src/index.d.ts.map +1 -0
  23. package/eslint.config.mjs +13 -0
  24. package/package.json +52 -0
  25. package/rollup.config.js +32 -0
  26. package/src/ColorScheme.ts +2 -0
  27. package/src/ContrastLevel.ts +2 -0
  28. package/src/MotionScheme.ts +2 -0
  29. package/src/ThemeElement.ts +284 -0
  30. package/src/ThemeVariant.ts +11 -0
  31. package/src/index.ts +5 -0
  32. package/tsconfig.json +9 -0
package/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 matraic
4
+ Contact: matraic@yahoo.com
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining a copy
7
+ of this software and associated documentation files (the "Software"), to deal
8
+ in the Software without restriction, including without limitation the rights
9
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
+ copies of the Software, and to permit persons to whom the Software is
11
+ furnished to do so, subject to the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be included in all
14
+ copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,92 @@
1
+ # @m3e/theme
2
+
3
+ The `m3e-theme` component is a non-visual element used to apply dynamic color, expressive motion, density, and strong focus indicators to nested, theme-aware elements.
4
+
5
+ When `m3e-theme` is nested directly beneath the `<body>` of a document, the `<body>`'s `background-color` is set to the computed value of `--md-sys-color-background` and `color` is set to the computed value of `--md-sys-color-on-background`. In addition the document's `scrollbar-color` is set to the computed values of `--m3e-scrollbar-thumb-color` and `--m3e-scrollbar-track-color` which, when supported, cascades to all viewport scrollbars.
6
+
7
+ > **Part of the [M3E](../../README.md) monorepo**
8
+ > This package is maintained within the unified M3E repository, which provides a suite of Material 3 web components.
9
+
10
+ ## ๐Ÿ“ฆ Installation
11
+
12
+ ```bash
13
+ npm install @m3e/theme
14
+ ```
15
+
16
+ ## ๐Ÿ’ป Editor Integration
17
+
18
+ This package includes a [Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest) to support enhanced editor tooling and developer experience.
19
+
20
+ ### Visual Studio Code
21
+
22
+ To enable autocomplete and hover documentation for `@m3e/theme`, install the [Custom Elements Manifest Language Server](https://marketplace.visualstudio.com/items?itemName=pwrs.cem-language-server-vscode) extension. It will automatically detect the manifest bundled with this package and surface tag names, attributes, slots, and events in supported files.
23
+
24
+ Alternately, you can explicitly reference the `html-custom-data.json` and `css-custom-data.json` in your workspace settings:
25
+
26
+ ```json
27
+ {
28
+ "html.customData": ["./node_modules/@m3e/theme/dist/html-custom-data.json"],
29
+ "css.customData": ["./node_modules/@m3e/theme/dist/css-custom-data.json"]
30
+ }
31
+ ```
32
+
33
+ ## ๐Ÿš€ Browser Usage
34
+
35
+ This package uses [JavaScript Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#module_specifiers). To use it directly in a browser without a bundler, use a module script similar to the following.
36
+
37
+ ```html
38
+ <script type="module" src="/node_modules/@m3e/theme/dist/index.js"></script>
39
+ ```
40
+
41
+ In addition, you must use an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap) to include dependencies.
42
+
43
+ ```html
44
+ <script type="importmap">
45
+ {
46
+ "imports": {
47
+ "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
48
+ "@m3e/core": "/node_modules/@m3e/core/dist/index.js"
49
+ }
50
+ }
51
+ </script>
52
+ ```
53
+
54
+ > For production, use index.min.js for faster load times.
55
+
56
+ ## ๐Ÿ—‚๏ธ Elements
57
+
58
+ - `m3e-theme` โ€” A non-visual element responsible for application-level theming.
59
+
60
+ ## ๐Ÿงช Examples
61
+
62
+ The following example adds a top-level `m3e-theme` directly beneath a document's `<body>` element to apply application-level theming. In this example, `color` and `scheme` are used to create a dynamic color palette which automatically adjusts to a user's light or dark color preference. In addition, expressive motion and strong focus indicators are enabled.
63
+
64
+ ```html
65
+ <body>
66
+ <m3e-theme color="#7D67BE" scheme="auto" motion="expressive" strong-focus>
67
+ <!-- App content here -->
68
+ </m3e-theme>
69
+ </body>
70
+ ```
71
+
72
+ ## ๐Ÿ“– API Reference
73
+
74
+ ### โš™๏ธ Attributes
75
+
76
+ | Attribute | Type | Default | Description |
77
+ | -------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------- |
78
+ | `color` | `string` | `"#7D67BE"` | The hex color from which to derive dynamic color palettes. |
79
+ | `variant` | `"monochrome" \| "neutral" \| "tonal-spot" \| "vibrant" \| "expressive" \| "fidelity" \| "rainbow" \| "fruit-salad" \| "content"` | `"vibrant"` | The color variant of the theme. |
80
+ | `scheme` | `"auto" \| "light" \| "dark"` | `"auto"` | The color scheme of the theme. |
81
+ | `contrast` | `"standard" \| "medium" \| "high"` | `"standard"` | The contrast level of the theme. |
82
+ | `strong-focus` | `boolean` | `false` | Whether to enable strong focus indicators. |
83
+ | `density` | `number` | `0` | The density scale (0, -1, -2). |
84
+ | `motion` | `"standard" \| "expressive"` | `"standard"` | The motion scheme. |
85
+
86
+ ## ๐Ÿค Contributing
87
+
88
+ See the root monorepo `CONTRIBUTING.md` for guidelines on contributing to this package.
89
+
90
+ ## ๐Ÿ“„ License
91
+
92
+ This package is licensed under the MIT License.
package/cem.config.mjs ADDED
@@ -0,0 +1,16 @@
1
+ import { customElementVsCodePlugin } from "custom-element-vs-code-integration";
2
+
3
+ export default {
4
+ globs: ["src/**/*.ts"],
5
+ exclude: ["src/**/*.spec.ts"],
6
+ packagejson: true,
7
+ outdir: "dist",
8
+ litelement: true,
9
+ plugins: [
10
+ customElementVsCodePlugin({
11
+ outdir: "dist",
12
+ htmlFileName: "html-custom-data.json",
13
+ cssFileName: "css-custom-data.json",
14
+ }),
15
+ ],
16
+ };
package/dist/css-custom-data.json ADDED
@@ -0,0 +1,6 @@
1
+ {
2
+ "$schema": "https://raw.githubusercontent.com/microsoft/vscode-css-languageservice/main/docs/customData.schema.json",
3
+ "version": 1.1,
4
+ "properties": [],
5
+ "pseudoElements": []
6
+ }
package/dist/custom-elements.json ADDED
@@ -0,0 +1,349 @@
1
+ {
2
+ "schemaVersion": "1.0.0",
3
+ "readme": "",
4
+ "modules": [
5
+ {
6
+ "kind": "javascript-module",
7
+ "path": "src/ColorScheme.ts",
8
+ "declarations": [],
9
+ "exports": []
10
+ },
11
+ {
12
+ "kind": "javascript-module",
13
+ "path": "src/ContrastLevel.ts",
14
+ "declarations": [],
15
+ "exports": []
16
+ },
17
+ {
18
+ "kind": "javascript-module",
19
+ "path": "src/index.ts",
20
+ "declarations": [],
21
+ "exports": [
22
+ {
23
+ "kind": "js",
24
+ "name": "*",
25
+ "declaration": {
26
+ "name": "*",
27
+ "package": "\"./ColorScheme\""
28
+ }
29
+ },
30
+ {
31
+ "kind": "js",
32
+ "name": "*",
33
+ "declaration": {
34
+ "name": "*",
35
+ "package": "\"./ContrastLevel\""
36
+ }
37
+ },
38
+ {
39
+ "kind": "js",
40
+ "name": "*",
41
+ "declaration": {
42
+ "name": "*",
43
+ "package": "\"./MotionScheme\""
44
+ }
45
+ },
46
+ {
47
+ "kind": "js",
48
+ "name": "*",
49
+ "declaration": {
50
+ "name": "*",
51
+ "package": "\"./ThemeElement\""
52
+ }
53
+ },
54
+ {
55
+ "kind": "js",
56
+ "name": "*",
57
+ "declaration": {
58
+ "name": "*",
59
+ "package": "\"./ThemeVariant\""
60
+ }
61
+ }
62
+ ]
63
+ },
64
+ {
65
+ "kind": "javascript-module",
66
+ "path": "src/MotionScheme.ts",
67
+ "declarations": [],
68
+ "exports": []
69
+ },
70
+ {
71
+ "kind": "javascript-module",
72
+ "path": "src/ThemeElement.ts",
73
+ "declarations": [
74
+ {
75
+ "kind": "class",
76
+ "description": "",
77
+ "name": "M3eThemeElement",
78
+ "members": [
79
+ {
80
+ "kind": "field",
81
+ "name": "#styleSheet",
82
+ "privacy": "private",
83
+ "default": "new CSSStyleSheet()"
84
+ },
85
+ {
86
+ "kind": "field",
87
+ "name": "#firstUpdated",
88
+ "privacy": "private",
89
+ "type": {
90
+ "text": "boolean"
91
+ },
92
+ "default": "false"
93
+ },
94
+ {
95
+ "kind": "field",
96
+ "name": "#light",
97
+ "privacy": "private",
98
+ "type": {
99
+ "text": "MediaQueryList | undefined"
100
+ }
101
+ },
102
+ {
103
+ "kind": "field",
104
+ "name": "#dark",
105
+ "privacy": "private",
106
+ "type": {
107
+ "text": "MediaQueryList | undefined"
108
+ }
109
+ },
110
+ {
111
+ "kind": "field",
112
+ "name": "#forcedColor",
113
+ "privacy": "private",
114
+ "type": {
115
+ "text": "MediaQueryList | undefined"
116
+ }
117
+ },
118
+ {
119
+ "kind": "field",
120
+ "name": "#colorSchemeChangeHandler",
121
+ "privacy": "private",
122
+ "readonly": true
123
+ },
124
+ {
125
+ "kind": "field",
126
+ "name": "color",
127
+ "type": {
128
+ "text": "string"
129
+ },
130
+ "default": "\"#7D67BE\"",
131
+ "description": "The hex color from which to derive dynamic color palettes.",
132
+ "attribute": "color"
133
+ },
134
+ {
135
+ "kind": "field",
136
+ "name": "variant",
137
+ "type": {
138
+ "text": "ThemeVariant"
139
+ },
140
+ "default": "\"vibrant\"",
141
+ "description": "The color variant of the theme.",
142
+ "attribute": "variant"
143
+ },
144
+ {
145
+ "kind": "field",
146
+ "name": "scheme",
147
+ "type": {
148
+ "text": "ColorScheme"
149
+ },
150
+ "default": "\"auto\"",
151
+ "description": "The color scheme of the theme.",
152
+ "attribute": "scheme"
153
+ },
154
+ {
155
+ "kind": "field",
156
+ "name": "contrast",
157
+ "type": {
158
+ "text": "ContrastLevel"
159
+ },
160
+ "default": "\"standard\"",
161
+ "description": "The contrast level of the theme.",
162
+ "attribute": "contrast"
163
+ },
164
+ {
165
+ "kind": "field",
166
+ "name": "strongFocus",
167
+ "type": {
168
+ "text": "boolean"
169
+ },
170
+ "default": "false",
171
+ "description": "Whether to enable strong focus indicators.",
172
+ "attribute": "strong-focus"
173
+ },
174
+ {
175
+ "kind": "field",
176
+ "name": "density",
177
+ "type": {
178
+ "text": "number"
179
+ },
180
+ "default": "0",
181
+ "description": "The density scale (0, -1, -2).",
182
+ "attribute": "density"
183
+ },
184
+ {
185
+ "kind": "field",
186
+ "name": "motion",
187
+ "type": {
188
+ "text": "MotionScheme"
189
+ },
190
+ "default": "\"standard\"",
191
+ "description": "The motion scheme.",
192
+ "attribute": "motion"
193
+ },
194
+ {
195
+ "kind": "field",
196
+ "name": "isDark",
197
+ "type": {
198
+ "text": "boolean"
199
+ },
200
+ "description": "Whether a dark theme is applied.",
201
+ "readonly": true
202
+ },
203
+ {
204
+ "kind": "method",
205
+ "name": "#apply",
206
+ "privacy": "private",
207
+ "return": {
208
+ "type": {
209
+ "text": "void"
210
+ }
211
+ }
212
+ },
213
+ {
214
+ "kind": "method",
215
+ "name": "#getVariant",
216
+ "privacy": "private",
217
+ "return": {
218
+ "type": {
219
+ "text": "number"
220
+ }
221
+ }
222
+ },
223
+ {
224
+ "kind": "method",
225
+ "name": "#getContrastLevel",
226
+ "privacy": "private",
227
+ "return": {
228
+ "type": {
229
+ "text": "number"
230
+ }
231
+ }
232
+ }
233
+ ],
234
+ "events": [
235
+ {
236
+ "name": "change",
237
+ "type": {
238
+ "text": "Event"
239
+ },
240
+ "description": "Dispatched when the theme changes."
241
+ }
242
+ ],
243
+ "attributes": [
244
+ {
245
+ "description": "The hex color from which to derive dynamic color palettes.",
246
+ "name": "color",
247
+ "type": {
248
+ "text": "string"
249
+ },
250
+ "default": "\"#7D67BE\"",
251
+ "fieldName": "color"
252
+ },
253
+ {
254
+ "description": "The contrast level of the theme.",
255
+ "name": "contrast",
256
+ "type": {
257
+ "text": "ContrastLevel"
258
+ },
259
+ "default": "\"standard\"",
260
+ "fieldName": "contrast"
261
+ },
262
+ {
263
+ "description": "The density scale (0, -1, -2).",
264
+ "name": "density",
265
+ "type": {
266
+ "text": "number"
267
+ },
268
+ "default": "0",
269
+ "fieldName": "density"
270
+ },
271
+ {
272
+ "description": "The color scheme of the theme.",
273
+ "name": "scheme",
274
+ "type": {
275
+ "text": "ColorScheme"
276
+ },
277
+ "default": "\"auto\"",
278
+ "fieldName": "scheme"
279
+ },
280
+ {
281
+ "description": "Whether to enable strong focus indicators.",
282
+ "name": "strong-focus",
283
+ "type": {
284
+ "text": "boolean"
285
+ },
286
+ "default": "false",
287
+ "fieldName": "strongFocus"
288
+ },
289
+ {
290
+ "description": "The color variant of the theme.",
291
+ "name": "variant",
292
+ "type": {
293
+ "text": "ThemeVariant"
294
+ },
295
+ "default": "\"vibrant\"",
296
+ "fieldName": "variant"
297
+ },
298
+ {
299
+ "name": "motion",
300
+ "type": {
301
+ "text": "MotionScheme"
302
+ },
303
+ "default": "\"standard\"",
304
+ "description": "The motion scheme.",
305
+ "fieldName": "motion"
306
+ }
307
+ ],
308
+ "mixins": [
309
+ {
310
+ "name": "Role",
311
+ "package": "@m3e/core"
312
+ }
313
+ ],
314
+ "superclass": {
315
+ "name": "LitElement",
316
+ "package": "lit"
317
+ },
318
+ "tagName": "m3e-theme",
319
+ "customElement": true,
320
+ "summary": "A non-visual element responsible for application-level theming."
321
+ }
322
+ ],
323
+ "exports": [
324
+ {
325
+ "kind": "js",
326
+ "name": "M3eThemeElement",
327
+ "declaration": {
328
+ "name": "M3eThemeElement",
329
+ "module": "src/ThemeElement.ts"
330
+ }
331
+ },
332
+ {
333
+ "kind": "custom-element-definition",
334
+ "name": "m3e-theme",
335
+ "declaration": {
336
+ "name": "M3eThemeElement",
337
+ "module": "src/ThemeElement.ts"
338
+ }
339
+ }
340
+ ]
341
+ },
342
+ {
343
+ "kind": "javascript-module",
344
+ "path": "src/ThemeVariant.ts",
345
+ "declarations": [],
346
+ "exports": []
347
+ }
348
+ ]
349
+ }
package/dist/html-custom-data.json ADDED
@@ -0,0 +1,48 @@
1
+ {
2
+ "$schema": "https://raw.githubusercontent.com/microsoft/vscode-html-languageservice/main/docs/customData.schema.json",
3
+ "version": 1.1,
4
+ "tags": [
5
+ {
6
+ "name": "m3e-theme",
7
+ "description": "A non-visual element responsible for application-level theming.\n---\n\n\n### **Events:**\n - **change** - Dispatched when the theme changes.",
8
+ "attributes": [
9
+ {
10
+ "name": "color",
11
+ "description": "The hex color from which to derive dynamic color palettes.",
12
+ "values": []
13
+ },
14
+ {
15
+ "name": "contrast",
16
+ "description": "The contrast level of the theme.",
17
+ "values": [{ "name": "ContrastLevel" }]
18
+ },
19
+ {
20
+ "name": "density",
21
+ "description": "The density scale (0, -1, -2).",
22
+ "values": []
23
+ },
24
+ {
25
+ "name": "scheme",
26
+ "description": "The color scheme of the theme.",
27
+ "values": [{ "name": "ColorScheme" }]
28
+ },
29
+ {
30
+ "name": "strong-focus",
31
+ "description": "Whether to enable strong focus indicators.",
32
+ "values": []
33
+ },
34
+ {
35
+ "name": "variant",
36
+ "description": "The color variant of the theme.",
37
+ "values": [{ "name": "ThemeVariant" }]
38
+ },
39
+ {
40
+ "name": "motion",
41
+ "description": "The motion scheme.",
42
+ "values": [{ "name": "MotionScheme" }]
43
+ }
44
+ ],
45
+ "references": []
46
+ }
47
+ ]
48
+ }