From 278f0fe24cc303d3ba8a0e84033ce850a6b85bd6 Mon Sep 17 00:00:00 2001 From: mehm8128 Date: Wed, 22 Apr 2026 23:14:19 +0900 Subject: [PATCH 1/4] Set up guarding-keyboard-event-handlers technique --- .../guarding-keyboard-event-handlers.html | 66 +++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 techniques/client-side-script/guarding-keyboard-event-handlers.html diff --git a/techniques/client-side-script/guarding-keyboard-event-handlers.html b/techniques/client-side-script/guarding-keyboard-event-handlers.html new file mode 100644 index 0000000000..5d4e46ca6b --- /dev/null +++ b/techniques/client-side-script/guarding-keyboard-event-handlers.html @@ -0,0 +1,66 @@ + + + + + Guarding keyboard event handlers against IME composition + + + +

Guarding keyboard event handlers against IME composition

+
+

Metadata

+

Provide information below to help editors associate the technique properly. Contents of the meta section are not output by the processor.

+

+

+
+
+

Applicability

+

Describe the situations in which to use the technique, such as types of pages, features in use that might use the technique, etc. Do not add references to the part of WCAG to which the technique relates; this is taken from the Understanding pages and inserted in technique pages upon publication.

+
+
+

Description

+

Describe how the technique works. This begins with a description of the problem the technique solves, then describes how to apply the technique. The description should be detailed enough to provide all the information a reader needs to be able to apply the technique, without recourse to following example code.

+

The objective of this technique is to ...

+
+
+

Examples

+

Copy the following section for each example. Examples must have a title and a description, and usually have a code sample. Code samples should be elided if necessary to show the core of the technique without necessarily providing all the surrounding code that would also be involved. A working example link references a location where the technique can be shown working live.

+
+

Example Title

+

Description

+ Code sample +

Working example of {Example Title}

+
+
+
+

Tests

+

Tests must have a test procedure and expected results. Populate the following sections as appropriate. If a technique has multiple alternative testing approaches, add a new section with class="test" for each one, and put the test-procedure and test-results sections inside that.

+
+

Procedure

+
    +
  1. Step 1
    2. +
+
+
+

Expected Results

+
    +
  • Result
    • +
+
+
+ +
+

Resources

+

Provide links to external resources that are relevant to users of the technique. This section is optional.

+ +
+ + From 0898fe0e4f84c2d1bb44ada58e759610687a16af Mon Sep 17 00:00:00 2001 From: mehm8128 Date: Thu, 23 Apr 2026 00:20:01 +0900 Subject: [PATCH 2/4] Write the content of guarding keyboard event handlers technique --- .../guarding-keyboard-event-handlers.html | 58 +++++++++++++------ understanding/understanding.11tydata.js | 2 + 2 files changed, 42 insertions(+), 18 deletions(-) diff --git a/techniques/client-side-script/guarding-keyboard-event-handlers.html b/techniques/client-side-script/guarding-keyboard-event-handlers.html index 5d4e46ca6b..d5facad2bc 100644 --- a/techniques/client-side-script/guarding-keyboard-event-handlers.html +++ b/techniques/client-side-script/guarding-keyboard-event-handlers.html @@ -9,57 +9,79 @@

Guarding keyboard event handlers against IME composition

Metadata

-

Provide information below to help editors associate the technique properly. Contents of the meta section are not output by the processor.

-

-

+

SC 2.1.1 Keyboard, SC 3.2.2 On Input

+

sufficient

Applicability

-

Describe the situations in which to use the technique, such as types of pages, features in use that might use the technique, etc. Do not add references to the part of WCAG to which the technique relates; this is taken from the Understanding pages and inserted in technique pages upon publication.

+

Web pages that use JavaScript keydown or keyup event handlers to trigger actions on interactive elements.

Description

-

Describe how the technique works. This begins with a description of the problem the technique solves, then describes how to apply the technique. The description should be detailed enough to provide all the information a reader needs to be able to apply the technique, without recourse to following example code.

-

The objective of this technique is to ...

+

The objective of this technique is to ensure that keydown and keyup event handlers do not unintentionally trigger application actions during Input Method Editor (IME) composition.

+

An IME allows users to enter characters not directly available on their keyboard, such as Chinese, Japanese, and Korean characters. During composition, keys like Enter, Tab, and Escape are used to control the IME (for example, confirming a candidate character), but they also fire keydown events on the page. If an event handler does not account for this, it may incorrectly execute application actions — such as submitting a form — while the user is still composing. This can violate SC 2.1.1 (keyboard shortcuts collide with IME controls) and SC 3.2.2 (unexpected change of context from input intended solely for the IME).

+

The KeyboardEvent.isComposing property is true during IME composition. Checking this property at the start of a handler lets developers skip application logic while the user is composing. Some older versions of Safari have a bug where isComposing is false on the final confirmation keypress; additionally checking event.keyCode === 229 provides a reliable cross-browser guard.

+

Alternatively, for form submission specifically, using the submit event is inherently IME-safe because the browser only fires it after composition is complete.

Examples

-

Copy the following section for each example. Examples must have a title and a description, and usually have a code sample. Code samples should be elided if necessary to show the core of the technique without necessarily providing all the surrounding code that would also be involved. A working example link references a location where the technique can be shown working live.

-

Example Title

-

Description

- Code sample -

Working example of {Example Title}

+

Guarding a keydown handler with isComposing

+

In this example, a keydown event listener is attached to a text input. The handler checks event.isComposing and the Safari-compatibility fallback event.keyCode === 229 before triggering form submission when Enter is pressed. This ensures that pressing Enter to confirm an IME candidate does not accidentally submit the form.

+ 
const inputElement = document.querySelector("input");
+
+inputElement.addEventListener("keydown", (event) => {
+  if (event.isComposing || event.keyCode === 229) return;
+  if (event.key === "Enter") submit();
+});
+
+
+

Using the submit event instead of keydown

+

The submit event on a form element is inherently IME-safe. The browser fires submit only after IME composition has ended, so this approach avoids the issue entirely for form submission scenarios.

+ 
const formElement = document.querySelector("form");
+
+formElement.addEventListener("submit", (event) => {
+  event.preventDefault();
+  submit();
+});

Tests

-

Tests must have a test procedure and expected results. Populate the following sections as appropriate. If a technique has multiple alternative testing approaches, add a new section with class="test" for each one, and put the test-procedure and test-results sections inside that.

Procedure

+

For each keydown or keyup event handler that executes an action when a specific key (such as Enter, Tab, or Escape) is pressed on an input element:

    -
  1. Step 1
    2. +
  2. Enable an IME for a language that requires composition (for example, Japanese, Chinese, or Korean).
    3. +
  3. Focus the input element.
    4. +
  4. Begin IME composition by typing a sequence that produces candidate characters.
    5. +
  5. While IME composition is active, press Enter (or the key targeted by the handler) to confirm an IME candidate.
    6. +
  6. Check that the application-level action (for example, form submission) was not triggered.
    7. +
  7. End the IME session and press the same key again without an active IME composition.
    8. +
  8. Check that the application-level action is triggered.

Expected Results

    -
  • Result
    • +
  • Checks #5 and #7 are true.

Resources

-

Provide links to external resources that are relevant to users of the technique. This section is optional.

diff --git a/understanding/understanding.11tydata.js b/understanding/understanding.11tydata.js index b560f13296..9da71021a7 100644 --- a/understanding/understanding.11tydata.js +++ b/understanding/understanding.11tydata.js @@ -578,6 +578,7 @@ export default function (data) { id: "G90", using: ["SCR20", "SCR35", "SCR2"], }, + { id: "guarding-keyboard-event-handlers" }, ], advisory: [ { @@ -1051,6 +1052,7 @@ export default function (data) { }, "G13", "SCR19", + { id: "guarding-keyboard-event-handlers" }, ], sufficientNote: ` A change of content is not always a change of context. From 14e3f6dcf79bd818424764077e3ecd2b895c6d18 Mon Sep 17 00:00:00 2001 From: mehm8128 Date: Thu, 23 Apr 2026 22:38:16 +0900 Subject: [PATCH 3/4] Add IME to custom-words --- custom-words.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/custom-words.txt b/custom-words.txt index 2c478b1424..cee0d204f1 100644 --- a/custom-words.txt +++ b/custom-words.txt @@ -28,6 +28,7 @@ HFS ICT IEC IDREF +IME IMS ISA LINQ From d727e353a5998c1ddb5cfba55cac1a6b8691c5f3 Mon Sep 17 00:00:00 2001 From: mehm8128 Date: Sun, 10 May 2026 23:37:11 +0900 Subject: [PATCH 4/4] Change file name --- .../{guarding-keyboard-event-handlers.html => SCR41.html} | 0 understanding/understanding.11tydata.js | 4 ++-- 2 files changed, 2 insertions(+), 2 deletions(-) rename techniques/client-side-script/{guarding-keyboard-event-handlers.html => SCR41.html} (100%) diff --git a/techniques/client-side-script/guarding-keyboard-event-handlers.html b/techniques/client-side-script/SCR41.html similarity index 100% rename from techniques/client-side-script/guarding-keyboard-event-handlers.html rename to techniques/client-side-script/SCR41.html diff --git a/understanding/understanding.11tydata.js b/understanding/understanding.11tydata.js index 9da71021a7..7ccf864047 100644 --- a/understanding/understanding.11tydata.js +++ b/understanding/understanding.11tydata.js @@ -578,7 +578,7 @@ export default function (data) { id: "G90", using: ["SCR20", "SCR35", "SCR2"], }, - { id: "guarding-keyboard-event-handlers" }, + "SCR41", ], advisory: [ { @@ -1052,7 +1052,7 @@ export default function (data) { }, "G13", "SCR19", - { id: "guarding-keyboard-event-handlers" }, + "SCR41", ], sufficientNote: ` A change of content is not always a change of context.