docs: Vue remaining character count example (#46)

* fix: exclude live region spoken phrases when performing "no change" check
* docs: add example for text area with remaining character count live region

Author: jlp-craigmorten

examples/vue/README.md

@@ -2,10 +2,20 @@
 
 A basic example combining Vue, Vitest, Vue Testing Library, and Virtual Screen Reader.
 
+There are two components with tests:
+
+1. A button that increments a polite live region counter
+2. A text area with a remaining character count live region with debounce logic
+
 Run this example with:
 
 ```bash
 cd examples/vue
 yarn install --frozen-lockfile
 yarn test
 ```
+
+> [!IMPORTANT]
+> This example serves to demonstrate how you can use the Virtual screen reader. The components themselves may not be using best accessibility practices.
+>
+> Always evaluate your own components for accessibility and test with real users.

examples/vue/src/IncrementCounter.vue

@@ -14,6 +14,6 @@ export default {
 
 <template>
   <h1>Increment Counter</h1>
-  <p aria-live="polite">Times clicked: {{ count }}</p>
+  <span aria-live="polite">Times clicked: {{ count }}</span>
   <button @click="increment">increment</button>
 </template>

examples/vue/src/TextAreaCounter.vue

@@ -0,0 +1,79 @@
+<template>
+  <h1>Text Area Counter</h1>
+  <textarea @input="handleInput" :maxCount="maxCount"></textarea>
+  <span data-testid="remaining-count">{{ remainingCharacters }} characters left</span>
+  <span class="visually-hidden" aria-live="polite">{{ remainingCharactersForAnnouncement }} characters left</span>
+</template>
+
+<script lang="ts">
+import { defineComponent } from 'vue'
+
+// Announce character count at most every 1 second, EXCEPT
+const DEBOUNCE_TIMEOUT = 1000
+// When have fewer than 10 characters remaining, in which case announce every
+// character.
+const DEBOUNCE_CHAR_LIMIT = 10
+
+export default defineComponent({
+  name: 'TextAreaCounter',
+  props: {
+    maxCount: {
+      type: Number,
+      default: 50
+    },
+    modelValue: {
+      type: String,
+      default: '',
+      required: false
+    }
+  },
+  data() {
+    const remainingCharacters = this.maxCount - this.modelValue.length
+
+    return {
+      debounceTimerId: 0,
+      remainingCharacters,
+      remainingCharactersForAnnouncement: remainingCharacters
+    }
+  },
+  methods: {
+    handleInput(event: Event): void {
+      const value = (event.target as HTMLTextAreaElement).value
+      this.$emit('update:modelValue', value)
+
+      const remainingCharacters = this.maxCount - value.length
+      this.remainingCharacters = remainingCharacters
+      this.handleRemainingCharactersAnnouncement(remainingCharacters)
+    },
+    handleRemainingCharactersAnnouncement(remainingCharacters: number) {
+      if (remainingCharacters <= DEBOUNCE_CHAR_LIMIT) {
+        clearTimeout(this.debounceTimerId)
+
+        this.remainingCharactersForAnnouncement = remainingCharacters
+
+        return
+      }
+
+      clearTimeout(this.debounceTimerId)
+
+      this.debounceTimerId = setTimeout(() => {
+        this.remainingCharactersForAnnouncement = remainingCharacters
+      }, DEBOUNCE_TIMEOUT)
+    }
+  }
+})
+</script>
+
+<style>
+.visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+</style>

examples/vue/src/__tests__/IncrementCounter.spec.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it } from 'vitest'
 import { render, screen, waitFor } from '@testing-library/vue'
 import IncrementCounter from '../IncrementCounter.vue'
 
@@ -12,11 +12,15 @@ import IncrementCounter from '../IncrementCounter.vue'
 import { virtual } from '../../../../src'
 
 describe('Increment Counter', () => {
+  afterEach(async () => {
+    await virtual.stop()
+  })
+
   it('increments value on click', async () => {
     const { container } = render(IncrementCounter)
 
     // Start the virtual screen reader for just the Component under test
-    virtual.start({ container })
+    await virtual.start({ container })
 
     // Move to the increment button
     await virtual.next()

examples/vue/src/__tests__/TextAreaCounter.spec.ts

@@ -0,0 +1,87 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { render, screen, waitFor } from '@testing-library/vue'
+import TextareaCounter from '../TextAreaCounter.vue'
+
+/**
+ * Replace with:
+ *
+ * import { virtual } from '@guidepup/virtual-screen-reader'
+ *
+ * in your own code.
+ */
+import { virtual } from '../../../../src'
+
+describe('Text Area Counter', () => {
+  afterEach(async () => {
+    await virtual.stop()
+  })
+
+  it('announces the remaining character count after 1 second if there are more than 10 allowed characters remaining', async () => {
+    const { container } = render(TextareaCounter)
+
+    await virtual.start({ container })
+    await virtual.next()
+
+    // Type 9 characters
+    await virtual.type('123456789')
+    await waitFor(() => screen.getByDisplayValue('123456789'))
+    await waitFor(() =>
+      screen.getByText('41 characters left', { selector: '[data-testid="remaining-count"]' })
+    )
+
+    // Has not yet announced the character count
+    expect(await virtual.spokenPhraseLog()).toMatchInlineSnapshot(`
+      [
+        "heading, Text Area Counter, level 1",
+        "textbox",
+      ]
+    `)
+
+    // Wait 1 second
+    await new Promise((resolve) => setTimeout(resolve, 1000))
+
+    // Ensure that the screen reader experience is as expected
+    expect(await virtual.spokenPhraseLog()).toMatchInlineSnapshot(`
+      [
+        "heading, Text Area Counter, level 1",
+        "textbox",
+        "polite: 41 characters left",
+      ]
+    `)
+  })
+
+  it('announces the remaining character count for every character when in the last 10 remaining characters', async () => {
+    const { container } = render(TextareaCounter)
+
+    await virtual.start({ container })
+    await virtual.next()
+
+    // Type 50 characters
+    await virtual.type('12345678901234567890123456789012345678901234567890')
+    await waitFor(() =>
+      screen.getByDisplayValue('12345678901234567890123456789012345678901234567890')
+    )
+    await waitFor(() =>
+      screen.getByText('0 characters left', { selector: '[data-testid="remaining-count"]' })
+    )
+
+    // Ensure that the screen reader experience is as expected
+    expect(await virtual.spokenPhraseLog()).toMatchInlineSnapshot(`
+      [
+        "heading, Text Area Counter, level 1",
+        "textbox",
+        "polite: 10 characters left",
+        "polite: 9 characters left",
+        "polite: 8 characters left",
+        "polite: 7 characters left",
+        "polite: 6 characters left",
+        "polite: 5 characters left",
+        "polite: 4 characters left",
+        "polite: 3 characters left",
+        "polite: 2 characters left",
+        "polite: 1 characters left",
+        "polite: 0 characters left",
+      ]
+    `)
+  })
+})

src/Virtual.ts

@@ -13,9 +13,9 @@ import {
   ERR_VIRTUAL_MISSING_CONTAINER,
   ERR_VIRTUAL_NOT_STARTED,
 } from "./errors";
+import { getLiveSpokenPhrase, Live } from "./getLiveSpokenPhrase";
 import { getElementFromNode } from "./getElementFromNode";
 import { getItemText } from "./getItemText";
-import { getLiveSpokenPhrase } from "./getLiveSpokenPhrase";
 import { getSpokenPhrase } from "./getSpokenPhrase";
 import { observeDOM } from "./observeDOM";
 import { tick } from "./tick";
@@ -219,6 +219,14 @@ export class Virtual implements ScreenReader {
       });
   }
 
+  #spokenPhraseLogWithoutLiveRegions() {
+    return this.#spokenPhraseLog.filter(
+      (spokenPhrase) =>
+        !spokenPhrase.startsWith(Live.ASSERTIVE) &&
+        !spokenPhrase.startsWith(Live.POLITE)
+    );
+  }
+
   #updateState(accessibilityNode: AccessibilityNode, ignoreIfNoChange = false) {
     const spokenPhrase = getSpokenPhrase(accessibilityNode);
     const itemText = getItemText(accessibilityNode);
@@ -227,7 +235,7 @@ export class Virtual implements ScreenReader {
 
     if (
       ignoreIfNoChange &&
-      spokenPhrase === this.#spokenPhraseLog.at(-1) &&
+      spokenPhrase === this.#spokenPhraseLogWithoutLiveRegions().at(-1) &&
       itemText === this.#itemTextLog.at(-1)
     ) {
       return;

src/getLiveSpokenPhrase.ts

@@ -36,7 +36,7 @@ import { sanitizeString } from "./sanitizeString";
  * - https://www.w3.org/TR/wai-aria-1.2/#aria-live
  */
 
-enum Live {
+export enum Live {
   ASSERTIVE = "assertive",
   OFF = "off",
   POLITE = "polite",