@mndw/ui 0.1.2 → 0.1.3

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 (52) hide show
  1. package/README.md +35 -669
  2. package/dist/button/button.d.ts.map +1 -1
  3. package/dist/button/button.js +11 -7
  4. package/dist/button/button.js.map +1 -1
  5. package/dist/charts/bar-chart.d.ts.map +1 -1
  6. package/dist/charts/bar-chart.js +23 -0
  7. package/dist/charts/bar-chart.js.map +1 -1
  8. package/dist/charts/heat-strip.d.ts +3 -0
  9. package/dist/charts/heat-strip.d.ts.map +1 -1
  10. package/dist/charts/heat-strip.js +27 -1
  11. package/dist/charts/heat-strip.js.map +1 -1
  12. package/dist/checkbox/checkbox.d.ts.map +1 -1
  13. package/dist/checkbox/checkbox.js +14 -1
  14. package/dist/checkbox/checkbox.js.map +1 -1
  15. package/dist/icon/generated/names.d.ts +1 -1
  16. package/dist/icon/generated/names.d.ts.map +1 -1
  17. package/dist/icon/generated/names.js +1 -0
  18. package/dist/icon/generated/names.js.map +1 -1
  19. package/dist/icons.svg +6 -0
  20. package/dist/input/input.d.ts.map +1 -1
  21. package/dist/input/input.js +7 -3
  22. package/dist/input/input.js.map +1 -1
  23. package/dist/segmented/segment.d.ts.map +1 -1
  24. package/dist/segmented/segment.js +11 -5
  25. package/dist/segmented/segment.js.map +1 -1
  26. package/dist/select/select-panel.js +3 -3
  27. package/dist/select/select-panel.js.map +1 -1
  28. package/dist/select/select.d.ts.map +1 -1
  29. package/dist/select/select.js +5 -1
  30. package/dist/select/select.js.map +1 -1
  31. package/dist/slider/slider.d.ts.map +1 -1
  32. package/dist/slider/slider.js +9 -1
  33. package/dist/slider/slider.js.map +1 -1
  34. package/dist/styles/base.d.ts +8 -0
  35. package/dist/styles/base.d.ts.map +1 -1
  36. package/dist/styles/base.js +17 -0
  37. package/dist/styles/base.js.map +1 -1
  38. package/dist/styles.css +16 -2
  39. package/dist/switch/switch.d.ts.map +1 -1
  40. package/dist/switch/switch.js +9 -1
  41. package/dist/switch/switch.js.map +1 -1
  42. package/dist/table/column-menu.js +2 -2
  43. package/dist/table/column-menu.js.map +1 -1
  44. package/dist/table/table.d.ts.map +1 -1
  45. package/dist/table/table.js +20 -8
  46. package/dist/table/table.js.map +1 -1
  47. package/dist/tabs/tab.js +3 -3
  48. package/dist/tabs/tab.js.map +1 -1
  49. package/dist/textarea/textarea.d.ts.map +1 -1
  50. package/dist/textarea/textarea.js +5 -1
  51. package/dist/textarea/textarea.js.map +1 -1
  52. package/package.json +3 -2
package/README.md CHANGED
@@ -1,675 +1,41 @@
1
1
  # @mndw/ui
2
2
 
3
- Framework-agnostic custom elements for mndw plugins and host pages. Components read the
4
- `--mndw-*` design tokens published by the host; this package does not import `tokens.css`.
3
+ Framework-agnostic custom elements for mndw plugins and host pages.
5
4
 
6
- ## Registration
7
-
8
- The host is the sole registrar because `customElements.define` is page-global.
9
-
10
- ```ts
11
- import {defineMndwUi} from '@mndw/ui';
12
-
13
- defineMndwUi({overlay: uiOverlayService});
14
- ```
15
-
16
- Plugins use elements directly. `@mndw/ui` is a shared dependency and is external at pack time.
17
- Without an overlay, `<mndw-select>` uses a minimal fixed-position fallback for standalone use.
18
-
19
- ## Elements
20
-
21
- | Element | Notes |
22
- |----------------------|--------------------------------------------------------------------------------------------------------------------------------------|
23
- | `<mndw-select>` | Slotted `<mndw-option>` children. Emits `mndwchange`. |
24
- | `<mndw-option>` | Declarative option data and rich label content; announces mutations. |
25
- | `<mndw-checkbox>` | Emits `mndwchange`; form-associated with `name`, `value`, `required`, and `invalid`. |
26
- | `<mndw-button>` | `variant="primary"`, `"secondary"`, `"ghost"`, or `"danger"`; `type="button"`, `"submit"`, or `"reset"`. |
27
- | `<mndw-scroll-area>` | Native viewport with an always-visible bespoke scrollbar when content overflows. |
28
- | `<mndw-field>` | Light-DOM label/hint/error wrapper for a single control. Renders no shadow root. |
29
- | `<mndw-input>` | Native inner `<input>` with delegated focus. Emits `mndwinput` and `mndwchange`. |
30
- | `<mndw-textarea>` | Native inner `<textarea>`; `rows` sizing with opt-in `autosize`. Same events. |
31
- | `<mndw-switch>` | `role="switch"` on the host; immediate-effect toggle. Emits `mndwchange`. |
32
- | `<mndw-segmented>` | `role="radiogroup"` with slotted `<mndw-segment>` children. Emits `mndwchange`. |
33
- | `<mndw-segment>` | One choice in a segmented group; `value` and `disabled` only. |
34
- | `<mndw-slider>` | `role="slider"` on the host; numeric range with pointer drag. Emits `mndwinput` and `mndwchange`. |
35
- | `<mndw-tabs>` | Container owning an internal `tablist`, the active `value`, and its children's ARIA. Emits `mndwchange`. |
36
- | `<mndw-tab>` | One tab; `id` (required) and `disabled` only. |
37
- | `<mndw-tab-panel>` | Content for one tab; `for` points at that tab's `id`. |
38
- | `<mndw-tooltip>` | Describes its first slotted element on hover and focus. Not form-associated. |
39
- | `<mndw-line-chart>` | Timestamped multi-series line/area chart; data is assigned through properties. |
40
- | `<mndw-bar-chart>` | Timestamped positional bar chart; data is assigned through properties. |
41
- | `<mndw-sparkline>` | Compact percentage bar chart; data is assigned through `points`. |
42
- | `<mndw-heat-strip>` | Compact utilization heat strip; data is assigned through `points`. |
43
- | `<mndw-table>` | Framework-neutral data table; `columns`/`rows` as properties, controlled sort/selection/visibility, custom light-DOM cell renderers. |
44
- | `<mndw-column-menu>` | Portaled ARIA `menu` column-visibility panel owned by `<mndw-table>`; not opened directly. |
45
- | `<mndw-icon>` | Renders one Lucide symbol from the shared sprite; `name` and `label`; host supplies `iconSpriteUrl`. |
46
-
47
- `<mndw-select>` uses an anchored popover above `600px`, with its maximum height derived from
48
- available viewport space. Long desktop lists scroll inside the panel's nested native scroll area;
49
- the panel owns border, radius, background, shadow, clipping, and a stable scrollbar gutter. At
50
- `<=600px`, it opens a full-width bottom sheet sized to its content up to the viewport, with
51
- title/close chrome, backdrop, scroll lock, and a scrolling option region when the list is long.
52
- Sheet mode sizes panel to content up to viewport; nested option region owns scrolling. Sheet title
53
- comes from `label`, falling back to `Select option`.
54
-
55
- Breakpoint is evaluated from `window.innerWidth` when opening. Resizing across `600px` does not
56
- morph an open layer; close and reopen to use the new presentation. Host focus containment is not
57
- implemented for sheets; pressing `Tab` dismisses the panel and restores focus to the trigger.
58
-
59
- Events are lowercase and hyphen-free (`mndwchange`) for vanilla, Svelte, Vue, and Angular.
60
-
61
- ### Charts
62
-
63
- Charts accept normalized epoch-millisecond data. Assign arrays and objects as DOM properties; they
64
- are not serialized into attributes:
65
-
66
- ```ts
67
- import type {MndwChartSeries, MndwLineChartProps} from '@mndw/ui';
68
-
69
- const series: MndwChartSeries[] = [
70
- {
71
- id: 'upload',
72
- label: 'Upload',
73
- color: 'accent',
74
- fill: true,
75
- data: [
76
- {time: 1_700_000_000_000, value: 100},
77
- {time: 1_700_000_060_000, value: 200},
78
- ],
79
- },
80
- ];
81
-
82
- const lineOptions: MndwLineChartProps = {
83
- series,
84
- domain: {start: 1_700_000_000_000, end: 1_700_000_060_000},
85
- };
86
- const line = document.querySelector('mndw-line-chart');
87
-
88
- if (line !== null) {
89
- Object.assign(line, lineOptions);
90
- }
91
- ```
92
-
93
- `MndwChartPoint` requires an epoch-millisecond `time`; `MndwChartSample` makes `time` optional for
94
- compact charts. `<mndw-line-chart>` exposes `series`, optional `domain`, `valueLabel`, and the
95
- presentation callbacks. `<mndw-bar-chart>` exposes `points`, `valueLabel`, `color`, and the same
96
- callbacks; it uses positional band slots and has no time-domain property. `<mndw-sparkline>` exposes
97
- `points`, optional `timeDomain`, `max`, `valueLabel`, and the presentation callbacks;
98
- `<mndw-heat-strip>` exposes `points`, `max`, `valueLabel`, and the presentation callbacks.
99
- `points`, `series`, `domain`, and callbacks are property-only. String attributes use explicit
100
- hyphenated names: `empty-label="No data"` and `value-label="Throughput"`.
101
-
102
- `*Props` interfaces are optional input bags for object assignment; initialized custom-element
103
- instances still expose concrete defaults such as `points = []`, `color = "accent"`, and `max = 100`.
104
- Replace array properties with a new array reference after data changes.
105
-
106
- All charts accept `valueFormatter(value)` and `timeFormatter(epochMs)` callbacks. Defaults are
107
- network-speed formatting for line/bar values, rounded percentages for compact values, and local
108
- `HH:MM:SS` clock labels. Compact axes render only when every normalized sample has a finite time;
109
- mixed timed and untimed samples render without an axis. Invalid compact `max` values resolve to
110
- `100` for drawing while tooltips and accessibility retain actual sample values. Sparkline colors and
111
- bar colors use `accent`, `success`, `warning`, or `muted`; invalid runtime colors fall back to
112
- `accent`. Heat-strip colors always use its utilization scale.
113
-
114
- For sparklines, `timeDomain` controls the start/end axis independently of finite samples. When it is
115
- provided, timed non-finite sample values reserve empty slots instead of being removed from layout.
116
-
117
- Line and bar charts expose `container`, `plot`, `grid`, `axis`, `tooltip`, and `empty` parts.
118
- Sparkline and heat-strip expose `container`, `plot`, `axis`, `tooltip`, and `empty`; compact `axis`
119
- appears only for fully timed data. Tooltips are local to the plot; data redraw clears stale tooltip
120
- state and does not replay it until the pointer moves again.
121
-
122
- All chart hosts have `role="img"`. An authored `aria-label` wins. Otherwise line labels use each
123
- series' `label` or `id`, while bar and compact labels use `value-label` or localized neutral
124
- `Values`; empty charts use resolved `empty-label`. These fallbacks never assume plugin-specific
125
- vocabulary. `formatSpeed` is exported for consumers that need matching text outside a chart, such as
126
- a plugin-owned summary.
127
-
128
- `<mndw-checkbox>` and `<mndw-select>` participate in form submission through `ElementInternals`.
129
- Unchecked checkboxes and empty or unmatched selects are omitted from `FormData`. Both controls
130
- restore authored defaults on form reset and compose with `<fieldset disabled>`. Their roles and
131
- focus targets live on the host, so external `<label for>` elements work as expected.
132
-
133
- ### `<mndw-table>`
134
-
135
- The shared framework-neutral data table. Plugins declare `columns` (via the curried `column<Row>()`
136
- builder) and assign `rows` as a new array reference on each update; the table owns sorting, checkbox
137
- selection with select-all, row drag/keyboard reorder, and uniform column show/hide. Complex values
138
- (`columns`, `rows`, `rowKey`, `selected`, `sort`, `hiddenColumns`, `rowLabel`, `labels`) are
139
- property-only; the string/enum fields use explicit kebab-case attributes: `row-key` (string form
140
- only), `sort-mode`,
141
- `empty-label`, `caption`, `column-menu-panel-class`, `layout`, `min-width`, and `sticky-header`.
142
-
143
- ```ts
144
- import {column} from '@mndw/ui';
145
-
146
- interface NodeRow {
147
- id: string;
148
- node: {name: string; ip: string; clients: number};
149
- }
150
-
151
- const columns = [
152
- column<NodeRow>()({id: 'name', label: 'Name', accessor: (row) => row.node.name, sortable: true}),
153
- column<NodeRow>()({id: 'ip', label: 'IP', accessor: (row) => row.node.ip}),
154
- column<NodeRow>()({
155
- id: 'clients',
156
- label: 'Clients',
157
- accessor: (row) => row.node.clients,
158
- kind: 'number',
159
- sortable: true
160
- }),
161
- ];
162
-
163
- const table = document.querySelector('mndw-table');
164
- table.rowKey = 'id';
165
- table.columns = columns;
166
- table.rows = nodeRows;
167
- table.sort = {columnId: 'name', direction: 'asc'};
168
- ```
169
-
170
- Sort and selection are controlled: the table renders from `sort` and `selected` and emits
171
- `mndwsortchange` / `mndwselectionchange` / `mndwrowreorder` / `mndwcolumnvisibilitychange` /
172
- `mndwerror` (all `{ bubbles: true, composed: true }`); the plugin writes the prop back. Column
173
- visibility supports both modes: with `hiddenColumns` it is controlled; without it the built-in
174
- column menu (the portaled `<mndw-column-menu>`) drives `internalHidden` and still emits
175
- `mndwcolumnvisibilitychange` informationally. `columnMenu={false}` suppresses the menu.
176
-
177
- `rowKey` is required and resolves to a non-empty string per row (a field name or
178
- `(row) => string`). Empty or duplicate keys and duplicate column ids drop the offending
179
- rows/columns, render a visible `error` part with `role="alert"`, and emit `mndwerror` once per
180
- violation-set change.
181
-
182
- Expandable tables render a controlled inline detail row with `expandable`, `expandOn`, and
183
- `expandedRenderer`. Set `toggleCell` to `leading` or `trailing` for utility-column placement, or set
184
- `toggleAfterColumn` to a visible column id to place its chevron beside that column. Column `width`
185
- values apply to their header and body cells; selection and expand utility columns stay narrow.
186
-
187
- Set `Column.sticky: 'start'` to pin a contiguous leading run of visible data columns to the logical
188
- inline-start edge. Every pinned column must declare `width`; a non-leading or widthless sticky
189
- column stays unpinned, sets `data-mndw-sticky-inactive="not-leading"` or `"missing-width"`, and
190
- emits one development warning. Leading selection, drag, and expand utility cells pin ahead of that
191
- run. Offsets use logical `inset-inline-start` and `border-inline-end`, so pinning is RTL-correct;
192
- pinned cells assume a `--mndw-surface` background. With `reorderable`, the pinned drag column is
193
- clamped to
194
- `2.5rem`, a known cosmetic limitation.
195
-
196
- Set `Column.nowrap: true` to apply `white-space: nowrap` to that column's header and body cells.
197
- `layout="auto"` uses `table-layout: auto` and `width: max-content` for content sizing and horizontal
198
- scroll; virtualization keeps fixed layout and exposes `data-mndw-layout-inactive="virtual"`.
199
- `min-width` applies inline `min-width` to the table and can force horizontal overflow. Set
200
- `sticky-header` to make the header component-owned and sticky; combined with a pinned column, the
201
- top-left cell sticks on both axes.
202
-
203
- #### Dynamic virtualization
204
-
205
- Set `virtual`, `estimatedRowHeight` (default `49`), and pixel `overscan` (default `400`) to render a
206
- bounded contiguous window while keeping validation, sorting, selection, expansion, and
207
- `scrollToRow()` lookup over the complete `rows` array. `estimatedRowHeight` is a pre-measurement
208
- estimate only; after four valid summary measurements, the running mean replaces it for the current
209
- width epoch. `overscan={0}` is valid. Invalid tuning values use defaults and do not create data
210
- violations. Numeric attributes are `estimated-row-height` and `overscan`.
211
-
212
- Virtual mode requires a bounded viewport for bounded DOM work. It uses native positive-height
213
- `virtual-spacer` rows, direct `<tr>` measurement, keyed anchor correction, and `ResizeObserver`.
214
- Custom-cell renderers outside the live window are destroyed; scrolling them back mounts fresh
215
- instances. Keep data needed across that boundary in consumer state. The viewport owns scrolling and
216
- enforces `overflow-anchor: none`, instant internal movement, and `scrollbar-gutter: stable`.
217
-
218
- `scrollToRow(key, {align})` accepts `start`, `center`, `end`, or `nearest` (default). It returns
219
- `false` for an absent valid key and otherwise returns `true`; deep unmeasured targets first land on
220
- estimates and then correct after measurement. `virtual && reorderable` falls back to full rendering
221
- and exposes `data-mndw-virtual-inactive="reorderable"`. If `ResizeObserver` is unavailable, the
222
- fallback reason is `resize-observer-unavailable`. Neither fallback changes logical behavior.
223
-
224
- #### Framework adapters
225
-
226
- Built-in `kind`s are `text`, `number`, `badge`, and a non-interactive `boolean` glyph. Rich cells
227
- use a `CellRenderer` (`mount`/`update`/`destroy`), supplied through `column.renderer`, and render in
228
- a parked light-DOM node so the plugin cell's scoped styles apply. Framework adapters
229
- (`@mndw/ui-svelte`, `@mndw/ui-vue`, `@mndw/ui-angular`) turn native cells into renderers. Parts:
230
- `viewport`, `table`, `caption`, `header`, `header-cell`, `sort-indicator`, `row`, `cell`,
231
- `select-cell`,
232
- `select-all`, `drag-handle`, `column-menu-trigger`, `empty`, `error`. The menu panel is portaled, so
233
- it is styled through `column-menu-panel-class`, not `mndw-table::part(...)`.
234
-
235
- The internal viewport also has class `mndw-table-viewport`. Consumers must keep table controls in a
236
- light-DOM sibling region named `mndw-table-controls`; the viewport is the sole horizontal scroll
237
- owner. The class and `part="viewport"` are both stable hooks for host, Vue, and Angular consumers.
238
-
239
- Adapters render into the parked node on mount/update and unmount on destroy; host startup registers
240
- `@mndw/ui` before plugin mount, so they never wait on `customElements.whenDefined()`.
241
-
242
- ```ts
243
- // Angular — mndwCell directive on an ng-template
244
- column<NodeRow>()({id: 'name', label: 'Name', accessor: (r) => r.node.name, sortable: true})
245
- // <ng-template mndwCell="name" [mndwCellRows]="rows()" let-row>{{ row.node.name }}</ng-template>
246
- ```
247
-
248
- ```svelte
249
- <script lang="ts">
250
- import {svelteCell} from '@mndw/ui-svelte';
251
- import PackageNameCell from './PackageNameCell.svelte';
252
- export const nameCell = svelteCell<PackageEntry, string>()(PackageNameCell)();
253
- </script>
254
- ```
255
-
256
- ```ts
257
- // Vue — defineComponent or functional component
258
- import {vueCell} from '@mndw/ui-vue';
259
- import ClientNameCell from './ClientNameCell.vue';
260
-
261
- const nameCell = vueCell<ClientRecord, string>()(ClientNameCell)();
262
- ```
263
-
264
- ### `<mndw-field>`
265
-
266
- Field takes the control as a light-DOM child and wires labelling itself. It renders into light DOM,
267
- so it exposes classes rather than `::part()`:
268
-
269
- ```html
270
-
271
- <mndw-field label="Host name" hint="Shown in the device list." error="" required>
272
- <input name="hostname"/>
273
- </mndw-field>
274
- ```
275
-
276
- Properties are `label`, `hint`, `error`, and `required`; each is a string except `required`, and an
277
- empty string hides its node instead of rendering it blank. Field creates exactly three nodes once —
278
- `label.mndw-field__label`, `.mndw-field__hint`, and `.mndw-field__error` (which carries
279
- `role="alert"` and the `.mndw-alert--danger` classes) — and places them around the control in label,
280
- control, hint, error order. The control is the first child that is an `Element`, so comments,
281
- placeholder nodes, and whitespace are skipped, and replacing the control rewires automatically.
282
-
283
- Field owns only what it writes. It generates an `id` on the control when it has none, points its
284
- `<label for>` at that id, appends its hint/error ids to `aria-describedby`, sets `aria-invalid`while
285
- `error` is non-empty, and mirrors `required`. Consumer-supplied ids, describedby tokens, and prior
286
- attribute values are preserved and restored; a control that is not labelable is named through
287
- `aria-labelledby` pointing at field's own label instead.
288
-
289
- **The control's own name always wins.** Field renders no label when the control has a non-empty
290
- `aria-label`, an `aria-labelledby` pointing outside field, a consumer `<label for>` anywhere in the
291
- same tree, or its own declared label source. A control declares that source as a static
292
- `mndwLabelSource`: `<mndw-checkbox>` uses `'slot'` (its slotted content is the name) and
293
- `<mndw-select>` uses `'label-property'` (its `label` property is the name). Controls whose label
294
- source can change after mount dispatch `mndwlabelchange` (`bubbles`, `composed`) so field rewires.
295
-
296
- ### `<mndw-input>`
297
-
298
- A text control: the host owns form participation, and a real native `<input>` inside the shadow root
299
- owns editing, caret, selection, IME, and masking. The shadow root uses `delegatesFocus`, so a
300
- `<label for>` click or `.focus()` lands on the native element.
301
-
302
- ```html
303
-
304
- <mndw-field label="Listen port" hint="1–65535">
305
- <mndw-input type="number" name="port" min="1" max="65535" step="1">
306
- <span slot="suffix">s</span>
307
- </mndw-input>
308
- </mndw-field>
309
- ```
310
-
311
- Properties are `value`, `type` (`text | password | search | number | url`, default `text`; anything
312
- else falls back to `text`), `placeholder`, `readonly`, `min`, `max`, `step`, `maxlength`,
313
- `autocomplete`, plus the shared `name`, `disabled`, `required`, and `invalid`. `value` is state, so
314
- it does **not** reflect — the `value` attribute stays the authored default that form reset restores.
315
- Parts are `field`, `input`, `prefix`, and `suffix`; `prefix` and `suffix` are slots for adornments.
316
-
317
- Events are `mndwinput` on every keystroke and `mndwchange` on commit, both with
318
- `detail: {value: string}`. Commit means blur or Enter, and only when the value differs from what it
319
- was when the control gained focus; Enter resets that baseline so the following blur does not fire a
320
- second event. A programmatic write emits nothing and replaces the baseline, so framework bindings
321
- that write `value` back on render cannot loop.
322
-
323
- Because the announced element lives in the shadow root, the control forwards what names and
324
- describes it: `aria-labelledby` (resolved to text), else `aria-label`, else the text of its
325
- associated `<label>` elements becomes the inner element's `aria-label`; `aria-describedby` becomes
326
- its `aria-description`; and `aria-invalid` — from the host attribute, else the `invalid` property,
327
- else computed constraint validity — is mirrored too. The host keeps its own attributes; only the
328
- resolved copies move inward. Resolution reads `textContent` minus `aria-hidden` subtrees, so
329
- decorative content such as `<mndw-field>`'s required marker is never announced, while text hidden
330
- only by CSS still contributes — the same rules the platform applies to a native input. Re-resolution
331
- runs when those host attributes change and when referenced text is edited. A `<label for>` inserted,
332
- removed, or re-pointed elsewhere in the tree is the one case nothing observes: call
333
- `refreshAccessibleName()` for it, as `<mndw-field>` does.
334
-
335
- Validation delegates to the platform. `type`, `required`, `min`, `max`, `step`, and `maxlength` live
336
- on the native element, and the host mirrors its `validity` and `validationMessage` through
337
- `ElementInternals`, so the form sees the same result a native `<input>` would produce.
338
-
339
- ### `<mndw-textarea>`
340
-
341
- The same text-family control as `<mndw-input>`, wrapping a native `<textarea>`. It shares the
342
- forwarding rules, form participation, and commit condition described above; what differs is the
343
- inner element and three things that follow from it.
344
-
345
- ```html
346
-
347
- <mndw-field label="Release notes" hint="Markdown is supported.">
348
- <mndw-textarea name="notes" rows="5" maxlength="2000"></mndw-textarea>
349
- </mndw-field>
350
- ```
351
-
352
- Properties are `value`, `rows` (default `3`), `autosize` (default `false`), `readonly`, and
353
- `maxlength`, plus the shared `name`, `disabled`, `required`, and `invalid`. Parts are `field` and
354
- `textarea`.
355
-
356
- **Enter does not commit.** It inserts a newline, as in a native `<textarea>`, so `mndwchange` fires
357
- on blur only — still just when the value differs from what it was at focus. `mndwinput` is
358
- unchanged.
359
-
360
- **`autosize` is opt-in** because it costs a `ResizeObserver`: the height has to be recomputed when
361
- the width changes and the text reflows, not only when the value changes. While it is on, the control
362
- drives the inner element's height from its content and drops `rows`, since a row count would fight
363
- it; turning it off restores `rows` sizing and clears the inline height.
5
+ ## Part of mndw
364
6
 
365
- ### `<mndw-switch>`
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/).
366
8
 
367
- An immediate-effect toggle. It differs from `<mndw-checkbox>` by semantics rather than styling: a
368
- switch applies its change at once, a checkbox travels with a form submission. The host's dark-theme
369
- setting is a switch; package selection is a checkbox.
370
-
371
- ```html
372
-
373
- <mndw-field label="Dark theme">
374
- <mndw-switch name="theme" value="dark"></mndw-switch>
375
- </mndw-field>
376
- ```
377
-
378
- Properties are `checked` and `value` (default `'on'`), plus the shared `name`, `disabled`,
379
- `required`, and `invalid`. Both `checked` and `value` reflect — `value` is configuration, the token
380
- submitted while the switch is on. Parts are `track`, `thumb`, and `label`. `mndwchange` carries
381
- `detail: {checked: boolean}` and fires on user activation only, never on a programmatic write.
382
-
383
- The host carries `role="switch"`, the tab stop, and the keyboard handling; Space and Enter toggle,
384
- and the shadow track and thumb are presentational and `aria-hidden`. `FormData` gets `value` while
385
- checked and nothing at all while unchecked, and form reset restores the `checked` **attribute**.
386
-
387
- **`required` is accepted and inert**, as it is on a native `<input type="range">`: a switch always
388
- holds a value, so `valueMissing` can never be true. It sets no validity flag and no `aria-required`.
389
- `invalid` reflects for styling; `<mndw-field>` owns the `aria-invalid` announcement.
390
-
391
- The accessible name comes from outside: a `<label for>` on the host, or `<mndw-field>`. Slotted
392
- content renders in the `label` part for standalone use, but a switch declares no `mndwLabelSource`,
393
- so a wrapping field always renders its own label rather than deferring to that content.
394
-
395
- ### `<mndw-segmented>` and `<mndw-segment>`
396
-
397
- A radio group in segmented-control clothing, following the `<mndw-select>` / `<mndw-option>` idiom:
398
- the group owns the value, the events, and the form state; the children are declarative.
399
-
400
- ```html
401
-
402
- <mndw-segmented label="Range" name="range" value="day">
403
- <mndw-segment value="day">Day</mndw-segment>
404
- <mndw-segment value="week">Week</mndw-segment>
405
- <mndw-segment value="month" disabled>Month</mndw-segment>
406
- </mndw-segmented>
407
- ```
408
-
409
- The group carries `value`, the author-facing `label`, and the shared `name`, `disabled`,
410
- `required`, and `invalid`; `value` is state and does not reflect. Part `group`. `mndwchange` carries
411
- `detail: {value: string}` and fires on user activation only. Each `<mndw-segment>` carries just
412
- `value` (required, reflected) and `disabled` (reflected), with content in its default slot and part
413
- `segment`. A segment with no `value` is ignored rather than treated as an error.
414
-
415
- `role="radiogroup"` sits on the group and `role="radio"` on each segment, written by the group along
416
- with `aria-checked`, `aria-disabled`, and the roving `tabindex` — and removed again from any segment
417
- that leaves the group. **The tab stop is the checked segment**, or the first enabled one when
418
- nothing is checked; the group host stays at `tabindex="-1"` so `form.reportValidity()` has an anchor
419
- without Tab ever landing on it. Arrow keys move and select with wraparound, Home and End jump to the
420
- first and last enabled segment, Space and Enter select the focused one, and disabled segments are
421
- skipped throughout.
422
-
423
- Nothing selected is a valid initial state: `FormData` omits the group entirely, and `required`
424
- reports `valueMissing` only while the value matches no segment. Reset restores the `value`
425
- **attribute**, or clears the selection when none was authored. The `label` property is the group's
426
- accessible name — it has no slotted text to take one from — so it declares
427
- `mndwLabelSource = 'label-property'` and emits `mndwlabelchange` when it changes, which is what lets
428
- a wrapping `<mndw-field>` decide whether to render its own label.
429
-
430
- ### `<mndw-slider>`
431
-
432
- A numeric range control. The host is the slider: it carries `role="slider"`, the tab stop, the
433
- keyboard matrix, and the pointer drag, while the track, fill, thumb, and output inside the shadow
434
- root are presentational.
435
-
436
- ```html
437
-
438
- <mndw-field label="Transmit power">
439
- <mndw-slider name="power" min="0" max="20" step="5" value="10"
440
- value-text="10 dBm"></mndw-slider>
441
- </mndw-field>
442
- ```
443
-
444
- Properties are `value`, `min`, `max`, and `step` (all `number`, defaults `0`, `100`, `1`, with
445
- `value` defaulting to `min`), `valueText` (attribute `value-text`), plus the shared `name`,
446
- `disabled`, `required`, and `invalid`. `min`, `max`, and `step` reflect because they are
447
- configuration; `value` is state and does not, so the `value` attribute stays the default that form
448
- reset restores. Parts are `track`, `fill`, `thumb`, and `output`.
449
-
450
- **`value` is a `number` end to end.** Both events carry `detail: {value: number}`, and only the form
451
- value is stringified — `FormData` always contains the slider's `name`, since a slider always holds a
452
- value. Every write is clamped into range and snapped onto the step grid measured from `min`, so a
453
- value that arrives out of range or off-grid is corrected rather than rejected. An empty `valueText`
454
- leaves `aria-valuetext` unset so the browser announces `aria-valuenow`; a non-empty one is announced
455
- instead and is also what the `output` part shows.
456
-
457
- `mndwinput` fires on every pointer move or keystroke that moves the value. `mndwchange` commits:
458
- once on `pointerup` or `pointercancel`, and only when the value differs from what it was at
459
- `pointerdown`; on the keyboard it fires immediately after each `mndwinput`, on the same keystroke,
460
- as a native `<input type="range">` does. Neither fires for a programmatic write.
461
-
462
- Arrow keys step, PageUp and PageDown jump a tenth of the range (never less than one step), and Home
463
- and End go to `min` and `max`. **`required` is accepted and inert**, as on `<mndw-switch>`;
464
- `rangeUnderflow`, `rangeOverflow`, and `stepMismatch` are computed by the control, which normally
465
- means no flag at all — normalization keeps the value legal, so they surface a contradictory
466
- configuration such as a `min` above `max`. The accessible name comes from outside: a `<label for>`
467
- on the host, or `<mndw-field>`.
468
-
469
- ### `<mndw-tabs>`, `<mndw-tab>`, and `<mndw-tab-panel>`
470
-
471
- Three elements, one relationship. The group owns the active `value`, the keyboard matrix, and every
472
- ARIA attribute on its children; the children are declarative.
473
-
474
- ```html
475
-
476
- <mndw-tabs value="network">
477
- <mndw-tab id="general">General</mndw-tab>
478
- <mndw-tab id="network">Network</mndw-tab>
479
- <mndw-tab id="advanced" disabled>Advanced</mndw-tab>
480
- <mndw-tab-panel for="general">General settings</mndw-tab-panel>
481
- <mndw-tab-panel for="network">Network settings</mndw-tab-panel>
482
- </mndw-tabs>
483
- ```
484
-
485
- `<mndw-tabs>` carries `value` — the active tab's `id`, state, so it does not reflect — and part
486
- `tablist`. It has **no role of its own**: making the group a `tablist` would wrongly include the
487
- panels, so the role sits on an internal wrapper that only the tabs are slotted into. `mndwchange`
488
- carries `detail: {value: string}` and fires on user activation only. Not form-associated; tab
489
- selection is view state, not form data.
490
-
491
- `<mndw-tab>` carries `id` (required) and `disabled`, with part `tab`. `<mndw-tab-panel>` carries
492
- `for` — its tab's id — plus a generated `mndw-tab-panel-N` id when the consumer supplies none, and
493
- part `panel`. **The panel points at its tab, not the other way round**, mirroring the ARIA
494
- relationship and letting tabs be reordered or conditionally rendered without every reference
495
- breaking; a `for` on a `<mndw-tab>` gets a `console.warn` naming the right element.
496
-
497
- The group writes `role`, `aria-selected`, `aria-controls`, `aria-disabled`, the roving `tabindex`,
498
- and `slot="tab"` onto its tabs, and `role`, `aria-labelledby`, and `hidden` onto its panels — and
499
- removes exactly those again when a child leaves or the group disconnects. It rewires when a tab`id`,
500
- a panel `for`, or the child order changes. Activation is **automatic**: arrow keys move focus and
501
- selection together with wraparound, Home and End jump to the first and last enabled tab, and
502
- disabled tabs are skipped. An inactive panel is `hidden` rather than unmounted, so its content
503
- leaves the accessibility tree and the tab order while keeping its state.
504
-
505
- Malformed markup degrades rather than throws, each case reported once: a panel whose `for` matches
506
- no tab stays hidden, a tab with no `id` renders inert (it can be neither referenced nor selected),
507
- and when two panels claim one tab the first in document order wins.
508
-
509
- ### `<mndw-tooltip>`
510
-
511
- Wraps a trigger and describes it. Properties are `text`, `placement` (`top | bottom | left | right`,
512
- default `top`), and `delay` (ms before showing, default `500`; hiding is immediate). Part `tooltip`.
513
-
514
- ```html
515
-
516
- <mndw-tooltip text="Restarts the device immediately" placement="bottom">
517
- <mndw-button variant="danger">Restart</mndw-button>
518
- </mndw-tooltip>
519
- ```
520
-
521
- The first assigned element in the default slot is the trigger; anything after it is ignored and
522
- warned about once. Shows on hover and focus after `delay`, hides on pointer leave, blur, and
523
- Escape — Escape is not consumed, so a dialog behind the tooltip still sees it. An empty `text`
524
- renders nothing, carries no role, and describes nothing rather than showing an empty bubble.
525
-
526
- **The host carries `role="tooltip"` and the id, not the bubble.** An `aria-describedby` token cannot
527
- cross into a shadow root, so the described element has to be the host — which means the trigger sits
528
- inside the described subtree and a screen reader announces the trigger's own name first, then this
529
- text. The component appends only its own id token to the trigger's `aria-describedby`, preserving
530
- every consumer token, and removes only that token when `text` empties, the trigger is replaced, the
531
- host id changes, or the tooltip disconnects. It rewires when any of those change, including a
532
- consumer rewriting `aria-describedby` underneath it.
533
-
534
- The closed bubble is invisible but **not** removed: the description resolves from its text, so
535
- `display: none` or `hidden` would leave the trigger describing nothing. Positioning comes from the
536
- same shared module `<mndw-select>` uses, exported as `computeTooltipCoords`; the tooltip centres on
537
- the requested side, flips when that side is clipped, clamps the cross axis into the viewport, and
538
- publishes the side it settled on as `data-placement` for styling.
539
-
540
- `<mndw-button>` uses `ElementInternals` only to reach its containing form: `type="submit"` calls
541
- `requestSubmit()` and `type="reset"` calls `reset()`. It contributes no name/value pair and is not a
542
- native submitter; use a native `<button>` when submitter data is required.
543
-
544
- `variant` is `primary`, `secondary`, `ghost`, or `danger`, and the default stays `secondary`.
545
- `danger` is for destructive actions — deleting a plugin, forgetting a device — and renders as a
546
- `--mndw-danger-bg` tint with `--mndw-danger` text and border, deepening slightly on hover. It is
547
- deliberately **not** a solid danger fill: the palette models `danger` as a foreground and emits no
548
- contrast pair for it, so a solid fill would be a colour combination the generator never validated.
549
-
550
- ### `<mndw-icon>`
551
-
552
- `<mndw-icon>` renders one symbol from a single locally served SVG sprite. Names come from the
553
- generated catalog in `src/icon/generated/names.ts`; adding a name is a host-side change.
554
-
555
- ```html
556
- <mndw-icon name="settings"></mndw-icon>
557
- <mndw-icon name="info" label="Information"></mndw-icon>
558
- <mndw-button aria-label="Settings">
559
- <mndw-icon name="settings"></mndw-icon>
560
- </mndw-button>
561
- ```
562
-
563
- `name` defaults to empty. Unknown or empty names render no `<use>` and still reserve the icon box;
564
- nothing is substituted and nothing is logged per render. `label` defaults to empty: labeled icons
565
- render `role="img"` with `aria-label`, unlabeled ones are `aria-hidden="true"`. The inner SVG is
566
- never focusable and exposes `part="svg"`. For icon-only buttons, keep the accessible name on the
567
- button and leave the icon unlabeled.
568
-
569
- Size comes from CSS: the host is `1em` square, so `width`/`height` or `font-size` on the element
570
- control it. Color inherits through `currentColor`.
571
-
572
- `name` and `label` reflect to attributes. Svelte and Vue assign properties on custom elements, so
573
- reflection keeps the value visible in the DOM for templates, DevTools, and tests.
574
-
575
- ```css
576
- mndw-icon.size-16 {
577
- width: 16px;
578
- height: 16px;
579
- }
580
- ```
581
-
582
- The host is the only registrar, and the sprite URL is host configuration:
583
-
584
- ```ts
585
- import iconSpriteUrl from '@mndw/ui/icons.svg?url&no-inline';
586
-
587
- defineMndwUi({overlay: uiOverlayService, iconSpriteUrl});
588
- ```
589
-
590
- Without `iconSpriteUrl`, icons render empty SVGs and issue no requests. Standalone or test usage must
591
- pass a URL explicitly. `defineMndwUi()` without arguments stays valid and preserves a previously
592
- configured URL.
593
-
594
- Plugins use raw string names in templates and consult the documented catalog; no SDK re-export or
595
- extra plugin dependency is involved. Names are public API and depend on the host build: a plugin
596
- must not assume a newer name exists on an older host. Adding an icon means updating
597
- `icons/lucide/UPSTREAM.json`, acquiring the matching SVG, and running
598
- `pnpm --filter @mndw/ui generate-icons`. The generator fails loudly on any missing or extra SVG,
599
- reporting `Missing SVGs:` and `Extra SVGs:` filename lists; `pnpm --filter @mndw/ui check:icons`
600
- verifies committed output matches the generator.
601
-
602
- Sources in `icons/lucide/` are unmodified Lucide artwork (ISC, with inherited Feather notices) and
603
- the sprite carries that license as XML metadata. `src/icon/generated/` is committed generated output
604
- — edit upstream sources and regenerate instead.
605
-
606
- ## Styling
607
-
608
- Components consume inherited `--mndw-*` tokens. Use `::part()` for component styling. Select panels
609
- are portaled, so `panel-class` must be global and is applied to the overlay layer wrapper:
610
-
611
- ```html
612
-
613
- <mndw-select panel-class="tx-rx-iface-panel"></mndw-select>
614
- ```
615
-
616
- ```css
617
- .tx-rx-iface-panel mndw-select-panel::part(option) {
618
- padding: 0.625rem;
619
- }
620
-
621
- .tx-rx-iface-panel mndw-select-panel::part(listbox) {
622
- padding-inline-end: 1.25rem;
623
- }
624
-
625
- .tx-rx-iface-panel mndw-select-panel::part(thumb) {
626
- background: var(--mndw-accent);
627
- }
628
- ```
629
-
630
- ### Global class layer
631
-
632
- Host pages import `@mndw/sdk/tokens.css` and `@mndw/ui/styles.css` once. The class layer styles
633
- light-DOM content without registering elements:
634
-
635
- ```html
636
-
637
- <div class="mndw-alert mndw-alert--danger" role="alert">
638
- <div class="mndw-alert__title">Connection failed</div>
639
- <div class="mndw-alert__body">Retry request.</div>
640
- </div>
641
- <span class="mndw-badge mndw-badge--success">Connected</span>
642
- <span class="mndw-status-dot mndw-status-dot--success" aria-hidden="true"></span>
643
- <span class="mndw-spinner" aria-hidden="true"></span>
644
- <div class="mndw-progress" role="progressbar" aria-busy="true"></div>
645
- ```
646
-
647
- Alerts, badges, and status dots support `--danger`, `--success`, `--warning`, and `--info`
648
- modifiers. `.mndw-empty`, `.mndw-card`, and `.mndw-toolbar` are semantic containers; consumers own
649
- headings, roles, names, and live-region semantics. `.mndw-spinner` and `.mndw-progress` add no
650
- roles. Use native `[hidden]` for visibility and attributes such as `[aria-busy]` for runtime state.
651
-
652
- Fields use `.mndw-field` with `.mndw-field__label`, `.mndw-field__hint`, and
653
- `.mndw-field__error`. Consumer owns control IDs and `aria-describedby`/`aria-invalid` wiring; error
654
- content carries `role="alert"` when it interrupts the user. `<mndw-field>` applies the same classes
655
- to itself and its owned nodes, and does that wiring for you.
656
-
657
- Tables use `.mndw-table` with normal `caption`, `thead`, `tbody`, `tr`, `th`, and `td` markup. Add
658
- `.mndw-table--sticky-head` to opt into a sticky header. Sort state is expressed with native
659
- `aria-sort`; no runtime state classes are required.
660
-
661
- The overlay wrapper owns width and height bounds; the panel owns its visual chrome, and the nested
662
- `<mndw-scroll-area>` owns option scrolling. Its `viewport`, `scrollbar`, `track`, and
663
- `thumb` parts are forwarded by the select panel. Use `refresh()` for content changes observers
664
- cannot see, or `viewportElement` for direct native `scrollTop`/`scrollTo` access.
665
-
666
- Scrollbar hooks are `--mndw-scrollbar-size`, `--mndw-scrollbar-thumb`,
667
- `--mndw-scrollbar-thumb-hover`, `--mndw-scrollbar-track`, `--mndw-scrollbar-radius`, and
668
- `--mndw-scrollbar-thumb-min-size` (default `1.5rem`). Generator emits defaults; ancestor overrides
669
- inherit correctly. Scrollbar chrome is `aria-hidden`; native viewport and listbox remain accessible
670
- interaction surface.
9
+ ## Registration
671
10
 
672
- When `ElementInternals.ariaControlsElements` is unavailable, the select omits `aria-controls`
673
- because its panel is portaled into another node tree. Rich option child nodes are cloned into the
674
- panel without HTML string interpolation. Sheet chrome belongs to the host overlay and is not exposed
675
- through `::part()`.
11
+ The host calls `defineMndwUi()` once because custom element registration is page-global. Plugins use the tags directly;
12
+ `@mndw/ui` is a host-provided shared dependency and is externalized when packing. For standalone use, pass
13
+ `iconSpriteUrl` to `defineMndwUi` so `<mndw-icon>` can load the SVG sprite; see [icon setup](https://eralde.github.io/mndw/ui/icon).
14
+
15
+ ## Components
16
+
17
+ | Component | Summary |
18
+ | --- | --- |
19
+ | [`<mndw-button>`](https://eralde.github.io/mndw/ui/button) | `variant` accepts `primary`, `secondary`, `ghost`, or `danger`; `type` accepts `button`, `submit`, or `reset`. |
20
+ | [`<mndw-icon>`](https://eralde.github.io/mndw/ui/icon) | Renders a Lucide symbol from the shared sprite; host supplies `iconSpriteUrl`. |
21
+ | [`<mndw-checkbox>`](https://eralde.github.io/mndw/ui/checkbox) | Form-associated checkbox; emits `mndwchange`. |
22
+ | [`<mndw-switch>`](https://eralde.github.io/mndw/ui/switch) | Immediate-effect toggle; emits `mndwchange`. |
23
+ | [`<mndw-input>`](https://eralde.github.io/mndw/ui/input) | Native input with delegated focus; emits `mndwinput` and `mndwchange`. |
24
+ | [`<mndw-textarea>`](https://eralde.github.io/mndw/ui/textarea) | Native textarea with optional autosize. |
25
+ | [`<mndw-field>`](https://eralde.github.io/mndw/ui/field) | Light-DOM label, hint, and error wrapper. |
26
+ | [`<mndw-select>`](https://eralde.github.io/mndw/ui/select) | Slotted `<mndw-option>` children; emits `mndwchange`. |
27
+ | [`<mndw-segmented>`](https://eralde.github.io/mndw/ui/segmented) | Radiogroup with slotted `<mndw-segment>` children. |
28
+ | [`<mndw-slider>`](https://eralde.github.io/mndw/ui/slider) | Numeric range with pointer drag. |
29
+ | [`<mndw-tabs>`](https://eralde.github.io/mndw/ui/tabs) | Owns tab selection and ARIA for `<mndw-tab>` and `<mndw-tab-panel>`. |
30
+ | [`<mndw-tooltip>`](https://eralde.github.io/mndw/ui/tooltip) | Describes its first slotted element on hover and focus. |
31
+ | [`<mndw-scroll-area>`](https://eralde.github.io/mndw/ui/scroll-area) | Native viewport with a visible scrollbar when content overflows. |
32
+ | [`<mndw-table>`](https://eralde.github.io/mndw/ui/table) | Framework-neutral table with properties for rows and columns; includes `<mndw-column-menu>`. |
33
+ | [`<mndw-line-chart>`](https://eralde.github.io/mndw/ui/line-chart) | Timestamped multi-series line and area chart. |
34
+ | [`<mndw-bar-chart>`](https://eralde.github.io/mndw/ui/bar-chart) | Timestamped positional bar chart. |
35
+ | [`<mndw-sparkline>`](https://eralde.github.io/mndw/ui/sparkline) | Compact percentage bar chart. |
36
+ | [`<mndw-heat-strip>`](https://eralde.github.io/mndw/ui/heat-strip) | Compact utilization heat strip. |
37
+ | [CSS classes](https://eralde.github.io/mndw/ui/css-classes) | Global layout, status, form, and table styles. |
38
+
39
+ ## Read on
40
+
41
+ See the [UI components overview](https://eralde.github.io/mndw/ui/), [Styling and UI](https://eralde.github.io/mndw/guides/styling-and-ui), and [Shared UI components](https://eralde.github.io/mndw/guides/ui-components).