@rxap/ngx-theme 19.0.4-dev.0 → 19.1.0-dev.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 (75) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/README.md +85 -0
  3. package/compodoc/changelog.html +5 -0
  4. package/compodoc/dependencies.html +4 -4
  5. package/compodoc/index.html +69 -1
  6. package/compodoc/injectables/ThemeModeService.html +1256 -0
  7. package/compodoc/injectables/ThemeService.html +82 -265
  8. package/compodoc/interfaces/ColorPaletteConfig.html +6 -71
  9. package/compodoc/interfaces/ColorPaletteConfigWithName.html +6 -71
  10. package/compodoc/interfaces/ThemeConfig.html +6 -71
  11. package/compodoc/js/menu-wc.js +6 -0
  12. package/compodoc/js/menu-wc_es5.js +1 -1
  13. package/compodoc/js/search/search_index.js +2 -2
  14. package/compodoc/miscellaneous/typealiases.html +235 -0
  15. package/compodoc/miscellaneous/variables.html +32 -0
  16. package/compodoc/overview.html +1 -1
  17. package/compodoc/properties.html +1 -1
  18. package/docs/documentation.json +1672 -532
  19. package/docs/html/assets/hierarchy.js +1 -1
  20. package/docs/html/assets/highlight.css +28 -0
  21. package/docs/html/assets/navigation.js +1 -1
  22. package/docs/html/assets/search.js +1 -1
  23. package/docs/html/classes/ThemeModeService.html +35 -0
  24. package/docs/html/classes/ThemeService.html +4 -6
  25. package/docs/html/enums/ColorPaletteAlgorithm.html +2 -2
  26. package/docs/html/functions/ComputeColorPalette.html +1 -1
  27. package/docs/html/functions/ObserveCurrentThemeDensity.html +1 -1
  28. package/docs/html/functions/provideTheme.html +1 -1
  29. package/docs/html/hierarchy.html +1 -1
  30. package/docs/html/index.html +60 -2
  31. package/docs/html/interfaces/ColorPalette.html +2 -2
  32. package/docs/html/interfaces/ColorPaletteConfig.html +2 -2
  33. package/docs/html/interfaces/ColorPaletteConfigWithName.html +2 -2
  34. package/docs/html/interfaces/ThemeConfig.html +2 -2
  35. package/docs/html/modules.html +1 -1
  36. package/docs/html/types/ActiveTheme.html +1 -0
  37. package/docs/html/types/ThemeSetting.html +1 -0
  38. package/docs/html/variables/THEME_SETTING_KEY.html +1 -0
  39. package/docs/markdown/README.md +86 -1
  40. package/docs/markdown/classes/ThemeModeService.md +282 -0
  41. package/docs/markdown/classes/ThemeService.md +39 -69
  42. package/docs/markdown/enumerations/ColorPaletteAlgorithm.md +4 -4
  43. package/docs/markdown/functions/ComputeColorPalette.md +2 -2
  44. package/docs/markdown/functions/ObserveCurrentThemeDensity.md +2 -2
  45. package/docs/markdown/functions/provideTheme.md +2 -2
  46. package/docs/markdown/globals.md +12 -2
  47. package/docs/markdown/interfaces/ColorPalette.md +16 -16
  48. package/docs/markdown/interfaces/ColorPaletteConfig.md +5 -5
  49. package/docs/markdown/interfaces/ColorPaletteConfigWithName.md +6 -6
  50. package/docs/markdown/interfaces/ThemeConfig.md +7 -7
  51. package/docs/markdown/type-aliases/ActiveTheme.md +11 -0
  52. package/docs/markdown/type-aliases/ThemeSetting.md +11 -0
  53. package/docs/markdown/variables/THEME_SETTING_KEY.md +11 -0
  54. package/docs/wiki/Class.ThemeModeService.md +278 -0
  55. package/docs/wiki/Class.ThemeService.md +38 -68
  56. package/docs/wiki/Enumeration.ColorPaletteAlgorithm.md +3 -3
  57. package/docs/wiki/Function.ComputeColorPalette.md +1 -1
  58. package/docs/wiki/Function.ObserveCurrentThemeDensity.md +1 -1
  59. package/docs/wiki/Function.provideTheme.md +1 -1
  60. package/docs/wiki/Home.md +85 -0
  61. package/docs/wiki/Interface.ColorPalette.md +15 -15
  62. package/docs/wiki/Interface.ColorPaletteConfig.md +4 -4
  63. package/docs/wiki/Interface.ColorPaletteConfigWithName.md +5 -5
  64. package/docs/wiki/Interface.ThemeConfig.md +6 -6
  65. package/docs/wiki/TypeAlias.ActiveTheme.md +7 -0
  66. package/docs/wiki/TypeAlias.ThemeSetting.md +7 -0
  67. package/docs/wiki/Variable.THEME_SETTING_KEY.md +7 -0
  68. package/docs/wiki/_Sidebar.md +10 -0
  69. package/docs/wiki/globals.md +11 -1
  70. package/fesm2022/rxap-ngx-theme.mjs +142 -61
  71. package/fesm2022/rxap-ngx-theme.mjs.map +1 -1
  72. package/index.d.ts +1 -0
  73. package/lib/theme-mode.service.d.ts +61 -0
  74. package/lib/theme.service.d.ts +3 -5
  75. package/package.json +12 -12
@@ -1,4 +1,4 @@
1
- **@rxap/ngx-theme v19.0.4-dev.0**
1
+ **@rxap/ngx-theme v19.1.0-dev.0**
2
2
 
3
3
  ***
4
4
 
@@ -12,6 +12,7 @@ This package provides an Angular theme service that allows you to manage and cus
12
12
  ![NPM](https://img.shields.io/npm/l/@rxap/ngx-theme)
13
13
 
14
14
  - [Installation](#installation)
15
+ - [Guides](#guides)
15
16
  - [Generators](#generators)
16
17
  - [init](#init)
17
18
 
@@ -29,6 +30,90 @@ yarn add @angular/cdk @angular/core @rxap/config @rxap/ngx-pub-sub @rxap/rxjs @r
29
30
  ```bash
30
31
  yarn nx g @rxap/ngx-theme:init
31
32
  ```
33
+ # Guides
34
+
35
+ # Dark and Light mode with tailwind and angular material 3
36
+
37
+ This guide provides the setup steps for configuring Tailwind CSS and Angular Material for the light/dark/system theme switching mechanism, using the approaches we discussed previously.
38
+
39
+ ## 1. Configure Tailwind with the Variant Strategy
40
+
41
+ Update your tailwind.config.js to use the variant strategy. This allows Tailwind to react to both the system preference (prefers-color-scheme) and specific classes (.light, .dark) for manual overrides.
42
+
43
+ ```js
44
+ // tailwind.config.js
45
+ /** @type {import('tailwindcss').Config} */
46
+ module.exports = {
47
+ // ... other configurations
48
+ darkMode: 'selector',
49
+ theme: {
50
+ extend: {
51
+ // ... your theme extensions
52
+ },
53
+ },
54
+ plugins: [],
55
+ // ...
56
+ };
57
+ ```
58
+
59
+ This configuration tells Tailwind to apply dark: variants if EITHER the system preference is dark (and not overridden by .light) OR if the .dark class is explicitly set on an ancestor element.
60
+
61
+ ## 2. Integrate with Angular Material (Modern MDC Approach)
62
+
63
+ Use the modern Angular Material Sass API (mat.theme) to define your theme once and emit CSS variables. Then, use CSS to control the color-scheme property based on the .light and .dark classes applied by the ThemeService. Material components will react automatically to the computed color-scheme.
64
+
65
+ ```scss
66
+ @use '@angular/material' as mat;
67
+
68
+ html {
69
+ @include mat.theme((
70
+ color: mat.$violet-palette,
71
+ typography: Roboto,
72
+ density: 0
73
+ ));
74
+ }
75
+
76
+ // --- Tailwind Integration ---
77
+ @tailwind base;
78
+ @tailwind components;
79
+ @tailwind utilities;
80
+
81
+ // --- Color Scheme Control & Base Styles ---
82
+ html { // Setting on html or :root is fine
83
+ // Default: Let the browser choose light/dark based on system preference.
84
+ // Material components & Tailwind's media query variant will react to this.
85
+ color-scheme: light dark;
86
+
87
+ // Apply base background/text colors (Tailwind handles dark via variants).
88
+ // Add transitions for smoother switching.
89
+ @apply bg-white text-gray-800 transition-colors duration-200 ease-in-out;
90
+ }
91
+
92
+ // Force light mode when .light class is present on an ancestor (e.g., body)
93
+ // Use :where to keep specificity low, preventing conflicts.
94
+ :where(html.light, body.light, .light) {
95
+ color-scheme: light;
96
+ // Ensure light background/text if overriding system dark mode
97
+ @apply bg-white text-gray-800;
98
+ }
99
+
100
+ // Force dark mode when .dark class is present on an ancestor (e.g., body)
101
+ // Use :where to keep specificity low.
102
+ :where(html.dark, body.dark, .dark) {
103
+ color-scheme: dark;
104
+ // Apply dark background/text (complements Tailwind's dark: variants)
105
+ @apply bg-gray-900 text-gray-200;
106
+ }
107
+
108
+ // Other global styles can go here
109
+ body {
110
+ // Ensure body takes full height if needed, etc.
111
+ @apply min-h-screen m-0; // Added margin reset
112
+ }
113
+ ```
114
+
115
+ This setup provides the configuration for Tailwind and the recommended SCSS structure for Angular Material theming that integrates with the ThemeService managing the .light and .dark classes.
116
+
32
117
  # Generators
33
118
 
34
119
  ## init
@@ -0,0 +1,282 @@
1
+ [**@rxap/ngx-theme v19.1.0-dev.0**](../README.md)
2
+
3
+ ***
4
+
5
+ [@rxap/ngx-theme](../globals.md) / ThemeModeService
6
+
7
+ # Class: ThemeModeService
8
+
9
+ Defined in: [theme-mode.service.ts:46](https://gitlab.com/rxap/packages/-/blob/b32f110144dafee760d535d217a2855e77f154a5/packages/angular/theme/src/lib/theme-mode.service.ts#L46)
10
+
11
+ Service to manage theme mode (light/dark/system) for the application.
12
+ It provides functionality to handle theme preferences, persist them, and synchronize changes.
13
+
14
+ This service integrates with media queries to detect system-level theme changes and allows the user
15
+ or application logic to toggle or set a specific theme.
16
+
17
+ It utilizes dependency injection to access various required services and the document object.
18
+ Additionally, it publishes theme-related events for other parts of the application to react to
19
+ theme changes.
20
+
21
+ ## Implements
22
+
23
+ - `OnDestroy`
24
+
25
+ ## Constructors
26
+
27
+ ### new ThemeModeService()
28
+
29
+ > **new ThemeModeService**(`mediaMatcher`, `document`): [`ThemeModeService`](ThemeModeService.md)
30
+
31
+ Defined in: [theme-mode.service.ts:62](https://gitlab.com/rxap/packages/-/blob/b32f110144dafee760d535d217a2855e77f154a5/packages/angular/theme/src/lib/theme-mode.service.ts#L62)
32
+
33
+ #### Parameters
34
+
35
+ ##### mediaMatcher
36
+
37
+ `MediaMatcher`
38
+
39
+ ##### document
40
+
41
+ `Document`
42
+
43
+ #### Returns
44
+
45
+ [`ThemeModeService`](ThemeModeService.md)
46
+
47
+ ## Properties
48
+
49
+ ### activeTheme
50
+
51
+ > `readonly` **activeTheme**: `WritableSignal`\<[`ActiveTheme`](../type-aliases/ActiveTheme.md)\>
52
+
53
+ Defined in: [theme-mode.service.ts:51](https://gitlab.com/rxap/packages/-/blob/b32f110144dafee760d535d217a2855e77f154a5/packages/angular/theme/src/lib/theme-mode.service.ts#L51)
54
+
55
+ ***
56
+
57
+ ### config
58
+
59
+ > `readonly` **config**: `ConfigService`\<`any`\>
60
+
61
+ Defined in: [theme-mode.service.ts:48](https://gitlab.com/rxap/packages/-/blob/b32f110144dafee760d535d217a2855e77f154a5/packages/angular/theme/src/lib/theme-mode.service.ts#L48)
62
+
63
+ ***
64
+
65
+ ### darkColorSchemaMediaQuery
66
+
67
+ > `protected` `readonly` **darkColorSchemaMediaQuery**: `MediaQueryList`
68
+
69
+ Defined in: [theme-mode.service.ts:55](https://gitlab.com/rxap/packages/-/blob/b32f110144dafee760d535d217a2855e77f154a5/packages/angular/theme/src/lib/theme-mode.service.ts#L55)
70
+
71
+ ***
72
+
73
+ ### darkMode
74
+
75
+ > `readonly` **darkMode**: `Signal`\<`boolean`\>
76
+
77
+ Defined in: [theme-mode.service.ts:53](https://gitlab.com/rxap/packages/-/blob/b32f110144dafee760d535d217a2855e77f154a5/packages/angular/theme/src/lib/theme-mode.service.ts#L53)
78
+
79
+ ***
80
+
81
+ ### document
82
+
83
+ > `protected` `readonly` **document**: `Document`
84
+
85
+ Defined in: [theme-mode.service.ts:64](https://gitlab.com/rxap/packages/-/blob/b32f110144dafee760d535d217a2855e77f154a5/packages/angular/theme/src/lib/theme-mode.service.ts#L64)
86
+
87
+ ***
88
+
89
+ ### mediaMatcher
90
+
91
+ > `protected` `readonly` **mediaMatcher**: `MediaMatcher`
92
+
93
+ Defined in: [theme-mode.service.ts:63](https://gitlab.com/rxap/packages/-/blob/b32f110144dafee760d535d217a2855e77f154a5/packages/angular/theme/src/lib/theme-mode.service.ts#L63)
94
+
95
+ ***
96
+
97
+ ### mediaQueryListener()
98
+
99
+ > `protected` `readonly` **mediaQueryListener**: (`this`, `ev`) => `any`
100
+
101
+ Defined in: [theme-mode.service.ts:58](https://gitlab.com/rxap/packages/-/blob/b32f110144dafee760d535d217a2855e77f154a5/packages/angular/theme/src/lib/theme-mode.service.ts#L58)
102
+
103
+ #### Parameters
104
+
105
+ ##### this
106
+
107
+ `MediaQueryList`
108
+
109
+ ##### ev
110
+
111
+ `MediaQueryListEvent`
112
+
113
+ #### Returns
114
+
115
+ `any`
116
+
117
+ ***
118
+
119
+ ### pubSub
120
+
121
+ > `readonly` **pubSub**: `PubSubService`
122
+
123
+ Defined in: [theme-mode.service.ts:49](https://gitlab.com/rxap/packages/-/blob/b32f110144dafee760d535d217a2855e77f154a5/packages/angular/theme/src/lib/theme-mode.service.ts#L49)
124
+
125
+ ***
126
+
127
+ ### subscriptions
128
+
129
+ > `protected` `readonly` **subscriptions**: `null` \| `Subscription` = `null`
130
+
131
+ Defined in: [theme-mode.service.ts:57](https://gitlab.com/rxap/packages/-/blob/b32f110144dafee760d535d217a2855e77f154a5/packages/angular/theme/src/lib/theme-mode.service.ts#L57)
132
+
133
+ ***
134
+
135
+ ### syncSubscription?
136
+
137
+ > `protected` `optional` **syncSubscription**: `Subscription`
138
+
139
+ Defined in: [theme-mode.service.ts:60](https://gitlab.com/rxap/packages/-/blob/b32f110144dafee760d535d217a2855e77f154a5/packages/angular/theme/src/lib/theme-mode.service.ts#L60)
140
+
141
+ ***
142
+
143
+ ### themeSetting
144
+
145
+ > `readonly` **themeSetting**: `WritableSignal`\<[`ThemeSetting`](../type-aliases/ThemeSetting.md)\>
146
+
147
+ Defined in: [theme-mode.service.ts:52](https://gitlab.com/rxap/packages/-/blob/b32f110144dafee760d535d217a2855e77f154a5/packages/angular/theme/src/lib/theme-mode.service.ts#L52)
148
+
149
+ ## Methods
150
+
151
+ ### ngOnDestroy()
152
+
153
+ > **ngOnDestroy**(): `void`
154
+
155
+ Defined in: [theme-mode.service.ts:128](https://gitlab.com/rxap/packages/-/blob/b32f110144dafee760d535d217a2855e77f154a5/packages/angular/theme/src/lib/theme-mode.service.ts#L128)
156
+
157
+ Cleans up subscriptions and event listeners when the service is destroyed.
158
+
159
+ #### Returns
160
+
161
+ `void`
162
+
163
+ #### Implementation of
164
+
165
+ `OnDestroy.ngOnDestroy`
166
+
167
+ ***
168
+
169
+ ### removeThemeClasses()
170
+
171
+ > `protected` **removeThemeClasses**(): `void`
172
+
173
+ Defined in: [theme-mode.service.ts:148](https://gitlab.com/rxap/packages/-/blob/b32f110144dafee760d535d217a2855e77f154a5/packages/angular/theme/src/lib/theme-mode.service.ts#L148)
174
+
175
+ #### Returns
176
+
177
+ `void`
178
+
179
+ ***
180
+
181
+ ### restoreFromPubSub()
182
+
183
+ > `protected` **restoreFromPubSub**(): `void`
184
+
185
+ Defined in: [theme-mode.service.ts:108](https://gitlab.com/rxap/packages/-/blob/b32f110144dafee760d535d217a2855e77f154a5/packages/angular/theme/src/lib/theme-mode.service.ts#L108)
186
+
187
+ #### Returns
188
+
189
+ `void`
190
+
191
+ ***
192
+
193
+ ### restoreThemeSetting()
194
+
195
+ > `protected` **restoreThemeSetting**(): [`ThemeSetting`](../type-aliases/ThemeSetting.md)
196
+
197
+ Defined in: [theme-mode.service.ts:136](https://gitlab.com/rxap/packages/-/blob/b32f110144dafee760d535d217a2855e77f154a5/packages/angular/theme/src/lib/theme-mode.service.ts#L136)
198
+
199
+ #### Returns
200
+
201
+ [`ThemeSetting`](../type-aliases/ThemeSetting.md)
202
+
203
+ ***
204
+
205
+ ### setTheme()
206
+
207
+ > **setTheme**(`active`, `publish`?): `void`
208
+
209
+ Defined in: [theme-mode.service.ts:179](https://gitlab.com/rxap/packages/-/blob/b32f110144dafee760d535d217a2855e77f154a5/packages/angular/theme/src/lib/theme-mode.service.ts#L179)
210
+
211
+ Sets the active theme for the application and optionally publishes the change.
212
+
213
+ #### Parameters
214
+
215
+ ##### active
216
+
217
+ [`ActiveTheme`](../type-aliases/ActiveTheme.md)
218
+
219
+ The theme to be set as active.
220
+
221
+ ##### publish?
222
+
223
+ `boolean` = `true`
224
+
225
+ Indicates whether to publish the theme change event.
226
+
227
+ #### Returns
228
+
229
+ `void`
230
+
231
+ ***
232
+
233
+ ### setThemeClasses()
234
+
235
+ > `protected` **setThemeClasses**(`active`): `void`
236
+
237
+ Defined in: [theme-mode.service.ts:153](https://gitlab.com/rxap/packages/-/blob/b32f110144dafee760d535d217a2855e77f154a5/packages/angular/theme/src/lib/theme-mode.service.ts#L153)
238
+
239
+ #### Parameters
240
+
241
+ ##### active
242
+
243
+ [`ActiveTheme`](../type-aliases/ActiveTheme.md)
244
+
245
+ #### Returns
246
+
247
+ `void`
248
+
249
+ ***
250
+
251
+ ### storeThemeSetting()
252
+
253
+ > `protected` **storeThemeSetting**(`setting`): `void`
254
+
255
+ Defined in: [theme-mode.service.ts:144](https://gitlab.com/rxap/packages/-/blob/b32f110144dafee760d535d217a2855e77f154a5/packages/angular/theme/src/lib/theme-mode.service.ts#L144)
256
+
257
+ #### Parameters
258
+
259
+ ##### setting
260
+
261
+ [`ThemeSetting`](../type-aliases/ThemeSetting.md)
262
+
263
+ #### Returns
264
+
265
+ `void`
266
+
267
+ ***
268
+
269
+ ### toggleTheme()
270
+
271
+ > **toggleTheme**(): `void`
272
+
273
+ Defined in: [theme-mode.service.ts:164](https://gitlab.com/rxap/packages/-/blob/b32f110144dafee760d535d217a2855e77f154a5/packages/angular/theme/src/lib/theme-mode.service.ts#L164)
274
+
275
+ Toggles the application theme between 'light' and 'dark' modes.
276
+ It checks the currently active theme and switches to the opposite mode.
277
+
278
+ #### Returns
279
+
280
+ `void`
281
+
282
+ Does not return a value.