@mistriwork/ui 1.0.0-rc.39 → 1.0.0-rc.40

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 (47) hide show
  1. package/dist/Avatar.d.ts +3 -1
  2. package/dist/Avatar.js +4 -1
  3. package/dist/Button.d.ts +13 -3
  4. package/dist/Button.js +9 -1
  5. package/dist/Choices.d.ts +11 -5
  6. package/dist/Choices.js +12 -5
  7. package/dist/DateField.d.ts +3 -1
  8. package/dist/DateField.js +4 -1
  9. package/dist/Drawer.d.ts +2 -1
  10. package/dist/Drawer.js +4 -1
  11. package/dist/DropMenu.d.ts +8 -4
  12. package/dist/DropMenu.js +10 -4
  13. package/dist/Dropdown.d.ts +4 -2
  14. package/dist/Dropdown.js +6 -2
  15. package/dist/Modal.d.ts +2 -1
  16. package/dist/Modal.js +4 -1
  17. package/dist/Pagination.d.ts +2 -1
  18. package/dist/Pagination.js +4 -1
  19. package/dist/Popover.d.ts +3 -1
  20. package/dist/Popover.js +4 -1
  21. package/dist/Select.d.ts +4 -2
  22. package/dist/Select.js +6 -2
  23. package/dist/SensitiveField.d.ts +3 -1
  24. package/dist/SensitiveField.js +4 -1
  25. package/dist/Slider.d.ts +3 -1
  26. package/dist/Slider.js +4 -1
  27. package/dist/Switch.d.ts +3 -1
  28. package/dist/Switch.js +4 -1
  29. package/dist/Tabs.d.ts +3 -1
  30. package/dist/Tabs.js +4 -1
  31. package/dist/TextField.d.ts +7 -3
  32. package/dist/TextField.js +8 -3
  33. package/dist/Tooltip.d.ts +3 -1
  34. package/dist/Tooltip.js +4 -1
  35. package/dist/Typeahead.d.ts +3 -2
  36. package/dist/Typeahead.js +4 -1
  37. package/dist/UiKit.d.ts +86 -0
  38. package/dist/UiKit.js +32 -0
  39. package/dist/conformance.d.ts +9 -0
  40. package/dist/conformance.js +470 -0
  41. package/dist/index.d.ts +3 -2
  42. package/dist/index.js +3 -1
  43. package/dist/internal/uiKitContext.d.ts +15 -0
  44. package/dist/internal/uiKitContext.js +23 -0
  45. package/dist/uiKitSlots.d.ts +13 -0
  46. package/dist/uiKitSlots.js +83 -0
  47. package/package.json +4 -1
@@ -0,0 +1,470 @@
1
+ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ /**
3
+ * The conformance suite a control kit is held to (Preview): what the platform's screens rely on from each slot,
4
+ * written as checks a test runner calls. A kit's own test file runs it —
5
+ *
6
+ * import { test } from 'vitest';
7
+ * import { uiKitConformance } from '@mistriwork/ui/conformance.js';
8
+ * import kit from './kit.js';
9
+ * uiKitConformance(kit, test);
10
+ *
11
+ * — in a DOM environment (happy-dom or jsdom). It imports no test library: the runner's `test` is handed in, a
12
+ * failure is a thrown Error that says which slot broke which promise, and the events are dispatched by hand the way a
13
+ * browser sends them, so a kit is judged by what a reader does rather than by how the kit is built.
14
+ *
15
+ * The roles are the contract, not the markup: a button is a `button`, a listbox lists `option`s, a menu `menuitem`s, a
16
+ * dialog is a `dialog` named by its `ariaLabel`. Every check renders through the kit with `UiKitProvider`, so a slot the
17
+ * kit leaves out is checked as the platform draws it; the default kit (`{}`) passes every check.
18
+ */
19
+ import { act, createRef, useState } from 'react';
20
+ import { createRoot } from 'react-dom/client';
21
+ import { Avatar } from './Avatar.js';
22
+ import { Button, ButtonLink } from './Button.js';
23
+ import { CheckCards, Checkbox, ChoiceCards, Consent, YesNo } from './Choices.js';
24
+ import { DateField } from './DateField.js';
25
+ import { Drawer } from './Drawer.js';
26
+ import { DropGroup, DropItem, DropMenu, DropSeparator } from './DropMenu.js';
27
+ import { Dropdown, MultiDropdown } from './Dropdown.js';
28
+ import { Modal } from './Modal.js';
29
+ import { Pagination } from './Pagination.js';
30
+ import { Popover } from './Popover.js';
31
+ import { MultiSelect, Select } from './Select.js';
32
+ import { SensitiveField } from './SensitiveField.js';
33
+ import { Slider } from './Slider.js';
34
+ import { Switch } from './Switch.js';
35
+ import { Tabs } from './Tabs.js';
36
+ import { MaskedField, MoneyField, TextField } from './TextField.js';
37
+ import { Tooltip } from './Tooltip.js';
38
+ import { Typeahead } from './Typeahead.js';
39
+ import { UiKitProvider } from './UiKit.js';
40
+ import { masks } from './masks.js';
41
+ /* ---- A browser's events, by hand ---- */
42
+ function fail(message) {
43
+ throw new Error(message);
44
+ }
45
+ function check(holds, message) {
46
+ if (!holds)
47
+ fail(message);
48
+ }
49
+ const settle = (ms = 0) => act(() => new Promise((done) => setTimeout(done, ms)));
50
+ /* Waits for something to appear (a popup is drawn after a frame or two), and says what never did. */
51
+ async function until(find, what, timeout = 1500) {
52
+ const end = Date.now() + timeout;
53
+ for (;;) {
54
+ const found = find();
55
+ if (found)
56
+ return found;
57
+ if (Date.now() > end)
58
+ fail(what);
59
+ await settle(10);
60
+ }
61
+ }
62
+ function pointer(type, init) {
63
+ return typeof PointerEvent === 'function'
64
+ ? new PointerEvent(type, { pointerType: 'mouse', isPrimary: true, ...init })
65
+ : new MouseEvent(type, init);
66
+ }
67
+ /* A press as a mouse makes one: the pointer and mouse events a press is made of, then the click. */
68
+ async function click(element) {
69
+ const init = { bubbles: true, cancelable: true, composed: true, button: 0, buttons: 1 };
70
+ await act(async () => {
71
+ element.dispatchEvent(pointer('pointerdown', init));
72
+ element.dispatchEvent(new MouseEvent('mousedown', init));
73
+ if (element instanceof HTMLElement && element.tabIndex >= 0)
74
+ element.focus();
75
+ element.dispatchEvent(pointer('pointerup', { ...init, buttons: 0 }));
76
+ element.dispatchEvent(new MouseEvent('mouseup', { ...init, buttons: 0 }));
77
+ element.dispatchEvent(new MouseEvent('click', { ...init, buttons: 0 }));
78
+ });
79
+ await settle();
80
+ }
81
+ /* A key on what has the focus; Enter and Space on a button activate it when nothing stopped them, as a browser does. */
82
+ async function press(key, target = document.activeElement) {
83
+ check(target, `nothing has the focus to press ${key} on`);
84
+ const init = { key, bubbles: true, cancelable: true, composed: true };
85
+ await act(async () => {
86
+ const down = new KeyboardEvent('keydown', init);
87
+ target.dispatchEvent(down);
88
+ const activates = key === 'Enter' || key === ' ';
89
+ if (activates && !down.defaultPrevented && target instanceof HTMLButtonElement && !target.disabled)
90
+ target.click();
91
+ target.dispatchEvent(new KeyboardEvent('keyup', init));
92
+ });
93
+ await settle();
94
+ }
95
+ /* Typing into a React-controlled box: the native setter, then the input event React listens for. */
96
+ async function type(input, text) {
97
+ const proto = input instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
98
+ await act(async () => {
99
+ input.focus();
100
+ Object.getOwnPropertyDescriptor(proto, 'value')?.set?.call(input, text);
101
+ input.dispatchEvent(new Event('input', { bubbles: true }));
102
+ });
103
+ await settle();
104
+ }
105
+ /* ---- Roles and names, read the way assistive technology reads them ---- */
106
+ const IMPLICIT = { BUTTON: 'button', TEXTAREA: 'textbox', SELECT: 'combobox', DIALOG: 'dialog', NAV: 'navigation' };
107
+ const INPUTS = { checkbox: 'checkbox', radio: 'radio', range: 'slider', button: 'button', submit: 'button' };
108
+ function roleOf(element) {
109
+ const explicit = element.getAttribute('role');
110
+ if (explicit)
111
+ return explicit.split(' ')[0];
112
+ if (element.tagName === 'A' && element.hasAttribute('href'))
113
+ return 'link';
114
+ if (element.tagName === 'INPUT') {
115
+ const kind = (element.getAttribute('type') ?? 'text').toLowerCase();
116
+ if (kind === 'hidden')
117
+ return undefined;
118
+ return INPUTS[kind] ?? (element.hasAttribute('list') ? 'combobox' : 'textbox');
119
+ }
120
+ return IMPLICIT[element.tagName];
121
+ }
122
+ const text = (element) => (element?.textContent ?? '').replace(/\s+/g, ' ').trim();
123
+ function nameOf(element) {
124
+ const label = element.getAttribute('aria-label');
125
+ if (label)
126
+ return label.trim();
127
+ const labelledBy = element.getAttribute('aria-labelledby');
128
+ if (labelledBy)
129
+ return labelledBy
130
+ .split(/\s+/)
131
+ .map((id) => text(document.getElementById(id)))
132
+ .join(' ')
133
+ .trim();
134
+ if (element.id) {
135
+ const forLabel = document.querySelector(`label[for="${CSS.escape(element.id)}"]`);
136
+ if (forLabel)
137
+ return text(forLabel);
138
+ }
139
+ const wrapping = element.closest('label');
140
+ if (wrapping && wrapping !== element)
141
+ return text(wrapping);
142
+ if (element instanceof HTMLInputElement && element.type !== 'button')
143
+ return element.title || element.placeholder || '';
144
+ return text(element) || element.getAttribute('title') || '';
145
+ }
146
+ const hidden = (element) => element.closest('[hidden], [aria-hidden="true"], [inert]') !== null;
147
+ function all(role, within = document.body) {
148
+ return [...within.querySelectorAll('*')].filter((element) => roleOf(element) === role && !hidden(element));
149
+ }
150
+ /* The first element with the role whose name starts with `name` (a listbox's button says its label and its value). */
151
+ function find(role, name, within = document.body) {
152
+ return all(role, within).find((element) => name === undefined || nameOf(element).startsWith(name));
153
+ }
154
+ function get(role, name, slot, within) {
155
+ return find(role, name, within) ?? fail(`${slot}: no ${role}${name ? ` named "${name}"` : ''} is drawn`);
156
+ }
157
+ function showsText(words, slot, within = document.body) {
158
+ check(within.textContent?.includes(words) ?? false, `${slot}: the words "${words}" it was given are not shown`);
159
+ }
160
+ function runner(kit, test) {
161
+ return (name, body) => test(`UI kit conformance: ${name}`, async () => {
162
+ globalThis.IS_REACT_ACT_ENVIRONMENT = true;
163
+ const roots = [];
164
+ const mount = async (node) => {
165
+ const host = document.body.appendChild(document.createElement('div'));
166
+ const root = createRoot(host);
167
+ roots.push({ root, host });
168
+ const draw = (n) => act(async () => root.render(_jsx(UiKitProvider, { kit: kit, children: n })));
169
+ await draw(node);
170
+ await settle();
171
+ return { host, rerender: draw };
172
+ };
173
+ try {
174
+ await body(mount);
175
+ }
176
+ finally {
177
+ for (const { root, host } of roots) {
178
+ await act(async () => root.unmount());
179
+ host.remove();
180
+ }
181
+ // A portal a kit forgot to take down would be read by the next check.
182
+ document.body.replaceChildren();
183
+ }
184
+ });
185
+ }
186
+ /* Records what a callback was told. */
187
+ function heard() {
188
+ const calls = [];
189
+ const fn = (...args) => {
190
+ calls.push(args);
191
+ };
192
+ return Object.assign(fn, { calls });
193
+ }
194
+ const DATE_WORDS = {
195
+ dateTimePattern: 'YYYY-MM-DD HH:MM',
196
+ enterDateAndTime: 'Enter a date and time.',
197
+ enterDate: (format) => `Enter a date as ${format}.`,
198
+ dateAndTimeFormat: 'Date and time format.',
199
+ dateFormat: (format) => `Date format: ${format}.`,
200
+ openWithKeys: 'Alt and Down arrow opens the calendar.',
201
+ chooseDate: (label) => `Pick a day for ${label ?? 'it'}`,
202
+ calendar: (label) => `Days of ${label ?? 'it'}`,
203
+ previousMonth: 'Month before',
204
+ nextMonth: 'Month after',
205
+ clear: 'Empty it',
206
+ today: 'This day',
207
+ };
208
+ const ITEMS = [
209
+ { value: 'low', label: 'Low' },
210
+ { value: 'high', label: 'High' },
211
+ ];
212
+ function Typed({ pick, onText }) {
213
+ const [typed, setTyped] = useState('');
214
+ const [open, setOpen] = useState(false);
215
+ return (_jsx(Typeahead, { text: typed, onText: (next) => {
216
+ onText?.(next);
217
+ setTyped(next);
218
+ setOpen(true);
219
+ }, items: ['Alder', 'Birch'].filter((item) => item.toLowerCase().startsWith(typed.toLowerCase())), itemKey: (item) => item, itemLabel: (item) => item, itemClassName: () => '', renderItem: (item) => item, onPick: (item) => {
220
+ pick(item);
221
+ setTyped(item);
222
+ setOpen(false);
223
+ }, open: open, onOpenChange: setOpen, inputProps: { 'aria-label': 'Tree' }, popupClassName: "conformance-popup", listClassName: "conformance-list" }));
224
+ }
225
+ function Menu({ run }) {
226
+ return (_jsxs(DropMenu, { label: "Row actions", children: [_jsxs(DropGroup, { label: "Change", children: [_jsx(DropItem, { onClick: () => run('edit'), children: "Edit row" }), _jsx(DropItem, { disabled: true, onClick: () => run('lock'), children: "Lock row" })] }), _jsx(DropSeparator, {}), _jsx(DropItem, { onClick: () => run('remove'), children: "Remove row" })] }));
227
+ }
228
+ /**
229
+ * Registers the conformance checks for `kit` with the runner's `test`. Each check names the slot and the promise it
230
+ * holds the slot to; a slot the kit leaves out is checked as the platform draws it.
231
+ */
232
+ export function uiKitConformance(kit, test) {
233
+ const it = runner(kit, test);
234
+ it('Button shows its words, is pressed, and refuses a press while disabled', async (mount) => {
235
+ const pressed = heard();
236
+ const { rerender } = await mount(_jsx(Button, { onClick: pressed, children: "Save changes" }));
237
+ await click(get('button', 'Save changes', 'Button'));
238
+ check(pressed.calls.length === 1, 'Button: a click did not reach onClick');
239
+ await rerender(_jsx(Button, { onClick: pressed, disabled: true, children: "Save changes" }));
240
+ await click(get('button', 'Save changes', 'Button'));
241
+ check(pressed.calls.length === 1, 'Button: a disabled button still ran onClick');
242
+ });
243
+ it('ButtonLink is a link to its address with its words', async (mount) => {
244
+ await mount(_jsx(ButtonLink, { href: "/files/report.csv", intent: "primary", children: "Download report" }));
245
+ const link = get('link', 'Download report', 'ButtonLink');
246
+ check(link.getAttribute('href') === '/files/report.csv', 'ButtonLink: the link does not go to its href');
247
+ });
248
+ it('TextField is named by its label, shows its value, reports what is typed, and is disabled when told', async (mount) => {
249
+ const changed = heard();
250
+ const { rerender } = await mount(_jsx(TextField, { label: "Company", hint: "As it is registered", value: "Acme", onChange: changed }));
251
+ showsText('As it is registered', 'TextField');
252
+ const box = get('textbox', 'Company', 'TextField');
253
+ check(box.value === 'Acme', `TextField: the box shows "${box.value}", not its value "Acme"`);
254
+ await type(box, 'Acme Ltd');
255
+ check(changed.calls.at(-1)?.[0] === 'Acme Ltd', 'TextField: onChange was not told the typed value');
256
+ await rerender(_jsx(TextField, { label: "Company", value: "Acme", onChange: changed, disabled: true }));
257
+ check(get('textbox', 'Company', 'TextField').disabled, 'TextField: disabled did not disable the box');
258
+ });
259
+ it('MaskedField shows its value through the mask and reports the raw value', async (mount) => {
260
+ const changed = heard();
261
+ await mount(_jsx(MaskedField, { label: "Phone", mask: masks.phone, value: "5551234567", onChange: changed }));
262
+ const box = get('textbox', 'Phone', 'MaskedField');
263
+ check(box.value === '555-123-4567', `MaskedField: the box shows "${box.value}", not the masked "555-123-4567"`);
264
+ await type(box, '555-123-9');
265
+ check(changed.calls.at(-1)?.[0] === '5551239', 'MaskedField: onChange was not told the raw value');
266
+ });
267
+ it('MoneyField and SensitiveField are named by their labels and say the words they are given', async (mount) => {
268
+ await mount(_jsxs(_Fragment, { children: [_jsx(MoneyField, { label: "Amount", value: "1200", onChange: () => { } }), _jsx(SensitiveField, { label: "Tax number", value: "123456789", onChange: () => { }, mask: masks.ssn, showLabel: "Reveal it", hideLabel: "Hide it" })] }));
269
+ get('textbox', 'Amount', 'MoneyField');
270
+ get('button', 'Reveal it', 'SensitiveField');
271
+ });
272
+ it('Checkbox and Consent are named by their labels, turn on when clicked, and are disabled when told', async (mount) => {
273
+ const ticked = heard();
274
+ const agreed = heard();
275
+ const { rerender } = await mount(_jsxs(_Fragment, { children: [_jsx(Checkbox, { label: "Send a copy", checked: false, onChange: ticked }), _jsx(Consent, { label: "I agree to the terms", checked: false, onChange: agreed })] }));
276
+ await click(get('checkbox', 'Send a copy', 'Checkbox'));
277
+ check(ticked.calls.at(-1)?.[0] === true, 'Checkbox: a click on an unchecked box did not report true');
278
+ await click(get('checkbox', 'I agree to the terms', 'Consent'));
279
+ check(agreed.calls.at(-1)?.[0] === true, 'Consent: a click on an unchecked box did not report true');
280
+ await rerender(_jsx(Checkbox, { label: "Send a copy", checked: true, onChange: ticked, disabled: true }));
281
+ const box = get('checkbox', 'Send a copy', 'Checkbox');
282
+ check(box.disabled || box.getAttribute('aria-disabled') === 'true', 'Checkbox: disabled did not disable the box');
283
+ });
284
+ it('YesNo, ChoiceCards and CheckCards say their words and report the pick', async (mount) => {
285
+ const answered = heard();
286
+ const chosen = heard();
287
+ const toggled = heard();
288
+ await mount(_jsxs(_Fragment, { children: [_jsx(YesNo, { label: "Is it urgent?", value: "", onChange: answered, yes: "Indeed", no: "Not at all" }), _jsx(ChoiceCards, { label: "Size", options: ITEMS, value: [], onChange: chosen }), _jsx(CheckCards, { cards: [
289
+ { key: 'a', label: 'Email me', on: false },
290
+ { key: 'b', label: 'Text me', on: false },
291
+ ], onToggle: toggled })] }));
292
+ showsText('Is it urgent?', 'YesNo');
293
+ await click(get('radio', 'Indeed', 'YesNo'));
294
+ check(answered.calls.at(-1)?.[0] === 'yes', 'YesNo: picking the yes word did not report "yes"');
295
+ await click(find('radio', 'High') ?? find('checkbox', 'High') ?? fail('ChoiceCards: no card named "High" is drawn'));
296
+ check(chosen.calls.at(-1)?.[0]?.join() === 'high', 'ChoiceCards: picking a card did not report its value');
297
+ await click(get('checkbox', 'Text me', 'CheckCards'));
298
+ check(toggled.calls.at(-1)?.join() === '1,true', 'CheckCards: turning the second card on did not report (1, true)');
299
+ });
300
+ it('Switch is named by its label, turns on when clicked, and is disabled when told', async (mount) => {
301
+ const switched = heard();
302
+ const { rerender } = await mount(_jsx(Switch, { label: "Notify the owner", checked: false, onCheckedChange: switched }));
303
+ await click(find('switch', 'Notify the owner') ?? get('checkbox', 'Notify the owner', 'Switch'));
304
+ check(switched.calls.at(-1)?.[0] === true, 'Switch: a click on an off switch did not report true');
305
+ await rerender(_jsx(Switch, { label: "Notify the owner", checked: false, onCheckedChange: switched, disabled: true }));
306
+ const control = find('switch', 'Notify the owner') ?? get('checkbox', 'Notify the owner', 'Switch');
307
+ check(control.disabled || control.getAttribute('aria-disabled') === 'true' || control.hasAttribute('data-disabled'), 'Switch: disabled did not disable the switch');
308
+ });
309
+ it('Slider is named by its label and shows its value', async (mount) => {
310
+ await mount(_jsx(Slider, { label: "Budget", value: 40, onChange: () => { }, min: 0, max: 100 }));
311
+ showsText('Budget', 'Slider');
312
+ showsText('40', 'Slider');
313
+ });
314
+ it('Dropdown says its choice, opens from the keyboard, reports a pick, closes on Escape, and is disabled when told', async (mount) => {
315
+ const changed = heard();
316
+ const { rerender } = await mount(_jsx(Dropdown, { ariaLabel: "Priority", items: ITEMS, value: "low", onChange: changed }));
317
+ const trigger = get('button', 'Priority', 'Dropdown');
318
+ showsText('Low', 'Dropdown', trigger);
319
+ trigger.focus();
320
+ await press('ArrowDown', trigger);
321
+ const list = await until(() => find('listbox'), 'Dropdown: ArrowDown on the button did not open a listbox');
322
+ check(all('option', list).map(text).join().includes('High'), 'Dropdown: the listbox does not list its items');
323
+ await press('Escape', document.activeElement ?? list);
324
+ await until(() => !find('listbox'), 'Dropdown: Escape did not close the listbox');
325
+ await until(() => document.activeElement === get('button', 'Priority', 'Dropdown'), 'Dropdown: Escape did not hand the focus back to its button');
326
+ await click(get('button', 'Priority', 'Dropdown'));
327
+ const option = await until(() => find('option', 'High'), 'Dropdown: a click on the button did not list the options');
328
+ await click(option);
329
+ check(changed.calls.at(-1)?.[0] === 'high', 'Dropdown: picking an option did not report its value');
330
+ await rerender(_jsx(Dropdown, { ariaLabel: "Priority", items: ITEMS, value: "low", onChange: changed, disabled: true }));
331
+ const off = get('button', 'Priority', 'Dropdown');
332
+ check(off.disabled || off.getAttribute('aria-disabled') === 'true', 'Dropdown: disabled did not disable its button');
333
+ });
334
+ it('Select, MultiSelect and MultiDropdown are named and say their choices', async (mount) => {
335
+ await mount(_jsxs(_Fragment, { children: [_jsx(Select, { label: "Stage", options: ITEMS, value: "high", onChange: () => { } }), _jsx(MultiSelect, { label: "Tags", options: ITEMS, value: ['low'], onChange: () => { } }), _jsx(MultiDropdown, { ariaLabel: "Levels", items: ITEMS, value: ['high'], onChange: () => { } })] }));
336
+ showsText('Stage', 'Select');
337
+ showsText('High', 'Select', get('button', 'Stage', 'Select'));
338
+ showsText('Low', 'MultiSelect', get('button', 'Tags', 'MultiSelect'));
339
+ showsText('High', 'MultiDropdown', get('button', 'Levels', 'MultiDropdown'));
340
+ });
341
+ it('Typeahead reports typing, lists matches, and picks the lit one with the keyboard', async (mount) => {
342
+ const picked = heard();
343
+ const typed = heard();
344
+ await mount(_jsx(Typed, { pick: picked, onText: typed }));
345
+ const box = get('combobox', 'Tree', 'Typeahead');
346
+ await type(box, 'b');
347
+ check(typed.calls.at(-1)?.[0] === 'b', 'Typeahead: onText was not told the typed text');
348
+ const list = await until(() => find('listbox'), 'Typeahead: typing did not open a list of matches');
349
+ check(all('option', list).map(text).join() === 'Birch', 'Typeahead: the list does not show the matching item');
350
+ await press('ArrowDown', box);
351
+ await press('Enter', box);
352
+ await until(() => picked.calls.at(-1)?.[0] === 'Birch', 'Typeahead: ArrowDown then Enter did not pick the lit item');
353
+ });
354
+ it('DateField shows its value, reports what is typed, names its calendar button with its words, and is disabled when told', async (mount) => {
355
+ const changed = heard();
356
+ const { rerender } = await mount(_jsx(DateField, { id: "due", "aria-label": "Due", words: DATE_WORDS, calendarIcon: null, value: "2026-03-14", onChange: changed, locale: "en-US" }));
357
+ const box = get('textbox', 'Due', 'DateField');
358
+ check(box.value.length > 0, 'DateField: the box does not show its value');
359
+ await type(box, '2026-04-01');
360
+ check(changed.calls.at(-1)?.[0] === '2026-04-01', 'DateField: onChange was not told the typed text');
361
+ get('button', 'Pick a day for', 'DateField');
362
+ await rerender(_jsx(DateField, { id: "due", "aria-label": "Due", words: DATE_WORDS, calendarIcon: null, value: "2026-03-14", onChange: changed, locale: "en-US", disabled: true }));
363
+ check(get('textbox', 'Due', 'DateField').disabled, 'DateField: disabled did not disable the box');
364
+ });
365
+ it('Modal is a dialog named by ariaLabel; Escape and its handle close it once; the focus goes back', async (mount) => {
366
+ const closed = heard();
367
+ const handle = createRef();
368
+ const { host } = await mount(_jsx("button", { type: "button", children: "Opener" }));
369
+ const opener = get('button', 'Opener', 'Modal', host);
370
+ opener.focus();
371
+ const { rerender } = await mount(_jsxs(Modal, { ariaLabel: "Edit the row", onClose: closed, ref: handle, children: [_jsx("p", { children: "The row's fields" }), _jsx("button", { type: "button", children: "Inside" })] }));
372
+ const dialog = await until(() => find('dialog', 'Edit the row'), 'Modal: no dialog named by its ariaLabel is drawn');
373
+ showsText("The row's fields", 'Modal', dialog);
374
+ await until(() => dialog.contains(document.activeElement), 'Modal: the focus did not move into the dialog when it opened');
375
+ await press('Escape', document.activeElement ?? dialog);
376
+ check(closed.calls.length === 1, `Modal: Escape told onClose ${closed.calls.length} times, not once`);
377
+ await rerender(null);
378
+ await until(() => document.activeElement === opener, 'Modal: the focus did not go back to what had it before the dialog opened');
379
+ const again = heard();
380
+ await rerender(_jsx(Modal, { ariaLabel: "Edit the row", onClose: again, ref: handle, beforeClose: () => false, children: _jsx("button", { type: "button", children: "Inside" }) }));
381
+ await until(() => handle.current, 'Modal: ref was not given a handle');
382
+ await act(async () => handle.current?.close());
383
+ check(again.calls.length === 0, 'Modal: the handle closed it though beforeClose said no');
384
+ const twice = heard();
385
+ await rerender(_jsx(Modal, { ariaLabel: "Edit the row", onClose: twice, ref: handle, children: _jsx("button", { type: "button", children: "Inside" }) }));
386
+ await act(async () => {
387
+ handle.current?.close();
388
+ handle.current?.close();
389
+ });
390
+ await settle();
391
+ check(twice.calls.length === 1, `Modal: closing by its handle twice told onClose ${twice.calls.length} times, not once`);
392
+ });
393
+ it('Drawer is a dialog with its title and its close word', async (mount) => {
394
+ const changed = heard();
395
+ await mount(_jsx(Drawer, { open: true, title: "Filters", closeLabel: "Put it away", onOpenChange: changed, children: _jsx("p", { children: "Pick what to show" }) }));
396
+ const dialog = await until(() => find('dialog'), 'Drawer: no dialog is drawn while open');
397
+ showsText('Filters', 'Drawer', dialog);
398
+ showsText('Pick what to show', 'Drawer', dialog);
399
+ await click(get('button', 'Put it away', 'Drawer', dialog));
400
+ check(changed.calls.at(-1)?.[0] === false, 'Drawer: its close button did not report onOpenChange(false)');
401
+ });
402
+ it('Popover and Tooltip draw their trigger, and an open popover its content', async (mount) => {
403
+ await mount(_jsxs(_Fragment, { children: [_jsx(Popover, { trigger: _jsx("span", { children: "More about it" }), open: true, ariaLabel: "Details", children: _jsx("p", { children: "The long story" }) }), _jsx(Tooltip, { trigger: _jsx("span", { children: "Hover me" }), children: "A short note" })] }));
404
+ showsText('More about it', 'Popover');
405
+ showsText('Hover me', 'Tooltip');
406
+ await until(() => document.body.textContent?.includes('The long story'), 'Popover: an open popover does not show its content');
407
+ });
408
+ it('DropMenu opens from the keyboard, runs an item, skips a disabled one, and closes on Escape', async (mount) => {
409
+ const ran = heard();
410
+ await mount(_jsx(Menu, { run: ran }));
411
+ const trigger = get('button', 'Row actions', 'DropMenu');
412
+ trigger.focus();
413
+ await press('ArrowDown', trigger);
414
+ const menu = await until(() => find('menu'), 'DropMenu: ArrowDown on the trigger did not open a menu');
415
+ check(all('menuitem', menu).map(text).join() === 'Edit row,Lock row,Remove row', 'DropMenu: the menu does not list its items in order');
416
+ get('group', 'Change', 'DropGroup', menu);
417
+ get('separator', undefined, 'DropSeparator', menu);
418
+ const locked = get('menuitem', 'Lock row', 'DropItem', menu);
419
+ check(locked.getAttribute('aria-disabled') === 'true' || locked.disabled, 'DropItem: a disabled item is not marked disabled');
420
+ await press('Escape', document.activeElement ?? menu);
421
+ await until(() => !find('menu'), 'DropMenu: Escape did not close the menu');
422
+ await until(() => document.activeElement === get('button', 'Row actions', 'DropMenu'), 'DropMenu: Escape did not hand the focus back to the trigger');
423
+ await click(get('button', 'Row actions', 'DropMenu'));
424
+ await click(await until(() => find('menuitem', 'Remove row'), 'DropMenu: a click on the trigger did not open the menu'));
425
+ check(ran.calls.at(-1)?.[0] === 'remove', 'DropItem: clicking an item did not run it');
426
+ await until(() => !find('menu'), 'DropMenu: running an item did not close the menu');
427
+ });
428
+ it("popups opened inside a dialog are drawn inside it, in the dialog's focus trap", async (mount) => {
429
+ await mount(_jsxs("div", { role: "dialog", "aria-label": "Enclosing", "data-conformance-dialog": "", children: [_jsx(Dropdown, { ariaLabel: "Priority", items: ITEMS, value: "low", onChange: () => { } }), _jsx(Menu, { run: () => { } }), _jsx(Typed, { pick: () => { } })] }));
430
+ const dialog = document.querySelector('[data-conformance-dialog]') ?? fail('the enclosing dialog is gone');
431
+ await click(get('button', 'Priority', 'Dropdown', dialog));
432
+ const list = await until(() => find('listbox'), 'Dropdown: a click did not open its listbox inside a dialog');
433
+ check(dialog.contains(list), 'Dropdown: its listbox was drawn outside the dialog it was opened in');
434
+ await press('Escape', document.activeElement ?? list);
435
+ await until(() => !find('listbox'), 'Dropdown: Escape did not close the listbox');
436
+ await click(get('button', 'Row actions', 'DropMenu', dialog));
437
+ const menu = await until(() => find('menu'), 'DropMenu: a click did not open its menu inside a dialog');
438
+ check(dialog.contains(menu), 'DropMenu: its menu was drawn outside the dialog it was opened in');
439
+ await press('Escape', document.activeElement ?? menu);
440
+ await until(() => !find('menu'), 'DropMenu: Escape did not close the menu');
441
+ await type(get('combobox', 'Tree', 'Typeahead', dialog), 'a');
442
+ const matches = await until(() => find('listbox'), 'Typeahead: typing did not open its list inside a dialog');
443
+ check(dialog.contains(matches), 'Typeahead: its list was drawn outside the dialog it was opened in');
444
+ });
445
+ it('Tabs name their tabs, and choosing one reports it and shows its panel', async (mount) => {
446
+ const chose = heard();
447
+ await mount(_jsx(Tabs, { ariaLabel: "Record sections", defaultValue: "details", onValueChange: chose, tabs: [
448
+ { value: 'details', label: 'Details', children: _jsx("p", { children: "The details panel" }) },
449
+ { value: 'history', label: 'History', children: _jsx("p", { children: "The history panel" }) },
450
+ ] }));
451
+ get('tab', 'Details', 'Tabs');
452
+ showsText('The details panel', 'Tabs');
453
+ await click(get('tab', 'History', 'Tabs'));
454
+ check(chose.calls.at(-1)?.[0] === 'history', 'Tabs: choosing a tab did not report its value');
455
+ await until(() => document.body.textContent?.includes('The history panel'), 'Tabs: the chosen tab does not show its panel');
456
+ });
457
+ it('Pagination says its words and reports the page asked for', async (mount) => {
458
+ const went = heard();
459
+ await mount(_jsx(Pagination, { page: 2, pages: 5, onPageChange: went, ariaLabel: "Invoices, pages", words: { previous: 'Earlier', next: 'Later' } }));
460
+ get('navigation', 'Invoices, pages', 'Pagination');
461
+ await click(get('button', 'Later', 'Pagination'));
462
+ check(went.calls.at(-1)?.[0] === 3, 'Pagination: its next button did not ask for the next page');
463
+ await click(get('button', 'Earlier', 'Pagination'));
464
+ check(went.calls.at(-1)?.[0] === 1, 'Pagination: its previous button did not ask for the page before');
465
+ });
466
+ it('Avatar draws a picture or the initials of its name', async (mount) => {
467
+ const { host } = await mount(_jsx(Avatar, { name: "Ada Lovelace" }));
468
+ check(host.textContent?.includes('AL') || host.querySelector('img, svg, [role="img"]'), 'Avatar: neither initials nor a picture is drawn');
469
+ });
470
+ }
package/dist/index.d.ts CHANGED
@@ -5,12 +5,12 @@
5
5
  * icons, its answers and its hooks are props (scripts/check-boundary.mjs holds the `ui` layer to importing only
6
6
  * itself).
7
7
  */
8
- export { Button, buttonClass, type ButtonIntent, type ButtonSize } from './Button.js';
8
+ export { Button, ButtonLink, buttonClass, type ButtonIntent, type ButtonLinkProps, type ButtonProps, type ButtonSize } from './Button.js';
9
9
  export { Field, type AnswerKind, type FieldControlProps } from './Field.js';
10
10
  export { Modal, type ModalHandle } from './Modal.js';
11
11
  export { DropMenu, DropGroup, DropItem, DropSeparator } from './DropMenu.js';
12
12
  export { Dropdown, MultiDropdown, type DropdownAction, type DropdownItem, type DropdownProps, type MultiDropdownProps, } from './Dropdown.js';
13
- export { Typeahead } from './Typeahead.js';
13
+ export { Typeahead, type TypeaheadProps } from './Typeahead.js';
14
14
  export { Icon, loadIconsWith, registerIcons, weighIconsWith, type IconGlyph, type IconProps, type IconWeight, type IconWeighting, } from './Icon.js';
15
15
  export { DateField, type DateFieldProps, type DateFieldWords } from './DateField.js';
16
16
  export type { FieldFrame } from './fieldFrame.js';
@@ -37,3 +37,4 @@ export { Carousel, type CarouselProps, type CarouselSlide } from './Carousel.js'
37
37
  export { Resizable, type ResizablePanel, type ResizableProps } from './Resizable.js';
38
38
  export { ScrollArea, type ScrollAreaProps } from './ScrollArea.js';
39
39
  export { Tooltip, type TooltipProps } from './Tooltip.js';
40
+ export { SLOT_NAMES, UiKitProvider, defaultUiKit, defineUiKit, installUiKit, uiKitProblems, type SlotName, type UiKit, type UiKitSlots, } from './UiKit.js';
package/dist/index.js CHANGED
@@ -5,7 +5,7 @@
5
5
  * icons, its answers and its hooks are props (scripts/check-boundary.mjs holds the `ui` layer to importing only
6
6
  * itself).
7
7
  */
8
- export { Button, buttonClass } from './Button.js';
8
+ export { Button, ButtonLink, buttonClass } from './Button.js';
9
9
  export { Field } from './Field.js';
10
10
  export { Modal } from './Modal.js';
11
11
  export { DropMenu, DropGroup, DropItem, DropSeparator } from './DropMenu.js';
@@ -39,3 +39,5 @@ export { Carousel } from './Carousel.js';
39
39
  export { Resizable } from './Resizable.js';
40
40
  export { ScrollArea } from './ScrollArea.js';
41
41
  export { Tooltip } from './Tooltip.js';
42
+ /* The seam a control kit plugs into: the slots, their props, and a kit's declaration. Preview. */
43
+ export { SLOT_NAMES, UiKitProvider, defaultUiKit, defineUiKit, installUiKit, uiKitProblems, } from './UiKit.js';
@@ -0,0 +1,15 @@
1
+ /**
2
+ * The seam a control kit plugs into (UiKit.tsx): every slotted primitive reads this one context and draws the kit's
3
+ * component for its slot when there is one, its own otherwise, with the same props. The context's default value is
4
+ * the installed kit, so a page that installs one before its first render needs no provider anywhere: nothing
5
+ * re-renders, because nothing changes after paint (a control that swapped once drawn would shift the page).
6
+ */
7
+ import { type ComponentType } from 'react';
8
+ type AnyComponent = ComponentType<any>;
9
+ /** The primitives' own drawing, by slot, filled as each slotted module loads. */
10
+ export declare const defaultSlots: Record<string, AnyComponent>;
11
+ export declare const UiKitContext: import("react").Context<Record<string, AnyComponent | undefined>>;
12
+ /** Puts a kit in place for every render that has no provider above it; called once, before the first render. */
13
+ export declare function installUiKit(kit: Record<string, AnyComponent | undefined> | undefined): void;
14
+ export declare function slotted<C extends AnyComponent>(name: string, Default: C): C;
15
+ export {};
@@ -0,0 +1,23 @@
1
+ /**
2
+ * The seam a control kit plugs into (UiKit.tsx): every slotted primitive reads this one context and draws the kit's
3
+ * component for its slot when there is one, its own otherwise, with the same props. The context's default value is
4
+ * the installed kit, so a page that installs one before its first render needs no provider anywhere: nothing
5
+ * re-renders, because nothing changes after paint (a control that swapped once drawn would shift the page).
6
+ */
7
+ import { createContext, createElement, useContext } from 'react';
8
+ const installed = {};
9
+ /** The primitives' own drawing, by slot, filled as each slotted module loads. */
10
+ export const defaultSlots = {};
11
+ export const UiKitContext = createContext(installed);
12
+ /** Puts a kit in place for every render that has no provider above it; called once, before the first render. */
13
+ export function installUiKit(kit) {
14
+ for (const name of Object.keys(installed))
15
+ delete installed[name];
16
+ Object.assign(installed, kit);
17
+ }
18
+ /* The wrapper is the whole cost of the seam on a page without a kit: one context read and one element. React 19
19
+ carries `ref` as a prop, so a handle (Modal's) and a forwarded element ref (Button's) pass through untouched. */
20
+ export function slotted(name, Default) {
21
+ defaultSlots[name] = Default;
22
+ return ((props) => createElement(useContext(UiKitContext)[name] ?? Default, props));
23
+ }
@@ -0,0 +1,13 @@
1
+ /**
2
+ * The slots a control kit may fill and the rules a kit is held to before it draws (UiKit.tsx, Preview), in a module
3
+ * with no React and no primitive in it: an App's load and `mistri check` judge a kit with these on the server, where
4
+ * an App's own typecheck follows the import and has no JSX to read a primitive's module with.
5
+ */
6
+ /** Every slot a kit may fill, in the order the docs list them. */
7
+ export declare const SLOT_NAMES: readonly ['Button', 'ButtonLink', 'TextField', 'MaskedField', 'MoneyField', 'SensitiveField', 'Select', 'MultiSelect', 'Dropdown', 'MultiDropdown', 'Typeahead', 'DateField', 'Checkbox', 'YesNo', 'ChoiceCards', 'CheckCards', 'Consent', 'Switch', 'Slider', 'Modal', 'Drawer', 'Popover', 'Tooltip', 'DropMenu', 'DropGroup', 'DropItem', 'DropSeparator', 'Tabs', 'Pagination', 'Avatar'];
8
+ export type SlotName = (typeof SLOT_NAMES)[number];
9
+ /**
10
+ * What is wrong with a value offered as a kit, each as the rest of a sentence that begins with the kit's name ("the
11
+ * UI kit (./ui/kit.tsx) has no slot named …"); none for a kit. `mistri check` and an App's load say the same.
12
+ */
13
+ export declare function uiKitProblems(value: unknown): string[];