{"_id":"@dwack1234/arabic-keyboard-nextjs","_rev":"7-77cab41fc3146ded1eb00b879708f83c","name":"@dwack1234/arabic-keyboard-nextjs","dist-tags":{"latest":"1.0.7"},"versions":{"1.0.5":{"name":"@dwack1234/arabic-keyboard-nextjs","version":"1.0.5","keywords":["arabic","keyboard","nextjs","react","typescript","virtual-keyboard","arabic-keyboard","tashkeel","diacritics","rtl"],"author":{"name":"d-wack"},"license":"MIT","_id":"@dwack1234/arabic-keyboard-nextjs@1.0.5","maintainers":[{"name":"dwack1234","email":"brandonpaulbailey@gmail.com"}],"homepage":"https://github.com/d-wack/arabic-keyboard-nextjs#readme","bugs":{"url":"https://github.com/d-wack/arabic-keyboard-nextjs/issues"},"dist":{"shasum":"a83f1908abc70caffe76331033ec0e8545d20047","tarball":"https://registry.npmjs.org/@dwack1234/arabic-keyboard-nextjs/-/arabic-keyboard-nextjs-1.0.5.tgz","fileCount":84,"integrity":"sha512-2fTavsp3uLI6j061B1G4zLM2R4XM5BOcyxNkt/1/7Hc4BM9q5tUxBD0EFhjnRtOIzXRDsRLPfAMqhPTDaosaEA==","signatures":[{"sig":"MEUCIBtvyCped0FutR6y+xZMo0pApeBTeLo/zYlO5i6QasNpAiEA8O8kamzTxEhbigSuZ6SbgQ/fa5Jk5gLOA3vQkQ/INdc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":364112},"main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"},"./styles":"./dist/styles.css","./sounds/*":"./sounds/*"},"gitHead":"12d28d6b552e364e74931dea4ccf7e9b9a8ab8ed","scripts":{"dev":"next dev","lint":"eslint","test":"jest","build":"next build","start":"next start","build:ts":"tsc --project tsconfig.build.json","build:css":"node scripts/build-css.js","test:watch":"jest --watch","build:sounds":"mkdir -p sounds && cp src/assets/sounds/*.ogg sounds/","build:package":"npm run build:ts && npm run build:css && npm run build:sounds","test:coverage":"jest --coverage","prepublishOnly":"npm run test && npm run build:package"},"_npmUser":{"name":"dwack1234","email":"brandonpaulbailey@gmail.com"},"repository":{"url":"git+https://github.com/d-wack/arabic-keyboard-nextjs.git","type":"git"},"_npmVersion":"10.9.4","description":"A full-featured Arabic keyboard component for Next.js and React applications","directories":{},"_nodeVersion":"22.21.0","dependencies":{"react":"19.2.0","react-dom":"19.2.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.2.0","next":"16.0.0","eslint":"^9","typescript":"^5","@types/jest":"^30.0.0","@types/node":"^20","tailwindcss":"^4","@types/react":"^19","@types/react-dom":"^19","eslint-config-next":"16.0.0","@tailwindcss/postcss":"^4","@testing-library/react":"^16.3.0","jest-environment-jsdom":"^30.2.0","@testing-library/jest-dom":"^6.9.1","@testing-library/user-event":"^14.6.1"},"peerDependencies":{"next":"^14.0.0 || ^15.0.0 || ^16.0.0","react":"^18.0.0 || ^19.0.0","react-dom":"^18.0.0 || ^19.0.0"},"peerDependenciesMeta":{"next":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/arabic-keyboard-nextjs_1.0.5_1761589516015_0.10211993706984135","host":"s3://npm-registry-packages-npm-production"}},"1.0.6":{"name":"@dwack1234/arabic-keyboard-nextjs","version":"1.0.6","keywords":["arabic","keyboard","nextjs","react","typescript","virtual-keyboard","arabic-keyboard","tashkeel","diacritics","rtl"],"author":{"name":"d-wack"},"license":"MIT","_id":"@dwack1234/arabic-keyboard-nextjs@1.0.6","maintainers":[{"name":"dwack1234","email":"brandonpaulbailey@gmail.com"}],"homepage":"https://github.com/d-wack/arabic-keyboard-nextjs#readme","bugs":{"url":"https://github.com/d-wack/arabic-keyboard-nextjs/issues"},"dist":{"shasum":"d4edc981b9b6ce962c7958733f577a07215f7206","tarball":"https://registry.npmjs.org/@dwack1234/arabic-keyboard-nextjs/-/arabic-keyboard-nextjs-1.0.6.tgz","fileCount":84,"integrity":"sha512-WBWEQHxZIQOqDfKQR3VtU9bhW4Aoam0ci+AYwBLMgGhqy+vOpjZ1ibFwAls8tzc8J7yCKL2NSNOF2hBoScyyEA==","signatures":[{"sig":"MEUCIQCwDKrmCRTTqQOnS0fZjMeD7c0KpvSK8+Z3NxyIJcANggIgJgOog2OcbQcouhDtpatL36FPYuzu0mvEGPSB3mQWGqU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":364216},"main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"},"./styles":"./dist/styles.css","./sounds/*":"./sounds/*"},"gitHead":"12d28d6b552e364e74931dea4ccf7e9b9a8ab8ed","scripts":{"dev":"next dev","lint":"eslint","test":"jest","build":"next build","start":"next start","build:ts":"tsc --project tsconfig.build.json && tsc-alias -p tsconfig.build.json","build:css":"node scripts/build-css.js","test:watch":"jest --watch","build:sounds":"mkdir -p sounds && cp src/assets/sounds/*.ogg sounds/","build:package":"npm run build:ts && npm run build:css && npm run build:sounds","test:coverage":"jest --coverage","prepublishOnly":"npm run test && npm run build:package"},"_npmUser":{"name":"dwack1234","email":"brandonpaulbailey@gmail.com"},"repository":{"url":"git+https://github.com/d-wack/arabic-keyboard-nextjs.git","type":"git"},"_npmVersion":"10.9.4","description":"A full-featured Arabic keyboard component for Next.js and React applications","directories":{},"_nodeVersion":"22.21.0","dependencies":{"react":"^18.0.0 || ^19.0.0","react-dom":"^18.0.0 || ^19.0.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.2.0","next":"16.0.0","eslint":"^9","tsc-alias":"^1.8.16","typescript":"^5","@types/jest":"^30.0.0","@types/node":"^20","tailwindcss":"^4","@types/react":"^19","@types/react-dom":"^19","eslint-config-next":"16.0.0","@tailwindcss/postcss":"^4","@testing-library/react":"^16.3.0","jest-environment-jsdom":"^30.2.0","@testing-library/jest-dom":"^6.9.1","@testing-library/user-event":"^14.6.1"},"peerDependencies":{"next":"^14.0.0 || ^15.0.0 || ^16.0.0","react":"^18.0.0 || ^19.0.0","react-dom":"^18.0.0 || ^19.0.0"},"peerDependenciesMeta":{"next":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/arabic-keyboard-nextjs_1.0.6_1761589995363_0.48389049252488103","host":"s3://npm-registry-packages-npm-production"}},"1.0.7":{"name":"@dwack1234/arabic-keyboard-nextjs","version":"1.0.7","description":"A full-featured Arabic keyboard component for Next.js and React applications","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"},"./styles":"./dist/styles.css","./sounds/*":"./sounds/*"},"keywords":["arabic","keyboard","nextjs","react","typescript","virtual-keyboard","arabic-keyboard","tashkeel","diacritics","rtl"],"author":{"name":"d-wack"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/d-wack/arabic-keyboard-nextjs.git"},"bugs":{"url":"https://github.com/d-wack/arabic-keyboard-nextjs/issues"},"homepage":"https://github.com/d-wack/arabic-keyboard-nextjs#readme","peerDependencies":{"next":"^14.0.0 || ^15.0.0 || ^16.0.0","react":"^18.0.0 || ^19.0.0","react-dom":"^18.0.0 || ^19.0.0"},"peerDependenciesMeta":{"next":{"optional":true}},"scripts":{"dev":"next dev","build":"next build","build:package":"npm run build:ts && npm run build:css && npm run build:sounds","build:ts":"tsc --project tsconfig.build.json && tsc-alias -p tsconfig.build.json","build:css":"node scripts/build-css.js","build:sounds":"mkdir -p sounds && cp src/assets/sounds/*.ogg sounds/","start":"next start","lint":"eslint","test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage","prepublishOnly":"npm run test && npm run build:package"},"dependencies":{"react":"^18.0.0 || ^19.0.0","react-dom":"^18.0.0 || ^19.0.0"},"devDependencies":{"@tailwindcss/postcss":"^4","@testing-library/jest-dom":"^6.9.1","@testing-library/react":"^16.3.0","@testing-library/user-event":"^14.6.1","@types/jest":"^30.0.0","@types/node":"^20","@types/react":"^19","@types/react-dom":"^19","eslint":"^9","eslint-config-next":"16.0.0","jest":"^30.2.0","jest-environment-jsdom":"^30.2.0","next":"16.0.0","tailwindcss":"^4","tsc-alias":"^1.8.16","typescript":"^5"},"_id":"@dwack1234/arabic-keyboard-nextjs@1.0.7","gitHead":"12d28d6b552e364e74931dea4ccf7e9b9a8ab8ed","_nodeVersion":"22.21.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-QAo+Fhtdoc9Bkas0sW/cvLph0DfiJE7/XwgUduVltQ1fBPeStOsb1e+SK7SuqXUEd1+tPUzvj6KSPvJcKlsgAA==","shasum":"e7df004f84e861b5f2cd70f7a12e4ddc737184fa","tarball":"https://registry.npmjs.org/@dwack1234/arabic-keyboard-nextjs/-/arabic-keyboard-nextjs-1.0.7.tgz","fileCount":84,"unpackedSize":364204,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC9fk8sdyntIMSflATfpAHOk4Ia5vzY1DiCPHgAJlqBeAIgT1wC2IsuBJbWsm8KXH1/GEc57/mXpp5rugbvdQ9cRMM="}]},"_npmUser":{"name":"dwack1234","email":"brandonpaulbailey@gmail.com"},"directories":{},"maintainers":[{"name":"dwack1234","email":"brandonpaulbailey@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/arabic-keyboard-nextjs_1.0.7_1761591036025_0.9597406075226316"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-27T18:25:15.912Z","modified":"2025-10-27T18:50:36.411Z","1.0.0":"2025-10-27T17:18:28.896Z","1.0.1":"2025-10-27T17:21:58.251Z","1.0.2":"2025-10-27T17:26:47.514Z","1.0.5":"2025-10-27T18:25:16.181Z","1.0.6":"2025-10-27T18:33:15.607Z","1.0.7":"2025-10-27T18:50:36.236Z"},"bugs":{"url":"https://github.com/d-wack/arabic-keyboard-nextjs/issues"},"author":{"name":"d-wack"},"license":"MIT","homepage":"https://github.com/d-wack/arabic-keyboard-nextjs#readme","keywords":["arabic","keyboard","nextjs","react","typescript","virtual-keyboard","arabic-keyboard","tashkeel","diacritics","rtl"],"repository":{"type":"git","url":"git+https://github.com/d-wack/arabic-keyboard-nextjs.git"},"description":"A full-featured Arabic keyboard component for Next.js and React applications","maintainers":[{"name":"dwack1234","email":"brandonpaulbailey@gmail.com"}],"readme":"# Arabic Keyboard for Next.js\n\nA fully-featured, customizable Arabic virtual keyboard web application built with Next.js 16, React 19, and TypeScript. Features an interactive virtual keyboard for typing Arabic text with support for tashkeel (diacritical marks), Alif variants, and real-time word display.\n\n**Version:** 2.0.0  \n**Last Updated:** October 27, 2025\n\n---\n\n## 📑 Table of Contents\n\n- [Features](#-features)\n- [Getting Started](#-getting-started)\n- [Development Commands](#-development-commands)\n- [Architecture](#-architecture)\n- [Component API](#-component-api)\n- [Keyboard Layouts](#-keyboard-layouts)\n- [Settings & Configuration](#-settings--configuration)\n- [Testing](#-testing)\n- [Browser Support](#-browser-support)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n---\n\n## ✨ Features\n\n### Core Functionality\n- ✅ **Dual Language Support** - Arabic (KBDA1) and English (QWERTY) layouts\n- ✅ **Real-time Character Input** - Character-by-character callback API\n- ✅ **Comprehensive Callback System** - 15+ event callbacks for complete control\n- ✅ **Standalone or Integrated** - Works as pure input device or with text areas\n- ✅ **Modifier Keys** - Shift, Ctrl, Alt support\n- ✅ **Special Characters** - Full Tashkeel (diacritics) support\n- ✅ **Sound Effects** - Keypress, clear, and UI sounds (optional)\n- ✅ **Responsive Design** - Works on all screen sizes\n- ✅ **Floating Words Display** - Completed words float across the screen with random positions and colors\n\n### Advanced Features\n- 🎨 **Extensive Customization** - 100+ settings across 11 categories\n- 🎵 **Sound System** - Multiple sound profiles with volume control\n- 📱 **Touch Optimized** - Smooth touch interactions\n- ♿ **Accessibility** - ARIA labels and keyboard navigation\n- 🌈 **Theme Support** - Multiple built-in themes\n- ⚡ **Performance** - Optimized rendering with React 19\n- 📦 **TypeScript** - Full type safety with comprehensive interfaces\n- 🧪 **Tested** - Unit tests with Jest and React Testing Library\n\n---\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n- Node.js 18+ \n- npm, yarn, or pnpm\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/d-wack/arabic-keyboard-nextjs.git\ncd arabic-keyboard-nextjs\n\n# Install dependencies\nnpm install\n\n# Start development server\nnpm run dev\n```\n\nOpen [http://localhost:3000](http://localhost:3000) to see the application.\n\n---\n\n## 🛠️ Development Commands\n\n### Running the Application\n\n```bash\nnpm run dev          # Start development server (http://localhost:3000)\nnpm run build        # Build for production\nnpm start            # Start production server\n```\n\n### Testing\n\n```bash\nnpm test             # Run all tests with Jest\nnpm run test:watch   # Run tests in watch mode\nnpm run test:coverage # Run tests with coverage report\n```\n\n### Linting\n\n```bash\nnpm run lint         # Run ESLint\n```\n\n---\n\n## 🏛️ Architecture\n\nThe application follows a clean component-based architecture:\n\n### Main Components\n\n1. **`src/app/page.tsx`** - Main page with demo selector and three demo modes:\n   - Original: Floating words demo\n   - Real-Time: Character-by-character display with statistics\n   - Form: Multi-field form integration example\n\n2. **`src/components/ArabicKeyboard.tsx`** - Virtual keyboard component\n   - Supports Arabic (KBDA1) and English (QWERTY) layouts\n   - Three input modes: Normal, Shift (tashkeel), Ctrl (Alif variants)\n   - Comprehensive callback API for integration\n   - Physical keyboard support with visual feedback\n\n3. **`src/components/WordDisplay.tsx`** - Floating word display\n   - Shows completed words as floating elements\n   - Random positions, sizes, colors, and opacity\n   - Click to remove words\n\n4. **`src/context/SettingsContext.tsx`** - Settings management\n   - Centralized settings with localStorage persistence\n   - 11 categories: appearance, layout, behavior, sound, animations, etc.\n\n### Key Features\n\n- **Callback-based API**: Character input, backspace, enter, clear, modifiers\n- **Dual Modes**: Standalone (internal state) or Integrated (external state via callbacks)\n- **Settings System**: 100+ customizable settings with live preview\n- **Language Toggle**: Alt+L keyboard shortcut or UI button\n\n---\n\n## 📚 Component API\n\n### ArabicKeyboard Props\n\n```tsx\ninterface ArabicKeyboardProps {\n  // ===== REQUIRED =====\n  isVisible: boolean;                    // Control keyboard visibility\n  onToggle: () => void;                  // Toggle handler\n\n  // ===== CALLBACK API =====\n  callbacks?: KeyboardCallbacks;         // Event callbacks (see below)\n  mode?: 'standalone' | 'integrated';    // Default: 'standalone'\n\n  // ===== TARGET ELEMENT (Optional) =====\n  targetInputRef?: React.RefObject<HTMLInputElement | HTMLTextAreaElement>;\n  targetInputId?: string;\n  autoFocusTarget?: boolean;             // Default: false\n  syncWithTarget?: boolean;              // Default: true\n\n  // ===== CONTROLLED MODE (Optional) =====\n  value?: string;                        // External text value\n  onValueChange?: (value: string) => void;\n  cursorPosition?: number;\n  onCursorPositionChange?: (position: number) => void;\n\n  // ===== BEHAVIOR =====\n  insertMode?: 'append' | 'cursor';      // Default: 'cursor'\n  textChangeDebounce?: number;           // Default: 0 (ms)\n  emitEventsInStandaloneMode?: boolean;  // Default: false\n\n  // ===== LEGACY =====\n  onWordComplete?: (word: string) => void; // Backward compatible\n}\n```\n\n### Callback API\n\nThe callback API provides 15+ events for complete control over keyboard interactions:\n\n```tsx\ninterface KeyboardCallbacks {\n  // ===== CHARACTER INPUT =====\n  onCharacterInput?: (\n    char: string,\n    metadata: InputMetadata\n  ) => void;\n\n  onBackspace?: (\n    deletedText: string,\n    metadata: Omit<InputMetadata, 'keyType'>\n  ) => void;\n\n  onTextChange?: (\n    newText: string,\n    previousText: string,\n    changeType: 'insert' | 'delete' | 'clear' | 'external',\n    metadata: InputMetadata\n  ) => void;\n\n  // ===== WORD & SUBMISSION =====\n  onWordComplete?: (word: string) => void;\n  \n  onEnter?: (\n    currentText: string,\n    metadata: Omit<InputMetadata, 'keyType'>\n  ) => void;\n\n  onClear?: (\n    clearedText: string,\n    metadata: Omit<InputMetadata, 'keyType'>\n  ) => void;\n\n  // ===== MODIFIER KEYS =====\n  onShiftToggle?: (isPressed: boolean) => void;\n  onCtrlToggle?: (isPressed: boolean) => void;\n  onAltToggle?: (isPressed: boolean) => void;\n\n  // ===== CURSOR CONTROL =====\n  onCursorMove?: (\n    newPosition: number,\n    oldPosition: number\n  ) => void;\n\n  onTextSelect?: (\n    selectedText: string,\n    startPos: number,\n    endPos: number\n  ) => void;\n\n  // ===== KEYBOARD STATE =====\n  onKeyboardOpen?: () => void;\n  onKeyboardClose?: () => void;\n\n  onLanguageChange?: (\n    newLanguage: 'ar' | 'en',\n    previousLanguage: 'ar' | 'en'\n  ) => void;\n\n  // ===== SPECIAL KEYS =====\n  onSpacePressed?: () => void;\n  onTabPressed?: () => void;\n}\n```\n\n### InputMetadata\n\nEvery callback includes metadata about the input context:\n\n```tsx\ninterface InputMetadata {\n  keyType: 'letter' | 'number' | 'tashkeel' | 'special' | 'modifier';\n  language: 'ar' | 'en';\n  timestamp: number;\n  cursorPosition: number;\n  textLength: number;\n  isShiftPressed: boolean;\n  isCtrlPressed: boolean;\n  isAltPressed: boolean;\n  insertMode: 'append' | 'cursor';\n}\n```\n\n---\n\n## 💡 Usage Examples\n\nSee the live examples in the application:\n- **Original Demo**: Floating words display (default view)\n- **Real-Time Demo**: Character tracking with statistics  \n- **Form Demo**: Multi-field form integration\n\n### Basic Integration\n\n### Example 1: Real-Time Display\n\n```tsx\n'use client';\n\nimport { useState, useMemo } from 'react';\nimport ArabicKeyboard from '@/components/ArabicKeyboard';\nimport type { KeyboardCallbacks } from '@/types/keyboard.types';\n\nexport default function RealTimeExample() {\n  const [displayText, setDisplayText] = useState('');\n  const [eventLog, setEventLog] = useState<string[]>([]);\n  const [stats, setStats] = useState({\n    totalKeystrokes: 0,\n    letters: 0,\n    numbers: 0,\n    tashkeel: 0,\n  });\n\n  const callbacks: KeyboardCallbacks = useMemo(() => ({\n    onCharacterInput: (char, metadata) => {\n      setDisplayText(prev => prev + char);\n      setStats(prev => ({\n        ...prev,\n        totalKeystrokes: prev.totalKeystrokes + 1,\n        letters: metadata.keyType === 'letter' ? prev.letters + 1 : prev.letters,\n        numbers: metadata.keyType === 'number' ? prev.numbers + 1 : prev.numbers,\n        tashkeel: metadata.keyType === 'tashkeel' ? prev.tashkeel + 1 : prev.tashkeel,\n      }));\n    },\n\n    onBackspace: (deletedText) => {\n      setDisplayText(prev => prev.slice(0, -deletedText.length));\n    },\n\n    onEnter: () => {\n      setDisplayText(prev => prev + '\\n');\n    },\n\n    onClear: () => {\n      setDisplayText('');\n    },\n\n    onWordComplete: (word) => {\n      setEventLog(prev => [...prev, `Word: ${word}`]);\n    },\n  }), []);\n\n  return (\n    <div>\n      <div className=\"display\" dir=\"rtl\">\n        {displayText || 'Start typing...'}\n      </div>\n      \n      <div className=\"stats\">\n        <p>Keystrokes: {stats.totalKeystrokes}</p>\n        <p>Letters: {stats.letters}</p>\n        <p>Numbers: {stats.numbers}</p>\n        <p>Tashkeel: {stats.tashkeel}</p>\n      </div>\n\n      <ArabicKeyboard\n        isVisible={true}\n        onToggle={() => {}}\n        callbacks={callbacks}\n        mode=\"integrated\"\n      />\n    </div>\n  );\n}\n```\n\n### Example 2: Form Integration\n\n```tsx\n'use client';\n\nimport { useState, useMemo } from 'react';\nimport ArabicKeyboard from '@/components/ArabicKeyboard';\nimport type { KeyboardCallbacks } from '@/types/keyboard.types';\n\nexport default function FormExample() {\n  const [currentField, setCurrentField] = useState<'name' | 'email' | 'bio' | null>(null);\n  const [formData, setFormData] = useState({\n    name: '',\n    email: '',\n    bio: '',\n  });\n\n  const callbacks: KeyboardCallbacks = useMemo(() => ({\n    onCharacterInput: (char) => {\n      if (!currentField) return;\n      setFormData(prev => ({\n        ...prev,\n        [currentField]: prev[currentField] + char,\n      }));\n    },\n\n    onBackspace: () => {\n      if (!currentField) return;\n      setFormData(prev => ({\n        ...prev,\n        [currentField]: prev[currentField].slice(0, -1),\n      }));\n    },\n\n    onEnter: () => {\n      // Auto-advance to next field\n      if (currentField === 'name') setCurrentField('email');\n      else if (currentField === 'email') setCurrentField('bio');\n    },\n\n    onKeyboardClose: () => {\n      setCurrentField(null);\n    },\n  }), [currentField]);\n\n  return (\n    <form>\n      <input\n        type=\"text\"\n        value={formData.name}\n        onFocus={() => setCurrentField('name')}\n        placeholder=\"Name\"\n      />\n      \n      <input\n        type=\"text\"\n        value={formData.email}\n        onFocus={() => setCurrentField('email')}\n        placeholder=\"Email\"\n      />\n      \n      <textarea\n        value={formData.bio}\n        onFocus={() => setCurrentField('bio')}\n        placeholder=\"Bio\"\n      />\n\n      <ArabicKeyboard\n        isVisible={currentField !== null}\n        onToggle={() => setCurrentField(null)}\n        callbacks={callbacks}\n        mode=\"integrated\"\n      />\n    </form>\n  );\n}\n```\n\n### Example 3: Controlled Mode\n\n```tsx\n'use client';\n\nimport { useState } from 'react';\nimport ArabicKeyboard from '@/components/ArabicKeyboard';\n\nexport default function ControlledExample() {\n  const [text, setText] = useState('');\n  const [cursor, setCursor] = useState(0);\n\n  return (\n    <>\n      <textarea\n        value={text}\n        onChange={(e) => setText(e.target.value)}\n        onSelect={(e) => setCursor(e.currentTarget.selectionStart)}\n      />\n\n      <ArabicKeyboard\n        isVisible={true}\n        onToggle={() => {}}\n        value={text}\n        onValueChange={setText}\n        cursorPosition={cursor}\n        onCursorPositionChange={setCursor}\n        mode=\"integrated\"\n      />\n    </>\n  );\n}\n```\n\n---\n\n## ⌨️ Keyboard Layouts\n\n### Arabic Layout (KBDA1)\n\nStandard Arabic keyboard layout with full Tashkeel support:\n\n**Row 1:** ` 1 2 3 4 5 6 7 8 9 0 - = Backspace`  \n**Row 2:** Tab ض ص ث ق ف غ ع ه خ ح ج د \\  \n**Row 3:** Shift ش س ي ب ل ا ت ن م ك ط Enter  \n**Row 4:** Ctrl ئ ء ؤ ر لا ى ة و ز ظ / Shift  \n**Row 5:** Alt Space Alt\n\n**Tashkeel (Diacritics):**\n- Fatha (َ), Damma (ُ), Kasra (ِ)\n- Sukun (ْ), Shadda (ّ), Tanween variants\n- Hamza variants, Alef variants\n\n### English Layout (QWERTY)\n\nStandard QWERTY layout with full punctuation:\n\n**Row 1:** ` 1 2 3 4 5 6 7 8 9 0 - = Backspace`  \n**Row 2:** Tab Q W E R T Y U I O P [ ] \\  \n**Row 3:** Shift A S D F G H J K L ; ' Enter  \n**Row 4:** Ctrl Z X C V B N M , . / Shift  \n**Row 5:** Alt Space Alt\n\n---\n\n## ⚙️ Settings & Configuration\n\nThe keyboard includes comprehensive settings across 11 categories:\n\n### 1. Appearance & Theme\n\n```tsx\nappearance: {\n  theme: 'dark' | 'light' | 'high-contrast' | 'minimal' | 'colorful' | 'custom',\n  keyboardBackground: string,      // CSS color\n  regularKeyColor: string,\n  numberKeyColor: string,\n  tashkeelKeyColor: string,\n  specialKeyColors: {\n    backspace: string,\n    enter: string,\n    space: string,\n    clear: string,\n    shift: string,\n    ctrl: string,\n    alt: string,\n  },\n}\n```\n\n### 2. Layout & Positioning\n\n```tsx\nlayout: {\n  position: 'bottom-center' | 'bottom-left' | 'bottom-right' | \n            'top-center' | 'top-left' | 'top-right' | 'floating',\n  width: 'full' | 'auto' | number,     // px or percentage\n  height: 'auto' | number,              // px\n  keySize: 'small' | 'medium' | 'large' | number,\n  keySpacing: 'tight' | 'normal' | 'relaxed' | number,\n  rowSpacing: 'tight' | 'normal' | 'relaxed' | number,\n  borderRadius: number,                 // px\n  padding: number,                      // px\n}\n```\n\n### 3. Behavior\n\n```tsx\nbehavior: {\n  autoCapitalize: boolean,\n  doubleClickDelay: number,             // ms\n  longPressDelay: number,               // ms\n  repeatDelay: number,                  // ms for key repeat\n  repeatInterval: number,               // ms\n  closeOnClickOutside: boolean,\n  closeOnEnter: boolean,\n  closeOnEscape: boolean,\n}\n```\n\n### 4. Sound Effects\n\n```tsx\nsound: {\n  enabled: boolean,\n  volume: number,                       // 0-100\n  keypress: {\n    enabled: boolean,\n    sound: 'click' | 'tap' | 'mechanical' | 'silent' | 'custom',\n    volume: number,\n  },\n  clear: {\n    enabled: boolean,\n    sound: string,\n    volume: number,\n  },\n  enter: {\n    enabled: boolean,\n    sound: string,\n    volume: number,\n  },\n}\n```\n\n### 5. Animations\n\n```tsx\nanimations: {\n  enabled: boolean,\n  slideIn: boolean,\n  slideOut: boolean,\n  duration: number,                     // ms\n  keyHoverEffect: 'none' | 'scale' | 'glow' | 'lift',\n  keyPressEffect: 'none' | 'ripple' | 'scale' | 'glow',\n}\n```\n\n### 6. Language Settings\n\n```tsx\nlanguage: {\n  default: 'ar' | 'en',\n  allowToggle: boolean,\n  showLanguageIndicator: boolean,\n  rtlDirection: boolean,\n}\n```\n\n### 7. Special Keys\n\n```tsx\nspecialKeys: {\n  showTashkeel: boolean,\n  showNumbers: boolean,\n  showEnglish: boolean,\n  showEmoji: boolean,\n  customKeys: Array<{\n    label: string,\n    value: string,\n    position: number,\n  }>,\n}\n```\n\n### 8. Accessibility\n\n```tsx\naccessibility: {\n  ariaLabels: boolean,\n  keyboardNavigation: boolean,\n  highContrast: boolean,\n  screenReaderAnnouncements: boolean,\n  focusIndicator: boolean,\n}\n```\n\n### 9. Performance\n\n```tsx\nperformance: {\n  virtualScrolling: boolean,\n  memoization: boolean,\n  lazyLoadSounds: boolean,\n  debounceDelay: number,                // ms\n}\n```\n\n### 10. Display\n\n```tsx\ndisplay: {\n  showTextArea: boolean,                // Deprecated in v2.0\n  textAreaHeight: number,\n  fontSize: number,\n  fontFamily: string,\n  showClearButton: boolean,\n  showCloseButton: boolean,\n}\n```\n\n### 11. Advanced\n\n```tsx\nadvanced: {\n  enableLogging: boolean,\n  debugMode: boolean,\n  customCSS: string,\n  allowMultipleInstances: boolean,\n}\n```\n\n### Using Settings\n\n```tsx\nimport { SettingsProvider, useSettings } from '@/context/SettingsContext';\n\nfunction App() {\n  return (\n    <SettingsProvider initialSettings={{\n      appearance: { theme: 'dark' },\n      sound: { enabled: true, volume: 75 },\n      layout: { position: 'bottom-center' },\n    }}>\n      <MyKeyboardComponent />\n    </SettingsProvider>\n  );\n}\n\nfunction MyKeyboardComponent() {\n  const { settings, updateSettings } = useSettings();\n\n  return (\n    <ArabicKeyboard\n      isVisible={true}\n      onToggle={() => {}}\n      // Settings are automatically applied via context\n    />\n  );\n}\n```\n\n---\n\n## 🔤 TypeScript Support\n\nFull TypeScript support with comprehensive type definitions:\n\n```tsx\nimport type {\n  ArabicKeyboardProps,\n  KeyboardCallbacks,\n  InputMetadata,\n  KeyboardSettings,\n  KeyType,\n  Language,\n} from '@/types/keyboard.types';\n```\n\n### Key Types\n\n```tsx\ntype KeyType = 'letter' | 'number' | 'tashkeel' | 'special' | 'modifier';\ntype Language = 'ar' | 'en';\ntype InsertMode = 'append' | 'cursor';\ntype ChangeType = 'insert' | 'delete' | 'clear' | 'external';\n```\n\n---\n\n## 🌐 Browser Support\n\n- ✅ Chrome 90+\n- ✅ Firefox 88+\n- ✅ Safari 14+\n- ✅ Edge 90+\n- ✅ Mobile browsers (iOS Safari, Chrome Mobile)\n\n**Requirements:**\n- React 18+ (React 19 recommended)\n- Next.js 14+ (Next.js 15+ recommended)\n- Modern browser with ES6 support\n\n---\n\n## 🧪 Testing\n\nThe project includes comprehensive unit tests using Jest and React Testing Library.\n\n### Running Tests\n\n```bash\nnpm test                 # Run all tests\nnpm test -- --watch      # Watch mode\nnpm test -- --coverage   # With coverage report\n```\n\n### Test Structure\n\nTests are organized in `src/components/__tests__/`:\n- `ArabicKeyboard.test.tsx` - Keyboard component tests\n- `WordDisplay.test.tsx` - Floating words display tests\n- `Settings.test.tsx` - Settings context and modal tests\n\n### Test Coverage\n\n- Visibility and toggle behavior\n- Keyboard key rendering (Arabic/English layouts)\n- Callback integration (character input, backspace, etc.)\n- Modifier keys (Shift, Ctrl, Alt)\n- Settings persistence\n- Accessibility\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please follow these guidelines:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Run tests to ensure everything works (`npm test`)\n4. Commit your changes (`git commit -m 'Add amazing feature'`)\n5. Push to the branch (`git push origin feature/amazing-feature`)\n6. Open a Pull Request\n\n### Development Guidelines\n\n- Follow existing code style and patterns\n- Add tests for new features\n- Update documentation as needed\n- Ensure all tests pass before submitting PR\n- Run `npm run lint` to check for linting errors\n\n---\n\n## 📄 License\n\nMIT License - see [LICENSE](../LICENSE) file for details\n\n---\n\n## 🙏 Acknowledgments\n\n- Arabic keyboard layout based on KBDA1 standard\n- Sound effects from open source libraries\n- Built with Next.js, React, and TypeScript\n- Styled with Tailwind CSS\n\n---\n\n## 📞 Support\n\n- **GitHub Issues:** [Report bugs or request features](https://github.com/d-wack/arabic-keyboard-nextjs/issues)\n- **Documentation:** This README and inline code comments\n- **Examples:** See `src/components/examples/` folder\n\n---\n\n## 🗺️ Roadmap\n\n### v2.1 (Planned)\n- [ ] Swipe gesture support\n- [ ] Voice input integration\n- [ ] Predictive text\n- [ ] Custom layouts API\n\n### v3.0 (Future)\n- [ ] Multi-language support (French, Spanish, etc.)\n- [ ] Emoji picker integration\n- [ ] Advanced autocomplete\n- [ ] Cloud sync for settings\n\n---\n\n**Made with ❤️ for the Arabic-speaking developer community**\n","readmeFilename":"README.md"}