@mndw/ui 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.
- package/LICENSE +21 -0
- package/README.md +674 -2
- package/dist/button/button.d.ts +27 -0
- package/dist/button/button.d.ts.map +1 -0
- package/dist/button/button.js +147 -0
- package/dist/button/button.js.map +1 -0
- package/dist/charts/bar-chart.d.ts +33 -0
- package/dist/charts/bar-chart.d.ts.map +1 -0
- package/dist/charts/bar-chart.js +235 -0
- package/dist/charts/bar-chart.js.map +1 -0
- package/dist/charts/chart-frame-controller.d.ts +23 -0
- package/dist/charts/chart-frame-controller.d.ts.map +1 -0
- package/dist/charts/chart-frame-controller.js +66 -0
- package/dist/charts/chart-frame-controller.js.map +1 -0
- package/dist/charts/chart-frame.d.ts +20 -0
- package/dist/charts/chart-frame.d.ts.map +1 -0
- package/dist/charts/chart-frame.js +95 -0
- package/dist/charts/chart-frame.js.map +1 -0
- package/dist/charts/chart-types.d.ts +67 -0
- package/dist/charts/chart-types.d.ts.map +1 -0
- package/dist/charts/chart-types.js +2 -0
- package/dist/charts/chart-types.js.map +1 -0
- package/dist/charts/chart-utils.d.ts +17 -0
- package/dist/charts/chart-utils.d.ts.map +1 -0
- package/dist/charts/chart-utils.js +118 -0
- package/dist/charts/chart-utils.js.map +1 -0
- package/dist/charts/heat-strip.d.ts +43 -0
- package/dist/charts/heat-strip.d.ts.map +1 -0
- package/dist/charts/heat-strip.js +269 -0
- package/dist/charts/heat-strip.js.map +1 -0
- package/dist/charts/line-chart.d.ts +40 -0
- package/dist/charts/line-chart.d.ts.map +1 -0
- package/dist/charts/line-chart.js +307 -0
- package/dist/charts/line-chart.js.map +1 -0
- package/dist/charts/sparkline-geometry.d.ts +21 -0
- package/dist/charts/sparkline-geometry.d.ts.map +1 -0
- package/dist/charts/sparkline-geometry.js +31 -0
- package/dist/charts/sparkline-geometry.js.map +1 -0
- package/dist/charts/sparkline.d.ts +56 -0
- package/dist/charts/sparkline.d.ts.map +1 -0
- package/dist/charts/sparkline.js +303 -0
- package/dist/charts/sparkline.js.map +1 -0
- package/dist/checkbox/checkbox.d.ts +46 -0
- package/dist/checkbox/checkbox.d.ts.map +1 -0
- package/dist/checkbox/checkbox.js +243 -0
- package/dist/checkbox/checkbox.js.map +1 -0
- package/dist/field/field.d.ts +61 -0
- package/dist/field/field.d.ts.map +1 -0
- package/dist/field/field.js +359 -0
- package/dist/field/field.js.map +1 -0
- package/dist/focus.d.ts +24 -0
- package/dist/focus.d.ts.map +1 -0
- package/dist/focus.js +226 -0
- package/dist/focus.js.map +1 -0
- package/dist/forms/form-associated.d.ts +39 -0
- package/dist/forms/form-associated.d.ts.map +1 -0
- package/dist/forms/form-associated.js +124 -0
- package/dist/forms/form-associated.js.map +1 -0
- package/dist/forms/text-control.d.ts +83 -0
- package/dist/forms/text-control.d.ts.map +1 -0
- package/dist/forms/text-control.js +238 -0
- package/dist/forms/text-control.js.map +1 -0
- package/dist/i18n/en.json +43 -0
- package/dist/i18n/ru.json +43 -0
- package/dist/i18n.d.ts +7 -0
- package/dist/i18n.d.ts.map +1 -0
- package/dist/i18n.js +65 -0
- package/dist/i18n.js.map +1 -0
- package/dist/icon/generated/names.d.ts +4 -0
- package/dist/icon/generated/names.d.ts.map +1 -0
- package/dist/icon/generated/names.js +39 -0
- package/dist/icon/generated/names.js.map +1 -0
- package/dist/icon/icon.d.ts +26 -0
- package/dist/icon/icon.d.ts.map +1 -0
- package/dist/icon/icon.js +74 -0
- package/dist/icon/icon.js.map +1 -0
- package/dist/icon/sprite-config.d.ts +4 -0
- package/dist/icon/sprite-config.d.ts.map +1 -0
- package/dist/icon/sprite-config.js +24 -0
- package/dist/icon/sprite-config.js.map +1 -0
- package/dist/icons.svg +189 -0
- package/dist/index.d.ts +59 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +105 -0
- package/dist/index.js.map +1 -0
- package/dist/input/input.d.ts +71 -0
- package/dist/input/input.d.ts.map +1 -0
- package/dist/input/input.js +304 -0
- package/dist/input/input.js.map +1 -0
- package/dist/locale-controller.d.ts +19 -0
- package/dist/locale-controller.d.ts.map +1 -0
- package/dist/locale-controller.js +29 -0
- package/dist/locale-controller.js.map +1 -0
- package/dist/localized-property.d.ts +11 -0
- package/dist/localized-property.d.ts.map +1 -0
- package/dist/localized-property.js +144 -0
- package/dist/localized-property.js.map +1 -0
- package/dist/overlay-adapter.d.ts +4 -0
- package/dist/overlay-adapter.d.ts.map +1 -0
- package/dist/overlay-adapter.js +72 -0
- package/dist/overlay-adapter.js.map +1 -0
- package/dist/overlay.d.ts +24 -0
- package/dist/overlay.d.ts.map +1 -0
- package/dist/overlay.js +210 -0
- package/dist/overlay.js.map +1 -0
- package/dist/position/position.d.ts +56 -0
- package/dist/position/position.d.ts.map +1 -0
- package/dist/position/position.js +194 -0
- package/dist/position/position.js.map +1 -0
- package/dist/scroll-area/scroll-area.d.ts +47 -0
- package/dist/scroll-area/scroll-area.d.ts.map +1 -0
- package/dist/scroll-area/scroll-area.js +332 -0
- package/dist/scroll-area/scroll-area.js.map +1 -0
- package/dist/segmented/segment.d.ts +23 -0
- package/dist/segmented/segment.d.ts.map +1 -0
- package/dist/segmented/segment.js +75 -0
- package/dist/segmented/segment.js.map +1 -0
- package/dist/segmented/segmented.d.ts +55 -0
- package/dist/segmented/segmented.d.ts.map +1 -0
- package/dist/segmented/segmented.js +265 -0
- package/dist/segmented/segmented.js.map +1 -0
- package/dist/select/option-model.d.ts +8 -0
- package/dist/select/option-model.d.ts.map +1 -0
- package/dist/select/option-model.js +11 -0
- package/dist/select/option-model.js.map +1 -0
- package/dist/select/option.d.ts +23 -0
- package/dist/select/option.d.ts.map +1 -0
- package/dist/select/option.js +58 -0
- package/dist/select/option.js.map +1 -0
- package/dist/select/select-panel.d.ts +35 -0
- package/dist/select/select-panel.d.ts.map +1 -0
- package/dist/select/select-panel.js +212 -0
- package/dist/select/select-panel.js.map +1 -0
- package/dist/select/select-popover.d.ts +32 -0
- package/dist/select/select-popover.d.ts.map +1 -0
- package/dist/select/select-popover.js +73 -0
- package/dist/select/select-popover.js.map +1 -0
- package/dist/select/select-position.d.ts +2 -0
- package/dist/select/select-position.d.ts.map +1 -0
- package/dist/select/select-position.js +2 -0
- package/dist/select/select-position.js.map +1 -0
- package/dist/select/select.d.ts +68 -0
- package/dist/select/select.d.ts.map +1 -0
- package/dist/select/select.js +413 -0
- package/dist/select/select.js.map +1 -0
- package/dist/slider/slider.d.ts +67 -0
- package/dist/slider/slider.d.ts.map +1 -0
- package/dist/slider/slider.js +380 -0
- package/dist/slider/slider.js.map +1 -0
- package/dist/styles/base.d.ts +22 -0
- package/dist/styles/base.d.ts.map +1 -0
- package/dist/styles/base.js +36 -0
- package/dist/styles/base.js.map +1 -0
- package/dist/styles.css +266 -0
- package/dist/switch/switch.d.ts +41 -0
- package/dist/switch/switch.d.ts.map +1 -0
- package/dist/switch/switch.js +182 -0
- package/dist/switch/switch.js.map +1 -0
- package/dist/table/column-menu.d.ts +35 -0
- package/dist/table/column-menu.d.ts.map +1 -0
- package/dist/table/column-menu.js +150 -0
- package/dist/table/column-menu.js.map +1 -0
- package/dist/table/table-builder.d.ts +15 -0
- package/dist/table/table-builder.d.ts.map +1 -0
- package/dist/table/table-builder.js +7 -0
- package/dist/table/table-builder.js.map +1 -0
- package/dist/table/table-cells.d.ts +22 -0
- package/dist/table/table-cells.d.ts.map +1 -0
- package/dist/table/table-cells.js +127 -0
- package/dist/table/table-cells.js.map +1 -0
- package/dist/table/table-focus.d.ts +5 -0
- package/dist/table/table-focus.d.ts.map +1 -0
- package/dist/table/table-focus.js +10 -0
- package/dist/table/table-focus.js.map +1 -0
- package/dist/table/table-geometry.d.ts +25 -0
- package/dist/table/table-geometry.d.ts.map +1 -0
- package/dist/table/table-geometry.js +36 -0
- package/dist/table/table-geometry.js.map +1 -0
- package/dist/table/table-state.d.ts +35 -0
- package/dist/table/table-state.d.ts.map +1 -0
- package/dist/table/table-state.js +265 -0
- package/dist/table/table-state.js.map +1 -0
- package/dist/table/table-test-geometry.d.ts +29 -0
- package/dist/table/table-test-geometry.d.ts.map +1 -0
- package/dist/table/table-test-geometry.js +108 -0
- package/dist/table/table-test-geometry.js.map +1 -0
- package/dist/table/table-types.d.ts +142 -0
- package/dist/table/table-types.d.ts.map +1 -0
- package/dist/table/table-types.js +8 -0
- package/dist/table/table-types.js.map +1 -0
- package/dist/table/table-virtualizer.d.ts +62 -0
- package/dist/table/table-virtualizer.d.ts.map +1 -0
- package/dist/table/table-virtualizer.js +289 -0
- package/dist/table/table-virtualizer.js.map +1 -0
- package/dist/table/table.d.ts +155 -0
- package/dist/table/table.d.ts.map +1 -0
- package/dist/table/table.js +1417 -0
- package/dist/table/table.js.map +1 -0
- package/dist/tabs/tab-panel.d.ts +21 -0
- package/dist/tabs/tab-panel.d.ts.map +1 -0
- package/dist/tabs/tab-panel.js +48 -0
- package/dist/tabs/tab-panel.js.map +1 -0
- package/dist/tabs/tab.d.ts +21 -0
- package/dist/tabs/tab.d.ts.map +1 -0
- package/dist/tabs/tab.js +80 -0
- package/dist/tabs/tab.js.map +1 -0
- package/dist/tabs/tabs.d.ts +52 -0
- package/dist/tabs/tabs.d.ts.map +1 -0
- package/dist/tabs/tabs.js +248 -0
- package/dist/tabs/tabs.js.map +1 -0
- package/dist/testing/harness.d.ts +12 -0
- package/dist/testing/harness.d.ts.map +1 -0
- package/dist/testing/harness.js +31 -0
- package/dist/testing/harness.js.map +1 -0
- package/dist/testing/index.d.ts +4 -0
- package/dist/testing/index.d.ts.map +1 -0
- package/dist/testing/index.js +19 -0
- package/dist/testing/index.js.map +1 -0
- package/dist/testing/setup.d.ts +2 -0
- package/dist/testing/setup.d.ts.map +1 -0
- package/dist/testing/setup.js +9 -0
- package/dist/testing/setup.js.map +1 -0
- package/dist/textarea/textarea.d.ts +59 -0
- package/dist/textarea/textarea.d.ts.map +1 -0
- package/dist/textarea/textarea.js +227 -0
- package/dist/textarea/textarea.js.map +1 -0
- package/dist/tokens-required.d.ts +3 -0
- package/dist/tokens-required.d.ts.map +1 -0
- package/dist/tokens-required.js +62 -0
- package/dist/tokens-required.js.map +1 -0
- package/dist/tooltip/tooltip.d.ts +52 -0
- package/dist/tooltip/tooltip.d.ts.map +1 -0
- package/dist/tooltip/tooltip.js +240 -0
- package/dist/tooltip/tooltip.js.map +1 -0
- package/package.json +75 -3
package/README.md
CHANGED
|
@@ -1,3 +1,675 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @mndw/ui
|
|
2
2
|
|
|
3
|
-
|
|
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`.
|
|
5
|
+
|
|
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.
|
|
364
|
+
|
|
365
|
+
### `<mndw-switch>`
|
|
366
|
+
|
|
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.
|
|
671
|
+
|
|
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()`.
|