keyboard-shortcuts: Display "Ctrl" for Vim "Esc" keybinding behavior.

For all users, we want to display "Ctrl" for the "Ctrl" "[" keyboard
shortcuts that match the "Esc" Vim keybinding behavior.

We use the "data-mac-key" attribute to override the default mapping
of "Ctrl" to "Cmd" for Mac users in the documentation of these
keyboard shortcuts.

Fixes #20107.

help/configure-home-view.md

@@ -13,8 +13,8 @@ on how to use these views.
 
 You can configure which view is set as your home view, and whether
 the <kbd>Esc</kbd> key navigates to the home view. Also, you can
-always reach the home view by using the <kbd>Ctrl</kbd> + <kbd>[</kbd>
+always reach the home view by using the
-shortcut.
+<kbd data-mac-key="Ctrl">Ctrl</kbd> + <kbd>[</kbd> shortcut.
 
 ## Change home view
 
@@ -44,7 +44,8 @@ organization settings:
 
 1. To see your changes in action, open a new Zulip tab, or use a keyboard
    shortcut twice to exit the settings and navigate to your home view
-   (<kbd>Ctrl</kbd> + <kbd>[</kbd> or <kbd>Esc</kbd> if enabled).
+   (<kbd data-mac-key="Ctrl">Ctrl</kbd> + <kbd>[</kbd> or <kbd>Esc</kbd>
+   if enabled).
 
 !!! tip ""
 
@@ -62,8 +63,8 @@ designed to enhance the user experience in the app.
 By default, the <kbd>Esc</kbd> key shortcut will ultimately navigate to
 your home view. You can disable this key binding if you would prefer.
 This will not disable other <kbd>Esc</kbd> key shortcuts used in Zulip,
-and will not affect the behavior of the <kbd>Ctrl</kbd> + <kbd>[</kbd>
+and will not affect the behavior of the
-shortcut.
+<kbd data-mac-key="Ctrl">Ctrl</kbd> + <kbd>[</kbd> shortcut.
 
 ### Toggle whether <kbd>Esc</kbd> navigates to the home view
 

help/keyboard-shortcuts.md

@@ -32,9 +32,9 @@ in the Zulip app to add more to your repertoire as needed.
   <kbd>Ctrl</kbd> + <kbd>V</kbd>, and press <kbd>Ctrl</kbd> + <kbd>Z</kbd> to
   remove formatting.
 
-* **Cancel compose and save draft**: <kbd>Esc</kbd> or <kbd>Ctrl</kbd> +
+* **Cancel compose and save draft**: <kbd>Esc</kbd> or
-  <kbd>[</kbd> — Close the compose box and save the unsent message as a
+  <kbd data-mac-key="Ctrl">Ctrl</kbd> + <kbd>[</kbd> — Close the compose box
-  draft.
+  and save the unsent message as a draft.
 
 * **View drafts**: <kbd>D</kbd> — Use the arrow keys and <kbd>Enter</kbd>
   to restore a draft. Press <kbd>D</kbd> again to close.
@@ -54,8 +54,8 @@ in the Zulip app to add more to your repertoire as needed.
 
 * **Toggle keyboard shortcuts view**: <kbd>?</kbd>
 
-* **Go to your home view**: <kbd>Ctrl</kbd> + <kbd>[</kbd> (or
+* **Go to your home view**: <kbd data-mac-key="Ctrl">Ctrl</kbd> + <kbd>[</kbd>
-  <kbd>Esc</kbd>, [if enabled][disable-escape])
+  (or <kbd>Esc</kbd>, [if enabled][disable-escape])
   until you are in your [home view](/help/configure-home-view).
 
 [disable-escape]: /help/configure-home-view#configure-whether-esc-navigates-to-the-home-view
@@ -158,8 +158,9 @@ in the Zulip app to add more to your repertoire as needed.
 
 * **Toggle preview mode**: <kbd>Alt</kbd> + <kbd>P</kbd>
 
-* **Cancel compose and save draft**: <kbd>Esc</kbd> or <kbd>Ctrl</kbd> +
+* **Cancel compose and save draft**: <kbd>Esc</kbd> or
-  <kbd>[</kbd> — Close the compose box and save the unsent message as a draft.
+  <kbd data-mac-key="Ctrl">Ctrl</kbd> + <kbd>[</kbd> — Close the compose box
+  and save the unsent message as a draft.
 
 ## Message actions
 

web/src/common.ts

@@ -34,10 +34,14 @@ export function adjust_mac_kbd_tags(kbd_elem_class: string): void {
         let key_text = $(this).text();
 
         // We use data-mac-key attribute to override the default key in case
-        // of exceptions. Currently, there are 2 shortcuts (for navigating back
+        // of exceptions:
-        // and forth in browser history) which need `Cmd` instead of the expected
+        // - There are 2 shortcuts (for navigating back and forth in browser
-        // mapping (`Opt`) for the `Alt` key, so we use this attribute to override
+        //   history) which need "⌘" instead of the expected mapping ("Opt")
-        // `Opt` with `Cmd`.
+        //   for the "Alt" key, so we use this attribute to override "Opt"
+        //   with "⌘".
+        // - The "Ctrl" + "[" shortcuts (which match the Vim keybinding behavior
+        //   of mapping to "Esc") need to display "Ctrl" for all users, so we
+        //   use this attribute to override "⌘" with "Ctrl".
         const replace_key = $(this).attr("data-mac-key") ?? keys_map.get(key_text);
         if (replace_key !== undefined) {
             key_text = replace_key;

web/templates/keyboard_shortcuts.hbs

@@ -30,7 +30,7 @@
                 </tr>
                 <tr>
                     <td class="definition">{{t 'Cancel compose and save draft' }}</td>
-                    <td><span class="hotkey"><kbd>Esc</kbd> or <kbd>Ctrl</kbd> + <kbd>[</kbd></span></td>
+                    <td><span class="hotkey"><kbd>Esc</kbd> or <kbd data-mac-key="Ctrl">Ctrl</kbd> + <kbd>[</kbd></span></td>
                 </tr>
                 <tr>
                     <td class="definition">{{t 'View drafts' }}</td>
@@ -66,7 +66,7 @@
                 </tr>
                 <tr>
                     <td class="definition">{{t 'Go to your home view' }}</td>
-                    <td><span class="hotkey"><kbd>Ctrl</kbd> + <kbd>[</kbd><span id="go-to-home-view-hotkey-help"> or <kbd>Esc</kbd></span></span></td>
+                    <td><span class="hotkey"><kbd data-mac-key="Ctrl">Ctrl</kbd> + <kbd>[</kbd><span id="go-to-home-view-hotkey-help"> or <kbd>Esc</kbd></span></span></td>
                 </tr>
             </table>
         </div>
@@ -238,7 +238,7 @@
                 </tr>
                 <tr>
                     <td class="definition">{{t 'Cancel compose and save draft' }}</td>
-                    <td><span class="hotkey"><kbd>Esc</kbd> or <kbd>Ctrl</kbd> + <kbd>[</kbd></span></td>
+                    <td><span class="hotkey"><kbd>Esc</kbd> or <kbd data-mac-key="Ctrl">Ctrl</kbd> + <kbd>[</kbd></span></td>
                 </tr>
             </table>
         </div>