@24i/bigscreen-sdk 1.0.34 → 1.0.35-alpha.2578

package/packages/grid/README.md

@@ -1,169 +1,169 @@
----
-id: README
-title: Grid
-hide_title: true
-sidebar_label: Grid
----
-
-# Grid
-This package contains a variety of prepared grids with different focus/scroll behaviours and configuration.
-If you cannot find the grid with your desired behaviour, feel free to add it. The interface for adding new behaviours is rather simple.
-Check one of the existing implementations for inspiration on how to do it.
-
-Grids also support updating data with these two methods:
-- `appendData` - inserts new data at the end
-- `prependData` - inserts new data at the beginning
-
-## Importing Grid
-Grid package does not allow to import just the index file. Instead, please use the path import of the
-implementation that you require or the interface.
-```ts
-import { BasicGrid } from '@24i/bigscreen-sdk/grid/Basic';
-import { FixedToEndGrid } from '@24i/bigscreen-sdk/grid/FixedToEnd';
-import { FirstOnlyGrid } from '@24i/bigscreen-sdk/grid/FirstOnly';
-import { Props, Grid, GridComponent, Item, ItemComponent } from '@24i/bigscreen-sdk/grid/interface';
-```
-
-## Mouse support (MRCU)
-This component takes advantage of a MouseNavigation component and is automatically taking care of Mouse Support. This is enabled for `web, tizen, and webOS`. For other platform it is disabled.
-
-## GridBase
-This is an underlying component used by all grids. It is also exported so you could use it in your project as well.
-
-**Props**
-- `data` - array of data to pass into items during render
-- `renderItem` - function that will render one item - (item, index, ref) - ref must be passed onto item
-- `rows` / `columns` - number of rows / columns for horizontal / vertical grid
-- `visibleRows` / `visibleColumns` - number of maximal visible columns / rows for horizontal / vertical grid (including partially)
-- `horizontal` - sets grid to horizontal mode (default is vertical)
-- `continuousFocus` - whether to jump to next index item at the end of row / column (vertical / horizontal)
-- `onFocusChanged` - optional callback that receives focused item and its index
-- `onScrollChanged` - optional callback that receives item and index of current scroll performed every time grid is scrolled.
-- `className` - optional, class name for wrap element
-- `fastScrolling` - optional, enables fast scrolling on grid
-- `fastFocusingOptimization` - optional, enables fast focusing optimization
-
-**Props provided by behaviour controlling component (actual grid implementations)**
-- `forward` - function that is called when grid should move in forward direction by 1. Returns boolean whether it processed the move.
-- `backward` - function that is called when grid should move in backward direction by 1. Returns boolean whether it processed the move.
-- `forwardGroup` - function that is called when grid should move whole row / column (vertical / horizontal) in forward direction. Returns boolean whether it processed the move.
-- `backwardGroup` - function that is called when grid should move whole row / column (vertical / horizontal) in backward direction. Returns boolean whether it processed the move.
-
-The result in renderItem needs to implement one of these interfaces depending on your grid type:
-
-## Item<Model> interface
-```ts
-focus: (options?: FocusOptions) => void,
-show: () => void,
-hide: () => void, // expects the item to still occupy layout, just not be visible (do not use `display: none`)
-updateData: (item: Model, index: number) => void,
-hasDom?: (target: HTMLElement) => boolean, // returns whether passed target is the dom representation of the item
-onFastScrolling?: (isFastScrolling: boolean) => void,
-```
-
-## Grid fast scrolling
-Grid scrolling could be also optimized by reducing elements on items during
-scrolling. For this, fast scrolling could be enabled and grid will call
-`onFastScrolling(true)` on each item when started and `onFastScrolling(false)`
-when finished. When enabled, fast scrolling on the animated grid is turned on
-until the animation is finished. Fast scrolling is working only with forward and
-backward group, not with regular forward/backward.
-
-## Grid fast focusing
-Grid scrolling could be also optimized by preventing focusing items during
-scrolling. For this, fast focusing optimization could be enabled by setting
-`fastFocusingOptimization: true` in props. When enabled, it will not focus items
-during scrolling until the animation is finished or key up is emitted. Fast focusing
-is working only with forward and backward group, not with regular forward/backward.
-
-## onFocusChanged and onScrollChanged
-`onFocusChanged` is called every time next item in grid is focused, but after
-various optimization improvements, items are not focused step by step during scrolling.
-Because of this behavior, actions frequently used in onFocusChanged representing
-scroll change can't be used. For this purpose there is `onScrollChanged` callback,
-which is called every time grid is performing scroll operation.
-
-## Prevent blur on long press
-When the user holds a navigation key, he usually scrolls to the end (or start) of the grid,
-and then releases the key. This operation is very quick and most of the time he releases
-the key too late, so the keydown event from the grid will propagate to another component
-in the layout. This causes for example opening of the menu even though the user is still holding
-the key and scrolling the grid. For those situations and to have better control above the layout
-navigation, there is a prop `preventBlurOnLongPress`. When the user scrolls to the end (or start)
-of the grid, he needs to release the key and press it again to propagate the event higher
-and focus another component.
-
-```ts
-preventBlurOnLongPress: {
-    forward?: boolean, // apply when user scroll forward in the current grid group
-    backward?: boolean, // apply when user scroll backward in the current grid group
-    forwardGroup?: boolean, // apply when user scroll forward the whole grid group
-    backwardGroup?: boolean, // apply when user scroll backward the whole grid group
-}
-```
-
-## Prepared grids
-- [BasicGrid - (slow/animated)](./BasicGrid/README.md)
-- [FixedToEndGrid - (slow/animated)](./FixedToEndGrid/README.md)
-- [FirstOnlyGrid - (slow/animated)](./FirstOnlyGrid/README.md)
-
-## Usage (with AnimatedBasicGrid example)
-```jsx
-<AnimatedBasicGrid<Packshot, Movie>
-    ref={this.grid}
-    rtl
-    continuousFocus
-    columns={4}
-    visibleRows={3}
-    scrollStep={240}
-    firstScrollStep={240}
-    data={this.movies}
-    renderItem={(movie, index, ref) => (
-        <Packshot
-            movie={movie}
-            ref={ref}
-            onFocus={() => { console.log(`focused index ${index}`); }}
-        />
-    )}
-/>
-```
-
-## AnimationConfiguration
-```ts
-type AnimationConfiguration = {
-    normal: {
-        time: number,
-        easing: EasingType,
-    },
-    fastLinear?: {
-        time: number,
-        startRatio: number,
-        endRatio?: number,
-    }
-    slowdownRatio?: number
-}
-```
-
-### Properties
-- normal - main animation type used for scrolling
-- fastLinear - optional - linear animation type used during fast scrolling (when user holds a key
-and scroll with the grid for longer period)
-- slowdownRatio - optional - number between 0 > and <= 1, determines how much scroll would be slowed down.
-Less the number, slower the scrolling. Undefined or 0 is unlimited scroll speed. Slowing down the scroll
-speed could improve overall animation performance in some cases.
-
-### fastLinear property
-Grid animation provides possibility of optimizing the animation during slow speeds and smoothing
-the scrolling effect without easing in `normal` property interfering the movement.
-This is achieved by changing the ease of the animation to linear when the scroll is longer
-and user is moving the grid further.
-`fastLinear` property have these settings:
-- time - duration of the animation, same as in `normal` property
-- startRatio - this number represents the threshold, when should linear animation start.
-Under the hood, threshold is one `scrollStep`. This number is basically multiplied by scrollStep number,
-so the linear animation will start, when the current scroll size is larger than `threshold * startRatio`.
-When the number is 1, threshold is exactly one scrollStep.
-- endRatio - optional - this number represents when the scroll animation should switch from fast linear back
-to normal. Threshold is the same as in `startRatio`, but animation will switch when scroll length is less
-than `threshold * startRatio`. Parameter is optional, so if it is not set, animation will finish in fast linear
-mode.
+---
+id: README
+title: Grid
+hide_title: true
+sidebar_label: Grid
+---
+
+# Grid
+This package contains a variety of prepared grids with different focus/scroll behaviours and configuration.
+If you cannot find the grid with your desired behaviour, feel free to add it. The interface for adding new behaviours is rather simple.
+Check one of the existing implementations for inspiration on how to do it.
+
+Grids also support updating data with these two methods:
+- `appendData` - inserts new data at the end
+- `prependData` - inserts new data at the beginning
+
+## Importing Grid
+Grid package does not allow to import just the index file. Instead, please use the path import of the
+implementation that you require or the interface.
+```ts
+import { BasicGrid } from '@24i/bigscreen-sdk/grid/Basic';
+import { FixedToEndGrid } from '@24i/bigscreen-sdk/grid/FixedToEnd';
+import { FirstOnlyGrid } from '@24i/bigscreen-sdk/grid/FirstOnly';
+import { Props, Grid, GridComponent, Item, ItemComponent } from '@24i/bigscreen-sdk/grid/interface';
+```
+
+## Mouse support (MRCU)
+This component takes advantage of a MouseNavigation component and is automatically taking care of Mouse Support. This is enabled for `web, tizen, and webOS`. For other platform it is disabled.
+
+## GridBase
+This is an underlying component used by all grids. It is also exported so you could use it in your project as well.
+
+**Props**
+- `data` - array of data to pass into items during render
+- `renderItem` - function that will render one item - (item, index, ref) - ref must be passed onto item
+- `rows` / `columns` - number of rows / columns for horizontal / vertical grid
+- `visibleRows` / `visibleColumns` - number of maximal visible columns / rows for horizontal / vertical grid (including partially)
+- `horizontal` - sets grid to horizontal mode (default is vertical)
+- `continuousFocus` - whether to jump to next index item at the end of row / column (vertical / horizontal)
+- `onFocusChanged` - optional callback that receives focused item and its index
+- `onScrollChanged` - optional callback that receives item and index of current scroll performed every time grid is scrolled.
+- `className` - optional, class name for wrap element
+- `fastScrolling` - optional, enables fast scrolling on grid
+- `fastFocusingOptimization` - optional, enables fast focusing optimization
+
+**Props provided by behaviour controlling component (actual grid implementations)**
+- `forward` - function that is called when grid should move in forward direction by 1. Returns boolean whether it processed the move.
+- `backward` - function that is called when grid should move in backward direction by 1. Returns boolean whether it processed the move.
+- `forwardGroup` - function that is called when grid should move whole row / column (vertical / horizontal) in forward direction. Returns boolean whether it processed the move.
+- `backwardGroup` - function that is called when grid should move whole row / column (vertical / horizontal) in backward direction. Returns boolean whether it processed the move.
+
+The result in renderItem needs to implement one of these interfaces depending on your grid type:
+
+## Item<Model> interface
+```ts
+focus: (options?: FocusOptions) => void,
+show: () => void,
+hide: () => void, // expects the item to still occupy layout, just not be visible (do not use `display: none`)
+updateData: (item: Model, index: number) => void,
+hasDom?: (target: HTMLElement) => boolean, // returns whether passed target is the dom representation of the item
+onFastScrolling?: (isFastScrolling: boolean) => void,
+```
+
+## Grid fast scrolling
+Grid scrolling could be also optimized by reducing elements on items during
+scrolling. For this, fast scrolling could be enabled and grid will call
+`onFastScrolling(true)` on each item when started and `onFastScrolling(false)`
+when finished. When enabled, fast scrolling on the animated grid is turned on
+until the animation is finished. Fast scrolling is working only with forward and
+backward group, not with regular forward/backward.
+
+## Grid fast focusing
+Grid scrolling could be also optimized by preventing focusing items during
+scrolling. For this, fast focusing optimization could be enabled by setting
+`fastFocusingOptimization: true` in props. When enabled, it will not focus items
+during scrolling until the animation is finished or key up is emitted. Fast focusing
+is working only with forward and backward group, not with regular forward/backward.
+
+## onFocusChanged and onScrollChanged
+`onFocusChanged` is called every time next item in grid is focused, but after
+various optimization improvements, items are not focused step by step during scrolling.
+Because of this behavior, actions frequently used in onFocusChanged representing
+scroll change can't be used. For this purpose there is `onScrollChanged` callback,
+which is called every time grid is performing scroll operation.
+
+## Prevent blur on long press
+When the user holds a navigation key, he usually scrolls to the end (or start) of the grid,
+and then releases the key. This operation is very quick and most of the time he releases
+the key too late, so the keydown event from the grid will propagate to another component
+in the layout. This causes for example opening of the menu even though the user is still holding
+the key and scrolling the grid. For those situations and to have better control above the layout
+navigation, there is a prop `preventBlurOnLongPress`. When the user scrolls to the end (or start)
+of the grid, he needs to release the key and press it again to propagate the event higher
+and focus another component.
+
+```ts
+preventBlurOnLongPress: {
+    forward?: boolean, // apply when user scroll forward in the current grid group
+    backward?: boolean, // apply when user scroll backward in the current grid group
+    forwardGroup?: boolean, // apply when user scroll forward the whole grid group
+    backwardGroup?: boolean, // apply when user scroll backward the whole grid group
+}
+```
+
+## Prepared grids
+- [BasicGrid - (slow/animated)](./BasicGrid/README.md)
+- [FixedToEndGrid - (slow/animated)](./FixedToEndGrid/README.md)
+- [FirstOnlyGrid - (slow/animated)](./FirstOnlyGrid/README.md)
+
+## Usage (with AnimatedBasicGrid example)
+```jsx
+<AnimatedBasicGrid<Packshot, Movie>
+    ref={this.grid}
+    rtl
+    continuousFocus
+    columns={4}
+    visibleRows={3}
+    scrollStep={240}
+    firstScrollStep={240}
+    data={this.movies}
+    renderItem={(movie, index, ref) => (
+        <Packshot
+            movie={movie}
+            ref={ref}
+            onFocus={() => { console.log(`focused index ${index}`); }}
+        />
+    )}
+/>
+```
+
+## AnimationConfiguration
+```ts
+type AnimationConfiguration = {
+    normal: {
+        time: number,
+        easing: EasingType,
+    },
+    fastLinear?: {
+        time: number,
+        startRatio: number,
+        endRatio?: number,
+    }
+    slowdownRatio?: number
+}
+```
+
+### Properties
+- normal - main animation type used for scrolling
+- fastLinear - optional - linear animation type used during fast scrolling (when user holds a key
+and scroll with the grid for longer period)
+- slowdownRatio - optional - number between 0 > and <= 1, determines how much scroll would be slowed down.
+Less the number, slower the scrolling. Undefined or 0 is unlimited scroll speed. Slowing down the scroll
+speed could improve overall animation performance in some cases.
+
+### fastLinear property
+Grid animation provides possibility of optimizing the animation during slow speeds and smoothing
+the scrolling effect without easing in `normal` property interfering the movement.
+This is achieved by changing the ease of the animation to linear when the scroll is longer
+and user is moving the grid further.
+`fastLinear` property have these settings:
+- time - duration of the animation, same as in `normal` property
+- startRatio - this number represents the threshold, when should linear animation start.
+Under the hood, threshold is one `scrollStep`. This number is basically multiplied by scrollStep number,
+so the linear animation will start, when the current scroll size is larger than `threshold * startRatio`.
+When the number is 1, threshold is exactly one scrollStep.
+- endRatio - optional - this number represents when the scroll animation should switch from fast linear back
+to normal. Threshold is the same as in `startRatio`, but animation will switch when scroll length is less
+than `threshold * startRatio`. Parameter is optional, so if it is not set, animation will finish in fast linear
+mode.