Skip to content

Email for professionals and teams

feat(shortcuts): add keyboard navigation and Command Palette (Cmd+K)

ivi503297f0d4f8
diff --git a/src/app/(dashboard)/layout.tsx b/src/app/(dashboard)/layout.tsx
index 24f82b8..d1ea398 100644
--- a/src/app/(dashboard)/layout.tsx
+++ b/src/app/(dashboard)/layout.tsx
@@ -12,6 +12,7 @@ import { MailboxSelector } from "@/components/mailbox-selector";
import { LicenseIndicator } from "@/components/license-indicator";
import { DashboardNav } from "@/components/dashboard-nav";
import { SidebarProvider } from "@/components/sidebar-state";
+import { ShortcutsProvider } from "@/components/shortcuts";
export default function DashboardLayout({
children,
@@ -21,34 +22,37 @@ export default function DashboardLayout({
return (
<AuthGuard>
<SidebarProvider>
- <MailboxProvider>
- <ComposeProvider>
- <MailSearchProvider>
- <div className="grid h-dvh grid-cols-[var(--sidebar-width)_minmax(0,1fr)] overflow-hidden bg-[#f6f8fc] transition-[grid-template-columns] duration-200">
- <aside className="min-h-0 overflow-y-auto overscroll-contain px-3 py-4 scrollbar-gutter-stable">
- <DashboardNav />
- </aside>
- <div className="flex min-h-0 min-w-0 flex-col">
- <header className="flex h-16 w-full shrink-0 items-center gap-4 pr-4 text-sm">
- <MailSearchInput />
- <Link
- href="/settings/account"
- className="flex h-10 w-10 items-center justify-center rounded-full text-neutral-600 hover:bg-neutral-200"
- >
- <HelpCircle className="h-5 w-5" />
- </Link>
- <LicenseIndicator />
- <MailboxSelector />
- </header>
- <main className="min-h-0 flex-1 overflow-y-auto overscroll-contain rounded-tl-3xl bg-white scrollbar-gutter-stable">
- {children}
- </main>
- </div>
- <FloatingComposer />
- </div>
- </MailSearchProvider>
- </ComposeProvider>
- </MailboxProvider>
+ <MailboxProvider>
+ <ComposeProvider>
+ <MailSearchProvider>
+ <ShortcutsProvider>
+ <div className="grid h-dvh grid-cols-[var(--sidebar-width)_minmax(0,1fr)] overflow-hidden bg-[#f6f8fc] transition-[grid-template-columns] duration-200">
+ <aside className="min-h-0 overflow-y-auto overscroll-contain px-3 py-4 scrollbar-gutter-stable">
+ <DashboardNav />
+ </aside>
+ <div className="flex min-h-0 min-w-0 flex-col">
+ <header className="flex h-16 w-full shrink-0 items-center gap-3 pr-4 text-sm">
+ <MailSearchInput />
+ <Link
+ href="/settings/account"
+ className="flex h-10 w-10 items-center justify-center rounded-full text-neutral-600 hover:bg-neutral-200"
+ title="Account Settings"
+ >
+ <HelpCircle className="h-5 w-5" />
+ </Link>
+ <LicenseIndicator />
+ <MailboxSelector />
+ </header>
+ <main className="min-h-0 flex-1 overflow-y-auto overscroll-contain rounded-tl-3xl bg-white scrollbar-gutter-stable">
+ {children}
+ </main>
+ </div>
+ <FloatingComposer />
+ </div>
+ </ShortcutsProvider>
+ </MailSearchProvider>
+ </ComposeProvider>
+ </MailboxProvider>
</SidebarProvider>
</AuthGuard>
);
diff --git a/src/components/mail-search/mail-search-input.tsx b/src/components/mail-search/mail-search-input.tsx
index 44a03b1..a3a7173 100644
--- a/src/components/mail-search/mail-search-input.tsx
+++ b/src/components/mail-search/mail-search-input.tsx
@@ -3,20 +3,22 @@
import { Search, X } from "lucide-react";
import { Input } from "@/components/ui/input";
import { useMailSearch } from "./mail-search-context";
+import { useShortcuts } from "@/components/shortcuts";
export function MailSearchInput() {
const { query, setQuery } = useMailSearch();
+ const { openCommandPalette } = useShortcuts();
return (
- <div className="flex h-12 flex-1 items-center gap-3 rounded-full bg-[#eaf1fb] px-4 text-neutral-600">
+ <div className="flex h-12 flex-1 items-center gap-2.5 rounded-full bg-[#eaf1fb] px-4 text-neutral-600 focus-within:ring-2 focus-within:ring-blue-500/30 transition-all">
<Search className="h-5 w-5 shrink-0" />
<Input
value={query}
onChange={(event) => setQuery(event.target.value)}
- placeholder='Search mail'
+ placeholder="Search mail (press / to focus)"
className="h-full min-w-0 flex-1 bg-transparent text-[15px] text-neutral-800 outline-none! shadow-none! border-none! placeholder:text-neutral-500"
/>
- {query && (
+ {query ? (
<button
type="button"
onClick={() => setQuery("")}
@@ -25,6 +27,15 @@ export function MailSearchInput() {
>
<X className="h-4 w-4" />
</button>
+ ) : (
+ <button
+ type="button"
+ onClick={openCommandPalette}
+ className="hidden sm:flex items-center gap-1 px-2 py-0.5 text-xs font-medium text-neutral-500 bg-white/70 hover:bg-white border border-neutral-200/80 rounded-md shadow-2xs transition-colors"
+ title="Open Command Palette (⌘K)"
+ >
+ <span className="text-[11px] font-mono">⌘K</span>
+ </button>
)}
</div>
);
diff --git a/src/components/message-actions/message-actions.tsx b/src/components/message-actions/message-actions.tsx
index 75b535c..4e37385 100644
--- a/src/components/message-actions/message-actions.tsx
+++ b/src/components/message-actions/message-actions.tsx
@@ -1,9 +1,10 @@
"use client";
-import { createElement, useState } from "react";
+import { createElement, useState, useMemo } from "react";
import { useRouter } from "next/navigation";
import { Archive, Ban, BellOff, Forward, Mail, MailOpen, MoreVertical, Reply, ReplyAll, ShieldAlert, Trash2 } from "lucide-react";
import { useCompose } from "@/components/compose/compose-context";
+import { useHotkeys } from "@/components/shortcuts";
import { Button } from "@/components/ui/button";
import { Tooltip } from "@/components/ui/tooltip";
import type { BulkMessageAction } from "@/app/api/messages/bulk/types";
@@ -63,6 +64,58 @@ export function MessageActions({
}
}
+ const shortcuts = useMemo(
+ () => [
+ {
+ key: "e",
+ label: "Archive Message",
+ category: "Actions" as const,
+ action: () => {
+ if (status !== "archived") void runAction("archive");
+ },
+ },
+ {
+ key: "y",
+ label: "Archive Message",
+ category: "Actions" as const,
+ action: () => {
+ if (status !== "archived") void runAction("archive");
+ },
+ },
+ {
+ key: "#",
+ label: "Move to Trash",
+ category: "Actions" as const,
+ action: () => {
+ if (status !== "trash") void runAction("trash");
+ },
+ },
+ {
+ key: "r",
+ label: "Reply to Message",
+ category: "Composing" as const,
+ action: () => void handleReply("reply"),
+ },
+ {
+ key: "!",
+ label: "Report Spam",
+ category: "Actions" as const,
+ action: () => {
+ if (status !== "spam" && direction === "inbound") void runAction("spam");
+ },
+ },
+ {
+ key: "u",
+ label: "Back to List",
+ category: "Navigation" as const,
+ action: () => router.back(),
+ },
+ ],
+ [status, direction, runAction, router]
+ );
+
+ useHotkeys(shortcuts);
+
async function onUnsubscribe() {
setMoreOpen(false);
setError(null);
@@ -171,12 +224,12 @@ export function MessageActions({
<div className="flex items-center gap-3 text-neutral-600">
{error && <span className="text-xs text-red-600">{error}</span>}
<div className="flex items-center gap-2">
- <Tooltip label="Reply">
+ <Tooltip label="Reply (r)">
<Button
type="button"
variant="ghost"
size="sm"
- aria-label="Reply"
+ aria-label="Reply (r)"
disabled={disabled}
onClick={() => handleReply("reply")}
>
@@ -211,33 +264,33 @@ export function MessageActions({
</Button>
</Tooltip>
)}
- <Tooltip label="Archive">
+ <Tooltip label="Archive (e)">
<Button
variant="ghost"
size="sm"
- aria-label="Archive"
+ aria-label="Archive (e)"
disabled={disabled || status === "archived"}
onClick={() => runAction("archive")}
>
<Archive className="h-5 w-5" />
</Button>
</Tooltip>
- <Tooltip label="Report spam">
+ <Tooltip label="Report spam (!)">
<Button
variant="ghost"
size="sm"
- aria-label="Report spam"
+ aria-label="Report spam (!)"
disabled={disabled || status === "spam" || direction !== "inbound"}
onClick={() => runAction("spam")}
>
<ShieldAlert className="h-5 w-5" />
</Button>
</Tooltip>
- <Tooltip label="Delete">
+ <Tooltip label="Delete (#)">
<Button
variant="ghost"
size="sm"
- aria-label="Move to trash"
+ aria-label="Move to trash (#)"
disabled={disabled || status === "trash"}
onClick={() => runAction("trash")}
>
diff --git a/src/components/shortcuts/command-palette.tsx b/src/components/shortcuts/command-palette.tsx
new file mode 100644
index 0000000..5d05cde
--- /dev/null
+++ b/src/components/shortcuts/command-palette.tsx
@@ -0,0 +1,206 @@
+"use client";
+
+import React, { useState, useEffect, useRef, useMemo } from "react";
+import { Search, CornerDownLeft } from "lucide-react";
+import type { CommandItem } from "./types";
+
+interface CommandPaletteProps {
+ isOpen: boolean;
+ onClose: () => void;
+ commands: CommandItem[];
+}
+
+export function CommandPalette({
+ isOpen,
+ onClose,
+ commands,
+}: CommandPaletteProps) {
+ const [query, setQuery] = useState("");
+ const [selectedIndex, setSelectedIndex] = useState(0);
+ const inputRef = useRef<HTMLInputElement>(null);
+ const listRef = useRef<HTMLDivElement>(null);
+
+ useEffect(() => {
+ if (isOpen) {
+ setQuery("");
+ setSelectedIndex(0);
+ setTimeout(() => inputRef.current?.focus(), 50);
+ }
+ }, [isOpen]);
+
+ const filteredCommands = useMemo(() => {
+ if (!query.trim()) return commands;
+ const lowerQuery = query.toLowerCase();
+ return commands.filter((cmd) => {
+ const matchTitle = cmd.title.toLowerCase().includes(lowerQuery);
+ const matchSubtitle = cmd.subtitle?.toLowerCase().includes(lowerQuery);
+ const matchCategory = cmd.category.toLowerCase().includes(lowerQuery);
+ const matchKeywords = cmd.keywords?.some((k) =>
+ k.toLowerCase().includes(lowerQuery)
+ );
+ return matchTitle || matchSubtitle || matchCategory || matchKeywords;
+ });
+ }, [commands, query]);
+
+ useEffect(() => {
+ setSelectedIndex(0);
+ }, [filteredCommands]);
+
+ const handleKeyDown = (e: React.KeyboardEvent) => {
+ if (e.key === "ArrowDown") {
+ e.preventDefault();
+ setSelectedIndex((prev) => (prev + 1) % (filteredCommands.length || 1));
+ } else if (e.key === "ArrowUp") {
+ e.preventDefault();
+ setSelectedIndex(
+ (prev) => (prev - 1 + filteredCommands.length) % (filteredCommands.length || 1)
+ );
+ } else if (e.key === "Enter") {
+ e.preventDefault();
+ if (filteredCommands[selectedIndex]) {
+ filteredCommands[selectedIndex].perform();
+ onClose();
+ }
+ } else if (e.key === "Escape") {
+ e.preventDefault();
+ onClose();
+ }
+ };
+
+ if (!isOpen) return null;
+
+ const grouped = filteredCommands.reduce((acc, item) => {
+ if (!acc[item.category]) acc[item.category] = [];
+ acc[item.category].push(item);
+ return acc;
+ }, {} as Record<string, CommandItem[]>);
+
+ let flatIndex = 0;
+
+ return (
+ <div className="fixed inset-0 z-50 flex items-start justify-center pt-24 px-4 bg-neutral-900/40 backdrop-blur-xs animate-in fade-in duration-100">
+ <div
+ className="fixed inset-0"
+ onClick={onClose}
+ aria-hidden="true"
+ />
+ <div
+ className="relative w-full max-w-xl bg-white dark:bg-neutral-900 border border-neutral-200 dark:border-neutral-800 rounded-2xl shadow-2xl overflow-hidden flex flex-col z-10"
+ onKeyDown={handleKeyDown}
+ >
+ {/* Search header */}
+ <div className="flex items-center px-4 py-3.5 border-b border-neutral-100 dark:border-neutral-800 gap-3">
+ <Search className="w-5 h-5 text-neutral-400" />
+ <input
+ ref={inputRef}
+ type="text"
+ value={query}
+ onChange={(e) => setQuery(e.target.value)}
+ placeholder="Type a command or search actions..."
+ className="w-full bg-transparent text-neutral-900 dark:text-neutral-100 placeholder-neutral-400 text-[15px] focus:outline-none"
+ />
+ <kbd className="px-2 py-0.5 text-xs font-semibold text-neutral-400 bg-neutral-100 dark:bg-neutral-800 border border-neutral-200 dark:border-neutral-700 rounded-md shadow-xs">
+ ESC
+ </kbd>
+ </div>
+
+ {/* Results */}
+ <div
+ ref={listRef}
+ className="max-h-80 overflow-y-auto p-2"
+ >
+ {filteredCommands.length === 0 ? (
+ <div className="p-8 text-center text-sm text-neutral-400">
+ No matching commands found for &ldquo;{query}&rdquo;
+ </div>
+ ) : (
+ Object.entries(grouped).map(([category, items]) => (
+ <div key={category} className="mb-2 last:mb-0">
+ <div className="px-3 py-1 text-[11px] font-semibold uppercase tracking-wider text-neutral-400">
+ {category}
+ </div>
+ {items.map((item) => {
+ const isCurrent = flatIndex === selectedIndex;
+ const itemIndex = flatIndex;
+ flatIndex++;
+ const Icon = item.icon;
+
+ return (
+ <button
+ key={item.id}
+ type="button"
+ onClick={() => {
+ item.perform();
+ onClose();
+ }}
+ onMouseEnter={() => setSelectedIndex(itemIndex)}
+ className={`w-full text-left px-3 py-2.5 rounded-xl flex items-center justify-between transition-colors ${
+ isCurrent
+ ? "bg-blue-600 text-white"
+ : "text-neutral-800 dark:text-neutral-200 hover:bg-neutral-100 dark:hover:bg-neutral-800/70"
+ }`}
+ >
+ <div className="flex items-center gap-3 min-w-0">
+ {Icon && (
+ <Icon
+ className={`w-4 h-4 shrink-0 ${
+ isCurrent
+ ? "text-white"
+ : "text-neutral-500 dark:text-neutral-400"
+ }`}
+ />
+ )}
+ <div className="truncate">
+ <span className="text-sm font-medium">{item.title}</span>
+ {item.subtitle && (
+ <span
+ className={`ml-2 text-xs truncate ${
+ isCurrent
+ ? "text-blue-100"
+ : "text-neutral-400 dark:text-neutral-500"
+ }`}
+ >
+ {item.subtitle}
+ </span>
+ )}
+ </div>
+ </div>
+ {item.shortcut && (
+ <kbd
+ className={`text-xs px-2 py-0.5 rounded-md font-mono font-medium shrink-0 ${
+ isCurrent
+ ? "bg-blue-700 text-blue-100"
+ : "bg-neutral-100 dark:bg-neutral-800 text-neutral-500 dark:text-neutral-400 border border-neutral-200 dark:border-neutral-700"
+ }`}
+ >
+ {item.shortcut}
+ </kbd>
+ )}
+ </button>
+ );
+ })}
+ </div>
+ ))
+ )}
+ </div>
+
+ {/* Footer */}
+ <div className="px-4 py-2.5 bg-neutral-50 dark:bg-neutral-950/60 border-t border-neutral-100 dark:border-neutral-800 flex items-center justify-between text-xs text-neutral-400">
+ <div className="flex items-center gap-3">
+ <span>
+ <kbd className="px-1.5 py-0.5 bg-neutral-200 dark:bg-neutral-800 rounded mr-1 text-[10px]">
+ ↑↓
+ </kbd>
+ to navigate
+ </span>
+ <span className="flex items-center">
+ <CornerDownLeft className="w-3 h-3 mr-1 inline" />
+ to select
+ </span>
+ </div>
+ <span className="text-[11px]">Mailflare Actions</span>
+ </div>
+ </div>
+ </div>
+ );
+}
diff --git a/src/components/shortcuts/index.ts b/src/components/shortcuts/index.ts
new file mode 100644
index 0000000..bfab0b1
--- /dev/null
+++ b/src/components/shortcuts/index.ts
@@ -0,0 +1,5 @@
+export * from "./types";
+export * from "./use-hotkeys";
+export * from "./shortcuts-context";
+export * from "./command-palette";
+export * from "./shortcuts-help-dialog";
diff --git a/src/components/shortcuts/shortcuts-context.tsx b/src/components/shortcuts/shortcuts-context.tsx
new file mode 100644
index 0000000..0f2cf12
--- /dev/null
+++ b/src/components/shortcuts/shortcuts-context.tsx
@@ -0,0 +1,317 @@
+"use client";
+
+import React, { createContext, useContext, useState, useMemo } from "react";
+import { useRouter } from "next/navigation";
+import {
+ Inbox,
+ Star,
+ Clock,
+ Send,
+ FileText,
+ Archive,
+ ShieldAlert,
+ Trash2,
+ MailPlus,
+ Search,
+ Settings,
+ HelpCircle,
+} from "lucide-react";
+import { useCompose } from "@/components/compose/compose-context";
+import { useMailSearch } from "@/components/mail-search/mail-search-context";
+import type { ShortcutDefinition, CommandItem } from "./types";
+import { useHotkeys } from "./use-hotkeys";
+import { CommandPalette } from "./command-palette";
+import { ShortcutsHelpDialog } from "./shortcuts-help-dialog";
+
+interface ShortcutsContextValue {
+ openCommandPalette: () => void;
+ closeCommandPalette: () => void;
+ openHelpModal: () => void;
+ closeHelpModal: () => void;
+ registerShortcut: (shortcut: ShortcutDefinition) => void;
+ registerCommand: (command: CommandItem) => void;
+ shortcuts: ShortcutDefinition[];
+ commands: CommandItem[];
+}
+
+const ShortcutsContext = createContext<ShortcutsContextValue | null>(null);
+
+export function useShortcuts() {
+ const ctx = useContext(ShortcutsContext);
+ if (!ctx) {
+ throw new Error("useShortcuts must be used within a ShortcutsProvider");
+ }
+ return ctx;
+}
+
+export function ShortcutsProvider({
+ children,
+ extraShortcuts = [],
+ extraCommands = [],
+}: {
+ children: React.ReactNode;
+ extraShortcuts?: ShortcutDefinition[];
+ extraCommands?: CommandItem[];
+}) {
+ const router = useRouter();
+ const { openComposer } = useCompose();
+ const { setQuery } = useMailSearch();
+
+ const [isCommandPaletteOpen, setIsCommandPaletteOpen] = useState(false);
+ const [isHelpModalOpen, setIsHelpModalOpen] = useState(false);
+ const [customShortcuts, setCustomShortcuts] = useState<ShortcutDefinition[]>(extraShortcuts);
+ const [customCommands, setCustomCommands] = useState<CommandItem[]>(extraCommands);
+
+ const openCommandPalette = () => setIsCommandPaletteOpen(true);
+ const closeCommandPalette = () => setIsCommandPaletteOpen(false);
+ const openHelpModal = () => setIsHelpModalOpen(true);
+ const closeHelpModal = () => setIsHelpModalOpen(false);
+
+ const registerShortcut = (shortcut: ShortcutDefinition) => {
+ setCustomShortcuts((prev) => {
+ const idx = prev.findIndex((s) => s.key === shortcut.key);
+ if (idx >= 0) {
+ const next = [...prev];
+ next[idx] = shortcut;
+ return next;
+ }
+ return [...prev, shortcut];
+ });
+ };
+
+ const registerCommand = (command: CommandItem) => {
+ setCustomCommands((prev) => {
+ const idx = prev.findIndex((c) => c.id === command.id);
+ if (idx >= 0) {
+ const next = [...prev];
+ next[idx] = command;
+ return next;
+ }
+ return [...prev, command];
+ });
+ };
+
+ // Base navigation and global shortcuts
+ const baseShortcuts = useMemo<ShortcutDefinition[]>(() => {
+ return [
+ {
+ key: "k",
+ modifiers: ["meta", "ctrl"],
+ label: "Command Palette",
+ category: "General",
+ action: () => setIsCommandPaletteOpen((prev) => !prev),
+ },
+ {
+ key: "?",
+ label: "Shortcuts Cheat Sheet",
+ category: "General",
+ action: () => setIsHelpModalOpen((prev) => !prev),
+ },
+ {
+ key: "c",
+ label: "Compose Email",
+ category: "Composing",
+ action: () => openComposer(),
+ },
+ {
+ key: "/",
+ label: "Search Mail",
+ category: "Navigation",
+ action: () => {
+ const searchInput = document.querySelector<HTMLInputElement>(
+ 'input[placeholder*="Search"]'
+ );
+ if (searchInput) {
+ searchInput.focus();
+ searchInput.select();
+ }
+ },
+ },
+ {
+ key: "g i",
+ label: "Go to Inbox",
+ category: "Navigation",
+ action: () => router.push("/inbox"),
+ },
+ {
+ key: "g s",
+ label: "Go to Starred",
+ category: "Navigation",
+ action: () => router.push("/starred"),
+ },
+ {
+ key: "g z",
+ label: "Go to Snoozed",
+ category: "Navigation",
+ action: () => router.push("/snoozed"),
+ },
+ {
+ key: "g t",
+ label: "Go to Sent",
+ category: "Navigation",
+ action: () => router.push("/sent"),
+ },
+ {
+ key: "g d",
+ label: "Go to Drafts",
+ category: "Navigation",
+ action: () => router.push("/drafts"),
+ },
+ {
+ key: "g a",
+ label: "Go to Archived",
+ category: "Navigation",
+ action: () => router.push("/archived"),
+ },
+ {
+ key: "g !",
+ label: "Go to Spam",
+ category: "Navigation",
+ action: () => router.push("/spam"),
+ },
+ {
+ key: "g x",
+ label: "Go to Trash",
+ category: "Navigation",
+ action: () => router.push("/trash"),
+ },
+ {
+ key: "escape",
+ label: "Dismiss Modal / Clear Focus",
+ category: "General",
+ action: () => {
+ setIsCommandPaletteOpen(false);
+ setIsHelpModalOpen(false);
+ },
+ },
+ ...customShortcuts,
+ ];
+ }, [router, openComposer, customShortcuts]);
+
+ useHotkeys(baseShortcuts, { enabled: true });
+
+ // Base Command Palette actions
+ const allCommands = useMemo<CommandItem[]>(() => {
+ const builtins: CommandItem[] = [
+ {
+ id: "compose",
+ title: "Compose new message",
+ subtitle: "Open draft editor",
+ category: "Actions",
+ icon: MailPlus,
+ shortcut: "c",
+ perform: () => openComposer(),
+ },
+ {
+ id: "nav-inbox",
+ title: "Go to Inbox",
+ category: "Navigation",
+ icon: Inbox,
+ shortcut: "g i",
+ perform: () => router.push("/inbox"),
+ },
+ {
+ id: "nav-starred",
+ title: "Go to Starred",
+ category: "Navigation",
+ icon: Star,
+ shortcut: "g s",
+ perform: () => router.push("/starred"),
+ },
+ {
+ id: "nav-snoozed",
+ title: "Go to Snoozed",
+ category: "Navigation",
+ icon: Clock,
+ shortcut: "g z",
+ perform: () => router.push("/snoozed"),
+ },
+ {
+ id: "nav-sent",
+ title: "Go to Sent",
+ category: "Navigation",
+ icon: Send,
+ shortcut: "g t",
+ perform: () => router.push("/sent"),
+ },
+ {
+ id: "nav-drafts",
+ title: "Go to Drafts",
+ category: "Navigation",
+ icon: FileText,
+ shortcut: "g d",
+ perform: () => router.push("/drafts"),
+ },
+ {
+ id: "nav-archived",
+ title: "Go to Archived",
+ category: "Navigation",
+ icon: Archive,
+ shortcut: "g a",
+ perform: () => router.push("/archived"),
+ },
+ {
+ id: "nav-spam",
+ title: "Go to Spam",
+ category: "Navigation",
+ icon: ShieldAlert,
+ shortcut: "g !",
+ perform: () => router.push("/spam"),
+ },
+ {
+ id: "nav-trash",
+ title: "Go to Trash",
+ category: "Navigation",
+ icon: Trash2,
+ shortcut: "g x",
+ perform: () => router.push("/trash"),
+ },
+ {
+ id: "settings-account",
+ title: "Account Settings",
+ subtitle: "Profile, password & preferences",
+ category: "Settings",
+ icon: Settings,
+ perform: () => router.push("/settings/account"),
+ },
+ {
+ id: "show-help",
+ title: "Keyboard Shortcuts Cheat Sheet",
+ subtitle: "View all quick keys",
+ category: "General",
+ icon: HelpCircle,
+ shortcut: "?",
+ perform: () => setIsHelpModalOpen(true),
+ },
+ ];
+
+ return [...builtins, ...customCommands];
+ }, [router, openComposer, customCommands]);
+
+ return (
+ <ShortcutsContext.Provider
+ value={{
+ openCommandPalette,
+ closeCommandPalette,
+ openHelpModal,
+ closeHelpModal,
+ registerShortcut,
+ registerCommand,
+ shortcuts: baseShortcuts,
+ commands: allCommands,
+ }}
+ >
+ {children}
+ <CommandPalette
+ isOpen={isCommandPaletteOpen}
+ onClose={closeCommandPalette}
+ commands={allCommands}
+ />
+ <ShortcutsHelpDialog
+ isOpen={isHelpModalOpen}
+ onClose={closeHelpModal}
+ shortcuts={baseShortcuts}
+ />
+ </ShortcutsContext.Provider>
+ );
+}
diff --git a/src/components/shortcuts/shortcuts-help-dialog.tsx b/src/components/shortcuts/shortcuts-help-dialog.tsx
new file mode 100644
index 0000000..dd1b0da
--- /dev/null
+++ b/src/components/shortcuts/shortcuts-help-dialog.tsx
@@ -0,0 +1,118 @@
+"use client";
+
+import React from "react";
+import { X, Keyboard } from "lucide-react";
+import type { ShortcutDefinition } from "./types";
+
+interface ShortcutsHelpDialogProps {
+ isOpen: boolean;
+ onClose: () => void;
+ shortcuts: ShortcutDefinition[];
+}
+
+export function ShortcutsHelpDialog({
+ isOpen,
+ onClose,
+ shortcuts,
+}: ShortcutsHelpDialogProps) {
+ if (!isOpen) return null;
+
+ const grouped = shortcuts.reduce((acc, item) => {
+ if (!acc[item.category]) acc[item.category] = [];
+ acc[item.category].push(item);
+ return acc;
+ }, {} as Record<string, ShortcutDefinition[]>);
+
+ const formatKey = (shortcut: ShortcutDefinition) => {
+ const parts: string[] = [];
+ if (shortcut.modifiers) {
+ shortcut.modifiers.forEach((m) => {
+ if (m === "ctrl") parts.push("Ctrl");
+ if (m === "meta") parts.push("⌘");
+ if (m === "alt") parts.push("Alt");
+ if (m === "shift") parts.push("Shift");
+ });
+ }
+ parts.push(shortcut.key.toUpperCase());
+ return parts.join(" + ");
+ };
+
+ return (
+ <div className="fixed inset-0 z-50 flex items-center justify-center p-4 bg-neutral-900/40 backdrop-blur-xs animate-in fade-in duration-100">
+ <div
+ className="fixed inset-0"
+ onClick={onClose}
+ aria-hidden="true"
+ />
+ <div className="relative w-full max-w-2xl bg-white dark:bg-neutral-900 border border-neutral-200 dark:border-neutral-800 rounded-2xl shadow-2xl overflow-hidden flex flex-col z-10 max-h-[85vh]">
+ {/* Header */}
+ <div className="flex items-center justify-between px-6 py-4 border-b border-neutral-100 dark:border-neutral-800">
+ <div className="flex items-center gap-2.5">
+ <div className="p-1.5 bg-blue-50 dark:bg-blue-950/50 text-blue-600 rounded-lg">
+ <Keyboard className="w-5 h-5" />
+ </div>
+ <div>
+ <h2 className="text-base font-semibold text-neutral-900 dark:text-neutral-100">
+ Keyboard Shortcuts
+ </h2>
+ <p className="text-xs text-neutral-400">
+ Superhuman &amp; Gmail style quick keys
+ </p>
+ </div>
+ </div>
+ <button
+ type="button"
+ onClick={onClose}
+ className="text-neutral-400 hover:text-neutral-700 dark:hover:text-neutral-200 p-1.5 rounded-lg hover:bg-neutral-100 dark:hover:bg-neutral-800 transition-colors"
+ >
+ <X className="w-5 h-5" />
+ </button>
+ </div>
+
+ {/* Categories */}
+ <div className="overflow-y-auto p-6 grid grid-cols-1 md:grid-cols-2 gap-6">
+ {Object.entries(grouped).map(([category, items]) => (
+ <div key={category} className="space-y-3">
+ <h3 className="text-xs font-semibold uppercase tracking-wider text-neutral-400 dark:text-neutral-500 border-b border-neutral-100 dark:border-neutral-800/80 pb-1.5">
+ {category}
+ </h3>
+ <div className="space-y-2">
+ {items.map((item, idx) => (
+ <div
+ key={idx}
+ className="flex items-center justify-between text-sm"
+ >
+ <span className="text-neutral-700 dark:text-neutral-300">
+ {item.label}
+ </span>
+ <kbd className="px-2 py-0.5 text-xs font-mono font-medium text-neutral-600 dark:text-neutral-300 bg-neutral-100 dark:bg-neutral-800 border border-neutral-200 dark:border-neutral-700 rounded-md shadow-2xs">
+ {formatKey(item)}
+ </kbd>
+ </div>
+ ))}
+ </div>
+ </div>
+ ))}
+ </div>
+
+ {/* Footer */}
+ <div className="px-6 py-3 bg-neutral-50 dark:bg-neutral-950/60 border-t border-neutral-100 dark:border-neutral-800 flex items-center justify-between text-xs text-neutral-400">
+ <span>
+ Press{" "}
+ <kbd className="px-1.5 py-0.5 bg-neutral-200 dark:bg-neutral-800 text-neutral-700 dark:text-neutral-300 rounded font-mono">
+ ?
+ </kbd>{" "}
+ to toggle
+ </span>
+ <span>
+ Press{" "}
+ <kbd className="px-1.5 py-0.5 bg-neutral-200 dark:bg-neutral-800 text-neutral-700 dark:text-neutral-300 rounded font-mono">
+ ESC
+ </kbd>{" "}
+ to close
+ </span>
+ </div>
+ </div>
+ </div>
+ );
+}
diff --git a/src/components/shortcuts/types.ts b/src/components/shortcuts/types.ts
new file mode 100644
index 0000000..6c73e32
--- /dev/null
+++ b/src/components/shortcuts/types.ts
@@ -0,0 +1,22 @@
+export type ModifierKey = 'ctrl' | 'meta' | 'alt' | 'shift';
+
+export interface ShortcutDefinition {
+ key: string; // e.g., 'j', 'k', 'e', 'c', '?', '/' or sequences like 'g i'
+ label: string; // e.g., 'Next conversation'
+ category: 'Navigation' | 'Actions' | 'Composing' | 'Selection' | 'General';
+ description?: string;
+ modifiers?: ModifierKey[];
+ allowInInputs?: boolean;
+ action: () => void;
+}
+
+export interface CommandItem {
+ id: string;
+ title: string;
+ subtitle?: string;
+ category: 'Actions' | 'Navigation' | 'Settings' | 'Mailboxes' | 'General';
+ icon?: React.ComponentType<{ className?: string }>;
+ shortcut?: string;
+ keywords?: string[];
+ perform: () => void;
+}
diff --git a/src/components/shortcuts/use-hotkeys.ts b/src/components/shortcuts/use-hotkeys.ts
new file mode 100644
index 0000000..9afa238
--- /dev/null
+++ b/src/components/shortcuts/use-hotkeys.ts
@@ -0,0 +1,142 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import type { ShortcutDefinition } from "./types";
+
+interface UseHotkeysOptions {
+ enabled?: boolean;
+}
+
+export function isTypingInInput(target: EventTarget | null): boolean {
+ if (!target || !(target instanceof HTMLElement)) return false;
+ const tagName = target.tagName.toUpperCase();
+ const isInputOrTextarea =
+ tagName === "INPUT" || tagName === "TEXTAREA" || tagName === "SELECT";
+ const isContentEditable =
+ target.isContentEditable ||
+ target.getAttribute("contenteditable") === "true";
+ return isInputOrTextarea || isContentEditable;
+}
+
+function matchModifiers(
+ e: KeyboardEvent,
+ shortcut: ShortcutDefinition
+): boolean {
+ const requiresCtrl = shortcut.modifiers?.includes("ctrl");
+ const requiresMeta = shortcut.modifiers?.includes("meta");
+ const requiresAlt = shortcut.modifiers?.includes("alt");
+ const requiresShift = shortcut.modifiers?.includes("shift");
+
+ const hasCtrl = e.ctrlKey;
+ const hasMeta = e.metaKey;
+ const hasAlt = e.altKey;
+ const hasShift = e.shiftKey;
+
+ if (requiresCtrl && requiresMeta) {
+ if (!hasCtrl && !hasMeta) return false;
+ } else if (requiresCtrl && !hasCtrl) {
+ return false;
+ } else if (requiresMeta && !hasMeta) {
+ return false;
+ }
+
+ if (requiresAlt && !hasAlt) return false;
+ if (requiresShift && !hasShift) return false;
+
+ if (!requiresCtrl && !requiresMeta && (hasCtrl || hasMeta)) return false;
+ if (!requiresAlt && hasAlt) return false;
+
+ return true;
+}
+
+export function useHotkeys(
+ shortcuts: ShortcutDefinition[],
+ options: UseHotkeysOptions = { enabled: true }
+) {
+ const sequenceBufferRef = useRef<string[]>([]);
+ const sequenceTimerRef = useRef<number | null>(null);
+ const shortcutsRef = useRef<ShortcutDefinition[]>(shortcuts);
+
+ useEffect(() => {
+ shortcutsRef.current = shortcuts;
+ }, [shortcuts]);
+
+ useEffect(() => {
+ if (options.enabled === false) return;
+
+ const handleKeyDown = (e: KeyboardEvent) => {
+ const isInput = isTypingInInput(e.target);
+ const key = e.key.toLowerCase();
+
+ // Always allow Cmd+K / Ctrl+K
+ if ((e.metaKey || e.ctrlKey) && key === "k") {
+ const cmdK = shortcutsRef.current.find(
+ (s) =>
+ s.key.toLowerCase() === "k" &&
+ (s.modifiers?.includes("meta") || s.modifiers?.includes("ctrl"))
+ );
+ if (cmdK) {
+ e.preventDefault();
+ cmdK.action();
+ return;
+ }
+ }
+
+ if (isInput) {
+ if (e.key === "Escape") {
+ const esc = shortcutsRef.current.find(
+ (s) => s.key.toLowerCase() === "escape" || s.key.toLowerCase() === "esc"
+ );
+ if (esc) esc.action();
+ }
+ return;
+ }
+
+ // Handle sequence buffer
+ sequenceBufferRef.current.push(key);
+
+ if (sequenceTimerRef.current) {
+ window.clearTimeout(sequenceTimerRef.current);
+ }
+
+ sequenceTimerRef.current = window.setTimeout(() => {
+ sequenceBufferRef.current = [];
+ }, 800);
+
+ const currentSequence = sequenceBufferRef.current.join(" ");
+ const sequenceMatch = shortcutsRef.current.find(
+ (s) => s.key.toLowerCase() === currentSequence
+ );
+
+ if (sequenceMatch) {
+ e.preventDefault();
+ sequenceBufferRef.current = [];
+ sequenceMatch.action();
+ return;
+ }
+
+ const singleMatch = shortcutsRef.current.find((s) => {
+ if (s.key === "?" && e.key === "?") return true;
+ if (s.key === "/" && e.key === "/") return true;
+ if (s.key === "#" && e.key === "#") return true;
+
+ if (s.key.toLowerCase() !== key) return false;
+ return matchModifiers(e, s);
+ });
+
+ if (singleMatch) {
+ e.preventDefault();
+ sequenceBufferRef.current = [];
+ singleMatch.action();
+ }
+ };
+
+ window.addEventListener("keydown", handleKeyDown);
+ return () => {
+ window.removeEventListener("keydown", handleKeyDown);
+ if (sequenceTimerRef.current) {
+ window.clearTimeout(sequenceTimerRef.current);
+ }
+ };
+ }, [options.enabled]);
+}
diff --git a/src/components/sidebar-footer.tsx b/src/components/sidebar-footer.tsx
index 41a6a7a..d037b90 100644
--- a/src/components/sidebar-footer.tsx
+++ b/src/components/sidebar-footer.tsx
@@ -1,15 +1,41 @@
+"use client";
+
import packageJson from "../../package.json";
import { useSidebar } from "./sidebar-state";
+import { useShortcuts } from "./shortcuts";
+import { Keyboard } from "lucide-react";
export function SidebarFooter() {
const { minimal } = useSidebar();
+ const { openHelpModal } = useShortcuts();
if (minimal) return null;
+
return (
- <p className="px-3 pt-3 text-xs text-neutral-400">
- Powered by{" "}
- <a href={`https://mailflare.co/?ref=${location.hostname}&v=${packageJson.version}`} target="_blank">
- Mailflare v{packageJson.version}
- </a>
- </p>
+ <div className="px-3 pt-3 flex flex-col gap-2">
+ <button
+ type="button"
+ onClick={openHelpModal}
+ className="flex items-center justify-between w-full px-2.5 py-1.5 text-xs text-neutral-500 hover:text-neutral-800 hover:bg-neutral-200/60 rounded-lg transition-colors"
+ >
+ <span className="flex items-center gap-1.5">
+ <Keyboard className="w-3.5 h-3.5 text-neutral-400" />
+ Shortcuts
+ </span>
+ <kbd className="px-1.5 py-0.5 font-mono text-[10px] bg-white border border-neutral-200 rounded text-neutral-500 shadow-2xs">
+ ?
+ </kbd>
+ </button>
+ <p className="text-[11px] text-neutral-400">
+ Powered by{" "}
+ <a
+ href={`https://mailflare.co/?ref=${typeof window !== "undefined" ? location.hostname : ""}&v=${packageJson.version}`}
+ target="_blank"
+ className="hover:underline text-neutral-500"
+ rel="noreferrer"
+ >
+ Mailflare v{packageJson.version}
+ </a>
+ </p>
+ </div>
);
}