@24i/bigscreen-sdk 1.0.32 → 1.0.33-alpha.2549

package/packages/epg/IMPLEMENTATION.md

@@ -1,228 +1,228 @@
----
-id: IMPLEMENTATION
-title: EPG V2 Implementation
-hide_title: true
-sidebar_label: EPG V2 Implementation
----
-
-# EPG Implementation
-This document describes the implementation details of the EPG component and its parts.
-For a more detailed technical description of all interfaces, head over to the [interface.ts](./interface.ts) file.
-
-**All timestamps are in milliseconds.**
-
-The EPG Component is in ideal case a self contained component that can render the EPG.
-
-The behaviour of the component regarding to the time is that it rounds itself based on the `scrollStepMs`.
-If no `initialTimestamp` is passed the center of the EPG is a current timestamp floored to the nearest
-scrollStepMs value. Similarly every time the displayed time of the EPG changes (after scrolling,
-date picker value selected, or from the outside) it does the same rounding again.
-
-E.g. The current time is 13:55, no `initialTimestamp` is given and no `scrollStepMs` is given.
-In this case the `scrollStepMs` will be default value (30 minutes). So the center of the EPG will be
-time 13:30 and the NowLine (as well as live program highlight) will be moved right of the center to
-the corresponding 13:55 time.
-
-## Structure
-```txt
-EPG - the main EPG component that glues everything together and handles time and "time" position of the focus
-    - `DataManager[]` - handles data fetching and ordering
-    - `Time` - time module that uses timeProvider to handle current time and time updates through EPG
-    - `NowLine` - component that represents the current time in the EPG
-    - `Timeline` - header of the EPG that shows each time segments
-    - `Day` - the current day component
-    - `DatePicker` - component for picking days
-    - `RowsManager` - renderer for the rows, manages scrolling and focusing through rows and its data
-        - `Row[]` - manager for data within the row, manages getting new data on scrolls
-            - `CellsManager` - renderer for the cells, manages scrolling and focusing between cells
-                - `Cell[]` - component that renders 1 program data, handles mouse/mrcu and press action
-                    - `Program` - visual component for 1 cell
-    - `MouseNavigation` - component that renders mouse arrows on certain platforms
-    - `Plugin[]`
-```
-
-## Fast Scrolling
-Fast scrolling is a term that says that the user is moving inside the EPG by holding a button for
-movement. In this fast scrolling state there are these changes:
-- fetching data is debounced until the movements stops and only the needed data for the viewport are
-then fetched.
-- if `DateToast` plugin is enabled then it will be displayed over the epg component
-- in most cases only 1 "loading..." cell will be visible
-
-## Mockup
-```txt
-/**
- * Current time: 13:55
- * initialTimestamp: not set (defaults to current time)
- * scrollStepMs: not set (defaults to 30 minutes)
- * timelineSectionWidthMs: not set (defaults to 30 minutes)
- * The initial render of the EPG aims at time:
- * Math.floor(currentTimestamp / scrollStepMs) * scrollStepMs
- * which results in 13:30 and it is the center of the EPG viewport
- */
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-|  Day / DatePicker                                                  |
-|12:00        12:30       13:00       13:30        14:00       14:30 |
-|  |            |           |           |         NOW|           |   |
-|--------------------------------------------------█-----------------|
-| Channel A | Program 1 | Program 2                █ | Pro... | Progr|
-|--------------------------------------------------█-----------------|
-| Channel B | m 5 | Program 6           | Program 7█                 |
-|--------------------------------------------------█-----------------|
-| Channel C | gram 8                | Program 9    █ | Program 10    |
-|--------------------------------------------------█-----------------|
-| Channel D | Program 11             | Program 12  █               | |
-|--------------------------------------------------█-----------------|
-| Channel E | 14 |               | Progr...| Progra█ 16              |
-+++++++++++++++++++++++++++++++++++++++++++++++++++█+++++++++++++++++|
-```
-
-## EPG
-EPG component is the main component of the EPG. It:
-- puts all parts together
-- is responsible for synchronizing time and focus time among all other components
-- is responsible for rendering plugins and calling their interface for events
-- creates and holds all data for all the channels
-- enables/disables mouse navigation arrows if they are rendered
-
-## DataManager[]
-Non-graphical module that holds 1 channel and its data. It is responsible for fetching new data if
-needed after being told to do so (by a Row). Row initiates data fetch after it has been scrolled to
-the given timestamp. However, the fetch might not be finished before the user scrolls the rows.
-
-Therefore data and its fetching must be decoupled from the graphical component so it can finish while
-being a part of a different Row or when not being utilized by any Row at all. The decision whether the
-new data are needed is on DataManager as it receives the timestamp of the EPG from Row and based on
-its data it decides whether more data are indeed needed and if so, it manages their fetch and setting.
-After the fetch completes it calls the `onDataUpdated` callback which notifies its currently assigned
-row (if any) that it should update its cells (and the data that is displayed).
-
-The fetching is also debounced for performance reasons. This debounce reduces render requirements,
-unnecessary background processing and also bandwidth, especially during the fast horizontal scrolling.
-The debounce also affects fast vertical scrolling in a way that it won't start fetching if the user
-is still fast scrolling.
-
-If there are data missing from the fetch (missing data at the start / missing data at the end / holes in the middle)
-the Data Manager generates "No data" program that will fill up these missing time intervals.
-
-## Time
-Non-graphical module that works with time provider on providing current time and time updates through
-the whole EPG. It implements the Events interface and the reference to its instance is passed through
-props to all components that need to subscribe to these events (NowLine, Cell).
-It synchronizes the updates to the whole minute (+/- a couple of milliseconds needed for doing so)
-Events it provides:
-- `onminute` - fired every minute with the current timestamp as a payload
-- `onsecond` - fired every second with the current timestamp as a payload
-
-## NowLine
-Graphical component that renders on top of the rows as a thin vertical line that marks the current time.
-By default, it has no header and updates its position every second based on `onsecond` event.
-It also updates its position after the EPG is scrolled and hides once it gets out of visible range.
-
-## Timeline
-Graphical representation of the header for the rows that displays timeline sections with time marks.
-These move in connection with rows, so it does not need time updates `onminute`. The sections are
-offset with the idea of the exact time corresponding to their mark being in their center.
-This component has basic and animated version to easily handle different visuals when the EPG is scrolled.
-The section component has only 1 version that can be used by both.
-```txt
-              Timeline section
-___________<------------------->_____________
-           |       12:00       |
-           |         |         |
-___________|___________________|_____________
-```
-
-## Day
-Day is a simple component for rendering the day of the EPG in the header section. The default component
-is provided. If the props for DatePicker are present, the Day does not render. It is a one-time render
-component that receives a new timestamp through `updateData` method when the EPG scrolls left/right.
-
-## DatePicker
-DatePicker is an implemented way to quickly pick a specific date in the EPG. It is rendered when the DatePicker
-props are provided. It displays the current day displayed by the EPG and sets it as a value to the Picker.
-
-## RowsManager
-RowsManager has basic and animated versions with the same interfaces but different internal implementations.
-It is responsible for rendering rows, scrolling rows, focusing between them and passing the correct DataManager
-to the correct row. It is responsible for clearing `onDataUpdated` callbacks on DataManagers
-that are removed from a row and not assigned to a new Row.
-
-It is also responsible for rendering Header components and updating them the same way.
-
-## Header
-Header is a simple visual component to display the header of the channel. Default component renders
-channelId. It can be reused for multiple channels (as the rows scroll). Therefore it needs
-to implement `updateData` method. It can also need to be able to hide/show (for additional rows). 
-For this, it needs to implement `show` and `hide` methods.
-
-## Row
-Row is a component that is a bridge between the current row DataManager and CellsManager. It also is
-responsible for telling its current DataManager to fetch additional data when the EPG scrolls left/right.
-This way, only visible rows (channels) fetch new data if they are needed. The Row needs to pass its
-`onDataUpdated` callback to the currently assigned DataManager. This is the way that it knows when
-the new data are ready and instructs its CellsManager to update the cells with the new data.
-
-The Row can be used by multiple channels. It also needs to be able to hide/show (for additional rows).
-Therefore it needs to implement `updateData`, `show` and `hide`.
-
-## CellsManager
-CellsManager is a renderer for Cells. It has a basic and animated version to easily handle different
-visuals when scrolling left/right. It receives a `dataGetter` from the Row that it calls on initial
-render and every time it is instructed to update its data by a Row.
-It renders only that many cells as it needs. There are 2 loading cells (start and end) ready at all
-times. Then it gets visible data (through `dataGetter`) and passes them into data cells. If there are
-no more cells for the data, it dynamically creates new cells. If there are remaining cells after
-assigning all visible data, they are hidden and kept for the future.
-
-## Cell
-Cell is a component that handles the basic behavior of the Program representation. It handles a press,
-mouse/mrcu focus. It can be reused by multiple programs. It needs to implement these functions:
-- `setWidth` - to set the current width of the cell based on the program length
-- `setOffset` - to move the cell from on the row based on the program start time
-- `updateData` - to update data about current program <-- these are just program data, not width and offset
-- `show` - function to display previously hidden cell
-- `hide` - function to hide cell if the cell is not needed currently (it is out of visible range)
-
-## Program
-Program is a visual component for displaying the program. The default provided version renders program
-name. As it is a child of a cell it does not need to handle press or mouse events. Furthermore, it does
-not need to handle show/hide. The only needed function to implement is the `updateData` function that
-is called each render/update with current data.
-
-## MouseNavigation
-This component renders mouse navigation arrows. It has an interface for enabling/disable an arrow
-in the given direction. It receives callbacks for each direction through props and it binds those with
-corresponding arrows.
-
-## Plugins
-Plugins are interfaces meant for further extending the EPG and adding more components. Plugins are
-rendered at the end of the EPG and can be either just static functional components or class components
-that react to certain events:
-- `onItemPress`
-- `onFocusChange`
-- `onScrolledToTimestamp`
-- `onFastScrollingStart`
-- `onFastScrollingEng`
-- `onFastVerticalScrollingStart`
-- `onFastVerticalScrollingEnd`
-- `onFastHorizontalScrollingStart`
-- `onFastHorizontalScrollingEnd`
-
-Plugins also receive a reference to the main EPG component via `epg` prop.
-
-The EPG holds the references to all plugins and when those events happen, it calls the functions of the
-same names as the events on the rendered components. If the function is not implemented it is not called.
-Therefore plugin can implement only the function for the events it needs.
-
-The data passed into these functions are the same as they are passed into the outside callbacks of the
-same name set by props.
-
-There are a couple of already prepared plugins that can be imported and set on the project side.
-
-## ProgramInfo
-Plugin to display extended information about the currently displayed Program. It changes itself with
-the focus. This change is debounced and the debounce time can be set through props (default 700ms).
-
-## DateToast
-Plugin to display a toast with the current date and time during the fast horizontal scrolling.
+---
+id: IMPLEMENTATION
+title: EPG V2 Implementation
+hide_title: true
+sidebar_label: EPG V2 Implementation
+---
+
+# EPG Implementation
+This document describes the implementation details of the EPG component and its parts.
+For a more detailed technical description of all interfaces, head over to the [interface.ts](./interface.ts) file.
+
+**All timestamps are in milliseconds.**
+
+The EPG Component is in ideal case a self contained component that can render the EPG.
+
+The behaviour of the component regarding to the time is that it rounds itself based on the `scrollStepMs`.
+If no `initialTimestamp` is passed the center of the EPG is a current timestamp floored to the nearest
+scrollStepMs value. Similarly every time the displayed time of the EPG changes (after scrolling,
+date picker value selected, or from the outside) it does the same rounding again.
+
+E.g. The current time is 13:55, no `initialTimestamp` is given and no `scrollStepMs` is given.
+In this case the `scrollStepMs` will be default value (30 minutes). So the center of the EPG will be
+time 13:30 and the NowLine (as well as live program highlight) will be moved right of the center to
+the corresponding 13:55 time.
+
+## Structure
+```txt
+EPG - the main EPG component that glues everything together and handles time and "time" position of the focus
+    - `DataManager[]` - handles data fetching and ordering
+    - `Time` - time module that uses timeProvider to handle current time and time updates through EPG
+    - `NowLine` - component that represents the current time in the EPG
+    - `Timeline` - header of the EPG that shows each time segments
+    - `Day` - the current day component
+    - `DatePicker` - component for picking days
+    - `RowsManager` - renderer for the rows, manages scrolling and focusing through rows and its data
+        - `Row[]` - manager for data within the row, manages getting new data on scrolls
+            - `CellsManager` - renderer for the cells, manages scrolling and focusing between cells
+                - `Cell[]` - component that renders 1 program data, handles mouse/mrcu and press action
+                    - `Program` - visual component for 1 cell
+    - `MouseNavigation` - component that renders mouse arrows on certain platforms
+    - `Plugin[]`
+```
+
+## Fast Scrolling
+Fast scrolling is a term that says that the user is moving inside the EPG by holding a button for
+movement. In this fast scrolling state there are these changes:
+- fetching data is debounced until the movements stops and only the needed data for the viewport are
+then fetched.
+- if `DateToast` plugin is enabled then it will be displayed over the epg component
+- in most cases only 1 "loading..." cell will be visible
+
+## Mockup
+```txt
+/**
+ * Current time: 13:55
+ * initialTimestamp: not set (defaults to current time)
+ * scrollStepMs: not set (defaults to 30 minutes)
+ * timelineSectionWidthMs: not set (defaults to 30 minutes)
+ * The initial render of the EPG aims at time:
+ * Math.floor(currentTimestamp / scrollStepMs) * scrollStepMs
+ * which results in 13:30 and it is the center of the EPG viewport
+ */
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+|  Day / DatePicker                                                  |
+|12:00        12:30       13:00       13:30        14:00       14:30 |
+|  |            |           |           |         NOW|           |   |
+|--------------------------------------------------█-----------------|
+| Channel A | Program 1 | Program 2                █ | Pro... | Progr|
+|--------------------------------------------------█-----------------|
+| Channel B | m 5 | Program 6           | Program 7█                 |
+|--------------------------------------------------█-----------------|
+| Channel C | gram 8                | Program 9    █ | Program 10    |
+|--------------------------------------------------█-----------------|
+| Channel D | Program 11             | Program 12  █               | |
+|--------------------------------------------------█-----------------|
+| Channel E | 14 |               | Progr...| Progra█ 16              |
++++++++++++++++++++++++++++++++++++++++++++++++++++█+++++++++++++++++|
+```
+
+## EPG
+EPG component is the main component of the EPG. It:
+- puts all parts together
+- is responsible for synchronizing time and focus time among all other components
+- is responsible for rendering plugins and calling their interface for events
+- creates and holds all data for all the channels
+- enables/disables mouse navigation arrows if they are rendered
+
+## DataManager[]
+Non-graphical module that holds 1 channel and its data. It is responsible for fetching new data if
+needed after being told to do so (by a Row). Row initiates data fetch after it has been scrolled to
+the given timestamp. However, the fetch might not be finished before the user scrolls the rows.
+
+Therefore data and its fetching must be decoupled from the graphical component so it can finish while
+being a part of a different Row or when not being utilized by any Row at all. The decision whether the
+new data are needed is on DataManager as it receives the timestamp of the EPG from Row and based on
+its data it decides whether more data are indeed needed and if so, it manages their fetch and setting.
+After the fetch completes it calls the `onDataUpdated` callback which notifies its currently assigned
+row (if any) that it should update its cells (and the data that is displayed).
+
+The fetching is also debounced for performance reasons. This debounce reduces render requirements,
+unnecessary background processing and also bandwidth, especially during the fast horizontal scrolling.
+The debounce also affects fast vertical scrolling in a way that it won't start fetching if the user
+is still fast scrolling.
+
+If there are data missing from the fetch (missing data at the start / missing data at the end / holes in the middle)
+the Data Manager generates "No data" program that will fill up these missing time intervals.
+
+## Time
+Non-graphical module that works with time provider on providing current time and time updates through
+the whole EPG. It implements the Events interface and the reference to its instance is passed through
+props to all components that need to subscribe to these events (NowLine, Cell).
+It synchronizes the updates to the whole minute (+/- a couple of milliseconds needed for doing so)
+Events it provides:
+- `onminute` - fired every minute with the current timestamp as a payload
+- `onsecond` - fired every second with the current timestamp as a payload
+
+## NowLine
+Graphical component that renders on top of the rows as a thin vertical line that marks the current time.
+By default, it has no header and updates its position every second based on `onsecond` event.
+It also updates its position after the EPG is scrolled and hides once it gets out of visible range.
+
+## Timeline
+Graphical representation of the header for the rows that displays timeline sections with time marks.
+These move in connection with rows, so it does not need time updates `onminute`. The sections are
+offset with the idea of the exact time corresponding to their mark being in their center.
+This component has basic and animated version to easily handle different visuals when the EPG is scrolled.
+The section component has only 1 version that can be used by both.
+```txt
+              Timeline section
+___________<------------------->_____________
+           |       12:00       |
+           |         |         |
+___________|___________________|_____________
+```
+
+## Day
+Day is a simple component for rendering the day of the EPG in the header section. The default component
+is provided. If the props for DatePicker are present, the Day does not render. It is a one-time render
+component that receives a new timestamp through `updateData` method when the EPG scrolls left/right.
+
+## DatePicker
+DatePicker is an implemented way to quickly pick a specific date in the EPG. It is rendered when the DatePicker
+props are provided. It displays the current day displayed by the EPG and sets it as a value to the Picker.
+
+## RowsManager
+RowsManager has basic and animated versions with the same interfaces but different internal implementations.
+It is responsible for rendering rows, scrolling rows, focusing between them and passing the correct DataManager
+to the correct row. It is responsible for clearing `onDataUpdated` callbacks on DataManagers
+that are removed from a row and not assigned to a new Row.
+
+It is also responsible for rendering Header components and updating them the same way.
+
+## Header
+Header is a simple visual component to display the header of the channel. Default component renders
+channelId. It can be reused for multiple channels (as the rows scroll). Therefore it needs
+to implement `updateData` method. It can also need to be able to hide/show (for additional rows). 
+For this, it needs to implement `show` and `hide` methods.
+
+## Row
+Row is a component that is a bridge between the current row DataManager and CellsManager. It also is
+responsible for telling its current DataManager to fetch additional data when the EPG scrolls left/right.
+This way, only visible rows (channels) fetch new data if they are needed. The Row needs to pass its
+`onDataUpdated` callback to the currently assigned DataManager. This is the way that it knows when
+the new data are ready and instructs its CellsManager to update the cells with the new data.
+
+The Row can be used by multiple channels. It also needs to be able to hide/show (for additional rows).
+Therefore it needs to implement `updateData`, `show` and `hide`.
+
+## CellsManager
+CellsManager is a renderer for Cells. It has a basic and animated version to easily handle different
+visuals when scrolling left/right. It receives a `dataGetter` from the Row that it calls on initial
+render and every time it is instructed to update its data by a Row.
+It renders only that many cells as it needs. There are 2 loading cells (start and end) ready at all
+times. Then it gets visible data (through `dataGetter`) and passes them into data cells. If there are
+no more cells for the data, it dynamically creates new cells. If there are remaining cells after
+assigning all visible data, they are hidden and kept for the future.
+
+## Cell
+Cell is a component that handles the basic behavior of the Program representation. It handles a press,
+mouse/mrcu focus. It can be reused by multiple programs. It needs to implement these functions:
+- `setWidth` - to set the current width of the cell based on the program length
+- `setOffset` - to move the cell from on the row based on the program start time
+- `updateData` - to update data about current program <-- these are just program data, not width and offset
+- `show` - function to display previously hidden cell
+- `hide` - function to hide cell if the cell is not needed currently (it is out of visible range)
+
+## Program
+Program is a visual component for displaying the program. The default provided version renders program
+name. As it is a child of a cell it does not need to handle press or mouse events. Furthermore, it does
+not need to handle show/hide. The only needed function to implement is the `updateData` function that
+is called each render/update with current data.
+
+## MouseNavigation
+This component renders mouse navigation arrows. It has an interface for enabling/disable an arrow
+in the given direction. It receives callbacks for each direction through props and it binds those with
+corresponding arrows.
+
+## Plugins
+Plugins are interfaces meant for further extending the EPG and adding more components. Plugins are
+rendered at the end of the EPG and can be either just static functional components or class components
+that react to certain events:
+- `onItemPress`
+- `onFocusChange`
+- `onScrolledToTimestamp`
+- `onFastScrollingStart`
+- `onFastScrollingEng`
+- `onFastVerticalScrollingStart`
+- `onFastVerticalScrollingEnd`
+- `onFastHorizontalScrollingStart`
+- `onFastHorizontalScrollingEnd`
+
+Plugins also receive a reference to the main EPG component via `epg` prop.
+
+The EPG holds the references to all plugins and when those events happen, it calls the functions of the
+same names as the events on the rendered components. If the function is not implemented it is not called.
+Therefore plugin can implement only the function for the events it needs.
+
+The data passed into these functions are the same as they are passed into the outside callbacks of the
+same name set by props.
+
+There are a couple of already prepared plugins that can be imported and set on the project side.
+
+## ProgramInfo
+Plugin to display extended information about the currently displayed Program. It changes itself with
+the focus. This change is debounced and the debounce time can be set through props (default 700ms).
+
+## DateToast
+Plugin to display a toast with the current date and time during the fast horizontal scrolling.