@24i/bigscreen-sdk 0.9.9-alpha.2147

package/packages/epg/README.md

@@ -0,0 +1,582 @@
+---
+id: README
+title: EPG V2
+hide_title: true
+sidebar_label: EPG V2
+---
+
+# EPG
+This package contains a prepared Electronic Program Guide component.
+
+**All timestamps are in milliseconds.**
+
+## Props
+- `timelineWidthPx` - the width of the timeline (the part where the programs are) in pixels
+- `rowHeightPx` - the height of 1 row in pixels
+- `navigatableRows` - the number of rows that can be navigated with focus
+- `additionalRows` - the number of rows that are rendered below `navigatableRows` but cannot be focused
+- `channelHeaderWidthPx` - the width of the channel headers (the part before programs in a row) in pixels
+- `channelData` - the array of channels of a type that extends `EpgChannel` from the data layer
+- `fetchPrograms` - the function to fetch more programs for a channel in a given time range
+- `timelineWidthMs` - optional - the width of the timeline (the part where the programs are) in milliseconds (defaults to `90 minutes`)
+- `scrollStepMs` - optional - the amount of movement step left/right in milliseconds (defaults to `0.5 hours`)
+- `timelineSectionWidthMs` - optional - the width of timeline header section (above rows) in milliseconds (defaults to `0.5 hours`)
+- `limitFromMs` - optional - left limit for movement (cannot go more into history) (defaults to `-Infinity`)
+- `limitToMs` - optional - right limit for movement (cannot go further into future) (defaults to `Infinity`)
+- `timeProvider` - optional - a function returning current timestamp (defaults to `Date.now`)
+- `initialTimestamp` - optional - an initial point in time for EPG render (must be between `limitFromMs` and `limitToMs`) (defaults to `Date.now()`)
+- `initialChannelIndex` - optional - an initial channel index to scroll to and to focus (defaults to `0`)
+- `fetchDebounceTimeMs` - optional - time to debounce the fetch of programs (defaults to `500`)
+- `programTextModeResolver` - optional - function to set custom no-text/ellipsis-only/full-text breakpoints
+- `onItemPress` - callback for pressing an item
+- `onFocusChange` - optional - callback for changing a focus (works for mouse/mrcu as well)
+- `onScrolledToTimestamp` - optional - callback that is called with the current timestamp after scroll
+- `renderNowLineHeader` - optional - render function for now line header (e.g. the live pointer arrow)
+- `renderChannelHeader` - optional - render function for channel header (defaults to channel number and name)
+- `renderProgram` - optional - render function for program (the inside of each cell) (defaults to program name)
+- `renderDay` - optional - render function for day/date counter in the header (defaults to locale day, date, short month)
+- `renderTime` - optional - render function for timeline section (defaults to `hh:mm` and vertical pointer)
+- `datePickerProps` - optional - props for a DatePicker, if present DatePicker replaces `renderDay`
+- `plugins` - optional - an array of plugins
+
+## Plugins
+The EPG supports plugins. Plugins are rendered at the end of the component, in the order of being inside
+the `plugins` prop.
+Plugins can react to scrolling, focus changes and item press events. They can also control EPG through
+its public interface.
+
+Available prepared plugins:
+- ProgramInfo - a box that shows more info from the currently focused program
+- DateToast - a toast that is displayed during fast horizontal scrolling and shows the current day and time
+
+## Translations
+These are keys for translations that are used in EPG:
+- `date.yesterday` - used in the DatePicker, Day and DateToast for 'Yesterday' string
+- `date.today` - used in the DatePicker, Day and DateToast for 'Today' string
+- `date.tomorrow` - used in the DatePicker, Day and DateToast for 'Tomorrow' string
+- `epg.noData.title` - used in no-data holes fillers as a Program name
+- `common.status.loading` - used in the loading cells as a Program name
+- `common.status.loading` - it is displayed when the ProgramInfo is loading data
+
+## How the EPG behaves
+- the time that EPG operates with is always in the center of the visible part
+  - `onScrolledToTimestamp` returns the timestamp in the center of the EPG
+  - `leftEdge` is always `currentTimestamp - timelineWidthMs / 2`
+  - `rightEdge` is always `currentTimestamp + timelineWidthMs / 2`
+  - `scrollToTimestamp` will move the EPG so the passed timestamp is in the center
+- the time of the EPG is always rounded
+  - for better UX experience, the EPG rounds down (floors) the given timestamp
+to the closest `scrollStepMs` multiple
+  - e.g., the current time is 13:55, `scrollStepMs` is set to default 0.5 hours,
+then the initial time of EPG will be `13:30` (if not set otherwise)
+  - this rounding also applies to `scrollToTimestamp` function and `initialTimestamp` prop
+- the focus inside a channel jumps to the next/previous program
+  - if the next/previous program is not visible in the range or it is just partially visible at the edge, the EPG scrolls by `scrollStepMs`
+- the focus between channels is driven by so-called `focusTimestamp`
+  - you can imagine the `focusTimestamp` as a vertical line (similar to NowLine) that marks the horizontal position of the focus
+- the decision which program to focus, mark as live, etc. if the timestamp is exactly `startTime` of one and `endTime` of another
+  - `startTime` is always taken as included = the part of the program
+  - `endTime` is always taken as excluded = not the part of the program
+  - so the program that gets focused/marked as live / etc. is the one that is just starting
+- when the Program displayed by the cell is currently live, the cell has an `.live` class
+- the Cell has also these following classes based on its width and breakpoints defined by `programTextModeResolver`
+  - `.with-text` - this cell should display full or ellipsis truncated text
+  - `.ellipsis-only` - this cell should display only ellipsis. You can use this class to center the text.
+  - `.no-text` - this cell is so small that it should be empty
+- the element of the currently focused row has an `.active` class
+
+## Styles
+There is a base for styles available for `import '@24i/bigscreen-sdk/epg/styles/Basic';`.
+(see [./styles/Basic.ts](https://github.com/24i/smartapps-bigscreen-sdk/blob/development/packages/epg/styles/Basic.ts))
+
+## Interfaces
+
+### EPG
+```ts
+interface EPG<
+    T extends EpgProgram,
+    U extends EpgChannel<T>,
+    V extends Header<U>,
+    W extends Program<T>,
+> extends Component<Props>, IFocusable {
+    /**
+     * Function to return whether EPG is fast scrolling
+     * @returns true if is fast scrolling in any axis, false otherwise
+     */
+    isFastScrolling: () => boolean,
+    /**
+     * Function to return whether EPG is fast scrolling horizontally
+     * @returns true if is fast scrolling horizontally, false otherwise
+     */
+    isHorizontallyFastScrolling: () => boolean,
+    /**
+     * Function to return whether EPG is fast scrolling
+     * @returns true if is fast scrolling vertically, false otherwise
+     */
+    isVerticallyFastScrolling: () => boolean,
+    /**
+     * Scrolls to given timestamp if possible, rounded down to nearest scrollStepMs multiple
+     * @param timestamp Timestamp to scroll to
+     * @throws when the timestamp is outside of limitFromMs and limitToMs range
+     */
+    scrollToTimestamp: (timestamp: number) => void,
+    /**
+     * Scrolls to given channel index if possible
+     * @param index Index of the channel to scroll to
+     * @throws when the index is outside of 0 and channels.length - 1 range
+     */
+    scrollToChannelIndex: (index: number) => void,
+}
+```
+
+### fetchPrograms
+```ts
+type ProgramsFetcher<
+    T extends EpgProgram,
+    U extends EpgChannel<T>,
+> = (channel: U, fromMs: number, toMs: number) => Promise<T[]>;
+```
+
+### programTextModeResolver
+```ts
+type ProgramTextMode = 'full' | 'ellipsis_only', 'empty';
+
+/**
+ * Function to set custom breakpoints for different cell display styles
+ * @param widthPx the width of the cell in pixels
+ * @returns ProgramTextMode which mode should be displayed
+ */
+type ProgramTextModeResolver = (widthPx: number) => ProgramTextMode;
+```
+
+### onItemPress
+```ts
+type OnItemPress<
+    T extends EpgProgram, // the model of the program used in the EPG
+    U extends EpgChannel<U>, // the model of the channel used in the EPG
+    V extends Program<T>, // the component rendered with renderProgram
+> = (data: T, channel: U, component: V) => void;
+```
+`onItemPress` is not called for loading indicating cells.
+
+### onFocusChange
+```ts
+type OnFocusChange<
+    T extends EpgProgram, // the model of the program used in the EPG
+    U extends EpgChannel<U>, // the model of the channel used in the EPG
+    V extends Program<T>, // the component rendered with renderProgram
+> = (data: T | undefined, channel: U, component: V) => void;
+```
+`onFocusChange` is called each time a cell is focused. This can happen in multiple ways and can result
+in the same data getting focused. In case a loading cell is focused, the `data` is undefined.
+
+Events causing `onFocusChange`:
+- moving left/right between programs
+- moving up/down between channels
+- focusing cells with mouse or mrcu
+- data in cells getting updated with new data
+
+### onScrolledToTimestamp
+```ts
+type OnScrolledToTimestamp = (timestamp: number) => void;
+```
+`onScrolledToTimestamp` is called each time the EPG scrolls to a new timestamp in ms. It is not called for
+the initial render.
+
+### renderNowLineHeader
+This function allows a custom render of the top of the NowLine. NowLine is a vertical
+line that indicates the current time on the timeline. In most cases, this can be used to add a custom
+header to this line (e.g., an arrow pointer with LIVE). NowLine header can be a pure functional
+component. If you display the current time inside the header, you should implement NowLineHeader interface
+and then you can update it based on the current time easily.
+```ts
+interface NowLineHeader extends Component<any> {
+    updateData: (timestamp: number) => void, // current time in ms
+}
+
+type NowLineHeaderRenderer = (timestamp: number, ref: Reference<NowLineHeader>) => JSX.Element;
+```
+
+### renderChannelHeader
+This function allows changing the default channel header render. Because this component
+can be reused by multiple channels during its lifetime, it needs to implement `EpgHeader`
+interface.
+```ts
+interface Header<
+    T extends EpgChannel
+> extends Component<any> {
+    show: () => void, // to show the header
+    hide: () => void, // to hide the header
+    updateData: (data: T) => void, // to update rendered data
+}
+
+type HeaderRenderer<
+    T extends EpgChannel,
+    U extends EpgHeader<T>,
+> = (data: T, ref: Reference<U>) => JSX.Element;
+```
+
+### renderProgram
+This function allows changing the default program cell content. The cell component that
+takes the care of focusing, pressing, showing and hiding is rendered by the EPG component.
+This makes this component easier as it only needs to handle the visuals.
+This component can also be reused by multiple programs and multiple channels.
+```ts
+ interface Program<T extends EpgProgram>
+    extends Component<any> {
+    /**
+     * Function to offset the Program component inside the cell.
+     * This is so the cells at the start of the viewport show text from the beginning
+     * even though the Cell itself goes more to the past.
+     * @param offset offset in x axis in px
+     */
+    setOffset?: (offset: number) => void,
+    /**
+     * Function to change the width of the Program component inside the cell.
+     * This is so the cells at the start of the viewport show text from the beginning
+     * even though the Cell itself goes more to the past.
+     * @param width width in px
+     */
+    setWidth?: (width: number) => void,
+    /**
+     * Function to change data and the visuals.
+     * (E.g. Use setText to change the name)
+     * @param data New Program data
+     * @param textMode ProgramTextMode that should be used currently
+     * @param widthPx Cell's width if needed for visuals (e.g. showing/hiding replay icon)
+     * @param xOffsetPx Cell's offset in pixels. If negative than widthPx + xOffsetPx = visibleWidthPx
+     */
+    updateData: (data: T, textMode: ProgramTextMode, widthPx: number, xOffsetPx: number) => void,
+}
+
+/**
+ * This function should return custom visual for Program.
+ * @typeparam T EpgProgram model - defaults to data-layer/models EpgProgram
+ * @typeparam U Program component - defaults to EpgProgram component
+ * @param isLoading Flag to mark whether it is just a loading placeholder
+ * @param data Program data or undefined for loading placeholder
+ * @param ref Reference to the component
+ * @param widthPx The initial width of the Program component to render with
+ * @param xOffsetPx The initial offset of the Program component to render with
+ * @param textMode ProgramTextMode for initial render
+ * @returns JSX.Element
+ */
+export type ProgramRenderer<
+    T extends EpgProgram,
+    U extends Program<T>,
+> = (
+    isLoading: boolean,
+    data: T | undefined,
+    ref: Reference<U>,
+    widthPx: number,
+    xOffsetPx: number,
+    textMode: ProgramTextMode,
+) => JSX.Element;
+```
+
+### renderDay
+This function allows changing the default day/date displayed in the timeline header.
+As the date changes, the day component needs to change as well. Therefore it needs to
+extend interface.
+```ts
+interface Day extends Component<any> {
+    updateData: (timestamp: number) => void,
+}
+
+type DayRenderer<
+    T extends Day = Day,
+> = (timestamp: number, ref: Reference<T>) => JSX.Element;
+```
+
+### renderTime
+This function allow changing the default time rendered in the timeline header.
+Similar to other components it can be reused to display multiple times so it needs an
+update function (interface to extend).
+```ts
+interface TimelineSection extends Component<any> {
+    setOffset: (x: number) => void, // function to change the offset during scroll
+    updateData: (timestamp: number) => void, // function to update the displayed time
+}
+
+type TimeRenderer<
+    T extends TimelineSection = TimelineSection,
+> = (timestamp: number, offset: number, ref: Reference<T>) => JSX.Element;
+```
+
+### datePickerProps
+This prop can be used to render a DatePicker that seamlessly integrates with the EPG.
+If these are omitted, the `renderDay` component is displayed instead.
+The EPG uses regular `DatePicker` component from the [@24i/bigscreen-sdk/picker](../picker/README.md) package.
+The set of props that you need to pass to the EPG is limited (some props are provided by EPG)
+as well as extended to allow more functionality.
+
+The props that **you need to provide** are:
+- daysInPast - number of days in past to allow to be selected (EPG converts this to `from` prop for `DatePicker`)
+- daysToFuture - number of days in future to allow to be selected (EPG converts this to `to` prop for `DatePicker`)
+- visibleItems - number of items visible in the Picker (passed directly to `DatePicker`)
+- scrollStep - number of pixels to scroll on each Picker item (passed directly to `DatePicker`)
+- modalService - reference to modal service that the Picker should use (passed directly to `DatePicker`)
+
+The props that **EPG handles by itself and cannot be changed** (do not pass these, it won't change anything):
+- selectedValue - timestamp of the initial selected day - it is generated based on the EPG timestamp
+- onValueChange - callback for value change handled by EPG - if you want, you can listen to EPG's
+`onScrolledToTimestamp` that will be fired consequently to this event
+
+The props that **EPG handles by itself but can be overridden by you** (you can pass these):
+- dayStartOffsetMs - optional - number of milliseconds to start of the day
+(the time that is displayed after choosing the day) (defaults to 0) (impacts generated `from` and `to`)
+- format - optional - function to convert Date object to string
+(defaults to `l10n.date(date).toLocaleDateString({ weekday: 'short', day: 'numeric', month: 'short' })`)
+- overrides - optional - `Record<number, string>` object to override string values from format
+(defaults to object for strings `yesterday`, `today` and `tomorrow`)
+- mode - optional - PickerMode to use (defaults to `Picker.MODAL`)
+- className - optional - className to render DatePicker with (no default value --> Picker's default value will be used)
+- Checkbox - optional - Checkbox component to pass to DatePicker (no default value --> Picker's default value will be used)
+
+### plugins
+EPG allows custom plugins to be rendered. They are rendered at the end of the EPG component (`div.epg`)
+in the order, they are in the `plugins` prop.
+
+```tsx
+// how EPG renders plugins
+return (
+    <div className="epg">
+        {/* All default EPG Components go here */}
+        {map(plugins, (Plugin) => (
+            <Plugin ref={this.getPluginRef()} epg={this} />
+        ))}
+    </div>
+)
+```
+
+The plugins can be either static or react to these events:
+- `onFocusChange`
+- `onItemPress`
+- `onScrolledToTimestamp`
+- `onFastScrollingStart`
+- `onFastScrollingEng`
+- `onFastVerticalScrollingStart`
+- `onFastVerticalScrollingEnd`
+- `onFastHorizontalScrollingStart`
+- `onFastHorizontalScrollingEnd`
+
+To achieve this behavior, the plugin should (but does not have to) implement the `Plugin` interface.
+In the case of a static plugin, it can be just a simple function component.
+
+```ts
+interface Plugin<
+    T extends EpgProgram = EpgProgram,
+    U extends EpgChannel<T> = EpgChannel<T>,
+    V extends Program<T> = Program<T>,
+> extends Component<any> {
+    /**
+     * Called each time a focus changes. Due to implementation this can result
+     * in focus to different element with same data as before as same element
+     * but different data. And also same element and same data
+     */
+    onFocusChange?: (data: T | undefined, channel: U, component: V) => void;
+    /**
+     * Called each time EPG scrolls left/right in time
+     * @param timestamp current time of EPG in ms
+     */
+    onScrolledToTimestamp?: (timestamp: number) => void,
+    /**
+     * Called each time the Item is pressed. This is called before the outside
+     * callback from props. However, it cannot stop the event. Intended more for
+     * logging purposes than actual overrides.
+     */
+    onItemPress?: (data: T, channel: U, component: V) => void;
+    /**
+     * Called each time EPG switches to fast scrolling in either direction.
+     * Called after onFast[Vertical/Horizontal]ScrollingStart.
+     * If both are implemented, then both (directional and general) methods are called.
+     */
+    onFastScrollingStart?: () => void,
+    /**
+     * Called each time EPG switches to fast scrolling in vertical (channels) direction.
+     */
+    onFastVerticalScrollingStart?: () => void,
+    /**
+     * Called each time EPG switches to fast scrolling in horizontal (time) direction.
+     */
+    onFastHorizontalScrollingStart?: () => void,
+    /**
+     * Called each time EPG switches back to normal scrolling in either direction.
+     * Called after onFast[Vertical/Horizontal]ScrollingEnd.
+     * If both are implemented, then both (directional and general) methods are called.
+     */
+    onFastScrollingEnd?: () => void,
+    /**
+     * Called each time EPG switches back to normal scrolling in vertical (channels) direction.
+     */
+    onFastVerticalScrollingEnd?: () => void,
+    /**
+     * Called each time EPG switches back to normal scrolling in horizontal (time) direction.
+     */
+    onFastHorizontalScrollingEnd?: () => void,
+}
+```
+
+There are several plugins already prepared. They do not import styles by default,
+so you need to import the styles by yourself.
+
+#### ProgramInfo
+Component that displays additional information about the focused program. The ProgramInfo show is
+debounced, so it does not display itself immediately.
+
+It hides itself during fast vertical scrolling. During horizontal scrolling (normal or fast) it
+displays "Loading..." text.
+
+If no detail information could've been obtained, "No information..." text is shown.
+
+If you want to change the debounce time (default is 700ms), you can do so through props. Then you will
+need to slightly alter the way you pass the plugin to the EPG component:
+```tsx
+import { ProgramInfo } from '@24i/bigscreen-sdk/epg/ProgramInfo';
+
+// using default debounce time
+return (
+    <EPG
+        // ...
+        plugins={[
+            ProgramInfo,
+        ]}
+    />
+);
+
+// with custom debounce time
+return (
+    <EPG
+        // ...
+        plugins={[
+            forwardRef((props, ref) => (
+                <ProgramInfo ref={ref} {...props} debounceMs={1000} />
+            )),
+        ]}
+    />
+)
+```
+
+#### DateToast
+Component that shows a toast with current date and time during fast horizontal scrolling.
+```tsx
+import { DateToast } from '@24i/bigscreen-sdk/epg/DateToast';
+
+return (
+    <EPG
+        // ...
+        plugins={[
+            DateToast,
+        ]}
+    />
+);
+```
+
+#### Example of a custom logging plugin
+```tsx
+import { Component } from '@24i/bigscreen-sdk/jsx';
+import { Plugin } from '@24i/bigscreen-sdk/epg/interface';
+import { EpgProgram, EpgChannel } from '@24i/smart-apps-data-layer/epg';
+
+export class PressLogger<
+    T extends EpgProgram,
+    U extends EpgChannel<T>,
+> extends Component<{}> implements Plugin {
+    onItemPress(data: T, channel: U) {
+        log({ data, channel });
+    }
+
+    render() {
+        return null;
+    }
+}
+```
+and then in EPG render:
+```tsx
+render() {
+    // ...
+    return (
+        // ...
+        <EPG
+            //...
+            plugins={[
+                PressLogger,
+            ]}
+        />
+    );
+}
+```
+
+## Examples
+
+### Minimal
+Minimal example of EPG with as much default stuff as possible:
+```tsx
+return (
+    <EPG
+        timelineWidthPx={500}
+        rowHeightPx={50}
+        navigatableRows={4}
+        additionalRows={3}
+        channelHeaderWidthPx={200}
+        channelData={this.channels}
+        fetchPrograms={this.fetchPrograms}
+        onItemPress={this.onItemPress}
+    />
+);
+```
+
+### Full
+Full example with as much modifications as possible:
+```tsx
+return (
+    <EPG
+        timelineWidthPx={500}
+        timelineWidthMs={4 * HOUR_IN_MS}
+        rowHeightPx={50}
+        navigatableRows={4}
+        additionalRows={3}
+        channelHeaderWidthPx={200}
+        scrollStepMs={HOUR_IN_MS}
+        timelineSectionWidthMs={15 * MINUTE_IN_MS}
+        limitFromMs={Date.now - WEEK_IN_MS}
+        limitToMs={Date.now + WEEK_IN_MS}
+        channelData={this.channels}
+        fetchPrograms={this.fetchPrograms}
+        timeProvider={() => time.getCurrentTime()}
+        initialTimestamp={getTodayNoon()}
+        initialChannelIndex={this.getCurrentChannelIndex()}
+        onItemPress={this.onItemPress}
+        onFocusChange={this.onFocusChange}
+        onScrolledToTimestamp={this.onScrolledToTimestamp}
+        renderNowLineHeader={
+            () => <NowLineHeader />
+        }
+        renderChannelHeader={
+            (data: U, ref: V) => <ChannelHeader ref={ref} channel={data} />
+        }
+        renderProgram={
+            (isLoading: boolean, data: T | undefined, ref: W) => (
+                <Program ref={ref} data={data} isLoading={isLoading} />
+            )
+        }
+        renderTime={
+            (timestamp: number, offset: number, ref: Reference<TimelineHeader>) => (
+                <TimelineHeader ref={ref} timestamp={timestamp} offset={offset} />
+            )
+        }
+        datePickerProps={{
+            daysInPast: 7,
+            daysToFuture: 7,
+            visibleItems: 10,
+            scrollStep: 72,
+            modalService,
+            dayStartOffsetMs: 12 * HOUR_IN_MS,
+        }}
+        plugins={[
+            ProgramInfo,
+            DateToast,
+        ]}
+    />
+);
+```