docs: update VSR docs with latest interface and commands

guidepup · Mar 10, 2024 · 11ae5f7 · 11ae5f7
1 parent 517ed43
commit 11ae5f7
Show file tree

Hide file tree

Showing 2 changed files with 345 additions and 0 deletions.
diff --git a/docs/api/class-start-options.md b/docs/api/class-start-options.md
@@ -35,9 +35,25 @@ test("example test", async () => {
 });
 ```
 
+If using in a headed browser environment such as [Storybook](https://storybook.js.org/), you can also opt-in to having the virtual cursor displayed visually:
+
+```ts
+import { virtual } from "@guidepup/virtual-screen-reader";
+
+test("example test", async () => {
+  // Start Virtual on the entire page with the virtual cursor displayed visually.
+  await virtual.start({ container: document.body, displayCursor: true });
+
+  // Stop the Virtual Screen Reader.
+  await virtual.stop();
+});
+```
+
 **Contents:**
 
 - [startOptions.container](./class-start-options#start-options-container)
+- [startOptions.window](./class-start-options#start-options-window)
+- [startOptions.displayCursor](./class-start-options#start-options-display-cursor)
 
 ## startOptions.container {#start-options-container}
 
@@ -47,4 +63,24 @@ To use the entire page pass `document.body`.
 
 **Type:** [HTMLElement]
 
+## startOptions.window {#start-options-window}
+
+**Optional:** The window instance.
+
+Only required if the `window` instance is not already globally available. For example, when you are in a Node environment and using a custom DOM implementation that is not attached to the global scope.
+
+Defaults to using the global `window` instance.
+
+**Type:** [Window]
+
+## startOptions.displayCursor {#start-options-display-cursor}
+
+**Optional:** Display the Virtual Screen Reader cursor visually on the target element.
+
+> Note: There is a performance overhead to visually rendering the cursor.
+
+**Type:** [boolean]
+
+[boolean]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean "boolean"
 [htmlelement]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement "HTMLElement"
+[window]: https://developer.mozilla.org/en-US/docs/Web/API/Window "Window"
diff --git a/docs/api/class-virtual-commands.md b/docs/api/class-virtual-commands.md
@@ -42,6 +42,20 @@ test("example test", async () => {
 - [virtualCommands.moveToPreviousFigure](./class-virtual-commands#virtual-commands-moveToPreviousFigure)
 - [virtualCommands.moveToNextForm](./class-virtual-commands#virtual-commands-moveToNextForm)
 - [virtualCommands.moveToPreviousForm](./class-virtual-commands#virtual-commands-moveToPreviousForm)
+- [virtualCommands.moveToNextHeading](./class-virtual-commands#virtual-commands-moveToNextHeading)
+- [virtualCommands.moveToPreviousHeading](./class-virtual-commands#virtual-commands-moveToPreviousHeading)
+- [virtualCommands.moveToNextHeadingLevel1](./class-virtual-commands#virtual-commands-moveToNextHeadingLevel1)
+- [virtualCommands.moveToPreviousHeadingLevel1](./class-virtual-commands#virtual-commands-moveToPreviousHeadingLevel1)
+- [virtualCommands.moveToNextHeadingLevel2](./class-virtual-commands#virtual-commands-moveToNextHeadingLevel2)
+- [virtualCommands.moveToPreviousHeadingLevel2](./class-virtual-commands#virtual-commands-moveToPreviousHeadingLevel2)
+- [virtualCommands.moveToNextHeadingLevel3](./class-virtual-commands#virtual-commands-moveToNextHeadingLevel3)
+- [virtualCommands.moveToPreviousHeadingLevel3](./class-virtual-commands#virtual-commands-moveToPreviousHeadingLevel3)
+- [virtualCommands.moveToNextHeadingLevel4](./class-virtual-commands#virtual-commands-moveToNextHeadingLevel4)
+- [virtualCommands.moveToPreviousHeadingLevel4](./class-virtual-commands#virtual-commands-moveToPreviousHeadingLevel4)
+- [virtualCommands.moveToNextHeadingLevel5](./class-virtual-commands#virtual-commands-moveToNextHeadingLevel5)
+- [virtualCommands.moveToPreviousHeadingLevel5](./class-virtual-commands#virtual-commands-moveToPreviousHeadingLevel5)
+- [virtualCommands.moveToNextHeadingLevel6](./class-virtual-commands#virtual-commands-moveToNextHeadingLevel6)
+- [virtualCommands.moveToPreviousHeadingLevel6](./class-virtual-commands#virtual-commands-moveToPreviousHeadingLevel6)
 - [virtualCommands.moveToNextMain](./class-virtual-commands#virtual-commands-moveToNextMain)
 - [virtualCommands.moveToPreviousMain](./class-virtual-commands#virtual-commands-moveToPreviousMain)
 - [virtualCommands.moveToNextNavigation](./class-virtual-commands#virtual-commands-moveToNextNavigation)
@@ -384,6 +398,300 @@ test("example test", async () => {
 
 **Type:** [string]
 
+## virtualCommands.moveToNextHeading {#virtual-commands-moveToNextHeading}
+
+Move to the next element with a [`heading`] role.
+
+```ts
+import { virtual } from "@guidepup/virtual-screen-reader";
+
+test("example test", async () => {
+  // Start the Virtual Screen Reader.
+  await virtual.start({ container: document.body });
+
+  // Perform action to move to the next heading element.
+  await virtual.perform(virtual.commands.moveToNextHeading);
+
+  // Stop the Virtual Screen Reader.
+  await virtual.stop();
+});
+```
+
+**Type:** [string]
+
+## virtualCommands.moveToPreviousHeading {#virtual-commands-moveToPreviousHeading}
+
+Move to the previous element with a [`heading`] role.
+
+```ts
+import { virtual } from "@guidepup/virtual-screen-reader";
+
+test("example test", async () => {
+  // Start the Virtual Screen Reader.
+  await virtual.start({ container: document.body });
+
+  // Perform action to move to the previous heading element.
+  await virtual.perform(virtual.commands.moveToPreviousHeading);
+
+  // Stop the Virtual Screen Reader.
+  await virtual.stop();
+});
+```
+
+**Type:** [string]
+
+## virtualCommands.moveToNextHeadingLevel1 {#virtual-commands-moveToNextHeadingLevel1}
+
+Move to the next element with a level 1 [`heading`] role.
+
+```ts
+import { virtual } from "@guidepup/virtual-screen-reader";
+
+test("example test", async () => {
+  // Start the Virtual Screen Reader.
+  await virtual.start({ container: document.body });
+
+  // Perform action to move to the next level 1 heading element.
+  await virtual.perform(virtual.commands.moveToNextHeadingLevel1);
+
+  // Stop the Virtual Screen Reader.
+  await virtual.stop();
+});
+```
+
+**Type:** [string]
+
+## virtualCommands.moveToPreviousHeadingLevel1 {#virtual-commands-moveToPreviousHeadingLevel1}
+
+Move to the previous element with a level 1 [`heading`] role.
+
+```ts
+import { virtual } from "@guidepup/virtual-screen-reader";
+
+test("example test", async () => {
+  // Start the Virtual Screen Reader.
+  await virtual.start({ container: document.body });
+
+  // Perform action to move to the previous level 1 heading element.
+  await virtual.perform(virtual.commands.moveToPreviousHeadingLevel1);
+
+  // Stop the Virtual Screen Reader.
+  await virtual.stop();
+});
+```
+
+**Type:** [string]
+
+## virtualCommands.moveToNextHeadingLevel2 {#virtual-commands-moveToNextHeadingLevel2}
+
+Move to the next element with a level 2 [`heading`] role.
+
+```ts
+import { virtual } from "@guidepup/virtual-screen-reader";
+
+test("example test", async () => {
+  // Start the Virtual Screen Reader.
+  await virtual.start({ container: document.body });
+
+  // Perform action to move to the next level 2 heading element.
+  await virtual.perform(virtual.commands.moveToNextHeadingLevel2);
+
+  // Stop the Virtual Screen Reader.
+  await virtual.stop();
+});
+```
+
+**Type:** [string]
+
+## virtualCommands.moveToPreviousHeadingLevel2 {#virtual-commands-moveToPreviousHeadingLevel2}
+
+Move to the previous element with a level 2 [`heading`] role.
+
+```ts
+import { virtual } from "@guidepup/virtual-screen-reader";
+
+test("example test", async () => {
+  // Start the Virtual Screen Reader.
+  await virtual.start({ container: document.body });
+
+  // Perform action to move to the previous level 2 heading element.
+  await virtual.perform(virtual.commands.moveToPreviousHeadingLevel2);
+
+  // Stop the Virtual Screen Reader.
+  await virtual.stop();
+});
+```
+
+**Type:** [string]
+
+## virtualCommands.moveToNextHeadingLevel3 {#virtual-commands-moveToNextHeadingLevel3}
+
+Move to the next element with a level 3 [`heading`] role.
+
+```ts
+import { virtual } from "@guidepup/virtual-screen-reader";
+
+test("example test", async () => {
+  // Start the Virtual Screen Reader.
+  await virtual.start({ container: document.body });
+
+  // Perform action to move to the next level 3 heading element.
+  await virtual.perform(virtual.commands.moveToNextHeadingLevel3);
+
+  // Stop the Virtual Screen Reader.
+  await virtual.stop();
+});
+```
+
+**Type:** [string]
+
+## virtualCommands.moveToPreviousHeadingLevel3 {#virtual-commands-moveToPreviousHeadingLevel3}
+
+Move to the previous element with a level 3 [`heading`] role.
+
+```ts
+import { virtual } from "@guidepup/virtual-screen-reader";
+
+test("example test", async () => {
+  // Start the Virtual Screen Reader.
+  await virtual.start({ container: document.body });
+
+  // Perform action to move to the previous level 3 heading element.
+  await virtual.perform(virtual.commands.moveToPreviousHeadingLevel3);
+
+  // Stop the Virtual Screen Reader.
+  await virtual.stop();
+});
+```
+
+**Type:** [string]
+
+## virtualCommands.moveToNextHeadingLevel4 {#virtual-commands-moveToNextHeadingLevel4}
+
+Move to the next element with a level 4 [`heading`] role.
+
+```ts
+import { virtual } from "@guidepup/virtual-screen-reader";
+
+test("example test", async () => {
+  // Start the Virtual Screen Reader.
+  await virtual.start({ container: document.body });
+
+  // Perform action to move to the next level 4 heading element.
+  await virtual.perform(virtual.commands.moveToNextHeadingLevel4);
+
+  // Stop the Virtual Screen Reader.
+  await virtual.stop();
+});
+```
+
+**Type:** [string]
+
+## virtualCommands.moveToPreviousHeadingLevel4 {#virtual-commands-moveToPreviousHeadingLevel4}
+
+Move to the previous element with a level 4 [`heading`] role.
+
+```ts
+import { virtual } from "@guidepup/virtual-screen-reader";
+
+test("example test", async () => {
+  // Start the Virtual Screen Reader.
+  await virtual.start({ container: document.body });
+
+  // Perform action to move to the previous level 4 heading element.
+  await virtual.perform(virtual.commands.moveToPreviousHeadingLevel4);
+
+  // Stop the Virtual Screen Reader.
+  await virtual.stop();
+});
+```
+
+**Type:** [string]
+
+## virtualCommands.moveToNextHeadingLevel5 {#virtual-commands-moveToNextHeadingLevel5}
+
+Move to the next element with a level 5 [`heading`] role.
+
+```ts
+import { virtual } from "@guidepup/virtual-screen-reader";
+
+test("example test", async () => {
+  // Start the Virtual Screen Reader.
+  await virtual.start({ container: document.body });
+
+  // Perform action to move to the next level 5 heading element.
+  await virtual.perform(virtual.commands.moveToNextHeadingLevel5);
+
+  // Stop the Virtual Screen Reader.
+  await virtual.stop();
+});
+```
+
+**Type:** [string]
+
+## virtualCommands.moveToPreviousHeadingLevel5 {#virtual-commands-moveToPreviousHeadingLevel5}
+
+Move to the previous element with a level 5 [`heading`] role.
+
+```ts
+import { virtual } from "@guidepup/virtual-screen-reader";
+
+test("example test", async () => {
+  // Start the Virtual Screen Reader.
+  await virtual.start({ container: document.body });
+
+  // Perform action to move to the previous level 5 heading element.
+  await virtual.perform(virtual.commands.moveToPreviousHeadingLevel5);
+
+  // Stop the Virtual Screen Reader.
+  await virtual.stop();
+});
+```
+
+**Type:** [string]
+
+## virtualCommands.moveToNextHeadingLevel6 {#virtual-commands-moveToNextHeadingLevel6}
+
+Move to the next element with a level 6 [`heading`] role.
+
+```ts
+import { virtual } from "@guidepup/virtual-screen-reader";
+
+test("example test", async () => {
+  // Start the Virtual Screen Reader.
+  await virtual.start({ container: document.body });
+
+  // Perform action to move to the next level 6 heading element.
+  await virtual.perform(virtual.commands.moveToNextHeadingLevel6);
+
+  // Stop the Virtual Screen Reader.
+  await virtual.stop();
+});
+```
+
+**Type:** [string]
+
+## virtualCommands.moveToPreviousHeadingLevel6 {#virtual-commands-moveToPreviousHeadingLevel6}
+
+Move to the previous element with a level 6 [`heading`] role.
+
+```ts
+import { virtual } from "@guidepup/virtual-screen-reader";
+
+test("example test", async () => {
+  // Start the Virtual Screen Reader.
+  await virtual.start({ container: document.body });
+
+  // Perform action to move to the previous level 6 heading element.
+  await virtual.perform(virtual.commands.moveToPreviousHeadingLevel6);
+
+  // Stop the Virtual Screen Reader.
+  await virtual.stop();
+});
+```
+
+**Type:** [string]
+
 ## virtualCommands.moveToNextMain {#virtual-commands-moveToNextMain}
 
 Move to the next element with a [`main`] role.
@@ -625,6 +933,7 @@ test("example test", async () => {
 [`contentinfo`]: https://www.w3.org/TR/wai-aria-1.2/#contentinfo "contentinfo"
 [`figure`]: https://www.w3.org/TR/wai-aria-1.2/#figure "figure"
 [`form`]: https://www.w3.org/TR/wai-aria-1.2/#form "form"
+[`heading`]: https://www.w3.org/TR/wai-aria-1.2/#heading "heading"
 [`landmark`]: https://www.w3.org/TR/wai-aria-1.2/#landmark "landmark"
 [`main`]: https://www.w3.org/TR/wai-aria-1.2/#main "main"
 [`navigation`]: https://www.w3.org/TR/wai-aria-1.2/#navigation "navigation"