Simulating Mobile Virtual Keyboards in Progressive Web Apps

Jonas Geschke — Sun, 08 Dec 2024 19:32:18 +0000

As a web developer working on progressive web apps (PWAs), I've discovered that mobile development tools can feel frustratingly limited compared to native app development. One specific challenge that often gets overlooked is how virtual keyboards interact with your app's interface.

The Mobile Keyboard Challenge

When developing for mobile platforms, the virtual keyboard is a unique beast. Unlike desktop environments, mobile devices overlay the keyboard on top of your app, typically obscuring around 40% of the screen. This can create unexpected user experience issues, especially for apps with multiple input types.

In my current project, chordel - a collaborative song writing app - I frequently encountered a subtle but annoying problem: some touch interactions were accidentally triggering text input focus and summoning the virtual keyboard when it wasn't needed.

Why Simulation Matters

Testing mobile behaviors on desktop browsers often means missing these nuanced interactions. While real device testing is an option, it comes with complications:

Requires physically having the device
Involves setting up remote debugging
Can be time-consuming to switch between development environments

A Custom Virtual Keyboard Simulator

I developed a React component to simulate mobile keyboard behavior during development. Here's how it works:

Use MutationObserver to detect when the DOM is fully loaded
Attach focus and blur handlers to all text-editable elements
Show/hide a simulated keyboard overlay with the handlers
Add smooth scrolling and animations (optionally :))

Key Component Features

The simulator provides:

Automatic keyboard overlay
Smooth scrolling to focused elements
A dismissal mechanism
Optional animation effects

Here is a quick demo:

Here's the complete implementation:


const MobileKeyboardSimulator = ({
                                     enableAutoScroll = true,
                                     keyboardHeight = 300
                                 }) => {
    const [activeElement, setActiveElement] = useState<HTMLElement | null>(null);
    const [isKeyboardVisible, setIsKeyboardVisible] = useState(false);
    const [isKeyboardDismissing, setIsKeyboardDismissing] = useState(false);
    const keyboardOverlayRef = useRef(null);
    const originalScrollPositionRef = useRef<null | number>(null);
    const blurTimeoutRef = useRef<null | ReturnType<typeof setTimeout>>(null);

    // Dismiss keyboard function
    const dismissKeyboard = useCallback(() => {
        // Trigger slide-down animation
        setIsKeyboardDismissing(true);

        // Use a slight delay to allow animation to complete
        setTimeout(() => {
            if (activeElement) {
                activeElement.blur();
            }
            setIsKeyboardVisible(false);
            setIsKeyboardDismissing(false);

            // Restore original scroll position if auto-scrolled
            if (originalScrollPositionRef.current !== null) {
                window.scrollTo(0, originalScrollPositionRef.current);
                originalScrollPositionRef.current = null;
            }
        }, 300); // Match the animation duration
    }, [activeElement]);

    // Memoized focus handler to ensure stable reference
    const createFocusHandler = useCallback(() => {
        return (e: Event) => {
            console.debug('Focus handler triggered', e.target);

            // Clear any pending blur timeout
            if (blurTimeoutRef.current) {
                clearTimeout(blurTimeoutRef.current);
                blurTimeoutRef.current = null;
            }

            setActiveElement(e.target as HTMLElement | null);
            setIsKeyboardVisible(true);
            setIsKeyboardDismissing(false);

            // Auto-scroll functionality
            if (enableAutoScroll) {
                // Store original scroll position
                originalScrollPositionRef.current = window.scrollY;

                // Calculate element position
                const rect = (e.target as HTMLElement).getBoundingClientRect();
                const viewportHeight = window.innerHeight;

                // Calculate scroll amount to center the element
                const scrollAmount =
                    rect.top -
                    (viewportHeight - keyboardHeight - rect.height) / 2;

                // Smooth scroll to element
                window.scrollTo({
                    top: scrollAmount,
                    behavior: 'smooth'
                });
            }
        };
    }, [enableAutoScroll, keyboardHeight]);

    // Memoized blur handler
    const createBlurHandler = useCallback(() => {
        return () => {
            console.debug('Blur handler triggered');
            // Create a timeout to delay keyboard dismissal
            blurTimeoutRef.current = setTimeout(() => {
                // Check if the new active element is another input/contenteditable
                const newActiveElement = document.activeElement;
                const isNewElementInteractive =
                    newActiveElement?.matches('input, textarea, [contenteditable="true"]');

                if (!isNewElementInteractive) {
                    dismissKeyboard();
                    setActiveElement(null);
                }
            }, 100);
        };
    }, [dismissKeyboard]);

    const attachListeners = useCallback(() => {
        const selectableElements = document.querySelectorAll(
            'input, textarea, [contenteditable], [contenteditable="true"]'
        );

        const focusHandler = createFocusHandler();
        const blurHandler = createBlurHandler();

        const cleanup: (() => void)[] =[]

        selectableElements.forEach((element, index) => {
            element.addEventListener('focus', focusHandler);
            element.addEventListener('blur', blurHandler);

            cleanup.push(() => {
                element.removeEventListener('focus', focusHandler);
                element.removeEventListener('blur', blurHandler);
            })
        });

        return () => {
            cleanup.forEach((fn) => {
                fn();
            });
        };
    }, [createBlurHandler, createFocusHandler]);

    useEffect(() => {
        let cleanup: null | (() => void) = null;
        const observer = new MutationObserver(() => {
            cleanup = attachListeners();
        });

        observer.observe(document.body, {
            childList: true,
            subtree: true
        });

        return () => {
            observer.disconnect();
            if(cleanup)
                cleanup();
        };
    }, [attachListeners]);

    // Don't render if keyboard is not visible
    if (!isKeyboardVisible) return null;

    return (
        <div
            ref={keyboardOverlayRef}
            className={`
              touch-none
              pointer-events-none
              fixed bottom-0 left-0 w-full
              flex flex-col
              p-4 
              bg-muted
              border-t border-border
              z-[1000] 
              shadow-[0_-2px_10px_rgba(0,0,0,0.1)] 
              ${isKeyboardDismissing
                ? 'animate-[slideDown_0.3s_ease-out]'
                : 'animate-[slideUp_0.3s_ease-out]'} 
              animate-fill-forward
            `}
            style={{height: `${keyboardHeight}px`}}
        >
            <div className='w-full flex justify-end items-center mb-4'>
                <button
                    className='px-2 py-1 pointer-events-auto'
                    onClick={dismissKeyboard}
                >
                    Dismiss
                </button>
            </div>
            <div>
                {/* Example keyboard layout */}
                {['q', 'w', 'e', 'r', 't', 'y', 'u', 'i', 'o', 'p'].map((key) => (
                    <button
                        key={key}
                        className='px-2 py-1 w-[30px] h-[40px] border border-border rounded-md mr-2 mb-2 text-muted-foreground'
                    >
                        {key}
                    </button>
                ))}
            </div>

            {/* Global style for animations */}
            <style>{`
        @keyframes slideUp {
          from { transform: translateY(100%); }
          to { transform: translateY(0); }
        }
        @keyframes slideDown {
          from { transform: translateY(0); }
          to { transform: translateY(100%); }
        }
      `}</style>
        </div>
    );
};

Platform-Specific Considerations

To ensure the simulator only runs when appropriate, I added a detection method for iOS devices, but something similar can be done for Android as well:

const isiOS = useCallback(() => {
        const iosQuirkPresent = function () {
            const audio = new Audio();

            audio.volume = 0.5;
            return audio.volume === 1;   // volume cannot be changed from "1" on iOS 12 and below
        };

        const isIOS = /iPad|iPhone|iPod/.test(navigator.userAgent);
        const isAppleDevice = navigator.userAgent.includes('Macintosh');
        const isTouchScreen = navigator.maxTouchPoints >= 1;   // true for iOS 13 (and hopefully beyond)

        return isIOS || (isAppleDevice && (isTouchScreen || iosQuirkPresent()));
    }, []);

Usage and Deployment

Simply drop the MobileKeyboardSimulator component into your layout. It's designed to only render during development and on mobile platforms.
By using Vite's environment variables (import.meta.env.PROD), you can easily prevent the simulator from rendering in production.

Final Thoughts

While not a complete solution for all mobile testing scenarios, this custom keyboard simulator provides developers with a quick, lightweight way to catch mobile interaction edge cases earlier in the development process.

Testing is crucial, but having tools that help us simulate real-world conditions can save significant time and frustration.

Should node be used for general dev tools?

Jonas Geschke — Wed, 29 Jan 2020 15:43:22 +0000

JavaScript and TypeScript are really popular nowadays. Why shouldn't they? There is a huge community for both of them. So it is only natural that also development tools are written in node.

On the one hand this is good for maintenance, because there is a big community that is possible able to maintain it. On the other hand those tools force the user to have node in specific version installed (what you cant always do).

Wouldn't it be better to leverage another technology to be able to publish those tools as binaries? This of course has also a lot of disadvantages, too. So what do you think?

Why asking why?

Jonas Geschke — Sat, 07 Dec 2019 11:59:58 +0000

Did you find yourself reading a documentation or listening to talk and it starts with:

Why you need X?

After that headline they usually start listing some facts that are totally based on something else but justifies why you should need X based on some vague examples. ~~So why is this a problem?~~

At first this will convince you because these problems sound familiar to you. You are glad to hear that there finally is a solution. Allegedly there is. But to be honest you bought that argument just because you did not really think about those problems at all. Basically you were sold at the word "need". This tricks our brain in thinking: "Oh my god, you are right I really need this".

Let's rephrase this why question.

X is solving following problems.

This will force you to think about those arguments and lets you decide more rational if you really need X.

So my matter of concern is following. If you are a developer writing documentation and used this kind of question unintentionally, rephrase those statements to be fair to the reader.

Forem: Jonas Geschke