Add modifier to filter keyboard events.

docs/reference/actions.md

@@ -65,11 +65,70 @@ 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 and keys is shown below.
+
+Filter | Key Name
+-------- | --------
+enter    | Enter
+tab      | Tab
+esc      | Escape
+space    | " "
+up       | ArrowUp
+down     | ArrowDown
+left     | ArrowLeft
+right    | ArrowRight
+home     | Home
+end      | End
+[a-z]    | [a-z]
+[0-9]    | [0-9]
+
+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, "@": "@" },
+}
+
+const app = Application.start(document.documentElement, customSchema);
+```
+
+If you want to subscribe to a compound filter using a modifier key, you can write it like `shift+a`.
+
+```html
+<div data-action="keydown.shift+a->listbox#selectAll" role="option" tabindex="0">...</div>
+```
+
+The list of supported modifier keys is shown below.
+
+* meta
+* ctrl
+* alt
+* shift
+
 ### 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 {
   readonly element: Element
@@ -9,24 +10,52 @@ 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(event: KeyboardEvent): boolean {
+    if (!this.keyFilter) { return false }
+
+    const filteres = this.keyFilter.split("+")
+    const modifiers = ["meta", "ctrl", "alt", "shift"]
+    const [meta, ctrl, alt, shift] = modifiers.map(modifier => filteres.includes(modifier))
+
+    if (event.metaKey !== meta || event.ctrlKey !== ctrl || event.altKey !== alt || event.shiftKey !== shift) {
+      return true
+    }
+
+    const standardFilter = filteres.filter(key => !modifiers.includes(key))[0]
+    if (!standardFilter) { // missing non modifier key
+      return false
+    }
+
+    if (!this.keyMappings.hasOwnProperty(standardFilter)) {
+      error(`contains unkown key filter: ${this.keyFilter}`)
+    }
+
+    return this.keyMappings[standardFilter].toLowerCase() !== event.key.toLowerCase()
   }
 
   get params() {
@@ -46,6 +75,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

@@ -1,11 +1,3 @@
-export interface ActionDescriptor {
-  eventTarget: EventTarget
-  eventOptions: AddEventListenerOptions
-  eventName: string
-  identifier: string
-  methodName: string
-}
-
 export type ActionDescriptorFilters = Record<string, ActionDescriptorFilter>
 export type ActionDescriptorFilter = (options: ActionDescriptorFilterOptions) => boolean
 type ActionDescriptorFilterOptions = {
@@ -37,18 +29,29 @@ export const defaultActionDescriptorFilters: ActionDescriptorFilters = {
   },
 }
 
-// capture nos.:            12   23 4               43   1 5   56 7      768 9  98
-const descriptorPattern = /^((.+?)(@(window|document))?->)?(.+?)(#([^:]+?))(:(.+))?$/
+export interface ActionDescriptor {
+  eventTarget: EventTarget
+  eventOptions: AddEventListenerOptions
+  eventName: string
+  identifier: string
+  methodName: string
+  keyFilter: string
+}
+
+
+// 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

@@ -81,6 +81,11 @@ export class Binding {
 
   private willBeInvokedByEvent(event: Event): boolean {
     const eventTarget = event.target
+
+    if (event instanceof KeyboardEvent && this.action.isFilterTarget(event)) {
+      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

@@ -4,6 +4,7 @@ export interface Schema {
   targetAttribute: string
   targetAttributeForScope(identifier: string): string
   outletAttributeForScope(identifier: string, outlet: string): string
+  keyMappings: {[key: string]: string}
 }
 
 export const defaultSchema: Schema = {
@@ -12,4 +13,24 @@ export const defaultSchema: Schema = {
   targetAttribute: "data-target",
   targetAttributeForScope: (identifier) => `data-${identifier}-target`,
   outletAttributeForScope: (identifier, outlet) => `data-${identifier}-${outlet}-outlet`,
+  keyMappings: {
+    "enter": "Enter",
+    "tab":   "Tab",
+    "esc":   "Escape",
+    "space": " ",
+    "up":    "ArrowUp",
+    "down":  "ArrowDown",
+    "left":  "ArrowLeft",
+    "right": "ArrowRight",
+    "home":  "Home",
+    "end":   "End",
+    // [a-z]
+    ...objectFromEntries("abcdefghijklmnopqrstuvwxyz".split("").map(c => [c, c])),
+    // [0-9]
+    ...objectFromEntries("0123456789".split("").map(n => [n, n]))
+  }
+}
+
+function objectFromEntries(array: [string, any][]): object { // polyfill
+  return array.reduce((memo, [k, v]) => ({...memo, [k]: v}), {})
 }

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