reactjs-virtual-keyboard 1.0.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 HydraFacial
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,327 @@
+# 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.
+
+## Features
+
+- **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
+
+## Installation
+
+```bash
+npm install reactjs-virtual-keyboard
+# or
+yarn add reactjs-virtual-keyboard
+# or
+pnpm add reactjs-virtual-keyboard
+```
+
+## Quick Start
+
+### Option 1: GlobalVirtualKeyboard (Easiest)
+
+Add once at your app root - automatically shows keyboard when any input is focused:
+
+```tsx
+import { GlobalVirtualKeyboard } from 'reactjs-virtual-keyboard';
+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" />
+      
+      {/* Add once - works for all inputs */}
+      <GlobalVirtualKeyboard />
+    </div>
+  );
+}
+```
+
+### Option 2: VirtualKeyboard (Manual Control)
+
+For more control over when the keyboard appears:
+
+```tsx
+import { useRef, useState } from 'react';
+import { VirtualKeyboard } from 'reactjs-virtual-keyboard';
+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>
+  );
+}
+```
+
+## Components
+
+### GlobalVirtualKeyboard
+
+Automatically shows keyboard when any text input is focused. Best for most use cases.
+
+```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
+/>
+```
+
+| 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`:
+
+- **`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
+
+## 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;
+}
+```
+
+### Built-in Theme Classes
+
+```tsx
+<VirtualKeyboard
+  className="vk-container--light"  // Light theme
+  // or
+  className="vk-container--blue"   // Blue theme
+  // or
+  className="vk-container--purple" // Purple theme
+  {...props}
+/>
+```
+
+### Custom Theme Example
+
+```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;
+}
+```
+
+## Hooks
+
+### useCaretManager
+
+Manages caret position and text insertion/deletion:
+
+```tsx
+import { useCaretManager } from 'reactjs-virtual-keyboard';
+
+function CustomKeyboard() {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const { insertText, backspace } = useCaretManager(inputRef);
+
+  return (
+    <button onClick={() => insertText('Hello')}>Insert Text</button>
+    <button onClick={backspace}>Delete</button>
+  );
+}
+```
+
+### useContinuousPress
+
+Handle hold-to-repeat functionality:
+
+```tsx
+import { useContinuousPress } from 'reactjs-virtual-keyboard';
+
+function DeleteButton({ onDelete }) {
+  const handlers = useContinuousPress(onDelete, {
+    initialDelay: 500, // Start repeating after 500ms
+    interval: 50,      // Repeat every 50ms
+  });
+
+  return <button {...handlers}>Delete</button>;
+}
+```
+
+### useHardwareKeyboard
+
+Sync with physical keyboard events:
+
+```tsx
+import { useHardwareKeyboard } from 'reactjs-virtual-keyboard';
+
+function KeyboardHandler() {
+  useHardwareKeyboard({
+    isInputFocused: true,
+    onBackspace: () => console.log('Backspace'),
+    onEnter: () => console.log('Enter'),
+    onSpace: () => console.log('Space'),
+    onCapsToggle: () => console.log('Caps Lock'),
+    onKeyClick: (key) => console.log('Key:', key),
+  });
+}
+```
+
+### useKeyboardScroll
+
+Automatically scroll inputs into view when keyboard appears:
+
+```tsx
+import { useKeyboardScroll } from 'reactjs-virtual-keyboard';
+
+function MyComponent() {
+  const { scrollInput, resetScroll } = useKeyboardScroll();
+
+  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
+  };
+
+  return <input onFocus={handleFocus} onBlur={handleBlur} />;
+}
+```
+
+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
+
+You can use the individual layout components:
+
+```tsx
+import {
+  KeyboardLayout,
+  TextLayout,
+  NumbersLayout,
+  QWERTY_LAYOUT,
+  SYMBOLS_LAYOUT,
+  NUMBERS_LAYOUT,
+} from 'reactjs-virtual-keyboard';
+
+// Use predefined layouts or create custom ones
+const CUSTOM_LAYOUT = [
+  ['A', 'B', 'C'],
+  ['D', 'E', 'F'],
+  ['G', 'H', 'I'],
+];
+```
+
+## Accessibility
+
+The keyboard includes:
+
+- 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
+
+- Chrome 60+
+- Firefox 55+
+- Safari 11+
+- Edge 79+
+
+## TypeScript
+
+All types are exported:
+
+```tsx
+import type {
+  VirtualKeyboardProps,
+  VirtualKeyboardTheme,
+  GlobalVirtualKeyboardProps,
+  UseKeyboardScrollReturn,
+  LayoutType,
+  KeyboardLayoutProps,
+} from 'reactjs-virtual-keyboard';
+```
+
+## License
+
+MIT © HydraFacial
+

package/dist/index.d.ts

@@ -0,0 +1,346 @@
+import { FC } from 'react';
+import { HTMLInputTypeAttribute } from 'react';
+import { ReactNode } from 'react';
+import { RefObject } from 'react';
+import { SVGProps } from 'react';
+
+export declare const BackspaceIcon: FC<IconProps>;
+
+export declare const CapsLockIcon: FC<IconProps>;
+
+export declare interface ContinuousPressOptions {
+    initialDelay?: number;
+    interval?: number;
+    shouldPreventDefault?: boolean;
+}
+
+export declare const DEFAULT_THEME: {
+    backgroundColor: string;
+    keyColor: string;
+    keyTextColor: string;
+    keyActiveColor: string;
+    keyHoverColor: string;
+    activeStateColor: string;
+    keyBorderRadius: string;
+    keyFontSize: string;
+    keyHeight: string;
+};
+
+export declare const EnterIcon: FC<IconProps>;
+
+declare type FocusedInputRef = RefObject<HTMLInputElement | HTMLTextAreaElement | null>;
+
+/**
+ * Get the initial layout based on input type
+ */
+export declare const getInitialLayout: (inputType: HTMLInputTypeAttribute, defaultLayout: LayoutType) => LayoutType;
+
+/**
+ * GlobalVirtualKeyboard automatically shows a virtual keyboard when any
+ * text input or textarea is focused. It handles:
+ * - Automatic show/hide based on focus
+ * - Scrolling inputs into view
+ * - Form submission on Enter
+ * - Input type detection for appropriate layouts
+ *
+ * @example
+ * ```tsx
+ * // Add once at the root of your app
+ * function App() {
+ *   return (
+ *     <div>
+ *       <YourAppContent />
+ *       <GlobalVirtualKeyboard />
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With controlled visibility
+ * function App() {
+ *   const [keyboardEnabled, setKeyboardEnabled] = useState(true);
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => setKeyboardEnabled(!keyboardEnabled)}>
+ *         Toggle Keyboard
+ *       </button>
+ *       <GlobalVirtualKeyboard enabled={keyboardEnabled} />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare const GlobalVirtualKeyboard: FC<GlobalVirtualKeyboardProps>;
+
+export declare interface GlobalVirtualKeyboardProps {
+    /**
+     * Whether the virtual keyboard is enabled.
+     * When false, the keyboard will not appear on input focus.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Additional CSS class name for the keyboard container
+     */
+    className?: string;
+    /**
+     * Callback fired when keyboard visibility changes
+     */
+    onVisibilityChange?: (isVisible: boolean) => void;
+    /**
+     * Callback fired when Enter key is pressed
+     */
+    onEnterClick?: () => void;
+    /**
+     * Callback fired when value changes
+     */
+    onChange?: (value: string) => void;
+}
+
+/**
+ * Handle value change on the focused input
+ */
+export declare const handleValueChangeUtil: (focusedInputRef: FocusedInputRef, value: string) => void;
+
+export declare interface HardwareKeyboardHandlers {
+    isInputFocused: boolean;
+    onBackspace: () => void;
+    onEnter: () => void;
+    onSpace: () => void;
+    onCapsToggle: () => void;
+    onKeyClick: (key: string) => void;
+}
+
+declare type IconProps = SVGProps<SVGSVGElement>;
+
+export declare type InputElement = HTMLInputElement | HTMLTextAreaElement;
+
+export declare const KeyboardLayout: FC<KeyboardLayoutProps>;
+
+export declare interface KeyboardLayoutProps {
+    currentLayout: LayoutType;
+    capsLock: boolean;
+    onKeyClick: (key: string) => void;
+    onBackspace: () => void;
+    onEnter: () => void;
+    onSpace: () => void;
+    onCapsToggle: () => void;
+    onLayoutToggle: () => void;
+    inputType: HTMLInputTypeAttribute;
+}
+
+export declare const KeyboardRow: FC<KeyboardRowProps>;
+
+export declare interface KeyboardRowProps {
+    children: ReactNode;
+    className?: string;
+}
+
+export declare type LayoutType = 'letters' | 'symbols' | 'numbers';
+
+export declare const NUMBERS_LAYOUT: string[][];
+
+export declare const NumbersLayout: FC<NumbersLayoutProps>;
+
+export declare interface NumbersLayoutProps {
+    currentLayoutData: string[][];
+    onBackspace: () => void;
+    onEnter: () => void;
+    onKeyClick: (key: string) => void;
+    capsLock: boolean;
+    currentLayout: LayoutType;
+}
+
+/**
+ * Handle Enter key click - blur input and submit form if applicable
+ */
+export declare const onEnterClickUtil: (focusedInputRef: FocusedInputRef) => void;
+
+export declare const QWERTY_LAYOUT: string[][];
+
+/**
+ * Reset scroll position by removing transforms from shifted elements
+ */
+export declare function resetScrollPosition(): void;
+
+/**
+ * Utility functions to handle layout shifting when virtual keyboard appears
+ */
+/**
+ * Scroll the input into view by shifting content elements up
+ */
+export declare function scrollInputIntoView(input: HTMLInputElement | HTMLTextAreaElement, keyboardContainerRef: HTMLSpanElement): void;
+
+/**
+ * Update an input's value using the native setter (so React tracks it)
+ * and dispatch bubbled, cancelable input/change events to notify listeners.
+ */
+export declare const setInputValueAndDispatchEvents: (input: InputElement, value: string, options?: {
+    skipValueAssignment?: boolean;
+}) => void;
+
+export declare const SpacebarIcon: FC<IconProps>;
+
+export declare const SpecialKey: FC<SpecialKeyProps>;
+
+export declare interface SpecialKeyProps {
+    type: string;
+    onClick: () => void;
+    extraClass?: string;
+    text?: string | null;
+    icon?: ReactNode;
+    capsLock?: boolean;
+    enableContinuousPress?: boolean;
+}
+
+export declare const SYMBOLS_LAYOUT: string[][];
+
+export declare const TextLayout: FC<TextLayoutProps>;
+
+export declare interface TextLayoutProps {
+    inputType: HTMLInputTypeAttribute;
+    currentLayoutData: string[][];
+    onBackspace: () => void;
+    onEnter: () => void;
+    onSpace: () => void;
+    onCapsToggle: () => void;
+    onLayoutToggle: () => void;
+    onKeyClick: (key: string) => void;
+    capsLock: boolean;
+    currentLayout: LayoutType;
+}
+
+/**
+ * Hook to manage caret position and text insertion/deletion in input elements
+ */
+export declare function useCaretManager(focusedInputRef: RefObject<InputElement | null>): UseCaretManagerReturn;
+
+export declare interface UseCaretManagerReturn {
+    insertText: (text: string) => void;
+    backspace: () => void;
+}
+
+/**
+ * Hook for handling continuous press events (like holding backspace to delete multiple characters)
+ */
+export declare function useContinuousPress(onPress: () => void, { initialDelay, interval, shouldPreventDefault, }?: ContinuousPressOptions): {
+    onMouseDown: (e: React.MouseEvent) => void;
+    onTouchStart: (e: React.TouchEvent) => void;
+    onMouseUp: () => void;
+    onMouseLeave: () => void;
+    onTouchEnd: (e: React.TouchEvent) => void;
+};
+
+/**
+ * Hook to keep virtual keyboard in sync with hardware keyboard events
+ * (e.g., when pressing caps lock on hardware keyboard, virtual keyboard should reflect it)
+ */
+export declare function useHardwareKeyboard({ isInputFocused, onBackspace, onEnter, onSpace, onCapsToggle, onKeyClick, }: HardwareKeyboardHandlers): void;
+
+/**
+ * Hook to handle keyboard scrolling for input elements.
+ * Automatically shifts content up when the virtual keyboard would cover the input.
+ *
+ * @returns Object with scroll and reset functions
+ *
+ * @example
+ * ```tsx
+ * const { scrollInput, resetScroll } = useKeyboardScroll();
+ *
+ * // When input is focused
+ * scrollInput(inputElement);
+ *
+ * // When keyboard is hidden
+ * resetScroll();
+ * ```
+ */
+export declare function useKeyboardScroll(keyboardContainerRef: RefObject<HTMLSpanElement | null>): UseKeyboardScrollReturn;
+
+export declare interface UseKeyboardScrollReturn {
+    /** Scroll the input into view when keyboard appears */
+    scrollInput: (input: HTMLInputElement | HTMLTextAreaElement) => void;
+    /** Reset scroll position when keyboard hides */
+    resetScroll: () => void;
+}
+
+/**
+ * Validate if the focused element should show the virtual keyboard
+ * Returns the input/textarea element or null if it shouldn't show keyboard
+ */
+export declare const validateFocusInputs: (event: Event) => HTMLInputElement | HTMLTextAreaElement | null;
+
+/**
+ * Validates a single character based on input type
+ */
+export declare const validateValueUtil: (value: string, inputType: HTMLInputTypeAttribute) => boolean;
+
+export declare const VirtualKey: FC<VirtualKeyProps>;
+
+/**
+ * Virtual Keyboard Component
+ *
+ * A customizable on-screen keyboard for React applications.
+ * Supports multiple layouts (QWERTY, symbols, numbers), hardware keyboard sync,
+ * and touch device compatibility.
+ */
+export declare const VirtualKeyboard: FC<VirtualKeyboardProps>;
+
+export declare const VirtualKeyboardContainer: FC<VirtualKeyboardContainerProps>;
+
+declare interface VirtualKeyboardContainerProps {
+    children: ReactNode;
+    className?: string;
+}
+
+export declare interface VirtualKeyboardProps {
+    /** Ref to the currently focused input element */
+    focusedInputRef: RefObject<HTMLInputElement | HTMLTextAreaElement | null>;
+    /** Whether an input is currently focused */
+    isInputFocused: boolean;
+    /** Type of the input element (affects layout and validation) */
+    inputType?: HTMLInputTypeAttribute;
+    /** Callback fired when Enter key is pressed */
+    onEnterClick?: () => void;
+    /** Callback fired when value changes */
+    onChange?: (value: string) => void;
+    /** Additional CSS class name */
+    className?: string;
+    /** Default layout to show ('letters' | 'symbols' | 'numbers') */
+    defaultLayout?: LayoutType;
+    /** Custom validation function */
+    validate?: (value: string) => boolean;
+    /** Theme configuration */
+    theme?: VirtualKeyboardTheme;
+}
+
+export declare interface VirtualKeyboardTheme {
+    /** Background color of the keyboard container */
+    backgroundColor?: string;
+    /** Color of the keys */
+    keyColor?: string;
+    /** Text color on keys */
+    keyTextColor?: string;
+    /** Active/pressed key background color */
+    keyActiveColor?: string;
+    /** Hover key background color */
+    keyHoverColor?: string;
+    /** Active state color (e.g., caps lock on) */
+    activeStateColor?: string;
+    /** Border radius for keys */
+    keyBorderRadius?: string;
+    /** Font size for keys */
+    keyFontSize?: string;
+    /** Key height */
+    keyHeight?: string;
+}
+
+export declare interface VirtualKeyProps {
+    keyValue: string;
+    onClick: (key: string) => void;
+    className?: string;
+}
+
+export { }