feat(timeline): add keyboard navigation with shortcut overlay

- Arrow left/right scrolls the timeline by 1 day (Shift: 1 week) - Delete/Backspace deletes selected allocations - ? toggles a keyboard shortcut overlay - Floating ? button in bottom-right corner provides persistent access - (Del) hint added to the FloatingActionBar delete button Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-09 13:20:32 +02:00
parent 05f6eba5d8
commit fa54ef4cbd
4 changed files with 184 additions and 2 deletions
@@ -55,7 +55,9 @@ export function FloatingActionBar({
            "disabled:opacity-40 disabled:cursor-not-allowed",
          )}
        >
-          {isDeleting ? "Deleting\u2026" : "Delete"}
+          {isDeleting ? "Deleting\u2026" : (
+            <>Delete <span className="opacity-60 text-[10px]">(Del)</span></>
+          )}
        </button>
      )}

@@ -0,0 +1,50 @@
+"use client";
+
+const SHORTCUTS: { keys: string; description: string }[] = [
+  { keys: "← / →", description: "Scroll timeline 1 day" },
+  { keys: "Shift + ← / →", description: "Scroll timeline 1 week" },
+  { keys: "Delete / Backspace", description: "Delete selected allocations" },
+  { keys: "Ctrl / Cmd + Z", description: "Undo last action" },
+  { keys: "Ctrl / Cmd + Shift + Z", description: "Redo" },
+  { keys: "Shift + Wheel", description: "Horizontal scroll" },
+  { keys: "ESC", description: "Close popover / clear selection" },
+  { keys: "?", description: "Toggle this overlay" },
+];
+
+interface KeyboardShortcutOverlayProps {
+  onClose: () => void;
+}
+
+export function KeyboardShortcutOverlay({ onClose }: KeyboardShortcutOverlayProps) {
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/40" onClick={onClose}>
+      <div
+        className="bg-white dark:bg-gray-800 rounded-2xl shadow-2xl border border-gray-200 dark:border-gray-700 w-full max-w-sm mx-4 overflow-hidden"
+        onClick={(e) => e.stopPropagation()}
+      >
+        <div className="flex items-center justify-between px-5 py-4 border-b border-gray-100 dark:border-gray-700">
+          <h2 className="text-sm font-semibold text-gray-900 dark:text-gray-100">Keyboard Shortcuts</h2>
+          <button
+            onClick={onClose}
+            className="text-gray-400 hover:text-gray-600 dark:text-gray-500 dark:hover:text-gray-300 text-lg leading-none"
+          >
+            &times;
+          </button>
+        </div>
+        <ul className="divide-y divide-gray-50 dark:divide-gray-700/50">
+          {SHORTCUTS.map((s) => (
+            <li key={s.keys} className="flex items-center justify-between gap-4 px-5 py-2.5">
+              <span className="text-xs text-gray-500 dark:text-gray-400">{s.description}</span>
+              <kbd className="shrink-0 rounded-md border border-gray-200 dark:border-gray-600 bg-gray-50 dark:bg-gray-900 px-2 py-0.5 font-mono text-[11px] text-gray-700 dark:text-gray-300">
+                {s.keys}
+              </kbd>
+            </li>
+          ))}
+        </ul>
+        <div className="px-5 py-3 border-t border-gray-100 dark:border-gray-700 text-[11px] text-gray-400 dark:text-gray-500 text-center">
+          Press <kbd className="font-mono">?</kbd> to toggle
+        </div>
+      </div>
+    </div>
+  );
+}
@@ -1,5 +1,6 @@
 "use client";

+import { MILLISECONDS_PER_DAY } from "@capakraken/shared";
 import { clsx } from "clsx";
 import { useSession } from "next-auth/react";
 import { useEffect, useMemo, useRef, useState } from "react";
@@ -35,6 +36,9 @@ import { TimelineProjectPanel, type OpenDemandAssignment } from "./TimelineProje
 import { ProjectColorLegend } from "./ProjectColorLegend.js";
 import { useMultiSelectIntersection } from "~/hooks/useMultiSelectIntersection.js";
 import type { TimelineVisualOverrides } from "./allocationVisualState.js";
+import { SuccessToast } from "~/components/ui/SuccessToast.js";
+import { useTimelineKeyboard } from "~/hooks/useTimelineKeyboard.js";
+import { KeyboardShortcutOverlay } from "./KeyboardShortcutOverlay.js";

 // ─── Entry point ────────────────────────────────────────────────────────────
 // Two-layer mount: the outer shell creates drag state + project context,
@@ -86,6 +90,8 @@ export function TimelineView() {
    onSuccess: invalidateTimeline,
  });

+  const [dragErrorToast, setDragErrorToast] = useState<string | null>(null);
+
  const {
    dragState,
    allocDragState,
@@ -156,6 +162,7 @@ export function TimelineView() {
        clearMultiSelect();
      }
    },
+    onMutationError: (message) => setDragErrorToast(message),
  });

  const [openPanelProjectId, setOpenPanelProjectId] = useState<string | null>(null);
@@ -164,6 +171,13 @@ export function TimelineView() {
  const { contextResourceIds, contextAllocations } = useProjectDragContext(contextProjectId, canManageTimeline);

  return (
+    <>
+    <SuccessToast
+      show={dragErrorToast !== null}
+      message={dragErrorToast ?? ""}
+      variant="warning"
+      onDone={() => setDragErrorToast(null)}
+    />
    <TimelineProvider
      isDragging={dragState.isDragging}
      contextAllocations={contextAllocations as TimelineAssignmentEntry[]}
@@ -209,6 +223,7 @@ export function TimelineView() {
        redo={redo}
      />
    </TimelineProvider>
+    </>
  );
 }

@@ -368,6 +383,20 @@ function TimelineViewContent({

  const { CELL_WIDTH, dates, totalCanvasWidth, toLeft, toWidth, gridLines, monthGroups, xToDate } =
    useTimelineLayout(viewStart, viewDays, filters.zoom, filters.showWeekends, today);
+
+  const { showShortcuts, setShowShortcuts } = useTimelineKeyboard({
+    scrollContainerRef,
+    cellWidth: CELL_WIDTH,
+    selectedAllocationIds: multiSelectState.selectedAllocationIds,
+    onDeleteSelected: () => {
+      if (multiSelectState.selectedAllocationIds.length === 0) return;
+      const msg = `Delete ${multiSelectState.selectedAllocationIds.length} allocation(s)? This cannot be undone.`;
+      if (window.confirm(msg)) {
+        batchDeleteMutation.mutate({ ids: multiSelectState.selectedAllocationIds });
+      }
+    },
+  });
+
  const hasActivePointerOverlay =
    dragState.isDragging || allocDragState.isActive || rangeState.isSelecting || multiSelectState.isMultiDragging;

@@ -896,7 +925,7 @@ function TimelineViewContent({
              rangeState.startDate <= end
                ? [rangeState.startDate, end]
                : [end, rangeState.startDate];
-            const days = Math.round((e.getTime() - s.getTime()) / 86400000) + 1;
+            const days = Math.round((e.getTime() - s.getTime()) / MILLISECONDS_PER_DAY) + 1;
            return `${days} day${days !== 1 ? "s" : ""}`;
          })()}
        </div>
@@ -1066,6 +1095,19 @@ function TimelineViewContent({
          onClose={() => setResourceHover(null)}
        />
      )}
+
+      {/* Keyboard shortcut overlay */}
+      {showShortcuts && <KeyboardShortcutOverlay onClose={() => setShowShortcuts(false)} />}
+
+      {/* Keyboard shortcut hint button */}
+      <button
+        type="button"
+        onClick={() => setShowShortcuts((prev) => !prev)}
+        title="Keyboard shortcuts (?)"
+        className="fixed bottom-6 right-6 z-40 rounded-full w-8 h-8 flex items-center justify-center bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 shadow text-gray-500 dark:text-gray-400 hover:text-gray-700 dark:hover:text-gray-200 text-sm font-medium"
+      >
+        ?
+      </button>
    </div>
  );
 }
@@ -0,0 +1,88 @@
+import React, { useEffect, useRef, useState } from "react";
+import type { RefObject } from "react";
+
+interface UseTimelineKeyboardOptions {
+  scrollContainerRef: RefObject<HTMLElement | null>;
+  cellWidth: number;
+  selectedAllocationIds: string[];
+  onDeleteSelected: () => void;
+}
+
+export interface UseTimelineKeyboardResult {
+  showShortcuts: boolean;
+  setShowShortcuts: React.Dispatch<React.SetStateAction<boolean>>;
+}
+
+function isTypingTarget(el: Element | null): boolean {
+  if (!el) return false;
+  const tag = el.tagName.toLowerCase();
+  if (tag === "input" || tag === "textarea" || tag === "select") return true;
+  if ((el as HTMLElement).isContentEditable) return true;
+  return false;
+}
+
+export function useTimelineKeyboard({
+  scrollContainerRef,
+  cellWidth,
+  selectedAllocationIds,
+  onDeleteSelected,
+}: UseTimelineKeyboardOptions): UseTimelineKeyboardResult {
+  const [showShortcuts, setShowShortcuts] = useState(false);
+
+  // Keep stable refs so the handler closure doesn't need to be re-registered on every render
+  const onDeleteRef = useRef(onDeleteSelected);
+  onDeleteRef.current = onDeleteSelected;
+  const selectedCountRef = useRef(selectedAllocationIds.length);
+  selectedCountRef.current = selectedAllocationIds.length;
+  const cellWidthRef = useRef(cellWidth);
+  cellWidthRef.current = cellWidth;
+
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if (isTypingTarget(document.activeElement)) return;
+
+      const isMac = navigator.platform.toUpperCase().includes("MAC");
+      const modKey = isMac ? e.metaKey : e.ctrlKey;
+      const dayPx = cellWidthRef.current;
+      const el = scrollContainerRef.current;
+
+      switch (e.key) {
+        case "?":
+          e.preventDefault();
+          setShowShortcuts((prev) => !prev);
+          break;
+
+        case "ArrowLeft":
+          if (el) {
+            e.preventDefault();
+            el.scrollLeft -= (e.shiftKey ? 7 : 1) * dayPx;
+          }
+          break;
+
+        case "ArrowRight":
+          if (el) {
+            e.preventDefault();
+            el.scrollLeft += (e.shiftKey ? 7 : 1) * dayPx;
+          }
+          break;
+
+        case "Delete":
+        case "Backspace":
+          if (modKey) break; // let browser handle Cmd+Backspace etc.
+          if (selectedCountRef.current > 0) {
+            e.preventDefault();
+            onDeleteRef.current();
+          }
+          break;
+
+        default:
+          break;
+      }
+    };
+
+    window.addEventListener("keydown", handler);
+    return () => window.removeEventListener("keydown", handler);
+  }, [scrollContainerRef]); // stable — uses refs for everything that changes
+
+  return { showShortcuts, setShowShortcuts };
+}