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

package/packages/sass-utils/README.md

@@ -0,0 +1,197 @@
+---
+id: README
+title: Sass utils
+hide_title: true
+sidebar_label: Sass utils
+---
+
+# Sass utils
+This package contains only sass utils to speed up style writing and unify it across projects.
+
+## Available utils
+All utils that do prefixing (except for `linear-gradient`) use `webkit` as a default list of prefixes.
+With all of them you can pass your own prefixes if needed as the last param.
+```scss
+@include transform(translate3d());
+/* vs */
+@include transform(translate3d(), moz ms);
+```
+
+### Mixins
+- [box-shadow](#box-shadow---mixin)
+- [ellipsis and multiline ellipsis](#ellipsis-and-multiline-ellipsis---mixin)
+- [linear-gradient](#linear-gradient---mixin)
+- [transform](#transform---mixin)
+- [transition](#transition---mixin)
+- [prefix](#prefix---mixin)
+- [prefix-value](#prefix-value---mixin)
+
+### Functions
+- [scale](#scale---function)
+- [prefix-property](#prefix-property---function)
+
+### box-shadow - mixin
+```scss
+@import '@24i/bigscreen-sdk/sass-utils/box-shadow';
+
+.my-element {
+    @include box-shadow(1px 2px 3px 4px #fff);
+}
+```
+outputs:
+```css
+.my-element {
+    -webkit-box-shadow: 1px 2px 3px 4px #fff;
+    box-shadow: 1px 2px 3px 4px #fff;
+}
+```
+
+### ellipsis and multiline-ellipsis - mixin
+```scss
+@import '@24i/bigscreen-sdk/sass-utils/ellipsis';
+
+.my-component-1 {
+    @include ellipsis;
+}
+
+.my-component-2 {
+    @include multiline-ellipsis(3);
+}
+```
+outputs:
+```css
+.my-component-1 {
+    overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+}
+
+.my-component-2 {
+    display: -webkit-box;
+    display: box;
+    -webkit-line-clamp: 3;
+    line-clamp: 3;
+    -webkit-box-orient: vertical;
+    overflow: hidden;
+}
+```
+
+### linear-gradient - mixin
+Linear gradient adds only webkit prefix for simplicity.
+```scss
+@import '@24i/bigscreen-sdk/sass-utils/linear-gradient';
+
+.my-component {
+    @include linear-gradient(to left, #f00 0%, #0f0 50%, #00f 100%);
+}
+```
+outputs:
+```css
+.my-component {
+    background: -webkit-linear-gradient(right, #f00 0%, #0f0 50%, #00f 100%);
+    background: linear-gradient(to left, #f00 0%, #0f0 50%, #00f 100%);
+}
+```
+
+### transform - mixin
+```scss
+@import '@24i/bigscreen-sdk/sass-utils/transform';
+
+.my-element {
+    @include transform(translate3d($left-offset, $top-offset, 0));
+}
+```
+outputs:
+```css
+.my-element {
+    -webkit-transform: translate3d(40px, 20px, 0);
+    transform: translate3d(40px, 20px, 0);
+}
+```
+
+### transition - mixin
+```scss
+@import '@24i/bigscreen-sdk/sass-utils/transition';
+@import '@24i/bigscreen-sdk/sass-utils/prefix-property';
+
+.my-element {
+    @include transition(prefix-property(transform) 300ms);
+}
+```
+outputs:
+```css
+.my-element {
+    -webkit-transition: all 300ms;
+    transition: all 300ms;
+    -webkit-transition-property: transform, -webkit-transform;
+    transition-property: transform, -webkit-transform;
+}
+```
+### scale - function
+Scale behaves slightly differently from other functions. There are two exports - one for 720 builds and
+one for 1080 builds. In your project, you should import the scale function in the styles file based
+on the size that you need. Then you should access the scale function through this import.
+- `scale.1080` just rounds the value.
+- `scale.720` divides the value by `1.5` and then rounds it.
+```scss
+// MyComponent.styles.scss
+@import '@24i/bigscreen-sdk/sass-utils/scale.720';
+@import './MyComponent';
+
+// MyComponent.styles.1080.scss
+@import '@24i/bigscreen-sdk/sass-utils/scale.1080';
+@import './MyComponent';
+
+// MyComponent.scss
+.my-component {
+    width: scale(1920px);
+}
+```
+
+### prefix-property - function
+```scss
+@import '@24i/bigscreen-sdk/sass-utils/prefix-property';
+
+.my-element {
+    /* Only to demonstrate standalone prefix-property. You should however use transition mixin */
+    transition: prefix-property(transform);
+}
+```
+outputs:
+```css
+.my-element {
+    transition: transform, -webkit-transform;
+}
+```
+
+### prefix - mixin
+```scss
+@import '@24i/bigscreen-sdk/sass-utils/prefix';
+
+.my-element {
+    @include prefix(transform, translate3d(10px, 20px, 0));
+}
+```
+outputs:
+```css
+.my-element {
+    -webkit-transform: translate3d(10px, 20px, 0);
+    transform: translate3d(10px, 20px, 0);
+}
+```
+
+### prefix-value - mixin
+```scss
+@import '@24i/bigscreen-sdk/sass-utils/prefix-value';
+
+.my-element {
+    @include prefix-value(display, box);
+}
+```
+outputs:
+```css
+.my-element {
+    display: -webkit-box;
+    display: box;
+}
+```

package/packages/sass-utils/src/box-shadow.scss

@@ -0,0 +1,5 @@
+@import './prefix';
+
+@mixin box-shadow($value, $prefixes: (webkit)) {
+    @include prefix(box-shadow, $value, $prefixes);
+}

package/packages/sass-utils/src/ellipsis.scss

@@ -0,0 +1,15 @@
+@import './prefix-value';
+@import './prefix';
+
+@mixin ellipsis {
+    overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+}
+
+@mixin multiline-ellipsis($lines, $prefixes: (webkit)) {
+    @include prefix-value(display, box, $prefixes);
+    @include prefix(line-clamp, $lines, $prefixes);
+    -webkit-box-orient: vertical;
+    overflow: hidden;
+}

package/packages/sass-utils/src/linear-gradient.scss

@@ -0,0 +1,43 @@
+@function legacy-direction($value) {
+    @if is-direction($value) == false {
+        @error "Cannot convert `#{$value}` to legacy syntax because it doesn't seem to be a direction.";
+    }
+    $conversion-map: (
+        to top          : bottom,
+        to top right    : bottom left,
+        to right top    : left bottom,
+        to right        : left,
+        to bottom right : top left,
+        to right bottom : left top,
+        to bottom       : top,
+        to bottom left  : top right,
+        to left bottom  : right top,
+        to left         : right,
+        to left top     : right bottom,
+        to top left     : bottom right
+    );
+    @if map-has-key($conversion-map, $value) {
+        @return map-get($conversion-map, $value);
+    }
+    @return 90deg - $value;
+}
+
+@function is-direction($value) {
+    $is-keyword: index((
+        to top, to top right, to right top, to right, to bottom right, to right bottom,
+        to bottom, to bottom left, to left bottom, to left, to left top, to top left,
+    ), $value);
+    $is-angle: type-of($value) == 'number' and index('deg' 'grad' 'turn' 'rad', unit($value));
+
+    @return $is-keyword or $is-angle;
+}
+
+@mixin linear-gradient($direction, $color-stops...) {
+    @if is-direction($direction) == false {
+        $color-stops: $direction, $color-stops;
+        $direction: 180deg;
+    }
+
+    background: -webkit-linear-gradient(legacy-direction($direction), $color-stops);
+    background: linear-gradient($direction, $color-stops);
+}

package/packages/sass-utils/src/prefix-property.scss

@@ -0,0 +1,7 @@
+@function prefix-property($property, $prefixes: (webkit)) {
+    $val: $property;
+    @each $prefix in $prefixes {
+        $val: #{$val + ', ' + '-' + $prefix + '-' + $property};
+    }
+    @return $val;
+}

package/packages/sass-utils/src/prefix-value.scss

@@ -0,0 +1,6 @@
+@mixin prefix-value($property, $value, $prefixes: (webkit)) {
+    @each $prefix in $prefixes {
+        #{$property}: #{'-' + $prefix + '-' + $value};
+    }
+    #{$property}: $value;
+}

package/packages/sass-utils/src/prefix.scss

@@ -0,0 +1,6 @@
+@mixin prefix($property, $value, $prefixes: (webkit)) {
+    @each $prefix in $prefixes {
+        #{'-' + $prefix + '-' + $property}: $value;
+    }
+    #{$property}: $value;
+}

package/packages/sass-utils/src/scale.1080.scss

@@ -0,0 +1,3 @@
+@function scale($value) {
+    @return round($number: $value);
+}

package/packages/sass-utils/src/scale.720.scss

@@ -0,0 +1,5 @@
+@use 'sass:math';
+
+@function scale($value) {
+    @return round($number: math.div($value, 1.5));
+}

package/packages/sass-utils/src/transform.scss

@@ -0,0 +1,5 @@
+@import './prefix';
+
+@mixin transform($value, $prefixes: (webkit)) {
+    @include prefix(transform, $value, $prefixes);
+}

package/packages/sass-utils/src/transition.scss

@@ -0,0 +1,6 @@
+@import './prefix';
+
+@mixin transition($properties, $value, $prefixes: (webkit)) {
+    @include prefix(transition, all $value, $prefixes);
+    @include prefix(transition-property, $properties, $prefixes);
+}

package/packages/scheduler/README.md

@@ -0,0 +1,55 @@
+---
+id: README
+title: Scheduler
+hide_title: true
+sidebar_label: Scheduler
+---
+
+# Scheduler
+This package is for your runtime scheduling needs. You can create reusable tasks and have them executed either once or periodically.
+
+## Scheduler Interface
+- `newTask` - creates and returns a new task that is not active, needs to be unique
+- `getTaskList` - returns a list with all task id's
+- `hasTask` - returns true if a task with id is managed
+- `getTask` - returns task with given id or undefined
+- `removeTask` - cancels and removes a task from Schedulers list
+- `setTimeProvider` - defaults time provider is Date.now, this method allows to change it
+
+**Task Interface**
+- `id` - tasks id
+- `isActive` - returns true if task is scheduled and waiting for execution, returns false if task wasn't started or already finished
+- `flush` - executes Task immediately and cancels its scheduling
+- `cancel` - cancels Tasks scheduling, task will not be executed
+
+Following methods schedule when task should execute:
+- `at` - executes the task at given time (timestamp), Schedulers time provider is used for time comparison
+- `in` - executes the task after given time in milliseconds (like setTimeout)
+- `every` - executes the task after X milliseconds, every X milliseconds (like setInterval)
+Calling them on active task will throw an exception, if you want to override active tasks scheduling without throwing exception call the scheduling method like so: `task.reschedule.at(TIMESTAMP)`
+
+Note that flushing or canceling a task doesn't remove it from Schedulers task list.
+
+## Usage
+Here are some common examples of Scheduler's use:
+
+Polling for news / messages every 10 minutes:
+```tsx
+Scheduler.newTask('message-polling', async () => {
+    const data = await fetchMessage();
+    if (data.message) MessageSystem.dispatch(data.message);
+}).every(TEN_MINUTES_IN_MS);
+```
+
+Update live/changing data:
+```tsx
+// componentDidMount
+const liveUpdater = Scheduler.newTask('live-metadata', async () => {
+    const newData = await fetchMetadata();
+    this.updateData(newData);
+    liveUpdater.at(newData.broadcastToMs);
+}).flush();
+
+// componentWillUnmount
+Scheduler.removeTask('live-metadata');
+```

package/packages/scheduler/src/Scheduler.ts

@@ -0,0 +1,43 @@
+import { timeProvider } from './timeProvider';
+import { Task } from './Task';
+
+export const Scheduler = {
+    taskList: [] as { key: string, task: Task }[],
+
+    setTimeProvider(newNow: () => number) {
+        timeProvider.now = newNow;
+    },
+
+    newTask(id: string, callback: Function): Task {
+        if (this.hasTask(id)) throw new Error('Duplicate task id in Scheduler');
+        const newTask = new Task(id, callback);
+        Scheduler.taskList.push({ key: id, task: newTask });
+        return newTask;
+    },
+
+    getTaskList(): string[] {
+        return this.taskList.map(({ key }) => key);
+    },
+
+    hasTask(id: string): boolean {
+        return this.taskList.findIndex(({ key }) => (key === id)) >= 0;
+    },
+
+    getTask(id: string): Task | null {
+        const taskEntry = this.taskList.find(({ key }) => (key === id));
+        if (taskEntry) return taskEntry.task;
+        return null;
+    },
+
+    removeTask(id: string) {
+        const taskEntryIdx = this.taskList.findIndex(({ key }) => (key === id));
+        if (taskEntryIdx < 0) {
+            console.warn(`Task ${id} not found.`);
+            return;
+        }
+
+        const { task } = this.taskList[taskEntryIdx];
+        this.taskList.splice(taskEntryIdx, 1);
+        task.cancel();
+    },
+};

package/packages/scheduler/src/Task.ts

@@ -0,0 +1,72 @@
+import {
+    createInterval,
+    createTimeout,
+    TimedFunction,
+} from '@24i/bigscreen-sdk/utils/timers';
+import { timeProvider } from './timeProvider';
+
+export class Task {
+    id: string;
+
+    callback: Function;
+
+    timer: TimedFunction | null = null;
+
+    constructor(id: string, callback: Function) {
+        this.id = id;
+        this.callback = callback;
+    }
+
+    private startTicker(
+        ms: number,
+        method: typeof createTimeout | typeof createInterval = createTimeout,
+    ) {
+        this.timer = method();
+        this.timer.set(() => {
+            if (method === createTimeout) this.timer = null;
+            this.callback();
+        }, ms);
+    }
+
+    isActive() {
+        return this.timer && this.timer.isActive();
+    }
+
+    at(timestamp: number): Task {
+        if (this.isActive()) throw new Error(`Task ${this.id} is already active`);
+        const now = timeProvider.now();
+        this.startTicker(Math.max(0, timestamp - now));
+        return this;
+    }
+
+    in(milliseconds: number): Task {
+        if (this.isActive()) throw new Error(`Task ${this.id} is already active`);
+        this.startTicker(Math.max(0, milliseconds));
+        return this;
+    }
+
+    reschedule = {
+        at: (timestamp: number): Task => this.cancel().at(timestamp),
+        in: (milliseconds: number): Task => this.cancel().in(milliseconds),
+        every: (milliseconds: number): Task => this.cancel().every(milliseconds),
+    };
+
+    every(milliseconds: number): Task {
+        if (this.isActive()) throw new Error(`Task ${this.id} is already active`);
+        this.startTicker(Math.max(0, milliseconds), createInterval);
+        return this;
+    }
+
+    flush(): Task {
+        if (this.isActive()) {
+            this.cancel();
+        }
+        this.callback();
+        return this;
+    }
+
+    cancel(): Task {
+        this.timer?.clear();
+        return this;
+    }
+}

package/packages/scheduler/src/index.ts

@@ -0,0 +1,4 @@
+import { Task as TaskClass } from './Task';
+
+export type TaskType = InstanceType<typeof TaskClass>;
+export { Scheduler } from './Scheduler';

package/packages/scheduler/src/timeProvider.ts

@@ -0,0 +1,3 @@
+export const timeProvider = {
+    now: Date.now,
+};

package/packages/scroll-text/README.md

@@ -0,0 +1,78 @@
+---
+id: README
+title: Scroll Text
+hide_title: true
+sidebar_label: Scroll Text
+---
+
+# Scroll Text
+Scroll Text is a component that should be used for focusable block of content that scrolls on user input.
+
+## Render
+Renders a `Scroller` component in a wrapper that scrolls using `offsetPosition`
+utility. The wrapper can be supplied with custom class to style the scroller 
+differently. It is rendered together with arrow navigation that indicates current
+scrolling position.
+
+## Props
+- `className` - classname for wrapper element
+- `horizontal` - whether to scroll horizontally
+- `scrollStepPx` - scroll step in px
+- `children`
+- `scrollLimitPx` - optional, maximum scroll offset in px, if not provided is calculated from content height
+- `onScrollChanged` - optional callback called when scroll offset changes
+
+**additional props for Animated version**
+- `animationSpeedMs` - animation speed in ms
+- `animationEasing` - optional, animation easing, default is linear
+
+## Usage
+```
+<ScrollText
+    className="scroll-text-1"
+    ref={this.scrollText}
+    scrollStepPx={50}
+    scrollLimitPx={200}
+    onFocusChanged={console.log}
+    animationSpeedMs={500}
+>
+    <div>{this.superLongText}</div>
+    <IconButton
+        ref={buttonRef}
+        icon="book"
+        text="Read more"
+        onPress={this.goToMore}
+    />
+</ScrollText>
+```
+
+## Arrow navigation
+Arrow navigation is rendered together with scroller. Every arrow element is
+modified by adding/removing `disabled` class to indicate its validity of scroll
+direction for current scroll position.
+
+```tsx
+<div class="arrow-navigation">
+    <div class="nav-arrow icon-arrow-up" />
+    <div class="nav-arrow icon-arrow-down disabled" /> // "disabled" indicates it is scrolled at end.
+</div>
+```
+
+If content is not scrollable, then `disabled` class name is added to both arrow elements and `.arrow-navigation` element:
+
+```tsx
+<div class="arrow-navigation disabled">
+    <div class="nav-arrow icon-arrow-up disabled" />
+    <div class="nav-arrow icon-arrow-down disabled" />
+</div>
+```
+
+Based on `horizontal` property, there are rendered two elements with class
+`icon-arrow-{up,down}` for vertical or `icon-arrow-{left,right}` for horizontal scroller.
+
+## Useful methods
+- `scrollToPx` - scrolls to given px position, clamped to scroll area
+- `scrollToPercent` - scrolls to given % position, input clamps to 0-1 range
+- `update` - update after content changed
+
+`scrollToPx` and `scrollToPercent` can be given 2nd parameter `true` in the animated version to make the scroller snap to the position instantly instead of animate over `animationSpeedMs`.