test(ui): stand up the mounted-DOM interaction test harness (#3243)

Co-authored-by: Codesmith <codesmith-bot@users.noreply.github.com>

Author: ubugeeei

npm/ui/core/package.json

@@ -89,7 +89,7 @@
     "dev": "vp pack --watch",
     "lint:sfc": "vp exec node scripts/lint-sfc.ts src",
     "pretest": "vp pack && pnpm check:size",
-    "test": "vp exec node --test 'src/**/*.test.ts'",
+    "test": "vp test run",
     "check": "vp check src scripts vite.config.ts",
     "check:fix": "vp check --fix src scripts vite.config.ts",
     "check:size": "node scripts/check-size.mjs",
@@ -101,6 +101,8 @@
     "@vitejs/plugin-vue": "catalog:vite-stack",
     "@vizejs/native": "workspace:*",
     "@vizejs/ui-tooling": "workspace:*",
+    "@vue/test-utils": "catalog:vue-stable",
+    "happy-dom": "catalog:testing",
     "typescript": "catalog:typescript",
     "vite": "catalog:vite-stack",
     "vite-plus": "catalog:vite-stack",

npm/ui/core/src/ActionButton.vue

@@ -7,7 +7,7 @@ import type { PrimitiveAs, PrimitiveElement } from "./primitive.ts";
 
 const {
   as = "button",
-  native,
+  native = undefined,
   type = "button",
   disabled = false,
   loading = false,

npm/ui/core/src/CheckboxControl.vue

@@ -5,7 +5,7 @@ import { getCheckboxState } from "./checkbox-state.ts";
 import { useControllableState } from "./controllable-state.ts";
 
 const {
-  modelValue,
+  modelValue = undefined,
   defaultChecked = false,
   indeterminate = false,
   disabled = false,

npm/ui/core/src/authoring-gate.test.ts

@@ -0,0 +1,15 @@
+import assert from "node:assert/strict";
+// Paths are resolved from the package cwd: the runner virtualizes import.meta.url.
+import path from "node:path";
+
+import {
+  auditComponentAuthoring,
+  formatAuthoringViolations,
+} from "@vizejs/ui-tooling/authoring-gate";
+import { test } from "vite-plus/test";
+
+test("every component ships a behavior table, interaction tests, and no source-regex behavior assertions", async () => {
+  const violations = await auditComponentAuthoring(path.resolve("src"));
+  assert.equal(formatAuthoringViolations(violations), "");
+  assert.deepEqual(violations, []);
+});

npm/ui/core/src/button.behavior.md

@@ -0,0 +1,31 @@
+# Button behavior contract
+
+Normative state × input → outcome table for `ActionButton.vue` (`@vizejs/ui/button`).
+Every row is proven by the named mounted-DOM test in `src/button.test.ts`; a row
+without a passing test is a contract violation.
+
+| #   | State                | Input                       | Outcome                                                                         | Proven by                                                                     |
+| --- | -------------------- | --------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| B1  | idle, native         | render                      | `role=button`, accessible name from slot, `type="button"`, `data-state="idle"`  | `renders a native button with an accessible name`                             |
+| B2  | idle                 | Tab                         | control receives focus                                                          | `joins the tab order and focuses programmatically`                            |
+| B3  | idle                 | exposed `focus()`           | control receives focus                                                          | `joins the tab order and focuses programmatically`                            |
+| B4  | idle                 | pointer click               | exactly one `press` carrying the `MouseEvent`                                   | `pointer click fires exactly one press`                                       |
+| B5  | idle, native         | Enter                       | exactly one `press` (activation on keydown)                                     | `Enter and Space each fire exactly one press on a native button`              |
+| B6  | idle, native         | Space                       | exactly one `press` (activation on keyup)                                       | `Enter and Space each fire exactly one press on a native button`              |
+| B7  | idle, non-native     | Enter                       | the component itself clicks the element; exactly one `press`                    | `Enter and Space activate a non-native button through its own handlers`       |
+| B8  | idle, non-native     | Space                       | keydown canceled (no page scroll); one `press` on keyup                         | `Enter and Space activate a non-native button through its own handlers`       |
+| B9  | idle, non-native     | Escape                      | ignored: not canceled, no `press`                                               | `Enter and Space activate a non-native button through its own handlers`       |
+| B10 | idle                 | click, Enter, Space         | three `press` emits in dispatch order, each indistinguishably a `MouseEvent`    | `keyboard and pointer presses are indistinguishable MouseEvents in order`     |
+| B11 | disabled, native     | render                      | native `disabled` attribute, no `aria-disabled` mirror, `data-state="disabled"` | `disabled native button removes activation and keeps native semantics`        |
+| B12 | disabled, native     | click / Enter / Space       | no `press`                                                                      | `disabled native button removes activation and keeps native semantics`        |
+| B13 | disabled, native     | Tab                         | skipped by the tab order                                                        | `disabled native button removes activation and keeps native semantics`        |
+| B14 | disabled, non-native | render                      | `tabindex="-1"`, `aria-disabled="true"`                                         | `disabled non-native button leaves the tab order and announces aria-disabled` |
+| B15 | disabled, non-native | click / Enter / Space / Tab | no `press`; skipped by the tab order                                            | `disabled non-native button leaves the tab order and announces aria-disabled` |
+| B16 | loading              | render                      | `aria-busy="true"`, `aria-disabled="true"`, `data-state="loading"`, focusable   | `loading button announces busy, stays focusable, and suppresses press`        |
+| B17 | loading              | `focus()`                   | focus is accepted and retained                                                  | `loading button announces busy, stays focusable, and suppresses press`        |
+| B18 | loading              | click / Enter / Space       | no `press`                                                                      | `loading button announces busy, stays focusable, and suppresses press`        |
+| B19 | any                  | default slot render         | slot receives live `disabled`, `loading`, `unavailable` state                   | `exposes disabled, loading, and unavailable to the default slot`              |
+
+Keyboard activation timing (`Enter` on keydown, `Space` on keyup, `Space` keydown
+canceled) is additionally pinned as pure logic by `matches native keyboard
+activation timing`.

npm/ui/core/src/button.test.ts

@@ -1,32 +1,187 @@
 import assert from "node:assert/strict";
-import { readFile } from "node:fs/promises";
-import { test } from "node:test";
 
-import { getButtonKeyboardAction } from "./button-keyboard.ts";
+import { test } from "vite-plus/test";
 
-const source = await readFile(new URL("./ActionButton.vue", import.meta.url), "utf8");
+import ActionButton from "./ActionButton.vue";
+import { getButtonKeyboardAction } from "./button-keyboard.ts";
+import { mountInteraction } from "./testing/mount.ts";
 
-void test("matches native keyboard activation timing", () => {
+test("matches native keyboard activation timing", () => {
   assert.equal(getButtonKeyboardAction("Enter", "keydown"), "activate");
   assert.equal(getButtonKeyboardAction("Enter", "keyup"), "ignore");
   assert.equal(getButtonKeyboardAction(" ", "keydown"), "prevent");
   assert.equal(getButtonKeyboardAction(" ", "keyup"), "activate");
   assert.equal(getButtonKeyboardAction("Escape", "keydown"), "ignore");
 });
 
-void test("ships typed disabled and loading semantics in an explicit SFC", () => {
-  assert.match(source, /defineEmits<\{[\s\S]*press: \[event: MouseEvent\]/);
-  assert.match(source, /:disabled="isNativeButton \? disabled : undefined"/);
-  assert.match(source, /:aria-disabled=/);
-  assert.match(source, /:aria-busy=/);
-  assert.match(source, /:tabindex="tabIndex"/);
-  assert.doesNotMatch(source, /\bh\s*\(/);
-  assert.doesNotMatch(source, /defineOptions|withDefaults|interface (?:Props|Emits)/);
+test("renders a native button with an accessible name", () => {
+  const handle = mountInteraction(ActionButton, { slots: { default: "Save" } });
+  const button = handle.getByRole("button", { name: "Save" });
+
+  assert.equal(button.tagName, "BUTTON");
+  assert.equal(button.getAttribute("type"), "button");
+  assert.equal(button.getAttribute("data-vize-ui"), "button");
+  assert.equal(button.getAttribute("data-state"), "idle");
+  assert.equal(button.getAttribute("aria-disabled"), null);
+  assert.equal(button.getAttribute("aria-busy"), null);
+  handle.unmount();
+});
+
+test("joins the tab order and focuses programmatically", async () => {
+  const handle = mountInteraction(ActionButton, { slots: { default: "Save" } });
+  const button = handle.getByRole("button");
+
+  assert.ok((await handle.tab()) === button, "Tab must move focus to the button");
+  assert.ok(handle.activeElement() === button);
+
+  button.blur();
+  handle.exposes<{ focus: (options?: FocusOptions) => void }>().focus();
+  assert.ok(handle.activeElement() === button, "exposed focus() must focus the control");
+  handle.unmount();
+});
+
+test("pointer click fires exactly one press", async () => {
+  const handle = mountInteraction(ActionButton, { slots: { default: "Save" } });
+
+  await handle.click(handle.getByRole("button"));
+
+  const presses = handle.wrapper.emitted("press");
+  assert.equal(presses?.length, 1);
+  assert.ok(presses?.[0]?.[0] instanceof MouseEvent);
+  handle.unmount();
+});
+
+test("Enter and Space each fire exactly one press on a native button", async () => {
+  const handle = mountInteraction(ActionButton, { slots: { default: "Save" } });
+  const button = handle.getByRole("button");
+  button.focus();
+
+  const enter = await handle.press(button, "Enter");
+  assert.equal(enter.activated, true);
+  assert.equal(handle.wrapper.emitted("press")?.length, 1);
+
+  const space = await handle.press(button, " ");
+  assert.equal(space.activated, true);
+  assert.equal(handle.wrapper.emitted("press")?.length, 2);
+  handle.unmount();
+});
+
+test("Enter and Space activate a non-native button through its own handlers", async () => {
+  const handle = mountInteraction(ActionButton, {
+    props: { as: "div" },
+    slots: { default: "Save" },
+  });
+  const button = handle.getByRole("button", { name: "Save" });
+
+  assert.equal(button.tagName, "DIV");
+  assert.equal(button.getAttribute("role"), "button");
+  assert.equal(button.getAttribute("tabindex"), "0");
+
+  const enter = await handle.press(button, "Enter");
+  assert.equal(enter.activated, false, "the component, not the harness, must synthesize clicks");
+  assert.equal(handle.wrapper.emitted("press")?.length, 1);
+
+  const space = await handle.press(button, " ");
+  assert.equal(space.keydownPrevented, true, "Space keydown must be canceled to prevent scrolling");
+  assert.equal(handle.wrapper.emitted("press")?.length, 2);
+
+  const escape = await handle.press(button, "Escape");
+  assert.equal(escape.keydownPrevented, false);
+  assert.equal(handle.wrapper.emitted("press")?.length, 2);
+  handle.unmount();
+});
+
+test("keyboard and pointer presses are indistinguishable MouseEvents in order", async () => {
+  const handle = mountInteraction(ActionButton, {
+    slots: { default: "Save" },
+    record: ["press"],
+  });
+  const button = handle.getByRole("button");
+  button.focus();
+
+  await handle.click(button);
+  await handle.press(button, "Enter");
+  await handle.press(button, " ");
+
+  const recorded = handle.recorded();
+  assert.equal(recorded.length, 3);
+  for (const emit of recorded) {
+    assert.equal(emit.event, "press");
+    assert.ok(emit.payload[0] instanceof MouseEvent);
+  }
+  handle.unmount();
+});
+
+test("disabled native button removes activation and keeps native semantics", async () => {
+  const handle = mountInteraction(ActionButton, {
+    props: { disabled: true },
+    slots: { default: "Save" },
+  });
+  const button = handle.getByRole("button");
+
+  assert.ok(button.hasAttribute("disabled"), "native disabled must be forwarded");
+  assert.equal(button.getAttribute("aria-disabled"), null, "native disabled needs no aria mirror");
+  assert.equal(button.getAttribute("data-state"), "disabled");
+
+  await handle.click(button);
+  await handle.press(button, "Enter");
+  await handle.press(button, " ");
+  assert.equal(handle.wrapper.emitted("press"), undefined);
+
+  assert.ok((await handle.tab()) === null, "a disabled button must leave the tab order");
+  handle.unmount();
+});
+
+test("disabled non-native button leaves the tab order and announces aria-disabled", async () => {
+  const handle = mountInteraction(ActionButton, {
+    props: { as: "div", disabled: true },
+    slots: { default: "Save" },
+  });
+  const button = handle.getByRole("button");
+
+  assert.equal(button.getAttribute("tabindex"), "-1");
+  assert.equal(button.getAttribute("aria-disabled"), "true");
+
+  await handle.click(button);
+  await handle.press(button, "Enter");
+  await handle.press(button, " ");
+  assert.equal(handle.wrapper.emitted("press"), undefined);
+  assert.ok((await handle.tab()) === null, "tabindex -1 must remove it from the tab order");
+  handle.unmount();
+});
+
+test("loading button announces busy, stays focusable, and suppresses press", async () => {
+  const handle = mountInteraction(ActionButton, {
+    props: { loading: true },
+    slots: { default: "Save" },
+  });
+  const button = handle.getByRole("button");
+
+  assert.equal(button.getAttribute("aria-busy"), "true");
+  assert.equal(button.getAttribute("aria-disabled"), "true");
+  assert.equal(button.getAttribute("data-state"), "loading");
+  assert.equal(button.hasAttribute("disabled"), false, "loading must not steal focus");
+
+  button.focus();
+  assert.ok(handle.activeElement() === button, "a busy button must keep accepting focus");
+
+  await handle.click(button);
+  await handle.press(button, "Enter");
+  await handle.press(button, " ");
+  assert.equal(handle.wrapper.emitted("press"), undefined);
+  handle.unmount();
 });
 
-void test("exposes focus deliberately and provides programmable slot state", () => {
-  assert.match(source, /defineExpose\(\{ element, focus \}\)/);
-  assert.match(source, /<slot :disabled :loading :unavailable \/>/);
-  assert.match(source, /data-vize-ui="button"/);
-  assert.match(source, /:data-state=/);
+test("exposes disabled, loading, and unavailable to the default slot", async () => {
+  const handle = mountInteraction(ActionButton, {
+    slots: {
+      default: (state: { disabled: boolean; loading: boolean; unavailable: boolean }) =>
+        `disabled:${state.disabled} loading:${state.loading} unavailable:${state.unavailable}`,
+    },
+  });
+
+  assert.equal(handle.root().textContent, "disabled:false loading:false unavailable:false");
+  await handle.wrapper.setProps({ loading: true });
+  assert.equal(handle.root().textContent, "disabled:false loading:true unavailable:true");
+  handle.unmount();
 });

npm/ui/core/src/checkbox.behavior.md

@@ -0,0 +1,26 @@
+# Checkbox behavior contract
+
+Normative state × input → outcome table for `CheckboxControl.vue` (`@vizejs/ui/checkbox`).
+Every row is proven by the named mounted-DOM test in `src/checkbox.test.ts`; a row
+without a passing test is a contract violation.
+
+| #   | State                | Input              | Outcome                                                                       | Proven by                                                             |
+| --- | -------------------- | ------------------ | ----------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| C1  | any                  | render             | native `input[type=checkbox]`, accessible name from `ariaLabel`               | `renders a native checkbox with an accessible name and focus control` |
+| C2  | any                  | exposed `focus()`  | input receives focus                                                          | `renders a native checkbox with an accessible name and focus control` |
+| C3  | unchecked            | render             | `aria-checked="false"`, `data-state="unchecked"`                              | `reports aria-checked across unchecked, checked, and mixed states`    |
+| C4  | checked              | render             | `aria-checked="true"`, `data-state="checked"`                                 | `reports aria-checked across unchecked, checked, and mixed states`    |
+| C5  | indeterminate        | render             | `aria-checked="mixed"`, `data-state="indeterminate"`, native `.indeterminate` | `reports aria-checked across unchecked, checked, and mixed states`    |
+| C6  | uncontrolled         | pointer click      | toggles; emits `update:modelValue` then `change`, in that order               | `toggles with a pointer click and emits model before change`          |
+| C7  | uncontrolled         | Space              | toggles exactly once like a native checkbox                                   | `toggles with Space like a native checkbox`                           |
+| C8  | wrapped in `<label>` | click on the label | toggles the checkbox (label association)                                      | `clicking the associated label toggles the checkbox`                  |
+| C9  | controlled           | pointer click      | emits the request; the rendered state reverts to the prop value               | `controlled: the parent-provided value always wins`                   |
+| C10 | controlled           | prop update        | rendered state follows `modelValue`                                           | `controlled: the parent-provided value always wins`                   |
+| C11 | uncontrolled, seeded | render             | `defaultChecked` seeds the initial state                                      | `uncontrolled: defaultChecked seeds state and reset restores it`      |
+| C12 | uncontrolled, seeded | exposed `reset()`  | restores the default state                                                    | `uncontrolled: defaultChecked seeds state and reset restores it`      |
+| C13 | indeterminate        | pointer click      | emits `update:indeterminate` `false` and `change` `true`                      | `indeterminate announces mixed and requests clearing on toggle`       |
+| C14 | disabled             | click / Space      | no toggle, no `change`                                                        | `disabled checkbox ignores pointer and keyboard activation`           |
+| C15 | disabled             | Tab                | skipped by the tab order                                                      | `disabled checkbox ignores pointer and keyboard activation`           |
+
+Mixed-state precedence (`indeterminate` wins over `checked`) is additionally
+pinned as pure logic by `gives the mixed visual state precedence`.