Skip to content

CLAUDE.md

Latest commit

 

History

History
131 lines (106 loc) · 4.08 KB

CLAUDE.md

File metadata and controls

131 lines (106 loc) · 4.08 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

A React implementation of the Konami Code detector, featuring a custom hook (useKonami) for detecting keyboard input sequences. The project is built with React 19, TypeScript, Vite, and Vitest.

Development Commands

Development Server

npm run dev

Starts Vite dev server (typically http://localhost:5173)

Build

npm run build

Runs TypeScript compiler check (tsc -b) followed by Vite build. Output is in dist/.

Testing

npm test              # Run all tests once
npm run test:watch    # Watch mode for development
npm run test:ui       # Interactive UI for tests
npm run test:coverage # Generate coverage report

Tests use Vitest with jsdom environment. Test setup is in tests/setup.ts.

Linting

npm run lint

Runs ESLint with flat config (eslint.config.js).

Preview

npm run preview

Preview production build locally.

Architecture

Core Hook: useKonami

Located in src/hooks/useKonami.ts. This is the primary functionality of the library.

Key Implementation Details:

  • Uses useRef to maintain stable references for progress and callbacks, avoiding unnecessary effect re-runs
  • Global window keyboard listener attached when enabled=true
  • Timeout mechanism resets progress if keys aren't pressed within the timeout window (default 2s)
  • Ignores repeat keydown events from held keys (e.repeat check)
  • Progress resets to 0 after successful activation, but activated state remains true
  • Manual reset() function clears both progress and activated state

State Management:

  • progressRef keeps sync with progress state for closure stability in event handler
  • callbacksRef stores latest callback functions to prevent effect dependencies
  • timeoutRef tracks the reset timer between keypresses

Exports:

  • DEFAULT_KONAMI_CODE: Array of arrow keys + 'b', 'a'
  • KonamiOptions: Configuration interface
  • KonamiState: Return value interface
  • useKonami: Main hook function

Demo Component: KonamiDemo

Located in src/components/KonamiDemo.tsx.

Responsibilities:

  • Visual feedback for sequence progress
  • Success/error/timeout state display with temporary feedback messages
  • Progress bar visualization
  • Manual reset button after activation
  • Console logging in development mode only

State Management:

  • Container state controls overall UI state (normal/success/error/timeout)
  • Feedback messages with auto-hide after 2s
  • Progress calculation as percentage for progress bar

File Structure

src/
  hooks/
    useKonami.ts          # Core hook implementation
  components/
    KonamiDemo.tsx        # Demo UI component
    KonamiDemo.css        # Demo styles
    ErrorBoundary.tsx     # Error boundary wrapper
  App.tsx                 # Root component
  main.tsx                # Entry point
tests/
  setup.ts                # Vitest setup
  hooks/
    useKonami.test.ts     # Comprehensive hook tests

Testing Approach

Tests for useKonami in tests/hooks/useKonami.test.ts cover:

  • Default behavior and initialization
  • Custom code sequences
  • Wrong key reset behavior
  • Timeout mechanism with fake timers
  • All callback invocations (onActivated, onProgress, onReset)
  • Repeat key filtering
  • Manual reset functionality
  • Dynamic enable/disable
  • Proper cleanup on unmount

Testing Patterns:

  • Use vi.useFakeTimers() in beforeEach
  • Use simulateKeyPress() helper to dispatch keyboard events
  • Use act() from @testing-library/react for state updates
  • Use renderHook() for testing hooks in isolation

TypeScript Configuration

Project uses TypeScript 5.9 with project references:

  • tsconfig.json: Base config with references
  • tsconfig.app.json: App source configuration
  • tsconfig.node.json: Node/Vite configuration

Build Tools

  • Vite 7: Dev server and bundler
  • Vitest 4: Test runner with jsdom environment
  • ESLint 9: Linting with flat config, React hooks and refresh plugins
  • @vitejs/plugin-react: React Fast Refresh support