@assure-one/design-system 1.35.0 → 1.36.0

package/dist/{system-lyhOUTpa.d.ts → system-BDU18fVg.d.ts}

@@ -556,4 +556,4 @@ declare const systemTokens: {
 };
 type SystemTokens = typeof systemTokens;
 
-export { type ColorName as C, type ReferenceTokens as R, type SystemTokens as S, reference as a, breakpoints as b, colors as c, spacing as d, surfaces as e, systemTokens as f, iconSizes as i, layout as l, motion as m, overlays as o, radii as r, shadows as s, typography as t, zIndex as z };
+export { type ColorName as C, type ReferenceTokens as R, type SystemTokens as S, reference as a, spacing as b, colors as c, surfaces as d, systemTokens as e, breakpoints as f, iconSizes as i, layout as l, motion as m, overlays as o, radii as r, shadows as s, typography as t, zIndex as z };

package/dist/testing/index.cjs

@@ -312,14 +312,28 @@ function accessibleText(element) {
 function isDisabled(element) {
   return element.hasAttribute("disabled") || element.getAttribute("aria-disabled") === "true" || element.hasAttribute("data-disabled");
 }
+function isQueries(target) {
+  return typeof target.getByRole === "function";
+}
 function press(target, key) {
   const view = target.ownerDocument.defaultView ?? window;
   const init = { key, code: key === " " ? "Space" : key, bubbles: true, cancelable: true };
   target.dispatchEvent(new view.KeyboardEvent("keydown", init));
   target.dispatchEvent(new view.KeyboardEvent("keyup", init));
 }
+async function run(fn) {
+  const actEnvironment = globalThis.IS_REACT_ACT_ENVIRONMENT;
+  if (actEnvironment) {
+    await react.act(async () => {
+      await fn();
+    });
+    return;
+  }
+  await fn();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+}
 async function flush() {
-  await react.act(async () => {
+  await run(async () => {
     await Promise.resolve();
   });
 }
@@ -332,7 +346,7 @@ async function waitUntil(find, maxFlushes) {
   return null;
 }
 function resolveTrigger(target, name, role) {
-  if (typeof target.getByRole === "function") {
+  if (isQueries(target)) {
     if (name === void 0)
       throw new Error(`A ${role} name is required when passing a query object.`);
     return target.getByRole(role, { name });
@@ -350,8 +364,33 @@ function popupOf(trigger, role) {
   }
   return null;
 }
+function isTextControl(element) {
+  const tag = element.tagName;
+  return tag === "TEXTAREA" || tag === "INPUT" && !/^(checkbox|radio|file|button|submit|reset|image|hidden)$/i.test(
+    element.type
+  );
+}
+async function typeInto(control, text2, commit) {
+  const view = control.ownerDocument.defaultView ?? window;
+  const proto = control.tagName === "TEXTAREA" ? view.HTMLTextAreaElement.prototype : view.HTMLInputElement.prototype;
+  const setter = Object.getOwnPropertyDescriptor(proto, "value")?.set;
+  await run(() => {
+    control.focus();
+    if (setter) setter.call(control, text2);
+    else control.value = text2;
+    control.dispatchEvent(new view.Event("input", { bubbles: true }));
+  });
+  if (commit) {
+    await run(() => {
+      control.blur();
+    });
+  }
+  await flush();
+}
+
+// src/testing/interactions.ts
 async function selectOption(target, ...rest) {
-  const byQuery = typeof target.getByRole === "function";
+  const byQuery = isQueries(target);
   const label = byQuery ? rest[0] : void 0;
   const option = byQuery ? rest[1] : rest[0];
   const settings = (byQuery ? rest[2] : rest[1]) ?? {};
@@ -363,7 +402,7 @@ async function selectOption(target, ...rest) {
     );
   }
   if (trigger.getAttribute("aria-expanded") !== "true") {
-    await react.act(async () => {
+    await run(() => {
       trigger.focus();
       press(trigger, "Enter");
     });
@@ -378,16 +417,16 @@ async function selectOption(target, ...rest) {
   const wanted = all.find((el) => matches(accessibleText(el), option));
   if (!wanted) {
     const available = all.map((el) => JSON.stringify(accessibleText(el))).join(", ");
-    await react.act(async () => press(listbox, "Escape"));
+    await run(() => press(listbox, "Escape"));
     throw new Error(
       `selectOption: no option matches ${describe(option)}. Options: ${available || "(none)"}.`
     );
   }
   if (isDisabled(wanted)) {
-    await react.act(async () => press(listbox, "Escape"));
+    await run(() => press(listbox, "Escape"));
     throw new Error(`selectOption: the option ${describe(option)} is disabled.`);
   }
-  await react.act(async () => {
+  await run(() => {
     wanted.focus();
     press(wanted, "Enter");
   });
@@ -396,7 +435,7 @@ async function selectOption(target, ...rest) {
     throw new Error(`selectOption: the list stayed open after choosing ${describe(option)}.`);
 }
 async function openMenu(target, ...rest) {
-  const byQuery = typeof target.getByRole === "function";
+  const byQuery = isQueries(target);
   const name = byQuery ? rest[0] : void 0;
   const settings = (byQuery ? rest[1] : rest[0]) ?? {};
   const maxFlushes = settings.maxFlushes ?? 20;
@@ -407,7 +446,7 @@ async function openMenu(target, ...rest) {
     );
   }
   if (trigger.getAttribute("aria-expanded") !== "true") {
-    await react.act(async () => {
+    await run(() => {
       trigger.focus();
       press(trigger, "ArrowDown");
     });
@@ -445,21 +484,104 @@ async function openMenu(target, ...rest) {
       const item = getItem(itemName);
       if (isDisabled(item))
         throw new Error(`openMenu: the item ${describe(itemName)} is disabled.`);
-      await react.act(async () => {
+      await run(() => {
         item.focus();
         press(item, "Enter");
       });
       await waitUntil(() => menu.isConnected ? null : true, maxFlushes);
     },
     async close() {
-      await react.act(async () => press(menu, "Escape"));
+      await run(() => press(menu, "Escape"));
       await waitClosed("Escape");
     }
   };
 }
 
+// src/testing/helpers/fill-field.ts
+var TEXT_ROLES = ["textbox", "spinbutton", "combobox"];
+function resolveByLabel(queries, label) {
+  const errors = [];
+  for (const role of TEXT_ROLES) {
+    try {
+      return queries.getByRole(role, { name: label });
+    } catch (error) {
+      errors.push(error instanceof Error ? error.message : String(error));
+    }
+  }
+  throw new Error(
+    `fillField: no text control is labelled ${describe(label)} (looked for roles ${TEXT_ROLES.join(", ")}).
+${errors[0] ?? ""}`
+  );
+}
+async function fillField(target, ...rest) {
+  const byQuery = isQueries(target);
+  const label = byQuery ? rest[0] : void 0;
+  const value = byQuery ? rest[1] : rest[0];
+  const settings = (byQuery ? rest[2] : rest[1]) ?? {};
+  const control = byQuery ? resolveByLabel(target, label) : target;
+  const name = label ?? accessibleText(control);
+  if (!isTextControl(control)) {
+    throw new Error(
+      `fillField: ${describe(name)} is a <${control.tagName.toLowerCase()}>, not a text input or textarea. Use selectOption for a Select and pickDate for a DatePicker.`
+    );
+  }
+  if (isDisabled(control)) throw new Error(`fillField: the control ${describe(name)} is disabled.`);
+  if (control.readOnly || control.getAttribute("aria-readonly") === "true") {
+    throw new Error(`fillField: the control ${describe(name)} is read-only.`);
+  }
+  await typeInto(control, value, settings.commit ?? true);
+}
+
+// src/testing/helpers/pick-date.ts
+var ISO = /^(\d{4})-(\d{2})-(\d{2})$/;
+var DEFAULT_PATTERN = "MM/DD/YYYY";
+function looksLikePattern(text2) {
+  return !!text2 && /YYYY/.test(text2) && /MM/.test(text2) === /DD/.test(text2);
+}
+function formatIso(iso, pattern) {
+  const match = ISO.exec(iso);
+  if (!match) {
+    throw new Error(
+      `pickDate: expected an ISO date (YYYY-MM-DD), received ${JSON.stringify(iso)}.`
+    );
+  }
+  const [, year, month, day] = match;
+  return pattern.replace("YYYY", year).replace("MM", month).replace("DD", day);
+}
+async function pickDate(target, ...rest) {
+  const byQuery = isQueries(target);
+  const label = byQuery ? rest[0] : void 0;
+  const iso = byQuery ? rest[1] : rest[0];
+  const settings = (byQuery ? rest[2] : rest[1]) ?? {};
+  const input = byQuery ? target.getByRole("textbox", { name: label }) : target;
+  const name = label ?? accessibleText(input);
+  if (!isTextControl(input) || input.tagName !== "INPUT") {
+    throw new Error(
+      `pickDate: ${describe(name)} is not a DatePicker text input (a <${input.tagName.toLowerCase()}>).`
+    );
+  }
+  if (isDisabled(input))
+    throw new Error(`pickDate: the date picker ${describe(name)} is disabled.`);
+  if (input.readOnly) throw new Error(`pickDate: the date picker ${describe(name)} is read-only.`);
+  const placeholder = input.getAttribute("placeholder");
+  const pattern = settings.dateFormat ?? (looksLikePattern(placeholder) ? placeholder : DEFAULT_PATTERN);
+  const yearOnly = !/MM|DD/.test(pattern);
+  let display = "";
+  if (iso !== "") {
+    display = yearOnly ? formatIso(iso, "YYYY") : formatIso(iso, pattern);
+  }
+  await typeInto(input, display, true);
+  if (input.value !== display) {
+    throw new Error(
+      `pickDate: typed ${JSON.stringify(display)} into ${describe(name)} but it shows ${JSON.stringify(input.value)}. The picker's pattern is probably not ${JSON.stringify(pattern)}; pass { dateFormat } with the pattern the picker uses.`
+    );
+  }
+}
+
 exports.createToastRecorder = createToastRecorder;
+exports.fillField = fillField;
 exports.installDomPolyfills = installDomPolyfills;
 exports.openMenu = openMenu;
+exports.pickDate = pickDate;
 exports.selectOption = selectOption;
 exports.withAssureDesignSystem = withAssureDesignSystem;

package/dist/testing/index.d.cts

@@ -182,11 +182,22 @@ interface RoleQueries {
 }
 /** Text matcher: exact text (after trimming and collapsing whitespace) or a pattern. @experimental */
 type TextMatch = string | RegExp;
-/** Options for `selectOption` and `openMenu`. @experimental */
+/** Options for the interaction helpers. @experimental */
 interface InteractionOptions {
     /** How many render passes to wait for the popup to appear or close. Default 20. */
     maxFlushes?: number;
 }
+
+/**
+ * Interaction helpers that drive design-system components the way a keyboard
+ * user does, so tests do not encode Radix internals (ADR-014).
+ *
+ * They use only the DOM (roles, `aria-*`, keyboard events) and React's `act`,
+ * so they work with any renderer and any query library. This repository tests
+ * them against the real components; if a component's markup changes, those
+ * tests fail here rather than in a consumer.
+ */
+
 /**
  * Open a design-system `Select` and choose an option by its visible text.
  *
@@ -250,4 +261,89 @@ declare function openMenu(trigger: HTMLElement, options?: InteractionOptions): P
  */
 declare function openMenu(queries: RoleQueries, name: TextMatch, options?: InteractionOptions): Promise<MenuHandle>;
 
-export { type AssureJestOptions, type DomPolyfill, type DomPolyfillOptions, type InteractionOptions, type JestConfigInput, type JestConfigLike, type MenuHandle, type RecordedToast, type RecordedToastVariant, type RoleQueries, type TextMatch, type ToastRecorder, type ToastRecorderOptions, type WithAssureDesignSystem, createToastRecorder, installDomPolyfills, openMenu, selectOption, withAssureDesignSystem };
+/**
+ * `fillField` — type a value into a design-system text control found by its
+ * Field label (ADR-014, W4-26).
+ */
+
+/** Options for `fillField`. @experimental */
+interface FillFieldOptions {
+    /**
+     * Blur the control after typing so controls that commit on blur
+     * (`NumberInput` formatting) settle. Default `true`; pass `false` to keep
+     * focus, for example before pressing Enter yourself.
+     */
+    commit?: boolean;
+}
+/**
+ * Type `value` into a text control — `Input`, `Textarea`, `SearchInput`,
+ * `NumberInput`, a `DatePicker`'s text input — replacing what it holds.
+ *
+ * ```ts
+ * await fillField(screen, "Full name", "Ada Lovelace"); // control named by its Field label
+ * await fillField(screen.getByRole("textbox", { name: "Notes" }), "Late filing");
+ * ```
+ *
+ * The control is found by its accessible name, which inside a `<Field>` is
+ * the `Label` text. React's `onChange` fires once with the new value; the
+ * control's own masking or formatting applies as it would for a user. Throws
+ * when the control is disabled or read-only, or when nothing is labelled
+ * `label`.
+ *
+ * @experimental
+ */
+declare function fillField(control: HTMLElement, value: string, options?: FillFieldOptions): Promise<void>;
+/**
+ * Type `value` into the text control whose accessible name is `label`, found
+ * through `queries` (for example Testing Library's `screen`).
+ *
+ * @experimental
+ */
+declare function fillField(queries: RoleQueries, label: TextMatch, value: string, options?: FillFieldOptions): Promise<void>;
+
+/**
+ * `pickDate` — set a design-system `DatePicker` to an ISO date by typing into
+ * its masked text input (ADR-014, W4-26).
+ */
+
+/** Options for `pickDate`. @experimental */
+interface PickDateOptions {
+    /**
+     * The picker's display pattern — `MM`, `DD` and `YYYY` around literal
+     * separators, as passed to `DatePicker`'s `dateFormat` — when the helper
+     * cannot read it from the input's placeholder (a custom `placeholder`).
+     * Default: the placeholder, else `"MM/DD/YYYY"`.
+     */
+    dateFormat?: string;
+}
+/**
+ * Set a `DatePicker` to `iso` (`YYYY-MM-DD`) by typing the date into its text
+ * input in the picker's own display pattern. `""` clears it.
+ *
+ * ```ts
+ * await pickDate(screen, "Due date", "2025-03-14");           // input named by its Field label
+ * await pickDate(screen.getByRole("textbox", { name: "Due date" }), "2025-03-14");
+ * await pickDate(screen, "Fällig am", "2025-03-14", { dateFormat: "DD.MM.YYYY" });
+ * ```
+ *
+ * The pattern is read from the input's placeholder, which `DatePicker` sets to
+ * its pattern (`MM/DD/YYYY` for `en-US`, `DD.MM.YYYY` for `de-DE`, a custom
+ * `dateFormat`); pass `dateFormat` when the picker has its own placeholder. A
+ * year picker (`picker="year"`, placeholder `YYYY`) receives the year. The
+ * helper checks that the input shows the typed date afterwards, so a picker
+ * that masked it differently — a pattern mismatch — throws instead of
+ * submitting a wrong value. `onValueChange` / `onChange` fire and a `name`d
+ * picker updates its form value, as for a real user.
+ *
+ * @experimental
+ */
+declare function pickDate(input: HTMLElement, iso: string, options?: PickDateOptions): Promise<void>;
+/**
+ * Set the `DatePicker` whose text input has the accessible name `label`
+ * (found through `queries`, for example Testing Library's `screen`) to `iso`.
+ *
+ * @experimental
+ */
+declare function pickDate(queries: RoleQueries, label: TextMatch, iso: string, options?: PickDateOptions): Promise<void>;
+
+export { type AssureJestOptions, type DomPolyfill, type DomPolyfillOptions, type FillFieldOptions, type InteractionOptions, type JestConfigInput, type JestConfigLike, type MenuHandle, type PickDateOptions, type RecordedToast, type RecordedToastVariant, type RoleQueries, type TextMatch, type ToastRecorder, type ToastRecorderOptions, type WithAssureDesignSystem, createToastRecorder, fillField, installDomPolyfills, openMenu, pickDate, selectOption, withAssureDesignSystem };

package/dist/testing/index.d.ts

@@ -182,11 +182,22 @@ interface RoleQueries {
 }
 /** Text matcher: exact text (after trimming and collapsing whitespace) or a pattern. @experimental */
 type TextMatch = string | RegExp;
-/** Options for `selectOption` and `openMenu`. @experimental */
+/** Options for the interaction helpers. @experimental */
 interface InteractionOptions {
     /** How many render passes to wait for the popup to appear or close. Default 20. */
     maxFlushes?: number;
 }
+
+/**
+ * Interaction helpers that drive design-system components the way a keyboard
+ * user does, so tests do not encode Radix internals (ADR-014).
+ *
+ * They use only the DOM (roles, `aria-*`, keyboard events) and React's `act`,
+ * so they work with any renderer and any query library. This repository tests
+ * them against the real components; if a component's markup changes, those
+ * tests fail here rather than in a consumer.
+ */
+
 /**
  * Open a design-system `Select` and choose an option by its visible text.
  *
@@ -250,4 +261,89 @@ declare function openMenu(trigger: HTMLElement, options?: InteractionOptions): P
  */
 declare function openMenu(queries: RoleQueries, name: TextMatch, options?: InteractionOptions): Promise<MenuHandle>;
 
-export { type AssureJestOptions, type DomPolyfill, type DomPolyfillOptions, type InteractionOptions, type JestConfigInput, type JestConfigLike, type MenuHandle, type RecordedToast, type RecordedToastVariant, type RoleQueries, type TextMatch, type ToastRecorder, type ToastRecorderOptions, type WithAssureDesignSystem, createToastRecorder, installDomPolyfills, openMenu, selectOption, withAssureDesignSystem };
+/**
+ * `fillField` — type a value into a design-system text control found by its
+ * Field label (ADR-014, W4-26).
+ */
+
+/** Options for `fillField`. @experimental */
+interface FillFieldOptions {
+    /**
+     * Blur the control after typing so controls that commit on blur
+     * (`NumberInput` formatting) settle. Default `true`; pass `false` to keep
+     * focus, for example before pressing Enter yourself.
+     */
+    commit?: boolean;
+}
+/**
+ * Type `value` into a text control — `Input`, `Textarea`, `SearchInput`,
+ * `NumberInput`, a `DatePicker`'s text input — replacing what it holds.
+ *
+ * ```ts
+ * await fillField(screen, "Full name", "Ada Lovelace"); // control named by its Field label
+ * await fillField(screen.getByRole("textbox", { name: "Notes" }), "Late filing");
+ * ```
+ *
+ * The control is found by its accessible name, which inside a `<Field>` is
+ * the `Label` text. React's `onChange` fires once with the new value; the
+ * control's own masking or formatting applies as it would for a user. Throws
+ * when the control is disabled or read-only, or when nothing is labelled
+ * `label`.
+ *
+ * @experimental
+ */
+declare function fillField(control: HTMLElement, value: string, options?: FillFieldOptions): Promise<void>;
+/**
+ * Type `value` into the text control whose accessible name is `label`, found
+ * through `queries` (for example Testing Library's `screen`).
+ *
+ * @experimental
+ */
+declare function fillField(queries: RoleQueries, label: TextMatch, value: string, options?: FillFieldOptions): Promise<void>;
+
+/**
+ * `pickDate` — set a design-system `DatePicker` to an ISO date by typing into
+ * its masked text input (ADR-014, W4-26).
+ */
+
+/** Options for `pickDate`. @experimental */
+interface PickDateOptions {
+    /**
+     * The picker's display pattern — `MM`, `DD` and `YYYY` around literal
+     * separators, as passed to `DatePicker`'s `dateFormat` — when the helper
+     * cannot read it from the input's placeholder (a custom `placeholder`).
+     * Default: the placeholder, else `"MM/DD/YYYY"`.
+     */
+    dateFormat?: string;
+}
+/**
+ * Set a `DatePicker` to `iso` (`YYYY-MM-DD`) by typing the date into its text
+ * input in the picker's own display pattern. `""` clears it.
+ *
+ * ```ts
+ * await pickDate(screen, "Due date", "2025-03-14");           // input named by its Field label
+ * await pickDate(screen.getByRole("textbox", { name: "Due date" }), "2025-03-14");
+ * await pickDate(screen, "Fällig am", "2025-03-14", { dateFormat: "DD.MM.YYYY" });
+ * ```
+ *
+ * The pattern is read from the input's placeholder, which `DatePicker` sets to
+ * its pattern (`MM/DD/YYYY` for `en-US`, `DD.MM.YYYY` for `de-DE`, a custom
+ * `dateFormat`); pass `dateFormat` when the picker has its own placeholder. A
+ * year picker (`picker="year"`, placeholder `YYYY`) receives the year. The
+ * helper checks that the input shows the typed date afterwards, so a picker
+ * that masked it differently — a pattern mismatch — throws instead of
+ * submitting a wrong value. `onValueChange` / `onChange` fire and a `name`d
+ * picker updates its form value, as for a real user.
+ *
+ * @experimental
+ */
+declare function pickDate(input: HTMLElement, iso: string, options?: PickDateOptions): Promise<void>;
+/**
+ * Set the `DatePicker` whose text input has the accessible name `label`
+ * (found through `queries`, for example Testing Library's `screen`) to `iso`.
+ *
+ * @experimental
+ */
+declare function pickDate(queries: RoleQueries, label: TextMatch, iso: string, options?: PickDateOptions): Promise<void>;
+
+export { type AssureJestOptions, type DomPolyfill, type DomPolyfillOptions, type FillFieldOptions, type InteractionOptions, type JestConfigInput, type JestConfigLike, type MenuHandle, type PickDateOptions, type RecordedToast, type RecordedToastVariant, type RoleQueries, type TextMatch, type ToastRecorder, type ToastRecorderOptions, type WithAssureDesignSystem, createToastRecorder, fillField, installDomPolyfills, openMenu, pickDate, selectOption, withAssureDesignSystem };

package/dist/testing/index.js

@@ -310,14 +310,28 @@ function accessibleText(element) {
 function isDisabled(element) {
   return element.hasAttribute("disabled") || element.getAttribute("aria-disabled") === "true" || element.hasAttribute("data-disabled");
 }
+function isQueries(target) {
+  return typeof target.getByRole === "function";
+}
 function press(target, key) {
   const view = target.ownerDocument.defaultView ?? window;
   const init = { key, code: key === " " ? "Space" : key, bubbles: true, cancelable: true };
   target.dispatchEvent(new view.KeyboardEvent("keydown", init));
   target.dispatchEvent(new view.KeyboardEvent("keyup", init));
 }
+async function run(fn) {
+  const actEnvironment = globalThis.IS_REACT_ACT_ENVIRONMENT;
+  if (actEnvironment) {
+    await act(async () => {
+      await fn();
+    });
+    return;
+  }
+  await fn();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+}
 async function flush() {
-  await act(async () => {
+  await run(async () => {
     await Promise.resolve();
   });
 }
@@ -330,7 +344,7 @@ async function waitUntil(find, maxFlushes) {
   return null;
 }
 function resolveTrigger(target, name, role) {
-  if (typeof target.getByRole === "function") {
+  if (isQueries(target)) {
     if (name === void 0)
       throw new Error(`A ${role} name is required when passing a query object.`);
     return target.getByRole(role, { name });
@@ -348,8 +362,33 @@ function popupOf(trigger, role) {
   }
   return null;
 }
+function isTextControl(element) {
+  const tag = element.tagName;
+  return tag === "TEXTAREA" || tag === "INPUT" && !/^(checkbox|radio|file|button|submit|reset|image|hidden)$/i.test(
+    element.type
+  );
+}
+async function typeInto(control, text2, commit) {
+  const view = control.ownerDocument.defaultView ?? window;
+  const proto = control.tagName === "TEXTAREA" ? view.HTMLTextAreaElement.prototype : view.HTMLInputElement.prototype;
+  const setter = Object.getOwnPropertyDescriptor(proto, "value")?.set;
+  await run(() => {
+    control.focus();
+    if (setter) setter.call(control, text2);
+    else control.value = text2;
+    control.dispatchEvent(new view.Event("input", { bubbles: true }));
+  });
+  if (commit) {
+    await run(() => {
+      control.blur();
+    });
+  }
+  await flush();
+}
+
+// src/testing/interactions.ts
 async function selectOption(target, ...rest) {
-  const byQuery = typeof target.getByRole === "function";
+  const byQuery = isQueries(target);
   const label = byQuery ? rest[0] : void 0;
   const option = byQuery ? rest[1] : rest[0];
   const settings = (byQuery ? rest[2] : rest[1]) ?? {};
@@ -361,7 +400,7 @@ async function selectOption(target, ...rest) {
     );
   }
   if (trigger.getAttribute("aria-expanded") !== "true") {
-    await act(async () => {
+    await run(() => {
       trigger.focus();
       press(trigger, "Enter");
     });
@@ -376,16 +415,16 @@ async function selectOption(target, ...rest) {
   const wanted = all.find((el) => matches(accessibleText(el), option));
   if (!wanted) {
     const available = all.map((el) => JSON.stringify(accessibleText(el))).join(", ");
-    await act(async () => press(listbox, "Escape"));
+    await run(() => press(listbox, "Escape"));
     throw new Error(
       `selectOption: no option matches ${describe(option)}. Options: ${available || "(none)"}.`
     );
   }
   if (isDisabled(wanted)) {
-    await act(async () => press(listbox, "Escape"));
+    await run(() => press(listbox, "Escape"));
     throw new Error(`selectOption: the option ${describe(option)} is disabled.`);
   }
-  await act(async () => {
+  await run(() => {
     wanted.focus();
     press(wanted, "Enter");
   });
@@ -394,7 +433,7 @@ async function selectOption(target, ...rest) {
     throw new Error(`selectOption: the list stayed open after choosing ${describe(option)}.`);
 }
 async function openMenu(target, ...rest) {
-  const byQuery = typeof target.getByRole === "function";
+  const byQuery = isQueries(target);
   const name = byQuery ? rest[0] : void 0;
   const settings = (byQuery ? rest[1] : rest[0]) ?? {};
   const maxFlushes = settings.maxFlushes ?? 20;
@@ -405,7 +444,7 @@ async function openMenu(target, ...rest) {
     );
   }
   if (trigger.getAttribute("aria-expanded") !== "true") {
-    await act(async () => {
+    await run(() => {
       trigger.focus();
       press(trigger, "ArrowDown");
     });
@@ -443,17 +482,98 @@ async function openMenu(target, ...rest) {
       const item = getItem(itemName);
       if (isDisabled(item))
         throw new Error(`openMenu: the item ${describe(itemName)} is disabled.`);
-      await act(async () => {
+      await run(() => {
         item.focus();
         press(item, "Enter");
       });
       await waitUntil(() => menu.isConnected ? null : true, maxFlushes);
     },
     async close() {
-      await act(async () => press(menu, "Escape"));
+      await run(() => press(menu, "Escape"));
       await waitClosed("Escape");
     }
   };
 }
 
-export { createToastRecorder, installDomPolyfills, openMenu, selectOption, withAssureDesignSystem };
+// src/testing/helpers/fill-field.ts
+var TEXT_ROLES = ["textbox", "spinbutton", "combobox"];
+function resolveByLabel(queries, label) {
+  const errors = [];
+  for (const role of TEXT_ROLES) {
+    try {
+      return queries.getByRole(role, { name: label });
+    } catch (error) {
+      errors.push(error instanceof Error ? error.message : String(error));
+    }
+  }
+  throw new Error(
+    `fillField: no text control is labelled ${describe(label)} (looked for roles ${TEXT_ROLES.join(", ")}).
+${errors[0] ?? ""}`
+  );
+}
+async function fillField(target, ...rest) {
+  const byQuery = isQueries(target);
+  const label = byQuery ? rest[0] : void 0;
+  const value = byQuery ? rest[1] : rest[0];
+  const settings = (byQuery ? rest[2] : rest[1]) ?? {};
+  const control = byQuery ? resolveByLabel(target, label) : target;
+  const name = label ?? accessibleText(control);
+  if (!isTextControl(control)) {
+    throw new Error(
+      `fillField: ${describe(name)} is a <${control.tagName.toLowerCase()}>, not a text input or textarea. Use selectOption for a Select and pickDate for a DatePicker.`
+    );
+  }
+  if (isDisabled(control)) throw new Error(`fillField: the control ${describe(name)} is disabled.`);
+  if (control.readOnly || control.getAttribute("aria-readonly") === "true") {
+    throw new Error(`fillField: the control ${describe(name)} is read-only.`);
+  }
+  await typeInto(control, value, settings.commit ?? true);
+}
+
+// src/testing/helpers/pick-date.ts
+var ISO = /^(\d{4})-(\d{2})-(\d{2})$/;
+var DEFAULT_PATTERN = "MM/DD/YYYY";
+function looksLikePattern(text2) {
+  return !!text2 && /YYYY/.test(text2) && /MM/.test(text2) === /DD/.test(text2);
+}
+function formatIso(iso, pattern) {
+  const match = ISO.exec(iso);
+  if (!match) {
+    throw new Error(
+      `pickDate: expected an ISO date (YYYY-MM-DD), received ${JSON.stringify(iso)}.`
+    );
+  }
+  const [, year, month, day] = match;
+  return pattern.replace("YYYY", year).replace("MM", month).replace("DD", day);
+}
+async function pickDate(target, ...rest) {
+  const byQuery = isQueries(target);
+  const label = byQuery ? rest[0] : void 0;
+  const iso = byQuery ? rest[1] : rest[0];
+  const settings = (byQuery ? rest[2] : rest[1]) ?? {};
+  const input = byQuery ? target.getByRole("textbox", { name: label }) : target;
+  const name = label ?? accessibleText(input);
+  if (!isTextControl(input) || input.tagName !== "INPUT") {
+    throw new Error(
+      `pickDate: ${describe(name)} is not a DatePicker text input (a <${input.tagName.toLowerCase()}>).`
+    );
+  }
+  if (isDisabled(input))
+    throw new Error(`pickDate: the date picker ${describe(name)} is disabled.`);
+  if (input.readOnly) throw new Error(`pickDate: the date picker ${describe(name)} is read-only.`);
+  const placeholder = input.getAttribute("placeholder");
+  const pattern = settings.dateFormat ?? (looksLikePattern(placeholder) ? placeholder : DEFAULT_PATTERN);
+  const yearOnly = !/MM|DD/.test(pattern);
+  let display = "";
+  if (iso !== "") {
+    display = yearOnly ? formatIso(iso, "YYYY") : formatIso(iso, pattern);
+  }
+  await typeInto(input, display, true);
+  if (input.value !== display) {
+    throw new Error(
+      `pickDate: typed ${JSON.stringify(display)} into ${describe(name)} but it shows ${JSON.stringify(input.value)}. The picker's pattern is probably not ${JSON.stringify(pattern)}; pass { dateFormat } with the pattern the picker uses.`
+    );
+  }
+}
+
+export { createToastRecorder, fillField, installDomPolyfills, openMenu, pickDate, selectOption, withAssureDesignSystem };