@ngneers/controls-playwright 0.0.1-pre1

package/src/components/mask-input.ts

@@ -0,0 +1,119 @@
+import { type Locator, expect } from '@playwright/test';
+import { themeClasses } from '../utils/theme';
+import { maskInputControlTemplate } from '@ngneers/controls-themes/templates/mask-input';
+
+/**
+ * Playwright harness for `ngn-mask-input` (v2).
+ *
+ * ## Value assertion
+ * The control's `value` model (the serialized string, or `null` when incomplete)
+ * is NOT written into any DOM element — the proxy input stays empty at all times.
+ * E2E tests must assert the emitted value via a bound echo element rendered by the
+ * test component (e.g. `<span data-testid="value">{{ inputs().value }}</span>`).
+ * This harness intentionally does NOT expose an `expectValue` method.
+ */
+export class NgnMaskInputHarness {
+  public readonly classes = themeClasses(maskInputControlTemplate);
+
+  /**
+   * The visually-hidden proxy input — this is the element that receives focus
+   * and keyboard events. All `press` / `pressSequentially` calls target it.
+   */
+  public readonly proxy: Locator;
+
+  /**
+   * All `[role="spinbutton"]` section spans (both filled and placeholder state).
+   */
+  public readonly sections: Locator;
+
+  constructor(private readonly locator: Locator) {
+    // The proxy is the only <input> inside the control.
+    this.proxy = locator.locator('input').first();
+    this.sections = locator.locator('[role="spinbutton"]');
+  }
+
+  /** Focus the proxy input so subsequent key events are delivered to the control. */
+  public async focus(): Promise<void> {
+    await this.proxy.focus();
+  }
+
+  /** Press a single key on the proxy input (e.g. 'ArrowRight', 'Backspace', '1'). */
+  public async press(key: string): Promise<void> {
+    await this.proxy.focus();
+    await this.proxy.press(key);
+  }
+
+  /** Type a string of characters into the proxy input one by one, with a small delay. */
+  public async pressSequentially(text: string): Promise<void> {
+    await this.proxy.focus();
+    await this.proxy.pressSequentially(text, { delay: 5 });
+  }
+
+  /**
+   * Assert the visible rendered text of the control — the concatenation (with no
+   * separator) of all section, section-placeholder, and separator spans in DOM order.
+   * Screen-reader-only (`sr-only`) spans are excluded.
+   *
+   * Example: for a time mask `HH:MM:SS` with `12` entered in the first section
+   * the visible text is `'12:MM:SS'`.
+   *
+   * Uses Playwright's auto-retry (`expect.poll`) so it waits for Angular to render.
+   */
+  public expectText(visible: string): Promise<void> {
+    const visibleSelector = [
+      this.classes['section'],
+      this.classes['section-placeholder'],
+      this.classes.separator,
+    ].join(', ');
+
+    return expect
+      .poll(async () => {
+        const texts = await this.locator.locator(visibleSelector).allInnerTexts();
+        return texts.join('');
+      })
+      .toEqual(visible);
+  }
+
+  /**
+   * Returns the value of `aria-activedescendant` from the proxy input, which
+   * is the `id` of the currently focused section span. Returns `null` when the
+   * attribute is absent.
+   */
+  public async activeDescendantId(): Promise<string | null> {
+    const val = await this.proxy.getAttribute('aria-activedescendant');
+    return val ?? null;
+  }
+
+  /**
+   * Assert the innerText of the currently active section span.
+   * Useful for verifying which section is focused and what value it shows.
+   */
+  public async expectActiveText(text: string): Promise<void> {
+    const id = await this.activeDescendantId();
+    if (id === null) {
+      throw new Error('No aria-activedescendant on proxy — no active section');
+    }
+    const activeSpan = this.locator.locator(`#${id}`);
+    await expect(activeSpan).toHaveText(text, { useInnerText: true });
+  }
+
+  /**
+   * Clear all sections by focusing the proxy, pressing Home to jump to the first
+   * section, then pressing Backspace twice per section (once to clear the value,
+   * once to step back if it was already empty — harmless no-op).
+   *
+   * This is intentionally blunt: it over-presses rather than inspecting state.
+   */
+  public async clear(): Promise<void> {
+    await this.proxy.focus();
+    // Start from the LAST section: Backspace clears the active section then steps
+    // to the previous one, so walking from the end clears every section. Starting
+    // from Home would get stuck on section 0 (Backspace there is a no-op).
+    await this.proxy.press('End');
+    const count = await this.sections.count();
+    for (let i = 0; i < count; i++) {
+      await this.proxy.press('Backspace');
+      await this.proxy.press('Backspace');
+    }
+  }
+}

package/src/components/menu.ts

@@ -0,0 +1,29 @@
+import { expect, type Locator } from '@playwright/test';
+import { themeClasses } from '../utils/theme';
+import { menuControlTemplate } from '@ngneers/controls-themes/templates/menu';
+import { NgnPopoverHarness } from './popover';
+
+export class NgnMenuHarness {
+  public readonly classes = themeClasses(menuControlTemplate);
+  public readonly popover: NgnPopoverHarness;
+  public readonly item: Locator;
+
+  constructor(public locator: Locator) {
+    this.popover = new NgnPopoverHarness(locator.locator(this.classes['popover']['root']));
+    this.item = locator.locator(this.classes['item']);
+  }
+
+  public async expectItemCount(count: number) {
+    await expect(this.item).toHaveCount(count);
+  }
+
+  public async getItemByIndex(index: number) {
+    return this.item.nth(index);
+  }
+
+  public async openChildMenuByIndex(index: number) {
+    const item = this.item.nth(index);
+    await item.click();
+    return new NgnMenuHarness(item.locator('ngn-menu').first());
+  }
+}

package/src/components/message.ts

@@ -0,0 +1,25 @@
+import { messageControlTemplate } from '@ngneers/controls-themes/templates/message';
+import { themeClasses } from '../utils/theme';
+import test, { expect, type Locator } from '@playwright/test';
+
+export class NgnMessageHarness {
+  public readonly classes = themeClasses(messageControlTemplate);
+
+  public readonly locator: Locator;
+  public readonly content: Locator;
+  public readonly icon: Locator;
+
+  constructor(locator: Locator) {
+    this.locator = locator;
+    this.content = locator.locator(this.classes.content);
+    this.icon = locator.locator(this.classes.icon);
+  }
+
+  public async expectIcon(hasIcon: boolean) {
+    if (hasIcon) {
+      await expect(this.icon).toBeVisible();
+    } else {
+      await expect(this.icon).not.toBeVisible();
+    }
+  }
+}

package/src/components/popover.ts

@@ -0,0 +1,39 @@
+import { type Locator, expect } from '@playwright/test';
+import { themeClasses } from '../utils/theme';
+import { popoverControlTemplate } from '@ngneers/controls-themes/templates/popover';
+
+export class NgnPopoverHarness {
+  public readonly classes = themeClasses(popoverControlTemplate);
+
+  private readonly _ngnLazyCacher: Locator;
+  private readonly _contentWrapper: Locator;
+  private readonly _content: Locator;
+
+  constructor(locator: Locator) {
+    this._ngnLazyCacher = locator.locator('ngn-defer');
+    this._contentWrapper = locator.locator(this.classes.content);
+    this._content = this._ngnLazyCacher.locator('> *');
+  }
+
+  public get content(): Locator {
+    return this._content;
+  }
+
+  public async expectOpened() {
+    await expect(this._contentWrapper).toBeVisible();
+  }
+
+  public async expectRendered(rendered = true): Promise<void> {
+    await expect(this._ngnLazyCacher).toBeAttached();
+    await expect(async () => {
+      const el = await this._ngnLazyCacher.elementHandle();
+      const hasContent =
+        !!(await el?.innerText()) || !!(await el?.evaluate(e => e.childElementCount));
+      if (rendered) {
+        expect(hasContent).toBeTruthy();
+      } else {
+        expect(hasContent).toBeFalsy();
+      }
+    }).toPass({ timeout: 2000 });
+  }
+}

package/src/components/progress.ts

@@ -0,0 +1,53 @@
+import { progressControlTemplate } from '@ngneers/controls-themes/templates/progress';
+import { themeClasses } from '../utils/theme';
+import test, { expect, type Locator } from '@playwright/test';
+
+export class NgnProgressHarness {
+  public readonly classes = themeClasses(progressControlTemplate);
+
+  public readonly locator: Locator;
+  public readonly track: Locator;
+  public readonly fill: Locator;
+  public readonly fill2: Locator;
+  public readonly svg: Locator;
+
+  constructor(locator: Locator) {
+    this.locator = locator;
+    this.track = locator.locator(this.classes.track);
+    this.fill = locator.locator(this.classes.fill);
+    this.fill2 = locator.locator(this.classes.fill2);
+    this.svg = locator.locator(this.classes.svg);
+  }
+
+  public async expectValue(value: number) {
+    await expect(this.locator).toHaveAttribute('aria-valuenow', value.toString());
+  }
+
+  public async expectMin(min: number) {
+    await expect(this.locator).toHaveAttribute('aria-valuemin', min.toString());
+  }
+
+  public async expectMax(max: number) {
+    await expect(this.locator).toHaveAttribute('aria-valuemax', max.toString());
+  }
+
+  public async expectVisible() {
+    await expect(this.locator).toBeVisible();
+  }
+
+  public async expectIndeterminate(indeterminate: boolean) {
+    if (indeterminate) {
+      await expect(this.fill2).toBeAttached();
+    } else {
+      await expect(this.fill2).not.toBeAttached();
+    }
+  }
+
+  public async expectCircular(circular: boolean) {
+    if (circular) {
+      await expect(this.svg).toBeVisible();
+    } else {
+      await expect(this.svg).not.toBeAttached();
+    }
+  }
+}

package/src/components/radio.ts

@@ -0,0 +1,42 @@
+import { type Locator, expect } from '@playwright/test';
+
+export class NgnRadioGroupHarness {
+  public readonly locator: Locator;
+  /** All radio options in the group, in DOM order. */
+  public readonly radios: Locator;
+
+  constructor(locator: Locator) {
+    this.locator = locator;
+    this.radios = locator.locator('ngn-radio');
+  }
+
+  public radio(index: number): Locator {
+    return this.radios.nth(index);
+  }
+
+  /** Click the radio at `index` to select it. */
+  public async select(index: number, force = false) {
+    await this.radio(index).click({ force });
+  }
+
+  public async expectSelected(index: number) {
+    await expect(this.radio(index)).toHaveAttribute('aria-checked', 'true');
+  }
+
+  public async expectNotSelected(index: number) {
+    await expect(this.radio(index)).toHaveAttribute('aria-checked', 'false');
+  }
+
+  public async expectDisabled(index: number, disabled = true) {
+    if (disabled) {
+      await expect(this.radio(index)).toHaveAttribute('aria-disabled', 'true');
+    } else {
+      await expect(this.radio(index)).not.toHaveAttribute('aria-disabled', 'true');
+    }
+  }
+
+  /** Focus the currently active radio (the group's single tab stop). */
+  public async focusActive() {
+    await this.locator.locator('ngn-radio[tabindex="0"]').focus();
+  }
+}

package/src/components/scroller.ts

@@ -0,0 +1,68 @@
+import { expect, type Locator } from '@playwright/test';
+import { themeClasses } from '../utils/theme';
+import { scrollerControlTemplate } from '@ngneers/controls-themes/templates/scroller';
+
+export class NgnScrollerHarness {
+  public readonly classes = themeClasses(scrollerControlTemplate);
+  public readonly scrollarea: Locator;
+  public readonly item: Locator;
+  public readonly itemSticky: Locator;
+
+  constructor(public locator: Locator) {
+    this.scrollarea = locator;
+    this.item = locator.locator(`> :not(${this.classes['item-sticky']})`);
+    this.itemSticky = locator.locator(this.classes['item-sticky']);
+  }
+
+  public expectItemsCount(count: number): Promise<void> {
+    return expect(this.item).toHaveCount(count);
+  }
+
+  public expectStickyItemsCount(count: number): Promise<void> {
+    return expect(this.itemSticky).toHaveCount(count);
+  }
+
+  public expectItemsCountBetween(min: number, max: number): Promise<void> {
+    return expect(async () => {
+      const count = await this.item.count();
+      if (count < min || count > max) {
+        throw new Error(`Expected item count to be between ${min} and ${max}, but got ${count}`);
+      }
+    }).toPass();
+  }
+
+  public expectItemsTexts(texts: string[]): Promise<void> {
+    return expect(this.item).toHaveText(texts);
+  }
+
+  public expectStickyItemsTexts(texts: string[]): Promise<void> {
+    return expect(this.itemSticky).toHaveText(texts);
+  }
+
+  public clickItemByIndex(index: number): Promise<void> {
+    return this.item.nth(index).click();
+  }
+
+  public clickItemByText(text: string): Promise<void> {
+    return this.item.filter({ hasText: new RegExp(`^\\s*${text}\\s*$`, 'i') }).click();
+  }
+
+  public getItemByIndex(index: number): Locator {
+    return this.item.nth(index);
+  }
+
+  public getItemByText(text: string): Locator {
+    return this.item.filter({ hasText: new RegExp(`^\\s*${text}\\s*$`, 'i') });
+  }
+
+  public async scrollToIndex(index: number, itemHeight?: number): Promise<void> {
+    if (!itemHeight) {
+      await this.item.nth(index).scrollIntoViewIfNeeded();
+      return;
+    }
+    const scrollAmount = index * itemHeight;
+    await this.scrollarea.evaluate((el, amount) => {
+      el.scrollTo({ top: amount });
+    }, scrollAmount);
+  }
+}

package/src/components/select-button.ts

@@ -0,0 +1,57 @@
+import { type Locator, expect } from '@playwright/test';
+import { themeClasses } from '../utils/theme';
+import { selectButtonControlTemplate } from '@ngneers/controls-themes/templates/select-button';
+import { NgnToggleButtonHarness } from './toggle-button';
+
+export class NgnSelectButtonHarness {
+  public readonly classes = themeClasses(selectButtonControlTemplate);
+
+  public readonly locator: Locator;
+  public readonly buttons: Locator;
+
+  constructor(locator: Locator) {
+    this.locator = locator;
+    this.buttons = locator.locator('ngn-toggle-button');
+  }
+
+  public getButtonAt(index: number): NgnToggleButtonHarness {
+    return new NgnToggleButtonHarness(this.buttons.nth(index));
+  }
+
+  public getButtonByTestId(testId: string): NgnToggleButtonHarness {
+    return new NgnToggleButtonHarness(
+      this.locator.locator(`ngn-toggle-button[data-testid="${testId}"]`)
+    );
+  }
+
+  public async clickButtonAt(index: number, force = false) {
+    await this.getButtonAt(index).click(force);
+  }
+
+  public async expectButtonCount(count: number) {
+    await expect(this.buttons).toHaveCount(count);
+  }
+
+  public async expectSelectedAt(index: number) {
+    await this.getButtonAt(index).expectActive(true);
+  }
+
+  public async expectNoneSelected() {
+    const count = await this.buttons.count();
+    for (let i = 0; i < count; i++) {
+      await this.getButtonAt(i).expectActive(false);
+    }
+  }
+
+  public async expectDisabled(disabled: boolean) {
+    const innerButtons = this.locator.locator('button');
+    const count = await innerButtons.count();
+    for (let i = 0; i < count; i++) {
+      if (disabled) {
+        await expect(innerButtons.nth(i)).toBeDisabled();
+      } else {
+        await expect(innerButtons.nth(i)).not.toBeDisabled();
+      }
+    }
+  }
+}

package/src/components/select.ts

@@ -0,0 +1,81 @@
+import { expect, type Locator } from '@playwright/test';
+import { themeClasses } from '../utils/theme';
+import { selectControlTemplate } from '@ngneers/controls-themes/templates/select';
+import { NgnInputHarness } from './input';
+import { NGN_CLASSES } from '../utils/classes';
+import { NgnListBoxHarness } from './list-box';
+import { NgnInputFieldHarness } from './input-field';
+import { NgnItemViewHarness } from './item-view';
+
+export class NgnSelectHarness {
+  public readonly classes = themeClasses(selectControlTemplate);
+  public readonly filter: NgnInputFieldHarness<{ input: NgnInputHarness }>;
+  public readonly filterIcon: Locator;
+  public readonly icon: Locator;
+  public readonly input: Locator;
+  public readonly inputEditable: NgnInputHarness;
+  public readonly listBox: NgnListBoxHarness;
+  public readonly popoverContent: Locator;
+  public readonly multipleItemView: NgnItemViewHarness;
+
+  constructor(public locator: Locator) {
+    this.filter = new NgnInputFieldHarness(locator.locator(this.classes['filter']['root']), l => ({
+      input: new NgnInputHarness(l.locator(NGN_CLASSES.input['root'])),
+    }));
+    this.filterIcon = locator.locator(this.classes['filter-icon']);
+    this.icon = locator.locator(this.classes['icon']);
+    this.input = locator.locator(this.classes['input']);
+    this.inputEditable = new NgnInputHarness(
+      locator.locator(`${this.classes['input-editable']} ${NGN_CLASSES.input['root']}`)
+    );
+    this.listBox = new NgnListBoxHarness(locator.locator(this.classes['list-box']['root']));
+    this.popoverContent = locator.locator(this.classes['popover-content']);
+    this.multipleItemView = new NgnItemViewHarness(locator.locator('ngn-item-view'));
+  }
+
+  public async expectOpened(opened = true) {
+    // Gate on the trigger's `aria-expanded` (bound to `popover.open()`), not just
+    // content visibility. `open()` is only set once the native popover has
+    // actually toggled in the top layer, whereas the content becomes CSS-visible
+    // a frame earlier — before the popover is a dismissible top-layer element.
+    // Waiting on visibility alone lets a follow-up keypress (e.g. Escape) race
+    // the open transition under load and get lost, leaving the popover stuck
+    // open. The `aria-expanded`/`aria-haspopup` attributes live on the inner
+    // combobox/input trigger, not the outer `input` wrapper.
+    const trigger = this.locator.locator('[aria-haspopup="listbox"]');
+    await expect(trigger).toHaveAttribute('aria-expanded', String(opened));
+    await expect(this.popoverContent).toBeVisible({ visible: opened });
+  }
+
+  public async open() {
+    await this.icon.click();
+    await this.expectOpened();
+  }
+
+  public async close() {
+    await this.icon.click();
+    await this.expectOpened(false);
+  }
+
+  public async expectSelectedItemText(text: string, editable = false) {
+    if (editable) {
+      await this.inputEditable.expectValue(text);
+    } else {
+      await expect(this.input).toHaveText(text, { useInnerText: true });
+    }
+  }
+
+  public async clickItemByText(text: string, expectClosed = true) {
+    await this.listBox.scroller.clickItemByText(text);
+    if (expectClosed) {
+      await this.expectOpened(false);
+    }
+  }
+
+  public async clickItemByIndex(index: number, expectClosed = true) {
+    await this.listBox.scroller.clickItemByIndex(index);
+    if (expectClosed) {
+      await this.expectOpened(false);
+    }
+  }
+}

package/src/components/slider.ts

@@ -0,0 +1,84 @@
+import { sliderControlTemplate } from '@ngneers/controls-themes/templates/slider';
+import { themeClasses } from '../utils/theme';
+import test, { expect, type Locator } from '@playwright/test';
+
+export class NgnSliderHarness {
+  public readonly classes = themeClasses(sliderControlTemplate);
+
+  public readonly locator: Locator;
+  public readonly track: Locator;
+  public readonly thumb: Locator;
+  public readonly fill: Locator;
+
+  constructor(locator: Locator) {
+    this.locator = locator;
+    this.track = locator.locator(this.classes.track);
+    this.thumb = locator.locator(this.classes.thumb);
+    this.fill = locator.locator(this.classes.fill);
+  }
+
+  public async expectValue(value: number) {
+    await expect(this.locator).toHaveAttribute('aria-valuenow', value.toString());
+  }
+
+  public async expectMin(min: number) {
+    await expect(this.locator).toHaveAttribute('aria-valuemin', min.toString());
+  }
+
+  public async expectMax(max: number) {
+    await expect(this.locator).toHaveAttribute('aria-valuemax', max.toString());
+  }
+
+  public async expectOrientation(orientation: 'horizontal' | 'vertical') {
+    await expect(this.locator).toHaveAttribute('aria-orientation', orientation);
+  }
+
+  public async expectReadonly(readonly: boolean) {
+    if (readonly) {
+      await expect(this.locator).toHaveAttribute('aria-readonly', 'true');
+      await expect(this.locator).toHaveAttribute('tabindex', '0');
+    } else {
+      await expect(this.locator).not.toHaveAttribute('aria-readonly');
+    }
+  }
+
+  public async expectDisabled(disabled: boolean) {
+    if (disabled) {
+      await expect(this.locator).toHaveAttribute('disabled');
+      await expect(this.locator).toHaveAttribute('tabindex', '-1');
+    } else {
+      await expect(this.locator).not.toHaveAttribute('disabled');
+    }
+  }
+
+  public async clickTrack(position: { x?: number; y?: number } = {}) {
+    const box = await this.track.boundingBox();
+    if (!box) {
+      throw new Error('Track not found');
+    }
+    const x = position.x !== undefined ? box.x + position.x : box.x + box.width / 2;
+    const y = position.y !== undefined ? box.y + position.y : box.y + box.height / 2;
+    await this.track.click({ position: { x: x - box.x, y: y - box.y } });
+  }
+
+  public async dragThumb(delta: { x?: number; y?: number }) {
+    await this.thumb.hover();
+    await this.locator.page().mouse.down();
+    const box = await this.thumb.boundingBox();
+    if (!box) {
+      throw new Error('Thumb not found');
+    }
+    await this.locator
+      .page()
+      .mouse.move(box.x + box.width / 2 + (delta.x || 0), box.y + box.height / 2 + (delta.y || 0));
+    await this.locator.page().mouse.up();
+  }
+
+  public async pressKey(key: string) {
+    await this.locator.press(key);
+  }
+
+  public async focus() {
+    await this.locator.focus();
+  }
+}

package/src/components/snackbar.ts

@@ -0,0 +1,84 @@
+import { snackbarControlTemplate } from '@ngneers/controls-themes/templates/snackbar';
+import { themeClasses } from '../utils/theme';
+import { expect, type Locator, type Page } from '@playwright/test';
+
+export class NgnSnackbarHarness {
+  public readonly classes = themeClasses(snackbarControlTemplate);
+
+  public readonly locator: Locator;
+  public readonly header: Locator;
+  public readonly content: Locator;
+  public readonly icon: Locator;
+  public readonly closeButton: Locator;
+
+  constructor(locator: Locator) {
+    this.locator = locator;
+    this.header = locator.locator(this.classes.defaultHeader);
+    this.content = locator.locator(this.classes.defaultContent);
+    this.icon = this.header.locator('ngn-icon').first();
+    // The close button is a direct child of the snackbar root (sibling of the body), not inside
+    // the header. It is the only <button> in the snackbar, so match it directly.
+    this.closeButton = locator.locator('button');
+  }
+
+  public async expectVisible() {
+    await expect(this.locator).toBeVisible();
+  }
+
+  public async expectHidden() {
+    await expect(this.locator).not.toBeVisible();
+  }
+
+  public async expectHeader(text: string) {
+    await expect(this.header).toContainText(text);
+  }
+
+  public async expectContent(text: string) {
+    await expect(this.content).toContainText(text);
+  }
+
+  public async expectIcon(hasIcon: boolean) {
+    if (hasIcon) {
+      await expect(this.icon).toBeVisible();
+    } else {
+      await expect(this.icon).not.toBeVisible();
+    }
+  }
+
+  public async expectClosable(closable: boolean) {
+    if (closable) {
+      await expect(this.closeButton).toBeVisible();
+    } else {
+      await expect(this.closeButton).not.toBeVisible();
+    }
+  }
+
+  public async close() {
+    await this.closeButton.click();
+  }
+}
+
+export class NgnSnackbarHostHarness {
+  public readonly classes = themeClasses(snackbarControlTemplate);
+  public readonly locator: Locator;
+
+  constructor(page: Page) {
+    this.locator = page.locator('ngn-snackbar-host');
+  }
+
+  public getSnackbar(index: number = 0): NgnSnackbarHarness {
+    return new NgnSnackbarHarness(this.locator.locator('ngn-snackbar').nth(index));
+  }
+
+  public getAllSnackbars(): Locator {
+    return this.locator.locator('ngn-snackbar');
+  }
+
+  public async expectSnackbarCount(count: number) {
+    await expect(this.getAllSnackbars()).toHaveCount(count);
+  }
+
+  public async expectVisible() {
+    await expect(this.locator).toBeVisible();
+  }
+}