@mndw/sdk 0.0.0-stage → 0.1.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 (157) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +558 -2
  3. package/dist/angular/create-translator-signals.d.ts +5 -0
  4. package/dist/angular/create-translator-signals.d.ts.map +1 -0
  5. package/dist/angular/create-translator-signals.js +26 -0
  6. package/dist/angular/create-translator-signals.js.map +1 -0
  7. package/dist/angular/index.d.ts +9 -0
  8. package/dist/angular/index.d.ts.map +1 -0
  9. package/dist/angular/index.js +6 -0
  10. package/dist/angular/index.js.map +1 -0
  11. package/dist/angular/mount-in-overlay.d.ts +11 -0
  12. package/dist/angular/mount-in-overlay.d.ts.map +1 -0
  13. package/dist/angular/mount-in-overlay.js +46 -0
  14. package/dist/angular/mount-in-overlay.js.map +1 -0
  15. package/dist/angular/mount-plugin-instance.d.ts +14 -0
  16. package/dist/angular/mount-plugin-instance.d.ts.map +1 -0
  17. package/dist/angular/mount-plugin-instance.js +78 -0
  18. package/dist/angular/mount-plugin-instance.js.map +1 -0
  19. package/dist/angular/provide-translator.d.ts +6 -0
  20. package/dist/angular/provide-translator.d.ts.map +1 -0
  21. package/dist/angular/provide-translator.js +8 -0
  22. package/dist/angular/provide-translator.js.map +1 -0
  23. package/dist/backend-client.d.ts +180 -0
  24. package/dist/backend-client.d.ts.map +1 -0
  25. package/dist/backend-client.js +330 -0
  26. package/dist/backend-client.js.map +1 -0
  27. package/dist/bind-locale.d.ts +4 -0
  28. package/dist/bind-locale.d.ts.map +1 -0
  29. package/dist/bind-locale.js +6 -0
  30. package/dist/bind-locale.js.map +1 -0
  31. package/dist/catalog.d.ts +4 -0
  32. package/dist/catalog.d.ts.map +1 -0
  33. package/dist/catalog.js +29 -0
  34. package/dist/catalog.js.map +1 -0
  35. package/dist/context.d.ts +123 -0
  36. package/dist/context.d.ts.map +1 -0
  37. package/dist/context.js +9 -0
  38. package/dist/context.js.map +1 -0
  39. package/dist/event-schema.d.ts +240 -0
  40. package/dist/event-schema.d.ts.map +1 -0
  41. package/dist/event-schema.js +137 -0
  42. package/dist/event-schema.js.map +1 -0
  43. package/dist/i18n-format.d.ts +3 -0
  44. package/dist/i18n-format.d.ts.map +1 -0
  45. package/dist/i18n-format.js +17 -0
  46. package/dist/i18n-format.js.map +1 -0
  47. package/dist/i18n.d.ts +14 -0
  48. package/dist/i18n.d.ts.map +1 -0
  49. package/dist/i18n.js +2 -0
  50. package/dist/i18n.js.map +1 -0
  51. package/dist/index.d.ts +28 -0
  52. package/dist/index.d.ts.map +1 -0
  53. package/dist/index.js +12 -0
  54. package/dist/index.js.map +1 -0
  55. package/dist/load-state.d.ts +19 -0
  56. package/dist/load-state.d.ts.map +1 -0
  57. package/dist/load-state.js +2 -0
  58. package/dist/load-state.js.map +1 -0
  59. package/dist/manifest.schema.json +635 -0
  60. package/dist/overlay.d.ts +72 -0
  61. package/dist/overlay.d.ts.map +1 -0
  62. package/dist/overlay.js +7 -0
  63. package/dist/overlay.js.map +1 -0
  64. package/dist/palette.d.ts +22 -0
  65. package/dist/palette.d.ts.map +1 -0
  66. package/dist/palette.js +104 -0
  67. package/dist/palette.js.map +1 -0
  68. package/dist/permissions.d.ts +19 -0
  69. package/dist/permissions.d.ts.map +1 -0
  70. package/dist/permissions.js +15 -0
  71. package/dist/permissions.js.map +1 -0
  72. package/dist/plugin.d.ts +15 -0
  73. package/dist/plugin.d.ts.map +1 -0
  74. package/dist/plugin.js +2 -0
  75. package/dist/plugin.js.map +1 -0
  76. package/dist/rci.d.ts +5 -0
  77. package/dist/rci.d.ts.map +1 -0
  78. package/dist/rci.js +7 -0
  79. package/dist/rci.js.map +1 -0
  80. package/dist/refresh.d.ts +16 -0
  81. package/dist/refresh.d.ts.map +1 -0
  82. package/dist/refresh.js +77 -0
  83. package/dist/refresh.js.map +1 -0
  84. package/dist/rrd.d.ts +16 -0
  85. package/dist/rrd.d.ts.map +1 -0
  86. package/dist/rrd.js +20 -0
  87. package/dist/rrd.js.map +1 -0
  88. package/dist/storage.d.ts +7 -0
  89. package/dist/storage.d.ts.map +1 -0
  90. package/dist/storage.js +2 -0
  91. package/dist/storage.js.map +1 -0
  92. package/dist/svelte/create-translator.d.ts +5 -0
  93. package/dist/svelte/create-translator.d.ts.map +1 -0
  94. package/dist/svelte/create-translator.js +19 -0
  95. package/dist/svelte/create-translator.js.map +1 -0
  96. package/dist/svelte/index.d.ts +4 -0
  97. package/dist/svelte/index.d.ts.map +1 -0
  98. package/dist/svelte/index.js +3 -0
  99. package/dist/svelte/index.js.map +1 -0
  100. package/dist/telemetry-client.d.ts +60 -0
  101. package/dist/telemetry-client.d.ts.map +1 -0
  102. package/dist/telemetry-client.js +199 -0
  103. package/dist/telemetry-client.js.map +1 -0
  104. package/dist/testing/dom.d.ts +6 -0
  105. package/dist/testing/dom.d.ts.map +1 -0
  106. package/dist/testing/dom.js +27 -0
  107. package/dist/testing/dom.js.map +1 -0
  108. package/dist/testing/i18n.d.ts +7 -0
  109. package/dist/testing/i18n.d.ts.map +1 -0
  110. package/dist/testing/i18n.js +25 -0
  111. package/dist/testing/i18n.js.map +1 -0
  112. package/dist/testing/index.d.ts +8 -0
  113. package/dist/testing/index.d.ts.map +1 -0
  114. package/dist/testing/index.js +6 -0
  115. package/dist/testing/index.js.map +1 -0
  116. package/dist/testing/observers.d.ts +2 -0
  117. package/dist/testing/observers.d.ts.map +1 -0
  118. package/dist/testing/observers.js +32 -0
  119. package/dist/testing/observers.js.map +1 -0
  120. package/dist/testing/plugin-context.d.ts +38 -0
  121. package/dist/testing/plugin-context.d.ts.map +1 -0
  122. package/dist/testing/plugin-context.js +199 -0
  123. package/dist/testing/plugin-context.js.map +1 -0
  124. package/dist/testing/vitest-project.d.ts +13 -0
  125. package/dist/testing/vitest-project.d.ts.map +1 -0
  126. package/dist/testing/vitest-project.js +26 -0
  127. package/dist/testing/vitest-project.js.map +1 -0
  128. package/dist/ticker.d.ts +14 -0
  129. package/dist/ticker.d.ts.map +1 -0
  130. package/dist/ticker.js +2 -0
  131. package/dist/ticker.js.map +1 -0
  132. package/dist/tokens.css +114 -0
  133. package/dist/tokens.d.ts +128 -0
  134. package/dist/tokens.d.ts.map +1 -0
  135. package/dist/tokens.js +128 -0
  136. package/dist/tokens.js.map +1 -0
  137. package/dist/translator.d.ts +9 -0
  138. package/dist/translator.d.ts.map +1 -0
  139. package/dist/translator.js +2 -0
  140. package/dist/translator.js.map +1 -0
  141. package/dist/version.d.ts +3 -0
  142. package/dist/version.d.ts.map +1 -0
  143. package/dist/version.js +3 -0
  144. package/dist/version.js.map +1 -0
  145. package/dist/vue/index.d.ts +5 -0
  146. package/dist/vue/index.d.ts.map +1 -0
  147. package/dist/vue/index.js +4 -0
  148. package/dist/vue/index.js.map +1 -0
  149. package/dist/vue/use-observable.d.ts +8 -0
  150. package/dist/vue/use-observable.d.ts.map +1 -0
  151. package/dist/vue/use-observable.js +16 -0
  152. package/dist/vue/use-observable.js.map +1 -0
  153. package/dist/vue/use-translator.d.ts +4 -0
  154. package/dist/vue/use-translator.d.ts.map +1 -0
  155. package/dist/vue/use-translator.js +32 -0
  156. package/dist/vue/use-translator.js.map +1 -0
  157. package/package.json +115 -3
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Eralde
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,559 @@
1
- # Temporary Holding Version
1
+ # @mndw/sdk — Plugin Author Guide
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The mndw host loads plugins as dashboard widgets or full-page routes.
4
+
5
+ ## 1. What is mndw?
6
+
7
+ One SPA. Plugins are dashboard widgets or full-page routes loaded dynamically. This guide covers the
8
+ `@mndw/sdk` package — everything a plugin author needs.
9
+
10
+ ## 2. Getting Started
11
+
12
+ Start with the [plugin author docs](https://eralde.github.io/mndw/) and browse the [API reference](https://eralde.github.io/mndw/api/).
13
+
14
+ ```sh
15
+ npm i -D @mndw/cli
16
+ npx mndw create my-widget
17
+ cd my-widget
18
+ npx mndw dev --addr http://router.lan
19
+ ```
20
+
21
+ ## Versioning
22
+
23
+ The SDK version tracks the `PluginContext` contract: a minor release adds capabilities, and a major
24
+ release changes the contract incompatibly. SDK, UI, framework adapters, and CLI are versioned
25
+ independently.
26
+
27
+ ## 3. Manifest Reference
28
+
29
+ | Field | Type | Required | Description |
30
+ |-------------------|------------------------|----------|----------------------------|
31
+ | `manifestVersion` | `1` | yes | Always 1 |
32
+ | `name` | string | yes | `^[a-z0-9][a-z0-9-]*$` |
33
+ | `version` | string | yes | Semver |
34
+ | `type` | `"widget"` or `"page"` | yes | |
35
+ | `label` | string | yes | Human-readable |
36
+ | `entry` | string | yes | Relative path to JS bundle |
37
+ | `icon` | string? | no | |
38
+
39
+ Widgets: `size: { w, h, minW?, minH? }` in grid units (12-column grid). Pages: `route` (single
40
+ segment, reserved: `/`, `/login`, `/packages`, `/packages/services`, `/settings`). SDK validation and
41
+ host routing reject these static paths.
42
+
43
+ Backend (optional): `kind: "exec"` with HTTP route commands, or `kind: "service"`
44
+ with one foreground command, protocol version, and HTTP/WebSocket routes.
45
+ Commands are relative executable paths; service args are literal values.
46
+
47
+ ## 4. Plugin Module
48
+
49
+ ```ts
50
+ import type {PluginContext, PluginInstance} from '@mndw/sdk'
51
+
52
+ export function createInstance(
53
+ container: HTMLElement,
54
+ context: PluginContext,
55
+ ): PluginInstance | Promise<PluginInstance> {
56
+ return {
57
+ unmount() {
58
+ // Clean up DOM, dispose framework component.
59
+ // Return type: void | Promise<void>
60
+ },
61
+ onResize(size: {w: number; h: number}) {
62
+ // Optional widget resize callback.
63
+ void size
64
+ },
65
+ };
66
+ }
67
+ ```
68
+
69
+ ### Svelte (Svelte 5)
70
+
71
+ ```ts
72
+ import {mount, unmount} from 'svelte'
73
+ import type {PluginContext, PluginInstance} from '@mndw/sdk'
74
+ import App from './App.svelte'
75
+
76
+ export function createInstance(container: HTMLElement, ctx: PluginContext): PluginInstance {
77
+ const app = mount(App, {target: container, props: {ctx}});
78
+
79
+ return {
80
+ unmount() {
81
+ void unmount(app);
82
+ },
83
+ };
84
+ }
85
+ ```
86
+
87
+ ### Vue
88
+
89
+ ```ts
90
+ import {createApp} from 'vue'
91
+ import type {PluginContext, PluginInstance} from '@mndw/sdk'
92
+ import App from './App.vue'
93
+
94
+ export function createInstance(container: HTMLElement, ctx: PluginContext): PluginInstance {
95
+ const app = createApp(App, {ctx});
96
+
97
+ app.mount(container);
98
+
99
+ return {
100
+ unmount() {
101
+ app.unmount()
102
+ },
103
+ };
104
+ }
105
+ ```
106
+
107
+ ### Angular
108
+
109
+ `@mndw/sdk/angular` provides optional helpers for common Angular plugin lifecycle work. Authors can
110
+ still use Angular APIs directly when they need different application or component management; these
111
+ helpers reduce repeated mounting and teardown boilerplate.
112
+
113
+ ```ts
114
+ import type {PluginContext, PluginInstance} from '@mndw/sdk';
115
+ import {createAngularPluginInstance, provideTranslator} from '@mndw/sdk/angular';
116
+ import 'zone.js'
117
+ import '@angular/compiler'
118
+ import {AppComponent} from './app.component'
119
+
120
+ export function createInstance(el: HTMLElement, ctx: PluginContext): PluginInstance {
121
+ return createAngularPluginInstance(el, {
122
+ rootComponent: AppComponent,
123
+ providers: [provideTranslator(ctx.i18n)],
124
+ configure: ({component}) => {
125
+ component.setInput('deviceName', ctx.deviceInfo.deviceName);
126
+ },
127
+ });
128
+ }
129
+ ```
130
+
131
+ The helper owns application creation, root view attachment, cancellation when unmounted before
132
+ bootstrap completes, mount-failure cleanup, and component/application teardown. Include
133
+ `provideTranslator(ctx.i18n)` when the component tree injects the SDK `TRANSLATOR` token.
134
+
135
+ For a component opened through the host-managed overlay service, use the optional
136
+ `mountComponentInOverlay` helper. Pass `appRef` from the root helper's `configure` callback and let
137
+ the overlay layer own cleanup; return subscription cleanup from `setup` when needed:
138
+
139
+ ```ts
140
+ import {mountComponentInOverlay} from '@mndw/sdk/angular';
141
+
142
+ configure: ({appRef, component}) => {
143
+ component.setInput('openSettings', () => {
144
+ ctx.overlay.open({
145
+ kind: 'modal',
146
+ title: 'Settings',
147
+ mount(target, layer) {
148
+ mountComponentInOverlay({
149
+ appRef,
150
+ target,
151
+ layer,
152
+ component: SettingsComponent,
153
+ setup: (ref) => {
154
+ ref.setInput('value', 'current');
155
+
156
+ return () => {
157
+ // Unsubscribe from plugin-owned subscriptions here.
158
+ };
159
+ },
160
+ });
161
+ },
162
+ });
163
+ });
164
+ }
165
+ ```
166
+
167
+ `mountComponentInOverlay` attaches the child view and registers detach/destroy cleanup with the
168
+ layer. Direct Angular mounting remains supported when this lifecycle does not fit the plugin.
169
+
170
+ ## 5. Host-managed ticker
171
+
172
+ Use `ctx.createTicker()` for drift-corrected periodic updates. The host shares one worker across
173
+ running plugin tickers and destroys each handle when its plugin context ends.
174
+
175
+ ```ts
176
+ const ticker = ctx.createTicker()
177
+ const subscription = ticker.tick$.subscribe(({timestamp, drift}) => {
178
+ // Update plugin state.
179
+ void timestamp
180
+ void drift
181
+ })
182
+
183
+ ticker.start(1000)
184
+
185
+ // During plugin teardown:
186
+ subscription.unsubscribe()
187
+ ticker.destroy()
188
+ ```
189
+
190
+ `tick$` emits `{timestamp, drift}`. `setInterval()` changes the period, `stop()` pauses this handle,
191
+ and `destroy()` completes its stream. The host ends every handle with its plugin context, so explicit
192
+ destruction is optional when context teardown owns the lifecycle. Plugin bundles do not include the
193
+ host worker.
194
+
195
+ ## 6. PluginContext API
196
+
197
+ ```ts
198
+ type PluginContext = WidgetPluginContext | PagePluginContext;
199
+
200
+ interface WidgetPluginContext {
201
+ kind: 'widget';
202
+ telemetry: TelemetryClient;
203
+ events?: PluginEventFacade;
204
+ rciManager: PluginRciManager;
205
+ storage: PluginStorage;
206
+ sharedStorage: PluginStorage;
207
+ deviceInfo: DeviceInfo;
208
+ i18n: PluginI18n;
209
+ instanceId: string;
210
+ theme: MndwThemeName;
211
+ theme$: Observable<MndwThemeName>;
212
+ locale: string;
213
+ locale$: Observable<string>;
214
+ palette: PaletteTokenMap;
215
+ palette$: Observable<PaletteTokenMap>;
216
+ backend?: BackendClient;
217
+ overlay: OverlayService;
218
+ createTicker(): Ticker;
219
+ setTileTitle?: (title: string) => void;
220
+ // pageRoute is unavailable on widget contexts.
221
+ }
222
+
223
+ interface PagePluginContext {
224
+ kind: 'page';
225
+ telemetry: TelemetryClient;
226
+ events?: PluginEventFacade;
227
+ rciManager: PluginRciManager;
228
+ storage: PluginStorage;
229
+ sharedStorage: PluginStorage;
230
+ deviceInfo: DeviceInfo;
231
+ i18n: PluginI18n;
232
+ instanceId: string;
233
+ theme: MndwThemeName;
234
+ theme$: Observable<MndwThemeName>;
235
+ locale: string;
236
+ locale$: Observable<string>;
237
+ palette: PaletteTokenMap;
238
+ palette$: Observable<PaletteTokenMap>;
239
+ backend?: BackendClient;
240
+ overlay: OverlayService;
241
+ createTicker(): Ticker;
242
+ pageRoute: PageRoute;
243
+ // setTileTitle is unavailable on page contexts.
244
+ }
245
+
246
+ interface PageRoute {
247
+ readonly childPath$: Observable<string>;
248
+ navigate(
249
+ childPath: string,
250
+ options?: {replace?: boolean; scrollToTop?: boolean},
251
+ ): Promise<void>;
252
+ }
253
+
254
+ type PageRouteErrorCode = 'INVALID_PATH' | 'COMPLETED' | 'NAVIGATION_FAILED';
255
+
256
+ class PageRouteError extends Error {
257
+ readonly code: PageRouteErrorCode;
258
+ }
259
+
260
+ interface DeviceInfo {
261
+ deviceName: string;
262
+ vendor: string;
263
+ manufacturer: string;
264
+ model: string;
265
+ series: string;
266
+ region: string;
267
+ hwId: string;
268
+ hwVersion: string;
269
+ hwType?: string;
270
+ firmwareVersion: string;
271
+ firmwareRelease: string;
272
+ architecture?: string;
273
+ features: readonly string[];
274
+ components: readonly string[];
275
+ switchports: Switchports;
276
+ usb: DeviceUsb;
277
+ hasFeature(name: string): boolean;
278
+ hasComponent(name: string): boolean;
279
+ }
280
+
281
+ interface Switchports {
282
+ list: readonly Switchport[];
283
+ layout: readonly (readonly string[])[];
284
+ hasPortStats: boolean;
285
+ }
286
+
287
+ interface Switchport {
288
+ id: string;
289
+ label: string;
290
+ index: number;
291
+ type: string;
292
+ group: string;
293
+ color: string;
294
+ interfaceId: string;
295
+ }
296
+
297
+ interface DeviceUsb {
298
+ ports: readonly ('usb2' | 'usb3')[];
299
+ }
300
+
301
+ interface PluginStorage {
302
+ get(key: string): Promise<string | null>;
303
+ set(key: string, value: string): Promise<void>;
304
+ delete(key: string): Promise<void>;
305
+ keys(): Promise<string[]>;
306
+ }
307
+ ```
308
+
309
+ `PluginContext` is host-created. Narrow variant-specific fields with `context.kind`; plugins do not
310
+ author the discriminant. `theme$`, `locale$`, and `palette$` are RxJS Observables that emit their
311
+ current value to each subscriber and complete when the plugin unmounts. `telemetry.fetchProjected()`
312
+ returns chart-ready data; `events`, when declared event permissions enable it, exposes `select$()` and
313
+ `resync$` Observables. `success` means current settled data, `refreshing` retains prior data while
314
+ a request is active, and `error` may retain prior data after a failed refresh. `unsupported` is a
315
+ terminal capability outcome for that plugin lifetime.
316
+
317
+ ## 6.1 Canonical async state
318
+
319
+ ```ts
320
+ type LoadState<T, E = unknown> =
321
+ | {status: 'idle'}
322
+ | {status: 'loading'}
323
+ | {status: 'success'; data: T}
324
+ | {status: 'refreshing'; data: T}
325
+ | {status: 'error'; error: E; data?: T}
326
+ | {status: 'unsupported'; reason: string};
327
+ ```
328
+
329
+ Reducers must carry `data` into `error` whenever the failed request started from a state that had
330
+ data. Initial `idle`/`loading` failures may omit it.
331
+
332
+ ## Localization
333
+
334
+ `PluginContext.i18n` is required. It is a synchronous `PluginI18n` snapshot for the committed host
335
+ locale. Catalog JSON is nested; dotted lookup uses the path through that tree, and hyphens separate
336
+ words inside one key part:
337
+
338
+ ```json
339
+ {
340
+ "wifi": {
341
+ "encryption": {"disabled": "Unsecured"},
342
+ "band": {"2": "2.4 GHz Wi-Fi"}
343
+ },
344
+ "error": {"integer-only": "Only integer values are allowed"}
345
+ }
346
+ ```
347
+
348
+ Use `wifi.encryption.disabled`, `wifi.band.2`, and `error.integer-only` in code. `i18n.t()` returns
349
+ the raw key when no catalog value exists; it never renders an empty string. `formatNumber()` and
350
+ `formatDate()` follow the committed host locale. `direction` is the reserved literal `'ltr'`; RTL is
351
+ out of scope for this plan.
352
+
353
+ Use framework helpers so child components observe the same locale revision:
354
+
355
+ ```svelte
356
+ <script lang="ts">
357
+ import type {PluginI18n} from '@mndw/sdk';
358
+ import {createTranslator} from '@mndw/sdk/svelte';
359
+
360
+ let {i18n}: {i18n: PluginI18n} = $props();
361
+ const translator = createTranslator(i18n);
362
+ </script>
363
+
364
+ <h1>{$translator.t('wifi.encryption.disabled')}</h1>
365
+ ```
366
+
367
+ ```ts
368
+ import {useTranslator} from '@mndw/sdk/vue';
369
+
370
+ const translator = useTranslator(props.ctx.i18n);
371
+ const label = translator.t('wifi.band.2');
372
+ ```
373
+
374
+ ```ts
375
+ import {DestroyRef, inject} from '@angular/core';
376
+ import {createTranslatorSignals} from '@mndw/sdk/angular';
377
+
378
+ const translator = createTranslatorSignals(ctx.i18n, inject(DestroyRef));
379
+ ```
380
+
381
+ ```ts
382
+ import {bindLocale} from '@mndw/sdk/bind-locale';
383
+
384
+ const unsubscribe = bindLocale(ctx.i18n, render);
385
+ // Call unsubscribe from PluginInstance.unmount().
386
+ ```
387
+
388
+ Angular plugins provide one translator through their root `TRANSLATOR` token and child components
389
+ inject that token. Svelte children receive the translator store/helper, not raw `PluginI18n`.
390
+ Vanilla translation calls belong in audited render modules with `bindLocale` teardown. Template-
391
+ reachable code must not call raw `PluginI18n.t`, `formatNumber`, or `formatDate`; the typed lint rule
392
+ enforces this for Svelte and Angular, with the MWS tile-label adapter as an explicit exemption.
393
+
394
+ The Vue SFC parser remains outside typed enforcement and has no textual raw-i18n rule. Generated
395
+ locale-switch tests and the packed smoke test provide behavioral coverage for Vue.
396
+
397
+ `@mndw/sdk/testing` exports `createTestI18n`, accepting either nested catalogs like production or
398
+ flat dotted-key maps for terse tests. Every generated/plugin/packed smoke probe must have different
399
+ English and Russian values and assert `enValue !== ruValue` before switching; otherwise a test could
400
+ pass without proving that the DOM reacted.
401
+
402
+ `createTestPluginContext()` creates a widget context by default. It exposes `setTheme()`, `setLocale()`,
403
+ `setPalette()`, and `unmount()` for stream and teardown tests. Enable event streams with
404
+ `{events: true}`; use the returned fixture's `emitEvent()` and `resync()` methods to drive them. Its
405
+ `tick()` method advances running handles created by `context.createTicker()`:
406
+
407
+ ```ts
408
+ import {createTestPluginContext} from '@mndw/sdk/testing';
409
+
410
+ const fixture = createTestPluginContext({events: true});
411
+ const themeValues: string[] = [];
412
+ const subscription = fixture.context.theme$.subscribe((theme) => themeValues.push(theme));
413
+
414
+ fixture.setTheme('dark');
415
+ fixture.unmount();
416
+ subscription.unsubscribe();
417
+ ```
418
+
419
+ ### Overlay
420
+
421
+ ```ts
422
+ interface OverlayService {
423
+ createLayer<Result>(options: OverlayLayerOptions): OverlayLayer<Result>;
424
+ open<Result>(options: OverlayOpenOptions<Result>): OverlaySession<Result>;
425
+ closeAll(): void;
426
+ }
427
+ ```
428
+
429
+ `OverlayOpenOptions` requires `kind` (`"modal"` or `"drawer"`), `title?`, `description?`,
430
+ `showCloseButton?`, and a `mount(target, layer, signal)` callback.
431
+
432
+ ## 7. Backend Client
433
+
434
+ ```ts
435
+ interface BackendClient {
436
+ fetch(id: string, options?: BackendFetchOptions): Promise<Response>;
437
+ socket(id: string, options?: BackendSocketOptions): WebSocket;
438
+ status(options?: BackendStatusOptions): Promise<BackendStatus>;
439
+ }
440
+ ```
441
+
442
+ The method and relative path come from endpoint declaration in manifest. Typed errors include
443
+ descriptor errors (`BackendNotApproved`, `BackendDisabled`, `BackendUnknownId`, and
444
+ `BackendTransportMismatch`) plus daemon lifecycle errors:
445
+ `BackendStarting`, `BackendUnavailable`, `BackendIncompatible`, `BackendMaintenance`, and
446
+ `BackendBadGateway`. Lifecycle errors carry `id` and literal `daemonCode`; starting and
447
+ maintenance also carry parsed integer `retryAfterSeconds` or `null`.
448
+
449
+ Page plugins use `context.pageRoute` for child routes. `childPath$` emits the normalized child
450
+ pathname (for example, `/clients`) and `navigate()` accepts a child pathname without query or
451
+ hash. It preserves valid ordinary percent encoding such as `%20`, rejects malformed or ambiguous
452
+ paths, and returns a rejected promise with `PageRouteError` (`INVALID_PATH`, `COMPLETED`, or
453
+ `NAVIGATION_FAILED`) when navigation cannot proceed. `scrollToTop` defaults to `true`.
454
+
455
+ ```ts
456
+ const client = context.backend;
457
+
458
+ if (client) {
459
+ try {
460
+ const res = await client.fetch('stats');
461
+ void res;
462
+ } catch (error) {
463
+ if (error instanceof BackendNotApproved || error instanceof BackendDisabled) {
464
+ // Show approval/availability UI.
465
+ } else if (error instanceof BackendStarting || error instanceof BackendMaintenance) {
466
+ // Show retrying UI; retryAfterSeconds is informational in this slice.
467
+ } else if (error instanceof BackendUnavailable || error instanceof BackendIncompatible
468
+ || error instanceof BackendBadGateway) {
469
+ // Classify daemon lifecycle state or degraded transport.
470
+ } else if (error instanceof BackendUnknownId || error instanceof BackendTransportMismatch) {
471
+ // Fix a stale declaration or route transport mismatch.
472
+ }
473
+ }
474
+ }
475
+ ```
476
+
477
+ ## 8. Design Tokens
478
+
479
+ Style with `var(--mndw-*)` custom properties (auto-themed light/dark):
480
+
481
+ ```css
482
+ .my-widget {
483
+ background: var(--mndw-surface);
484
+ color: var(--mndw-text-subtle);
485
+ border: 1px solid var(--mndw-border);
486
+ }
487
+ ```
488
+
489
+ Full reference: `@mndw/sdk/tokens` (typed) and `@mndw/sdk/tokens.css` (CSS properties).
490
+
491
+ For runtime JavaScript colours, read `context.palette` or subscribe to `context.palette$`.
492
+ `MNDW_TOKENS` contains compiled defaults only and does not include a device palette override.
493
+
494
+ ## 9. Externals Policy
495
+
496
+ Host-provided, must NOT be bundled:
497
+
498
+ | Package | Applies to |
499
+ |-------------------------------------------------------------------------------------------------|----------------------|
500
+ | `@rci-tools/core`, `rxjs`, `rxjs/operators`, `hash-wasm`, `d3` | all plugins |
501
+ | `@mndw/ui` | all plugins |
502
+ | `vue` | Vue plugins only |
503
+ | `zone.js`, `@angular/core`, `@angular/common`, `@angular/platform-browser`, `@angular/compiler` | Angular plugins only |
504
+
505
+ CLI enforces at pack time. Plugins import `@mndw/ui` directly for shared custom elements; the host
506
+ registers those elements and provides the versioned bundle.
507
+
508
+ ### D3 and extensions
509
+
510
+ The host provides the complete `d3@7.9.0` package as one shared bundle. Use the normal package import:
511
+
512
+ ```ts
513
+ import * as d3 from 'd3';
514
+ ```
515
+
516
+ All official d3 APIs, including `zoom`, are available from that namespace. Keep `d3` and `@types/d3` in `devDependencies` so local tests and type checking resolve the package; `mndw pack` externalizes it and the host import map supplies it at runtime.
517
+
518
+ Third-party extensions are not automatically host-provided. Declare an extension such as `d3-dag` in your plugin and let the packer bundle it. Any package not listed in the host shared-dependency table follows this same fallback rule; using it never requires a host release. Do not separately bundle official d3 modules already exposed by the full `d3` namespace.
519
+
520
+ ## 10. Packing & Uploading
521
+
522
+ ```bash
523
+ mndw pack my-widget # bundle -> my-widget/dist/
524
+ mndw zip my-widget # pack + create my-widget/my-widget.zip
525
+ ```
526
+
527
+ Upload through dashboard Settings (recommended). For an authenticated manual request, use the
528
+ persisted dashboard port from `/opt/var/lib/mndw/frontend-port`, an active session cookie, and the
529
+ CSRF header:
530
+
531
+ ```bash
532
+ curl --cookie '<authenticated-session-cookie>' \
533
+ -H 'X-Mndw-Csrf: 1' \
534
+ --data-binary @my-widget.zip \
535
+ http://<device>:<dashboard-port>/api/mgmt/upload
536
+ ```
537
+
538
+ Each zip includes `mndw.lock.json` with exact shared dependency versions.
539
+
540
+ ## 11. Examples
541
+
542
+ Built-in plugins in `plugins/builtin/`:
543
+
544
+ - `device-info-widget`
545
+ - `cpu-temp-widget`
546
+ - `tx-rx-chart-widget`
547
+ - `terminal-page`
548
+ - `clock-widget`
549
+ - `dns-lookup-widget`
550
+ - `mws-page`
551
+ - `clients-widget`
552
+ - `system-log-page`
553
+
554
+ Uploadable examples in `plugins/examples/`:
555
+
556
+ - `backend-echo`
557
+ - `demo-page`
558
+ - `device-traffic-widget`
559
+ - `ping-widget`
@@ -0,0 +1,5 @@
1
+ import { DestroyRef } from '@angular/core';
2
+ import type { PluginI18n } from '../i18n.js';
3
+ import type { Translator } from '../translator.js';
4
+ export declare function createTranslatorSignals(i18n: PluginI18n, destroyRef: DestroyRef): Translator;
5
+ //# sourceMappingURL=create-translator-signals.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"create-translator-signals.d.ts","sourceRoot":"","sources":["../../src/angular/create-translator-signals.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAS,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAEjD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,GAAG,UAAU,CA6B5F"}
@@ -0,0 +1,26 @@
1
+ import { signal } from '@angular/core';
2
+ export function createTranslatorSignals(i18n, destroyRef) {
3
+ const revision = signal(0);
4
+ const subscription = i18n.change$.subscribe(() => revision.update((value) => value + 1));
5
+ destroyRef.onDestroy(() => subscription.unsubscribe());
6
+ return {
7
+ t: (key, values) => {
8
+ revision();
9
+ return i18n.t(key, values);
10
+ },
11
+ formatNumber: (value, options) => {
12
+ revision();
13
+ return i18n.formatNumber(value, options);
14
+ },
15
+ formatDate: (value, options) => {
16
+ revision();
17
+ return i18n.formatDate(value, options);
18
+ },
19
+ get locale() {
20
+ revision();
21
+ return i18n.locale;
22
+ },
23
+ direction: 'ltr',
24
+ };
25
+ }
26
+ //# sourceMappingURL=create-translator-signals.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"create-translator-signals.js","sourceRoot":"","sources":["../../src/angular/create-translator-signals.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,MAAM,EAAC,MAAM,eAAe,CAAC;AAIjD,MAAM,UAAU,uBAAuB,CAAC,IAAgB,EAAE,UAAsB;IAC9E,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IAC3B,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;IAEzF,UAAU,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC,CAAC;IAEvD,OAAO;QACL,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE;YACjB,QAAQ,EAAE,CAAC;YAEX,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC7B,CAAC;QACD,YAAY,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;YAC/B,QAAQ,EAAE,CAAC;YAEX,OAAO,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAC3C,CAAC;QACD,UAAU,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;YAC7B,QAAQ,EAAE,CAAC;YAEX,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACzC,CAAC;QACD,IAAI,MAAM;YACR,QAAQ,EAAE,CAAC;YAEX,OAAO,IAAI,CAAC,MAAM,CAAC;QACrB,CAAC;QACD,SAAS,EAAE,KAAK;KACjB,CAAC;AACJ,CAAC"}
@@ -0,0 +1,9 @@
1
+ /** @module @mndw/sdk/angular */
2
+ export { createTranslatorSignals } from './create-translator-signals.js';
3
+ export { mountComponentInOverlay } from './mount-in-overlay.js';
4
+ export type { OverlayComponentMountOptions } from './mount-in-overlay.js';
5
+ export { createAngularPluginInstance } from './mount-plugin-instance.js';
6
+ export type { AngularPluginInstanceOptions } from './mount-plugin-instance.js';
7
+ export { provideTranslator, TRANSLATOR } from './provide-translator.js';
8
+ export type { Translator } from '../translator.js';
9
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/angular/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,OAAO,EAAC,uBAAuB,EAAC,MAAM,gCAAgC,CAAC;AACvE,OAAO,EAAC,uBAAuB,EAAC,MAAM,uBAAuB,CAAC;AAC9D,YAAY,EAAC,4BAA4B,EAAC,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAAC,2BAA2B,EAAC,MAAM,4BAA4B,CAAC;AACvE,YAAY,EAAC,4BAA4B,EAAC,MAAM,4BAA4B,CAAC;AAC7E,OAAO,EAAC,iBAAiB,EAAE,UAAU,EAAC,MAAM,yBAAyB,CAAC;AACtE,YAAY,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC"}
@@ -0,0 +1,6 @@
1
+ /** @module @mndw/sdk/angular */
2
+ export { createTranslatorSignals } from './create-translator-signals.js';
3
+ export { mountComponentInOverlay } from './mount-in-overlay.js';
4
+ export { createAngularPluginInstance } from './mount-plugin-instance.js';
5
+ export { provideTranslator, TRANSLATOR } from './provide-translator.js';
6
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/angular/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,OAAO,EAAC,uBAAuB,EAAC,MAAM,gCAAgC,CAAC;AACvE,OAAO,EAAC,uBAAuB,EAAC,MAAM,uBAAuB,CAAC;AAE9D,OAAO,EAAC,2BAA2B,EAAC,MAAM,4BAA4B,CAAC;AAEvE,OAAO,EAAC,iBAAiB,EAAE,UAAU,EAAC,MAAM,yBAAyB,CAAC"}
@@ -0,0 +1,11 @@
1
+ import { type ApplicationRef, type ComponentRef, type Type } from '@angular/core';
2
+ import type { OverlayLayer } from '../overlay.js';
3
+ export interface OverlayComponentMountOptions<C> {
4
+ appRef: ApplicationRef;
5
+ component: Type<C>;
6
+ target: HTMLElement;
7
+ layer: Pick<OverlayLayer, 'setCleanup'>;
8
+ setup?: (ref: ComponentRef<C>) => void | (() => void);
9
+ }
10
+ export declare function mountComponentInOverlay<C>(options: OverlayComponentMountOptions<C>): ComponentRef<C>;
11
+ //# sourceMappingURL=mount-in-overlay.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"mount-in-overlay.d.ts","sourceRoot":"","sources":["../../src/angular/mount-in-overlay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,KAAK,cAAc,EAAE,KAAK,YAAY,EAAuB,KAAK,IAAI,EAAkB,MAAM,eAAe,CAAC;AACtH,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,eAAe,CAAC;AAEhD,MAAM,WAAW,4BAA4B,CAAC,CAAC;IAC7C,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IACnB,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;IACxC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC;CACvD;AAED,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,OAAO,EAAE,4BAA4B,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CA6CpG"}