@interactors/core 0.3.0

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@interactors/core",
+  "version": "0.3.0",
+  "description": "Composable page objects for components",
+  "main": "dist/cjs/index.js",
+  "browser": "dist/esm/index.js",
+  "types": "dist/index.d.ts",
+  "repository": "https://github.com/thefrontside/interactors.git",
+  "homepage": "https://frontside.com/interactors",
+  "author": "Frontside Engineering <engineering@frontside.com>",
+  "license": "MIT",
+  "files": [
+    "dist/**/*",
+    "src/**/*",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "require": "./dist/cjs/index.js",
+      "default": "./dist/esm/index.js"
+    }
+  },
+  "scripts": {
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "lint": "eslint \"{src,test}/**/*.ts\"",
+    "check:types": "tsc --noEmit",
+    "test:unit": "mocha \"test/**/*.test.ts\"",
+    "test:types": "dtslint types --localTs ../../node_modules/typescript/lib --expectOnly",
+    "test": "yarn test:unit && yarn test:types",
+    "docs": "rm -rf docs && yarn typedoc --options typedoc.json",
+    "prepack": "tsc --build ./tsconfig.build.json && yarn prepack:es2015 && yarn prepack:commonjs",
+    "prepack:es2015": "tsc --project ./tsconfig.build.json --outdir dist/esm --module es2015",
+    "prepack:commonjs": "tsc --project ./tsconfig.build.json --outdir dist/cjs --module commonjs"
+  },
+  "dependencies": {
+    "@bigtest/globals": "^0.7.6",
+    "@interactors/globals": "^0.1.0",
+    "@testing-library/dom": "^8.5.0",
+    "@testing-library/user-event": "^13.2.1",
+    "change-case": "^4.1.1",
+    "element-is-visible": "^1.0.0",
+    "lodash.isequal": "^4.5.0",
+    "performance-api": "^1.0.0"
+  },
+  "devDependencies": {
+    "@frontside/tsconfig": "^1.2.0",
+    "@types/express": "^4.17.6",
+    "@types/jsdom": "^16.2.3",
+    "@types/lodash.isequal": "^4.5.5",
+    "@types/mocha": "^7.0.1",
+    "@types/node": "^14.17.5",
+    "dtslint": "^4.0.5",
+    "expect": "^24.9.0",
+    "express": "^4.17.1",
+    "jsdom": "^16.2.2",
+    "mocha": "^6.2.2",
+    "ts-node": "^10.4.0",
+    "typedoc": "^0.22.7",
+    "typescript": "~4.4.4"
+  },
+  "volta": {
+    "node": "14.17.5",
+    "yarn": "1.22.11"
+  }
+}

package/src/constructor.ts

@@ -0,0 +1,298 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import { globals } from '@interactors/globals';
+import { converge } from './converge';
+import { MergeObjects } from './merge-objects';
+import {
+  InteractorOptions,
+  ActionMethods,
+  InteractorConstructor,
+  Interactor,
+  Filters,
+  Actions,
+  FilterDefinition,
+  FilterParams,
+  FilterMethods,
+  InteractorSpecification,
+  BaseInteractor,
+  FilterObject,
+} from './specification';
+import { FilterSet } from './filter-set';
+import { Locator } from './locator';
+import { MatchFilter, applyFilter } from './match';
+import { formatTable } from './format-table';
+import { FilterNotMatchingError } from './errors';
+import { interaction, interactionFilter, check, checkFilter, Interaction, ReadonlyInteraction } from './interaction';
+import { Match } from './match';
+import { NoSuchElementError, NotAbsentError, AmbiguousElementError } from './errors';
+import { isMatcher } from './matcher';
+import { matching } from './matchers/matching';
+
+const defaultLocator: FilterDefinition<string, Element> = (element) => element.textContent || "";
+const defaultSelector = 'div';
+
+export function findElements<E extends Element>(parentElement: Element, interactor: InteractorOptions<any, any, any>): E[] {
+  if(typeof(interactor.specification.selector) === 'function') {
+    return interactor.specification.selector(parentElement);
+  } else if(interactor.specification.selector === ':root') {
+    // this is a bit of a hack, because otherwise there isn't a good way of selecting the root element
+    return [parentElement.ownerDocument.querySelector(':root') as E];
+  } else {
+    return Array.from(parentElement.querySelectorAll(interactor.specification.selector || defaultSelector));
+  }
+}
+
+function findMatches(parentElement: Element, interactor: InteractorOptions<any, any, any>): Match<Element, any>[] {
+  if (!interactor.name) {
+    throw new Error('One of your interactors was created without a name. Please provide a label for your interactor:\n\tHTML.extend(\'my interactor\') || createInteractor(\'my interactor\')');
+  }
+  return findElements(parentElement, interactor).map((e) => new Match(e, interactor.filter, interactor.locator));
+}
+
+function findMatchesMatching(parentElement: Element, interactor: InteractorOptions<any, any, any>): Match<Element, any>[] {
+  return findMatches(parentElement, interactor).filter((m) => m.matches);
+}
+
+function findMatchesNonEmpty(parentElement: Element, interactor: InteractorOptions<any, any, any>): Match<Element, any>[] {
+  let matches = findMatches(parentElement, interactor);
+  let matching = matches.filter((m) => m.matches);
+  if(matching.length > 0) {
+    return matching;
+  } else if(matches.length === 0) {
+    throw new NoSuchElementError(`did not find ${description(interactor)}`);
+  } else {
+    let table = formatTable({
+      headers: interactor.locator ? [interactor.name, ...interactor.filter.asTableHeader()] : interactor.filter.asTableHeader(),
+      rows: matches.slice().sort((a, b) => b.sortWeight - a.sortWeight).map((m) => m.asTableRow()),
+    });
+    throw new NoSuchElementError(`did not find ${description(interactor)}, did you mean one of:\n\n${table}`);
+  }
+}
+
+// Given a parent element, and an interactor, find exactly one matching element
+// and return it. If no elements match, raise an error. If more than one
+// element matches, raise an error.
+export function resolveUnique(parentElement: Element, interactor: InteractorOptions<any, any, any>): Element {
+  let matching = findMatchesNonEmpty(parentElement, interactor);
+
+  if(matching.length === 1) {
+    return matching[0].element;
+  } else {
+    let alternatives = matching.map((m) => '- ' + m.elementDescription());
+    throw new AmbiguousElementError(`${description(interactor)} matches multiple elements:\n\n${alternatives.join('\n')}`);
+  }
+}
+
+// Given a parent element, and an interactor, find all matching elements and
+// return them. If no elements match, raise an error.
+export function resolveNonEmpty(parentElement: Element, interactor: InteractorOptions<any, any, any>): Element[] {
+  return findMatchesNonEmpty(parentElement, interactor).map(m => m.element);
+}
+
+// Given a parent element, and an interactor, check if there are any matching
+// elements, and throw an error if there are. Otherwise return undefined.
+export function resolveEmpty(parentElement: Element, interactor: InteractorOptions<any, any, any>): void {
+  let matching = findMatchesMatching(parentElement, interactor);
+
+  if(matching.length !== 0) {
+    let alternatives = matching.map((m) => '- ' + m.elementDescription());
+    throw new NotAbsentError(`${description(interactor)} exists but should not:\n\n${alternatives.join('\n')}`);
+  }
+}
+
+function ownDescription(options: InteractorOptions<any, any, any>): string {
+  if(options.locator) {
+    return `${options.name} ${options.locator.description} ${options.filter.description}`.trim();
+  } else {
+    return `${options.name} ${options.filter.description}`.trim();
+  }
+}
+
+function description(options: InteractorOptions<any, any, any>): string {
+  let ancestorsAndSelf: InteractorOptions<any, any, any>[] = options.ancestors.concat(options);
+  return ancestorsAndSelf.reverse().map(ownDescription).join(' within ');
+}
+
+/**
+ * Removes any default values for a filter from the lookup if that filter is present in the
+ * assertion. Otherwise, it is not possible to make an assertion on a filter that might conflict
+ * see https://github.com/thefrontside/bigtest/issues/966
+*/
+function getLookupFilterForAssertion<E extends Element, F extends Filters<E>>(filter: FilterSet<E, F>, filters: FilterParams<E, F>): FilterSet<E, F> {
+  let lookupFilter = new FilterSet(filter.specification, Object.assign({}, filter.filters));
+  let specFilters = lookupFilter.specification.filters;
+  for (let key in specFilters) {
+    if (typeof specFilters[key] !== 'function'
+    && 'default' in specFilters[key]
+    && key in filters
+    && !(key in lookupFilter.filters)) {
+      lookupFilter.filters[key] = filters[key];
+    }
+  }
+  return lookupFilter;
+}
+
+export function unsafeSyncResolveParent(options: InteractorOptions<any, any, any>): Element {
+  return options.ancestors.reduce(resolveUnique, globals.document.documentElement);
+}
+
+export function unsafeSyncResolveUnique<E extends Element>(options: InteractorOptions<E, any, any>): E {
+  return resolveUnique(unsafeSyncResolveParent(options), options) as E;
+}
+
+export function instantiateBaseInteractor<E extends Element, F extends Filters<E>, A extends Actions<E>>(
+  options: InteractorOptions<E, F, A>,
+  resolver: (options: InteractorOptions<E, F, A>) => E
+): BaseInteractor<E, FilterParams<E, F>> & ActionMethods<E, A> {
+  let interactor = {
+    options,
+
+    get description(): string {
+      return description(options);
+    },
+
+    perform<T>(fn: (element: E) => T): Interaction<T> {
+      return interaction(`run perform on ${description(options)}`, () => converge(() => fn(resolver(options))))
+    },
+
+    assert(fn: (element: E) => void): ReadonlyInteraction<void> {
+      return check(`${description(options)} asserts`, () => {
+        return converge(() => {
+          fn(resolver(options));
+        });
+      });
+    },
+
+    has(filters: FilterParams<E, F>): ReadonlyInteraction<void> {
+      return interactor.is(filters);
+    },
+
+    is(filters: FilterParams<E, F>): ReadonlyInteraction<void> {
+      let filter = new FilterSet(options.specification, filters);
+      return check(`${description(options)} matches filters: ${filter.description}`, () => {
+        return converge(() => {
+          let element = resolver({...options, filter: getLookupFilterForAssertion(options.filter, filters) });
+          let match = new MatchFilter(element, filter);
+          if (!match.matches) {
+            throw new FilterNotMatchingError(`${description(options)} does not match filters:\n\n${match.formatAsExpectations()}`);
+          }
+        });
+      });
+    },
+
+    apply(parentElement: Element): string {
+      let element = [...options.ancestors, options].reduce(resolveUnique, parentElement);
+      return applyFilter(options.specification.locator || defaultLocator, element);
+    }
+  }
+
+  for (let [actionName, action] of Object.entries(options.specification.actions || {})) {
+    if (!interactor.hasOwnProperty(actionName)) {
+      Object.defineProperty(interactor, actionName, {
+        value: function(...args: unknown[]) {
+          let actionDescription = actionName;
+          if (args.length) {
+            actionDescription += ` with ` + args.map((a) => JSON.stringify(a)).join(', ');
+          }
+          return interaction(
+            `${actionDescription} on ${description(options)}`,
+            () => action(interactor as Interactor<E, FilterParams<E, F>> & ActionMethods<E, A>, ...args)
+          );
+        },
+        configurable: true,
+        writable: true,
+        enumerable: false,
+      });
+    }
+  }
+
+  for (let [filterName, filter] of Object.entries(options.specification.filters || {})) {
+    if (!interactor.hasOwnProperty(filterName)) {
+      Object.defineProperty(interactor, filterName, {
+        value: function() {
+          return interactionFilter(`${filterName} of ${description(options)}`, async () => {
+            return applyFilter(filter, resolver(options));
+          }, (parentElement) => {
+            let element = [...options.ancestors, options].reduce(resolveUnique, parentElement);
+            return applyFilter(filter, element);
+          });
+        },
+        configurable: true,
+        writable: true,
+        enumerable: false,
+      });
+    }
+  }
+
+  return interactor as BaseInteractor<E, FilterParams<E, F>> & ActionMethods<E, A>;
+}
+
+export function instantiateInteractor<E extends Element, F extends Filters<E>, A extends Actions<E>>(
+  options: InteractorOptions<E, F, A>,
+): Interactor<E, FilterParams<E, F>> & ActionMethods<E, A> {
+  let interactor = instantiateBaseInteractor(options, unsafeSyncResolveUnique)
+
+  return Object.assign(interactor, {
+    find<T extends Interactor<any, any>>(child: T): T {
+      return instantiateInteractor({
+        ...child.options,
+        ancestors: [...options.ancestors, options, ...child.options.ancestors]
+      }) as unknown as T;
+    },
+
+    exists(): ReadonlyInteraction<void> & FilterObject<boolean, Element> {
+      return checkFilter(`${description(options)} exists`, () => {
+        return converge(() => {
+          resolveNonEmpty(unsafeSyncResolveParent(options), options);
+        });
+      }, (element) => {
+        return findMatchesMatching(element, options).length > 0;
+      });
+    },
+
+    absent(): ReadonlyInteraction<void> & FilterObject<boolean, Element> {
+      return checkFilter(`${description(options)} does not exist`, () => {
+        return converge(() => {
+          resolveEmpty(unsafeSyncResolveParent(options), options);
+        });
+      }, (element) => {
+        return findMatchesMatching(element, options).length === 0;
+      });
+    }
+  });
+}
+
+export function createConstructor<E extends Element, FP extends FilterParams<any, any>, FM extends FilterMethods<any, any>, AM extends ActionMethods<any, any>>(
+  name: string,
+  specification: InteractorSpecification<E, any, any>,
+): InteractorConstructor<E, FP, FM, AM> {
+  function initInteractor(...args: any[]) {
+    let locator, filter;
+    let locatorValue = args[0] instanceof RegExp ? matching(args[0]) : args[0]
+    if (typeof(locatorValue) === 'string' || isMatcher(locatorValue)) {
+      locator = new Locator(specification.locator || defaultLocator, locatorValue);
+      filter = new FilterSet(specification, args[1] || {});
+    } else {
+      filter = new FilterSet(specification, args[0] || {});
+    }
+    return instantiateInteractor({ name, specification, filter, locator, ancestors: [] });
+  }
+
+  return Object.assign(initInteractor, {
+    selector: (value: string): InteractorConstructor<E, FP, FM, AM> => {
+      return createConstructor(name, { ...specification, selector: value });
+    },
+    locator: (value: FilterDefinition<string, E>): InteractorConstructor<E, FP, FM, AM> => {
+      return createConstructor(name, { ...specification, locator: value });
+    },
+    filters: <FR extends Filters<E>>(filters: FR): InteractorConstructor<E, MergeObjects<FP, FilterParams<E, FR>>, MergeObjects<FM, FilterMethods<E, FR>>, AM> => {
+      return createConstructor(name, { ...specification, filters: { ...specification.filters, ...filters } });
+    },
+    actions: <AR extends Actions<E>>(actions: AR): InteractorConstructor<E, FP, FM, MergeObjects<AM, ActionMethods<E, AR>>> => {
+      return createConstructor(name, { ...specification, actions: Object.assign({}, specification.actions, actions) });
+    },
+    extend: <ER extends Element = E>(newName: string): InteractorConstructor<ER, FP, FM, AM> => {
+      return createConstructor(newName, specification) as unknown as InteractorConstructor<ER, FP, FM, AM>;
+    },
+  }) as unknown as InteractorConstructor<E, FP, FM, AM>;
+}

package/src/converge.ts

@@ -0,0 +1,22 @@
+import { performance } from 'performance-api';
+import { globals } from '@interactors/globals'
+
+function wait(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function converge<T>(fn: () => T): Promise<T> {
+  let startTime = performance.now();
+  while(true) {
+    try {
+      return fn();
+    } catch(e) {
+      let diff = performance.now() - startTime;
+      if(diff > globals.interactorTimeout) {
+        throw e;
+      } else {
+        await wait(1);
+      }
+    }
+  }
+}

package/src/create-interactor.ts

@@ -0,0 +1,21 @@
+import { EmptyObject, InteractorConstructor } from './specification';
+import { createConstructor } from './constructor';
+
+/**
+ * Create a custom interactor with the given name.
+ *
+ * ### Creating a simple interactor
+ *
+ * ``` typescript
+ * let Paragraph = createInteractor('paragraph').selector('p');
+ * ```
+ *
+ * Note the double function call!
+ *
+ * @param interactorName The human readable name of the interactor, used mainly for debugging purposes and error messages
+ * @typeParam E The type of DOM Element that this interactor operates on. By specifying the element type, actions and filters defined for the interactor can be type checked against the actual element type.
+ * @returns You will need to call the returned builder to create an interactor.
+ */
+export function createInteractor<E extends Element>(name: string): InteractorConstructor<E, EmptyObject, EmptyObject, EmptyObject> {
+  return createConstructor(name, {});
+}

package/src/dispatch.ts

@@ -0,0 +1,24 @@
+export function dispatchChange(element: HTMLElement): boolean {
+  let Event = element.ownerDocument.defaultView?.Event || window.Event;
+  return element.dispatchEvent(new Event('change', { bubbles: true, cancelable: false }));
+}
+
+export function dispatchInput(element: HTMLElement, options: InputEventInit = {}): boolean {
+  let InputEvent = element.ownerDocument.defaultView?.InputEvent || window.InputEvent;
+  return element.dispatchEvent(new InputEvent('input', Object.assign({ bubbles: true, cancelable: false }, options)));
+}
+
+export function dispatchKeyDown(element: HTMLElement, options: KeyboardEventInit = {}): boolean {
+  let KeyboardEvent = element.ownerDocument.defaultView?.KeyboardEvent || window.KeyboardEvent;
+  return element.dispatchEvent(new KeyboardEvent('keydown', Object.assign({ bubbles: true, cancelable: true }, options)));
+}
+
+export function dispatchKeyUp(element: HTMLElement, options: KeyboardEventInit = {}): boolean {
+  let KeyboardEvent = element.ownerDocument.defaultView?.KeyboardEvent || window.KeyboardEvent;
+  return element.dispatchEvent(new KeyboardEvent('keyup', Object.assign({ bubbles: true, cancelable: true }, options)));
+}
+
+export function dispatchClick(element: HTMLElement, options: MouseEventInit = {}): boolean {
+  let MouseEvent = element.ownerDocument.defaultView?.MouseEvent || window.MouseEvent;
+  return element.dispatchEvent(new MouseEvent('click', Object.assign({ bubbles: true, cancelable: true }, options)));
+}

package/src/element/click.ts

@@ -0,0 +1,5 @@
+import userEvent from '@testing-library/user-event'
+
+export function click(element: Element, init?: MouseEventInit) {
+  return userEvent.click(element, init);
+}

package/src/element/fill-in.ts

@@ -0,0 +1,76 @@
+import { dispatchChange, dispatchInput, dispatchKeyDown, dispatchKeyUp } from '../dispatch';
+
+type TextFieldElement = HTMLInputElement | HTMLTextAreaElement;
+
+// do a best effort at determining the key code
+function guessCode(letter: string): string | undefined {
+  if(letter.match(/^[a-zA-Z]$/)) {
+    return `Key${letter.toUpperCase()}`;
+  } else if(letter.match(/^[0-9]$/)) {
+    return `Digit${letter}`;
+  }
+}
+
+function clearText(element: TextFieldElement) {
+  if(element.value.length) {
+    setValue(element, "");
+    dispatchInput(element, { inputType: 'deleteContentBackward', data: null });
+  }
+}
+
+function enterText(element: TextFieldElement, value: string) {
+  for(let letter of value) {
+    if(dispatchKeyDown(element, { key: letter, code: guessCode(letter) })) {
+      // don't change the value if the keydown event was stopped
+      setValue(element, element.value + letter);
+      // input is not dispatched if the keydown event was stopped
+      dispatchInput(element, { inputType: 'insertText', data: letter });
+    }
+    // keyup is always dispatched
+    dispatchKeyUp(element, { key: letter, code: guessCode(letter) });
+  }
+}
+
+
+/**
+ * Use the prototype setter of the element in order to set the value, that way any behavior that monkey patches
+ * the element itself is circumvented. This has the effect of the value just "magically" appearing on the input
+ * element just like it does when the browser sets the value because of the default action of an event.
+ * We have to do this because React actually does do this monkey-patching as an optimization. Basically, they
+ * short-circuit syncing the react state whenever someone sets input.value and then ignore the next `change` event.
+ *
+ * See https://github.com/cypress-io/cypress/issues/536
+ */
+function setValue(element: TextFieldElement, value: string): void {
+  let property = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(element), 'value');
+  if (property && property.set) {
+    property.set.call(element, value);
+  } else {
+    // if the value property on the element protoype is not present
+    // then there are worse problems. But this is very typesafe!
+    element.value = value;
+  }
+}
+
+/**
+ * Fill in text into an element by emulating how a user would do it, first
+ * focusing the element, then filling in the text letter by letter, generating
+ * the appropriate keyboard events.
+ *
+ * @param element The element to fill in text in
+ * @param value The text value to fill in
+ */
+export function fillIn(element: TextFieldElement, value: string): void {
+  let originalValue = element.value;
+
+  element.focus();
+
+  clearText(element);
+  enterText(element, value);
+
+  if(originalValue !== value) {
+    dispatchChange(element);
+  }
+
+  element.blur();
+}

package/src/errors.ts

@@ -0,0 +1,15 @@
+export class NoSuchElementError extends Error {
+  name = "NoSuchElementError";
+}
+
+export class AmbiguousElementError extends Error {
+  name = "AmbiguousElementError";
+}
+
+export class NotAbsentError extends Error {
+  name = "NotAbsentError";
+}
+
+export class FilterNotMatchingError extends Error {
+  name = "FilterNotMatchingError";
+}

package/src/escape-html.ts

@@ -0,0 +1,8 @@
+export function escapeHtml(text: string): string {
+  return text
+     .replace(/&/g, "&")
+     .replace(/</g, "&lt;")
+     .replace(/>/g, "&gt;")
+     .replace(/"/g, "&quot;")
+     .replace(/'/g, "&#039;");
+}

package/src/filter-set.ts

@@ -0,0 +1,45 @@
+import { Filters, FilterFn, FilterObject, FilterParams, InteractorSpecification } from './specification';
+import { noCase } from 'change-case';
+import { matcherDescription } from './matcher';
+
+export class FilterSet<E extends Element, F extends Filters<E>> {
+  constructor(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    public specification: InteractorSpecification<E, F, any>,
+    public filters: FilterParams<E, F>,
+  ) {};
+
+  get description(): string {
+    let entries = Object.entries(this.filters);
+    if(entries.length === 0) {
+      return '';
+    } else {
+      return entries.map(([key, value]) => {
+        if(typeof(value) === 'boolean') {
+          if(value) {
+            return `which is ${noCase(key)}`;
+          } else {
+            return `which is not ${noCase(key)}`;
+          }
+        } else {
+          return `with ${noCase(key)} ${matcherDescription(value)}`
+        }
+      }).join(' and ');
+    }
+  }
+
+  get all(): FilterParams<E, F> {
+    let filter: Record<string, unknown> = Object.assign({}, this.filters);
+    for(let key in this.specification.filters) {
+      let definition = this.specification.filters[key] as FilterFn<unknown, E> | FilterObject<unknown, E>;
+      if(!(key in this.filters) && typeof(definition) !== 'function' && 'default' in definition) {
+        filter[key] = definition.default;
+      }
+    }
+    return filter as FilterParams<E, F>;
+  }
+
+  asTableHeader(): string[] {
+    return Object.entries(this.all).map(([key, value]) => `${key}: ${matcherDescription(value)}`);
+  }
+}

package/src/focused.ts

@@ -0,0 +1,43 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import { Interactor } from './specification';
+
+/**
+ * Helper function for focused filters, returns whether the given element is focused.
+ */
+export function focused(element: Element): boolean {
+  console.warn("usage of the focused() helper is deprecated, and will be removed from the public API. Instead, switch your interactor to extend the `HTML` interactor to inherit the `focused` filter");
+  return element.ownerDocument.activeElement === element;
+}
+
+/**
+ * Helper function for focus action, performs `element.focus()` on the selected element.
+ *
+ * Can be used with object property value shorthand in your interactor actions.
+ *
+ * ```js
+ * actions: {
+ *   focus,
+ * }
+ * ```
+ */
+export async function focus<E extends HTMLElement>(interactor: Interactor<E, any>): Promise<void> {
+  console.warn("usage of the focus() helper is deprecated, and will be removed from the public API. Instead, switch your interactor to extend the `HTML` interactor to inherit the `focus()` action");
+  await interactor.perform((element) => element.focus())
+};
+
+/**
+ * Helper function for blur action, performs `element.blur()` on the selected element.
+ *
+ * Can be used with object property value shorthand in your interactor actions.
+ *
+ * ```js
+ * actions: {
+ *   focus,
+ * }
+ * ```
+ */
+export async function blur<E extends HTMLElement>(interactor: Interactor<E, any>): Promise<void> {
+  console.warn("usage of the blur() helper is deprecated, and will be removed from the public API. Instead, switch your interactor to extend the `HTML` interactor to inherit the `blur()` action");
+  await interactor.perform((element) => element.blur())
+};

package/src/format-table.ts

@@ -0,0 +1,34 @@
+export interface TableOptions {
+  headers: string[];
+  rows: string[][];
+}
+
+const MAX_COLUMN_WIDTH = 40
+
+function formatValue(value: string, width: number) {
+  if(value.length > width) {
+    return value.slice(0, width - 1) + '…';
+  } else {
+    return value.padEnd(width);
+  }
+}
+
+export function formatTable(options: TableOptions): string {
+  let columnWidths = options.headers.map((h, index) => {
+    return Math.min(MAX_COLUMN_WIDTH, Math.max(h.length, ...options.rows.map((r) => r[index].length)));
+  });
+
+  let formatRow = (cells: string[]) => {
+    return '┃ ' + cells.map((c, index) => formatValue(c, columnWidths[index])).join(' ┃ ') + ' ┃';
+  }
+
+  let spacerRow = () => {
+    return '┣━' + columnWidths.map((w) => "━".repeat(w)).join('━╋━') + '━┫';
+  }
+
+  return [
+    formatRow(options.headers),
+    spacerRow(),
+    ...options.rows.map((row) => formatRow(row))
+  ].join('\n');
+}