feat: add "move to heading" commands (#51)

Author: jcarstairs-scottlogic

src/Virtual.ts

@@ -8,7 +8,7 @@ import {
   ScreenReader,
   WindowsModifiers,
 } from "@guidepup/guidepup";
-import { commands, VirtualCommandKey, VirtualCommands } from "./commands";
+import { commands, VirtualCommands } from "./commands";
 import {
   ERR_VIRTUAL_MISSING_CONTAINER,
   ERR_VIRTUAL_NOT_STARTED,
@@ -369,11 +369,11 @@ export class Virtual implements ScreenReader {
    * ```
    */
   get commands() {
-    return Object.fromEntries<VirtualCommandKey>(
-      (Object.keys(commands) as VirtualCommandKey[]).map(
-        (command: VirtualCommandKey) => [command, command]
+    return Object.fromEntries<keyof VirtualCommands>(
+      (Object.keys(commands) as (keyof VirtualCommands)[]).map(
+        (command: keyof VirtualCommands) => [command, command]
       )
-    ) as { [K in VirtualCommandKey]: K };
+    ) as { [K in keyof VirtualCommands]: K };
   }
 
   /**
@@ -800,7 +800,7 @@ export class Virtual implements ScreenReader {
    * @param {object} [options] Command options.
    */
   async perform<
-    T extends VirtualCommandKey,
+    T extends keyof VirtualCommands,
     K extends Omit<Parameters<VirtualCommands[T]>[0], keyof VirtualCommandArgs>
   >(command: T, options?: { [L in keyof K]: K[L] } & CommandOptions) {
     this.#checkContainer();

src/commands/getIndexByRoleAndAttributes.ts

@@ -0,0 +1,37 @@
+import {
+  AccessibilityNode,
+  END_OF_ROLE_PREFIX,
+} from "../createAccessibilityTree";
+import { matchesAccessibleAttributes, matchesRoles } from "./nodeMatchers";
+import type { AriaAttributes } from "./types";
+
+export interface GetIndexFilters {
+  /** Matches a node only if the node has any of these roles */
+  roles?: Readonly<string[]>;
+
+  /** Matches a node only if the node has **all** of these aria attributes */
+  ariaAttributes?: Readonly<AriaAttributes>;
+}
+
+export function getIndexByRoleAndAttributes({
+  filters,
+  reorderedTree,
+  tree,
+}: {
+  filters: GetIndexFilters;
+  reorderedTree: AccessibilityNode[];
+  tree: AccessibilityNode[];
+}) {
+  const accessibilityNode = reorderedTree.find(
+    (node) =>
+      !node.spokenRole.startsWith(END_OF_ROLE_PREFIX) &&
+      matchesRoles(node, filters.roles) &&
+      matchesAccessibleAttributes(node, filters.ariaAttributes)
+  );
+
+  if (!accessibilityNode) {
+    return null;
+  }
+
+  return tree.findIndex((node) => node === accessibilityNode);
+}

src/commands/getNextIndexByRole.ts

@@ -0,0 +1,22 @@
+import {
+  getIndexByRoleAndAttributes,
+  type GetIndexFilters,
+} from "./getIndexByRoleAndAttributes";
+import type { VirtualCommandArgs } from "./types";
+
+export type GetNextIndexArgs = Omit<VirtualCommandArgs, "container">;
+
+export function getNextIndexByRoleAndAttributes(
+  filters: Readonly<GetIndexFilters>
+) {
+  return function getNextIndexByRoleAndAttributesInner({
+    currentIndex,
+    tree,
+  }: GetNextIndexArgs) {
+    const reorderedTree = tree
+      .slice(currentIndex + 1)
+      .concat(tree.slice(0, currentIndex + 1));
+
+    return getIndexByRoleAndAttributes({ filters, reorderedTree, tree });
+  };
+}

src/commands/getNextIndexByRoleAndAttributes.ts

@@ -0,0 +1,23 @@
+import {
+  getIndexByRoleAndAttributes,
+  type GetIndexFilters,
+} from "./getIndexByRoleAndAttributes";
+import type { GetNextIndexArgs } from "./getNextIndexByRoleAndAttributes";
+
+type GetPreviousIndexArgs = GetNextIndexArgs;
+
+export function getPreviousIndexByRoleAndAttributes(
+  filters: Readonly<GetIndexFilters>
+) {
+  return function getPreviousIndexInner({
+    currentIndex,
+    tree,
+  }: GetPreviousIndexArgs) {
+    const reorderedTree = tree
+      .slice(0, currentIndex)
+      .reverse()
+      .concat(tree.slice(currentIndex).reverse());
+
+    return getIndexByRoleAndAttributes({ filters, reorderedTree, tree });
+  };
+}