@mndw/sdk 0.1.2 → 0.1.4
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.
- package/README.md +36 -537
- package/dist/tokens.css +6 -6
- package/dist/tokens.d.ts +6 -6
- package/dist/tokens.js +6 -6
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -1,559 +1,58 @@
|
|
|
1
|
-
# @mndw/sdk
|
|
1
|
+
# @mndw/sdk
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Types, PluginContext, framework entry helpers, and design tokens for mndw plugins.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Part of mndw
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
`@mndw/sdk` package — everything a plugin author needs.
|
|
7
|
+
mndw is a modular web dashboard for Keenetic/Netcraze routers. Everything in it is a plugin: a dashboard widget or a full page. See [the plugin author site](https://eralde.github.io/mndw/).
|
|
9
8
|
|
|
10
|
-
##
|
|
11
|
-
|
|
12
|
-
Start with the [plugin author docs](https://eralde.github.io/mndw/) and browse the [API reference](https://eralde.github.io/mndw/api/).
|
|
9
|
+
## Install
|
|
13
10
|
|
|
14
11
|
```sh
|
|
15
|
-
npm i -D @mndw/
|
|
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
|
-
}
|
|
12
|
+
npm i -D @mndw/sdk
|
|
85
13
|
```
|
|
86
14
|
|
|
87
|
-
|
|
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
|
-
```
|
|
15
|
+
`mndw create` normally adds the SDK and its framework entry helpers to the plugin project.
|
|
106
16
|
|
|
107
|
-
|
|
17
|
+
## Plugin entry
|
|
108
18
|
|
|
109
|
-
|
|
110
|
-
still use Angular APIs directly when they need different application or component management; these
|
|
111
|
-
helpers reduce repeated mounting and teardown boilerplate.
|
|
19
|
+
The host calls `createInstance` with a container and `PluginContext`; return `unmount` to release framework work.
|
|
112
20
|
|
|
113
21
|
```ts
|
|
22
|
+
import {mount, unmount} from 'svelte';
|
|
114
23
|
import type {PluginContext, PluginInstance} from '@mndw/sdk';
|
|
115
|
-
import
|
|
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.
|
|
24
|
+
import App from './App.svelte';
|
|
401
25
|
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
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);
|
|
26
|
+
export function createInstance(container: HTMLElement, ctx: PluginContext): PluginInstance {
|
|
27
|
+
const app = mount(App, {target: container, props: {backend: ctx.backend, i18n: ctx.i18n}});
|
|
28
|
+
return {unmount: () => { void unmount(app); }};
|
|
486
29
|
}
|
|
487
30
|
```
|
|
488
31
|
|
|
489
|
-
|
|
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.
|
|
32
|
+
## Package versioning
|
|
539
33
|
|
|
540
|
-
|
|
34
|
+
All `@mndw/*` packages share the product version. Scaffolds use a caret range based on the creating CLI version for
|
|
35
|
+
SDK, CLI, UI, and the selected UI adapter. While the product is `0.x`, breaking API, manifest, or protocol changes
|
|
36
|
+
bump the minor version; for example, `^0.1.2` stays within its minor and receives fixes. Moving to a new minor is a
|
|
37
|
+
coordinated upgrade of all `@mndw/*` packages. See [project setup](https://eralde.github.io/mndw/guides/project-setup#package-versioning).
|
|
541
38
|
|
|
542
|
-
|
|
39
|
+
## Entry points
|
|
543
40
|
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
41
|
+
| Import | API |
|
|
42
|
+
| --- | --- |
|
|
43
|
+
| `@mndw/sdk` | [Core types and context](https://eralde.github.io/mndw/api/sdk) |
|
|
44
|
+
| `@mndw/sdk/svelte` | [Svelte helpers](https://eralde.github.io/mndw/api/sdk/svelte) |
|
|
45
|
+
| `@mndw/sdk/vue` | [Vue helpers](https://eralde.github.io/mndw/api/sdk/vue) |
|
|
46
|
+
| `@mndw/sdk/angular` | [Angular helpers](https://eralde.github.io/mndw/api/sdk/angular) |
|
|
47
|
+
| `@mndw/sdk/tokens` | [Typed design tokens](https://eralde.github.io/mndw/api/sdk/tokens) |
|
|
48
|
+
| `@mndw/sdk/tokens.css` | [Token usage](https://eralde.github.io/mndw/guides/styling-and-ui) |
|
|
49
|
+
| `@mndw/sdk/testing` | [Test helpers](https://eralde.github.io/mndw/api/sdk/testing) |
|
|
50
|
+
| `@mndw/sdk/testing/vitest-project` | [Vitest project helper](https://eralde.github.io/mndw/api/sdk/testing/vitest-project) |
|
|
51
|
+
| `@mndw/sdk/bind-locale` | [Locale binding](https://eralde.github.io/mndw/api/sdk/bind-locale) |
|
|
52
|
+
| `@mndw/sdk/refresh` | [Refresh loop](https://eralde.github.io/mndw/api/sdk/refresh) |
|
|
53
|
+
| `@mndw/sdk/rrd` | [RRD helpers](https://eralde.github.io/mndw/api/sdk/rrd) |
|
|
54
|
+
| `@mndw/sdk/manifest.schema.json` | [Manifest guide](https://eralde.github.io/mndw/guides/manifest) |
|
|
553
55
|
|
|
554
|
-
|
|
56
|
+
## Read on
|
|
555
57
|
|
|
556
|
-
-
|
|
557
|
-
- `demo-page`
|
|
558
|
-
- `device-traffic-widget`
|
|
559
|
-
- `ping-widget`
|
|
58
|
+
Start with the [plugin setup guide](https://eralde.github.io/mndw/guides/project-setup), [Hello Widget tutorial](https://eralde.github.io/mndw/tutorials/hello-widget), [frontend lifecycle](https://eralde.github.io/mndw/guides/frontend-lifecycle), and [SDK API reference](https://eralde.github.io/mndw/api/sdk).
|
package/dist/tokens.css
CHANGED
|
@@ -76,14 +76,14 @@
|
|
|
76
76
|
--mndw-accent: #016ca5;
|
|
77
77
|
--mndw-accent-hover: #2b84bf;
|
|
78
78
|
--mndw-accent-contrast: #ffffff;
|
|
79
|
-
--mndw-danger: #
|
|
80
|
-
--mndw-danger-bg: #
|
|
79
|
+
--mndw-danger: #ed3f3f;
|
|
80
|
+
--mndw-danger-bg: #390204;
|
|
81
81
|
--mndw-success: #5cb572;
|
|
82
82
|
--mndw-success-bg: #05210d;
|
|
83
83
|
--mndw-warning: #efa831;
|
|
84
84
|
--mndw-warning-bg: #271700;
|
|
85
|
-
--mndw-info: #
|
|
86
|
-
--mndw-info-bg: #
|
|
85
|
+
--mndw-info: #338ac5;
|
|
86
|
+
--mndw-info-bg: #021d2f;
|
|
87
87
|
--mndw-focus-ring: #338ac5;
|
|
88
88
|
--mndw-surface-hover: #1e2022;
|
|
89
89
|
--mndw-shadow-color: #0102038c;
|
|
@@ -104,8 +104,8 @@
|
|
|
104
104
|
--mndw-danger-bg: #ffe9e6;
|
|
105
105
|
--mndw-success: #137738;
|
|
106
106
|
--mndw-success-bg: #d7f9dc;
|
|
107
|
-
--mndw-warning: #
|
|
108
|
-
--mndw-warning-bg: #
|
|
107
|
+
--mndw-warning: #916100;
|
|
108
|
+
--mndw-warning-bg: #ffebd1;
|
|
109
109
|
--mndw-info: #016ca5;
|
|
110
110
|
--mndw-info-bg: #e0f1ff;
|
|
111
111
|
--mndw-focus-ring: #004f7a;
|
package/dist/tokens.d.ts
CHANGED
|
@@ -15,8 +15,8 @@ export declare const MNDW_TOKENS: {
|
|
|
15
15
|
readonly dangerBg: "#ffe9e6";
|
|
16
16
|
readonly success: "#137738";
|
|
17
17
|
readonly successBg: "#d7f9dc";
|
|
18
|
-
readonly warning: "#
|
|
19
|
-
readonly warningBg: "#
|
|
18
|
+
readonly warning: "#916100";
|
|
19
|
+
readonly warningBg: "#ffebd1";
|
|
20
20
|
readonly info: "#016ca5";
|
|
21
21
|
readonly infoBg: "#e0f1ff";
|
|
22
22
|
readonly focusRing: "#004f7a";
|
|
@@ -34,14 +34,14 @@ export declare const MNDW_TOKENS: {
|
|
|
34
34
|
readonly accent: "#016ca5";
|
|
35
35
|
readonly accentHover: "#2b84bf";
|
|
36
36
|
readonly accentContrast: "#ffffff";
|
|
37
|
-
readonly danger: "#
|
|
38
|
-
readonly dangerBg: "#
|
|
37
|
+
readonly danger: "#ed3f3f";
|
|
38
|
+
readonly dangerBg: "#390204";
|
|
39
39
|
readonly success: "#5cb572";
|
|
40
40
|
readonly successBg: "#05210d";
|
|
41
41
|
readonly warning: "#efa831";
|
|
42
42
|
readonly warningBg: "#271700";
|
|
43
|
-
readonly info: "#
|
|
44
|
-
readonly infoBg: "#
|
|
43
|
+
readonly info: "#338ac5";
|
|
44
|
+
readonly infoBg: "#021d2f";
|
|
45
45
|
readonly focusRing: "#338ac5";
|
|
46
46
|
readonly surfaceHover: "#1e2022";
|
|
47
47
|
readonly shadowColor: "#0102038c";
|
package/dist/tokens.js
CHANGED
|
@@ -16,8 +16,8 @@ export const MNDW_TOKENS = {
|
|
|
16
16
|
"dangerBg": "#ffe9e6",
|
|
17
17
|
"success": "#137738",
|
|
18
18
|
"successBg": "#d7f9dc",
|
|
19
|
-
"warning": "#
|
|
20
|
-
"warningBg": "#
|
|
19
|
+
"warning": "#916100",
|
|
20
|
+
"warningBg": "#ffebd1",
|
|
21
21
|
"info": "#016ca5",
|
|
22
22
|
"infoBg": "#e0f1ff",
|
|
23
23
|
"focusRing": "#004f7a",
|
|
@@ -35,14 +35,14 @@ export const MNDW_TOKENS = {
|
|
|
35
35
|
"accent": "#016ca5",
|
|
36
36
|
"accentHover": "#2b84bf",
|
|
37
37
|
"accentContrast": "#ffffff",
|
|
38
|
-
"danger": "#
|
|
39
|
-
"dangerBg": "#
|
|
38
|
+
"danger": "#ed3f3f",
|
|
39
|
+
"dangerBg": "#390204",
|
|
40
40
|
"success": "#5cb572",
|
|
41
41
|
"successBg": "#05210d",
|
|
42
42
|
"warning": "#efa831",
|
|
43
43
|
"warningBg": "#271700",
|
|
44
|
-
"info": "#
|
|
45
|
-
"infoBg": "#
|
|
44
|
+
"info": "#338ac5",
|
|
45
|
+
"infoBg": "#021d2f",
|
|
46
46
|
"focusRing": "#338ac5",
|
|
47
47
|
"surfaceHover": "#1e2022",
|
|
48
48
|
"shadowColor": "#0102038c"
|
package/dist/version.d.ts
CHANGED
package/dist/version.js
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mndw/sdk",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.4",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"homepage": "https://eralde.github.io/mndw/",
|
|
6
6
|
"repository": {
|
|
@@ -67,7 +67,7 @@
|
|
|
67
67
|
"dependencies": {
|
|
68
68
|
"intl-messageformat": "^11.2.13",
|
|
69
69
|
"zod": "^4.4.3",
|
|
70
|
-
"@mndw/palette-core": "0.1.
|
|
70
|
+
"@mndw/palette-core": "0.1.4"
|
|
71
71
|
},
|
|
72
72
|
"peerDependencies": {
|
|
73
73
|
"@rci-tools/core": "^0.6.0",
|
|
@@ -109,6 +109,7 @@
|
|
|
109
109
|
"vue": "^3.5.39",
|
|
110
110
|
"zone.js": "^0.15.1"
|
|
111
111
|
},
|
|
112
|
+
"description": "Types, PluginContext, framework entry helpers, and design tokens for mndw plugins.",
|
|
112
113
|
"scripts": {
|
|
113
114
|
"test": "vitest run",
|
|
114
115
|
"generate-manifest-schema": "pnpm --filter @mndw/sdk-internal generate-manifest-schema",
|