Add modifier to filter keyboard events.

docs/reference/actions.md

@@ -64,11 +64,40 @@ input type=submit | click
 select            | change
 textarea          | input
 
+## KeyboardEvent Filter
+
+You may have Actions that you wish to run only when certain keystrokes are received.
+
+You can install an event listener that responds only to the `Escape` key by adding `.esc` to the event name of the action descriptor, as in the following example.
+
+```html
+<div data-controller="modal"
+     data-action="keydown.esc->modal#close" tabindex="0">
+</div>
+```
+
+This will only work if the event being fired is a keyboard event.
+
+The correspondence between these filter modifier and keys is shown below.
+
+Modifier | Key Name
+-------- | --------
+enter    | Enter
+tab      | Tab
+esc      | Escape
+space:   | " "
+up       | ArrowUp
+down     | ArrowDown
+left     | ArrowLeft
+right    | ArrowRight
+home     | Home
+end      | End
+
 ### Global Events
 
 Sometimes a controller needs to listen for events dispatched on the global `window` or `document` objects.
 
-You can append `@window` or `@document` to the event name in an action descriptor to install the event listener on `window` or `document`, respectively, as in the following example:
+You can append `@window` or `@document` to the event name (contains filter modifer) in an action descriptor to install the event listener on `window` or `document`, respectively, as in the following example:
 
 <meta data-controller="callout" data-callout-text-value="resize@window">
 

src/core/action.ts

@@ -2,6 +2,19 @@ import { ActionDescriptor, parseActionDescriptorString, stringifyEventTarget } f
 import { Token } from "../mutation-observers"
 import { camelize } from "./string_helpers"
 
+const keyMappings: { [key: string]: string } = {
+  "enter": "Enter",
+  "tab":   "Tab",
+  "esc":   "Escape",
+  "space": " ",
+  "up":    "ArrowUp",
+  "down":  "ArrowDown",
+  "left":  "ArrowLeft",
+  "right": "ArrowRight",
+  "home":  "Home",
+  "end":   "End"
+}
+
 export class Action {
   readonly element: Element
   readonly index: number
@@ -10,6 +23,7 @@ export class Action {
   readonly eventOptions: AddEventListenerOptions
   readonly identifier: string
   readonly methodName: string
+  readonly keyFilter: string
 
   static forToken(token: Token) {
     return new this(token.element, token.index, parseActionDescriptorString(token.content))
@@ -23,11 +37,21 @@ export class Action {
     this.eventOptions = descriptor.eventOptions || {}
     this.identifier   = descriptor.identifier || error("missing identifier")
     this.methodName   = descriptor.methodName || error("missing method name")
+    this.keyFilter    = descriptor.keyFilter || ''
   }
 
   toString() {
-    const eventNameSuffix = this.eventTargetName ? `@${this.eventTargetName}` : ""
-    return `${this.eventName}${eventNameSuffix}->${this.identifier}#${this.methodName}`
+    const eventFilter = this.keyFilter ? `.${this.keyFilter}` : ""
+    const eventTarget = this.eventTargetName ? `@${this.eventTargetName}` : ""
+    return `${this.eventName}${eventFilter}${eventTarget}->${this.identifier}#${this.methodName}`
+  }
+
+  isFilterTarget(key: string): boolean {
+    if (!(this.keyFilter && keyMappings[this.keyFilter])) {
+      return false;
+    }
+
+    return keyMappings[this.keyFilter] !== key
   }
 
   get params(): object {

src/core/action_descriptor.ts

@@ -4,20 +4,22 @@ export interface ActionDescriptor {
   eventName: string
   identifier: string
   methodName: string
+  keyFilter: string
 }
 
-// capture nos.:            12   23 4               43   1 5   56 7      768 9  98
-const descriptorPattern = /^((.+?)(@(window|document))?->)?(.+?)(#([^:]+?))(:(.+))?$/
+// capture nos.:               1   1     2   2      3               3      4   4    5      5     6  6
+const descriptorPattern = /^(?:(.+?)(?:\.(.+?))?(?:@(window|document))?->)?(.+?)(?:#([^:]+?))(?::(.+))?$/
 
 export function parseActionDescriptorString(descriptorString: string): Partial<ActionDescriptor> {
   const source = descriptorString.trim()
   const matches = source.match(descriptorPattern) || []
   return {
-    eventTarget:  parseEventTarget(matches[4]),
-    eventName:    matches[2],
-    eventOptions: matches[9] ? parseEventOptions(matches[9]) : {},
-    identifier:   matches[5],
-    methodName:   matches[7]
+    eventTarget:  parseEventTarget(matches[3]),
+    eventName:    matches[1],
+    eventOptions: matches[6] ? parseEventOptions(matches[6]) : {},
+    identifier:   matches[4],
+    methodName:   matches[5],
+    keyFilter: matches[2]
   }
 }
 

src/core/binding.ts

@@ -63,6 +63,11 @@ export class Binding {
 
   private willBeInvokedByEvent(event: Event): boolean {
     const eventTarget = event.target
+
+    if (event instanceof KeyboardEvent && this.action.isFilterTarget(event.key)) {
+      return false;
+    }
+
     if (this.element === eventTarget) {
       return true
     } else if (eventTarget instanceof Element && this.element.contains(eventTarget)) {

src/tests/cases/dom_test_case.ts

@@ -51,6 +51,15 @@ export class DOMTestCase extends TestCase {
     return event
   }
 
+  async triggerKeyboardEvent(selectorOrTarget: string | EventTarget, type: string, options: KeyboardEventInit = {}) {
+    const eventTarget = typeof selectorOrTarget == "string" ? this.findElement(selectorOrTarget) : selectorOrTarget
+    const event = new KeyboardEvent(type, options);
+
+    eventTarget.dispatchEvent(event)
+    await this.nextFrame
+    return event
+  }
+
   findElement(selector: string) {
     const element = this.fixtureElement.querySelector(selector)
     if (element) {

src/tests/modules/core/action_keyboard_filter_tests.ts

@@ -0,0 +1,135 @@
+import { LogControllerTestCase } from "../../cases/log_controller_test_case"
+
+export default class ActionKeyboardFilterTests extends LogControllerTestCase {
+  identifier = ["a"]
+  fixtureHTML = `
+    <div data-controller="a" data-action="keydown.esc@document->a#log">
+      <button id="button1" data-action="keydown.enter->a#log keydown.space->a#log2 keydown->a#log3"></button>
+      <button id="button2" data-action="keydown.tab->a#log   keydown.esc->a#log2   keydown->a#log3"></button>
+      <button id="button3" data-action="keydown.up->a#log    keydown.down->a#log2  keydown->a#log3"></button>
+      <button id="button4" data-action="keydown.left->a#log  keydown.right->a#log2 keydown->a#log3"></button>
+      <button id="button5" data-action="keydown.home->a#log  keydown.end->a#log2   keydown->a#log3"></button>
+      <button id="button6" data-action="keyup.end->a#log     keyup->a#log3"></button>
+      <button id="button7"></button>
+    </div>
+  `
+
+  async "test ignore event handlers associated with modifiers other than Enter"() {
+    const button = this.findElement("#button1")
+    await this.nextFrame
+    await this.triggerKeyboardEvent(button, "keydown", {key: 'Enter'})
+    this.assertActions(
+      {name: "log", identifier: "a", eventType: 'keydown', currentTarget: button},
+      {name: "log3", identifier: "a", eventType: 'keydown', currentTarget: button}
+    )
+  }
+
+  async "test ignore event handlers associated with modifiers other than Space"() {
+    const button = this.findElement("#button1")
+    await this.nextFrame
+    await this.triggerKeyboardEvent(button, "keydown", {key: ' '})
+    this.assertActions(
+      {name: "log2", identifier: "a", eventType: 'keydown', currentTarget: button},
+      {name: "log3", identifier: "a", eventType: 'keydown', currentTarget: button}
+    )
+  }
+
+  async "test ignore event handlers associated with modifiers other than Tab"() {
+    const button = this.findElement("#button2")
+    await this.nextFrame
+    await this.triggerKeyboardEvent(button, "keydown", {key: 'Tab'})
+    this.assertActions(
+      {name: "log", identifier: "a", eventType: 'keydown', currentTarget: button},
+      {name: "log3", identifier: "a", eventType: 'keydown', currentTarget: button}
+    )
+  }
+
+  async "test ignore event handlers associated with modifiers other than Escape"() {
+    const button = this.findElement("#button2")
+    await this.nextFrame
+    await this.triggerKeyboardEvent(button, "keydown", {key: 'Escape'})
+    this.assertActions(
+      {name: "log2", identifier: "a", eventType: 'keydown', currentTarget: button},
+      {name: "log3", identifier: "a", eventType: 'keydown', currentTarget: button}
+    )
+  }
+
+  async "test ignore event handlers associated with modifiers other than ArrowUp"() {
+    const button = this.findElement("#button3")
+    await this.nextFrame
+    await this.triggerKeyboardEvent(button, "keydown", {key: 'ArrowUp'})
+    this.assertActions(
+      {name: "log", identifier: "a", eventType: 'keydown', currentTarget: button},
+      {name: "log3", identifier: "a", eventType: 'keydown', currentTarget: button}
+    )
+  }
+
+  async "test ignore event handlers associated with modifiers other than ArrowDown"() {
+    const button = this.findElement("#button3")
+    await this.nextFrame
+    await this.triggerKeyboardEvent(button, "keydown", {key: 'ArrowDown'})
+    this.assertActions(
+      {name: "log2", identifier: "a", eventType: 'keydown', currentTarget: button},
+      {name: "log3", identifier: "a", eventType: 'keydown', currentTarget: button}
+    )
+  }
+
+  async "test ignore event handlers associated with modifiers other than ArrowLeft"() {
+    const button = this.findElement("#button4")
+    await this.nextFrame
+    await this.triggerKeyboardEvent(button, "keydown", {key: 'ArrowLeft'})
+    this.assertActions(
+      {name: "log", identifier: "a", eventType: 'keydown', currentTarget: button},
+      {name: "log3", identifier: "a", eventType: 'keydown', currentTarget: button}
+    )
+  }
+
+  async "test ignore event handlers associated with modifiers other than ArrowRight"() {
+    const button = this.findElement("#button4")
+    await this.nextFrame
+    await this.triggerKeyboardEvent(button, "keydown", {key: 'ArrowRight'})
+    this.assertActions(
+      {name: "log2", identifier: "a", eventType: 'keydown', currentTarget: button},
+      {name: "log3", identifier: "a", eventType: 'keydown', currentTarget: button}
+    )
+  }
+
+  async "test ignore event handlers associated with modifiers other than Home"() {
+    const button = this.findElement("#button5")
+    await this.nextFrame
+    await this.triggerKeyboardEvent(button, "keydown", {key: 'Home'})
+    this.assertActions(
+      {name: "log", identifier: "a", eventType: 'keydown', currentTarget: button},
+      {name: "log3", identifier: "a", eventType: 'keydown', currentTarget: button}
+    )
+  }
+
+  async "test ignore event handlers associated with modifiers other than End"() {
+    const button = this.findElement("#button5")
+    await this.nextFrame
+    await this.triggerKeyboardEvent(button, "keydown", {key: 'End'})
+    this.assertActions(
+      {name: "log2", identifier: "a", eventType: 'keydown', currentTarget: button},
+      {name: "log3", identifier: "a", eventType: 'keydown', currentTarget: button}
+    )
+  }
+
+  async "test keyup"() {
+    const button = this.findElement("#button6")
+    await this.nextFrame
+    await this.triggerKeyboardEvent(button, "keyup", {key: 'End'})
+    this.assertActions(
+      {name: "log", identifier: "a", eventType: 'keyup', currentTarget: button},
+      {name: "log3", identifier: "a", eventType: 'keyup', currentTarget: button}
+    )
+  }
+
+  async "test global event"() {
+    const button = this.findElement("#button7")
+    await this.nextFrame
+    await this.triggerKeyboardEvent(button, "keydown", {key: 'Escape', bubbles: true})
+    this.assertActions(
+      {name: "log", identifier: "a", eventType: 'keydown', currentTarget: document},
+    )
+  }
+}