@vickbk/tests 0.1.0 → 0.2.0

package/dist/dom-DeHbD1ni.mjs

@@ -0,0 +1,459 @@
+import { expect } from "vitest";
+import { fireEvent, screen, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+//#region src/features/vitest/modules/dom/modules/toggle-event/utils/togglePolyfill.ts
+/**
+* Creates the browser ToggleEvent instance used by the fireEvent.toggle polyfill.
+*
+* @param type - Event type to dispatch.
+* @param initDict - Optional toggle event initialization state.
+* @returns A ToggleEvent matching the requested state.
+* @example
+* ```ts
+* const event = createToggleEvent("toggle", {
+*   oldState: "closed",
+*   newState: "open",
+* });
+* ```
+*/
+function createToggleEvent(type, initDict = {
+	oldState: "closed",
+	newState: "open"
+}) {
+	if (typeof globalThis.ToggleEvent === "undefined") {
+		class ToggleEventPolyfill extends Event {
+			oldState;
+			newState;
+			source = null;
+			constructor(eventType, eventInitDict = {}) {
+				super(eventType, eventInitDict);
+				this.oldState = eventInitDict.oldState ?? "closed";
+				this.newState = eventInitDict.newState ?? "open";
+			}
+		}
+		globalThis.ToggleEvent = ToggleEventPolyfill;
+	}
+	return new globalThis.ToggleEvent(type, {
+		bubbles: false,
+		cancelable: false,
+		...initDict
+	});
+}
+/**
+* Polyfills `fireEvent.toggle` for tests by dispatching a native ToggleEvent.
+*
+* @param element - Element or window to dispatch the toggle event on.
+* @param initDict - Optional state values for the toggle transition.
+* @returns Whether the event dispatch completed successfully.
+* @example
+* ```ts
+* fireEvent.toggle(document.body, { newState: "open" });
+* ```
+*/
+function togglePolyfill(element, initDict = {
+	oldState: "closed",
+	newState: "open"
+}) {
+	const event = createToggleEvent("toggle", initDict);
+	return fireEvent(element, event);
+}
+//#endregion
+//#region src/features/vitest/modules/dom/modules/toggle-event/utils/fireEvent.ts
+const callableFireEvent = (...args) => fireEvent(...args);
+/**
+* Testing Library's fireEvent API with an additional `toggle` event helper.
+*
+* The exported object copies the standard `fireEvent` properties and adds
+* `toggle`, which dispatches the toggle event through `togglePolyfill`.
+* It does not install the extension onto Testing Library's original export.
+*
+* Standard Testing Library event helpers remain available, including
+* `click`, `change`, `input`, `submit`, `focus`, and keyboard/mouse events.
+*
+* @remarks
+* The `toggle` helper defaults to a transition from `closed` to `open`.
+* Call-specific configuration overrides those defaults. This helper does
+* not maintain state between calls.
+*
+* @example
+* ```ts
+* import { fireEvent } from "@vickbk/tests/vitest";
+*
+* const disclosure = document.querySelector("details")!;
+*
+* fireEvent.toggle(disclosure);
+* fireEvent.toggle(disclosure, { newState: "closed" });
+* ```
+*
+* @example
+* ```ts
+* import { fireEvent } from "@vickbk/tests/vitest";
+*
+* const button = document.querySelector("button")!;
+*
+* fireEvent.click(button);
+* ```
+*/
+const fireEvent$1 = Object.assign(callableFireEvent, fireEvent, { 
+/**
+* Dispatches a toggle event using the toggle polyfill.
+*
+* @param element - The document, element, node, or window receiving the event.
+* @param initDict - Optional old/new state overrides for this dispatch.
+* @returns The result returned by `togglePolyfill`.
+*
+* @example
+* ```ts
+* fireEvent.toggle(document.body, {
+*   oldState: "closed",
+*   newState: "open",
+* });
+* ```
+*/
+toggle: (element, initDict) => togglePolyfill(element, {
+	oldState: "closed",
+	newState: "open",
+	...initDict
+}) });
+//#endregion
+//#region src/shared/regex/utils/escape-regex.ts
+function escapeRegExp(str) {
+	if (typeof RegExp.escape === "function") return RegExp.escape(str);
+	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//#endregion
+//#region src/shared/regex/utils/pattern-to-regex.ts
+function patternToRegex(target, flags = "i") {
+	return typeof target === "string" ? new RegExp(escapeRegExp(target), flags) : target;
+}
+//#endregion
+//#region src/features/vitest/modules/dom/utils/getSearchArea.ts
+/**
+* Returns the Testing Library query API for a container or the whole document.
+*
+* @param container Optional element to scope queries to.
+* @returns The scoped query API, or the global `screen` query API.
+* @example
+* ```ts
+* const queries = getSearchArea(formElement);
+* queries.getByRole("button", { name: "Submit" });
+* ```
+*/
+function getSearchArea(container) {
+	return container ? within(container) : screen;
+}
+//#endregion
+//#region src/features/vitest/modules/dom/utils/clickLabelInput.ts
+/**
+* Simulates clicking an input found by its label or placeholder.
+*
+* @param label Label or placeholder text/regular expression identifying the input.
+* @param container Optional element that limits the input search.
+* @returns A promise that resolves after the click interaction completes.
+* @example
+* ```ts
+* await clickLabelInput("Email address");
+* ```
+*/
+async function clickLabelInput(label, container) {
+	const user = userEvent.setup();
+	const regex = patternToRegex(label);
+	const searchArea = getSearchArea(container);
+	const element = typeof label === "string" && label.length === 0 ? searchArea.queryByPlaceholderText(regex) || searchArea.getByLabelText(regex) : searchArea.queryByLabelText(regex) || searchArea.getByPlaceholderText(regex);
+	await user.click(element);
+}
+//#endregion
+//#region src/features/vitest/modules/dom/utils/getCheckboxRadio.ts
+/**
+* Finds a checkbox or radio control by its accessible name.
+*
+* @param target Accessible name to match, as text or a regular expression.
+* @param container Optional element that limits the search.
+* @returns The matching checkbox or radio input.
+* @throws If neither a checkbox nor a radio control matches the target.
+* @example
+* ```ts
+* const consent = getCheckboxRadio("Accept terms");
+* expect(consent).toBeChecked();
+* ```
+*/
+function getCheckboxRadio(target, container) {
+	const regex = patternToRegex(target);
+	const searchArea = getSearchArea(container);
+	const element = searchArea.queryByRole("checkbox", { name: regex }) || searchArea.queryByRole("radio", { name: regex });
+	if (element) return element;
+	throw new Error(`Unable to find a checkbox or radio control named "${String(target)}".`);
+}
+//#endregion
+//#region src/features/vitest/modules/dom/utils/isChecked.ts
+/**
+* Asserts that the radio button or checkbox matching the accessible name is checked.
+*
+* @param selector Accessible label text or regular expression for the control.
+* @param container Optional element that limits the control search.
+* @returns Nothing; throws an assertion error if the control is absent or unchecked.
+* @example
+* ```ts
+* isChecked("Accept terms");
+* ```
+*/
+function isChecked(selector, container) {
+	expect(getCheckboxRadio(selector, container)).toBeChecked();
+}
+//#endregion
+//#region src/features/vitest/modules/dom/utils/isNotChecked.ts
+/**
+* Asserts that the radio button or checkbox matching the accessible name is unchecked.
+*
+* @param selector Accessible label text or regular expression for the control.
+* @param container Optional element that limits the control search.
+* @returns Nothing; throws an assertion error if the control is absent or checked.
+* @example
+* ```ts
+* isNotChecked("Subscribe to updates");
+* ```
+*/
+function isNotChecked(selector, container) {
+	expect(getCheckboxRadio(selector, container)).not.toBeChecked();
+}
+//#endregion
+//#region src/features/vitest/modules/dom/utils/shouldHaveAttributes.ts
+/**
+* Asserts that an HTMLElement possesses the expected set of DOM attributes and values.
+*
+* Handles string/numeric values, boolean attributes (true = present, false = absent),
+* and null/undefined values (absent).
+*
+* @param element The DOM element whose attributes will be checked.
+* @param attributes Attribute names mapped to their expected values.
+* @returns Nothing; throws an assertion error when any attribute does not match.
+* @example
+* ```ts
+* shouldHaveAttributes(input, { required: true, "aria-label": "Email" });
+* ```
+*/
+function shouldHaveAttributes(element, attributes) {
+	Object.entries(attributes).forEach(([key, value]) => {
+		if (value === null || value === void 0 || value === false) expect(element).not.toHaveAttribute(key);
+		else if (value === true) expect(element).toHaveAttribute(key);
+		else expect(element).toHaveAttribute(key, String(value));
+	});
+}
+//#endregion
+//#region src/features/vitest/modules/dom/utils/shouldHaveTestId.ts
+/**
+* Asserts that elements with all supplied test IDs are present in the document.
+*
+* @param ids One or more `data-testid` values to locate.
+* @returns The elements found, in the same order as the supplied IDs.
+* @example
+* ```ts
+* const [submitButton] = shouldHaveTestId("submit-button");
+* ```
+*/
+function shouldHaveTestId(...ids) {
+	const testElements = ids.map((id) => screen.getByTestId(id));
+	testElements.forEach((element) => expect(element).toBeInTheDocument());
+	return testElements;
+}
+//#endregion
+//#region src/features/vitest/modules/dom/utils/shouldNotHaveTestId.ts
+/**
+* Asserts that elements with all supplied test IDs are absent from the document.
+*
+* @param ids One or more `data-testid` values to verify are absent.
+* @returns The query results (`null` for each absent element), in ID order.
+* @example
+* ```ts
+* shouldNotHaveTestId("loading-spinner");
+* ```
+*/
+function shouldNotHaveTestId(...ids) {
+	const testElements = ids.map((id) => screen.queryByTestId(id));
+	testElements.forEach((element) => expect(element).not.toBeInTheDocument());
+	return testElements;
+}
+//#endregion
+//#region src/features/vitest/modules/dom/utils/shouldGetByText.ts
+/**
+* Creates assertion/element pairs for text matchers, supporting a zero-based occurrence index.
+*
+* @param texts Text strings, regular expressions, or `[matcher, occurrenceIndex]` pairs.
+* @returns Assertion and matching-element pairs, with `null` for missing text.
+* @example
+* ```ts
+* const [{ expected, element }] = shouldGetByText(["Item", 1]);
+* ```
+*/
+function shouldGetByText(...texts) {
+	return texts.map((text) => {
+		if (Array.isArray(text)) {
+			const [matcher, nth] = text;
+			const element = screen.queryAllByText(patternToRegex(matcher))[nth] ?? null;
+			return {
+				expected: expect(element),
+				element
+			};
+		}
+		const element = screen.queryByText(patternToRegex(text));
+		return {
+			expected: expect(element),
+			element
+		};
+	});
+}
+//#endregion
+//#region src/features/vitest/modules/dom/utils/shouldNotSee.ts
+/**
+* Asserts that none of the supplied text matchers appear in the document.
+*
+* @param texts Text strings or regular expressions that must be absent.
+* @returns Nothing; throws an assertion error if any text is found.
+* @example
+* ```ts
+* shouldNotSee("Error", /failed/i);
+* ```
+*/
+const shouldNotSee = (...texts) => {
+	shouldGetByText(...texts).forEach(({ expected }) => expected.not.toBeInTheDocument());
+};
+//#endregion
+//#region src/features/vitest/modules/dom/utils/shouldSee.ts
+/**
+* Asserts that each requested text matcher is present in the document.
+*
+* @param texts Text strings, regular expressions, or `[matcher, occurrenceIndex]` pairs.
+* @returns The matching elements in the same order as the supplied matchers.
+* @example
+* ```ts
+* const [heading] = shouldSee("Welcome");
+* ```
+*/
+const shouldSee = (...texts) => {
+	return shouldGetByText(...texts).map(({ expected, element }) => {
+		expected.toBeInTheDocument();
+		return element;
+	});
+};
+//#endregion
+//#region src/features/vitest/modules/dom/utils/togglePopover.ts
+/**
+* Dispatches a toggle event on the first element matching a selector.
+*
+* @param options Selector, optional search container, and target open/closed state.
+* @returns The matched element, or `undefined` when no matching element exists.
+* @example
+* ```ts
+* const popover = togglePopover({ selector: "#help", newState: "open" });
+* ```
+*/
+function togglePopover({ container, selector, newState = "open" }) {
+	const element = (container ?? document).querySelector(selector);
+	if (!element) return;
+	fireEvent$1.toggle(element, { newState });
+	return element;
+}
+//#endregion
+//#region src/features/vitest/modules/dom/utils/userClicks.ts
+/**
+* Simulates a user click on a button with the requested name, or matching text.
+*
+* @param target Button accessible name or text string/regular expression.
+* @param container Optional element that limits the target search.
+* @returns A promise that resolves after the click interaction completes.
+* @example
+* ```ts
+* await userClicks("Save");
+* ```
+*/
+const userClicks = async (target, container) => {
+	const user = userEvent.setup();
+	const regex = patternToRegex(target);
+	const searchArea = container ? within(container) : screen;
+	const element = searchArea.queryByRole("button", { name: regex }) || searchArea.getByText(regex);
+	await user.click(element);
+};
+//#endregion
+//#region src/features/vitest/modules/dom/utils/getTextBox.ts
+/**
+* Finds a text-entry control by its accessible name or placeholder.
+*
+* Supported controls are text-like inputs, textareas, and elements exposed
+* with the textbox role. A matching non-text element is rejected.
+*
+* @param target Accessible name or placeholder to match, as text or a regular expression.
+* @param container Optional element that limits the search.
+* @returns The matching textbox element.
+* @throws If no textbox matches, or a placeholder match is not a text-entry control.
+* @example
+* ```ts
+* const email = getTextBox("Email address");
+* const notes = getTextBox("Notes", dialog);
+* ```
+*/
+function getTextBox(target, container) {
+	const regex = patternToRegex(target);
+	const searchArea = getSearchArea(container);
+	const textBox = searchArea.queryByRole("textbox", { name: regex });
+	if (textBox) return textBox;
+	const placeholderMatch = searchArea.queryByPlaceholderText(regex);
+	if (placeholderMatch) {
+		const isTextInput = placeholderMatch instanceof HTMLInputElement && [
+			"text",
+			"search",
+			"email",
+			"url",
+			"tel",
+			"password"
+		].includes(placeholderMatch.type);
+		const isTextArea = placeholderMatch instanceof HTMLTextAreaElement;
+		const isContentEditable = placeholderMatch.getAttribute("contenteditable") === "true" && placeholderMatch.getAttribute("role") === "textbox";
+		if (isTextInput || isTextArea || isContentEditable) return placeholderMatch;
+		throw new Error(`Element matching placeholder "${String(target)}" is not a text-entry control.`);
+	}
+	return searchArea.getByRole("textbox", { name: regex });
+}
+//#endregion
+//#region src/features/vitest/modules/dom/utils/userTypes.ts
+/**
+* Replaces the value of a textbox found by its label, placeholder, or textbox name.
+*
+* @param target Accessible label, placeholder, or textbox name as text or a regex.
+* @param text Text to type after clearing the existing value.
+* @param container Optional element that limits the textbox search.
+* @param user User-event instance used for the interaction; defaults to a new instance.
+* @returns A promise resolving to the textbox that was updated.
+* @example
+* ```ts
+* const emailInput = await userTypes("Email", "person@example.com");
+* ```
+*/
+const userTypes = async (target, text, container, user = userEvent.setup()) => {
+	const element = getTextBox(target, container);
+	await user.clear(element);
+	if (text) await user.type(element, text);
+	return element;
+};
+//#endregion
+//#region src/features/vitest/modules/dom/utils/userTypesMultiple.ts
+/**
+* Replaces the values of multiple textboxes, located by their respective selectors.
+*
+* @param inputs Object mapping each textbox label/placeholder to the text to enter.
+* @param container Optional element that limits all textbox searches.
+* @returns A promise resolving to an object mapping each selector to its updated textbox.
+* @example
+* ```ts
+* const fields = await userTypesMultiple({ Email: "person@example.com", Name: "Pat" });
+* ```
+*/
+async function userTypesMultiple(inputs, container) {
+	const entries = Object.entries(inputs);
+	const outputs = {};
+	for (const [selector, value] of entries) outputs[selector] = await userTypes(selector, value, container);
+	return outputs;
+}
+//#endregion
+export { shouldSee as a, shouldHaveTestId as c, isChecked as d, clickLabelInput as f, togglePopover as i, shouldHaveAttributes as l, userTypes as n, shouldNotSee as o, fireEvent$1 as p, userClicks as r, shouldNotHaveTestId as s, userTypesMultiple as t, isNotChecked as u };
+
+//# sourceMappingURL=dom-DeHbD1ni.mjs.map

package/dist/dom-DeHbD1ni.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-DeHbD1ni.mjs","names":["rtlFireEvent","fireEvent"],"sources":["../src/features/vitest/modules/dom/modules/toggle-event/utils/togglePolyfill.ts","../src/features/vitest/modules/dom/modules/toggle-event/utils/fireEvent.ts","../src/shared/regex/utils/escape-regex.ts","../src/shared/regex/utils/pattern-to-regex.ts","../src/features/vitest/modules/dom/utils/getSearchArea.ts","../src/features/vitest/modules/dom/utils/clickLabelInput.ts","../src/features/vitest/modules/dom/utils/getCheckboxRadio.ts","../src/features/vitest/modules/dom/utils/isChecked.ts","../src/features/vitest/modules/dom/utils/isNotChecked.ts","../src/features/vitest/modules/dom/utils/shouldHaveAttributes.ts","../src/features/vitest/modules/dom/utils/shouldHaveTestId.ts","../src/features/vitest/modules/dom/utils/shouldNotHaveTestId.ts","../src/features/vitest/modules/dom/utils/shouldGetByText.ts","../src/features/vitest/modules/dom/utils/shouldNotSee.ts","../src/features/vitest/modules/dom/utils/shouldSee.ts","../src/features/vitest/modules/dom/utils/togglePopover.ts","../src/features/vitest/modules/dom/utils/userClicks.ts","../src/features/vitest/modules/dom/utils/getTextBox.ts","../src/features/vitest/modules/dom/utils/userTypes.ts","../src/features/vitest/modules/dom/utils/userTypesMultiple.ts"],"sourcesContent":["import { fireEvent } from \"@testing-library/react\";\nimport type { ToggleConfig } from \"./types\";\n\n/**\n * Creates the browser ToggleEvent instance used by the fireEvent.toggle polyfill.\n *\n * @param type - Event type to dispatch.\n * @param initDict - Optional toggle event initialization state.\n * @returns A ToggleEvent matching the requested state.\n * @example\n * ```ts\n * const event = createToggleEvent(\"toggle\", {\n *   oldState: \"closed\",\n *   newState: \"open\",\n * });\n * ```\n */\nexport function createToggleEvent(\n  type: string,\n  initDict: Partial<ToggleConfig> = {\n    oldState: \"closed\",\n    newState: \"open\",\n  },\n): ToggleEvent {\n  if (typeof globalThis.ToggleEvent === \"undefined\") {\n    class ToggleEventPolyfill extends Event {\n      oldState: string;\n      newState: string;\n      source: Element | null = null;\n\n      constructor(eventType: string, eventInitDict: ToggleEventInit = {}) {\n        super(eventType, eventInitDict);\n        this.oldState = (eventInitDict as Partial<ToggleConfig>).oldState ?? \"closed\";\n        this.newState = (eventInitDict as Partial<ToggleConfig>).newState ?? \"open\";\n      }\n    }\n\n    globalThis.ToggleEvent = ToggleEventPolyfill as typeof ToggleEvent;\n  }\n\n  return new globalThis.ToggleEvent(type, {\n    bubbles: false,\n    cancelable: false,\n    ...initDict,\n  });\n}\n\n/**\n * Polyfills `fireEvent.toggle` for tests by dispatching a native ToggleEvent.\n *\n * @param element - Element or window to dispatch the toggle event on.\n * @param initDict - Optional state values for the toggle transition.\n * @returns Whether the event dispatch completed successfully.\n * @example\n * ```ts\n * fireEvent.toggle(document.body, { newState: \"open\" });\n * ```\n */\nexport function togglePolyfill(\n  element: Document | Element | Node | Window,\n  initDict: Partial<ToggleConfig> = {\n    oldState: \"closed\",\n    newState: \"open\",\n  },\n): boolean {\n  const event = createToggleEvent(\"toggle\", initDict);\n  return fireEvent(element, event);\n}\n","import { fireEvent as rtlFireEvent } from \"@testing-library/react\";\nimport { togglePolyfill } from \"./togglePolyfill\";\nimport type { ToggleConfig, ToggleFireEventExtensions } from \"./types\";\n\nconst callableFireEvent = (...args: Parameters<typeof rtlFireEvent>) =>\n  rtlFireEvent(...args);\n/**\n * Testing Library's fireEvent API with an additional `toggle` event helper.\n *\n * The exported object copies the standard `fireEvent` properties and adds\n * `toggle`, which dispatches the toggle event through `togglePolyfill`.\n * It does not install the extension onto Testing Library's original export.\n *\n * Standard Testing Library event helpers remain available, including\n * `click`, `change`, `input`, `submit`, `focus`, and keyboard/mouse events.\n *\n * @remarks\n * The `toggle` helper defaults to a transition from `closed` to `open`.\n * Call-specific configuration overrides those defaults. This helper does\n * not maintain state between calls.\n *\n * @example\n * ```ts\n * import { fireEvent } from \"@vickbk/tests/vitest\";\n *\n * const disclosure = document.querySelector(\"details\")!;\n *\n * fireEvent.toggle(disclosure);\n * fireEvent.toggle(disclosure, { newState: \"closed\" });\n * ```\n *\n * @example\n * ```ts\n * import { fireEvent } from \"@vickbk/tests/vitest\";\n *\n * const button = document.querySelector(\"button\")!;\n *\n * fireEvent.click(button);\n * ```\n */\nexport const fireEvent = Object.assign(callableFireEvent, rtlFireEvent, {\n  /**\n   * Dispatches a toggle event using the toggle polyfill.\n   *\n   * @param element - The document, element, node, or window receiving the event.\n   * @param initDict - Optional old/new state overrides for this dispatch.\n   * @returns The result returned by `togglePolyfill`.\n   *\n   * @example\n   * ```ts\n   * fireEvent.toggle(document.body, {\n   *   oldState: \"closed\",\n   *   newState: \"open\",\n   * });\n   * ```\n   */\n  toggle: (\n    element: Document | Element | Node | Window,\n    initDict?: Partial<ToggleConfig>,\n  ) =>\n    togglePolyfill(element, {\n      oldState: \"closed\",\n      newState: \"open\",\n      ...initDict,\n    }),\n}) as typeof rtlFireEvent & ToggleFireEventExtensions;\n","export function escapeRegExp(str: string): string {\n  if (typeof RegExp.escape === \"function\") {\n    return RegExp.escape(str);\n  }\n  return str.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n}\n","import { TEXT_PATTERN } from \"../types\";\nimport { escapeRegExp } from \"./escape-regex\";\n\nexport function patternToRegex(\n  target: TEXT_PATTERN,\n  flags: string = \"i\",\n): RegExp {\n  return typeof target === \"string\"\n    ? new RegExp(escapeRegExp(target), flags)\n    : target;\n}\n","import { screen, within } from \"@testing-library/react\";\n\n/**\n * Returns the Testing Library query API for a container or the whole document.\n *\n * @param container Optional element to scope queries to.\n * @returns The scoped query API, or the global `screen` query API.\n * @example\n * ```ts\n * const queries = getSearchArea(formElement);\n * queries.getByRole(\"button\", { name: \"Submit\" });\n * ```\n */\nexport function getSearchArea(container?: HTMLElement) {\n  return container ? within(container) : screen;\n}\n","import type { TEXT_PATTERN } from \"@/shared/regex\";\nimport { patternToRegex } from \"@/shared/regex\";\nimport userEvent from \"@testing-library/user-event\";\nimport { getSearchArea } from \"./getSearchArea\";\n\n/**\n * Simulates clicking an input found by its label or placeholder.\n *\n * @param label Label or placeholder text/regular expression identifying the input.\n * @param container Optional element that limits the input search.\n * @returns A promise that resolves after the click interaction completes.\n * @example\n * ```ts\n * await clickLabelInput(\"Email address\");\n * ```\n */\nexport async function clickLabelInput(\n  label: TEXT_PATTERN,\n  container?: HTMLElement,\n) {\n  const user = userEvent.setup();\n  const regex = patternToRegex(label);\n  const searchArea = getSearchArea(container);\n  const element =\n    typeof label === \"string\" && label.length === 0\n      ? searchArea.queryByPlaceholderText(regex) ||\n        searchArea.getByLabelText(regex)\n      : searchArea.queryByLabelText(regex) ||\n        searchArea.getByPlaceholderText(regex);\n  await user.click(element);\n}\n","import type { TEXT_PATTERN } from \"@/shared/regex\";\nimport { patternToRegex } from \"@/shared/regex\";\nimport { getSearchArea } from \"./getSearchArea\";\n\n/**\n * Finds a checkbox or radio control by its accessible name.\n *\n * @param target Accessible name to match, as text or a regular expression.\n * @param container Optional element that limits the search.\n * @returns The matching checkbox or radio input.\n * @throws If neither a checkbox nor a radio control matches the target.\n * @example\n * ```ts\n * const consent = getCheckboxRadio(\"Accept terms\");\n * expect(consent).toBeChecked();\n * ```\n */\nexport function getCheckboxRadio(\n  target: TEXT_PATTERN,\n  container?: HTMLElement,\n) {\n  const regex = patternToRegex(target);\n  const searchArea = getSearchArea(container);\n  const element =\n    searchArea.queryByRole(\"checkbox\", { name: regex }) ||\n    searchArea.queryByRole(\"radio\", { name: regex });\n\n  if (element) return element;\n\n  throw new Error(\n    `Unable to find a checkbox or radio control named \"${String(target)}\".`,\n  );\n}\n","import type { TEXT_PATTERN } from \"@/shared/regex\";\nimport { expect } from \"vitest\";\nimport { getCheckboxRadio } from \"./getCheckboxRadio\";\n\n/**\n * Asserts that the radio button or checkbox matching the accessible name is checked.\n *\n * @param selector Accessible label text or regular expression for the control.\n * @param container Optional element that limits the control search.\n * @returns Nothing; throws an assertion error if the control is absent or unchecked.\n * @example\n * ```ts\n * isChecked(\"Accept terms\");\n * ```\n */\nexport function isChecked(selector: TEXT_PATTERN, container?: HTMLElement) {\n  expect(getCheckboxRadio(selector, container)).toBeChecked();\n}\n","import type { TEXT_PATTERN } from \"@/shared/regex\";\nimport { expect } from \"vitest\";\nimport { getCheckboxRadio } from \"./getCheckboxRadio\";\n\n/**\n * Asserts that the radio button or checkbox matching the accessible name is unchecked.\n *\n * @param selector Accessible label text or regular expression for the control.\n * @param container Optional element that limits the control search.\n * @returns Nothing; throws an assertion error if the control is absent or checked.\n * @example\n * ```ts\n * isNotChecked(\"Subscribe to updates\");\n * ```\n */\nexport function isNotChecked(selector: TEXT_PATTERN, container?: HTMLElement) {\n  expect(getCheckboxRadio(selector, container)).not.toBeChecked();\n}\n","import { expect } from \"vitest\";\n\n/**\n * Asserts that an HTMLElement possesses the expected set of DOM attributes and values.\n *\n * Handles string/numeric values, boolean attributes (true = present, false = absent),\n * and null/undefined values (absent).\n *\n * @param element The DOM element whose attributes will be checked.\n * @param attributes Attribute names mapped to their expected values.\n * @returns Nothing; throws an assertion error when any attribute does not match.\n * @example\n * ```ts\n * shouldHaveAttributes(input, { required: true, \"aria-label\": \"Email\" });\n * ```\n */\nexport function shouldHaveAttributes(\n  element: HTMLElement,\n  attributes: Record<string, unknown>,\n): void {\n  Object.entries(attributes).forEach(([key, value]) => {\n    if (value === null || value === undefined || value === false) {\n      expect(element).not.toHaveAttribute(key);\n    } else if (value === true) {\n      expect(element).toHaveAttribute(key);\n    } else {\n      expect(element).toHaveAttribute(key, String(value));\n    }\n  });\n}\n","import { screen } from \"@testing-library/react\";\nimport { expect } from \"vitest\";\n\n/**\n * Asserts that elements with all supplied test IDs are present in the document.\n *\n * @param ids One or more `data-testid` values to locate.\n * @returns The elements found, in the same order as the supplied IDs.\n * @example\n * ```ts\n * const [submitButton] = shouldHaveTestId(\"submit-button\");\n * ```\n */\nexport function shouldHaveTestId(...ids: string[]) {\n  const testElements = ids.map((id) => screen.getByTestId(id));\n\n  testElements.forEach((element) => expect(element).toBeInTheDocument());\n  return testElements;\n}\n","import { screen } from \"@testing-library/react\";\nimport { expect } from \"vitest\";\n\n/**\n * Asserts that elements with all supplied test IDs are absent from the document.\n *\n * @param ids One or more `data-testid` values to verify are absent.\n * @returns The query results (`null` for each absent element), in ID order.\n * @example\n * ```ts\n * shouldNotHaveTestId(\"loading-spinner\");\n * ```\n */\nexport function shouldNotHaveTestId(...ids: string[]) {\n  const testElements = ids.map((id) => screen.queryByTestId(id));\n\n  testElements.forEach((element) => expect(element).not.toBeInTheDocument());\n  return testElements;\n}\n","import type { TEXT_MATCHER } from \"@/shared/regex\";\nimport { patternToRegex } from \"@/shared/regex\";\nimport { screen } from \"@testing-library/react\";\nimport { expect } from \"vitest\";\n\n/**\n * Creates assertion/element pairs for text matchers, supporting a zero-based occurrence index.\n *\n * @param texts Text strings, regular expressions, or `[matcher, occurrenceIndex]` pairs.\n * @returns Assertion and matching-element pairs, with `null` for missing text.\n * @example\n * ```ts\n * const [{ expected, element }] = shouldGetByText([\"Item\", 1]);\n * ```\n */\nexport function shouldGetByText(...texts: TEXT_MATCHER[]) {\n  return texts.map((text) => {\n    if (Array.isArray(text)) {\n      const [matcher, nth] = text;\n      const element =\n        screen.queryAllByText(patternToRegex(matcher))[nth] ?? null;\n      return { expected: expect(element), element };\n    }\n    const element = screen.queryByText(patternToRegex(text));\n    return { expected: expect(element), element };\n  });\n}\n","import { shouldGetByText } from \"./shouldGetByText\";\n\n/**\n * Asserts that none of the supplied text matchers appear in the document.\n *\n * @param texts Text strings or regular expressions that must be absent.\n * @returns Nothing; throws an assertion error if any text is found.\n * @example\n * ```ts\n * shouldNotSee(\"Error\", /failed/i);\n * ```\n */\nexport const shouldNotSee = (...texts: (string | RegExp)[]) => {\n  shouldGetByText(...texts).forEach(({ expected }) =>\n    expected.not.toBeInTheDocument(),\n  );\n};\n","import type { TEXT_MATCHER } from \"@/shared/regex\";\nimport { shouldGetByText } from \"./shouldGetByText\";\n\n/**\n * Asserts that each requested text matcher is present in the document.\n *\n * @param texts Text strings, regular expressions, or `[matcher, occurrenceIndex]` pairs.\n * @returns The matching elements in the same order as the supplied matchers.\n * @example\n * ```ts\n * const [heading] = shouldSee(\"Welcome\");\n * ```\n */\nexport const shouldSee = (...texts: TEXT_MATCHER[]) => {\n  return shouldGetByText(...texts).map(({ expected, element }) => {\n    expected.toBeInTheDocument();\n    return element!;\n  });\n};\n","import { fireEvent, type ToggleState } from \"../modules/toggle-event\";\n\n/**\n * Dispatches a toggle event on the first element matching a selector.\n *\n * @param options Selector, optional search container, and target open/closed state.\n * @returns The matched element, or `undefined` when no matching element exists.\n * @example\n * ```ts\n * const popover = togglePopover({ selector: \"#help\", newState: \"open\" });\n * ```\n */\nexport function togglePopover({\n  container,\n  selector,\n  newState = \"open\",\n}: {\n  container?: HTMLElement;\n  selector: string;\n  newState?: ToggleState;\n}) {\n  const element = (container ?? document).querySelector(selector);\n  if (!element) return;\n  fireEvent.toggle(element, { newState });\n  return element;\n}\n","import { patternToRegex } from \"@/shared/regex\";\nimport { screen, within } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\n\n/**\n * Simulates a user click on a button with the requested name, or matching text.\n *\n * @param target Button accessible name or text string/regular expression.\n * @param container Optional element that limits the target search.\n * @returns A promise that resolves after the click interaction completes.\n * @example\n * ```ts\n * await userClicks(\"Save\");\n * ```\n */\nexport const userClicks = async (\n  target: string | RegExp,\n  container?: HTMLElement,\n) => {\n  const user = userEvent.setup();\n  const regex = patternToRegex(target);\n  const searchArea = container ? within(container) : screen;\n  const element =\n    searchArea.queryByRole(\"button\", { name: regex }) ||\n    searchArea.getByText(regex);\n\n  await user.click(element);\n};\n","import { patternToRegex, TEXT_PATTERN } from \"@/shared/regex\";\nimport { getSearchArea } from \"./getSearchArea\";\n\n/**\n * Finds a text-entry control by its accessible name or placeholder.\n *\n * Supported controls are text-like inputs, textareas, and elements exposed\n * with the textbox role. A matching non-text element is rejected.\n *\n * @param target Accessible name or placeholder to match, as text or a regular expression.\n * @param container Optional element that limits the search.\n * @returns The matching textbox element.\n * @throws If no textbox matches, or a placeholder match is not a text-entry control.\n * @example\n * ```ts\n * const email = getTextBox(\"Email address\");\n * const notes = getTextBox(\"Notes\", dialog);\n * ```\n */\nexport function getTextBox(target: TEXT_PATTERN, container?: HTMLElement) {\n  const regex = patternToRegex(target);\n  const searchArea = getSearchArea(container);\n  const textBox = searchArea.queryByRole(\"textbox\", { name: regex });\n\n  if (textBox) return textBox;\n\n  const placeholderMatch = searchArea.queryByPlaceholderText(regex);\n  if (placeholderMatch) {\n    const isTextInput =\n      placeholderMatch instanceof HTMLInputElement &&\n      [\"text\", \"search\", \"email\", \"url\", \"tel\", \"password\"].includes(\n        placeholderMatch.type,\n      );\n    const isTextArea = placeholderMatch instanceof HTMLTextAreaElement;\n    const isContentEditable =\n      placeholderMatch.getAttribute(\"contenteditable\") === \"true\" &&\n      placeholderMatch.getAttribute(\"role\") === \"textbox\";\n\n    if (isTextInput || isTextArea || isContentEditable) return placeholderMatch;\n\n    throw new Error(\n      `Element matching placeholder \"${String(target)}\" is not a text-entry control.`,\n    );\n  }\n\n  return searchArea.getByRole(\"textbox\", { name: regex });\n}\n","import { TEXT_PATTERN } from \"@/shared/regex\";\nimport userEvent from \"@testing-library/user-event\";\nimport { getTextBox } from \"./getTextBox\";\n\n/**\n * Replaces the value of a textbox found by its label, placeholder, or textbox name.\n *\n * @param target Accessible label, placeholder, or textbox name as text or a regex.\n * @param text Text to type after clearing the existing value.\n * @param container Optional element that limits the textbox search.\n * @param user User-event instance used for the interaction; defaults to a new instance.\n * @returns A promise resolving to the textbox that was updated.\n * @example\n * ```ts\n * const emailInput = await userTypes(\"Email\", \"person@example.com\");\n * ```\n */\nexport const userTypes = async (\n  target: TEXT_PATTERN,\n  text: string,\n  container?: HTMLElement,\n  user = userEvent.setup(),\n) => {\n  const element = getTextBox(target, container);\n\n  await user.clear(element);\n  if (text) await user.type(element, text);\n  return element;\n};\n","import { userTypes } from \"./userTypes\";\n\n/**\n * Replaces the values of multiple textboxes, located by their respective selectors.\n *\n * @param inputs Object mapping each textbox label/placeholder to the text to enter.\n * @param container Optional element that limits all textbox searches.\n * @returns A promise resolving to an object mapping each selector to its updated textbox.\n * @example\n * ```ts\n * const fields = await userTypesMultiple({ Email: \"person@example.com\", Name: \"Pat\" });\n * ```\n */\nexport async function userTypesMultiple(\n  inputs: Record<string, string>,\n  container?: HTMLElement,\n) {\n  const entries = Object.entries(inputs);\n  const outputs: Record<keyof typeof inputs, HTMLElement> = {};\n\n  for (const [selector, value] of entries) {\n    outputs[selector] = await userTypes(selector, value, container);\n  }\n\n  return outputs;\n}\n"],"mappings":"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"}