Norigin Spatial Navigation

Norigin Spatial Navigation is a library designed to bridge the gap between application interfaces and TV remote controls. It provides an automatic spatial algorithm that eliminates the need for manual focus wiring (e.g., manually defining that 'on right press, focus element X'). Instead, you point your components in a direction, and the library calculates the next focusable element based on spatial relationships.

Key features include:

• Automatic spatial algorithm: Handles focus movement automatically based on component positioning.
• TV-optimized: Built specifically for TV environments and actively used on Tizen, webOS, Hisense, Vizio, and Chromium-based STBs.
• Lightweight: Minimal footprint and low dependency count, making it suitable for constrained TV hardware.

Spatial navigation replaces pointer-based interaction (mouse/touch) with directional input (arrow keys, D-pads). Instead of clicking, users navigate by pressing directional keys, and the application moves focus between elements based on their physical position on the screen.

When a directional key is pressed, the library:

1. Identifies all registered focusable components.
2. Filters for components located in the pressed direction relative to the current focus.
3. Calculates a weighted distance score using primary-axis (direction of press) and secondary-axis (perpendicular) distances.
4. Selects the component with the lowest score, prioritizing 'adjacent' components (those that overlap significantly on the perpendicular axis) over diagonal ones.

Focus Hierarchy

RTL mode only changes how arrow key directions are interpreted. It does not affect FocusContext, boundaries, or the focus hierarchy logic. Your component implementation remains the same.

Custom Key Maps

If you have defined custom key mappings using setKeyMap, RTL mode is applied on top of those mappings. The library swaps the logical meaning of left and right navigation internally, regardless of which physical keys you have mapped to those directions.

Focusable components are organized into a tree structure. A container component can be focusable itself, and its children are nested within it.

• Context Detection: Children automatically detect their parent via FocusContext.
• Focus Routing: When focus enters a container, the library routes it to the appropriate child.
• Focus Memory: Containers can use the saveLastFocusedChild capability to remember which child was last focused and restore that specific child when focus returns to the container.

To manage a group of focusable children, use useFocusable with trackChildren: true and saveLastFocusedChild: true. This allows the container to know if it has a focused child and remember which child was last focused. Use FocusContext.Provider to pass the container's focusKey down to its children so they can be navigated relative to the container.

Note: Options like trackChildren and saveLastFocusedChild are only read at registration time and are not reactive.

function Row({ title }: { title: string }) {
  const { ref, focusKey, hasFocusedChild } = useFocusable({
    trackChildren: true,
    saveLastFocusedChild: true
  });

  return (
    <FocusContext.Provider value={focusKey}>
      <div ref={ref}>
        <h2>{title}</h2>
        <Card id="1" title="Item 1" />
        <Card id="2" title="Item 2" />
      </div>
    </FocusContext.Provider>
  );
}

A full layout adapter must implement the following conceptual contract:

• measureLayout(component): Returns a Promise resolving to layout data: { left, top, right, bottom, width, height, x, y, node }.
• focusNode(component): Applies native focus (e.g., HTMLElement.focus()) when shouldFocusDOMNode is enabled.
• blurNode(component): Clears native focus styling (e.g., removing a data-focused attribute).
• addEventListeners({ keyDown, keyUp }): Wires directional keys to the service.
• removeEventListeners(): Tears down the listeners.

If providing a partial object, you only need to supply the methods you wish to override; the rest will be merged from the default adapter.

Every focusable component is identified by a unique string called a focus key. The library uses these keys to track the current focus and to enable programmatic focus control.

• Automatic Keys: If no key is provided, the library generates one (e.g., sn:focusable-item-0).
• Manual Keys: You can provide a stable, human-readable key using the focusKey option. This is highly recommended for easier programmatic focus management.
• Root Key: The constant ROOT_FOCUS_KEY (value: 'SN:ROOT') identifies the root of the focus tree.