Keyboard Shortcut Pattern

.changeset/rude-heads-report.md

@@ -0,0 +1,5 @@
+---
+"@salt-ds/lab": minor
+---
+
+KS pattern - Added KS pattern and KeyboardKey component.

package.json

@@ -85,6 +85,7 @@
     "react": "^18.3.1",
     "react-docgen-typescript": "2.4.0",
     "react-dom": "^18.3.1",
+    "react-hotkeys-hook": "^5.1.0",
     "react-resizable-panels": "^3.0.0",
     "react-router": "^7.6.3",
     "storybook": "^9.0.4",

packages/core/stories/patterns/keyboard-shortcuts/keyboard-shortcuts.stories.css

@@ -0,0 +1,7 @@
+.keyboardShortcuts-description {
+  padding: var(--salt-spacing-25) 0;
+}
+
+.keyboardShortcuts-actions-title {
+  font-weight: var(--salt-text-heading-fontWeight);
+}

packages/core/stories/patterns/keyboard-shortcuts/keyboard-shortcuts.stories.tsx

@@ -0,0 +1,281 @@
+import {
+  Button,
+  ComboBox,
+  Dialog,
+  DialogContent,
+  FlexLayout,
+  Label,
+  StackLayout,
+  Switch,
+  Text,
+} from "@salt-ds/core";
+import { FilterIcon } from "@salt-ds/icons";
+import { KeyboardKey, Table, TBody, TD, TH, THead, TR } from "@salt-ds/lab";
+import type { Meta } from "@storybook/react-vite";
+import React, { type ChangeEvent, type SyntheticEvent, useState } from "react";
+import { HotkeysProvider, useHotkeys } from "react-hotkeys-hook";
+import "./keyboard-shortcuts.stories.css";
+
+export default {
+  title: "Patterns/Keyboard Shortcuts",
+} as Meta;
+
+// Keyboard shortcut data type
+type KeyboardShortcut = {
+  label: string;
+  shortcut: string[][];
+  connector: string;
+  action: () => void;
+  description?: string;
+};
+
+const keyboardShortcuts: KeyboardShortcut[] = [
+  {
+    label: "Open command palette",
+    shortcut: [["meta", "option", "p"]],
+    connector: "+",
+    action: () => alert("Open command palette triggered!"),
+  },
+  {
+    label: "Next",
+    shortcut: [["meta", "shift", "e"]],
+    connector: "+",
+    action: () => alert("Next triggered!"),
+  },
+  {
+    label: "Previous",
+    shortcut: [["meta", "e"]],
+    connector: "+",
+    action: () => alert("Previous triggered!"),
+  },
+  {
+    label: "Duplicate ticket",
+    description: "Make a copy of your ticket",
+    shortcut: [["meta", "d"]],
+    connector: "+",
+    action: () => alert("Duplicate ticket triggered!"),
+  },
+  {
+    label: "Set direction to buy",
+    shortcut: [["meta", "b"]],
+    connector: "+",
+    action: () => alert("Set direction to buy triggered!"),
+  },
+  {
+    label: "Set direction to sell",
+    shortcut: [["meta", "s"]],
+    connector: "+",
+    action: () => alert("Set direction to sell triggered!"),
+  },
+  {
+    label: "Bottom of list",
+    shortcut: [["meta", "end"]],
+    connector: "+",
+    action: () => alert("Bottom of list triggered!"),
+  },
+  {
+    label: "Top of list",
+    shortcut: [["meta", "home"]],
+    connector: "+",
+    action: () => alert("Top of list triggered!"),
+  },
+  {
+    label: "Test",
+    shortcut: [
+      ["meta", "u"], // Cmd+T
+      ["meta", "y"], // Cmd+Y
+    ],
+    connector: "+",
+    action: () => alert("Test shortcut triggered!"),
+    description: "Trigger test action with Cmd+U or Cmd+Y",
+  },
+];
+
+// Utility: highlight search match
+function highlightMatch(text: string, query: string): React.ReactNode {
+  if (!query) return text;
+  const regex = new RegExp(`(${query})`, "gi");
+  return text
+    .split(regex)
+    .map((part, i) =>
+      part.toLowerCase() === query.toLowerCase() ? (
+        <strong key={i}>{part}</strong>
+      ) : (
+        part
+      ),
+    );
+}
+
+function displayKeyName(key: string) {
+  if (key === "meta") return "ctrl";
+  return key;
+}
+
+// Table row for a shortcut
+const ShortcutRow: React.FC<{ shortcut: KeyboardShortcut; filter: string }> = ({
+  shortcut,
+  filter,
+}) => (
+  <TR>
+    <TD>
+      <StackLayout gap={0.5}>
+        <Text>{highlightMatch(shortcut.label, filter)}</Text>
+        {shortcut.description && (
+          <Label color="secondary">{shortcut.description}</Label>
+        )}
+      </StackLayout>
+    </TD>
+    <TD>
+      <StackLayout gap={0.5}>
+        {shortcut.shortcut.map((comboArr, comboIdx) => (
+          <FlexLayout
+            align="center"
+            gap={0.5}
+            key={comboArr.join("-") + comboIdx}
+          >
+            {comboArr.map((keyName, idx) => (
+              <React.Fragment key={keyName + idx}>
+                <KeyboardKey aria-label={displayKeyName(keyName)}>
+                  {displayKeyName(keyName)}
+                </KeyboardKey>
+                {idx < comboArr.length - 1 && <Text>{shortcut.connector}</Text>}
+              </React.Fragment>
+            ))}
+          </FlexLayout>
+        ))}
+      </StackLayout>
+    </TD>
+  </TR>
+);
+
+// Register all hotkeys when enabled
+const RegisterShortcuts: React.FC<{ enabled: boolean }> = ({ enabled }) => {
+  keyboardShortcuts.forEach((shortcut) => {
+    shortcut.shortcut.forEach((comboArr) => {
+      const combo = comboArr.join("+");
+      useHotkeys(
+        combo,
+        (event) => {
+          event.preventDefault();
+          if (enabled) shortcut.action();
+        },
+        { enabled },
+      );
+    });
+  });
+  return null;
+};
+
+const KeyboardShortcuts: React.FC = () => {
+  const [open, setOpen] = useState(false);
+  const [shortcutsEnabled, setShortcutsEnabled] = useState(true);
+  const [filter, setFilter] = useState("");
+
+  useHotkeys(
+    "meta+shift+k", // To open the keyboard shortcut key panel
+    (event) => {
+      event.preventDefault();
+      setOpen(true);
+    },
+    { enabled: shortcutsEnabled },
+  );
+
+  const filteredShortcuts = keyboardShortcuts.filter((s) =>
+    s.label.toLowerCase().includes(filter.trim().toLowerCase()),
+  );
+
+  // Handlers
+  const handleDialogOpen = () => setOpen(true);
+  const handleDialogChange = (value: boolean) => setOpen(value);
+  const handleSwitchChange = (event: ChangeEvent<HTMLInputElement>) =>
+    setShortcutsEnabled(event.target.checked);
+  const handleFilterChange = (event: ChangeEvent<HTMLInputElement>) =>
+    setFilter(event.target.value);
+  const handleFilterSelectionChange = (
+    _: SyntheticEvent,
+    newSelected: string[],
+  ) => setFilter(newSelected.length === 1 ? newSelected[0] : "");
+
+  return (
+    <HotkeysProvider>
+      {/* Register all shortcuts, only when enabled */}
+      <RegisterShortcuts enabled={shortcutsEnabled} />
+      <StackLayout gap={1}>
+        <Button data-testid="dialog-button" onClick={handleDialogOpen}>
+          Keyboard shortcuts panel
+        </Button>
+        <FlexLayout align="center" gap={1}>
+          <Text>hit </Text>
+          <FlexLayout align="center" gap={0}>
+            <KeyboardKey>ctrl</KeyboardKey>+<KeyboardKey>shift</KeyboardKey>+
+            <KeyboardKey>K</KeyboardKey>
+          </FlexLayout>
+          <Text>to open the keyboard shortcuts panel </Text>
+        </FlexLayout>
+      </StackLayout>
+      <Dialog
+        open={open}
+        onOpenChange={handleDialogChange}
+        id="keyboard-shortcuts-dialog"
+        size="medium"
+      >
+        <DialogContent>
+          <StackLayout gap={3}>
+            <FlexLayout gap={1}>
+              <Switch
+                checked={shortcutsEnabled}
+                onChange={handleSwitchChange}
+              />
+              <FlexLayout className="keyboardShortcuts-description">
+                <Text>Turn on keyboard shortcuts</Text>
+              </FlexLayout>
+            </FlexLayout>
+            {shortcutsEnabled && (
+              <StackLayout gap={1}>
+                <Text className="keyboardShortcuts-actions-title" styleAs="h3">
+                  Actions
+                </Text>
+                <StackLayout gap={filteredShortcuts.length ? 3 : 0.75}>
+                  <ComboBox
+                    onChange={handleFilterChange}
+                    onSelectionChange={handleFilterSelectionChange}
+                    value={filter}
+                    bordered
+                    variant="secondary"
+                    placeholder="Filter actions"
+                    startAdornment={<FilterIcon color="secondary" />}
+                  />
+                  {filteredShortcuts.length ? (
+                    <StackLayout style={{ overflow: "auto" }}>
+                      <Table>
+                        <THead>
+                          <TR>
+                            <TH>Action</TH>
+                            <TH>Key combination</TH>
+                          </TR>
+                        </THead>
+                        <TBody>
+                          {filteredShortcuts.map((shortcut, idx) => (
+                            <ShortcutRow
+                              key={shortcut.label + idx}
+                              shortcut={shortcut}
+                              filter={filter}
+                            />
+                          ))}
+                        </TBody>
+                      </Table>
+                    </StackLayout>
+                  ) : (
+                    <Text color="secondary">No actions found</Text>
+                  )}
+                </StackLayout>
+              </StackLayout>
+            )}
+          </StackLayout>
+        </DialogContent>
+      </Dialog>
+    </HotkeysProvider>
+  );
+};
+
+export const WithKeyboardShortcutExample = KeyboardShortcuts.bind({});

packages/lab/src/index.ts

@@ -33,6 +33,7 @@ export {
   type InputLegacyProps as InputProps,
   StaticInputAdornment,
 } from "./input-legacy";
+export * from "./keyboard-key";
 export * from "./layer-layout";
 export * from "./list";
 export type {

packages/lab/src/keyboard-key/KeyboardKey.css

@@ -0,0 +1,16 @@
+.saltKeyboardKey {
+  display: flex;
+  --saltText-fontFamily: var(--salt-text-code-fontFamily);
+  width: fit-content;
+  border-radius: var(--salt-palette-corner-weaker);
+  border: var(--salt-size-fixed-100) solid var(--salt-container-primary-borderColor);
+  background: var(--salt-container-primary-background);
+  box-shadow: 0 var(--salt-size-fixed-100) 0 0 var(--salt-container-primary-borderColor);
+  min-height: calc(var(--salt-size-base) - var(--salt-spacing-100));
+  align-items: center;
+  padding: 0 var(--salt-spacing-50);
+}
+
+.saltKeyboardKey .saltText {
+  width: fit-content;
+}

packages/lab/src/keyboard-key/KeyboardKey.tsx

@@ -0,0 +1,31 @@
+import { makePrefixer, Text } from "@salt-ds/core";
+import { useComponentCssInjection } from "@salt-ds/styles";
+import { useWindow } from "@salt-ds/window";
+import { clsx } from "clsx";
+import { forwardRef, type HTMLAttributes, useEffect, useState } from "react";
+import { useIsViewportLargerThanBreakpoint } from "../utils";
+
+import keyboardKeyCss from "./KeyboardKey.css";
+
+export interface KeyboardKeyProps extends HTMLAttributes<HTMLElement> {}
+
+const withBaseName = makePrefixer("saltKeyboardKey");
+
+export const KeyboardKey = forwardRef<HTMLDivElement, KeyboardKeyProps>(
+  function KeyboardKey(props, ref) {
+    const { children, className, ...rest } = props;
+
+    const targetWindow = useWindow();
+    useComponentCssInjection({
+      testId: "salt-keyboard-key",
+      css: keyboardKeyCss,
+      window: targetWindow,
+    });
+
+    return (
+      <kbd ref={ref} className={clsx(withBaseName(), className, {})} {...props}>
+        <Text>{children}</Text>
+      </kbd>
+    );
+  },
+);

packages/lab/src/keyboard-key/index.ts

@@ -0,0 +1 @@
+export * from "./KeyboardKey";

yarn.lock

@@ -3929,6 +3929,7 @@ __metadata:
     react: "npm:^18.3.1"
     react-docgen-typescript: "npm:2.4.0"
     react-dom: "npm:^18.3.1"
+    react-hotkeys-hook: "npm:^5.1.0"
     react-resizable-panels: "npm:^3.0.0"
     react-router: "npm:^7.6.3"
     rollup: "npm:^4.24.2"
@@ -14706,6 +14707,16 @@ __metadata:
   languageName: node
   linkType: hard
 
+"react-hotkeys-hook@npm:^5.1.0":
+  version: 5.1.0
+  resolution: "react-hotkeys-hook@npm:5.1.0"
+  peerDependencies:
+    react: ">=16.8.0"
+    react-dom: ">=16.8.0"
+  checksum: 10/e912c0178fbfb04b841007aa3fc50cb326082346f860d3b92a22ff71516dfd487c6f60c0474d9609b982ad15e6b4741c35ca2b38adfeb133789d43ff6b0029c6
+  languageName: node
+  linkType: hard
+
 "react-immutable-proptypes@npm:2.2.0":
   version: 2.2.0
   resolution: "react-immutable-proptypes@npm:2.2.0"