feat: Keyboard Shortcuts System

.storybook/preview.js

@@ -9,6 +9,7 @@ import getStore from '../src/bundles/index.js'
 import i18n from '../src/i18n.js'
 import DndBackend from '../src/lib/dnd-backend.js'
 import { HeliaProvider, ExploreProvider } from 'ipld-explorer-components/providers'
+import { ShortcutsProvider } from '../src/contexts/ShortcutsContext.js'
 import { ContextBridgeProvider } from '../src/helpers/context-bridge'
 
 /**
@@ -23,7 +24,9 @@ const baseAnnotations = {
             <DndProvider backend={DndBackend}>
               <HeliaProvider>
                 <ExploreProvider>
-                  <Story />
+                  <ShortcutsProvider>
+                      <Story />
+                  </ShortcutsProvider>
                 </ExploreProvider>
               </HeliaProvider>
             </DndProvider>

public/locales/en/app.json

@@ -105,5 +105,13 @@
     "skip": "Skip",
     "tooltip": "Click this button any time for a guided tour on the current page."
   },
+  "shortcutModal": {
+    "title": "Keyboard Shortcuts",
+    "description": "The following keyboard shortcuts are available in the Files section:",
+    "showShortcuts": "Show keyboard shortcuts",
+    "general": "General",
+    "tourHelp": "Show tour help",
+    "ipfsPath": "Enter QmHash or CID"
+  },
   "startTourHelper": "Start tour"
 }

public/locales/en/files.json

@@ -46,28 +46,6 @@
     "checkboxRemoveLocalPin": "Also remove local pin (recommended)",
     "checkboxUnpinFromServices": "Unpin from all pinning services"
   },
-  "shortcutModal": {
-    "title": "Keyboard Shortcuts",
-    "description": "The following keyboard shortcuts are available in the Files section:",
-    "navigation": "Navigation",
-    "selection": "Selection",
-    "actions": "Actions",
-    "other": "Other",
-    "moveDown": "Move down",
-    "moveUp": "Move up",
-    "moveLeft": "Move left",
-    "moveRight": "Move right",
-    "navigate": "Navigate to selected item",
-    "rename": "Rename selected item",
-    "delete": "Delete selected item(s)",
-    "toggleSelection": "Toggle selection",
-    "selectAll": "Select all items",
-    "deselectAll": "Deselect all items",
-    "copy": "Copy selected item(s)",
-    "paste": "Paste item(s)",
-    "cut": "Cut selected item(s)",
-    "showShortcuts": "Show keyboard shortcuts"
-  },
   "pinningModal": {
     "title": "Select where you would like to pin these items.",
     "complianceLabel": "🔍 Check pinning services' compliance",
@@ -191,6 +169,25 @@
   "noPinsInProgress": "All done, no remote pins in progress.",
   "remotePinningInProgress": "Remote pinning in progress:",
   "selectAllEntries": "Select all entries",
+  "shortcutModal": {
+    "navigation": "Navigation",
+    "selection": "Selection",
+    "actions": "Actions",
+    "other": "Other",
+    "moveDown": "Move down",
+    "moveUp": "Move up",
+    "moveLeft": "Move left",
+    "moveRight": "Move right",
+    "navigate": "Navigate to selected item",
+    "rename": "Rename selected item",
+    "delete": "Delete selected item(s)",
+    "toggleSelection": "Toggle selection",
+    "selectAll": "Select all items",
+    "deselectAll": "Deselect all items",
+    "copy": "Copy selected item(s)",
+    "paste": "Paste item(s)",
+    "cut": "Cut selected item(s)"
+  },
   "previewNotFound": {
     "title": "IPFS can't find this item",
     "helpTitle": "These are common troubleshooting steps might help:",

public/locales/en/peers.json

@@ -3,6 +3,7 @@
   "localNetwork": "Local Network",
   "nearby": "nearby",
   "protocols": "Open streams",
+  "filterPeers": "Filter peers",
   "agentVersion": "Agent Version",
   "addConnection": "Add connection",
   "insertPeerAddress": "Insert the peer address you want to connect to.",

src/components/notify/Toast.js

@@ -1,5 +1,5 @@
 import React from 'react'
-import CancelIcon from '../../icons/GlyphSmallCancel.js'
+import CancelIcon from '../../icons/GlyphSmallCancel'
 
 const Toast = ({ error, children, onDismiss }) => {
   const bg = error ? 'bg-yellow' : 'bg-green'

src/components/overlay/overlay.tsx

@@ -4,29 +4,32 @@ import { Modal } from 'react-overlays'
 type ModalProps = React.ComponentProps<typeof Modal>
 
 export interface OverlayProps extends Omit<ModalProps, 'renderBackdrop' | 'onHide'> {
+  children: React.ReactNode
   show: boolean
   onLeave: () => void
   hidden: boolean
 }
 
 const Overlay: React.FC<OverlayProps> = ({ children, show, onLeave, className = '', hidden, ...props }) => {
-  const renderBackdrop: React.FC<React.HTMLAttributes<HTMLDivElement>> = (props) => (
+  const renderBackdrop = (props: React.HTMLAttributes<HTMLDivElement>) => (
     <div className='fixed top-0 left-0 right-0 bottom-0 bg-black o-50' hidden={hidden} {...props} />
   )
 
   return (
     // Note: react-overlays Modal manages its own portal and positioning.
     // The Modal child component uses fixed positioning to center itself.
     // onHide handles both backdrop clicks and escape key presses.
+    // @ts-ignore - react-overlays(children) is not typed
     <Modal
       {...props}
       show={show}
       backdrop={true}
       className={`${className} z-max`}
       renderBackdrop={renderBackdrop}
-      onHide={onLeave}>
-      {children}
-    </Modal>
+      onHide={onLeave}
+      >
+       {children}
+      </Modal>
   )
 }
 

src/components/tour/TourHelper.js

@@ -1,14 +1,27 @@
 import React from 'react'
 import { connect } from 'redux-bundler-react'
 import { withTranslation } from 'react-i18next'
+import { useShortcuts } from '../../contexts/ShortcutsContext'
 
 export const TourHelper = ({ doEnableTours, className = '', size = 23, t }) => {
   const handleClick = () => {
     doEnableTours()
   }
 
+  const tourHelperRef = React.useRef()
+
+  useShortcuts([{
+    id: 'tour-help',
+    keys: ['Shift', 'H'],
+    label: t('app:shortcutModal.tourHelp'),
+    action: () => {
+      tourHelperRef.current?.click?.()
+    },
+    group: t('app:shortcutModal.general')
+  }])
+
   return (
-    <button className={`dib mr1 ml4-m pointer ${className}`} onClick={handleClick} aria-label={ t('startTourHelper')}>
+    <button id='tour-helper' ref={tourHelperRef} className={`dib mr1 ml4-m pointer ${className}`} onClick={handleClick} aria-label={ t('startTourHelper')}>
       <svg className='fill-teal o-60 glow' viewBox='0 0 44 44' width={size} height={size} aria-hidden="true">
         <path d='m22,0c-12.2,0-22,9.8-22,22s9.8,22 22,22 22-9.8 22-22-9.8-22-22-22zm2,34c0,0.6-0.4,1-1,1h-2c-0.6,0-1-0.4-1-1v-2c0-0.6 0.4-1 1-1h2c0.6,0 1,0.4 1,1v2zm2.7-8.9c-1.4,1.2-2.4,2-2.7,3.1-0.1,0.5-0.5,0.8-1,0.8h-2c-0.6,0-1.1-0.5-1-1.1 0.4-2.9 2.5-4.5 4.2-5.9 1.8-1.4 2.8-2.3 2.8-4 0-2.8-2.2-5-5-5s-5,2.2-5,5c0,0.2 0,0.4 0,0.6 0.1,0.5-0.2,1-0.7,1.1l-1.9,.6c-0.6,0.2-1.2-0.2-1.3-0.8-0.1-0.5-0.1-1-0.1-1.5 0-5 4-9 9-9s9,4 9,9c0,3.7-2.4,5.6-4.3,7.1z' />
       </svg>

src/contexts/ShortcutsContext.tsx

@@ -0,0 +1,196 @@
+import React, { createContext, useContext, useCallback, useEffect, useRef, useMemo } from 'react'
+import ShortcutModal from '../files/modals/shortcut-modal/shortcut-modal'
+import Overlay from '../components/overlay/overlay'
+import { t } from 'i18next'
+
+interface Shortcut {
+  id: string
+  keys: string[]
+  label: string
+  hidden?: boolean
+  action: () => void
+  group?: string
+  ref?: React.RefObject<HTMLElement | null>
+}
+
+interface ShortcutsContextType {
+  shortcuts: Shortcut[]
+  registerShortcuts: (shortcuts: Omit<Shortcut, 'id'>[]) => string[]
+  unregisterShortcuts: (ids: string[]) => void
+  updateShortcuts: (newShortcuts: Shortcut[]) => void
+}
+
+const ShortcutsContext = createContext<ShortcutsContextType | null>(null)
+
+export const ShortcutsProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  const [showShortcuts, setShowShortcuts] = React.useState(false)
+  const defaultShortcut: Shortcut[] = [
+    {
+      id: 'tour-help',
+      keys: ['Shift', 'H'],
+      label: t('app:shortcutModal.tourHelp'),
+      action: () => {
+        const tourHelper = document.getElementById('tour-helper')
+        if (tourHelper) {
+          tourHelper.click()
+        }
+      },
+      group: t('app:shortcutModal.general')
+    },
+    {
+      id: 'ipfs-path',
+      keys: ['/'],
+      label: t('app:shortcutModal.ipfsPath'),
+      action: () => {
+        const ipfsPath = document.getElementById('ipfs-path')
+        if (ipfsPath) {
+          ipfsPath.focus()
+        }
+      },
+      group: t('app:shortcutModal.general')
+    },
+    {
+      id: 'show-shortcuts',
+      keys: ['Shift', '?'],
+      label: t('app:shortcutModal.showShortcuts'),
+      action: () => {
+        setShowShortcuts(prev => !prev)
+      },
+      group: t('app:shortcutModal.general')
+    }
+  ]
+  const [shortcuts, setShortcuts] = React.useState<Shortcut[]>(defaultShortcut)
+  const registeredShortcutsRef = useRef<Map<string, Shortcut>>(new Map())
+
+  const closeModal = () => {
+    setShowShortcuts(false)
+  }
+
+  const isPressed = (keys: string[], e: KeyboardEvent) => {
+    return keys.every(key => {
+      switch (key.toLowerCase()) {
+        case 'shift':
+          return e.shiftKey
+        case 'ctrl':
+          return e.ctrlKey
+        case 'alt':
+          return e.altKey
+        case 'meta':
+          return e.metaKey
+        case 'space':
+          return e.key === ' '
+        default:
+          return e.key === key
+      }
+    })
+  }
+
+  const handleKeyDown = useCallback((e: KeyboardEvent) => {
+    const target = e.target as HTMLElement
+    if ((target.tagName === 'INPUT' ||
+         target.tagName === 'TEXTAREA' ||
+         target.tagName === 'SELECT') &&
+        target.closest('.modal')) return
+
+    if ((document.activeElement?.tagName === 'INPUT' &&
+         (document.activeElement as HTMLInputElement).type !== 'checkbox') ||
+        document.activeElement?.tagName === 'TEXTAREA' ||
+        (document.activeElement as HTMLElement)?.isContentEditable) {
+      return
+    }
+
+    shortcuts.forEach(shortcut => {
+      // Check if shortcut should be scoped to a specific ref
+      if (shortcut.ref) {
+        const refElement = shortcut.ref.current
+        if (!refElement || !refElement.contains(target)) {
+          return // Skip this shortcut if target is not within the ref scope
+        }
+      }
+
+      if (isPressed(shortcut.keys, e)) {
+        e.preventDefault()
+        if (shortcut.id !== 'show-shortcuts') {
+          closeModal()
+        }
+        shortcut.action()
+      }
+    })
+  }, [shortcuts])
+
+  useEffect(() => {
+    document.addEventListener('keydown', handleKeyDown)
+    return () => document.removeEventListener('keydown', handleKeyDown)
+  }, [handleKeyDown])
+
+  const registerShortcuts = useCallback((newShortcuts: Omit<Shortcut, 'id'>[]) => {
+    const ids: string[] = []
+    const shortcutsToAdd: Shortcut[] = []
+
+    newShortcuts.forEach((shortcut, index) => {
+      const id = `${shortcut.group || 'custom'}-${Date.now()}-${index}`
+      ids.push(id)
+      const shortcutWithId = { ...shortcut, id }
+      shortcutsToAdd.push(shortcutWithId)
+      registeredShortcutsRef.current.set(id, shortcutWithId)
+    })
+
+    setShortcuts(prev => [...prev, ...shortcutsToAdd])
+    return ids
+  }, [])
+
+  const unregisterShortcuts = useCallback((ids: string[]) => {
+    ids.forEach(id => {
+      registeredShortcutsRef.current.delete(id)
+    })
+
+    setShortcuts(prev => prev.filter(shortcut => !ids.includes(shortcut.id)))
+  }, [])
+
+  return (
+    <ShortcutsContext.Provider value={{
+      shortcuts,
+      registerShortcuts,
+      unregisterShortcuts,
+      updateShortcuts: useCallback((newShortcuts: Shortcut[]) => {
+        setShortcuts([...defaultShortcut, ...newShortcuts])
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+      }, [])
+    }}>
+      {children}
+      <div>
+        <Overlay show={showShortcuts} hidden={!showShortcuts} className='' onLeave={closeModal}>
+          <ShortcutModal
+            className='outline-0'
+            onLeave={closeModal} />
+        </Overlay>
+      </div>
+    </ShortcutsContext.Provider>
+  )
+}
+
+export const useShortcuts = (shortcuts: Omit<Shortcut, 'id'>[], ref?: React.RefObject<HTMLElement | null>) => {
+  const context = useContext(ShortcutsContext)
+  if (!context) {
+    throw new Error('Shortcuts hook is out of context')
+  }
+
+  const memoizedShortcuts = useMemo(() =>
+    shortcuts.map(shortcut => ({ ...shortcut, ref })),
+  [shortcuts, ref]
+  )
+
+  useEffect(() => {
+    if (memoizedShortcuts.length > 0) {
+      const ids = context.registerShortcuts(memoizedShortcuts)
+
+      return () => {
+        context.unregisterShortcuts(ids)
+      }
+    }
+    return undefined
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  return context.shortcuts
+}