Add modifier to filter keyboard events.

docs/reference/actions.md

@@ -65,11 +65,56 @@ 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
+
+If you need to support other keys, you can customize the modifier using custom schema.
+
+```javascript
+import { Application, defaultSchema } from "@hotwired/stimulus"
+
+const customSchema = {
+  ...defaultSchema,
+  keyMappings: {...defaultSchema.keyMappings, a: "a", w: "w", s: "s", d: "d" },
+}
+
+const app = Application.start(document.documentElement, customSchema);
+```
+
+
 ### 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">
 

examples/controllers/tabs_controller.js

@@ -0,0 +1,44 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = [ "tab", "tabpanel" ]
+  static classes = [ "current" ]
+  static values = { index: { default: 0, type: Number } }
+
+  next() {
+    if (this.indexValue < this.lastIndex) {
+      this.indexValue++
+      return
+    }
+    this.indexValue = 0
+  }
+
+  previous() {
+    if (this.indexValue > 0) {
+      this.indexValue--
+      return
+    }
+    this.indexValue = this.lastIndex
+  }
+
+  open(evt) {
+    this.indexValue = this.tabTargets.indexOf(evt.currentTarget)
+  }
+
+  get lastIndex() {
+    return this.tabTargets.length - 1
+  }
+
+  indexValueChanged(current, old) {
+    let panels = this.tabpanelTargets
+    let tabs = this.tabTargets
+
+    if (old != null) {
+      panels[old].classList.remove(...this.currentClasses)
+      tabs[old].tabIndex = -1
+    }
+    panels[current].classList.add(...this.currentClasses)
+    tabs[current].tabIndex = 0
+    tabs[current].focus()
+  }
+}

examples/index.js

@@ -16,3 +16,6 @@ application.register("hello", HelloController)
 
 import SlideshowController from "./controllers/slideshow_controller"
 application.register("slideshow", SlideshowController)
+
+import TabsController from "./controllers/tabs_controller"
+application.register("tabs", TabsController)

examples/public/examples.css

@@ -94,3 +94,13 @@ main {
   min-width: 16em;
 }
 
+.tabpanel {
+  border: 1px solid #dedede;
+  display: none;
+  margin-top: .4rem;
+  padding: 0.8rem;
+  font-size: 6rem;
+}
+.tabpanel--current {
+  display: block;
+}

examples/server.js

@@ -22,6 +22,7 @@ const pages = [
   { path: "/clipboard", title: "Clipboard" },
   { path: "/slideshow", title: "Slideshow" },
   { path: "/content-loader", title: "Content Loader" },
+  { path: "/tabs", title: "Tabs" },
 ]
 
 app.get("/", (req, res) => {

examples/views/tabs.ejs

@@ -0,0 +1,42 @@
+<% include layout/head %>
+
+<div data-controller="tabs" data-tabs-current-class="tabpanel--current" aria-label="example">
+  <p>This tabbed interface is operated by focusing on a button and pressing the left and right keys.</p>
+  <div role="tablist">
+    <button
+      id="tab1"
+      role="tab"
+      tabindex="0"
+      data-action="keydown.left->tabs#previous keydown.right->tabs#next click->tabs#open"
+      data-tabs-target="tab"
+      aria-controls="panel1"
+    >tab1</button>
+    <button
+      id="tab2"
+      role="tab"
+      tabindex="0"
+      data-action="keydown.left->tabs#previous keydown.right->tabs#next click->tabs#open"
+      data-tabs-target="tab"
+      aria-controls="panel2"
+    >tab2</button>
+  </div>
+
+  <div
+    id="panel1"
+    role="tabpanel"
+    tabindex="0"
+    data-tabs-target="tabpanel"
+    class="tabpanel tabpanel--current"
+    aria-labelledby="tab1"
+  >🐵</div>
+  <div
+    id="panel2"
+    role="tabpanel"
+    tabindex="0"
+    data-tabs-target="tabpanel"
+    class="tabpanel"
+    aria-labelledby="tab2"
+  >🙈</div>
+</div>
+
+<% include layout/tail %>

src/core/action.ts

@@ -1,5 +1,6 @@
 import { ActionDescriptor, parseActionDescriptorString, stringifyEventTarget } from "./action_descriptor"
 import { Token } from "../mutation-observers"
+import { Schema } from "./schema"
 import { camelize } from "./string_helpers"
 
 export class Action {
@@ -10,24 +11,37 @@ export class Action {
   readonly eventOptions: AddEventListenerOptions
   readonly identifier: string
   readonly methodName: string
+  readonly keyFilter: string
+  readonly schema: Schema
 
-  static forToken(token: Token) {
-    return new this(token.element, token.index, parseActionDescriptorString(token.content))
+  static forToken(token: Token, schema: Schema) {
+    return new this(token.element, token.index, parseActionDescriptorString(token.content), schema)
   }
 
-  constructor(element: Element, index: number, descriptor: Partial<ActionDescriptor>) {
+  constructor(element: Element, index: number, descriptor: Partial<ActionDescriptor>, schema: Schema) {
     this.element      = element
     this.index        = index
     this.eventTarget  = descriptor.eventTarget || element
     this.eventName    = descriptor.eventName || getDefaultEventNameForElement(element) || error("missing event name")
     this.eventOptions = descriptor.eventOptions || {}
     this.identifier   = descriptor.identifier || error("missing identifier")
     this.methodName   = descriptor.methodName || error("missing method name")
+    this.keyFilter    = descriptor.keyFilter || ''
+    this.schema = schema
   }
 
   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 && this.keyMappings[this.keyFilter])) {
+      return false;
+    }
+
+    return this.keyMappings[this.keyFilter] !== key
   }
 
   get params() {
@@ -47,6 +61,10 @@ export class Action {
   private get eventTargetName() {
     return stringifyEventTarget(this.eventTarget)
   }
+
+  private get keyMappings() {
+    return this.schema.keyMappings;
+  }
 }
 
 const defaultEventNames: { [tagName: string]: (element: Element) => string } = {

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/core/binding_observer.ts

@@ -79,7 +79,7 @@ export class BindingObserver implements ValueListObserverDelegate<Action> {
   // Value observer delegate
 
   parseValueForToken(token: Token): Action | undefined {
-    const action = Action.forToken(token)
+    const action = Action.forToken(token, this.schema)
     if (action.identifier == this.identifier) {
       return action
     }

src/core/schema.ts

@@ -3,11 +3,24 @@ export interface Schema {
   actionAttribute: string
   targetAttribute: string
   targetAttributeForScope(identifier: string): string
+  keyMappings: {[key: string]: string}
 }
 
 export const defaultSchema: Schema = {
   controllerAttribute: "data-controller",
   actionAttribute: "data-action",
   targetAttribute: "data-target",
-  targetAttributeForScope: identifier => `data-${identifier}-target`
+  targetAttributeForScope: identifier => `data-${identifier}-target`,
+  keyMappings: {
+    "enter": "Enter",
+    "tab":   "Tab",
+    "esc":   "Escape",
+    "space": " ",
+    "up":    "ArrowUp",
+    "down":  "ArrowDown",
+    "left":  "ArrowLeft",
+    "right": "ArrowRight",
+    "home":  "Home",
+    "end":   "End"
+  }
 }

src/tests/cases/application_test_case.ts

@@ -2,7 +2,7 @@ import { Application } from "../../core/application";
 import { DOMTestCase } from "./dom_test_case";
 import { Schema, defaultSchema } from "../../core/schema";
 
-class TestApplication extends Application {
+export class TestApplication extends Application {
   handleError(error: Error, message: string, detail: object) {
     throw error
   }

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) {