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

package/packages/list/AttachDetachItem/README.md

@@ -0,0 +1,128 @@
+---
+id: README
+title: AttachDetachItem
+hide_title: true
+sidebar_label: AttachDetachItem
+---
+
+# AttachDetachItem
+This is a wrapper item that is used when you don't want to use `updateData` method on items, but instead,
+you want to render the item only once during the list's lifetime. The most common use case is when you
+need to have more complex items in the list such as other List components (e.g. Home scene).
+Rendered item is then attached or detached by the list during scrolling when it's needed.
+
+## Item Specific Props
+
+```ts
+type Props<T extends AttachDetachItemData<any, any>> = {
+    data: T,
+    index: number,
+    children: (data: T['data'], index: number, ref: T['ref']) => JSX.Element,
+    className?: string,
+};
+```
+
+## Interfaces
+
+```ts
+type AttachDetachItemData<T, U> = {
+    data: U,
+    ref: Reference<T>,
+    isFastScrolling: boolean,
+    node?: HTMLElement,
+};
+```
+
+## Usage
+First you need to wrap your original list types with `AttachDetachItemData` type. It is because you need to provide
+to your list another layer of additional information, where the references and rendered items are stored.
+
+### Defining data types
+Lets assume that this is our original list, where `Teaser` is an item and `Asset` is the type of your data inserted into the list:
+
+```ts
+type MyCustomList = BasicList<Teaser, Asset>
+```
+
+Now, the `Teaser` and `Asset` are the T and U types of the `AttachDetachItemData` type. This represents our wrapped list data.
+We also need to define, what type would be the actual item. For simplifying we will use two types `ListData` and `ListItem`.
+
+```ts
+type ListData = AttachDetachItemData<Teaser, Asset>;
+type ListItem = AttachDetachItem<ListData>;
+```
+
+Now we can define our new list type, which uses `AttachDetachItem`:
+
+```ts
+type MyCustomList = BasicList<ListItem, ListData>
+```
+
+or without support types like this:
+
+```ts
+type MyCustomList = BasicList<AttachDetachItem<AttachDetachItemData<Teaser, Asset>>, AttachDetachItemData<Teaser, Asset>>
+```
+
+### Preparing data
+Next we need to prepare our data. It basically means that we will create a list of `ListData` type, where would be our references and
+rendered items stored. For this procedure, there is a function `prepareAttachDetachItemData` from the AttachDetachItem item package.
+
+```ts
+function prepareAttachDetachItemData<T, U>(data: U[]): AttachDetachItemData<T, U>[]
+```
+
+```ts
+const preparedData = prepareAttachDetachItemData<Teaser, Asset>(models) as ListData[];
+```
+
+this step will wrap our original data like this:
+
+```
+[
+    {
+        data: <original data on index 0>,
+        ref: { current: null },
+        isFastScrolling: false,
+    },
+    {
+        data: <original data on index 1>,
+        ref: { current: null },
+        isFastScrolling: false,
+    },
+    {
+        data: <original data on index 2>,
+        ref: { current: null },
+        isFastScrolling: false,
+    },
+    {
+        data: <original data on index 3>,
+        ref: { current: null },
+        isFastScrolling: false,
+    }
+]
+```
+
+This structure is ready to be used instead of the original data in the list.
+
+### Wrapping the original item
+Final step is to wrap our original list item with `AttachDetachItem` in the `renderItem` method of the list.
+AttachDetachItem as its children prop takes function for rendering the actual original item.
+
+```tsx
+renderItem: (data: ListData, index: number, ref: Reference<ListItem>) => (
+    <AttachDetachItem 
+        data={data}
+        index={index}
+        ref={ref}
+        className="stack-panel-item"
+    >
+        {(asset: Asset, index: number, itemRef: Reference<Teaser>) => (
+            <Teaser
+                model={asset}
+                ref={itemRef}
+            />
+        )}
+    </AttachDetachItem>
+)
+```

package/packages/list/AttachDetachItem/index.ts

@@ -0,0 +1,3 @@
+export { AttachDetachItem } from '../src/AttachDetachItem/AttachDetachItem';
+export { AttachDetachItemData } from '../src/interface';
+export { prepareAttachDetachItemData } from '../src/AttachDetachItem/prepareAttachDetachItemData';

package/packages/list/BasicList/README.md

@@ -0,0 +1,71 @@
+---
+id: README
+title: BasicList
+hide_title: true
+sidebar_label: BasicList
+---
+
+# BasicList
+Basic List is a type of list that prefers moving the focus first and only after the focus reaches the last fully visible item
+it starts scrolling and keeping the focus at the same position (on the edge).
+
+## List Specific Props
+- `firstScrollStep` - value in pixels to move on the first scroll
+- `scrollStep` - value to move on other scrolls (should be equal to item width + its spacing)
+
+## Default Animation Configuration
+- normal: 700ms with easeOutQuart
+
+## Usage
+
+Most of the use cases of the Basic List are that you have an N amount of fully visible items and navigatable items.
+Then you also have 2 partially visible items (1 on each side) to indicate the possibility to scroll in that direction.
+
+Therefore you usually set visible items to the number of fully visible (=== navigatable) items + 2.
+
+There can be cases when you do not indicate the possibility to scroll with a partial item but with some other technique (e.g. an arrow).
+For this case see Example 2
+
+## Examples
+
+### Example 1
+Probably the most common usage of the BasicList.
+- `firstScrollStep` is slightly smaller to keep the first item partially visible.
+- `scrollStep` is equal to an item width + the space between two items
+- `visibleItems` is set to 5 because there can be 5 visible items (3 fully visible and navigatable and 2 partially visible)
+```tsx
+<BasicList
+    data={[1, 2, 3, 4, 5]}
+    renderItem={(item: number, index, ref) => (
+        <Item title={item} ref={ref} />
+    )}
+    visibleItems={5}
+    firstScrollStep={280}
+    scrollStep={300}
+    horizontal
+/>
+```
+![Example 1](./examples/example1.gif)
+
+### Example 2
+This example shows how to use BasicList when you have some other way to indicate scrolling.
+- `firstScrollStep` is equal to `scrollStep`
+- `scrollStep` is equal to an item width + the space between two items
+- `visibleItems` is set to 6 (4 fully visible and navigatable + 2)
+
+To better understand why it needs to be 6 here. Imagine that each item would be 1px narrower. Then the 1st and the last items would become partial indicators thus increasing the number of maximal visible items to 6.
+
+This is a quiet an edge case. But this setting will also solve preload of image for you.
+```tsx
+<BasicList
+    data={[1, 2, 3, 4, 5, 6]}
+    renderItem={(item: number, index, ref) => (
+        <Item title={item} ref={ref} />
+    )}
+    visibleItems={6}
+    firstScrollStep={316}
+    scrollStep={316}
+    horizontal
+>
+```
+![Example 2](./examples/example2.gif)

package/packages/list/BasicList/index.ts

@@ -0,0 +1 @@
+export { BasicList } from '../src/BasicList/BasicList';

package/packages/list/CenteredList/README.md

@@ -0,0 +1,42 @@
+---
+id: README
+title: CenteredList
+hide_title: true
+sidebar_label: CenteredList
+---
+
+# CenteredList
+Centered List is a type of list that keeps the focus in the center and scroll the list underneath.
+The center item is determined from `visibleItems`.
+If `visibleItems` is odd then the correct center item is used.
+If `visibleItems` is even then the "closer to the start" center item is used.
+
+## List Specific Props
+- `scrollStep` - value to move on scrolls (should be equal to item width + its spacing)
+
+## Default Animation Configuration
+- normal: 700ms with easeOutQuart
+
+## Usage
+Most of the use cases are that you keep the focus in the center of the screen and you scroll the list
+underneath this focus. Something like Time/Date selector in iOS.
+
+## Examples
+
+### Example 1
+Probably the most common usage of the CenteredList.
+- `scrollStep` is equal to an item width + the space between two items
+- `visibleItems` is set to 5 because there can be 5 visible items (3 fully visible and 2 partially visible)
+```tsx
+<CenteredList
+    data={[1, 2, 3, 4, 5]}
+    renderItem={(item: number, index, ref) => (
+        <Item title={item} ref={ref} />
+    )}
+    visibleItems={5}
+    firstScrollStep={280}
+    scrollStep={300}
+    horizontal
+/>
+```
+![Example 1](./examples/example1.gif)

package/packages/list/CenteredList/index.ts

@@ -0,0 +1 @@
+export { CenteredList } from '../src/CenteredList/CenteredList';

package/packages/list/EdgeOffsetList/README.md

@@ -0,0 +1,58 @@
+---
+id: README
+title: EdgeOffsetList
+hide_title: true
+sidebar_label: EdgeOffsetList
+---
+
+# EdgeOffsetList
+EdgeOffset List is a type of list that prefers moving the focus first like BasicList. Unlike in BasicList,
+the focus stops `edgeOffset` items from the end. Then it starts scrolling and when the scroll reaches
+the end, focus continues to the rest of the items.
+
+## List Specific Props
+- `edgeOffset` - number of visible items from the edge where to start scroll (defaults to 1)
+- `scrollStep` - value to move on scrolls (should be equal to item width + its spacing)
+
+## Default Animation Configuration
+- normal: 700ms with easeOutQuart
+
+## Usage
+There aren't any typical use cases for EdgeOffsetList. The only known usage at the time of writing this document is in the WL menu.
+
+## Examples
+
+### Example 1
+- `edgeOffset` is omitted so it defaults to 1
+- `scrollStep` is equal to an item width + the space between two items
+- `visibleItems` is set to 5 because there can be 5 visible items
+```tsx
+<EdgeOffsetList
+    data={[1, 2, 3, 4, 5, 6, 7, 8]}
+    renderItem={(item: number, index, ref) => (
+        <Item title={item} ref={ref} />
+    )}
+    visibleItems={5}
+    scrollStep={300}
+    horizontal
+/>
+```
+![Example 1](./examples/example1.gif)
+
+### Example 2
+- `edgeOffset` is set to 2
+- `scrollStep` is equal to an item width + the space between two items
+- `visibleItems` is set to 5 because there can be 5 visible items
+```tsx
+<EdgeOffsetList
+    data={[1, 2, 3, 4, 5, 6, 7, 8]}
+    renderItem={(item: number, index, ref) => (
+        <Item title={item} ref={ref} />
+    )}
+    visibleItems={5}
+    edgeOffset={2}
+    scrollStep={300}
+    horizontal
+/>
+```
+![Example 2](./examples/example2.gif)

package/packages/list/EdgeOffsetList/index.ts

@@ -0,0 +1 @@
+export { EdgeOffsetList } from '../src/EdgeOffsetList/EdgeOffsetList';

package/packages/list/FirstOnlyList/README.md

@@ -0,0 +1,39 @@
+---
+id: README
+title: FirstOnlyList
+hide_title: true
+sidebar_label: FirstOnlyList
+---
+
+# FirstOnlyList
+FirstOnly List is a type of list that keeps the focus on the first item
+and scrolls the list underneath.
+
+## List Specific Props
+- `scrollStep` - value to move on scrolls (should be equal to item width + its spacing)
+
+## Default Animation Configuration
+- normal: 700ms with easeOutQuart
+
+## Usage
+Most of the use cases are that you keep the focus on the first item and you scroll the list
+underneath this focus. Something like Netflix lists.
+
+## Examples
+
+### Example 1
+Probably the most common usage of the FirstOnlyList.
+- `scrollStep` is equal to an item width + the space between two items
+- `visibleItems` is set to 5 because there can be 5 visible items (3 fully visible and 2 partially visible)
+```tsx
+<FirstOnlyList
+    data={[1, 2, 3, 4, 5]}
+    renderItem={(item: number, index, ref) => (
+        <Item title={item} ref={ref} />
+    )}
+    visibleItems={6}
+    scrollStep={300}
+    horizontal
+/>
+```
+![Example 1](./examples/example1.gif)

package/packages/list/FirstOnlyList/index.ts

@@ -0,0 +1 @@
+export { FirstOnlyList } from '../src/FirstOnlyList/FirstOnlyList';

package/packages/list/FirstOnlyVariedList/README.md

@@ -0,0 +1,105 @@
+---
+id: README
+title: FirstOnlyVariedList
+hide_title: true
+sidebar_label: FirstOnlyVariedList
+---
+
+# FirstOnlyVariedList
+FirstOnly Varied List is a type of list component where
+- *Varied* means list can contains items with various sizes, and 
+- *FirstOnly* means that keeps the focus on the first item
+and scrolls the list underneath.
+
+## Props
+- `data`*: U[]* - Array of data items, be passed to render
+- `renderItem`*: (item: U, index: number, ref: Reference<T>) => JSX.Element* - Function to render item in list where
+    - `item` - The data item to be rendered
+    - `index` - Index of item in the array
+    - `ref` - Reference has to be set to rendered item component
+- `viewportSizePx`*: number* - Size of visible list area in pixels. Provide width size of viewport for horizontal list, otherwise height size.
+- `itemsSizesPx`*: number[]* - Sizes of data items in pixels. Provide width size of items for horizontal list, otherwise height size.
+- `visibleItems`*: number* - Number of visible items, which be rendered in list's DOM element.
+- `extraPrevItems?`*: number* (default: `0`) - optional, Number of rendered items above visibleItems at beginning side of list.
+- `extraNextItems?`*: number* (default: `0`) - optional, Number of rendered items above visibleItems at end side of list.
+- `firstScrollStepPx?`*: number* (default: `0`) - optional, size in pixels applied to first scroll. Enables previous item to be partially visible in viewport while another content scrolls, should be used in combination with `extraPrevItems=1`
+- `className?`*: string* (default: `''`) - optional, Additional class name to add to list's DOM element
+- `horizontal?`*: boolean* (default: `false`) - optional, Flag of list orientation. `true` for horizontal, otherwise vertical.
+- `onFocusChanged?`*: (item: Reference\<T\>, index: number) => void* - optional, Function called every time when focus of item is changed in list, where
+    - `item` - Reference to new focused item
+    - `index` - Index of item in the array
+- `animation?`*: Partial\<AnimationConfiguration\>* - optional, [Animation configuration](../README.md#animationconfiguration) that is deep merged with default configuration of the list. Default object is:
+    - `normal`: 700ms with easeOutQuart
+    - `fast`: 100ms with easeOutQuart
+    - `normalToFast`: after 2 items with 0.65 sensitivity
+
+## Usage
+Most of the use cases are that you keep the focus on the first item and you scroll the list
+underneath this focus. Something like Netflix lists.
+
+## Examples
+
+### Example 1
+Probably the most common usage of the FirstOnlyVariedList.
+```tsx
+import { FirstOnlyVariedList } from '@24i/bigscreen-sdk/list/FirstOnlyVariedList';
+import { calcVisibleItemCount } from '@24i/bigscreen-sdk/list/utils';
+
+<FirstOnlyVariedList
+    data={[1, 2, 3, 4, 5]}
+    renderItem={(item: number, index, ref) => (
+        <Item title={item} ref={ref} />
+    )}
+    viewportSizePx={1280}
+    itemsSizesPx={[350, 200, 350, 200, 350]}
+    visibleItems={calcVisibleItemCount(1280, 200)} // is 7
+    horizontal
+/>
+```
+
+- `viewportSizePx` - defines size of viewport of list, area in which ensures to display items. Size should be equal to width of `.scroll-wrap` element
+- `itemsSizesPx` - array contains width in px of items from data
+- `visibleItems` - number of items to cover viewport area. It is set to 7 because there can be 7 visible items (5 fully visible and 2 partially visible) in case of 200px-width items. 
+ To simplify determination, there is provided `calcVisibleItemCount` util function.
+
+`calcVisibleItemCount(viewportSizePx: number, minItemSizePx: number): number`
+- `viewportSizePx` - Size (in pixels) of viewport of list. For vertical list, use height size.
+- `minItemSizePx` - Size (in pixels) of item in list. If list can contain items with different size, use the smallest item size.
+
+Function returns maximum number of visible items in list viewport.
+
+### Example 2
+Illustrates case list keeps part-visible previous item.
+```tsx
+import { FirstOnlyVariedList } from '@24i/bigscreen-sdk/list/FirstOnlyVariedList';
+import { calcVisibleItemCount } from '@24i/bigscreen-sdk/list/utils';
+
+<FirstOnlyVariedList
+    data={[1, 2, 3, 4, 5]}
+    renderItem={(item: number, index, ref) => (
+        <Item title={item} ref={ref} />
+    )}
+    viewportSizePx={1280}
+    itemsSizesPx={[350, 200, 350, 200, 350]}
+    visibleItems={calcVisibleItemCount(1280, 200)}
+    firstScrollStepPx={300}
+    extraPrevItems={1}
+    horizontal
+/>
+```
+- `firstScrollStepPx` - on first scroll, content is moved by 300px, which enables previous item to be partially visible (50px) for another content scrolls  
+- `extraPrevItems` - is set to 1, to keep one extra previous item present in list DOM
+
+## Required Styles
+Please note that you should set specific SCSS values for DOM items depending on kind of list.
+```SCSS
+// non-animated/animated list
+.animated .item {
+    position: absolute;
+}
+
+// static non-animated list
+.basic .item {
+    position: static;
+}
+```

package/packages/list/FirstOnlyVariedList/index.ts

@@ -0,0 +1 @@
+export { FirstOnlyVariedList } from '../src/FirstOnlyVariedList/FirstOnlyVariedList';

package/packages/list/FixedToEndList/README.md

@@ -0,0 +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)

package/packages/list/FixedToEndList/index.ts

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

package/packages/list/Item/index.ts

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