reactjs-virtual-keyboard 1.0.2 → 2.0.1

package/README.md

@@ -1,18 +1,21 @@
 # reactjs-virtual-keyboard
 
-A customizable virtual keyboard component for React applications. Features multiple keyboard layouts (QWERTY, symbols, numbers), hardware keyboard synchronization, touch device support, and full TypeScript support.
+A lightweight, customizable virtual keyboard component for React applications. Features multiple layouts, multi-language support, hardware keyboard sync, extensive customization options, and full TypeScript support.
 
-## Features
+📚 **[Documentation & Live Demo](https://kalpesh442266.github.io/virtual-keyboard-lib/)**
 
-- **Multiple Layouts**: QWERTY letters, symbols, and numeric keypad layouts
-- **Hardware Keyboard Sync**: Virtual keyboard state syncs with physical keyboard (e.g., Caps Lock)
-- **Touch Optimized**: Designed for touch screens with continuous press support (hold backspace to delete)
-- **Customizable Themes**: CSS variables for easy theming, plus built-in theme classes
-- **TypeScript Support**: Full type definitions included
-- **Accessible**: Keyboard navigation and focus management
-- **Lightweight**: No external dependencies except React
+## ✨ Features
 
-## Installation
+- **🎹 Multiple Layouts**: QWERTY letters, symbols, and numeric keypad
+- **🌍 Multi-Language Support**: Built-in language switcher with custom language layouts
+- **⌨️ Hardware Keyboard Sync**: Virtual keyboard syncs with physical keyboard (Caps Lock, key presses)
+- **📱 Touch Optimized**: Continuous press support (hold backspace to delete)
+- **🎨 Highly Customizable**: Custom layouts, key labels, disabled/hidden keys, render functions
+- **🪶 Lightweight**: Only ~26 KB minified (~6.3 KB gzipped), no external dependencies
+- **📘 TypeScript**: Full type definitions included
+- **♿ Accessible**: Keyboard navigation and focus management
+
+## 📦 Installation
 
 ```bash
 npm install reactjs-virtual-keyboard
@@ -22,11 +25,11 @@ yarn add reactjs-virtual-keyboard
 pnpm add reactjs-virtual-keyboard
 ```
 
-## Quick Start
+## 🚀 Quick Start
 
-### Option 1: GlobalVirtualKeyboard (Easiest)
+### Option 1: GlobalVirtualKeyboard (Recommended)
 
-Add once at your app root - automatically shows keyboard when any input is focused:
+Add once at your app root - automatically shows keyboard for all inputs:
 
 ```tsx
 import { GlobalVirtualKeyboard } from 'reactjs-virtual-keyboard';
@@ -35,11 +38,10 @@ import 'reactjs-virtual-keyboard/styles.css';
 function App() {
   return (
     <div>
-      <input type="text" placeholder="Click me!" />
-      <input type="email" placeholder="Email input" />
-      <input type="number" placeholder="Number input" />
+      <input type="text" placeholder="Click any input!" />
+      <input type="email" placeholder="Email" />
+      <input type="number" placeholder="Numbers" />
       
-      {/* Add once - works for all inputs */}
       <GlobalVirtualKeyboard />
     </div>
   );
@@ -48,7 +50,7 @@ function App() {
 
 ### Option 2: VirtualKeyboard (Manual Control)
 
-For more control over when the keyboard appears:
+For more control over when and where the keyboard appears:
 
 ```tsx
 import { useRef, useState } from 'react';
@@ -58,27 +60,20 @@ import 'reactjs-virtual-keyboard/styles.css';
 function App() {
   const inputRef = useRef<HTMLInputElement>(null);
   const [isInputFocused, setIsInputFocused] = useState(false);
-  const [value, setValue] = useState('');
 
   return (
     <div>
       <input
         ref={inputRef}
         type="text"
-        value={value}
-        onChange={(e) => setValue(e.target.value)}
         onFocus={() => setIsInputFocused(true)}
         onBlur={() => setIsInputFocused(false)}
-        placeholder="Click to show keyboard"
       />
 
       {isInputFocused && (
         <VirtualKeyboard
           focusedInputRef={inputRef}
           isInputFocused={isInputFocused}
-          inputType="text"
-          onEnterClick={() => console.log('Enter pressed!')}
-          onChange={(newValue) => setValue(newValue)}
         />
       )}
     </div>
@@ -86,242 +81,351 @@ function App() {
 }
 ```
 
-## Components
+## 📖 API Reference
+
+### `<GlobalVirtualKeyboard />`
 
-### GlobalVirtualKeyboard
+Automatically manages keyboard visibility for all inputs on the page.
 
-Automatically shows keyboard when any text input is focused. Best for most use cases.
+```tsx
+interface GlobalVirtualKeyboardProps {
+  enabled?: boolean;                              // Enable/disable keyboard (default: true)
+  className?: string;                              // Custom CSS class
+  onVisibilityChange?: (visible: boolean) => void; // Visibility change callback
+  onEnterClick?: () => void;                       // Enter key callback
+  onChange?: (value: string) => void;              // Value change callback
+}
+```
 
+**Example:**
 ```tsx
 <GlobalVirtualKeyboard
-  enabled={true}           // Enable/disable the keyboard
-  className="my-theme"     // Custom CSS class
-  onVisibilityChange={(visible) => {}}  // Called when keyboard shows/hides
-  onEnterClick={() => {}}  // Called when Enter is pressed
-  onChange={(value) => {}} // Called when value changes
+  enabled={true}
+  onEnterClick={() => console.log('Enter pressed!')}
+  onChange={(value) => console.log('Value:', value)}
 />
 ```
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `enabled` | `boolean` | `true` | Enable/disable the keyboard |
-| `className` | `string` | - | Additional CSS class name |
-| `onVisibilityChange` | `(isVisible: boolean) => void` | - | Callback when visibility changes |
-| `onEnterClick` | `() => void` | - | Callback when Enter key is pressed |
-| `onChange` | `(value: string) => void` | - | Callback when value changes |
-
-### VirtualKeyboard
-
-Manual control over keyboard display. Use when you need precise control.
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `focusedInputRef` | `RefObject<HTMLInputElement \| HTMLTextAreaElement>` | **required** | Ref to the currently focused input element |
-| `isInputFocused` | `boolean` | **required** | Whether an input is currently focused |
-| `inputType` | `HTMLInputTypeAttribute` | `'text'` | Type of input (affects layout and validation) |
-| `onEnterClick` | `() => void` | - | Callback when Enter key is pressed |
-| `onChange` | `(value: string) => void` | - | Callback when value changes |
-| `className` | `string` | - | Additional CSS class name |
-| `defaultLayout` | `'letters' \| 'symbols' \| 'numbers'` | `'letters'` | Default keyboard layout |
-| `validate` | `(value: string) => boolean` | - | Custom validation function |
-
-## Input Type Behaviors
+---
 
-The keyboard automatically adapts based on `inputType`:
+### `<VirtualKeyboard />`
 
-- **`text`**: Shows QWERTY layout, allows all characters
-- **`email`**: Shows QWERTY layout with quick access `.` and `@` keys
-- **`number`**: Shows numeric keypad, only allows digits
-- **`tel`**: Shows QWERTY layout, validates phone characters
-- **`password`**: Shows QWERTY layout, allows all characters
-- **`url`**: Shows QWERTY layout, validates URL characters
+Main keyboard component with extensive customization options.
 
-## Theming
-
-### Using CSS Variables
-
-```css
-:root {
-  --vk-bg-color: #1a1a1a;
-  --vk-key-color: #444444;
-  --vk-key-text-color: #ffffff;
-  --vk-key-active-color: #666666;
-  --vk-key-hover-color: #555555;
-  --vk-active-state-color: #4a90e2;
-  --vk-key-border-radius: 0.5vw;
-  --vk-key-font-size: 32px;
-  --vk-gap: 0.75vw;
-  --vk-padding: 1vw;
-  --vk-height: 35vh;
-  --vk-z-index: 2001;
+```tsx
+interface VirtualKeyboardProps {
+  // Required props
+  focusedInputRef: RefObject<HTMLInputElement | HTMLTextAreaElement | null>;
+  isInputFocused: boolean;
+  
+  // Layout & behavior
+  inputType?: 'text' | 'email' | 'number' | etc;  // HTML input type
+  defaultLayout?: 'letters' | 'symbols' | 'numbers';
+  syncWithHardwareKeyboard?: boolean;             // Enable hardware sync (default: true)
+  
+  // Callbacks
+  onEnterClick?: () => void;
+  onChange?: (value: string) => void;
+  validate?: (value: string) => boolean;          // Custom validation
+  
+  // Customization
+  className?: string;
+  theme?: VirtualKeyboardTheme;
+  customLayouts?: {
+    letters?: string[][];
+    symbols?: string[][];
+    numbers?: string[][];
+  };
+  
+  // Key customization
+  keyLabels?: Record<string, string>;             // Custom key labels
+  hiddenKeys?: string[];                          // Keys to hide
+  disabledKeys?: string[];                        // Keys to disable
+  renderKey?: (key: string, defaultRender: ReactNode) => ReactNode;
+  renderSpecialKey?: (type: string, defaultRender: ReactNode) => ReactNode;
+  
+  // Behavior configuration
+  continuousPressConfig?: {
+    initialDelay?: number;                        // Default: 500ms
+    interval?: number;                            // Default: 50ms
+  };
+  scrollConfig?: {
+    enabled?: boolean;
+    offset?: number;
+  };
 }
 ```
 
-### Built-in Theme Classes
-
+**Example with customization:**
 ```tsx
 <VirtualKeyboard
-  className="vk-container--light"  // Light theme
-  // or
-  className="vk-container--blue"   // Blue theme
-  // or
-  className="vk-container--purple" // Purple theme
-  {...props}
+  focusedInputRef={inputRef}
+  isInputFocused={isInputFocused}
+  
+  // Custom key labels
+  keyLabels={{
+    enter: 'Submit',
+    space: 'Space Bar',
+    backspace: 'Del'
+  }}
+  
+  // Hide specific keys
+  hiddenKeys={['capslock']}
+  
+  // Disable certain keys
+  disabledKeys={['@', '#']}
+  
+  // Custom layout
+  customLayouts={{
+    letters: [
+      ['q', 'w', 'e', 'r', 't', 'y'],
+      ['a', 's', 'd', 'f', 'g', 'h'],
+      ['z', 'x', 'c', 'v', 'b', 'n']
+    ]
+  }}
+  
+  // Adjust continuous press behavior
+  continuousPressConfig={{
+    initialDelay: 300,
+    interval: 40
+  }}
+  
+  // Disable hardware keyboard sync
+  syncWithHardwareKeyboard={false}
 />
 ```
 
-### Custom Theme Example
+---
+
+## 🎨 Theming
+
+### Using CSS Variables
 
 ```css
-.my-custom-theme {
-  --vk-bg-color: #2d3748;
-  --vk-key-color: #4a5568;
-  --vk-key-text-color: #e2e8f0;
-  --vk-key-hover-color: #718096;
-  --vk-key-active-color: #a0aec0;
-  --vk-active-state-color: #48bb78;
+.vk-container {
+  --vk-bg-color: #2c3e50;
+  --vk-key-color: #34495e;
+  --vk-key-text-color: #ecf0f1;
+  --vk-key-active-color: #3498db;
+  --vk-key-hover-color: #2c3e50;
+  --vk-active-state-color: #e74c3c;
+  --vk-key-border-radius: 8px;
+  --vk-key-font-size: 18px;
+  --vk-key-height: 50px;
 }
 ```
 
-## Hooks
+### Theme Object
 
-### useCaretManager
+```tsx
+const darkTheme = {
+  backgroundColor: '#1a1a1a',
+  keyColor: '#2d2d2d',
+  keyTextColor: '#ffffff',
+  keyActiveColor: '#0066cc',
+  keyHoverColor: '#3d3d3d',
+  activeStateColor: '#00cc66',
+  keyBorderRadius: '6px',
+  keyFontSize: '16px',
+  keyHeight: '48px'
+};
+
+<VirtualKeyboard theme={darkTheme} {...props} />
+```
 
-Manages caret position and text insertion/deletion:
+---
 
-```tsx
-import { useCaretManager } from 'reactjs-virtual-keyboard';
+## 🔧 Utility Functions & Hooks
 
-function CustomKeyboard() {
-  const inputRef = useRef<HTMLInputElement>(null);
-  const { insertText, backspace } = useCaretManager(inputRef);
+For advanced use cases, you can import utilities directly:
 
-  return (
-    <button onClick={() => insertText('Hello')}>Insert Text</button>
-    <button onClick={backspace}>Delete</button>
-  );
-}
+```tsx
+import {
+  // Caret management
+  createCaretManager,
+  
+  // Hardware keyboard event handling
+  setupHardwareKeyboard,
+  
+  // Validation utilities
+  validateValueUtil,
+  getInitialLayout,
+  
+  // Scroll utilities
+  scrollInputIntoView,
+  resetScrollPosition,
+  
+  // Input value sync
+  setInputValueAndDispatchEvents,
+  
+  // Hooks (only for React state/effects)
+  useContinuousPress,
+  useKeyboardScroll
+} from 'reactjs-virtual-keyboard';
 ```
 
-### useContinuousPress
+### `createCaretManager`
 
-Handle hold-to-repeat functionality:
+Pure function for managing caret position and text manipulation:
 
 ```tsx
-import { useContinuousPress } from 'reactjs-virtual-keyboard';
+import { createCaretManager } from 'reactjs-virtual-keyboard';
 
-function DeleteButton({ onDelete }) {
-  const handlers = useContinuousPress(onDelete, {
-    initialDelay: 500, // Start repeating after 500ms
-    interval: 50,      // Repeat every 50ms
-  });
+const inputRef = useRef<HTMLInputElement>(null);
+const { insertText, backspace } = createCaretManager(() => inputRef.current);
 
-  return <button {...handlers}>Delete</button>;
-}
+// Insert text at caret position
+insertText('Hello');
+
+// Delete character before caret
+backspace();
 ```
 
-### useHardwareKeyboard
+### `setupHardwareKeyboard`
 
-Sync with physical keyboard events:
+Set up hardware keyboard event listeners:
 
 ```tsx
-import { useHardwareKeyboard } from 'reactjs-virtual-keyboard';
+import { setupHardwareKeyboard } from 'reactjs-virtual-keyboard';
 
-function KeyboardHandler() {
-  useHardwareKeyboard({
-    isInputFocused: true,
+useEffect(() => {
+  const cleanup = setupHardwareKeyboard({
     onBackspace: () => console.log('Backspace'),
     onEnter: () => console.log('Enter'),
     onSpace: () => console.log('Space'),
-    onCapsToggle: () => console.log('Caps Lock'),
-    onKeyClick: (key) => console.log('Key:', key),
+    onCapsToggle: () => console.log('Caps'),
+    onKeyClick: (key) => console.log('Key:', key)
   });
-}
+  
+  return cleanup; // Clean up listeners
+}, []);
 ```
 
-### useKeyboardScroll
+---
+
+## 📱 Input Type Behaviors
+
+The keyboard automatically adapts to different input types:
+
+| Input Type | Layout | Special Keys | Validation |
+|-----------|--------|--------------|------------|
+| `text` | QWERTY | All | None |
+| `email` | QWERTY + @ | Space, @ | Email chars only |
+| `number` | Numbers only | Backspace, Enter | Digits only |
+| `tel` | Numbers | Phone chars | Digits, +, - |
+| `url` | QWERTY | .com, www. | URL chars |
 
-Automatically scroll inputs into view when keyboard appears:
+---
+
+## 🎯 Custom Layouts Example
 
 ```tsx
-import { useKeyboardScroll } from 'reactjs-virtual-keyboard';
+const customLayouts = {
+  letters: [
+    ['a', 'b', 'c', 'd', 'e'],
+    ['f', 'g', 'h', 'i', 'j'],
+    ['k', 'l', 'm', 'n', 'o'],
+    ['p', 'q', 'r', 's', 't'],
+    ['u', 'v', 'w', 'x', 'y', 'z']
+  ],
+  symbols: [
+    ['!', '@', '#', '$', '%'],
+    ['^', '&', '*', '(', ')'],
+    ['-', '_', '=', '+', '['],
+    [']', '{', '}', '|', '\\']
+  ]
+};
 
-function MyComponent() {
-  const { scrollInput, resetScroll } = useKeyboardScroll();
+<VirtualKeyboard
+  {...props}
+  customLayouts={customLayouts}
+/>
+```
 
-  const handleFocus = (e: FocusEvent) => {
-    const input = e.target as HTMLInputElement;
-    scrollInput(input); // Shifts content up if input would be covered
-  };
+---
 
-  const handleBlur = () => {
-    resetScroll(); // Restores original position
-  };
+## 🎭 Custom Render Functions
 
-  return <input onFocus={handleFocus} onBlur={handleBlur} />;
-}
+```tsx
+<VirtualKeyboard
+  {...props}
+  renderKey={(key, defaultRender) => (
+    <div className="my-custom-key">
+      {key.toUpperCase()}
+    </div>
+  )}
+  renderSpecialKey={(type, defaultRender) => {
+    if (type === 'enter') {
+      return <button className="submit-btn">Submit</button>;
+    }
+    return defaultRender;
+  }}
+/>
 ```
 
-The hook automatically:
-- Calculates if the input would be covered by the keyboard
-- Smoothly transitions content up to keep input visible
-- Resets position when keyboard hides
-- Cleans up on component unmount
+---
 
-## Custom Layouts
+## 📦 Bundle Size
 
-You can use the individual layout components:
+- **ESM**: 26.14 kB minified (6.28 kB gzipped)
+- **CJS**: 12.56 kB minified (4.69 kB gzipped)
+- **CSS**: 6.03 kB (1.68 kB gzipped)
 
-```tsx
-import {
-  KeyboardLayout,
-  TextLayout,
-  NumbersLayout,
-  QWERTY_LAYOUT,
-  SYMBOLS_LAYOUT,
-  NUMBERS_LAYOUT,
-} from 'reactjs-virtual-keyboard';
+Tree-shaking enabled - import only what you need!
 
-// Use predefined layouts or create custom ones
-const CUSTOM_LAYOUT = [
-  ['A', 'B', 'C'],
-  ['D', 'E', 'F'],
-  ['G', 'H', 'I'],
-];
-```
+---
 
-## Accessibility
+## 🌐 Browser Support
 
-The keyboard includes:
+- **Modern Browsers**: Chrome, Firefox, Safari, Edge (last 2 versions)
+- **Mobile**: iOS Safari, Chrome Mobile, Samsung Internet
+- Requires React 16.8+ (hooks support)
 
-- Focus management to prevent input blur when clicking keys
-- `aria-label` attributes on special keys
-- Keyboard navigation support
-- Respects `prefers-reduced-motion` for animations
+---
 
-## Browser Support
+## 🛠️ Development
 
-- Chrome 60+
-- Firefox 55+
-- Safari 11+
-- Edge 79+
+```bash
+# Clone repository
+git clone https://github.com/yourusername/reactjs-virtual-keyboard.git
 
-## TypeScript
+# Install dependencies
+npm install
 
-All types are exported:
+# Build library
+npm run build
 
-```tsx
-import type {
-  VirtualKeyboardProps,
-  VirtualKeyboardTheme,
-  GlobalVirtualKeyboardProps,
-  UseKeyboardScrollReturn,
-  LayoutType,
-  KeyboardLayoutProps,
-} from 'reactjs-virtual-keyboard';
+# Run demo (if available)
+cd demo && npm install && npm run dev
 ```
 
-## License
+---
+
+## 📄 License
+
+MIT © Kalpesh Rane
+
+---
+
+## 🤝 Contributing
+
+Contributions welcome! Please open an issue or submit a PR.
+
+---
+
+## 📝 Changelog
+
+### v2.0.0 (Latest)
+- ✨ **New**: Multi-language support with built-in language switcher
+- ✨ Added `languages`, `currentLanguage`, `onLanguageChange`, `showLanguageSwitcher` props
+- ✨ Enhanced customization API (24+ new props)
+- ⚡ Removed unnecessary hook wrappers for better performance
+- 📦 Optimized bundle size with better tree-shaking
+- 🏗️ Reorganized file structure for clarity
+- 🔧 Exported utility functions for advanced usage
+- 📘 Improved TypeScript types with ReadonlyArray support
+- 📚 Complete documentation website with interactive playground
 
-MIT © kalpesh442266
+### v1.0.0
+- 🎉 Initial release