@atomic-testing/component-driver-mui-v9 0.0.0

package/src/components/PaginationDriver.ts

@@ -0,0 +1,117 @@
+import { byAttribute, byCssSelector, ComponentDriver, locatorUtil, PartLocator } from '@atomic-testing/core';
+
+// Numbered page controls are the only ones that carry the `MuiPaginationItem-page`
+// state class; matching on it selects every page button regardless of selection.
+const pageItemLocator = byCssSelector('.MuiPaginationItem-page');
+// MUI marks exactly the selected page with an `aria-current` attribute (value
+// "page"); matching on its presence is version-agnostic.
+const selectedPageLocator = byCssSelector('[aria-current]');
+const firstButtonLocator = byAttribute('aria-label', 'Go to first page');
+const previousButtonLocator = byAttribute('aria-label', 'Go to previous page');
+const nextButtonLocator = byAttribute('aria-label', 'Go to next page');
+const lastButtonLocator = byAttribute('aria-label', 'Go to last page');
+
+/**
+ * Driver for the Material UI v9 Pagination component.
+ *
+ * Pagination renders a `<nav>` whose `MuiPaginationItem` buttons are each wrapped
+ * in their own `<li>` (so they are not siblings — positional `:nth-of-type`
+ * iteration does not apply). Page controls are read by their accessible name
+ * instead: every page button's aria-label ends in its page number ("Go to page N",
+ * or "page N" once selected), and first/previous/next/last carry stable
+ * aria-labels and become `disabled` at the bounds.
+ * @see https://mui.com/material-ui/react-pagination/
+ */
+export class PaginationDriver extends ComponentDriver {
+  private get pageItemsLocator(): PartLocator {
+    return locatorUtil.append(this.locator, pageItemLocator);
+  }
+
+  /**
+   * The selected page number, or `-1` when no page is marked current.
+   */
+  async getSelectedPage(): Promise<number> {
+    const locator = locatorUtil.append(this.locator, selectedPageLocator);
+    if (!(await this.interactor.exists(locator))) {
+      return -1;
+    }
+    const text = await this.interactor.getText(locator);
+    const page = Number.parseInt(text?.trim() ?? '', 10);
+    return Number.isNaN(page) ? -1 : page;
+  }
+
+  /**
+   * Total number of pages, taken from the highest numbered page control. MUI
+   * always renders the upper boundary page (boundaryCount >= 1), so this is exact
+   * even when middle pages collapse into an ellipsis.
+   */
+  async getPageCount(): Promise<number> {
+    const labels = await this.interactor.getAttribute(this.pageItemsLocator, 'aria-label', true);
+    let max = 0;
+    for (const label of labels) {
+      const match = label?.match(/(\d+)\s*$/);
+      if (match != null) {
+        const page = Number.parseInt(match[1], 10);
+        if (page > max) {
+          max = page;
+        }
+      }
+    }
+    return max;
+  }
+
+  /**
+   * Click the numbered control for `page`. A no-op (returns `true`) when `page` is
+   * already selected.
+   * @returns `false` when that page is not currently rendered (e.g. hidden behind
+   * an ellipsis) or is disabled.
+   */
+  async goToPage(page: number): Promise<boolean> {
+    if ((await this.getSelectedPage()) === page) {
+      return true;
+    }
+    const locator = locatorUtil.append(this.locator, byAttribute('aria-label', `Go to page ${page}`));
+    if (!(await this.interactor.exists(locator)) || (await this.interactor.isDisabled(locator))) {
+      return false;
+    }
+    await this.interactor.click(locator);
+    return true;
+  }
+
+  /**
+   * Click a navigation control unless it is absent or disabled (at a bound).
+   * @returns whether the click was performed.
+   */
+  private async clickNavButton(navLocator: PartLocator): Promise<boolean> {
+    const locator = locatorUtil.append(this.locator, navLocator);
+    if (!(await this.interactor.exists(locator)) || (await this.interactor.isDisabled(locator))) {
+      return false;
+    }
+    await this.interactor.click(locator);
+    return true;
+  }
+
+  /** Go to the next page. Returns `false` when on the last page or the control is hidden. */
+  async next(): Promise<boolean> {
+    return this.clickNavButton(nextButtonLocator);
+  }
+
+  /** Go to the previous page. Returns `false` when on the first page or the control is hidden. */
+  async previous(): Promise<boolean> {
+    return this.clickNavButton(previousButtonLocator);
+  }
+
+  /** Jump to the first page. Returns `false` when already there or the control is hidden (needs `showFirstButton`). */
+  async first(): Promise<boolean> {
+    return this.clickNavButton(firstButtonLocator);
+  }
+
+  /** Jump to the last page. Returns `false` when already there or the control is hidden (needs `showLastButton`). */
+  async last(): Promise<boolean> {
+    return this.clickNavButton(lastButtonLocator);
+  }
+
+  override get driverName(): string {
+    return 'MuiV9PaginationDriver';
+  }
+}

package/src/components/ProgressDriver.ts

@@ -0,0 +1,78 @@
+import { HTMLRadioButtonGroupDriver } from '@atomic-testing/component-driver-html';
+import {
+  byCssSelector,
+  byInputType,
+  byValue,
+  ComponentDriver,
+  IComponentDriverOption,
+  IInputDriver,
+  Interactor,
+  locatorUtil,
+  PartLocator,
+  ScenePart,
+} from '@atomic-testing/core';
+
+export const parts = {
+  choices: {
+    locator: byInputType('radio'),
+    driver: HTMLRadioButtonGroupDriver,
+  },
+} satisfies ScenePart;
+
+export class ProgressDriver extends ComponentDriver<typeof parts> implements IInputDriver<number | null> {
+  constructor(locator: PartLocator, interactor: Interactor, option?: Partial<IComponentDriverOption>) {
+    super(locator, interactor, {
+      ...option,
+      parts,
+    });
+  }
+
+  async getValue(): Promise<number | null> {
+    const rawValue = await this.getAttribute('aria-valuenow');
+    const numValue = Number(rawValue);
+    if (rawValue == null || isNaN(numValue)) {
+      return null;
+    }
+    return Number(rawValue);
+  }
+
+  async getType(): Promise<'linear' | 'circular'> {
+    const cssClasses = await this.getAttribute('class');
+    if (cssClasses?.includes('MuiCircularProgress-root')) {
+      return 'circular';
+    }
+    return 'linear';
+  }
+
+  async isDeterminate(): Promise<boolean> {
+    const val = await this.getValue();
+    return val != null;
+  }
+
+  //TODO: Buffer value can be extracted from style="transform: translateX(-15%);" actual value would be 100 - 15 = 85
+  // <span class="MuiLinearProgress-bar MuiLinearProgress-bar2 MuiLinearProgress-colorPrimary MuiLinearProgress-bar2Buffer css-1v1662g-MuiLinearProgress-bar2" style="transform: translateX(-15%);"></span>
+
+  async setValue(value: number | null): Promise<boolean> {
+    // TODO: Setting value to null is not supported.  https://github.com/atomic-testing/atomic-testing/issues/68
+    const currentValue = await this.getValue();
+    if (value === currentValue) {
+      return true;
+    }
+
+    const valueToClick = (value == null ? currentValue : value) as number;
+    const targetLocator = locatorUtil.append(this.parts.choices.locator, byValue(valueToClick.toString(), 'Same'));
+
+    const targetExists = await this.interactor.exists(targetLocator);
+    if (targetExists) {
+      const id = await this.interactor.getAttribute(targetLocator, 'id');
+      const labelLocator = locatorUtil.append(this.locator, byCssSelector(`label[for="${id}"]`));
+      await this.interactor.click(labelLocator);
+    }
+    // TODO: throw error if the value does not exist
+    return targetExists;
+  }
+
+  get driverName(): string {
+    return 'MuiV9ProgressDriver';
+  }
+}

package/src/components/RadioDriver.ts

@@ -0,0 +1,63 @@
+import { byCssSelector, ComponentDriver, locatorUtil, Optional, PartLocator } from '@atomic-testing/core';
+
+// The radio `<input>` carries checked/value/disabled; located as a descendant of
+// this option's FormControlLabel root.
+const inputLocator: PartLocator = byCssSelector('input');
+const checkedInputLocator: PartLocator = byCssSelector('input:checked');
+
+/**
+ * Driver for a single Material UI v9 Radio option (a `FormControlLabel` wrapping a
+ * `Radio`). Its label text is the `FormControlLabel`'s text; selected/value/disabled
+ * state is read from the underlying radio `<input>`.
+ *
+ * Used as the item driver of {@link RadioGroupDriver}, but also usable on its own
+ * when a single radio option is addressed directly. It declares no parts (so it
+ * composes as a list item) and reads the input via descendant locators.
+ * @see https://mui.com/material-ui/react-radio-button/
+ */
+export class RadioDriver extends ComponentDriver {
+  private get input(): PartLocator {
+    return locatorUtil.append(this.locator, inputLocator);
+  }
+
+  /**
+   * The option's visible label, or `undefined` when it renders without text.
+   */
+  async getLabel(): Promise<Optional<string>> {
+    const text = await this.getText();
+    return text?.trim() || undefined;
+  }
+
+  /**
+   * The option's `value` attribute.
+   */
+  async getValue(): Promise<string | null> {
+    const value = await this.interactor.getAttribute(this.input, 'value');
+    return value ?? null;
+  }
+
+  /**
+   * Whether this option is the selected one in its group.
+   */
+  isSelected(): Promise<boolean> {
+    return this.interactor.exists(locatorUtil.append(this.locator, checkedInputLocator));
+  }
+
+  /**
+   * Whether this option is disabled.
+   */
+  isDisabled(): Promise<boolean> {
+    return this.interactor.isDisabled(this.input);
+  }
+
+  /**
+   * Select this option by clicking its radio input. No-op effect when already selected.
+   */
+  async select(): Promise<void> {
+    await this.interactor.click(this.input);
+  }
+
+  get driverName(): string {
+    return 'MuiV9RadioDriver';
+  }
+}

package/src/components/RadioGroupDriver.ts

@@ -0,0 +1,129 @@
+import {
+  byCssSelector,
+  escapeUtil,
+  IComponentDriverOption,
+  IInputDriver,
+  Interactor,
+  ListComponentDriver,
+  ListComponentDriverSpecificOption,
+  locatorUtil,
+  Nullable,
+  PartLocator,
+} from '@atomic-testing/core';
+
+import { RadioDriver } from './RadioDriver';
+
+/**
+ * Radio options are located by their `FormControlLabel` root, which wraps the
+ * radio `<input>` and renders the label text — the unit a {@link RadioDriver}
+ * drives.
+ */
+export const defaultRadioGroupDriverOption: ListComponentDriverSpecificOption<RadioDriver> = {
+  itemClass: RadioDriver,
+  itemLocator: byCssSelector('.MuiFormControlLabel-root'),
+};
+
+type RadioGroupDriverOption<ItemT extends RadioDriver> = ListComponentDriverSpecificOption<ItemT> &
+  Partial<IComponentDriverOption<any>>;
+
+/**
+ * Driver for the Material UI v9 RadioGroup component.
+ *
+ * `<RadioGroup>` renders a `role="radiogroup"` whose options are `FormControlLabel`s
+ * wrapping a radio `<input>`. This driver is a {@link ListComponentDriver} over those
+ * options, so per-option {@link RadioDriver} instances are available via
+ * `getItems`/`getItemByIndex`/`getItemByLabel`, on top of the group-level value and
+ * label helpers. The selected value is read from the checked `<input>` and selection
+ * is made by value or label.
+ * @see https://mui.com/material-ui/react-radio-button/
+ */
+export class RadioGroupDriver<ItemT extends RadioDriver = RadioDriver>
+  extends ListComponentDriver<ItemT>
+  implements IInputDriver<string | null>
+{
+  constructor(locator: PartLocator, interactor: Interactor, option: Partial<RadioGroupDriverOption<ItemT>> = {}) {
+    // The option shape is fixed (FormControlLabel options driven by RadioDriver),
+    // so defaults are merged in rather than relying on a default parameter, which a
+    // scene part's always-present option object would otherwise shadow.
+    super(locator, interactor, {
+      ...defaultRadioGroupDriverOption,
+      ...option,
+    } as RadioGroupDriverOption<ItemT>);
+  }
+
+  /**
+   * The `value` of the selected option, or `null` when none is selected.
+   */
+  async getValue(): Promise<string | null> {
+    const checked = locatorUtil.append(this.locator, byCssSelector('input:checked'));
+    const value = await this.interactor.getAttribute(checked, 'value');
+    return value ?? null;
+  }
+
+  /**
+   * Select the option whose radio `<input>` has the given `value`.
+   * @returns `false` when no option has that value, or when `value` is `null`.
+   */
+  async setValue(value: string | null): Promise<boolean> {
+    if (value == null) {
+      return false;
+    }
+    const input = locatorUtil.append(this.locator, byCssSelector(`input[value="${escapeUtil.escapeValue(value)}"]`));
+    if (!(await this.interactor.exists(input))) {
+      return false;
+    }
+    await this.interactor.click(input);
+    return true;
+  }
+
+  /**
+   * The visible label of every option, in DOM order.
+   */
+  async getOptions(): Promise<string[]> {
+    const items = await this.getItems();
+    const labels: string[] = [];
+    for (const item of items) {
+      labels.push((await item.getLabel()) ?? '');
+    }
+    return labels;
+  }
+
+  /**
+   * The label of the selected option, or `null` when none is selected.
+   */
+  async getSelectedLabel(): Promise<Nullable<string>> {
+    const items = await this.getItems();
+    for (const item of items) {
+      if (await item.isSelected()) {
+        return (await item.getLabel()) ?? null;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Select the first option whose visible label equals `label`.
+   * @returns `false` when no option matches.
+   */
+  async selectByLabel(label: string): Promise<boolean> {
+    const option = await this.getItemByLabel(label);
+    if (option == null) {
+      return false;
+    }
+    await option.select();
+    return true;
+  }
+
+  /**
+   * Whether the option with the given label is disabled.
+   * @returns `false` when no option matches.
+   */
+  async isOptionDisabled(label: string): Promise<boolean> {
+    const option = await this.getItemByLabel(label);
+    return option == null ? false : option.isDisabled();
+  }
+
+  override get driverName(): string {
+    return 'MuiV9RadioGroupDriver';
+  }
+}

package/src/components/RatingDriver.ts

@@ -0,0 +1,121 @@
+import { HTMLRadioButtonGroupDriver } from '@atomic-testing/component-driver-html';
+import {
+  byCssClass,
+  byCssSelector,
+  byInputType,
+  byValue,
+  ComponentDriver,
+  IComponentDriverOption,
+  IInputDriver,
+  Interactor,
+  locatorUtil,
+  PartLocator,
+  ScenePart,
+} from '@atomic-testing/core';
+
+export const parts = {
+  choices: {
+    locator: byInputType('radio'),
+    driver: HTMLRadioButtonGroupDriver,
+  },
+} satisfies ScenePart;
+
+/**
+ * MUI marks the disabled/read-only state with a class on the Rating root span
+ * (`Mui-disabled` / `Mui-readOnly`), not on the visually-hidden radio inputs that
+ * the composed {@link HTMLRadioButtonGroupDriver} can see — so these states are
+ * only observable from the root element.
+ */
+const disabledClassName = 'Mui-disabled';
+const readOnlyClassName = 'Mui-readOnly';
+const filledIconClassName = 'MuiRating-iconFilled';
+
+export class RatingDriver extends ComponentDriver<typeof parts> implements IInputDriver<number | null> {
+  constructor(locator: PartLocator, interactor: Interactor, option?: Partial<IComponentDriverOption>) {
+    super(locator, interactor, {
+      ...option,
+      parts,
+    });
+  }
+
+  async getValue(): Promise<number | null> {
+    // A read-only Rating renders no radio inputs (root becomes `role="img"` with the
+    // value carried in `aria-label`), so the radio-based read below cannot be used.
+    const isReadOnly = await this.interactor.hasCssClass(this.locator, readOnlyClassName);
+    if (isReadOnly) {
+      return this.getReadOnlyValue();
+    }
+
+    await this.enforcePartExistence('choices');
+    const value = await this.parts.choices.getValue();
+    // The "no rating" state is the visually-hidden radio whose `value` attribute is the
+    // empty string; treat it the same as an absent selection.
+    if (value == null || value === '') {
+      return null;
+    }
+    return parseFloat(value);
+  }
+
+  /**
+   * Read the value of a read-only Rating.
+   *
+   * Primary source is the root's `aria-label`, which MUI populates with the accessible
+   * name (e.g. `"2.5 Stars"`) — accessibility-first and precision-accurate. When a
+   * caller supplies a custom, non-numeric `aria-label`, fall back to counting the
+   * filled star icons; that count is exact for whole-star ratings.
+   */
+  private async getReadOnlyValue(): Promise<number | null> {
+    const label = await this.interactor.getAttribute(this.locator, 'aria-label');
+    if (label != null) {
+      const parsed = parseFloat(label);
+      if (!Number.isNaN(parsed)) {
+        return parsed;
+      }
+    }
+
+    const filledLocator = locatorUtil.append(this.locator, byCssClass(filledIconClassName));
+    const filledIcons = await this.interactor.getAttribute(filledLocator, 'class', true);
+    return filledIcons.length > 0 ? filledIcons.length : null;
+  }
+
+  /**
+   * Whether the Rating is disabled. `disabled` is reflected as the `Mui-disabled`
+   * class on the root span (the composed radio-group driver exposes no `isDisabled`).
+   */
+  async isDisabled(): Promise<boolean> {
+    return this.interactor.hasCssClass(this.locator, disabledClassName);
+  }
+
+  async setValue(value: number | null): Promise<boolean> {
+    const currentValue = await this.getValue();
+    if (value === currentValue) {
+      return true;
+    }
+
+    // Clearing (value == null) reuses MUI's "click the selected star again to
+    // reset" behaviour by re-clicking the current value's label. This resets the
+    // rating in real browsers but not in jsdom, where MUI's clear path depends on
+    // pointer coordinates that jsdom does not provide; the empty radio (`value=""`)
+    // that jsdom could click has no `<label>` and is not reliably clickable in
+    // browsers. A fully portable clear needs a coordinate-free click primitive on
+    // the Interactor. TODO(#68): revisit once that primitive exists.
+    const valueToClick = value ?? currentValue;
+    if (valueToClick == null) {
+      return true;
+    }
+
+    const targetLocator = locatorUtil.append(this.parts.choices.locator, byValue(valueToClick.toString(), 'Same'));
+    const targetExists = await this.interactor.exists(targetLocator);
+    if (targetExists) {
+      const id = await this.interactor.getAttribute(targetLocator, 'id');
+      const labelLocator = locatorUtil.append(this.locator, byCssSelector(`label[for="${id}"]`));
+      await this.interactor.click(labelLocator);
+    }
+    // TODO: throw error if the value does not exist
+    return targetExists;
+  }
+
+  get driverName(): string {
+    return 'MuiV9RatingDriver';
+  }
+}