RFC: react-sunbeam@2.0.0 API

[vovacodes]

Introduction

I'm in the middle of a rewrite that should get away from the reliance on React context for the focus state updates and use subscriptions to FocusManager to propagate the updates surgically only to the components that actually have their focus state changed, thus reducing the amount of unnecessary re-rendering.
While working on it, I've changed some user-facing TypeScript types so I would also like to use this opportunity to change the API slightly so it's clearer and more cohesive.

Problem

This RFC seeks feedback for the proposed API and the use-cases that might not work nicely with it.

Core API

FocusManager

FocusManager is a React-agnostic class that knows how to move focus between the focusable tree nodes in response to the calls to its methods, it maintains the current focus path - path to the focused leaf node in the tree - and can be subscribed to to receive notifications when that path changes.
It has to be instantiated by the user and the user needs to decide what events should trigger the navigation methods, it can be anything from the regular key presses to the browser Gamepad API events or even scroll.

interface FocusManager {
    moveLeft(): void
    moveRight(): void 
    moveUp(): void 
    moveDown(): void
    setFocus(focusPath: FocusPath): void
    subscribe(subscriber: (event: { focusPath: FocusPath }) => void): () => void
}

<Root>

Root, (formerly SunbeamProvider) is the root focusable component. It instantiates the focusable tree and holds its root node as well as passing FocusManager and some other utilities through the React context to other focusable components in the tree.

function Root(props: {
    focusManager: FocusManager
    keyPressManager?: KeyPressManager
    onFocusUpdate?: (event: { focusPath: FocusPath }) => void
    onKeyPress?: KeyPressListener
    getPreferredChildOnFocus?: CustomGetPreferredChildFn
    children: React.ReactNode
})

useFocusable()

A hook that makes the component that uses it a focusable node in the tree.

function useFocusable(params: {
    elementRef: Element
    focusKey?: string
    focusable?: boolean
    lock?: Direction | Direction[]
    onKeyPress?: KeyPressListener
    onFocus?: (event: FocusEvent) => void
    onBlur?: (event: FocusEvent) => void
    getPreferredChildOnFocus?: CustomGetPreferredChildFn
}): { focused: boolean; path: string[]; node: BranchNode }

This is the part of the API that I expect to be used the most. It can be used both for creating a leaf node or a branch node. If the latter is the goal the node has to be passed down the tree through the React context, in order to do that, the user needs to render a Branch component and pass it the opaque node object returned from the useFocusable() call:

const { focused, node } = useFocusable(...)

return (
    <Branch node={node}>
        ...
    </Branch>
)

<Branch>

The sole purpose of the Branch component is described in the section above. I'd love to not have this part of the API but, currently, there is no way of providing a React context value to the subtree just from a hook, a Provider element has to be used.

Auxiliary API

TODO