@instructure/ui-a11y-utils 8.12.0 → 8.12.1-snapshot.15

package/src/FocusRegion.ts

@@ -27,7 +27,6 @@ import keycode from 'keycode'
 import {
   contains,
   addEventListener,
-  getFrameDocumentSafe,
   ownerDocument,
   findTabbable
 } from '@instructure/ui-dom-utils'
@@ -36,66 +35,54 @@ import { logError as error } from '@instructure/console'
 
 import { ScreenReaderFocusRegion } from './ScreenReaderFocusRegion'
 import { KeyboardFocusRegion } from './KeyboardFocusRegion'
+import { FocusRegionOptions } from './FocusRegionOptions'
 
 class FocusRegion {
-  // @ts-expect-error ts-migrate(7006) FIXME: Parameter 'element' implicitly has an 'any' type.
-  constructor(element, options) {
-    // @ts-expect-error ts-migrate(2339) FIXME: Property '_options' does not exist on type 'FocusR... Remove this comment to see the full error message
+  private _contextElement: Node | Element | null = null
+  private _preventCloseOnDocumentClick = false
+  private _options: FocusRegionOptions
+  private readonly _screenReaderFocusRegion: ScreenReaderFocusRegion
+  private readonly _keyboardFocusRegion: KeyboardFocusRegion
+  private readonly _id: string
+  private _listeners: ReturnType<typeof addEventListener>[] = []
+  private _active = false
+
+  constructor(element: Element | Node, options: FocusRegionOptions) {
     this._options = options || {
       shouldCloseOnDocumentClick: true,
-      shouldCloseOnEscape: true,
-      // @ts-expect-error ts-migrate(6133) FIXME: 'event' is declared but its value is never read.
-      onDismiss: (event) => {}
+      shouldCloseOnEscape: true
     }
     this._contextElement = element
-    // @ts-expect-error ts-migrate(2339) FIXME: Property '_screenReaderFocusRegion' does not exist... Remove this comment to see the full error message
     this._screenReaderFocusRegion = new ScreenReaderFocusRegion(
       element,
       options
     )
-    // @ts-expect-error ts-migrate(2339) FIXME: Property '_keyboardFocusRegion' does not exist on ... Remove this comment to see the full error message
     this._keyboardFocusRegion = new KeyboardFocusRegion(element, options)
-    // @ts-expect-error ts-migrate(2339) FIXME: Property '_id' does not exist on type 'FocusRegion... Remove this comment to see the full error message
     this._id = uid()
   }
 
-  _contextElement = null
-  _preventCloseOnDocumentClick = false
-  _listeners = []
-  _active = false
-
-  // @ts-expect-error ts-migrate(7006) FIXME: Parameter 'element' implicitly has an 'any' type.
-  updateElement(element) {
+  updateElement(element: Element | Node) {
     this._contextElement = element
-    // @ts-expect-error ts-migrate(2339) FIXME: Property '_keyboardFocusRegion' does not exist on ... Remove this comment to see the full error message
     if (this._keyboardFocusRegion) {
-      // @ts-expect-error ts-migrate(2339) FIXME: Property '_keyboardFocusRegion' does not exist on ... Remove this comment to see the full error message
       this._keyboardFocusRegion.updateElement(element)
     }
-    // @ts-expect-error ts-migrate(2339) FIXME: Property '_screenReaderFocusRegion' does not exist... Remove this comment to see the full error message
     if (this._screenReaderFocusRegion) {
-      // @ts-expect-error ts-migrate(2339) FIXME: Property '_screenReaderFocusRegion' does not exist... Remove this comment to see the full error message
       this._screenReaderFocusRegion.updateElement(element)
     }
   }
 
-  // @ts-expect-error ts-migrate(7006) FIXME: Parameter 'event' implicitly has an 'any' type.
-  handleDismiss = (event, documentClick) => {
-    // @ts-expect-error ts-migrate(2339) FIXME: Property '_options' does not exist on type 'FocusR... Remove this comment to see the full error message
-    this._options.onDismiss(event, documentClick)
+  handleDismiss = (event: Event, documentClick?: boolean) => {
+    this._options.onDismiss?.(event, documentClick)
   }
 
-  // @ts-expect-error ts-migrate(7006) FIXME: Parameter 'event' implicitly has an 'any' type.
-  captureDocumentClick = (event) => {
+  captureDocumentClick = (event: MouseEvent) => {
     const { target } = event
     this._preventCloseOnDocumentClick =
-      event.button !== 0 || contains(this._contextElement, target)
+      event.button !== 0 || contains(this._contextElement, target as Node)
   }
 
-  // @ts-expect-error ts-migrate(7006) FIXME: Parameter 'event' implicitly has an 'any' type.
-  handleDocumentClick = (event) => {
+  handleDocumentClick = (event: MouseEvent) => {
     if (
-      // @ts-expect-error ts-migrate(2339) FIXME: Property '_options' does not exist on type 'FocusR... Remove this comment to see the full error message
       this._options.shouldCloseOnDocumentClick &&
       !this._preventCloseOnDocumentClick
     ) {
@@ -103,30 +90,24 @@ class FocusRegion {
     }
   }
 
-  // @ts-expect-error ts-migrate(7006) FIXME: Parameter 'event' implicitly has an 'any' type.
-  handleFrameClick = (event, frame) => {
+  handleFrameClick = (event: MouseEvent, frame: HTMLIFrameElement) => {
     if (!contains(this._contextElement, frame)) {
       // dismiss if frame is not within the region
       this.handleDismiss(event, true)
     }
   }
 
-  // @ts-expect-error ts-migrate(7006) FIXME: Parameter 'event' implicitly has an 'any' type.
-  handleKeyUp = (event) => {
+  handleKeyUp = (event: KeyboardEvent) => {
     if (
-      // @ts-expect-error ts-migrate(2339) FIXME: Property '_options' does not exist on type 'FocusR... Remove this comment to see the full error message
       this._options.shouldCloseOnEscape &&
-      // @ts-expect-error ts-migrate(2339) FIXME: Property 'escape' does not exist on type 'CodesMap... Remove this comment to see the full error message
-      event.keyCode === keycode.codes.escape &&
+      event.keyCode === keycode.codes.esc &&
       !event.defaultPrevented
     ) {
-      // @ts-expect-error ts-migrate(2554) FIXME: Expected 2 arguments, but got 1.
       this.handleDismiss(event)
     }
   }
 
   get id() {
-    // @ts-expect-error ts-migrate(2339) FIXME: Property '_id' does not exist on type 'FocusRegion... Remove this comment to see the full error message
     return this._id
   }
 
@@ -144,63 +125,59 @@ class FocusRegion {
     if (!this._active) {
       const doc = ownerDocument(this._contextElement)
 
-      // @ts-expect-error ts-migrate(2339) FIXME: Property '_keyboardFocusRegion' does not exist on ... Remove this comment to see the full error message
       this._keyboardFocusRegion.activate()
-      // @ts-expect-error ts-migrate(2339) FIXME: Property '_screenReaderFocusRegion' does not exist... Remove this comment to see the full error message
       this._screenReaderFocusRegion.activate()
 
-      // @ts-expect-error ts-migrate(2339) FIXME: Property '_options' does not exist on type 'FocusR... Remove this comment to see the full error message
       if (this._options.shouldCloseOnDocumentClick) {
         this._listeners.push(
-          // @ts-expect-error ts-migrate(2345) FIXME: Argument of type '{ remove(): void; }' is not assi... Remove this comment to see the full error message
-          addEventListener(doc, 'click', this.captureDocumentClick, true)
+          addEventListener(
+            doc,
+            'click',
+            this.captureDocumentClick as EventListener,
+            true
+          )
         )
         this._listeners.push(
-          // @ts-expect-error ts-migrate(2345) FIXME: Argument of type '{ remove(): void; }' is not assi... Remove this comment to see the full error message
-          addEventListener(doc, 'click', this.handleDocumentClick)
+          addEventListener(
+            doc,
+            'click',
+            this.handleDocumentClick as EventListener
+          )
         )
 
         Array.from(doc.getElementsByTagName('iframe')).forEach((el) => {
           // listen for mouseup events on any iframes in the document
-          const frameDoc = getFrameDocumentSafe(el)
-
+          const frameDoc = el.contentDocument
           if (frameDoc) {
             this._listeners.push(
-              // @ts-expect-error ts-migrate(2345) FIXME: Argument of type '{ remove(): void; }' is not assi... Remove this comment to see the full error message
               addEventListener(frameDoc, 'mouseup', (event) => {
-                this.handleFrameClick(event, el)
+                this.handleFrameClick(event as MouseEvent, el)
               })
             )
           }
         })
       }
 
-      // @ts-expect-error ts-migrate(2339) FIXME: Property '_options' does not exist on type 'FocusR... Remove this comment to see the full error message
       if (this._options.shouldCloseOnEscape) {
-        // @ts-expect-error ts-migrate(2345) FIXME: Argument of type '{ remove(): void; }' is not assi... Remove this comment to see the full error message
-        this._listeners.push(addEventListener(doc, 'keyup', this.handleKeyUp))
+        this._listeners.push(
+          addEventListener(doc, 'keyup', this.handleKeyUp as EventListener)
+        )
       }
 
       this._active = true
     }
   }
 
-  deactivate({ keyboard = true } = {}) {
+  deactivate({ keyboard = true }: { keyboard?: boolean } = {}) {
     if (this._active) {
       this._listeners.forEach((listener) => {
-        // @ts-expect-error ts-migrate(2339) FIXME: Property 'remove' does not exist on type 'never'.
         listener.remove()
       })
       this._listeners = []
-
       if (keyboard) {
-        // @ts-expect-error ts-migrate(2339) FIXME: Property '_keyboardFocusRegion' does not exist on ... Remove this comment to see the full error message
         this._keyboardFocusRegion.deactivate()
       }
-
-      // @ts-expect-error ts-migrate(2339) FIXME: Property '_screenReaderFocusRegion' does not exist... Remove this comment to see the full error message
       this._screenReaderFocusRegion.deactivate()
-
       this._active = false
     }
   }
@@ -210,7 +187,6 @@ class FocusRegion {
       this._active,
       `[FocusRegion] Cannot call '.focus()' on a region that is not currently active.`
     )
-    // @ts-expect-error ts-migrate(2339) FIXME: Property '_keyboardFocusRegion' does not exist on ... Remove this comment to see the full error message
     this._keyboardFocusRegion.focus()
   }
 
@@ -219,7 +195,6 @@ class FocusRegion {
       !this._active,
       `[FocusRegion] Cannot call '.blur()' on a region that is currently active.`
     )
-    // @ts-expect-error ts-migrate(2339) FIXME: Property '_keyboardFocusRegion' does not exist on ... Remove this comment to see the full error message
     this._keyboardFocusRegion.blur()
   }
 }
@@ -230,11 +205,13 @@ export {
    * ---
    * category: utilities/a11y
    * ---
-   * @module FocusRegion
-   * Class for focus operations.
+   *
+   * Class for focus operations, manages [ScreenReaderFocusRegion](#ScreenReaderFocusRegion)
+   * and [KeyboardFocusRegion](#KeyboardFocusRegion) for the given DOM element.
    * - Scoping focus within a given context (DOM node),
    * - Mark active element for focus later
    * - Return focus to the marked element
+   * @module FocusRegion
    */
   FocusRegion
 }

package/src/FocusRegionManager.ts

@@ -21,15 +21,25 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
+
 import { logError as error } from '@instructure/console'
 import { FocusRegion } from './FocusRegion'
-
-// @ts-expect-error ts-migrate(7034) FIXME: Variable 'ENTRIES' implicitly has type 'any[]' in ... Remove this comment to see the full error message
-let ENTRIES = []
+import { FocusRegionOptions } from './FocusRegionOptions'
+
+type Entry = {
+  id: string
+  element: Element | Node
+  region: FocusRegion
+  children: Entry[]
+  parent?: Entry
+}
+let ENTRIES: Entry[] = []
 
 class FocusRegionManager {
-  // @ts-expect-error ts-migrate(7006) FIXME: Parameter 'element' implicitly has an 'any' type.
-  static focusRegion = (element, idOrOptions = {}) => {
+  static focusRegion = (
+    element: Element | Node,
+    idOrOptions: string | FocusRegionOptions = {}
+  ) => {
     let entry
     if (typeof idOrOptions === 'string') {
       entry = FocusRegionManager.getEntry(element, idOrOptions)
@@ -45,60 +55,57 @@ class FocusRegionManager {
         `[FocusRegionManager] Could not focus region with element: ${element}`
       )
     }
+    return
   }
 
-  // @ts-expect-error ts-migrate(7006) FIXME: Parameter 'element' implicitly has an 'any' type.
-  static activateRegion = (element, options) => {
+  static activateRegion = (
+    element: Element | Node,
+    options: FocusRegionOptions
+  ) => {
     const { region } = FocusRegionManager.addEntry(element, options)
     return region
   }
 
   static getActiveEntry = () => {
-    // @ts-expect-error ts-migrate(7005) FIXME: Variable 'ENTRIES' implicitly has an 'any[]' type.
     return ENTRIES.find(({ region }) => region.focused)
   }
 
-  // @ts-expect-error ts-migrate(7006) FIXME: Parameter 'element' implicitly has an 'any' type.
-  static findEntry = (element, id) => {
+  static findEntry = (element: Element | Node, id?: string) => {
     let index
     if (id) {
-      // @ts-expect-error ts-migrate(7005) FIXME: Variable 'ENTRIES' implicitly has an 'any[]' type.
       index = ENTRIES.findIndex((entry) => entry.id === id)
     } else {
-      // @ts-expect-error ts-migrate(7005) FIXME: Variable 'ENTRIES' implicitly has an 'any[]' type.
       index = ENTRIES.findIndex((entry) => entry.element === element)
     }
     return index
   }
 
-  // @ts-expect-error ts-migrate(7006) FIXME: Parameter 'element' implicitly has an 'any' type.
-  static getEntry = (element, id) => {
-    // @ts-expect-error ts-migrate(7005) FIXME: Variable 'ENTRIES' implicitly has an 'any[]' type.
+  static getEntry = (element: Element | Node, id?: string) => {
     return ENTRIES[FocusRegionManager.findEntry(element, id)]
   }
 
-  // @ts-expect-error ts-migrate(7006) FIXME: Parameter 'element' implicitly has an 'any' type.
-  static addEntry = (element, options = {}) => {
+  static addEntry = (
+    element: Element | Node,
+    options: FocusRegionOptions = {}
+  ) => {
     const region = new FocusRegion(element, options)
     const activeEntry = FocusRegionManager.getActiveEntry()
 
     const { keyboardFocusable } = region
 
-    // @ts-expect-error ts-migrate(7005) FIXME: Variable 'ENTRIES' implicitly has an 'any[]' type.
     ENTRIES.forEach(({ region }) => {
       if (region) {
         // If the active region is triggering a new focus region that does not have
         // keyboard focusable content, don't deactivate the active region's keyboard
         // focus region
-        region.deactivate(
-          region.focused && !keyboardFocusable && { keyboard: false }
-        )
+        const keyboard =
+          region.focused && !keyboardFocusable ? { keyboard: false } : undefined
+        region.deactivate(keyboard)
       }
     })
 
     region.activate()
 
-    // @ts-expect-error ts-migrate(2339) FIXME: Property 'shouldFocusOnOpen' does not exist on typ... Remove this comment to see the full error message
     if (options.shouldFocusOnOpen) {
       region.focus()
     }
@@ -117,22 +124,16 @@ class FocusRegionManager {
     return entry
   }
 
-  // @ts-expect-error ts-migrate(7006) FIXME: Parameter 'element' implicitly has an 'any' type.
-  static removeEntry = (element, id) => {
+  static removeEntry = (element: Element | Node, id?: string) => {
     const index = FocusRegionManager.findEntry(element, id)
-    // @ts-expect-error ts-migrate(7005) FIXME: Variable 'ENTRIES' implicitly has an 'any[]' type.
     const entry = ENTRIES[index]
-
     if (index > -1) {
-      // @ts-expect-error ts-migrate(7005) FIXME: Variable 'ENTRIES' implicitly has an 'any[]' type.
       ENTRIES.splice(index, 1)
     }
-
     return entry
   }
 
-  // @ts-expect-error ts-migrate(7006) FIXME: Parameter 'element' implicitly has an 'any' type.
-  static isFocused = (element, id) => {
+  static isFocused = (element: Element | Node, id?: string) => {
     const entry = FocusRegionManager.getActiveEntry()
     if (id) {
       return entry && entry.region && entry.id === id
@@ -145,8 +146,7 @@ class FocusRegionManager {
     ENTRIES = []
   }
 
-  // @ts-expect-error ts-migrate(7006) FIXME: Parameter 'element' implicitly has an 'any' type.
-  static blurRegion = (element, id) => {
+  static blurRegion = (element: Element | Node, id?: string) => {
     const entry = FocusRegionManager.removeEntry(element, id)
 
     if (entry) {
@@ -157,7 +157,6 @@ class FocusRegionManager {
 
       // and any regions created from it
       if (children) {
-        // @ts-expect-error ts-migrate(7031) FIXME: Binding element 'id' implicitly has an 'any' type.
         children.forEach(({ id, element }) => {
           const entry = FocusRegionManager.removeEntry(element, id)
           entry && entry.region && entry.region.deactivate()
@@ -178,11 +177,12 @@ export {
    * ---
    * category: utilities/a11y
    * ---
-   * @module FocusManager
-   * Class for focus operations.
+   *
+   * Class for focus operations, manages multiple [FocusRegion](#FocusRegion)s.
    * - Scoping focus within a given context,
    * - Mark active element for focus later
    * - Return focus to the marked element
+   * @module FocusManager
    */
   FocusRegionManager
 }

package/src/FocusRegionOptions.ts

@@ -0,0 +1,80 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import type { LiveRegion, UIElement } from '@instructure/shared-types'
+
+export type FocusRegionOptions = {
+  /**
+   * Function called when tab focus leaves the focusable content. This only
+   * occurs when `shouldContainFocus` is set to false.
+   */
+  onBlur?: (event: Event) => void
+  /**
+   * Function called when a focus region is dismissed. This can happen when
+   * the user presses the escape key and `shouldCloseOnEscape` is true or
+   * when an IFrame is clicked or when anything outside the focus region
+   * is clicked if `shouldCloseOnDocumentClick` is true.
+   * @param event The event triggered the dismissal
+   * @param documentClick Whether the dismissal was triggered by a mouse click.
+   */
+  onDismiss?: (event: Event, documentClick?: boolean) => void
+  /**
+   * An element or a function returning an element to focus by default
+   */
+  defaultFocusElement?: UIElement
+  /**
+   * An element, function returning an element, or array of elements that will not be hidden from
+   * the screen reader when the focus region is active
+   */
+  liveRegion?: LiveRegion
+  /**
+   * When set to true or its an array that includes the 'keyboard' string,
+   * the keyboard and screenreader focus is trapped; when set to 'screenreader'
+   * only the screenreader focus is trapped.
+   */
+  shouldContainFocus?: boolean | ('keyboard' | 'screenreader')[]
+  /**
+   * When set to true the keyboard focus is returned to the active element
+   * before the focus region was activated.
+   */
+  shouldReturnFocus?: boolean
+  /**
+   * When set to true the `onDismiss` function is called on a click outside
+   * the focus region.
+   */
+  shouldCloseOnDocumentClick?: boolean
+  /**
+   * When set to true the `onDismiss` function is called on the `Escape`
+   * keypress
+   */
+  shouldCloseOnEscape?: boolean
+  /**
+   * When set to true, the `defaultFocusElement` is focused on initialization.
+   */
+  shouldFocusOnOpen?: boolean
+  /**
+   * provides a reference to the underlying html root element
+   */
+  elementRef?: (element: Element | null) => void
+}