@24i/bigscreen-sdk 1.0.33 → 1.0.34-alpha.2562

package/packages/list/FixedToEndList/README.md

@@ -1,42 +1,42 @@
----
-id: README
-title: FixedToEndList
-hide_title: true
-sidebar_label: FixedToEndList
----
-
-# FixedToEndList
-Fixed To End List is a type of list that prefers scrolling before moving the focus.
-First the focus remains at the same position. Only after the last item is fully visible it starts moving the focus to the end of the list.
-Going back it first moves the focus to the first position and then scrolls to the start.
-
-## List Specific Props
-- `scrollStep` - value to move on scroll
-
-## Default Animation Configuration
-- normal: 700ms with easeOutQuart
-
-## Usage
-FixedToEnd list is most often used for portrait Packshots in apps that want to have similar behaviour as Netflix.
-
-Unlike Netflix's list, it does not scroll until the last item. Rather it starts moving the focus once it reaches the last item.
-
-## Examples
-
-### Example 1
-Probably the most common usage of the FixedToEndList.
-Similar to BasicList it also counts with two partially visible items on each end.
-Therefore `visibleItems` is equal to fully visible/navigatable items + 2.
-`scrollStep` is equal to item width + the space between two items
-```tsx
-<FixedToEndList
-    data={[1, 2, 3, 4, 5, 6, 7]}
-    renderItem={(item: number, index, ref) => (
-        <Item title={item} ref={ref} />
-    )}
-    visibleItems={6}
-    scrollStep={139}
-    horizontal
-/>
-```
-![Example 1](./examples/example1.gif)
+---
+id: README
+title: FixedToEndList
+hide_title: true
+sidebar_label: FixedToEndList
+---
+
+# FixedToEndList
+Fixed To End List is a type of list that prefers scrolling before moving the focus.
+First the focus remains at the same position. Only after the last item is fully visible it starts moving the focus to the end of the list.
+Going back it first moves the focus to the first position and then scrolls to the start.
+
+## List Specific Props
+- `scrollStep` - value to move on scroll
+
+## Default Animation Configuration
+- normal: 700ms with easeOutQuart
+
+## Usage
+FixedToEnd list is most often used for portrait Packshots in apps that want to have similar behaviour as Netflix.
+
+Unlike Netflix's list, it does not scroll until the last item. Rather it starts moving the focus once it reaches the last item.
+
+## Examples
+
+### Example 1
+Probably the most common usage of the FixedToEndList.
+Similar to BasicList it also counts with two partially visible items on each end.
+Therefore `visibleItems` is equal to fully visible/navigatable items + 2.
+`scrollStep` is equal to item width + the space between two items
+```tsx
+<FixedToEndList
+    data={[1, 2, 3, 4, 5, 6, 7]}
+    renderItem={(item: number, index, ref) => (
+        <Item title={item} ref={ref} />
+    )}
+    visibleItems={6}
+    scrollStep={139}
+    horizontal
+/>
+```
+![Example 1](./examples/example1.gif)

package/packages/list/FixedToEndList/index.ts

@@ -1 +1 @@
-export { FixedToEndList } from '../src/FixedToEndList/FixedToEndList';
+export { FixedToEndList } from '../src/FixedToEndList/FixedToEndList';

package/packages/list/Item/index.ts

@@ -1 +1 @@
-export { Item } from '../src/types';
+export { Item } from '../src/types';

package/packages/list/README.md

@@ -1,193 +1,193 @@
----
-id: README
-title: List
-hide_title: true
-sidebar_label: List
----
-
-# List
-This package contains a variety of prepared lists with different focus/scroll
-behaviours and configuration. If you cannot find the list 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.
-
-To programatically scroll to certain index, use:
-- `scrollTo(index)` - This method scrolls the list to given index as if the user moved there manually.
-So e.g. BasicList if you scroll to index 7 from index 0, it will be at the bottom. If you scroll to
-index 7 from index 20, it will be at the top. IMPORTANT: This function does not focus.
-
-Lists also support updating data with these two methods:
-- `appendData` - inserts new data at the end
-- `prependData` - inserts new data at the beginning
-
-## Importing List
-List 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 { BasicList } from '@24i/bigscreen-sdk/list/Basic';
-import { FixedToEndList } from '@24i/bigscreen-sdk/list/FixedToEnd';
-import { CenteredList } from '@24i/bigscreen-sdk/list/Centered';
-import { FirstOnlyList } from '@24i/bigscreen-sdk/list/FirstOnly';
-import { FirstOnlyVariedList } from '@24i/bigscreen-sdk/list/FirstOnlyVaried';
-import { EdgeOffsetList } from '@24i/bigscreen-sdk/list/EdgeOffset';
-import { Props, List, ListComponent, Item, ItemComponent } from '@24i/bigscreen-sdk/list/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.
-
-## ListBase
-This is an underlying component used by all lists. 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
-- `visibleItems` - number of maximal visible items (including partially)
-- `horizontal` - sets List to horizontal mode (default is vertical)
-- `onFocusChanged` - optional callback that receives focused item and its index
-- `onScrollChanged` - optional callback that receives item and index of current scroll performed every time list is scrolled.
-- `animation` - optional AnimationConfiguration that is deep merged with default configuration of the list
-- `className` - optional, class name for wrap element
-- `animate` - optional, enables scrolling animation
-- `fastScrolling` - optional, enables fast scrolling on list
-- `fastFocusingOptimization` - optional, enables fast focusing optimization
-
-**Props provided by behaviour controlling component (actual list implementations)**
-- `limit` - optional limit to the number of rendered items
-- `forward` - function that is called when list should move in forward direction. Returns boolean whether it processed the move.
-- `backward` - function that is called when list should move in backward direction. Returns boolean whether it processed the move.
-
-The result in renderItem needs to implement one of these interfaces depending
-on your list 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, // change item content according to new model
-hasDom?: (target: HTMLElement) => boolean, // returns whether passed target is the dom representation of the item
-onFastScrolling?: (isFastScrolling: boolean) => void,
-```
-
-## List scrolling
-All lists consist of a finite number of item elements. In the basic and animated
-variant, those elements are moved from the left side of the list to the right
-side and vice versa. This creates a scrolling effect. There is an `updateData`
-method called on the items, so the content is properly changed during scrolling.
-There are situations, however, in which you can't use `updateData` method on the item,
-because the content is too complex for being updated, or it is not possible
-(for example the item is whole another List component). For these situations,
-there is a special wrapper item called `AttachDetachItem`. The item inside is not updated,
-but instead, it is rendered only once inside the wrapper item during scrolling.
-For more information check [AttachDetachItem](./AttachDetachItem/README.md) docs.
-
-## List fast scrolling
-List scrolling could be also optimized by reducing elements on items during
-scrolling. For this, fast scrolling could be enabled and list will call
-`onFastScrolling(true)` on each item when started and `onFastScrolling(false)`
-when finished. When enabled, fast scrolling on the animated list is turned on
-until the animation is finished.
-
-## List fast focusing
-List 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.
-
-## onFocusChanged and onScrollChanged
-`onFocusChanged` is called every time next item in list 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 list 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 list
-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 list 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 list. 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 list, 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
-    backward?: boolean, // apply when user scroll backward
-}
-```
-
-## Prepared lists
-- Fixed item size lists
-    - [BasicList - (slow/animated)](./BasicList/README.md)
-    - [CenteredList - (slow/animated)](./CenteredList/README.md)
-    - [EdgeOffsetList - (slow/animated)](./EdgeOffsetList/README.md)
-    - [FirstOnlyList - (slow/animated)](./FirstOnlyList/README.md)
-    - [FixedToEndList - (slow/animated)](./FixedToEndList/README.md)
-- Variable item size lists
-    - [FirstOnlyVariedList - (slow/animated)](./FirstOnlyVariedList/README.md)
-
-## Usage (with BasicList example)
-```jsx
-<BasicList<Packshot, MovieModel>
-    ref={this.lists[categoryIndex]}
-    data={movies}
-    renderItem={(movie, index, ref) => (
-        <Packshot
-            ref={ref}
-            movie={movie}
-        />
-    )}
-    visibleItems={6}
-    firstScrollStep={150}
-    scrollStep={240}
-    horizontal
-/>
-```
-
-## 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 list 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
-List animation provides possibility of optimizing the animation during slow speeds and smoother
-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 list 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` (or an average item size in case of varied list variant).
-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: List
+hide_title: true
+sidebar_label: List
+---
+
+# List
+This package contains a variety of prepared lists with different focus/scroll
+behaviours and configuration. If you cannot find the list 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.
+
+To programatically scroll to certain index, use:
+- `scrollTo(index)` - This method scrolls the list to given index as if the user moved there manually.
+So e.g. BasicList if you scroll to index 7 from index 0, it will be at the bottom. If you scroll to
+index 7 from index 20, it will be at the top. IMPORTANT: This function does not focus.
+
+Lists also support updating data with these two methods:
+- `appendData` - inserts new data at the end
+- `prependData` - inserts new data at the beginning
+
+## Importing List
+List 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 { BasicList } from '@24i/bigscreen-sdk/list/Basic';
+import { FixedToEndList } from '@24i/bigscreen-sdk/list/FixedToEnd';
+import { CenteredList } from '@24i/bigscreen-sdk/list/Centered';
+import { FirstOnlyList } from '@24i/bigscreen-sdk/list/FirstOnly';
+import { FirstOnlyVariedList } from '@24i/bigscreen-sdk/list/FirstOnlyVaried';
+import { EdgeOffsetList } from '@24i/bigscreen-sdk/list/EdgeOffset';
+import { Props, List, ListComponent, Item, ItemComponent } from '@24i/bigscreen-sdk/list/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.
+
+## ListBase
+This is an underlying component used by all lists. 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
+- `visibleItems` - number of maximal visible items (including partially)
+- `horizontal` - sets List to horizontal mode (default is vertical)
+- `onFocusChanged` - optional callback that receives focused item and its index
+- `onScrollChanged` - optional callback that receives item and index of current scroll performed every time list is scrolled.
+- `animation` - optional AnimationConfiguration that is deep merged with default configuration of the list
+- `className` - optional, class name for wrap element
+- `animate` - optional, enables scrolling animation
+- `fastScrolling` - optional, enables fast scrolling on list
+- `fastFocusingOptimization` - optional, enables fast focusing optimization
+
+**Props provided by behaviour controlling component (actual list implementations)**
+- `limit` - optional limit to the number of rendered items
+- `forward` - function that is called when list should move in forward direction. Returns boolean whether it processed the move.
+- `backward` - function that is called when list should move in backward direction. Returns boolean whether it processed the move.
+
+The result in renderItem needs to implement one of these interfaces depending
+on your list 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, // change item content according to new model
+hasDom?: (target: HTMLElement) => boolean, // returns whether passed target is the dom representation of the item
+onFastScrolling?: (isFastScrolling: boolean) => void,
+```
+
+## List scrolling
+All lists consist of a finite number of item elements. In the basic and animated
+variant, those elements are moved from the left side of the list to the right
+side and vice versa. This creates a scrolling effect. There is an `updateData`
+method called on the items, so the content is properly changed during scrolling.
+There are situations, however, in which you can't use `updateData` method on the item,
+because the content is too complex for being updated, or it is not possible
+(for example the item is whole another List component). For these situations,
+there is a special wrapper item called `AttachDetachItem`. The item inside is not updated,
+but instead, it is rendered only once inside the wrapper item during scrolling.
+For more information check [AttachDetachItem](./AttachDetachItem/README.md) docs.
+
+## List fast scrolling
+List scrolling could be also optimized by reducing elements on items during
+scrolling. For this, fast scrolling could be enabled and list will call
+`onFastScrolling(true)` on each item when started and `onFastScrolling(false)`
+when finished. When enabled, fast scrolling on the animated list is turned on
+until the animation is finished.
+
+## List fast focusing
+List 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.
+
+## onFocusChanged and onScrollChanged
+`onFocusChanged` is called every time next item in list 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 list 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 list
+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 list 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 list. 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 list, 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
+    backward?: boolean, // apply when user scroll backward
+}
+```
+
+## Prepared lists
+- Fixed item size lists
+    - [BasicList - (slow/animated)](./BasicList/README.md)
+    - [CenteredList - (slow/animated)](./CenteredList/README.md)
+    - [EdgeOffsetList - (slow/animated)](./EdgeOffsetList/README.md)
+    - [FirstOnlyList - (slow/animated)](./FirstOnlyList/README.md)
+    - [FixedToEndList - (slow/animated)](./FixedToEndList/README.md)
+- Variable item size lists
+    - [FirstOnlyVariedList - (slow/animated)](./FirstOnlyVariedList/README.md)
+
+## Usage (with BasicList example)
+```jsx
+<BasicList<Packshot, MovieModel>
+    ref={this.lists[categoryIndex]}
+    data={movies}
+    renderItem={(movie, index, ref) => (
+        <Packshot
+            ref={ref}
+            movie={movie}
+        />
+    )}
+    visibleItems={6}
+    firstScrollStep={150}
+    scrollStep={240}
+    horizontal
+/>
+```
+
+## 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 list 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
+List animation provides possibility of optimizing the animation during slow speeds and smoother
+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 list 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` (or an average item size in case of varied list variant).
+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.