### Install Project Dependencies

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/packages/example/README.md

Run this command to install all necessary project dependencies.

```bash
yarn install
```

--------------------------------

### Install react-tv-space-navigation

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/tutorial.md

Install the package using npm or yarn. This package has no external dependencies.

```bash
npm install react-tv-space-navigation
# or
yarn add react-tv-space-navigation
```

--------------------------------

### Run Web Application

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/packages/example/README.md

Command to run the web version of the project, starting a development server with Webpack.

```bash
yarn web
```

--------------------------------

### Run TVOS Application

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/packages/example/README.md

Commands to start the TV application on Apple TV or Android TV using React Native's Metro bundler.

```bash
yarn start
```

```bash
yarn ios
```

```bash
yarn android
```

--------------------------------

### SpatialNavigationVirtualizedGrid Usage

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

Example of how to use the SpatialNavigationVirtualizedGrid component with its essential props.

```APIDOC
## SpatialNavigationVirtualizedGrid

### Description
Component for rendering a virtualized grid with spatial navigation capabilities.

### Props
- `data` (Array) - Required - The data array to be rendered.
- `renderItem` (Function) - Required - A function that renders each item in the grid.
- `numberOfColumns` (number) - Required - The number of columns in the grid.
- `itemHeight` (number) - Required - The height of each item in the grid.
- `additionalItemsRendered` (number) - Optional - Number of additional items to render beyond the viewport.
- `onEndReachedThresholdRowsNumber` (number) - Optional - Threshold for triggering `onEndReached` event in rows.
- `rowContainerStyle` (object) - Optional - Styles to apply to the row container.
```

--------------------------------

### Configure Remote Control for Web

Source: https://context7.com/bamlab/react-tv-space-navigation/llms.txt

Register platform-specific key event listeners. This must be called once at app startup before any spatial navigation components are rendered. This example shows configuration for the web platform using keyboard events.

```tsx
import { Directions, SpatialNavigation } from 'react-tv-space-navigation';

// Web platform example — call this once at app entry point
SpatialNavigation.configureRemoteControl({
  remoteControlSubscriber: (callback) => {
    const mapping: Record<string, Directions> = {
      ArrowRight: Directions.RIGHT,
      ArrowLeft: Directions.LEFT,
      ArrowUp: Directions.UP,
      ArrowDown: Directions.DOWN,
      Enter: Directions.ENTER,
    };

    const handler = (keyEvent: KeyboardEvent) => {
      const direction = mapping[keyEvent.code];
      if (direction !== undefined) {
        callback(direction);
      }
    };

    window.addEventListener('keydown', handler);
    return handler; // returned value is passed to unsubscriber
  },

  remoteControlUnsubscriber: (handler) => {
    window.removeEventListener('keydown', handler);
  },
});
```

--------------------------------

### Configure Remote Control for Web

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

Configure the remote control interaction for SpatialNavigation components using configureRemoteControl. This example sets up arrow key listeners for web environments.

```jsx
SpatialNavigation.configureRemoteControl({
  remoteControlSubscriber: (callback) => {
    const mapping = {
      ArrowRight: Directions.RIGHT,
      ArrowLeft: Directions.LEFT,
      ArrowUp: Directions.UP,
      ArrowDown: Directions.DOWN,
    };

    const eventId = window.addEventListener('keydown', (keyEvent) => {
      callback(mapping[keyEvent.code]);
    });

    return eventId;
  },

  remoteControlUnsubscriber: (eventId) => {
    window.removeEventListener('keydown', eventId);
  },
});
```

--------------------------------

### SpatialNavigationNode with Active State

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

This example shows how to use SpatialNavigationNode to conditionally style a container based on whether any of its child nodes are active. Note that using 'isActive' on virtualized nodes is not recommended.

```jsx
<SpatialNavigationNode orientation="horizontal" isFocusable={false}>
  {({ isActive }) => (
    <View style={{ backgroundColor: isActive ? 'grey' : 'black' }}>
      <FocusableNodes />
    </View>
  )}
</SpatialNavigationNode>
```

--------------------------------

### SpatialNavigationNode Usage

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

Example of how to use the SpatialNavigationNode component to manage focus and selection within a navigation hierarchy. It accepts props like onFocus, onSelect, orientation, and isFocusable.

```APIDOC
## SpatialNavigationNode

### Description
Manages spatial navigation for its children, handling focus and selection events.

### Props
- **onFocus** (function) - Callback when the node gains focus.
- **onSelect** (function) - Callback when the node is selected.
- **orientation** (string) - 'horizontal' or 'vertical' to define navigation direction.
- **isFocusable** (boolean) - Determines if the node can receive focus.

### Render Props
- **isFocused** (boolean) - True if the node is currently focused.
- **isRootActive** (boolean) - True if the node is the active root in the navigation tree.
- **isActive** (boolean) - True if the node or one of its descendants is focused (use with caution on virtualized nodes).

### Example
```jsx
<SpatialNavigationNode
  onFocus={() => console.log('Node gained focus')}
  onSelect={() => console.log('Node was selected')}
  orientation="horizontal"
  isFocusable={true}
>
  {({ isFocused, isRootActive }) => <Text style={{ color: (isFocused && isRootActive) ? 'red' : 'black' }}>Hello World!</Text>}
</SpatialNavigationNode>
```
```

--------------------------------

### SpatialNavigationView with Horizontal Direction

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

Illustrates the usage of SpatialNavigationView to manage the orientation of child navigation nodes. This example sets the direction to horizontal, affecting how nodes are laid out and navigated.

```jsx
const FocusableNode = () => (
  <SpatialNavigationNode isFocusable={true}>
    {({ isFocused }) => <Text style={{ color: isFocused ? 'red' : 'black' }}>Hello World!</Text>}
  </SpatialNavigationNode>
);

<SpatialNavigationView direction="horizontal">
  {/* Nodes will be horizontal, and flex view will be row */}
  <FocusableNode />
  <FocusableNode />
  <FocusableNode />
</SpatialNavigationView>;
```

--------------------------------

### Provide Accessibility Props for Focusable Components

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

Use this hook to get accessibility properties for a focusable component. It includes workarounds for TalkBack compatibility, requiring an initial 'Enter' press for custom focus.

```tsx
const Button = () => {
  // You can't use the hook directly in `FocusableButton` since it needs to access
  // the current SpatialNavigationNode's context
  const accessibilityProps = useSpatialNavigatorFocusableAccessibilityProps();

  return <Button {...accessibilityProps}>My Button</Button>;
};

const FocusableButton = () => {
  // Do not put the hook here!
  return <SpatialNavigationNode isFocusable>{({isFocused}) => <Button isFocused={isFocused} />}</SpatialNavigationNode>
}
```

--------------------------------

### Prebuild Expo App

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/packages/example/README.md

Execute this command to prebuild the application with Expo before running.

```bash
yarn prebuild
```

--------------------------------

### Set up Spatial Navigation Root

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/tutorial.md

Wrap your application's navigable elements with SpatialNavigationRoot to enable spatial navigation.

```diff
const Element = () => (
  <View>
    <Text>Page element</Text>
  </View>
);

const Page = () => {
  return (
+    <SpatialNavigationRoot>
      <Element />
      <Element />
+    </SpatialNavigationRoot>
  );
};
```

--------------------------------

### Basic Focusable Node and Scroll View Usage

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

Demonstrates how to create a focusable node within a spatial navigation context and use it inside a horizontal scroll view. The color of the text changes when the node is focused.

```jsx
const FocusableNode = () => (
  <SpatialNavigationNode isFocusable={true}>
    {({ isFocused }) => <Text style={{ color: isFocused ? 'red' : 'black' }}>Hello World!</Text>}
  </SpatialNavigationNavigationNode>
);

<SpatialNavigationScrollView horizontal style={{ padding: 20 }} offsetFromStart={10}>
  <FocusableNode />
  <FocusableNode />
  <FocusableNode />
  <FocusableNode />
</SpatialNavigationScrollView>;
```

--------------------------------

### Publish Package Script

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/README.md

Commands to publish the package. Ensure version is incremented in package.json, commit changes, add a tag, generate changelog, and then publish.

```bash
cd packages/lib
yarn publish:package
```

--------------------------------

### TVSpaceNavigation Component Props

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

Configuration options for the TVSpaceNavigation component.

```APIDOC
## Props

| Name                              | Type                                                     |
| --------------------------------- | -------------------------------------------------------- |
| `data`                            | `Array<T>`                                               |
| `renderItem`                      | `(args: { item: T }) => JSX.Element`                     |
| `numberOfColumns`                 | `Number`                                                 |
| `itemHeight`                      | `Number`                                                 |
| `additionalRenderedRows`          | `Number`                                                 |
| `header`                          | `JSX.Element`                                            |
| `headerSize`                      | `Number`                                                 |
| `onEndReached`                    | `() => void`                                             |
| `onEndReachedThresholdRowsNumber` | `Number`                                                 |
| `style`                           | `Object`                                                 |
```

--------------------------------

### Temporarily Lock Spatial Navigation with useLockSpatialNavigation

Source: https://context7.com/bamlab/react-tv-space-navigation/llms.txt

Use the useLockSpatialNavigation hook to get lock and unlock functions for temporarily disabling spatial navigation. This is useful when a native keyboard or modal should take input precedence.

```tsx
import { useLockSpatialNavigation } from 'react-tv-space-navigation';
import { TextInput } from 'react-native';
import { SpatialNavigationFocusableView } from 'react-tv-space-navigation';

const SearchInput = () => {
  const { lock, unlock } = useLockSpatialNavigation();

  return (
    <SpatialNavigationFocusableView
      onSelect={() => {
        // Lock spatial nav when user activates the text input
        lock();
      }}
    >
      {( { isFocused } ) => (
        <TextInput
          placeholder="Search..."
          onFocus={lock}
          onBlur={unlock} // Restore spatial navigation when keyboard is dismissed
          style={{ borderWidth: isFocused ? 2 : 1, borderColor: isFocused ? '#0a84ff' : '#ccc' }}
        />
      )}
    </SpatialNavigationFocusableView>
  );
};

```

--------------------------------

### Virtualized Grid for Movie Catalogs

Source: https://context7.com/bamlab/react-tv-space-navigation/llms.txt

Implement SpatialNavigationVirtualizedGrid for displaying items in a multi-column layout, suitable for catalog pages. Configure columns, item height, and pagination. Use additionalRenderedRows for smoother scrolling.

```tsx
import { SpatialNavigationVirtualizedGrid, SpatialNavigationFocusableView } from 'react-tv-space-navigation';
import { View, Text } from 'react-native';
import React, { useMemo, useCallback, useRef } from 'react';

type Movie = { id: string; title: string };

const MovieTile = ({ item }: { item: Movie }) => (
  <SpatialNavigationFocusableView onSelect={() => console.log('Play:', item.title)}>
    {({
      isFocused
    }) => (
      <View
        style={{
          flex: 1,
          height: 160,
          margin: 8,
          backgroundColor: isFocused ? '#0a84ff' : '#444',
          borderRadius: 6,
          justifyContent: 'flex-end',
          padding: 8,
        }}
      >
        <Text style={{ color: '#fff', fontSize: 13 }}>{item.title}</Text>
      </View>
    )}
  </SpatialNavigationFocusableView>
);

const MovieGrid = ({ movies, onLoadMore }: { movies: Movie[]; onLoadMore: () => void }) => {
  const data = useMemo(() => movies, [movies]);
  const renderItem = useCallback(({ item }: { item: Movie }) => <MovieTile item={item} />, []);
  const gridRef = useRef(null);

  return (
    <SpatialNavigationVirtualizedGrid
      ref={gridRef}
      data={data}
      renderItem={renderItem}
      numberOfColumns={4}
      itemHeight={176} // tile height + margins
      additionalRenderedRows={3}
      scrollBehavior="stick-to-start"
      rowContainerStyle={{ paddingHorizontal: 16 }}
      onEndReached={onLoadMore}
      onEndReachedThresholdRowsNumber={2}
    />
  );
};

```

--------------------------------

### Control Remote Control Lock

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

This hook allows you to manage the lock state of the remote control. It's useful for synchronizing with native focus systems, for example, by disabling remote input while the focus system is active.

```tsx
const MyComponent = () => {
  const { lock, unlock } = useLockSpatialNavigation();

  // Doesn't really make sense to lock after selecting a button, but you get the idea
  return <Button onSelect={() => lock()} />; 
};
```

--------------------------------

### SpatialNavigationVirtualizedGrid Ref Methods

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

The `SpatialNavigationVirtualizedGrid` component ref exposes the following methods.

```APIDOC
## Ref Methods

- **focus** (index: number) => void: Give the focus to the selected node and scroll if needed.
- **scrollTo** (index: number) => void: ❌ does not work properly in the case of a grid.
```

--------------------------------

### Handle Basic Pointer Hovering with SpatialNavigationDeviceTypeProvider

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/tutorial.md

Wrap your application with SpatialNavigationDeviceTypeProvider to enable handling of remote pointers. SpatialNavigationFocusableView components will then respond to pointer hovering, triggering focus.

```tsx
function App(): JSX.Element {
  return (
    <SpatialNavigationDeviceTypeProvider>
      <DefaultFocus>
        <SomeFocusableComponent onSelect={() => console.log('selected first element')} />
      </DefaultFocus>
      <SomeFocusableComponent onSelect={() => console.log('selected second element')} />
    </SpatialNavigationDeviceTypeProvider>
  );
}

const SomeFocusableComponent = ({ onSelect }: Props) => {
  return (
    <SpatialNavigationFocusableView onSelect={onSelect}>
      {({ isFocused }) => <View isFocused={isFocused} />} // Can be an image or whatever you want
    </SpatialNavigationFocusableView>
  );
};

```

--------------------------------

### SpatialNavigationNode Methods

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

Methods available on the SpatialNavigationNode component's ref.

```APIDOC
## Methods

The `SpatialNavigationNode` component ref expose the following methods:

| Name    | Type       | Description                          |
| ------- | ---------- | ------------------------------------ |
| `focus` | `function` | Give the focus to the selected node. |
```

--------------------------------

### configureRemoteControl

Source: https://context7.com/bamlab/react-tv-space-navigation/llms.txt

Registers platform-specific key event listeners to enable spatial navigation. This function must be called once at the application's startup before any spatial navigation components are rendered.

```APIDOC
## configureRemoteControl

### Description
Registers platform-specific key event listeners so the library knows which direction the user is navigating. Must be called once at app startup before any spatial navigation components are rendered.

### Parameters
#### Request Body
- **remoteControlSubscriber** (function) - Required - A function that takes a callback and returns a handler for unsubscribing.
- **remoteControlUnsubscriber** (function) - Required - A function that takes a handler and removes the event listener.

### Request Example
```tsx
import { Directions, SpatialNavigation } from 'react-tv-space-navigation';

// Web platform example — call this once at app entry point
SpatialNavigation.configureRemoteControl({
  remoteControlSubscriber: (callback) => {
    const mapping: Record<string, Directions> = {
      ArrowRight: Directions.RIGHT,
      ArrowLeft: Directions.LEFT,
      ArrowUp: Directions.UP,
      ArrowDown: Directions.DOWN,
      Enter: Directions.ENTER,
    };

    const handler = (keyEvent: KeyboardEvent) => {
      const direction = mapping[keyEvent.code];
      if (direction !== undefined) {
        callback(direction);
      }
    };

    window.addEventListener('keydown', handler);
    return handler; // returned value is passed to unsubscriber
  },

  remoteControlUnsubscriber: (handler) => {
    window.removeEventListener('keydown', handler);
  },
});
```
```

--------------------------------

### Declare Rabbit Component with FocusableView

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/README.md

A simple component that shows a rabbit program. Plug it to the Spatial Navigation easily using a FocusableView.

```tsx
/**
 * A simple component that shows a rabbit program
 * We plug it to the Spatial Navigation easily using a FocusableView
 */
const Rabbit = ({ onSelect }) => (
  <SpatialNavigationFocusableView onSelect={onSelect}>
    {({ isFocused }) => <RabbitLayout isFocused={isFocused} />}
  </SpatialNavigationFocusableView>
);
```

--------------------------------

### SpatialNavigationVirtualizedList Ref Methods

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

Methods available on the ref of the SpatialNavigationVirtualizedList component.

```APIDOC
## Ref Methods

| Name | Type | Description |
|---|---|---|
| `focus` | `(index: number) => void` | Give the focus to the selected node and scroll if needed. |
| `scrollTo` | `(index: number) => void` | Scroll to the selected node if needed, without appyling focus. |
```

--------------------------------

### Implement Side Menu with Multi-Navigator Pattern

Source: https://context7.com/bamlab/react-tv-space-navigation/llms.txt

Use two SpatialNavigationRoot instances to manage focus between a side menu and page content. The `isActive` prop controls which navigator is currently active, and `onDirectionHandledWithoutMovement` allows switching focus between them.

```tsx
import React, { useState } from 'react';
import { SpatialNavigationRoot, DefaultFocus } from 'react-tv-space-navigation';
import { View } from 'react-native';

const AppWithSideMenu = () => {
  const [menuActive, setMenuActive] = useState(false);

  return (
    <View style={{ flex: 1, flexDirection: 'row' }}>
      {/* Side menu navigator */}
      <SpatialNavigationRoot isActive={menuActive}>
        <DefaultFocus enable={menuActive}>
          <SideMenuContent onNavigateToPage={() => setMenuActive(false)} />
        </DefaultFocus>
      </SpatialNavigationRoot>

      {/* Page navigator — hands off to menu when user presses LEFT at the edge */}
      <SpatialNavigationRoot
        isActive={!menuActive}
        onDirectionHandledWithoutMovement={(direction) => {
          if (direction === 'left') setMenuActive(true);
        }}
      >
        <DefaultFocus enable={!menuActive}>
          <PageContent />
        </DefaultFocus>
      </SpatialNavigationRoot>
    </View>
  );
};

```

--------------------------------

### Basic SpatialNavigationRoot Usage

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

Use SpatialNavigationRoot as the main container for your spatial navigation hierarchy. It manages context providers and node registration.

```jsx
<SpatialNavigationRoot>
  <SpatialNavigationNode>
    <Text>Hello World!</Text>
  </SpatialNavigationNode>
</SpatialNavigationRoot>
```

--------------------------------

### configureRemoteControl

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

API to configure how remote control inputs are handled by SpatialNavigation components.

```APIDOC
## configureRemoteControl

### Description
Configures the remote control interaction for SpatialNavigation components by providing functions to subscribe and unsubscribe from remote control events.

### Parameters
- `remoteControlSubscriber` (Function) - Required - A function that takes a callback and subscribes to remote control events, invoking the callback with a `Direction` enum. It should return a subscriber identifier.
- `remoteControlUnsubscriber` (Function) - Required - A function that takes a subscriber identifier and removes the associated event listener.
```

--------------------------------

### SpatialNavigationDeviceTypeProvider

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

Context provider to manage and detect the device type used for controlling focus.

```APIDOC
## SpatialNavigationDeviceTypeProvider

### Description
Provides context for the device type used to control focus (e.g., remote keys, remote pointer). Components can subscribe to this context to handle inputs accordingly.

### Usage
Wrap your application or relevantส่วน with this provider to enable device type detection.
```

--------------------------------

### DefaultFocus Component

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

How to use the DefaultFocus component to set the initial focus on a spatial navigation node.

```APIDOC
## DefaultFocus

### Description
Allows setting a default focus state for the first spatial navigation node within a group.

### Props
- `enable` (boolean) - Optional (default: `true`) - If `true`, enables default focus for children.
- `children` (ReactNode) - Required - The child elements that will be focusable.
```

--------------------------------

### Add Selection Behavior to Focusable View

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/tutorial.md

Add an `onSelect` prop to `SpatialNavigationFocusableView` to handle user selection events, similar to an `onPress` prop.

```diff
const Element = ({ onSelect }) => (
-  <SpatialNavigationFocusableView>
+  <SpatialNavigationFocusableView onSelect={onSelect}>
    {({ isFocused }) => (
      <View style={isFocused && { backgroundColor: 'green' }}>
        <Text>Page element</Text>
      </View>
    )}
  </SpatialNavigationFocusableView>
);

const Page = () => {
  return (
    <SpatialNavigationRoot>
-      <Element />
-      <Element />
+      <Element onSelect={() => console.log('selected first element')} />
+      <Element onSelect={() => console.log('selected second element')} />
    </SpatialNavigationRoot>
  );
};
```

--------------------------------

### SpatialNavigationNode Props

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

Configuration options for the SpatialNavigationNode component.

```APIDOC
## Props

| Name | Type | Default | Description |
|---|---|---|---|
| `onInactive` | `function` | `undefined` | Callback function to be called when the node was active and due to an updated focus, is no longer active. |
| `orientation` | `'vertical' | 'horizontal'` | `'vertical'` | Determines the orientation of the node. |
| `isFocusable` | `boolean` | `false` | Determines if the node is focusable or not. If it's `true`, the `children` prop must be a function that returns a React element and accepts a parameter with a `isFocused` property. If it's `false` or not provided, `children` can be any valid React node. |
| `alignInGrid` | `boolean` | `false` | Determines whether child lists should behave like a grid. |
| `indexRange` | `number[]` | `undefined` | Determines the indexes when using long nodes in a grid. If a grid row has one `indexRange`, you should specify each element's `indexRange`. You can check for more details in [`GridWithLongNodesPage`](https://github.com/bamlab/react-tv-space-navigation/blob/31bfe1def4a7e18e9e41f26a520090d1b7a5b149/packages/example/src/pages/GridWithLongNodesPage.tsx) example or in [lrud documentation](https://github.com/bbc/lrud/blob/master/docs/usage.md#indexrange). |
| `children` | `({ isFocused, isActive, isRootActive }: { isFocused: boolean, isActive: boolean, isRootActive: boolean }) => ReactNode` or `ReactNode` | `null` | See details of the different parameters below. Child elements of the component. It can be a function that returns a React element and accepts a parameter with a `isFocused` property when `isFocusable` is `true`. If `isFocusable` is `false` or not provided, it can be any valid React node. |
| `additionalOffset` | `number` | `0` | An additional offset used when the node is a children of a scrollview. If specified, this offset will be added to the `offsetFromStart` of the ScrollView. It allows a fine grained scroll for each scrollview item. |
```

--------------------------------

### SpatialNavigationFocusableView with Callbacks

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

Shows how to use the SpatialNavigationFocusableView component, including handling focus and select events, and passing custom props to the wrapped view. The child text color changes based on focus state.

```jsx
<SpatialNavigationFocusableView
  onFocus={() => console.log('Node gained focus')}
  onSelect={() => console.log('Node was selected')}
  orientation="horizontal"
  viewProps={{ role: 'This is my role' }}
>
  {({ isFocused }) => <Text style={{ color: isFocused ? 'red' : 'black' }}>Hello World!</Text>}
</SpatialNavigationFocusableView>
```

--------------------------------

### Provide Device Type Context with SpatialNavigationDeviceTypeProvider

Source: https://context7.com/bamlab/react-tv-space-navigation/llms.txt

Wrap your application with SpatialNavigationDeviceTypeProvider to detect the user's navigation input type (remote keys or pointer). This context is automatically used by focusable components.

```tsx
import { SpatialNavigationDeviceTypeProvider } from 'react-tv-space-navigation';

function App(): JSX.Element {
  return (
    <SpatialNavigationDeviceTypeProvider>
      {/* All components below can subscribe to device type changes.
          SpatialNavigationFocusableView, ScrollView, VirtualizedList,
          and VirtualizedGrid all use this context automatically. */}
      <AppNavigator />
    </SpatialNavigationDeviceTypeProvider>
  );
}

```

--------------------------------

### Handle Dynamic Lists with Keyed SpatialNavigationNodes

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/pitfalls.md

For dynamically changing lists of elements, wrap each element in a SpatialNavigationNode keyed by its index. This ensures the navigation nodes remain stable even if the list order changes, preventing navigation confusion.

```tsx
// DON'T ❌
<View>
  {elements.map((element) => <Element element={element} />)}
</View>
```

```tsx
// DO ✅
<View>
  {elements.map((element, index) =>
    <SpatialNavigationNode key={index}>
      <Element element={element} />)
    </SpatialNavigationNode>
  }
</View>
```

--------------------------------

### SpatialNavigationVirtualizedList Props

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

Configuration options for the SpatialNavigationVirtualizedList component.

```APIDOC
## Props

| Name | Type | Description |
|---|---|---|
| `nbMaxOfItems` | `number` | The total number of expected items for infinite scroll. This helps with aligning items and is used for pagination. If not provided, it defaults to the length of the data array. |
| `scrollDuration` | `number` | The duration of a scrolling animation inside the VirtualizedList. Defaults to 200ms. |
| `scrollBehavior` | `'stick-to-start' | 'stick-to-end' | 'jump-on-scroll'` | Determines the scrolling behavior. Defaults to `'stick-to-start'`. `'stick-to-start'` and `'stick-to-end'` fix the focused item at the beginning or the end of the visible items on screen. `jump-on-scroll` jumps from `numberOfItemsVisibleOnScreen` items when needed. Warning `jump-on-scroll` is not compatible with dynamic item size. |
| `ascendingArrow` | `ReactElement` | For web TVs cursor handling. Optional component to display as the arrow to scroll on the ascending order. |
| `ascendingArrowContainerStyle` | `ViewStyle` | For web TVs cursor handling. Style of the view which wraps the ascending arrow. Hover this view will trigger the scroll. |
| `descendingArrow` | `ReactElement` | For web TVs cursor handling. Optional component to display as the arrow to scroll on the descending order. |
| `descendingArrowContainerStyle` | `ViewStyle` | For web TVs cursor handling. Style of the view which wraps the descending arrow. Hover this view will trigger the scroll. |
| `scrollInterval` | `number` | For web TVs cursor handling. Speed of the pointer scroll. It represents the interval in ms between every item scrolled. Default value is set to 100. |
```

--------------------------------

### SpatialNavigationRoot

Source: https://context7.com/bamlab/react-tv-space-navigation/llms.txt

The root context provider for a spatial navigation tree. This component should wrap each full-screen page. The `isActive` prop can be used to enable or disable navigation on pages that are not currently visible, which is useful for multi-page applications with separate navigators.

```APIDOC
## SpatialNavigationRoot

### Description
The root context provider for a spatial navigation tree. Wrap each full-screen page in this component. Use `isActive` to enable/disable navigation on pages that are not currently visible, enabling multi-page apps with separate navigators.

### Parameters
#### Path Parameters
- **isActive** (boolean) - Required - Determines if navigation is active for this root.

#### Event Handlers
- **onDirectionHandledWithoutMovement** (function) - Optional - Called when focus hits the edge of this navigator, allowing focus to be handed off to another navigator.

### Request Example
```tsx
import { SpatialNavigationRoot } from 'react-tv-space-navigation';

const PageA = ({ isCurrentPage }: { isCurrentPage: boolean }) => (
  <SpatialNavigationRoot
    isActive={isCurrentPage}
    onDirectionHandledWithoutMovement={(direction) => {
      // Called when focus hits the edge of this navigator.
      // Use this to hand off focus to a side menu navigator.
      if (direction === 'left') {
        activateSideMenuNavigator();
      }
    }}
  >
    <MyPageContent />
  </SpatialNavigationRoot>
);
```
```

--------------------------------

### Integrate Screen Reader Accessibility with useSpatialNavigatorFocusableAccessibilityProps

Source: https://context7.com/bamlab/react-tv-space-navigation/llms.txt

Use the useSpatialNavigatorFocusableAccessibilityProps hook within a component that is a direct child of SpatialNavigationNode to provide recommended accessibility props for screen readers like TalkBack.

```tsx
import { useSpatialNavigatorFocusableAccessibilityProps, SpatialNavigationNode } from 'react-tv-space-navigation';
import { TouchableOpacity, Text } from 'react-native';

// Inner component — uses the hook here (it requires SpatialNavigationNode context)
const AccessibleButton = ({ label, isFocused }: { label: string; isFocused: boolean }) => {
  const accessibilityProps = useSpatialNavigatorFocusableAccessibilityProps();

  return (
    <TouchableOpacity
      {...accessibilityProps}
      style={{ backgroundColor: isFocused ? '#0a84ff' : '#333', padding: 12, borderRadius: 6 }}
    >
      <Text style={{ color: '#fff' }}>{label}</Text>
    </TouchableOpacity>
  );
};

// Outer focusable wrapper
const FocusableAccessibleButton = ({ label }: { label: string }) => (
  <SpatialNavigationNode isFocusable>
    {( { isFocused } ) => <AccessibleButton label={label} isFocused={isFocused} />}
  </SpatialNavigationNode>
);

```

--------------------------------

### Provide Device Type Context with SpatialNavigationDeviceTypeProvider

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

Wrap your application with SpatialNavigationDeviceTypeProvider to manage and provide the current device type (remoteKeys or remotePointer) for spatial navigation components. It defaults to 'remoteKeys'.

```tsx
function App(): JSX.Element {
  return (
    <SomeOtherProviders>
      <SpatialNavigationDeviceTypeProvider>
        <YourApp />
      </SpatialNavigationDeviceTypeProvider>
    </SomeOtherProviders>
  );
}
```

--------------------------------

### Configure Web Remote Control

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/tutorial.md

Configure the remote control for the web platform by mapping keyboard events to navigation directions. Ensure you handle event listeners and cleanup.

```tsx
import { Directions, SpatialNavigation } from 'react-tv-space-navigation';

SpatialNavigation.configureRemoteControl({
  remoteControlSubscriber: (callback) => {
    const mapping = {
      ArrowRight: Directions.RIGHT,
      ArrowLeft: Directions.LEFT,
      ArrowUp: Directions.UP,
      ArrowDown: Directions.DOWN,
      Enter: Directions.ENTER,
    };

    const eventId = window.addEventListener('keydown', (keyEvent) => {
      callback(mapping[keyEvent.code]);
    });

    return eventId;
  },

  remoteControlUnsubscriber: (eventId) => {
    window.removeEventListener('keydown', eventId);
  },
});
```

--------------------------------

### SpatialNavigationView for Rows and Columns

Source: https://context7.com/bamlab/react-tv-space-navigation/llms.txt

SpatialNavigationView is a convenience wrapper for creating rows or columns of focusable items. It combines a SpatialNavigationNode with a View and automatically sets the flex direction based on the 'direction' prop.

```tsx
import { SpatialNavigationView, SpatialNavigationFocusableView } from 'react-tv-space-navigation';
import { Text } from 'react-native';

const FocusableItem = ({ label }: { label: string }) => (
  <SpatialNavigationFocusableView onSelect={() => console.log(`Selected: ${label}`)}>
    {({ isFocused }) => (
      <Text style={{ color: isFocused ? '#0a84ff' : '#fff', padding: 12 }}>{label}</Text>
    )}
  </SpatialNavigationFocusableView>
);

// Horizontal row of items
const Row = () => (
  <SpatialNavigationView direction="horizontal" style={{ gap: 8 }}>
    <FocusableItem label="Movies" />
    <FocusableItem label="Series" />
    <FocusableItem label="Kids" />
  </SpatialNavigationView>
);

// Two rows stacked vertically (default orientation of Root is vertical)
const TwoRowLayout = () => (
  <SpatialNavigationRoot>
    <Row />
    <Row />
  </SpatialNavigationRoot>
);
```

--------------------------------

### SpatialNavigationRoot Component

Source: https://context7.com/bamlab/react-tv-space-navigation/llms.txt

The root context provider for a spatial navigation tree. Wrap each full-screen page in this component. Use `isActive` to enable/disable navigation on pages that are not currently visible, enabling multi-page apps with separate navigators. The `onDirectionHandledWithoutMovement` callback can be used to hand off focus to other navigators.

```tsx
import { SpatialNavigationRoot } from 'react-tv-space-navigation';

const PageA = ({ isCurrentPage }: { isCurrentPage: boolean }) => (
  <SpatialNavigationRoot
    isActive={isCurrentPage}
    onDirectionHandledWithoutMovement={(direction) => {
      // Called when focus hits the edge of this navigator.
      // Use this to hand off focus to a side menu navigator.
      if (direction === 'left') {
        activateSideMenuNavigator();
      }
    }}
  >
    <MyPageContent />
  </SpatialNavigationRoot>
);
```

--------------------------------

### Set Initial Focus with DefaultFocus

Source: https://context7.com/bamlab/react-tv-space-navigation/llms.txt

Use DefaultFocus to set the initial focus on a specific focusable element when a component mounts. Wrap the element that should receive focus by default.

```tsx
import {
  SpatialNavigationRoot,
  SpatialNavigationView,
  SpatialNavigationFocusableView,
  DefaultFocus,
} from 'react-tv-space-navigation';
import { Text } from 'react-native';

const NavBar = () => (
  <SpatialNavigationRoot>
    <SpatialNavigationView direction="horizontal">
      <SpatialNavigationFocusableView onSelect={() => console.log('Home')}>
        {( { isFocused } ) => <Text style={{ color: isFocused ? 'yellow' : 'white' }}>Home</Text>}
      </SpatialNavigationFocusableView>

      {/* "Series" tab receives focus on mount */}
      <DefaultFocus>
        <SpatialNavigationFocusableView onSelect={() => console.log('Series')}>
          {( { isFocused } ) => <Text style={{ color: isFocused ? 'yellow' : 'white' }}>Series</Text>}
        </SpatialNavigationFocusableView>
      </DefaultFocus>

      <SpatialNavigationFocusableView onSelect={() => console.log('Movies')}>
        {( { isFocused } ) => <Text style={{ color: isFocused ? 'yellow' : 'white' }}>Movies</Text>}
      </SpatialNavigationFocusableView>
    </SpatialNavigationView>
  </SpatialNavigationRoot>
);

```

--------------------------------

### Handle Scroll in Virtualized List

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/tutorial.md

Provide custom arrow components and container styles to enable interactive scrolling in virtualized lists. The `isActive` state can dynamically hide arrows when the list is not hovered.

```jsx
<SpatialNavigationVirtualizedList
  {...otherProps}
  descendingArrow={isActive ? <LeftArrow /> : null}
  descendingArrowContainerStyle={styles.leftArrowContainer}
  ascendingArrow={isActive ? <RightArrow /> : null}
  ascendingArrowContainerStyle={styles.rightArrowContainer}
/>
```

--------------------------------

### SpatialNavigationNode

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

A component used to handle spatial navigation. It helps describe the spatial layout of components and defines actions for focus and selection.

```APIDOC
## SpatialNavigationNode

### Description
The SpatialNavigationNode is a component that can be used to handle spatial navigation in a React application. It helps with describing the spatial layout of the components, and what to do when they are focused or selected.
```

--------------------------------

### SpatialNavigationVirtualizedGrid Props

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

These are the configurable props for the SpatialNavigationVirtualizedGrid component.

```APIDOC
## Props

- **nbMaxOfItems** (Number): The maximum number of items to render, used to compute the number of rows.
- **rowContainerStyle** (Object): Used to modify the style of each row in the grid.
- **scrollDuration** (number): The duration of a scrolling animation inside the VirtualizedList. Defaults to `200` (ms).
- **scrollBehavior** ('stick-to-start' | 'stick-to-end' | 'jump-on-scroll'): Determines the scrolling behavior. Defaults to `'stick-to-start'`. `'stick-to-start'` and `'stick-to-end'` fix the focused row at the beginning or the end of the visible items on screen. `jump-on-scroll` jumps from `numberOfItemsVisibleOnScreen` rows when needed.
- **ascendingArrow** (ReactElement): For web TVs cursor handling. Optional component to display as the arrow to scroll on the ascending order.
- **ascendingArrowContainerStyle** (ViewStyle): For web TVs cursor handling. Style of the view which wraps the ascending arrow. Hover this view will trigger the scroll.
- **descendingArrow** (ReactElement): For web TVs cursor handling. Optional component to display as the arrow to scroll on the descending order.
- **descendingArrowContainerStyle** (ViewStyle): For web TVs cursor handling. Style of the view which wraps the descending arrow. Hover this view will trigger the scroll.
- **scrollInterval** (number): For web TVs cursor handling. Speed of the pointer scroll. It represents the interval in ms between every item scrolled. Default value is set to 100.
```

--------------------------------

### Forwarding Ref with SpatialNavigationFocusableView

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

When using SpatialNavigationNode, you might need to forward refs to inner components for scrolling management. SpatialNavigationFocusableView simplifies this by allowing direct ref forwarding to a View.

```tsx
export const MyFocusableComponent = React.forwardRef<View, MyFocusableComponentProps>(
  ({ isFocused }, ref) => {
    // ...

    return (
      // pass the ref to the relevant View in your component.
      <View ref={ref}>
        <YourOtherElements />
      </View>
    );
  },
);
```

--------------------------------

### Basic SpatialNavigationNode Usage

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

Use SpatialNavigationNode to manage focus and selection events for elements. It accepts callbacks for focus and select events and can render children based on focus state.

```jsx
<SpatialNavigationNode
  onFocus={() => console.log('Node gained focus')}
  onSelect={() => console.log('Node was selected')}
  orientation="horizontal"
  isFocusable={true}
>
  {({ isFocused, isRootActive }) => <Text style={{ color: (isFocused && isRootActive) ? 'red' : 'black' }}>Hello World!</Text>}
</SpatialNavigationNode>
```

--------------------------------

### Render SpatialNavigationVirtualizedGrid

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

Use SpatialNavigationVirtualizedGrid to render a scrollable grid with spatial navigation capabilities. Ensure data is memoized for performance.

```jsx
import { SpatialNavigationVirtualizedGrid } from 'path/to/component';

// Define your data array and renderItem function
const data = [...];
const renderItem = ({ item }) => {
  return <ItemComponent item={item} />;
};

// Render the SpatialNavigationVirtualizedGrid component
<SpatialNavigationVirtualizedGrid
  // Do not forget to memoize data
  data={data}
  renderItem={renderItem}
  numberOfColumns={3}
  itemHeight={100}
  additionalItemsRendered={5}
  onEndReachedThresholdRowsNumber={2}
  rowContainerStyle={{gap: 15}}
/>
```

--------------------------------

### VirtualizedList Props

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

Configuration options for the VirtualizedList component, controlling its data, rendering, and behavior.

```APIDOC
## Props

| Name | Type | Description |
|---|---|---|
| `data` | `Array<T>` | The array of data items to render. Memoize this array for maximum performance. |
| `renderItem` | `(args: { item: T }) => JSX.Element` | A function that returns the JSX element to render for each item. |
| `itemSize` | `number | ((item: T) => number)` | The height (vertical) or width (horizontal) of an item, or a function to calculate it for variable item sizes. Memoize this function for maximal performances. |
| `additionalItemsRendered` | `number` | Optional: The number of items to render additionally to the minimum required for virtualization. Defaults to 2. |
| `onEndReached` | `() => void` | Optional callback function called when the user reaches the end of the list. Useful for pagination. |
| `onEndReachedThresholdItemsNumber` | `number` | The number of items left before triggering `onEndReached`. Defaults to 3. |
| `style` | `ViewStyle` | Custom style to be applied to the VirtualizedList container. |
| `orientation` | `'horizontal' | 'vertical'` | The orientation of the list. Defaults to `'horizontal'`. |
```

--------------------------------

### Virtualized List with Spatial Navigation

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

Use SpatialNavigationVirtualizedList for creating scrollable lists with spatial navigation. Ensure data is memoized and itemSize is provided. The orientation can be set to 'horizontal' or 'vertical'.

```jsx
import { SpatialNavigationVirtualizedList } from 'react-tv-spatial-navigation';

// Example data
const data = [
  { index: 0, name: 'Item 1' },
  { index: 1, name: 'Item 2' },
  { index: 2, name: 'Item 3' },
  // ...
];

const renderItem = ({ item }) => {
  return (
    <View>
      <Text>{item.name}</Text>
    </View>
  );
};

const MyComponent = () => {
  return (
    <SpatialNavigationVirtualizedList
      // Do not forget to memoize data
      data={data}
      renderItem={renderItem}
      // Do not forget to memoize this if you provide it as a function
      itemSize={50}
      numberOfRenderedItems={10}
      numberOfItemsVisibleOnScreen={5}
      onEndReached={() => {
        // Handle reaching the end of the list
        // you might trigger your backend pagination for example
      }}
      style={styles.container}
      orientation="horizontal"
    />
  );
};

```

--------------------------------

### SpatialNavigationView

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

The SpatialNavigationView component is a simple wrapper for SpatialNavigationNode, used to define the orientation and styling of navigation nodes.

```APIDOC
## SpatialNavigationView

The `SpatialNavigationView` component is a simple wrapper component that contains a `SpatialNavigationNode`.
This component allows you to describe the orientation along with the style of the `SpatialNavigationNode` and its children.

### Props

The `SpatialNavigationView` component receives the following props:

| Name          | Type                         | Default        | Description                                                                                                |
| ------------- | ---------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------- |
| `direction`   | `'horizontal' | 'vertical'` | `'horizontal'` | The orientation of the `SpatialNavigationNode`.                                                            |
| `alignInGrid` | `boolean`                    | `false`        | Determines whether child lists should behave like a grid.                                                  |
| `style`       | `ViewStyle`                  | `null`         | Style for the View. This can be any valid React Native style object.                                       |
| `children`    | `ReactNode`                  | `null`         | Child elements of the component. They are expected to be one or multiple `SpatialNavigationNode` elements. |

### Usage

```jsx
const FocusableNode = () => (
  <SpatialNavigationNode isFocusable={true}>
    {({ isFocused }) => <Text style={{ color: isFocused ? 'red' : 'black' }}>Hello World!</Text>}
  </SpatialNavigationNode>
);

<SpatialNavigationView direction="horizontal">
  {/* Nodes will be horizontal, and flex view will be row */}
  <FocusableNode />
  <FocusableNode />
  <FocusableNode />
</SpatialNavigationView>;
```

In this example, a `SpatialNavigationView` is created with vertical direction and a padding of 20 pixels provided by the style prop. It contains a single `SpatialNavigationNode`. When the node gains focus, the navigation adjusts according to the orientation.
```

--------------------------------

### SpatialNavigationRoot

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/docs/api.md

The root component for spatial navigation. It manages context providers and the registration/unregistration of the root node. It also handles locking/unlocking the navigator based on its activity state.

```APIDOC
## SpatialNavigationRoot

### Description
The `SpatialNavigationRoot` is the root component that contains all the spatial navigation nodes. It manages the context providers and handles the registration and unregistration of the root node. This component is also responsible for locking or unlocking the spatial navigator based on its activity state.

### Props
#### `isActive` (boolean) - Default: `true`
Determines if the spatial navigation is active. If `false`, the spatial navigation will be locked, and no nodes can be focused. This is useful to handle a multi-page app: you can disable the non-focused pages' spatial navigation roots.

#### `onDirectionHandledWithoutMovement` ((direction: Direction) => void) - Default: `undefined`
Called when you're reaching a border of the navigator. A use case for this would be the implementation of a side menu that's shared between pages. You can have a separate navigator for your side menu, which would be common across pages, and you'd make this menu active when you reach the left side of your page navigator.

#### `children` (ReactNode) - Default: `null`

### Usage
```jsx
<SpatialNavigationRoot>
  <SpatialNavigationNode>
    <Text>Hello World!</Text>
  </SpatialNavigationNode>
</SpatialNavigationRoot>
```
```

--------------------------------

### Define Page with Root Node and Vertical ScrollView

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/README.md

Add a page with a Root node and a vertical scroll view to scroll through rows. This sets up the main navigation structure for the application.

```tsx
/**
 * Now I simply add a page with a Root node and a vertical scroll view to scroll through my rows.
 */
const Page = () => (
  <SpatialNavigationRoot>
    <SpatialNavigationScrollView>
      <RabbitRow />
      <RabbitRow />
      <RabbitRow />
      <RabbitRow />
      <RabbitRow />
      <RabbitRow />
    </SpatialNavigationScrollView>
  </SpatialNavigationRoot>
);
```

--------------------------------

### Create Horizontal Rabbit Row with ScrollView

Source: https://github.com/bamlab/react-tv-space-navigation/blob/main/README.md

Group rabbits in a horizontal spatial navigation view to spatially describe a row layout. Includes a spatial navigation node and horizontal styling. Adds a horizontal scrollview for scrolling.

```tsx
/**
 * We can have as many nodes as we want. We group our rabbits in a horizontal spatial navigation view
 * to spatially describe a row layout
 * (it includes a spatial navigation node AND the horizontal styling for it)
 *
 * We also want to scroll horizontally, so we add a horizontal scrollview.
 */
const RabbitRow = () => (
  <SpatialNavigationScrollView horizontal>
    <SpatialNavigationView direction="horizontal">
      {/* assuming you have rabbits data */}
      {rabbits.map((_, index) => (
        <Rabbit onSelect={() => console.log('selected rabbit ', index)} />
      ))}
    </SpatialNavigationView>
  </SpatialNavigationScrollView>
);
```