Add keyboard shortcuts and hits-remaining guidance to attack log

Author: kabaka

README.md

@@ -56,6 +56,7 @@ Vitest (unit tests) and Playwright (e2e tests) validate that core sections rende
 - **Boss presets, Godhome variants, and custom targets:** Quickly switch between Hallownest encounters, Godhome trials (Attuned, Ascended, Radiant), or specify any target for practice sessions.
 - **Data-driven build controls with charm presets:** Choose nail upgrades, toggle influential charms, apply popular charm loadouts with one click, and declare which spell upgrades are available to tune damage presets.
 - **Categorized attack logging with undo/redo:** Nail strikes, spell casts, and advanced techniques each expose context-aware damage values that respect build modifiers like Unbreakable Strength or Shaman Stone, while new undo/redo controls make correcting mistakes effortless.
+- **Keyboard shortcuts and finishing guidance:** Each attack button surfaces the remaining hits required to reach zero HP if you relied solely on that move, and keyboard shortcuts (number row followed by QWERTY order) allow spectators to log attacks or press <kbd>Esc</kbd> for a quick reset without leaving the action.
 - **Live combat analytics:** Remaining HP, DPS, average damage, and actions per minute update instantly as attacks are logged, giving immediate feedback on fight pacing.
 
 Automated workflows in `.github/workflows/` run linting, unit tests, end-to-end tests, and GitHub Pages deployments on every push.

src/features/attack-log/AttackLogPanel.test.tsx

@@ -18,13 +18,14 @@ describe('AttackLogPanel', () => {
     );
 
     const nailStrikeButton = screen.getByRole('button', { name: /nail strike/i });
-    expect(nailStrikeButton).toHaveTextContent(/5/);
+    const damageDisplay = within(nailStrikeButton).getByLabelText(/damage per hit/i);
+    expect(damageDisplay).toHaveTextContent('5');
 
     await user.selectOptions(screen.getByLabelText(/nail upgrade/i), 'pure-nail');
-    expect(nailStrikeButton).toHaveTextContent(/21/);
+    expect(damageDisplay).toHaveTextContent('21');
 
     await user.click(screen.getByLabelText(/unbreakable strength/i));
-    expect(nailStrikeButton).toHaveTextContent(/32/);
+    expect(damageDisplay).toHaveTextContent('32');
   });
 
   it('surfaces spell upgrades in the advanced group when unlocked', async () => {
@@ -65,6 +66,20 @@ describe('AttackLogPanel', () => {
     expect(within(actionsRow as HTMLElement).getByText('1')).toBeInTheDocument();
   });
 
+  it('shows hits remaining for each attack and updates after logging damage', async () => {
+    const user = userEvent.setup();
+
+    renderWithFightProvider(<AttackLogPanel />);
+
+    const nailStrikeButton = screen.getByRole('button', { name: /nail strike/i });
+    const hitsDisplay = within(nailStrikeButton).getByLabelText(/hits to finish/i);
+    expect(hitsDisplay).toHaveTextContent(/hits to finish: 71/i);
+
+    await user.click(nailStrikeButton);
+
+    expect(hitsDisplay).toHaveTextContent(/hits to finish: 70/i);
+  });
+
   it('supports undo, redo, and quick reset controls', async () => {
     const user = userEvent.setup();
 
@@ -109,4 +124,25 @@ describe('AttackLogPanel', () => {
     expect(redoButton).toBeDisabled();
     expect(resetButton).toBeDisabled();
   });
+
+  it('supports keyboard shortcuts for logging attacks and resetting', async () => {
+    const user = userEvent.setup();
+
+    renderWithFightProvider(
+      <>
+        <AttackLogPanel />
+        <CombatStatsPanel />
+      </>,
+    );
+
+    await user.keyboard('1');
+
+    let damageRow = screen.getByText('Damage Logged').closest('.data-list__item');
+    expect(within(damageRow as HTMLElement).getByText('5')).toBeInTheDocument();
+
+    await user.keyboard('{Escape}');
+
+    damageRow = screen.getByText('Damage Logged').closest('.data-list__item');
+    expect(within(damageRow as HTMLElement).getByText('0')).toBeInTheDocument();
+  });
 });

src/features/attack-log/AttackLogPanel.tsx

@@ -1,5 +1,5 @@
 import type { FC } from 'react';
-import { useMemo } from 'react';
+import { useEffect, useMemo } from 'react';
 
 import {
   hasStrengthCharm,
@@ -23,6 +23,62 @@ type AttackGroup = {
   attacks: AttackDefinition[];
 };
 
+type AttackWithMetadata = AttackDefinition & {
+  hotkey?: string;
+  hitsRemaining: number | null;
+};
+
+type AttackGroupWithMetadata = {
+  id: string;
+  label: string;
+  attacks: AttackWithMetadata[];
+};
+
+const KEY_SEQUENCE = [
+  '1',
+  '2',
+  '3',
+  '4',
+  '5',
+  '6',
+  '7',
+  '8',
+  '9',
+  '0',
+  'q',
+  'w',
+  'e',
+  'r',
+  't',
+  'y',
+  'u',
+  'i',
+  'o',
+  'p',
+  'a',
+  's',
+  'd',
+  'f',
+  'g',
+  'h',
+  'j',
+  'k',
+  'l',
+  ';',
+  'z',
+  'x',
+  'c',
+  'v',
+  'b',
+  'n',
+  'm',
+  ',',
+  '.',
+  '/',
+];
+
+const RESET_SHORTCUT_KEY = 'Escape';
+
 const NAIL_ART_MULTIPLIERS: Record<string, number> = {
   'great-slash': 2.5,
   'dash-slash': 2,
@@ -132,11 +188,93 @@ const buildAttackGroups = (
 
 export const AttackLogPanel: FC = () => {
   const fight = useFightState();
-  const { actions, state } = fight;
+  const { actions, state, derived } = fight;
   const { damageLog, redoStack } = state;
 
   const attackGroups = useMemo(() => buildAttackGroups(state), [state]);
 
+  const { groupsWithMetadata, shortcutMap } = useMemo(() => {
+    const map = new Map<string, AttackDefinition>();
+    let hotkeyIndex = 0;
+
+    const groups: AttackGroupWithMetadata[] = attackGroups.map((group) => ({
+      ...group,
+      attacks: group.attacks.map((attack) => {
+        const hotkey = KEY_SEQUENCE[hotkeyIndex];
+        hotkeyIndex += 1;
+
+        if (hotkey) {
+          map.set(hotkey, attack);
+        }
+
+        const hitsRemaining =
+          attack.damage > 0
+            ? Math.ceil(Math.max(0, derived.remainingHp) / attack.damage)
+            : null;
+
+        return {
+          ...attack,
+          hotkey,
+          hitsRemaining,
+        } satisfies AttackWithMetadata;
+      }),
+    }));
+
+    return { groupsWithMetadata: groups, shortcutMap: map };
+  }, [attackGroups, derived.remainingHp]);
+
+  useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.defaultPrevented) {
+        return;
+      }
+
+      if (event.altKey || event.ctrlKey || event.metaKey) {
+        return;
+      }
+
+      const target = event.target as HTMLElement | null;
+      if (target) {
+        const interactiveElement = target.closest(
+          'input, textarea, select, [contenteditable="true"]',
+        );
+        if (interactiveElement) {
+          return;
+        }
+      }
+
+      const key = event.key.length === 1 ? event.key.toLowerCase() : event.key;
+
+      if (key === RESET_SHORTCUT_KEY) {
+        if (state.damageLog.length === 0 && state.redoStack.length === 0) {
+          return;
+        }
+        event.preventDefault();
+        actions.resetLog();
+        return;
+      }
+
+      if (key.length === 1) {
+        const attack = shortcutMap.get(key);
+        if (!attack) {
+          return;
+        }
+
+        event.preventDefault();
+        actions.logAttack({
+          id: attack.id,
+          label: attack.label,
+          damage: attack.damage,
+          category: attack.category,
+          soulCost: attack.soulCost,
+        });
+      }
+    };
+
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, [actions, shortcutMap, state.damageLog.length, state.redoStack.length]);
+
   return (
     <div>
       <p className="section__description">
@@ -165,13 +303,14 @@ export const AttackLogPanel: FC = () => {
           type="button"
           className="quick-actions__button"
           onClick={actions.resetLog}
+          aria-keyshortcuts="Esc"
           disabled={damageLog.length === 0 && redoStack.length === 0}
         >
-          Quick reset
+          Quick reset (Esc)
         </button>
       </div>
       <div className="attack-groups">
-        {attackGroups.map((group) => (
+        {groupsWithMetadata.map((group) => (
           <section key={group.id} className="attack-group">
             <h3 className="attack-group__title">{group.label}</h3>
             <div className="button-grid" role="group" aria-label={group.label}>
@@ -180,6 +319,7 @@ export const AttackLogPanel: FC = () => {
                   key={attack.id}
                   type="button"
                   className="button-grid__button"
+                  aria-keyshortcuts={attack.hotkey?.toUpperCase()}
                   onClick={() =>
                     actions.logAttack({
                       id: attack.id,
@@ -190,16 +330,36 @@ export const AttackLogPanel: FC = () => {
                     })
                   }
                 >
-                  <span className="button-grid__label">{attack.label}</span>
+                  <div className="button-grid__header">
+                    <span className="button-grid__label">{attack.label}</span>
+                    {attack.hotkey ? (
+                      <span className="button-grid__hotkey" aria-hidden="true">
+                        {attack.hotkey.toUpperCase()}
+                      </span>
+                    ) : null}
+                  </div>
+                  {attack.hotkey ? (
+                    <span className="visually-hidden">
+                      Shortcut key {attack.hotkey.toUpperCase()}.
+                    </span>
+                  ) : null}
                   <span className="button-grid__meta">
-                    <span className="button-grid__damage" aria-hidden="true">
+                    <span className="button-grid__damage" aria-label="Damage per hit">
                       {attack.damage}
                     </span>
                     {typeof attack.soulCost === 'number' ? (
                       <span className="button-grid__soul" aria-label="Soul cost">
                         {attack.soulCost} SOUL
                       </span>
                     ) : null}
+                    {typeof attack.hitsRemaining === 'number' ? (
+                      <span
+                        className="button-grid__hits"
+                        aria-label="Hits to finish with this attack"
+                      >
+                        Hits to finish: {attack.hitsRemaining}
+                      </span>
+                    ) : null}
                   </span>
                   {attack.description ? (
                     <span className="button-grid__description">{attack.description}</span>

src/styles/global.css

@@ -139,6 +139,14 @@ body {
   gap: 0.5rem;
 }
 
+.button-grid__header {
+  width: 100%;
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  gap: 0.5rem;
+}
+
 .button-grid__button:hover,
 .button-grid__button:focus-visible {
   outline: none;
@@ -151,9 +159,21 @@ body {
   font-size: 1rem;
 }
 
+.button-grid__hotkey {
+  font-size: 0.7rem;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  padding: 0.1rem 0.35rem;
+  border-radius: 0.4rem;
+  border: 1px solid rgba(255 255 255 / 18%);
+  color: var(--color-muted);
+  background: rgba(255 255 255 / 8%);
+}
+
 .button-grid__meta {
   display: flex;
   flex-wrap: wrap;
+  align-items: center;
   gap: 0.4rem;
   font-size: 0.85rem;
   color: var(--color-muted);
@@ -171,6 +191,12 @@ body {
   text-transform: uppercase;
 }
 
+.button-grid__hits {
+  font-size: 0.75rem;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+
 .button-grid__description {
   font-size: 0.75rem;
   color: var(--color-muted);
@@ -195,6 +221,18 @@ body {
   color: var(--color-muted);
 }
 
+.visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
 .data-list {
   display: flex;
   flex-direction: column;