Types

Complete TypeScript reference for Human-Like library. Use this as a lookup reference; practical examples are available on the Component, Hook, and Events pages.

Import Guide

Types are split between two modules:

// Core types (main package)
import type { 
  HumanLikeConfig,
  HumanLikeProps,
  HumanLikeHookReturn,
  MistakeInfo,
  TypingState,
  StateChangeEvent,
  ErrorEvent
} from '@ertekinno/human-like';

// Keyboard-specific types (keyboard module)
import type {
  KeyInfo,
  KeyPressEvent,
  KeyboardView,
  ShiftState,
  KeyboardMode,
  KeySequence,
  KeyboardClasses,
  LabelOverrides,
  IconOverrides
} from '@ertekinno/human-like/keyboard';

Core Interfaces

HumanLikeProps

Main component props interface.

interface HumanLikeProps {
  // Required
  text: string

  // Basic Configuration
  speed?: number                        // Base typing speed in ms (default: 80)
  mistakeFrequency?: number            // Error probability 0-1 (default: 0.03)
  keyboardMode?: 'mobile' | 'desktop'  // Platform behavior (default: 'mobile')
  autoStart?: boolean                  // Start typing on mount (default: true)
  
  // Cursor Configuration
  showCursor?: boolean                 // Show blinking cursor (default: true)
  cursorChar?: string                  // Cursor character (default: '|')
  cursorBlinkSpeed?: number           // Blink speed in ms (default: 530)
  
  // Styling & DOM
  id?: string                         // Component ID
  className?: string                  // CSS class names
  style?: React.CSSProperties         // Inline styles
  
  // Advanced Configuration
  config?: Partial<HumanLikeConfig>   // Detailed behavior config
  
  // Event Callbacks
  onStart?: (id?: string) => void
  onComplete?: (id?: string) => void
  onChar?: (char: string, index: number, id?: string) => void
  onMistake?: (mistake: MistakeInfo, id?: string) => void
  onBackspace?: (id?: string) => void
  onPause?: (id?: string) => void
  onResume?: (id?: string) => void
  onKey?: (keyInfo: KeyInfo, id?: string) => void
  onStateChange?: (event: StateChangeEvent, id?: string) => void
  onKeyboardReset?: (id?: string) => void
  onError?: (event: ErrorEvent, id?: string) => void
}

HumanLikeHookOptions

Hook options interface (extends component props).

interface HumanLikeHookOptions extends Omit<HumanLikeProps, 'className' | 'style'> {
  // Hook-specific options can be added here
}

HumanLikeHookReturn

Complete hook return interface.

interface HumanLikeHookReturn {
  // Display State
  displayText: string                  // Current typed text
  
  // Typing State
  isTyping: boolean                   // Currently typing
  isPaused: boolean                   // Currently paused
  isCompleted: boolean                // Typing finished
  currentState: TypingState           // Detailed state
  
  // Progress & Performance
  progress: number                    // Progress 0-100
  currentWPM: number                  // Words per minute
  mistakeCount: number                // Total mistakes made
  totalDuration: number               // Total time elapsed (ms)
  
  // Control Methods
  start: () => void                   // Start typing
  stop: () => void                    // Stop and reset
  pause: () => void                   // Pause typing
  resume: () => void                  // Resume typing
  reset: () => void                   // Reset to beginning
  skip: () => void                    // Skip to end
  rewind: () => void                  // Go back to start
  
  // Cursor State
  showCursor: boolean                 // Cursor visibility
  cursorChar: string                  // Cursor character
  cursorBlinkSpeed: number           // Blink speed
  
  // Cursor Control
  setCursorVisible: (visible: boolean) => void
  setCursorChar: (char: string) => void
  setCursorBlinkSpeed: (speed: number) => void
}

Configuration Types

HumanLikeConfig

Complete configuration interface with all timing and behavior options.

interface HumanLikeConfig {
  // Core Timing
  speed: number                       // Base delay between chars (ms)
  speedVariation: number              // Random variation ±ms
  minCharDelay: number               // Minimum delay between chars
  
  // Platform Behavior
  keyboardMode: 'mobile' | 'desktop' // Platform-specific behaviors
  
  // Mistake Configuration
  mistakeFrequency: number           // Error probability (0-1)
  mistakeTypes: {
    adjacent: boolean                // Hit nearby keys
    random: boolean                  // Random character errors
    doubleChar: boolean             // Accidental double typing
    commonTypos: boolean            // Real-world typos (teh → the)
  }
  
  // Human Behavior
  fatigueEffect: boolean             // Gradual slowdown over time
  concentrationLapses: boolean       // Random thinking pauses
  overcorrection: boolean            // Errors while correcting
  
  // Timing Controls
  sentencePause: number              // Pause after . ! ? (ms)
  wordPause: number                  // Pause between words (ms)
  thinkingPause: number             // Pause before complex words (ms)
  
  // Correction Timing
  backspaceSpeed: number             // Correction speed (ms)
  realizationDelay: number          // Time to notice mistake (ms)
  correctionPause: number           // Pause before retyping (ms)
  
  // Development
  debug: boolean                     // Enable console logging
}

MistakeTypes

Mistake configuration sub-interface.

interface MistakeTypes {
  adjacent: boolean      // Adjacent key errors (q → w)
  random: boolean        // Random character substitution
  doubleChar: boolean    // Double character typing (hello → heello)
  commonTypos: boolean   // Common typos (the → teh)
}

State & Event Types

TypingState

All possible typing states.

type TypingState = 
  | 'idle'         // Not started
  | 'typing'       // Actively typing
  | 'paused'       // Paused by user
  | 'correcting'   // Fixing a mistake
  | 'thinking'     // Concentration lapse pause
  | 'completed'    // Finished typing

MistakeInfo

Information about typing mistakes.

interface MistakeInfo {
  type: 'adjacent' | 'random' | 'doubleChar' | 'commonTypo'
  originalChar: string     // Intended character
  mistakeChar: string      // Actually typed character
  position: number         // Character position in text
  corrected?: boolean      // Whether mistake was corrected
  realizationTime?: number // Time to notice mistake (ms)
}

KeyInfo

Information about simulated key presses.

interface KeyInfo {
  key: string                                    // Key identifier (e.g., 'h', 'shift', '123', 'ABC')
  character: string                              // Original character produced (e.g., 'H', '@', '4')
  type: 'letter' | 'number' | 'symbol' | 'modifier' | 'view-switch' | 'space' | 'enter' | 'backspace'
  keyboardView: 'letters' | 'numbers' | 'symbols' | 'emoji'
  isCapsLock: boolean                           // Whether this is part of caps lock sequence
  duration: number                              // How long to highlight/hold key (ms)
  sequenceIndex: number                         // Position in key sequence (0-based)
  sequenceLength: number                        // Total keys in character sequence
}

StateChangeEvent

State transition event information.

interface StateChangeEvent {
  previousState: TypingState   // Previous state
  currentState: TypingState    // New state
  timestamp: number            // Event timestamp
}

ErrorEvent

Error event information.

interface ErrorEvent {
  code: string        // Error code
  message: string     // Error description
  timestamp: number   // Error timestamp
}

Keyboard Component Types

KeyboardView

Available keyboard view modes.

enum KeyboardView {
  Letters = 'letters',
  Numbers = 'numbers', 
  Symbols = 'symbols'
}

ShiftState

Shift key states for keyboard components.

enum ShiftState {
  Off = 'off',
  On = 'on',
  Caps = 'caps'
}

Utility Types

Platform

Platform detection type.

type Platform = 'mobile' | 'desktop'

KeyType

Classification of key types.

type KeyType = 
  | 'letter'      // Alphabetic characters
  | 'number'      // Numeric characters
  | 'symbol'      // Symbols and punctuation
  | 'modifier'    // Shift, caps, etc.
  | 'view-switch' // View switching keys

KeyboardViewType

Keyboard view classification.

type KeyboardViewType = 'letters' | 'numbers' | 'symbols'

MistakeType

Types of mistakes that can occur.

type MistakeType = 'adjacent' | 'random' | 'doubleChar' | 'commonTypo'

Type Guards

isTypingState

Type guard for typing states.

function isTypingState(value: any): value is TypingState {
  return ['idle', 'typing', 'paused', 'correcting', 'thinking', 'completed'].includes(value)
}

isMistakeType

Type guard for mistake types.

function isMistakeType(value: any): value is MistakeType {
  return ['adjacent', 'random', 'doubleChar', 'commonTypo'].includes(value)
}

isKeyType

Type guard for key types.

function isKeyType(value: any): value is KeyType {
  return ['letter', 'number', 'symbol', 'modifier', 'view-switch'].includes(value)
}

Advanced Patterns

Partial Configuration

Common pattern for optional configuration.

type PartialConfig = Partial<HumanLikeConfig>

// Usage
const config: PartialConfig = {
  speed: 70,
  mistakeFrequency: 0.05
  // Other options use defaults
}

Event Handler Types

Reusable event handler type definitions.

type StartHandler = (id?: string) => void
type CharHandler = (char: string, index: number, id?: string) => void
type MistakeHandler = (mistake: MistakeInfo, id?: string) => void
type KeyHandler = (keyInfo: KeyInfo, id?: string) => void
type StateChangeHandler = (event: StateChangeEvent, id?: string) => void
type ErrorHandler = (event: ErrorEvent, id?: string) => void

Generic Event Handler

Generic event handler for any Human-Like event.

type HumanLikeEventHandler<T = any> = (data: T, id?: string) => void

Types

On this page