focus-layers

This version (hopefully) actually fixes the autoFocus problem by breaking out of React's useEffect callback ordering and updating layer enabled/disabled states immediately (#16).

• Re-added the ability to specify a different target for returning focus when a layer is popped (#7, #13)
• Fixed issues with autoFocus appearing broken when a lock layer is added on top of another (#12, #14)
• Added useFocusLock as a named export for better compatibility in CJS modules (#11, #15)

All components of the package are now documented with descriptive context. The code has been split up into multiple distinct modules to improve readability with those comments inline. Finally, a number of edge cases have been addressed to improve stability and fix incorrect behavior with various blur and refocus situations.

Mainly an improvement for debugging, the lock stack now tracks whether a layer thinks it's enabled or not directly. This is simple extension of how setEnabled is called for each layer during usage.

Also, focus events that cause a wrap will now call preventDefault.

The call signature for useFocusLock now uses an object as the second parameter to contain multiple optional arguments.

This also adds the attachTo option to scope where useFocusLock will attach listeners. Any focus events that occur outside of that node will not be intercepted. This is useful for apps that are embedded in other pages, or where some utilities need to focus elements outside of the lock layer to do their job (e.g., copying data with execCommand).

As a result of this change, withFocusLayer has also been removed as it was not a safe guarantee that locks would be disabled by the time the callback was invoked.

withFocusLayer is an imperative utility for performing an action with a free focus layer added to the top of the lock stack. Useful for callback functions that need to move focus around the DOM, such as copy functions that use the browser's Selection API:

import useFocusLock, {withFocusLayer} from 'focus-layers';

function handleCopy(someText: string) {
  withFocusLayer(() => {
    // Programmatically focus anywhere you want while
    // inside this callback.
    doTheCopy(someText);
  });
}

function Dialog() {
  // This component pushes a focus layer while it is mounted.
  const containerRef = React.useRef<HTMLDivElement>(null);
  useFocusLock(containerRef);

  return (
    <div ref={containerRef}>
      <button onClick={() => copy("the copied text")}>Copy some text</button>
    </div>
  );
}

useLockSubscription is an easy way to subscribe to the lock stack inside of a component lifecycle.

Run yarn examples (or npm run examples) to load a demo app from the examples/ directory of this repo in your browser.