@livetv-app/tvguide

React Programme Guide
===

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

!Grid screenshot

!List screenshot

- [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 = / ... /;


`

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.

$3

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

`tsx

`

$3

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

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

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) [
// ...
]
`

$3

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));

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

$3

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
}

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
onChannelPressed={c => navigation.navigate('Channel', {id: c.id})} />
;
}

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

return
p.channel === route.params.id)} />
;
}

const Stack = createStackNavigator();

function App() {
return




;
}
``