brix-runtime-sdk-api-web 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 (135) hide show
  1. package/dist/index.js +190 -0
  2. package/dist/types/api-exports.test.d.ts +33 -0
  3. package/dist/types/api-exports.test.d.ts.map +1 -0
  4. package/dist/types/context/RuntimeContext.d.ts +69 -0
  5. package/dist/types/context/RuntimeContext.d.ts.map +1 -0
  6. package/dist/types/context/index.d.ts +23 -0
  7. package/dist/types/context/index.d.ts.map +1 -0
  8. package/dist/types/index.d.ts +52 -0
  9. package/dist/types/index.d.ts.map +1 -0
  10. package/dist/types/types/auth.d.ts +405 -0
  11. package/dist/types/types/auth.d.ts.map +1 -0
  12. package/dist/types/types/capability.d.ts +218 -0
  13. package/dist/types/types/capability.d.ts.map +1 -0
  14. package/dist/types/types/common.d.ts +99 -0
  15. package/dist/types/types/common.d.ts.map +1 -0
  16. package/dist/types/types/config.d.ts +85 -0
  17. package/dist/types/types/config.d.ts.map +1 -0
  18. package/dist/types/types/event.d.ts +658 -0
  19. package/dist/types/types/event.d.ts.map +1 -0
  20. package/dist/types/types/http.d.ts +132 -0
  21. package/dist/types/types/http.d.ts.map +1 -0
  22. package/dist/types/types/i18n.d.ts +327 -0
  23. package/dist/types/types/i18n.d.ts.map +1 -0
  24. package/dist/types/types/index.d.ts +61 -0
  25. package/dist/types/types/index.d.ts.map +1 -0
  26. package/dist/types/types/layout.d.ts +301 -0
  27. package/dist/types/types/layout.d.ts.map +1 -0
  28. package/dist/types/types/module.d.ts +78 -0
  29. package/dist/types/types/module.d.ts.map +1 -0
  30. package/dist/types/types/navigation.d.ts +295 -0
  31. package/dist/types/types/navigation.d.ts.map +1 -0
  32. package/dist/types/types/plugin-loader-capability.d.ts +142 -0
  33. package/dist/types/types/plugin-loader-capability.d.ts.map +1 -0
  34. package/dist/types/types/plugin.d.ts +250 -0
  35. package/dist/types/types/plugin.d.ts.map +1 -0
  36. package/dist/types/types/state.d.ts +306 -0
  37. package/dist/types/types/state.d.ts.map +1 -0
  38. package/dist/types/types/theme.d.ts +279 -0
  39. package/dist/types/types/theme.d.ts.map +1 -0
  40. package/dist/types/types/ui/adapter.d.ts +181 -0
  41. package/dist/types/types/ui/adapter.d.ts.map +1 -0
  42. package/dist/types/types/ui/avatar.d.ts +102 -0
  43. package/dist/types/types/ui/avatar.d.ts.map +1 -0
  44. package/dist/types/types/ui/badge.d.ts +101 -0
  45. package/dist/types/types/ui/badge.d.ts.map +1 -0
  46. package/dist/types/types/ui/button.d.ts +135 -0
  47. package/dist/types/types/ui/button.d.ts.map +1 -0
  48. package/dist/types/types/ui/card.d.ts +105 -0
  49. package/dist/types/types/ui/card.d.ts.map +1 -0
  50. package/dist/types/types/ui/common.d.ts +29 -0
  51. package/dist/types/types/ui/common.d.ts.map +1 -0
  52. package/dist/types/types/ui/icon.d.ts +78 -0
  53. package/dist/types/types/ui/icon.d.ts.map +1 -0
  54. package/dist/types/types/ui/index.d.ts +59 -0
  55. package/dist/types/types/ui/index.d.ts.map +1 -0
  56. package/dist/types/types/ui/input.d.ts +200 -0
  57. package/dist/types/types/ui/input.d.ts.map +1 -0
  58. package/dist/types/types/ui/menu.d.ts +211 -0
  59. package/dist/types/types/ui/menu.d.ts.map +1 -0
  60. package/dist/types/types/ui/message.d.ts +121 -0
  61. package/dist/types/types/ui/message.d.ts.map +1 -0
  62. package/dist/types/types/ui/modal.d.ts +167 -0
  63. package/dist/types/types/ui/modal.d.ts.map +1 -0
  64. package/dist/types/types/ui/select.d.ts +213 -0
  65. package/dist/types/types/ui/select.d.ts.map +1 -0
  66. package/dist/types/types/ui/theme-tokens.d.ts +226 -0
  67. package/dist/types/types/ui/theme-tokens.d.ts.map +1 -0
  68. package/dist/types/types/ui/tooltip.d.ts +98 -0
  69. package/dist/types/types/ui/tooltip.d.ts.map +1 -0
  70. package/dist/types/types/ui.d.ts +49 -0
  71. package/dist/types/types/ui.d.ts.map +1 -0
  72. package/package.json +34 -0
  73. package/src/api-exports.test.ts +199 -0
  74. package/src/context/RuntimeContext.d.ts +69 -0
  75. package/src/context/RuntimeContext.d.ts.map +1 -0
  76. package/src/context/RuntimeContext.ts +75 -0
  77. package/src/context/index.d.ts +23 -0
  78. package/src/context/index.d.ts.map +1 -0
  79. package/src/context/index.ts +23 -0
  80. package/src/index.d.ts +52 -0
  81. package/src/index.d.ts.map +1 -0
  82. package/src/index.ts +59 -0
  83. package/src/types/auth.d.ts +146 -0
  84. package/src/types/auth.d.ts.map +1 -0
  85. package/src/types/auth.ts +479 -0
  86. package/src/types/capability.d.ts +218 -0
  87. package/src/types/capability.d.ts.map +1 -0
  88. package/src/types/capability.ts +302 -0
  89. package/src/types/common.d.ts +99 -0
  90. package/src/types/common.d.ts.map +1 -0
  91. package/src/types/common.ts +115 -0
  92. package/src/types/config.d.ts +64 -0
  93. package/src/types/config.d.ts.map +1 -0
  94. package/src/types/config.ts +96 -0
  95. package/src/types/event.d.ts +206 -0
  96. package/src/types/event.d.ts.map +1 -0
  97. package/src/types/event.ts +776 -0
  98. package/src/types/http.d.ts +132 -0
  99. package/src/types/http.d.ts.map +1 -0
  100. package/src/types/http.ts +156 -0
  101. package/src/types/i18n.ts +420 -0
  102. package/src/types/index.d.ts +50 -0
  103. package/src/types/index.d.ts.map +1 -0
  104. package/src/types/index.ts +120 -0
  105. package/src/types/layout.ts +394 -0
  106. package/src/types/module.d.ts +78 -0
  107. package/src/types/module.d.ts.map +1 -0
  108. package/src/types/module.ts +92 -0
  109. package/src/types/navigation.d.ts +101 -0
  110. package/src/types/navigation.d.ts.map +1 -0
  111. package/src/types/navigation.ts +361 -0
  112. package/src/types/plugin-loader-capability.ts +159 -0
  113. package/src/types/plugin.d.ts +250 -0
  114. package/src/types/plugin.d.ts.map +1 -0
  115. package/src/types/plugin.ts +344 -0
  116. package/src/types/state.d.ts +119 -0
  117. package/src/types/state.d.ts.map +1 -0
  118. package/src/types/state.ts +366 -0
  119. package/src/types/theme.ts +378 -0
  120. package/src/types/ui/adapter.ts +222 -0
  121. package/src/types/ui/avatar.ts +113 -0
  122. package/src/types/ui/badge.ts +112 -0
  123. package/src/types/ui/button.ts +148 -0
  124. package/src/types/ui/card.ts +116 -0
  125. package/src/types/ui/common.ts +29 -0
  126. package/src/types/ui/icon.ts +85 -0
  127. package/src/types/ui/index.ts +78 -0
  128. package/src/types/ui/input.ts +225 -0
  129. package/src/types/ui/menu.ts +237 -0
  130. package/src/types/ui/message.ts +135 -0
  131. package/src/types/ui/modal.ts +188 -0
  132. package/src/types/ui/select.ts +239 -0
  133. package/src/types/ui/theme-tokens.ts +357 -0
  134. package/src/types/ui/tooltip.ts +120 -0
  135. package/src/types/ui.ts +49 -0
@@ -0,0 +1,306 @@
1
+ /**
2
+ * Copyright 2026 Brix Platform Authors
3
+ *
4
+ * Licensed under the Apache License, Version 2.0 (the "License");
5
+ * you may not use this file except in compliance with the License.
6
+ * You may obtain a copy of the License at
7
+ *
8
+ * http://www.apache.org/licenses/LICENSE-2.0
9
+ *
10
+ * Unless required by applicable law or agreed to in writing, software
11
+ * distributed under the License is distributed on an "AS IS" BASIS,
12
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ * See the License for the specific language governing permissions and
14
+ * limitations under the License.
15
+ */
16
+ /**
17
+ * @file State-Related Type Definitions
18
+ * @description Defines core types for the state management system, including state change events, listeners, etc.
19
+ * @module @brix/runtime-sdk-api-web/types/state
20
+ * @version 3.2.0
21
+ *
22
+ * [v3.2 Changes]
23
+ * Extracted from index.ts into a standalone type file, and promoted common contracts from infra-adapter-state-web.
24
+ *
25
+ * [v3.2.0 Phase 1 Contract Layer Fix]
26
+ * Added types required by PluginStateCapabilityImpl:
27
+ * - StatePersistenceOptions: State persistence options
28
+ * - PluginStateChangeEvent: Plugin state change event
29
+ * - PluginStateSubscribeOptions: Plugin state subscribe options
30
+ * - PluginStateCapability interface extension: get/set new method signatures
31
+ *
32
+ * [Design Principles]
33
+ * - Define common state management contracts, state adapters implement specific storage logic
34
+ * - Support namespace isolation (each plugin has independent state space)
35
+ * - Support state change subscription
36
+ */
37
+ /**
38
+ * Plugin State Storage Structure
39
+ *
40
+ * <p>Top level partitioned by plugin ID, each plugin has independent state namespace.</p>
41
+ *
42
+ * <h3>Namespace Isolation Mechanism</h3>
43
+ * <ul>
44
+ * <li>booking plugin: state.booking.*</li>
45
+ * <li>identity plugin: state.identity.*</li>
46
+ * </ul>
47
+ * <p>Plugin A cannot directly read/write Plugin B's state.</p>
48
+ */
49
+ export interface PluginStoreState {
50
+ /** State partitioned by plugin ID */
51
+ [pluginId: string]: Record<string, unknown>;
52
+ }
53
+ /**
54
+ * State Change Event
55
+ *
56
+ * <p>Describes details of state changes, used for observability and debugging.</p>
57
+ */
58
+ export interface StateChangeEvent {
59
+ /** Plugin ID */
60
+ readonly pluginId: string;
61
+ /** State key */
62
+ readonly key: string;
63
+ /** Old value */
64
+ readonly oldValue: unknown;
65
+ /** New value */
66
+ readonly newValue: unknown;
67
+ /** Timestamp */
68
+ readonly timestamp?: number;
69
+ }
70
+ /**
71
+ * State Change Listener
72
+ */
73
+ export type StateChangeListener = (event: StateChangeEvent) => void;
74
+ /**
75
+ * State Persistence Options
76
+ *
77
+ * <p>Controls state persistence behavior.</p>
78
+ *
79
+ * @since 3.2.0
80
+ */
81
+ export interface StatePersistenceOptions {
82
+ /**
83
+ * Whether to Persist to Local Storage
84
+ *
85
+ * @default false
86
+ */
87
+ readonly persist?: boolean;
88
+ /**
89
+ * Storage Location
90
+ *
91
+ * - 'localStorage': Persistent storage, retained after browser closes
92
+ * - 'sessionStorage': Session storage, cleared after browser closes
93
+ *
94
+ * @default 'localStorage'
95
+ */
96
+ readonly storage?: 'localStorage' | 'sessionStorage';
97
+ /**
98
+ * Expiration Time (milliseconds)
99
+ *
100
+ * <p>When set, state will be automatically cleared after the specified time.</p>
101
+ */
102
+ readonly ttl?: number;
103
+ /**
104
+ * Serializer Name
105
+ *
106
+ * <p>Used for custom serialization/deserialization logic.</p>
107
+ */
108
+ readonly serializer?: string;
109
+ }
110
+ /**
111
+ * Plugin State Change Event
112
+ *
113
+ * <p>Describes details of plugin state changes. Similar to StateChangeEvent,
114
+ * but specifically for plugin state subscription callbacks.</p>
115
+ *
116
+ * @since 3.2.0
117
+ */
118
+ export interface PluginStateChangeEvent<T = unknown> {
119
+ /** State key (without namespace prefix) */
120
+ readonly key: string;
121
+ /** Full state key (with namespace prefix) */
122
+ readonly fullKey: string;
123
+ /** Plugin ID */
124
+ readonly pluginId: string;
125
+ /** New value */
126
+ readonly value: T;
127
+ /** Previous value */
128
+ readonly previousValue?: T;
129
+ /** Change timestamp */
130
+ readonly timestamp: number;
131
+ }
132
+ /**
133
+ * Plugin State Subscribe Options
134
+ *
135
+ * <p>Configuration parameters controlling state subscription behavior.</p>
136
+ *
137
+ * @since 3.2.0
138
+ */
139
+ export interface PluginStateSubscribeOptions {
140
+ /**
141
+ * Whether to Fire Callback Immediately
142
+ *
143
+ * <p>If true, the callback function will be called immediately on subscription with the current value.</p>
144
+ *
145
+ * @default false
146
+ */
147
+ readonly fireImmediately?: boolean;
148
+ /**
149
+ * Equality Comparison Function
150
+ *
151
+ * <p>Used to determine if old and new values are equal, returns true if equal (no callback triggered).</p>
152
+ */
153
+ readonly equalityFn?: (a: unknown, b: unknown) => boolean;
154
+ }
155
+ /**
156
+ * Plugin State Capability Type Identifier
157
+ */
158
+ export declare const PluginStateCapabilityType: unique symbol;
159
+ /**
160
+ * Plugin State Capability Contract
161
+ *
162
+ * <p>Provides isolated state management capability for plugins, replacing direct use of localStorage/sessionStorage/zustand.</p>
163
+ *
164
+ * <h3>Usage Example</h3>
165
+ * ```typescript
166
+ * const state = context.getCapability<PluginStateCapability>(PluginStateCapabilityType);
167
+ * state.set('selectedDate', new Date());
168
+ * const date = state.get<Date>('selectedDate');
169
+ *
170
+ * // Subscribe to state changes
171
+ * const unsubscribe = state.subscribe('selectedDate', (value) => {
172
+ * console.log('Date changed:', value);
173
+ * });
174
+ * ```
175
+ *
176
+ * <h3>Architectural Notes</h3>
177
+ * <ul>
178
+ * <li>Each plugin's state is in an independent namespace</li>
179
+ * <li>Cross-plugin state sharing through EventBus</li>
180
+ * <li>Direct access to other plugins' state is prohibited</li>
181
+ * </ul>
182
+ *
183
+ * @since 3.2.0 Extended methods: get/set, delete, has, getOrDefault, update, reset, keys, getAll, setMany
184
+ */
185
+ export interface PluginStateCapability {
186
+ /**
187
+ * Get State Value
188
+ *
189
+ * @param key State key
190
+ * @returns State value, returns undefined if not exists
191
+ */
192
+ get<T>(key: string): T | undefined;
193
+ /**
194
+ * Set State Value
195
+ *
196
+ * @param key State key
197
+ * @param value State value
198
+ * @param options Persistence options
199
+ */
200
+ set<T>(key: string, value: T, options?: StatePersistenceOptions): void;
201
+ /**
202
+ * Delete State
203
+ *
204
+ * @param key State key
205
+ * @returns Whether deletion succeeded
206
+ * @since 3.2.0
207
+ */
208
+ delete?(key: string): boolean;
209
+ /**
210
+ * Check If State Exists
211
+ *
212
+ * @param key State key
213
+ * @returns Whether exists
214
+ * @since 3.2.0
215
+ */
216
+ has?(key: string): boolean;
217
+ /**
218
+ * Get State Value (With Default)
219
+ *
220
+ * @param key State key
221
+ * @param defaultValue Default value
222
+ * @returns State value or default value
223
+ * @since 3.2.0
224
+ */
225
+ getOrDefault?<T>(key: string, defaultValue: T): T;
226
+ /**
227
+ * Update State Value
228
+ *
229
+ * @param key State key
230
+ * @param updater Update function
231
+ * @since 3.2.0
232
+ */
233
+ update?<T>(key: string, updater: (currentValue: T | undefined) => T): void;
234
+ /**
235
+ * Reset All Plugin State
236
+ *
237
+ * @since 3.2.0
238
+ */
239
+ reset?(): void;
240
+ /**
241
+ * Get All State Keys
242
+ *
243
+ * @returns Array of state keys
244
+ * @since 3.2.0
245
+ */
246
+ keys?(): string[];
247
+ /**
248
+ * Get All State
249
+ *
250
+ * @returns State object
251
+ * @since 3.2.0
252
+ */
253
+ getAll?<T extends Record<string, unknown> = Record<string, unknown>>(): T;
254
+ /**
255
+ * Batch Set State
256
+ *
257
+ * @param states State object
258
+ * @since 3.2.0
259
+ */
260
+ setMany?(states: Record<string, unknown>): void;
261
+ /**
262
+ * Subscribe to State Changes
263
+ *
264
+ * @param key State key
265
+ * @param listener Change listener
266
+ * @param options Subscribe options
267
+ * @returns Unsubscribe function
268
+ */
269
+ subscribe<T>(key: string, listener: (value: T, event?: PluginStateChangeEvent<T>) => void, options?: PluginStateSubscribeOptions): () => void;
270
+ /**
271
+ * Selective State Change Subscription
272
+ *
273
+ * @param selector Selector function
274
+ * @param listener Change listener
275
+ * @returns Unsubscribe function
276
+ * @since 3.2.0
277
+ */
278
+ select?<T>(selector: (state: Record<string, unknown>) => T, listener: (value: T, previousValue: T | undefined) => void): () => void;
279
+ /**
280
+ * Destroy Capability Instance
281
+ *
282
+ * @since 3.2.0
283
+ */
284
+ destroy?(): void;
285
+ }
286
+ /**
287
+ * State Store Capability Type Identifier (Compatibility Alias)
288
+ *
289
+ * <p>Alias aligned with Java StateStoreCapability naming.
290
+ * New code should use PluginStateCapability, this alias is for migration compatibility.</p>
291
+ *
292
+ * @since 3.2.0
293
+ * @see PluginStateCapabilityType
294
+ */
295
+ export declare const StateStoreCapabilityType: symbol;
296
+ /**
297
+ * State Store Capability (Compatibility Alias)
298
+ *
299
+ * <p>Alias aligned with Java StateStoreCapability naming.
300
+ * New code should use PluginStateCapability, this alias is for migration compatibility.</p>
301
+ *
302
+ * @since 3.2.0
303
+ * @see PluginStateCapability
304
+ */
305
+ export type StateStoreCapability = PluginStateCapability;
306
+ //# sourceMappingURL=state.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/types/state.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,279 @@
1
+ /**
2
+ * Copyright 2026 Brix Platform Authors
3
+ *
4
+ * Licensed under the Apache License, Version 2.0 (the "License");
5
+ * you may not use this file except in compliance with the License.
6
+ * You may obtain a copy of the License at
7
+ *
8
+ * http://www.apache.org/licenses/LICENSE-2.0
9
+ *
10
+ * Unless required by applicable law or agreed to in writing, software
11
+ * distributed under the License is distributed on an "AS IS" BASIS,
12
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ * See the License for the specific language governing permissions and
14
+ * limitations under the License.
15
+ */
16
+ /**
17
+ * @file Theme Capability Type Definitions
18
+ * @description Defines core types for the theme system, including theme mode, color configuration, theme switching, etc.
19
+ * @module @brix/runtime-sdk-api-web/types/theme
20
+ * @version 3.2.0
21
+ *
22
+ * [v3.2.0 Addition]
23
+ * Phase 1 contract layer fix: elevated ThemeCapability interface from shell-web to runtime-sdk-api-web.
24
+ *
25
+ * [Design Principles]
26
+ * - Theme variables are implemented via CSS variables, ensuring runtime switchability
27
+ * - Plugins cannot directly modify global styles, only through ThemeCapability
28
+ * - Theme switching notifies all modules via events
29
+ * - Hardcoding color values in components is prohibited
30
+ *
31
+ * [Architectural Constraints]
32
+ * ❌ Do not directly manipulate document.documentElement.style
33
+ * ❌ Do not hardcode color values
34
+ * ❌ Do not directly use localStorage to store theme preferences
35
+ * ✅ Operate theme through ThemeCapability or useTheme hook
36
+ */
37
+ import type { Unsubscribe } from './event';
38
+ /**
39
+ * Theme Mode
40
+ *
41
+ * - 'light': Light mode
42
+ * - 'dark': Dark mode
43
+ * - 'system': Follow system settings
44
+ */
45
+ export type ThemeMode = 'light' | 'dark' | 'system';
46
+ /**
47
+ * Theme Color Configuration
48
+ *
49
+ * <p>Defines the core color variables for the theme.</p>
50
+ */
51
+ export interface ThemeColors {
52
+ /** Primary Color - Used for main buttons, links, highlighted elements */
53
+ readonly primary: string;
54
+ /** Secondary Color - Used for backgrounds, borders, auxiliary elements */
55
+ readonly secondary: string;
56
+ /** Tertiary Color - Used for page backgrounds, card backgrounds */
57
+ readonly tertiary?: string;
58
+ /** Success color */
59
+ readonly success: string;
60
+ /** Warning color */
61
+ readonly warning: string;
62
+ /** Error color */
63
+ readonly error: string;
64
+ /** Info color */
65
+ readonly info: string;
66
+ /** Primary text color */
67
+ readonly textPrimary?: string;
68
+ /** Secondary text color */
69
+ readonly textSecondary?: string;
70
+ /** Disabled text color */
71
+ readonly textDisabled?: string;
72
+ /** Default background color */
73
+ readonly backgroundDefault?: string;
74
+ /** Paper/card background color */
75
+ readonly backgroundPaper?: string;
76
+ /** Border color */
77
+ readonly border?: string;
78
+ /** Divider color */
79
+ readonly divider?: string;
80
+ }
81
+ /**
82
+ * Theme Configuration
83
+ *
84
+ * <p>Complete theme configuration, including colors and other style parameters.</p>
85
+ */
86
+ export interface ThemeConfig {
87
+ /** Color configuration */
88
+ readonly colors: ThemeColors;
89
+ /** Font family */
90
+ readonly fontFamily?: string;
91
+ /** Base font size */
92
+ readonly fontSize?: number;
93
+ /** Border radius base */
94
+ readonly borderRadius?: number;
95
+ /** Spacing base */
96
+ readonly spacing?: number;
97
+ /** Shadow configuration */
98
+ readonly shadows?: {
99
+ readonly sm?: string;
100
+ readonly md?: string;
101
+ readonly lg?: string;
102
+ };
103
+ /** Whether to use system font */
104
+ readonly useSystemFont?: boolean;
105
+ }
106
+ /**
107
+ * Theme Preset
108
+ *
109
+ * <p>Predefined theme configurations for quick switching.</p>
110
+ */
111
+ export interface ThemePreset {
112
+ /** Preset ID */
113
+ readonly id: string;
114
+ /** Preset name */
115
+ readonly name: string;
116
+ /** Preset description */
117
+ readonly description?: string;
118
+ /** Light mode configuration */
119
+ readonly light: ThemeConfig;
120
+ /** Dark mode configuration */
121
+ readonly dark: ThemeConfig;
122
+ }
123
+ /**
124
+ * Theme State
125
+ *
126
+ * <p>Describes the complete state of the current theme.</p>
127
+ */
128
+ export interface ThemeState {
129
+ /** User selected theme mode */
130
+ readonly mode: ThemeMode;
131
+ /** Actual resolved theme mode (system resolves to light or dark) */
132
+ readonly resolvedMode: 'light' | 'dark';
133
+ /** Current theme configuration */
134
+ readonly config: ThemeConfig;
135
+ /** Current preset ID (if using preset) */
136
+ readonly presetId?: string;
137
+ }
138
+ /**
139
+ * Theme Change Event
140
+ *
141
+ * <p>Triggered when theme mode or configuration changes.</p>
142
+ */
143
+ export interface ThemeChangeEvent {
144
+ /** New theme mode */
145
+ readonly mode: ThemeMode;
146
+ /** New resolved mode */
147
+ readonly resolvedMode: 'light' | 'dark';
148
+ /** Previous theme mode */
149
+ readonly previousMode: ThemeMode;
150
+ /** New theme configuration */
151
+ readonly config: ThemeConfig;
152
+ /** Change source */
153
+ readonly source: 'user' | 'system' | 'api';
154
+ /** Change timestamp */
155
+ readonly timestamp: number;
156
+ }
157
+ /**
158
+ * Theme Change Handler
159
+ */
160
+ export type ThemeChangeHandler = (event: ThemeChangeEvent) => void;
161
+ /**
162
+ * Theme Capability Type Identifier
163
+ */
164
+ export declare const ThemeCapabilityType: unique symbol;
165
+ /**
166
+ * Theme Capability Contract
167
+ *
168
+ * <p>Provides theme management capability for plugins, including mode switching, color retrieval, theme configuration, etc.</p>
169
+ *
170
+ * <h3>Design Principles</h3>
171
+ * <ul>
172
+ * <li>Theme is uniformly controlled by Host</li>
173
+ * <li>Plugins can only read theme or request switching</li>
174
+ * <li>Theme variables are automatically applied via CSS variables</li>
175
+ * </ul>
176
+ *
177
+ * <h3>Usage Example</h3>
178
+ * ```typescript
179
+ * const theme = context.getCapability<ThemeCapability>(ThemeCapabilityType);
180
+ *
181
+ * // Get current mode
182
+ * const mode = theme.getMode();
183
+ *
184
+ * // Switch mode
185
+ * theme.setMode('dark');
186
+ * theme.toggleMode();
187
+ *
188
+ * // Get color
189
+ * const primaryColor = theme.getColor('primary');
190
+ *
191
+ * // Listen to theme changes
192
+ * const unsubscribe = theme.onThemeChange((event) => {
193
+ * console.log(`Theme switched to ${event.resolvedMode}`);
194
+ * });
195
+ * ```
196
+ *
197
+ * @since 3.2.0
198
+ */
199
+ export interface ThemeCapability {
200
+ /**
201
+ * Get Current Theme Mode
202
+ *
203
+ * @returns Theme mode
204
+ */
205
+ getMode(): ThemeMode;
206
+ /**
207
+ * Get Actual Resolved Theme Mode
208
+ *
209
+ * <p>When mode='system', returns actual 'light' or 'dark'.</p>
210
+ *
211
+ * @returns Resolved mode
212
+ */
213
+ getResolvedMode(): 'light' | 'dark';
214
+ /**
215
+ * Set Theme Mode
216
+ *
217
+ * @param mode Target mode
218
+ */
219
+ setMode(mode: ThemeMode): void;
220
+ /**
221
+ * Toggle Light/Dark Mode
222
+ *
223
+ * <p>Toggles between light and dark. If current is system, switches to the opposite of current system mode.</p>
224
+ */
225
+ toggleMode(): void;
226
+ /**
227
+ * Get Current Theme Configuration
228
+ *
229
+ * @returns Theme configuration object
230
+ */
231
+ getConfig(): ThemeConfig;
232
+ /**
233
+ * Get Specified Color Value
234
+ *
235
+ * @param colorKey Color key name
236
+ * @returns Color value (CSS format)
237
+ */
238
+ getColor(colorKey: keyof ThemeColors): string;
239
+ /**
240
+ * Get CSS Variable Value
241
+ *
242
+ * @param varName CSS variable name (without --)
243
+ * @returns Variable value
244
+ */
245
+ getCssVar?(varName: string): string;
246
+ /**
247
+ * Get Complete Theme State
248
+ *
249
+ * @returns Theme state object
250
+ */
251
+ getState?(): ThemeState;
252
+ /**
253
+ * Get Available Preset List
254
+ *
255
+ * @returns Array of presets
256
+ */
257
+ getPresets?(): ThemePreset[];
258
+ /**
259
+ * Apply Specified Preset
260
+ *
261
+ * @param presetId Preset ID
262
+ * @returns Whether successful
263
+ */
264
+ applyPreset?(presetId: string): boolean;
265
+ /**
266
+ * Get Current Preset ID
267
+ *
268
+ * @returns Preset ID, returns undefined when not using preset
269
+ */
270
+ getCurrentPresetId?(): string | undefined;
271
+ /**
272
+ * Subscribe to Theme Change Events
273
+ *
274
+ * @param handler Event handler
275
+ * @returns Unsubscribe function
276
+ */
277
+ onThemeChange?(handler: ThemeChangeHandler): Unsubscribe;
278
+ }
279
+ //# sourceMappingURL=theme.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../../../src/types/theme.ts"],"names":[],"mappings":"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"}