frontend/aria: hotkey nav

Author: haraldschilly

src/dev/ARIA.md

@@ -27,6 +27,8 @@ import {
   get_dark_mode_config,
 } from "./dark-mode";
 import { EditorSettingsColorScheme } from "./editor-settings/color-schemes";
+import { HotkeyDelayTest } from "./hotkey-delay-test";
+import { HotkeySelector } from "./hotkey-selector";
 import { I18NSelector, I18N_MESSAGE, I18N_TITLE } from "./i18n-selector";
 import { OtherSettings } from "./other-settings";
 import { TerminalSettings } from "./terminal-settings";
@@ -241,6 +243,78 @@ export function AccountPreferencesAppearance() {
             </HelpIcon>
           </div>
         </LabeledRow>
+        <LabeledRow
+          label={
+            <>
+              <Icon name="flash" /> Quick Navigation Hotkey
+            </>
+          }
+        >
+          <HotkeySelector
+            value={other_settings.get("quick_nav_hotkey") ?? "shift+shift"}
+            onChange={(value) => on_change("quick_nav_hotkey", value)}
+            style={{ width: 200 }}
+          />
+        </LabeledRow>
+        {(other_settings.get("quick_nav_hotkey") ?? "shift+shift") ===
+          "shift+shift" && (
+          <LabeledRow
+            label={
+              <>
+                <Icon name="clock" /> Hotkey Delay (milliseconds)
+              </>
+            }
+          >
+            <div style={{ display: "flex", gap: 16, alignItems: "stretch" }}>
+              <div
+                style={{
+                  flex: "1 1 auto",
+                  display: "flex",
+                  alignItems: "center",
+                }}
+              >
+                <Slider
+                  min={100}
+                  max={800}
+                  step={100}
+                  value={other_settings.get("quick_nav_hotkey_delay") ?? 300}
+                  onChange={(value) =>
+                    on_change("quick_nav_hotkey_delay", value)
+                  }
+                  style={{ flex: 1 }}
+                  marks={Object.fromEntries(
+                    Array.from({ length: 8 }, (_, i) => (i + 1) * 100).map(
+                      (ms) => [ms, `${ms}ms`],
+                    ),
+                  )}
+                />
+                <span
+                  style={{
+                    minWidth: 60,
+                    textAlign: "right",
+                    fontWeight: 500,
+                    color: COLORS.GRAY_M,
+                    marginLeft: 12,
+                  }}
+                >
+                  {other_settings.get("quick_nav_hotkey_delay") ?? 300}ms
+                </span>
+              </div>
+              <div
+                style={{
+                  flex: "0 1 auto",
+                  display: "flex",
+                  flexDirection: "column",
+                  gap: 8,
+                }}
+              >
+                <HotkeyDelayTest
+                  delayMs={other_settings.get("quick_nav_hotkey_delay") ?? 300}
+                />
+              </div>
+            </div>
+          </LabeledRow>
+        )}
         <Switch
           checked={!!other_settings.get("auto_focus")}
           onChange={(e) => on_change("auto_focus", e.target.checked)}

src/packages/frontend/account/account-preferences-appearance.tsx

@@ -0,0 +1,162 @@
+/*
+ *  This file is part of CoCalc: Copyright © 2025 Sagemath, Inc.
+ *  License: MS-RSL – see LICENSE.md for details
+ */
+
+import { Button } from "antd";
+import React, { useEffect, useRef, useState } from "react";
+import { COLORS } from "@cocalc/util/theme";
+import { useAppContext } from "@cocalc/frontend/app/context";
+
+interface HotkeyDelayTestProps {
+  delayMs: number;
+}
+
+/**
+ * Test component for double-Shift hotkey detection
+ *
+ * Allows users to verify that their hotkey delay setting works correctly.
+ * When focused, it listens to Shift presses and indicates when a double-Shift
+ * is detected within the configured delay.
+ */
+export const HotkeyDelayTest: React.FC<HotkeyDelayTestProps> = ({
+  delayMs,
+}) => {
+  const { setBlockShiftShiftHotkey } = useAppContext();
+  const [isActive, setIsActive] = useState(false);
+  const [testResult, setTestResult] = useState<
+    "waiting" | "detected" | "failed"
+  >("waiting");
+  const lastShiftTimeRef = useRef<number>(0);
+  const buttonRef = useRef<HTMLButtonElement>(null);
+
+  useEffect(() => {
+    // Set block flag when test becomes active, unblock when inactive
+    setBlockShiftShiftHotkey?.(isActive);
+
+    if (!isActive) {
+      return;
+    }
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      // Only listen for Shift key
+      if (e.key !== "Shift") {
+        return;
+      }
+
+      const now = Date.now();
+      const timeSinceLastShift = now - lastShiftTimeRef.current;
+
+      // Check if this Shift is within delayMs of the last one
+      if (timeSinceLastShift <= delayMs && timeSinceLastShift > 0) {
+        // Double Shift detected! Prevent it from bubbling to the global detector
+        e.preventDefault();
+        e.stopPropagation();
+
+        setTestResult("detected");
+        lastShiftTimeRef.current = 0;
+
+        // Reset after 1 second to show success state
+        const timer = setTimeout(() => {
+          setTestResult("waiting");
+        }, 1000);
+
+        return () => clearTimeout(timer);
+      }
+
+      // Record this Shift press
+      lastShiftTimeRef.current = now;
+
+      // Reset counter after delayMs * 2
+      const resetTimer = setTimeout(() => {
+        lastShiftTimeRef.current = 0;
+      }, delayMs * 2);
+
+      return () => clearTimeout(resetTimer);
+    };
+
+    // Use capture phase to catch Shift key early
+    window.addEventListener("keydown", handleKeyDown, true);
+
+    return () => {
+      window.removeEventListener("keydown", handleKeyDown, true);
+      // Ensure we unblock when component unmounts or isActive becomes false
+      setBlockShiftShiftHotkey?.(false);
+    };
+  }, [isActive, delayMs, setBlockShiftShiftHotkey]);
+
+  const getButtonStyle = (): React.CSSProperties => {
+    const baseStyle: React.CSSProperties = {
+      fontWeight: 500,
+      minWidth: 100,
+    };
+
+    switch (testResult) {
+      case "waiting":
+        return {
+          ...baseStyle,
+          backgroundColor: isActive ? COLORS.ANTD_BLUE : COLORS.GRAY_LL,
+          color: isActive ? "white" : COLORS.GRAY_M,
+          borderColor: isActive ? COLORS.ANTD_BLUE : COLORS.GRAY_L,
+        };
+      case "detected":
+        return {
+          ...baseStyle,
+          backgroundColor: COLORS.ANTD_SUCCESS_GREEN,
+          color: "white",
+          borderColor: COLORS.ANTD_SUCCESS_GREEN,
+        };
+      case "failed":
+        return {
+          ...baseStyle,
+          backgroundColor: COLORS.ANTD_ERROR_RED,
+          color: "white",
+          borderColor: COLORS.ANTD_ERROR_RED,
+        };
+    }
+  };
+
+  const getButtonLabel = (): string => {
+    if (!isActive) {
+      return "Test Hotkey";
+    }
+    switch (testResult) {
+      case "waiting":
+        return "Press Shift Twice";
+      case "detected":
+        return "✓ Detected!";
+      case "failed":
+        return "✗ Try Again";
+    }
+  };
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: 8,
+        alignItems: "flex-start",
+      }}
+    >
+      <Button
+        ref={buttonRef}
+        style={getButtonStyle()}
+        onClick={() => {
+          setIsActive(!isActive);
+          setTestResult("waiting");
+          lastShiftTimeRef.current = 0;
+        }}
+      >
+        {getButtonLabel()}
+      </Button>
+      <span style={{ color: COLORS.GRAY_M, fontSize: 12 }}>
+        {isActive
+          ? `Press Shift twice within ${delayMs}ms`
+          : "Click to test hotkey detection"}
+      </span>
+    </div>
+  );
+};
+
+export default HotkeyDelayTest;

src/packages/frontend/account/hotkey-delay-test.tsx

@@ -0,0 +1,61 @@
+/*
+ *  This file is part of CoCalc: Copyright © 2025 Sagemath, Inc.
+ *  License: MS-RSL – see LICENSE.md for details
+ */
+
+import { Select, SelectProps } from "antd";
+import { IS_MACOS } from "@cocalc/frontend/feature";
+
+export type HotkeyOption =
+  | "shift+shift"
+  | "alt+shift+h"
+  | "alt+shift+space"
+  | "disabled";
+
+interface HotkeySelectorProps
+  extends Omit<SelectProps, "options" | "onChange"> {
+  value?: HotkeyOption;
+  onChange?: (hotkey: HotkeyOption) => void;
+}
+
+/**
+ * A selector for choosing the global hotkey to open quick navigation dialog
+ */
+export function HotkeySelector({
+  value,
+  onChange,
+  ...props
+}: HotkeySelectorProps) {
+  const altShiftH = IS_MACOS ? "Cmd+Shift+H" : "Alt+Shift+H";
+  const altShiftSpace = IS_MACOS ? "Cmd+Shift+Space" : "Alt+Shift+Space";
+
+  const options = [
+    {
+      value: "shift+shift" as HotkeyOption,
+      label: "Shift, Shift (double tap)",
+    },
+    {
+      value: "alt+shift+h" as HotkeyOption,
+      label: `${altShiftH}`,
+    },
+    {
+      value: "alt+shift+space" as HotkeyOption,
+      label: `${altShiftSpace}`,
+    },
+    {
+      value: "disabled" as HotkeyOption,
+      label: "<disabled>",
+    },
+  ];
+
+  return (
+    <Select
+      value={value ?? "shift+shift"}
+      onChange={onChange}
+      options={options}
+      placeholder="Select hotkey..."
+      popupMatchSelectWidth={false}
+      {...props}
+    />
+  );
+}

src/packages/frontend/account/hotkey-selector.tsx

@@ -26,6 +26,9 @@ export function useAppContextProvider(): AppState {
 
   const [narrow, setNarrow] = useState<boolean>(isNarrow());
 
+  const [blockShiftShiftHotkey, setBlockShiftShiftHotkey] =
+    useState<boolean>(false);
+
   function update() {
     setNarrow(isNarrow());
     if (window.innerWidth != pageWidthPx) {
@@ -74,6 +77,8 @@ export function useAppContextProvider(): AppState {
     pageWidthPx,
     pageStyle,
     showActBarLabels,
+    blockShiftShiftHotkey,
+    setBlockShiftShiftHotkey,
   };
 }