npm package: @livetv-app/tvguide
Description: An Android TV Live Channels-like Electronic Programme Guide for React DOM and React Native applications.
Author: Samuel Elliott
Latest version: 0.2.0

React Programme Guide
===

An Android TV Live Channels-like Electronic Programme Guide for React and React Native applications.

![Grid screenshot](assets/screenshots/Screenshot%202021-01-03%20at%2021.00.19.png)

![List screenshot](assets/screenshots/Screenshot%202021-01-03%20at%2022.29.21.png)

- [x] Grid view
    - Material design similar to Android TV's Live Channels app
    - Supports extended data fields (channel logos, programme series/episode information, programme images, etc) - see https://gitlab.fancy.org.uk/livetv-app/epgdata
    - Supports custom actions for programmes (e.g. Open in BBC iPlayer)
    - Renderer support:
        - [x] React DOM
        - [x] React Native
        - Supports pointer/touch controls, and directional controls for TVs
    - TODO:
        - [ ] Automatic directional controls handling with react-native-tvos
            - Support tvOS touch controls
        - [x] Automatically scroll when using directional controls
            - ~~Fix issue where a keypress might not do anything due to the scroll limit~~
        - [ ] Adapt to the system reduced transparency preference
        - [ ] Scrolling animations
        - [ ] Disable scrolling animations when the system reduced motion preference is enabled
        - [ ] Support using a custom colour scheme
        - [x] Support setting scrolling boundaries
        - [x] Hooks for loading additional data when scrolling to the end of the loaded data
- [x] Channels list view
    - Lists channels with their name and number or icon
    - Shows the current and next programme and it's start time
    - Automatically adapts to the system colour scheme
    - Renderer support:
        - [ ] React DOM
        - [x] React Native
        - Only supports pointer/touch controls
- [ ] Programmes list view
    - Show programmes in a list with details similar to the grid view
    - Group programmes by date (like Outlook's agenda view)
    - To be used with the channels list view, after pressing a channel

Data
---

Data is provided in formats defined in https://gitlab.fancy.org.uk/livetv-app/epgdata. This project also includes utilities to read XMLTV data and other formats.

```ts
import { Channel, Programme } from '@livetv-app/epgdata';

const channels: Channel[] = [
    // ...
];

const programmes: Programme[] = [
    // ...
];
```

Grid view
---

The `ProgrammeGuide` component expects two props: `channels` and `programmes`. A third prop, `channel` can be provided to indicate which channel is active - this is different to the channel that is currently selected in the guide.

```tsx
import { ProgrammeGuide } from '@livetv-app/tvguide';

const channels: Channel[] = /* ... */;
const programmes: Programme[] = /* ... */;
const channel: Channel | null = /* ... */;

<ProgrammeGuide channels={channels} programmes={programmes} channel={channel} />
```

All props are expected to be immutable. When updating any data in either the `channels` or `programmes` array the entire array must be replaced. Programmes are linked to channels by the channel ID, not any object instance, so updating data in only one array does not require updating the other.

### Scrolling

To enable (vertical) scrolling in the programme guide set the `internalScrolling` prop.

```tsx
<ProgrammeGuide channels={channels} programmes={programmes} channel={channel} internalScrolling />
```

### Passing user input

To support directional controls you must use a reference to send input events.

```tsx
const ref = React.createRef<ProgrammeGuideRef>(null);

<ProgrammeGuide
    channels={channels} programmes={programmes} channel={channel}
    onSelectChannel={c => setChannel(c.id)}
    ref={ref} />

// When user input is received...
if (event.key === 'Enter') ref.current?.sendSelectKeypress();
if (isLongSelect) ref.current?.sendLongSelectKeypress();
if (event.key === 'ArrowUp') ref.current?.sendUpKeypress();
if (event.key === 'ArrowDown') ref.current?.sendDownKeypress();
if (event.key === 'ArrowLeft') ref.current?.sendLeftKeypress();
if (event.key === 'ArrowRight') ref.current?.sendRightKeypress();
```

By default scrolling up/down at the end of the list will scroll to the other end, and scrolling left/right at a boundary will be ignored. This can be changed by passing options to the `send*Keypress` functions and watching the return value.

```ts
const result = event.key === 'Enter' ? ref.current?.sendSelectKeypress() :
    isLongSelect ? ref.current?.sendLongSelectKeypress() :
    event.key === 'ArrowUp' ? ref.current?.sendUpKeypress(/* wrap */ false) :
    event.key === 'ArrowDown' ? ref.current?.sendDownKeypress(/* wrap */ false) :
    event.key === 'ArrowLeft' ? ref.current?.sendLeftKeypress() :
    event.key === 'ArrowRight' ? ref.current?.sendRightKeypress() : null;

if (result === KeypressResult.IGNORED_DUE_TO_BOUNDARY) [
    // ...
]
```

### Scroll boundaries

Scroll boundaries can be set using the `leftBoundary` and `rightBoundary` props.

```tsx
const DAY = 1000 * 60 * 60 * 24;
// 12:00 am, 7 days in the past
const leftBoundary = new Date((Math.floor(Date.now() / DAY) * DAY) - (DAY * 7));
// 12:00 am, 7 days in the future
const rightBoundary = new Date((Math.ceil(Date.now() / DAY) * DAY) + (DAY * 7));

<ProgrammeGuide
    channels={channels} programmes={programmes} channel={channel}
    leftBoundary={leftBoundary} rightBoundary={rightBoundary} />
```

### Lazy loading data

Use the `onScroll` prop to react to the current scroll window.

```tsx
function onScroll({top, bottom, left, right}: {
    top: Channel;
    bottom: Channel;
    left: Date;
    right: Date;
}) {
    // Load any new data if necessary
    // This will be called on every scroll event so you should wait until some specific point is passed before doing anything
}

<ProgrammeGuide
    channels={channels} programmes={programmes} channel={channel}
    onScroll={onScroll} />
```

List view
---

The list views are designed for use on mobile devices, and only show the current and uncoming programme.

The `ChannelList` component expects only a `channels` and `programmes` prop, and optionally a `onChannelPressed` prop.

```tsx
import * as React from 'react';
import { Text, View } from 'react-native';
import { NavigationContainer } from '@react-navigation/native';
import { createStackNavigator } from '@react-navigation/stack';
import { ChannelList, ProgrammeList } from '@livetv-app/tvguide';

function ChannelListScreen({navigation}) {
    const {channels, programmes} = /* ... */;

    return <View>
        <ChannelList channels={channels} programmes={programmes}
            onChannelPressed={c => navigation.navigate('Channel', {id: c.id})} />
    </View>;
}

function ChannelScreen({navigation, route}) {
    const {programmes} = /* ... */;

    return <View>
        <ProgrammeList programmes={programmes.filter(p => p.channel === route.params.id)} />
    </View>;
}

const Stack = createStackNavigator();

function App() {
    return <NavigationContainer>
        <Stack.Navigator>
            <Stack.Screen name="Channels" component={ChannelListScreen} />
            <Stack.Screen name="Channel" component={ChannelScreen} />
        </Stack.Navigator>
    </NavigationContainer>;
}
```