feat(a11y): aria announcer (#443)

app.vue

@@ -12,5 +12,6 @@ const key = computed(() => `${currentUser.value?.server ?? currentServer.value}:
   <NuxtLayout :key="key">
     <NuxtPage v-if="isMastoInitialised" />
   </NuxtLayout>
+  <AriaAnnouncer />
   <PWAPrompt />
 </template>

components/aria/AriaAnnouncer.vue

@@ -0,0 +1,56 @@
+<script setup lang="ts">
+import type { AriaAnnounceType, AriaLive } from '~/composables/aria/types'
+import { useAriaAnnouncer } from '~/composables/aria'
+import type { LocaleObject } from '#i18n'
+
+const router = useRouter()
+const { t, locale, locales } = useI18n()
+const { ariaAnnouncer, announce } = useAriaAnnouncer()
+
+const localeMap = (locales.value as LocaleObject[]).reduce((acc, l) => {
+  acc[l.code!] = l.name!
+  return acc
+}, {} as Record<string, string>)
+
+let ariaLive = $ref<AriaLive>('polite')
+let ariaMessage = $ref<string>('')
+
+const onMessage = (event: AriaAnnounceType, message?: string) => {
+  if (event === 'announce')
+    ariaMessage = message!
+  else if (event === 'mute')
+    ariaLive = 'off'
+  else
+    ariaLive = 'polite'
+}
+
+watch(locale, (l, ol) => {
+  if (ol) {
+    announce(t('a11y.locale_changing', [localeMap[ol] ?? ol]))
+    setTimeout(() => {
+      announce(t('a11y.locale_changed', [localeMap[l] ?? l]))
+    }, 1000)
+  }
+}, { immediate: true })
+
+onMounted(() => {
+  ariaAnnouncer.on(onMessage)
+  router.beforeEach(() => {
+    announce(t('a11y.loading_page'))
+  })
+  router.afterEach((to, from) => {
+    from && setTimeout(() => {
+      requestAnimationFrame(() => {
+        const title = document.title.trim().split('|')
+        announce(t('a11y.route_loaded', [title[0]]))
+      })
+    }, 512)
+  })
+})
+</script>
+
+<template>
+  <p sr-only role="status" :aria-live="ariaLive">
+    {{ ariaMessage }}
+  </p>
+</template>

components/aria/AriaLog.vue

@@ -0,0 +1,40 @@
+<script setup lang="ts">
+import type { AriaLive } from '~/composables/aria/types'
+import { useAriaLog } from '~/composables/aria'
+
+// tsc complaining when using $defineProps
+withDefaults(defineProps<{
+  title: string
+  ariaLive?: AriaLive
+  messageKey?: (message: any) => any
+  heading?: 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
+}>(), {
+  heading: 'h2',
+  messageKey: (message: any) => message,
+  ariaLive: 'polite',
+})
+
+const { announceLogs, appendLogs, clearLogs, logs } = useAriaLog()
+
+defineExpose({
+  announceLogs,
+  appendLogs,
+  clearLogs,
+})
+</script>
+
+<template>
+  <slot />
+  <div sr-only role="log" :aria-live="ariaLive">
+    <component :is="heading">
+      {{ title }}
+    </component>
+    <ul>
+      <li v-for="log in logs" :key="messageKey(log)">
+        <slot name="log" :log="log">
+          {{ log }}
+        </slot>
+      </li>
+    </ul>
+  </div>
+</template>

components/aria/AriaStatus.vue

@@ -0,0 +1,27 @@
+<script setup lang="ts">
+import type { AriaLive } from '~/composables/aria/types'
+import { useAriaStatus } from '~/composables/aria'
+
+// tsc complaining when using $defineProps
+withDefaults(defineProps<{
+  ariaLive?: AriaLive
+}>(), {
+  ariaLive: 'polite',
+})
+
+const { announceStatus, clearStatus, status } = useAriaStatus()
+
+defineExpose({
+  announceStatus,
+  clearStatus,
+})
+</script>
+
+<template>
+  <slot />
+  <p sr-only role="status" :aria-live="ariaLive">
+    <slot name="status" :status="status">
+      {{ status }}
+    </slot>
+  </p>
+</template>

composables/aria/index.ts

@@ -0,0 +1,60 @@
+import type { AriaAnnounceType } from '~/composables/aria/types'
+
+const ariaAnnouncer = useEventBus<AriaAnnounceType, string | undefined>(Symbol('aria-announcer'))
+
+export const useAriaAnnouncer = () => {
+  const announce = (message: string) => {
+    ariaAnnouncer.emit('announce', message)
+  }
+
+  const mute = () => {
+    ariaAnnouncer.emit('mute')
+  }
+
+  const unmute = () => {
+    ariaAnnouncer.emit('unmute')
+  }
+
+  return { announce, ariaAnnouncer, mute, unmute }
+}
+
+export const useAriaLog = () => {
+  let logs = $ref<any[]>([])
+
+  const announceLogs = (messages: any[]) => {
+    logs = messages
+  }
+
+  const appendLogs = (messages: any[]) => {
+    logs = logs.concat(messages)
+  }
+
+  const clearLogs = () => {
+    logs = []
+  }
+
+  return {
+    announceLogs,
+    appendLogs,
+    clearLogs,
+    logs,
+  }
+}
+
+export const useAriaStatus = () => {
+  let status = $ref<any>('')
+
+  const announceStatus = (message: any) => {
+    status = message
+  }
+
+  const clearStatus = () => {
+    status = ''
+  }
+
+  return {
+    announceStatus,
+    clearStatus,
+    status,
+  }
+}

composables/aria/types.ts

@@ -0,0 +1,2 @@
+export type AriaLive = 'off' | 'polite' | 'assertive'
+export type AriaAnnounceType = 'announce' | 'mute' | 'unmute'

error.vue

@@ -55,5 +55,6 @@ const reload = async () => {
       </slot>
     </MainContent>
   </NuxtLayout>
+  <AriaAnnouncer />
   <PWAPrompt />
 </template>

locales/en-US.json

@@ -1,4 +1,11 @@
 {
+  "a11y": {
+    "loading_page": "Loading page, please wait",
+    "loading_titled_page": "Loading {0} page, please wait",
+    "locale_changed": "Language changed to {0}",
+    "locale_changing": "Changing language, please wait",
+    "route_loaded": "Page {0} loaded"
+  },
   "account": {
     "avatar_description": "{0}'s avatar",
     "blocked_by": "You're blocked by this user.",

locales/es-ES.json

@@ -1,4 +1,11 @@
 {
+  "a11y": {
+    "loading_page": "Cargando página, espere por favor",
+    "loading_titled_page": "Cargando página {0}, espere por favor",
+    "locale_changed": "Idioma cambiado a {0}",
+    "locale_changing": "Cambiando idioma, espere por favor",
+    "route_loaded": "Página {0} cargada"
+  },
   "account": {
     "avatar_description": "avatar de {0}",
     "blocked_by": "Estás bloqueado por este usuario.",