@cky__/lrud v0.1.0

lrud

A React library for managing focus in LRUD applications.

Motivation

The native focus system that ships with browsers is one-dimensional: users may only move forward and back. Some applications (typically those that use remote controls or video game controllers) require a two dimensional focus system.

Because of this, it is up to the application to manage its own focus state. That's where this library comes in: it makes working with two dimensional focus seamless.

Installation

Install using npm:

npm install @please/lrud

or yarn:

yarn add @please/lrud

This library has the following peer dependencies:

• react@^16.8.0 || react@^17.0.0

Updates

• feature: add config: enableFocusByHover, default Value: true, Focus when the mouse overed
• fix: mouse clicked a node that is not the focused node
• feature: add Interval between two clicks

Table of Contents

• Guides
  • Basic Setup
  • Getting Started
  • FAQ
• API Reference
  • \<FocusRoot/>
  • \<FocusNode/>
  • useFocusNodeById()
  • useLeafFocusedNode()
  • useActiveNode()
  • useSetFocus()
  • useNodeEvents()
  • useFocusHierarchy()
  • useProcessKey()
  • useFocusStoreDangerously()
• Interfaces
  • FocusNode
  • LRUDEvent
  • MoveEvent
  • GridMoveEvent
  • FocusStore
  • FocusState
• Examples
• Prior Art

Guides

Basic Setup

Render the FocusRoot high up in your application's component tree.

import { FocusRoot } from '@please/lrud';

export default function App() {
  return (
    <FocusRoot>
      <AppContents />
    </FocusRoot>
  );
}

You may then use FocusNode components to create a focusable elements on the page.

import { FocusNode } from '@please/lrud';

export default function Profile() {
  return <FocusNode className="profile">Profile</FocusNode>;
}

This library automatically moves the focus between the FocusNodes as the user inputs LRUD commands on their keyboard or remote control.

This behavior can be configured through the props of the FocusNode component. To learn more about those props, refer to the API documentation below.

Getting Started

The recommended way to familiarize yourself with this library is to begin by looking at the examples. The examples do a great job at demonstrating the kinds of interfaces you can create with this library using little code.

Once you've checked out a few examples you should be in a better position to read through these API docs!

FAQ

What is LRUD?

LRUD is an acronym that stands for left-right-up-down, and it refers to the directional buttons typically found on remotes. In LRUD systems, input devices usually also have some kind of "submit" button, and, less commonly, a back button.

API Reference

This section of the documentation describes the library's named exports.

<FocusRoot />

Serves as the root node of a new focus hierarchy. There should only ever be one FocusRoot in each application.

All props are optional.

import { FocusRoot } from '@please/lrud';

export default function App() {
  return (
    <FocusRoot orientation="vertical">
      <AppContents />
    </FocusRoot>
  );
}

<FocusNode />

A Component that represents a focusable node in your application.

All props are optional. Example usage appears beneath the props table.

import { FocusNode } from '@please/lrud';

export default function Profile() {
  return (
    <FocusNode
      elementType="button"
      className="profileBtn"
      onSelected={({ node }) => {
        console.log('The user just selected this profile', node);
      }}>
      Profile
    </FocusNode>
  );
}

useFocusNodeById( focusId )

A Hook that returns the focus node with ID focusId. If the node does not exist, then null will be returned instead.

import { useFocusNodeById } from '@please/lrud';

export default function MyComponent() {
  const navFocusNode = useFocusNodeById('nav');

  console.log('Is the nav focused?', navFocusNode?.isFocused);
}

useLeafFocusedNode()

A Hook that returns the currently-in-focus leaf node.

import { useLeafFocusedNode } from '@please/lrud';

export default function MyComponent() {
  const currentFocusedNode = useLeafFocusedNode();

  console.log('Currently focused node', currentFocusedNode);
}

useActiveNode()

A Hook that returns the active focus node, or null if no node is active. As a reminder, the active node is whatever node was selected last (similar to how interactive elements in the DOM become active after being clicked).

import { useActiveNode } from '@please/lrud';

export default function MyComponent() {
  const activeNode = useActiveNode();

  console.log('The active node:', activeNode);
}

useSetFocus()

A Hook that returns the setFocus function, which allows you to imperatively set the focus.

This can be used to:

• override the default navigation behavior of the library
• focus modals or traps
• exit traps

import { useSetFocus } from '@please/lrud';

export default function MyComponent() {
  const setFocus = useSetFocus();

  useEffect(() => {
    setFocus('nav');
  }, []);
}

useNodeEvents( focusId, events )

A Hook that allows you to tap into a focus nodes' focus lifecycle events. Use this hook when you need to respond to the focus lifecycle for a node that is not in your current component.

import { useNodeEvents } from '@please/lrud';

export default function MyComponent() {
  useNodeEvents('nav', {
    focus(navNode) {
      console.log('The nav node is focused', navNode);
    }

    blur(navNode) {
      console.log('The nav node is no longer focused', navNode);
    }
  });
}

Each callback receives a single argument, the focus node.

The available event keys are:

useFocusHierarchy()

A Hook that returns an array representing the focus hierarchy, which are the nodes that are currently focused. Each entry in the array is a focus node.

import { useFocusHierarchy } from '@please/lrud';

export default function MyComponent() {
  const focusHierarchy = useFocusHierarchy();

  console.log(focusHierarchy);
  // => [
  //   { focusId: 'root', ... },
  //   { focusId: 'homePage', ... },
  //   { focusId: 'mainNav', ... },
  // ]
}

useProcessKey()

A Hook that allows you to imperatively trigger LRUD key presses.

import { useProcessKey } from '@please/lrud';

function MyComponent() {
  const processKey = useProcessKey();

  useEffect(() => {
    // Imperatively trigger a down key press
    processKey.down();

    // Imperatively trigger a back key press
    processKey.select();

    // ...same, for the back button.
    processKey.back();
  }, []);
}

The full API is as follows.

interface ProcessKey {
  select: () => void;
  back: () => void;
  down: () => void;
  left: () => void;
  right: () => void;
  up: () => void;
}

useFocusStoreDangerously()

⚠️ Heads up! The FocusStore is an internal API. We strongly discourage you from accessing properties or calling methods on the FocusStore directly!

A Hook that returns the FocusStore. Typically, you should not need to use this hook.

One use-case for this hook is attaching the focusStore to the window when developing, which can be useful for debugging purposes.

import { useFocusStoreDangerously } from '@please/lrud';

export default function MyComponent() {
  const focusStore = useFocusStoreDangerously();

  useEffect(() => {
    if (process.env.NODE_ENV !== 'production') {
      window.focusStore = focusStore;
    }
  }, []);
}

Interfaces

These are the objects you will encounter when using this library.

FocusNode

A focus node. Each <FocusNode/> React component creates one of these.

LRUDEvent

An object that is passed to you in the LRUD-related callbacks of a FocusNode component:

• onKey
• onArrow
• onLeft
• onRight
• onUp
• onDown
• onSelected
• onBack

MoveEvent

An object that is passed to you in the onMove callback of a FocusNode component.

GridMoveEvent

An object that is passed to you in the onGridMove callback of a FocusNode component that is a grid.

FocusEvent

An object that is passed to you in the onFocused and onBlurred callbacks of a FocusNode component.

FocusStore

⚠️ Heads up! This is an internal API. We strongly discourage you from accessing properties or calling methods on the FocusStore directly!

An object that represents the store that contains all of the state related to what is in focus. Typically, you should not need to interact with this object directly, but it is made available to you for advanced use cases that you may have.

FocusState

⚠️ Heads up! This is an internal API. We strongly discourage you from accessing this object directly in your application.

An object representing the state of the focus in the app.

Examples

This repository contains example projects showing common patterns when using this library. Each example is located in the ./examples folder.

Instructions for running the examples are found in the README file for each example.

Basic Examples

• Basic Layout - Demonstrates using the orientation prop for vertical and horizontal lists
• Wrapping - Includes usage of the wrapping prop
• Grid - Shows how to build a grid of focus nodes
• Disabled Focus Nodes - Shows how to disable focus nodes using the disabled prop
• Focus Trap - Demonstrates how to create focus traps

Advanced Examples

• Modal - Show and hide an animated modal overlay
• Animated Page Transition - Animate between two pages
• isExiting Page Transition - Animating between pages without user input
• Pointer Events - An interface that supports both pointer and LRUD input
• Grid That Remembers Position - A grid that returns you to your previous position when you exit and re-enter it
• TV App - A simple TV app

Prior Art

• "Pass the Remote" on the Netflix Tech Blog
• bbc/lrud
• react-tv
• @xdproto/focus (the predecessor of this library)