@mistriwork/ui 1.0.0-rc.46 → 1.0.0-rc.48

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 (48) hide show
  1. package/dist/Carousel.d.ts +2 -1
  2. package/dist/Carousel.js +9 -8
  3. package/dist/Choices.d.ts +5 -4
  4. package/dist/Choices.js +18 -16
  5. package/dist/DateField.d.ts +8 -3
  6. package/dist/DateField.js +17 -14
  7. package/dist/Drawer.d.ts +2 -1
  8. package/dist/Drawer.js +4 -3
  9. package/dist/DropMenu.d.ts +2 -1
  10. package/dist/DropMenu.js +3 -2
  11. package/dist/Dropdown.d.ts +8 -3
  12. package/dist/Dropdown.js +10 -6
  13. package/dist/FileField.d.ts +3 -2
  14. package/dist/FileField.js +4 -2
  15. package/dist/Pagination.d.ts +2 -1
  16. package/dist/Pagination.js +3 -2
  17. package/dist/Popover.d.ts +2 -1
  18. package/dist/Popover.js +3 -2
  19. package/dist/Resizable.d.ts +2 -1
  20. package/dist/Resizable.js +10 -9
  21. package/dist/Select.d.ts +3 -3
  22. package/dist/Select.js +2 -2
  23. package/dist/SensitiveField.d.ts +2 -1
  24. package/dist/SensitiveField.js +6 -5
  25. package/dist/Slider.d.ts +2 -1
  26. package/dist/Slider.js +3 -2
  27. package/dist/Switch.d.ts +2 -2
  28. package/dist/Switch.js +4 -3
  29. package/dist/Tabs.d.ts +5 -2
  30. package/dist/Tabs.js +3 -2
  31. package/dist/TextField.d.ts +3 -2
  32. package/dist/TextField.js +6 -5
  33. package/dist/Tooltip.d.ts +2 -1
  34. package/dist/Tooltip.js +3 -3
  35. package/dist/Typeahead.d.ts +5 -2
  36. package/dist/Typeahead.js +31 -10
  37. package/dist/UiKit.d.ts +8 -2
  38. package/dist/changeDetails.d.ts +28 -0
  39. package/dist/changeDetails.js +54 -0
  40. package/dist/conformance.d.ts +1 -1
  41. package/dist/conformance.js +83 -5
  42. package/dist/conformancePatterns.d.ts +27 -0
  43. package/dist/conformancePatterns.js +421 -0
  44. package/dist/index.d.ts +4 -3
  45. package/dist/index.js +2 -0
  46. package/dist/internal/uiKitContext.d.ts +4 -1
  47. package/dist/internal/uiKitContext.js +49 -3
  48. package/package.json +1 -1
@@ -0,0 +1,54 @@
1
+ /* The hand behind an event that does not say so itself: an `input` from a range dragged or typed, a `change` from a
2
+ native select. The last key or pointer press on the page is that hand, as a browser's own :focus-visible guesses. */
3
+ let lastHand = 'program';
4
+ let listening = false;
5
+ function listen() {
6
+ if (listening || typeof document === 'undefined')
7
+ return;
8
+ listening = true;
9
+ document.addEventListener('keydown', () => (lastHand = 'keyboard'), { capture: true, passive: true });
10
+ document.addEventListener('pointerdown', () => (lastHand = 'pointer'), { capture: true, passive: true });
11
+ }
12
+ // From load, not from the first change: that change's own press came before anything asked.
13
+ listen();
14
+ /* The one fallback for every change that came from a person's hand but whose hand cannot be read off its own event: the
15
+ last key or pointer press on the page, and a pointer where there has been none yet (an autofill, a change before any
16
+ press). A change that carries an event, or that a kit reports, is never `program`: only a change with no event is. */
17
+ function lastKnownHand() {
18
+ listen();
19
+ return lastHand === 'program' ? 'pointer' : lastHand;
20
+ }
21
+ /** The hand behind an event: `program` when there is none. */
22
+ export function changeSource(event) {
23
+ if (!event)
24
+ return 'program';
25
+ if (typeof KeyboardEvent !== 'undefined' && event instanceof KeyboardEvent)
26
+ return 'keyboard';
27
+ /* Enter and Space on a button arrive as a click that counted no presses, but so does a pointer's click where nothing
28
+ counts them (a test's synthetic one), so the press that came before it decides. */
29
+ if (event.type === 'click' && event.detail === 0)
30
+ return lastKnownHand();
31
+ if (typeof MouseEvent !== 'undefined' && event instanceof MouseEvent)
32
+ return 'pointer';
33
+ if (typeof TouchEvent !== 'undefined' && event instanceof TouchEvent)
34
+ return 'pointer';
35
+ return lastKnownHand();
36
+ }
37
+ /** Details for a change this module's own code makes: a React event's native event, or none when the page did it. */
38
+ export function changeDetails(reason, event) {
39
+ // Typed by hand: the client's JSDoc check reads this module without strict null checks, and loses the narrowing.
40
+ const native = event && 'nativeEvent' in event ? event.nativeEvent : event;
41
+ return native ? { reason, source: changeSource(native), event: native } : { reason, source: 'program' };
42
+ }
43
+ /* Details for a change a control kit reported without them (a kit may leave them out). The change came from the kit's
44
+ control, so it was a person's hand, not the page's: a caller that skips `program` changes must not skip these too.
45
+ The last key or pointer press is the best word for which hand. */
46
+ export function keptDetails(reason) {
47
+ return { reason, source: lastKnownHand() };
48
+ }
49
+ export function fromBaseUi(details, own) {
50
+ const reason = details.reason === 'none' ? own : details.reason;
51
+ // Base UI stands an Event named `base-ui` in for the one it did not have: the page made that change.
52
+ const event = details.event?.type === 'base-ui' ? undefined : details.event;
53
+ return event ? { reason, source: changeSource(event), event } : { reason, source: 'program' };
54
+ }
@@ -1,4 +1,5 @@
1
1
  import { type UiKit } from './UiKit.js';
2
+ export { checkPatterns, type CheckPatternsOptions } from './conformancePatterns.js';
2
3
  /** The runner's `test` (Vitest's, Jest's, node:test's): a name and an async body. */
3
4
  type ConformanceTest = (name: string, body: () => Promise<void>) => unknown;
4
5
  /**
@@ -6,4 +7,3 @@ type ConformanceTest = (name: string, body: () => Promise<void>) => unknown;
6
7
  * holds the slot to; a slot the kit leaves out is checked as the platform draws it.
7
8
  */
8
9
  export declare function uiKitConformance(kit: UiKit, test: ConformanceTest): void;
9
- export {};
@@ -37,7 +37,9 @@ import { MaskedField, MoneyField, TextField } from './TextField.js';
37
37
  import { Tooltip } from './Tooltip.js';
38
38
  import { Typeahead } from './Typeahead.js';
39
39
  import { UiKitProvider } from './UiKit.js';
40
+ import { checkPatterns } from './conformancePatterns.js';
40
41
  import { masks } from './masks.js';
42
+ export { checkPatterns } from './conformancePatterns.js';
41
43
  /* ---- A browser's events, by hand ---- */
42
44
  function fail(message) {
43
45
  throw new Error(message);
@@ -102,6 +104,11 @@ async function type(input, text) {
102
104
  });
103
105
  await settle();
104
106
  }
107
+ /* The page as it stands, held to the ARIA patterns (conformancePatterns.ts), its keys pressed inside `act`. */
108
+ async function patterns(slot) {
109
+ const problems = await checkPatterns(document.body, { act: (step) => act(step) });
110
+ check(problems.length === 0, `${slot}: ${problems.join('; ')}`);
111
+ }
105
112
  /* ---- Roles and names, read the way assistive technology reads them ---- */
106
113
  const IMPLICIT = { BUTTON: 'button', TEXTAREA: 'textbox', SELECT: 'combobox', DIALOG: 'dialog', NAV: 'navigation' };
107
114
  const INPUTS = { checkbox: 'checkbox', radio: 'radio', range: 'slider', button: 'button', submit: 'button' };
@@ -191,6 +198,21 @@ function heard() {
191
198
  };
192
199
  return Object.assign(fn, { calls });
193
200
  }
201
+ /* A change callback's details, where the kit gave them: a kit may leave them out (the seam fills them in), but what it
202
+ gives must be the shape every caller reads, not an event or a word of its own in their place. */
203
+ function heardDetails(callback, at, what) {
204
+ for (const args of callback.calls) {
205
+ const details = args[at];
206
+ if (details === undefined)
207
+ continue;
208
+ check(typeof details === 'object' &&
209
+ details !== null &&
210
+ typeof details.reason === 'string' &&
211
+ details.reason !== '' &&
212
+ (details.source === 'pointer' || details.source === 'keyboard' || details.source === 'program') &&
213
+ (details.event === undefined || details.event instanceof Event), `${what}: its second word is not change details, { reason, source, event? }`);
214
+ }
215
+ }
194
216
  const DATE_WORDS = {
195
217
  dateTimePattern: 'YYYY-MM-DD HH:MM',
196
218
  enterDateAndTime: 'Enter a date and time.',
@@ -209,18 +231,18 @@ const ITEMS = [
209
231
  { value: 'low', label: 'Low' },
210
232
  { value: 'high', label: 'High' },
211
233
  ];
212
- function Typed({ pick, onText }) {
234
+ function Typed({ pick, onText, empty, }) {
213
235
  const [typed, setTyped] = useState('');
214
236
  const [open, setOpen] = useState(false);
215
- return (_jsx(Typeahead, { text: typed, onText: (next) => {
216
- onText?.(next);
237
+ return (_jsx(Typeahead, { text: typed, onText: (next, details) => {
238
+ onText?.(next, details);
217
239
  setTyped(next);
218
240
  setOpen(true);
219
241
  }, items: ['Alder', 'Birch'].filter((item) => item.toLowerCase().startsWith(typed.toLowerCase())), itemKey: (item) => item, itemLabel: (item) => item, itemClassName: () => '', renderItem: (item) => item, onPick: (item) => {
220
242
  pick(item);
221
243
  setTyped(item);
222
244
  setOpen(false);
223
- }, open: open, onOpenChange: setOpen, inputProps: { 'aria-label': 'Tree' }, popupClassName: "conformance-popup", listClassName: "conformance-list" }));
245
+ }, open: open, onOpenChange: setOpen, inputProps: { 'aria-label': 'Tree' }, popupClassName: "conformance-popup", listClassName: "conformance-list", empty: empty }));
224
246
  }
225
247
  function Menu({ run }) {
226
248
  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" })] }));
@@ -253,6 +275,7 @@ export function uiKitConformance(kit, test) {
253
275
  check(box.value === 'Acme', `TextField: the box shows "${box.value}", not its value "Acme"`);
254
276
  await type(box, 'Acme Ltd');
255
277
  check(changed.calls.at(-1)?.[0] === 'Acme Ltd', 'TextField: onChange was not told the typed value');
278
+ heardDetails(changed, 1, 'TextField: onChange');
256
279
  await rerender(_jsx(TextField, { label: "Company", value: "Acme", onChange: changed, disabled: true }));
257
280
  check(get('textbox', 'Company', 'TextField').disabled, 'TextField: disabled did not disable the box');
258
281
  });
@@ -263,6 +286,7 @@ export function uiKitConformance(kit, test) {
263
286
  check(box.value === '555-123-4567', `MaskedField: the box shows "${box.value}", not the masked "555-123-4567"`);
264
287
  await type(box, '555-123-9');
265
288
  check(changed.calls.at(-1)?.[0] === '5551239', 'MaskedField: onChange was not told the raw value');
289
+ heardDetails(changed, 1, 'MaskedField: onChange');
266
290
  });
267
291
  it('MoneyField and SensitiveField are named by their labels and say the words they are given', async (mount) => {
268
292
  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" })] }));
@@ -277,6 +301,8 @@ export function uiKitConformance(kit, test) {
277
301
  check(ticked.calls.at(-1)?.[0] === true, 'Checkbox: a click on an unchecked box did not report true');
278
302
  await click(get('checkbox', 'I agree to the terms', 'Consent'));
279
303
  check(agreed.calls.at(-1)?.[0] === true, 'Consent: a click on an unchecked box did not report true');
304
+ heardDetails(ticked, 1, 'Checkbox: onChange');
305
+ heardDetails(agreed, 1, 'Consent: onChange');
280
306
  await rerender(_jsx(Checkbox, { label: "Send a copy", checked: true, onChange: ticked, disabled: true }));
281
307
  const box = get('checkbox', 'Send a copy', 'Checkbox');
282
308
  check(box.disabled || box.getAttribute('aria-disabled') === 'true', 'Checkbox: disabled did not disable the box');
@@ -295,13 +321,17 @@ export function uiKitConformance(kit, test) {
295
321
  await click(find('radio', 'High') ?? find('checkbox', 'High') ?? fail('ChoiceCards: no card named "High" is drawn'));
296
322
  check(chosen.calls.at(-1)?.[0]?.join() === 'high', 'ChoiceCards: picking a card did not report its value');
297
323
  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)');
324
+ check(toggled.calls.at(-1)?.slice(0, 2).join() === '1,true', 'CheckCards: turning the second card on did not report (1, true)');
325
+ heardDetails(answered, 1, 'YesNo: onChange');
326
+ heardDetails(chosen, 1, 'ChoiceCards: onChange');
327
+ heardDetails(toggled, 2, 'CheckCards: onToggle');
299
328
  });
300
329
  it('Switch is named by its label, turns on when clicked, and is disabled when told', async (mount) => {
301
330
  const switched = heard();
302
331
  const { rerender } = await mount(_jsx(Switch, { label: "Notify the owner", checked: false, onCheckedChange: switched }));
303
332
  await click(find('switch', 'Notify the owner') ?? get('checkbox', 'Notify the owner', 'Switch'));
304
333
  check(switched.calls.at(-1)?.[0] === true, 'Switch: a click on an off switch did not report true');
334
+ heardDetails(switched, 1, 'Switch: onCheckedChange');
305
335
  await rerender(_jsx(Switch, { label: "Notify the owner", checked: false, onCheckedChange: switched, disabled: true }));
306
336
  const control = find('switch', 'Notify the owner') ?? get('checkbox', 'Notify the owner', 'Switch');
307
337
  check(control.disabled || control.getAttribute('aria-disabled') === 'true' || control.hasAttribute('data-disabled'), 'Switch: disabled did not disable the switch');
@@ -327,6 +357,7 @@ export function uiKitConformance(kit, test) {
327
357
  const option = await until(() => find('option', 'High'), 'Dropdown: a click on the button did not list the options');
328
358
  await click(option);
329
359
  check(changed.calls.at(-1)?.[0] === 'high', 'Dropdown: picking an option did not report its value');
360
+ heardDetails(changed, 1, 'Dropdown: onChange');
330
361
  await rerender(_jsx(Dropdown, { ariaLabel: "Priority", items: ITEMS, value: "low", onChange: changed, disabled: true }));
331
362
  const off = get('button', 'Priority', 'Dropdown');
332
363
  check(off.disabled || off.getAttribute('aria-disabled') === 'true', 'Dropdown: disabled did not disable its button');
@@ -345,6 +376,7 @@ export function uiKitConformance(kit, test) {
345
376
  const box = get('combobox', 'Tree', 'Typeahead');
346
377
  await type(box, 'b');
347
378
  check(typed.calls.at(-1)?.[0] === 'b', 'Typeahead: onText was not told the typed text');
379
+ heardDetails(typed, 1, 'Typeahead: onText');
348
380
  const list = await until(() => find('listbox'), 'Typeahead: typing did not open a list of matches');
349
381
  check(all('option', list).map(text).join() === 'Birch', 'Typeahead: the list does not show the matching item');
350
382
  await press('ArrowDown', box);
@@ -358,6 +390,7 @@ export function uiKitConformance(kit, test) {
358
390
  check(box.value.length > 0, 'DateField: the box does not show its value');
359
391
  await type(box, '2026-04-01');
360
392
  check(changed.calls.at(-1)?.[0] === '2026-04-01', 'DateField: onChange was not told the typed text');
393
+ heardDetails(changed, 1, 'DateField: onChange');
361
394
  get('button', 'Pick a day for', 'DateField');
362
395
  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
396
  check(get('textbox', 'Due', 'DateField').disabled, 'DateField: disabled did not disable the box');
@@ -452,6 +485,7 @@ export function uiKitConformance(kit, test) {
452
485
  showsText('The details panel', 'Tabs');
453
486
  await click(get('tab', 'History', 'Tabs'));
454
487
  check(chose.calls.at(-1)?.[0] === 'history', 'Tabs: choosing a tab did not report its value');
488
+ heardDetails(chose, 1, 'Tabs: onValueChange');
455
489
  await until(() => document.body.textContent?.includes('The history panel'), 'Tabs: the chosen tab does not show its panel');
456
490
  });
457
491
  it('Pagination says its words and reports the page asked for', async (mount) => {
@@ -462,9 +496,53 @@ export function uiKitConformance(kit, test) {
462
496
  check(went.calls.at(-1)?.[0] === 3, 'Pagination: its next button did not ask for the next page');
463
497
  await click(get('button', 'Earlier', 'Pagination'));
464
498
  check(went.calls.at(-1)?.[0] === 1, 'Pagination: its previous button did not ask for the page before');
499
+ heardDetails(went, 1, 'Pagination: onPageChange');
465
500
  });
466
501
  it('Avatar draws a picture or the initials of its name', async (mount) => {
467
502
  const { host } = await mount(_jsx(Avatar, { name: "Ada Lovelace" }));
468
503
  check(host.textContent?.includes('AL') || host.querySelector('img, svg, [role="img"]'), 'Avatar: neither initials nor a picture is drawn');
469
504
  });
505
+ it('an open Dropdown, DropMenu and Typeahead hold to their ARIA patterns', async (mount) => {
506
+ const { rerender } = await mount(_jsx(Dropdown, { ariaLabel: "Priority", items: ITEMS, value: "low", onChange: () => { } }));
507
+ const trigger = get('button', 'Priority', 'Dropdown');
508
+ trigger.focus();
509
+ await press('ArrowDown', trigger);
510
+ await until(() => find('listbox'), 'Dropdown: ArrowDown on the button did not open a listbox');
511
+ await patterns('Dropdown');
512
+ await rerender(_jsx(Menu, { run: () => { } }));
513
+ const opener = get('button', 'Row actions', 'DropMenu');
514
+ opener.focus();
515
+ await press('ArrowDown', opener);
516
+ await until(() => find('menu'), 'DropMenu: ArrowDown on the trigger did not open a menu');
517
+ await patterns('DropMenu');
518
+ await rerender(_jsx(Typed, { pick: () => { } }));
519
+ await type(get('combobox', 'Tree', 'Typeahead'), 'b');
520
+ await until(() => find('listbox'), 'Typeahead: typing did not open a list of matches');
521
+ await patterns('Typeahead');
522
+ /* Nothing matches: the empty message is a status beside the list, never inside a listbox, and no listbox is left
523
+ with no option to hold. */
524
+ await rerender(_jsx(Typed, { pick: () => { }, empty: "No tree by that name" }));
525
+ await type(get('combobox', 'Tree', 'Typeahead'), 'zz');
526
+ await until(() => document.body.textContent?.includes('No tree by that name'), 'Typeahead: a query that matches nothing did not show its empty message');
527
+ check(!find('listbox'), 'Typeahead: an empty list is drawn as a listbox with no option');
528
+ await patterns('Typeahead, nothing matched');
529
+ });
530
+ it('Tabs, YesNo, ChoiceCards and Switch hold to their ARIA patterns', async (mount) => {
531
+ await mount(_jsxs(_Fragment, { children: [_jsx(Tabs, { ariaLabel: "Record sections", defaultValue: "history", tabs: [
532
+ { value: 'details', label: 'Details', children: _jsx("p", { children: "The details panel" }) },
533
+ { value: 'history', label: 'History', children: _jsx("p", { children: "The history panel" }) },
534
+ { value: 'files', label: 'Files', children: _jsx("p", { children: "The files panel" }) },
535
+ ] }), _jsx(YesNo, { label: "Billable", value: "yes", onChange: () => { }, yes: "Yes", no: "No" }), _jsx(ChoiceCards, { label: "Size", options: ITEMS, value: ['low'], onChange: () => { } }), _jsx(Switch, { label: "Notify me", checked: true, onCheckedChange: () => { } })] }));
536
+ await patterns('Tabs, YesNo, ChoiceCards and Switch');
537
+ check(find('tab', 'History')?.getAttribute('aria-selected') === 'true', 'checkPatterns: reading the tabs left another tab chosen');
538
+ });
539
+ it('an open Modal and Drawer hold to the dialog pattern', async (mount) => {
540
+ const { rerender } = await mount(_jsx(Modal, { ariaLabel: "Edit the row", onClose: () => { }, children: _jsx("button", { type: "button", children: "Inside" }) }));
541
+ const dialog = await until(() => find('dialog', 'Edit the row'), 'Modal: no dialog named by its ariaLabel is drawn');
542
+ await until(() => dialog.contains(document.activeElement), 'Modal: the focus did not move into the dialog when it opened');
543
+ await patterns('Modal');
544
+ await rerender(_jsx(Drawer, { open: true, title: "Filters", closeLabel: "Put it away", onOpenChange: () => { }, children: _jsx("p", { children: "Pick what to show" }) }));
545
+ await until(() => find('dialog', 'Filters'), 'Drawer: no dialog named by its title is drawn while open');
546
+ await patterns('Drawer');
547
+ });
470
548
  }
@@ -0,0 +1,27 @@
1
+ /**
2
+ * `checkPatterns(root)`: the WAI-ARIA Authoring Practices patterns, read off a live page. Every listbox, menu, tab
3
+ * list, tree, dialog, combobox, radio group and switch under `root` is held to what its pattern promises a reader —
4
+ *
5
+ * - its role and an accessible name, and a name on each of its items;
6
+ * - the roles it must own (a listbox its options, a menu its menu items, a tab list its tabs, a tree its tree items,
7
+ * a radio group its radios), and nothing it may not;
8
+ * - one Tab stop for a composite widget, kept by a roving tabindex or by `aria-activedescendant` on a focusable
9
+ * holder — none inside a popup a combobox drives, since the focus stays in the box;
10
+ * - the keys the pattern names: the arrows, Home and End move the current item; Escape closes a popup;
11
+ * - the focus never falls to the body or into inert content, after any of those keys or in an open modal dialog.
12
+ *
13
+ * It answers with the problems it found, each naming the widget, so one run says everything wrong with a page; an
14
+ * empty list is a pass. The keys are pressed the way the conformance suite presses them — dispatched by hand — and a
15
+ * key that changes what is chosen (a tab list's arrows) is walked back afterwards; Escape on an open popup is left
16
+ * closed. A dialog's Escape belongs to whoever opened it, so dialogs are read, not pressed.
17
+ *
18
+ * It is self-contained on purpose — no imports, nothing read from this module's scope — so a browser test can hand the
19
+ * function itself to Playwright's `page.evaluate` and read a real App's page by the rules the unit tests use.
20
+ */
21
+ export interface CheckPatternsOptions {
22
+ /** Wraps each key press and the wait after it, so a renderer flushes what it scheduled: pass React's `act` in a unit test. */
23
+ act?: (step: () => Promise<void>) => unknown;
24
+ /** Press keys as well as read roles, names and Tab stops (the default). `false` reads the page without touching it. */
25
+ keys?: boolean;
26
+ }
27
+ export declare function checkPatterns(root?: ParentNode, options?: CheckPatternsOptions): Promise<string[]>;