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

package/packages/router/README.md

@@ -0,0 +1,163 @@
+---
+id: README
+title: Router
+hide_title: true
+sidebar_label: Router
+---
+
+# Router
+This package contains Router component, Route component and navigation (go, back, clearHistory).
+
+## Router component
+This component renders Routes passed in as children. It won't render anything else.
+It will take care of route switching based on hash changes. It also supports params in the route.
+
+### Props
+- `children` - Routes
+- `defaultPath` - optional path to which go after Router is mounted (default: `/`)
+- `detachInactiveRoutes` - optional flag if routes should detach from DOM entirely during route switching (default: `true`)
+
+### Interface
+- `getActiveRoute()`*: Route | null* - Returns active route component
+- `focus()`*: void* - Function calls focus on active route component
+
+## Route component
+Route component renders one single route.
+Passed component is not created and rendered until it should be shown for the first time.
+
+## Route switching
+There are two types of route switching. Routes are by default detached entirely from the DOM tree and only the
+one active route is present at the moment. This approach is better for performance, because of less elements in the DOM tree.
+Second type is keeping all routes in the DOM tree and every route has `display: none` except
+active one which has `display: block`. For this behaviour, set `detachInactiveRoutes` to `false` in props.
+
+### IRoute
+Interface that should be implemented by Route's component.
+```ts
+type RouteParams = { [key: string]: string };
+
+interface IRoute {
+    activate: (params: RouteParams) => void,
+    deactivate: (params: RouteParams) => void,
+    reactivate: (params: RouteParams) => void,
+    focus: () => void,
+}
+```
+
+### Props
+- `path` - path in string format. Prepend params with `:` (e.g. `/home` or `/detail/:id`)
+- `Component` - Component that will be rendered once the Route is active and must implement IRoute.
+
+### Interface
+- `focus()`*: void* - recall focus method on Route's component
+
+## Usage
+```tsx
+<Router defaultPath={window.location.href.split('#')[1] || '/home'}>
+    <Route path="/home" Component={Home} />
+    <Route path="/detail/:id" Component={Detail} />
+    <Route path="(.*)" Component={Route404} />
+</Router>
+```
+Note: `window.location.href.split('#')[1] || '/home'` allows deep linking from outside (or after refresh)
+
+## Route lifecycle
+```
+--> activate(params: RouteParams) --> deactivate() <-- --> reactivate(params: RouteParams)
+```
+
+- activate - called on the first activation of the route
+  - route element is rendered, scene inside (route component) is rendered and visible
+- deactivate - called everytime user is leaving the route
+  - route element and scene are still attached and visible
+- reactivate - called everytime user is entering the route except for the first time
+  - route element and scene are attached and visible
+
+When the route remains the same but with different params (e.g. detail A to detail B) then deactivate and reactivate is called.
+
+## Focusing
+For handling focus over routes, there is a helper function provided:
+- `focusActiveRoute()`*: void* - Function calls focus on router's active component
+```ts
+import { focusActiveRoute } from '@24i/bigscreen-sdk/router';
+
+onReturnFocusToScene() {
+    focusActiveRoute();
+}
+```
+
+## Navigation
+For navigation you should use these functions:
+- go
+- back
+- clearHistory
+
+### go
+This will go to specified path.
+```ts
+onMovieClick() {
+    go(`/detail/${movie.id}`);
+}
+```
+Go also supports optional params:
+```ts
+type NavigationConfig = {
+    skipHistory?: boolean,
+    replaceHistory?: boolean,
+};
+```
+- `skipHistory` - if true then the navigated route will not be added to the history
+- `replaceHistory` - if true then the navigated route will replace the last record in history
+More examples [here](#go-navigation-examples).
+
+### back
+This will go back in history.
+```ts
+onReturn() {
+    back();
+}
+```
+
+### clearHistory
+As its name suggests, this clears the history.
+
+## Go Navigation Examples
+
+### skipHistory: false, replaceHistory: false
+| Command | Active Route | History |
+| :- | :-: | :- |
+| `go('/home')` | /home | <ul><li>/home</li></ul> |
+| `go('/detail/A')` | /detail/A | <ul><li>/home</li><li>/detail/A</li></ul> |
+| `go('/detail/B')` | /detail/B | <ul><li>/home</li><li>/detail/A</li><li>/detail/B</li></ul> |
+| `go('/detail/C')` | /detail/C | <ul><li>/home</li><li>/detail/A</li><li>/detail/B</li><li>/detail/C</li></ul> |
+| `go('/player/C')` | /player/C | <ul><li>/home</li><li>/detail/A</li><li>/detail/B</li><li>/detail/C</li><li>/player/C</li></ul> |
+| `back()` | /detail/C | <ul><li>/home</li><li>/detail/A</li><li>/detail/B</li><li>/detail/C</li></ul> |
+| `back()` | /detail/B | <ul><li>/home</li><li>/detail/A</li><li>/detail/B</li></ul> |
+| `back()` | /detail/A | <ul><li>/home</li><li>/detail/A</li></ul> |
+| `back()` | /home | <ul><li>/home</li></ul> |
+
+### skipHistory: true, replaceHistory: false
+| Command | Active Route | History |
+| :- | :-: | :- |
+| `go('/home')` | /home | <ul><li>/home</li></ul> |
+| `go('/detail/A')` | /detail/A | <ul><li>/home</li><li>/detail/A</li></ul> |
+| `go('/detail/B', { skipHistory: true })` | /detail/B | <ul><li>/home</li><li>/detail/A</li></ul> |
+| `go('/detail/C', { skipHistory: true })` | /detail/C | <ul><li>/home</li><li>/detail/A</li></ul> |
+| `go('/player/C')` | /player/C | <ul><li>/home</li><li>/detail/A</li><li>/player/C</li></ul> |
+| `back()` | /detail/A | <ul><li>/home</li><li>/detail/A</li></ul> |
+| `back()` | /home | <ul><li>/home</li></ul> |
+
+### skipHistory: false, replaceHistory: true
+| Command | Active Route | History |
+| :- | :-: | :- |
+| `go('/home')` | /home | <ul><li>/home</li></ul> |
+| `go('/detail/A')` | /detail/A | <ul><li>/home</li><li>/detail/A</li></ul> |
+| `go('/detail/B', { replaceHistory: true })` | /detail/B | <ul><li>/home</li><li>/detail/B</li></ul> |
+| `go('/detail/C', { replaceHistory: true })` | /detail/C | <ul><li>/home</li><li>/detail/C</li></ul> |
+| `go('/player/C')` | /player/C | <ul><li>/home</li><li>/detail/C</li><li>/player/C</li></ul> |
+| `back()` | /detail/C | <ul><li>/home</li><li>/detail/C</li></ul> |
+| `back()` | /home | <ul><li>/home</li></ul> |
+
+### skipHistory: true, replaceHistory: true
+Although this param combination will not throw an error, technically it is an invalid combination
+and it will behave as `{ skipHistory: false, replaceHistory: true }`.

package/packages/router/src/Route.tsx

@@ -0,0 +1,132 @@
+import {
+    attachNode,
+    Component,
+    createRef,
+    detachNode,
+    replaceNode,
+} from '@24i/bigscreen-sdk/jsx';
+import { filter, forEach } from '@24i/bigscreen-sdk/perf-utils/array';
+import { getCurrentHash } from './utils';
+import { IRoute, RouteParams } from './types';
+
+type Props = {
+    path: string,
+    regexpPath?: RegExp,
+    paramNames?: string[],
+    isDetachable?: boolean;
+    Component: Function,
+};
+
+export class Route extends Component<Props> {
+    wasCreated = false;
+
+    isDetached = false;
+
+    domParent: HTMLElement | null = null;
+
+    domRef = createRef<HTMLDivElement>();
+
+    component = createRef<IRoute | null>();
+
+    componentDidMount() {
+        const { isDetachable } = this.props;
+        this.domParent = this.domRef.current?.parentElement!;
+        if (isDetachable) this.detach();
+    }
+
+    getParams(): RouteParams {
+        const { regexpPath, paramNames } = this.props;
+        if (!paramNames || !regexpPath) return {};
+        if (paramNames.length) {
+            const hash = getCurrentHash();
+            const matches = filter(hash.match(regexpPath) || [], (_, i) => i > 0);
+            const params: RouteParams = {};
+            forEach(matches, (match, i) => {
+                params[paramNames[i]] = match;
+            });
+            return params;
+        }
+        return {};
+    }
+
+    show() {
+        this.showRoute();
+        if (!this.wasCreated) {
+            this.mountRoute();
+            this.component.current?.activate(this.getParams());
+        } else {
+            this.component.current?.reactivate(this.getParams());
+        }
+    }
+
+    hide() {
+        if (this.wasCreated) {
+            this.component.current?.deactivate();
+            this.hideRoute();
+        }
+    }
+
+    replace(newRoute: Route) {
+        if (!this.isDetached && newRoute.isDetached) {
+            replaceNode(newRoute.domRef, this.domRef);
+            newRoute.isDetached = false;
+            this.isDetached = true;
+        }
+    }
+
+    attach() {
+        if (this.isDetached) {
+            attachNode(this.domRef, this.domParent!);
+            this.isDetached = false;
+        }
+    }
+
+    detach() {
+        if (!this.isDetached) {
+            detachNode(this.domRef);
+            this.isDetached = true;
+        }
+    }
+
+    deactivate() {
+        if (this.wasCreated) {
+            this.component.current?.deactivate();
+        }
+    }
+
+    focus() {
+        if (this.wasCreated) {
+            this.component.current?.focus();
+        }
+    }
+
+    private showRoute() {
+        const { isDetachable } = this.props;
+        if (!isDetachable) this.domRef.current!.style.display = 'block';
+    }
+
+    private hideRoute() {
+        const { isDetachable } = this.props;
+        if (!isDetachable) this.domRef.current!.style.display = 'none';
+    }
+
+    private mountRoute() {
+        const { Component: RouteComponent } = this.props;
+        this.appendMount(
+            <RouteComponent ref={this.component} />,
+            this.domRef,
+        );
+        this.wasCreated = true;
+    }
+
+    render() {
+        const { isDetachable } = this.props;
+        return (
+            <div
+                className="route"
+                style={!isDetachable ? { display: 'none' } : {}}
+                ref={this.domRef}
+            />
+        );
+    }
+}

package/packages/router/src/Router.tsx

@@ -0,0 +1,174 @@
+import { Component, Reference, createRef, DeclareProps } from '@24i/bigscreen-sdk/jsx';
+import { device } from '@24i/bigscreen-sdk/device';
+import { filter, forEach, map } from '@24i/bigscreen-sdk/perf-utils/array';
+import { stopEventImmediately } from '@24i/bigscreen-sdk/utils/stopEvent';
+import { Route } from './Route';
+import { pathToRegExp, getCurrentHash, isPathVisible } from './utils';
+import { go, back, history } from './history';
+
+type Props = {
+    children: JSX.Element[],
+    defaultPath?: string,
+    detachInactiveRoutes?: boolean,
+};
+
+type RoutePath = {
+    ref: Reference<Route>,
+    isVisible: boolean,
+    regexpPath: RegExp,
+    paramNames: string[],
+};
+
+export const routerRef = createRef<Router>();
+
+const filterNulls = (allChildren: (JSX.Element | null)[]) => (
+    <>{filter(allChildren, (child) => child !== null)}</>
+);
+
+export class Router extends Component<Props> {
+    paths: { [key: string]: RoutePath } = {};
+
+    static defaultProps = {
+        defaultPath: '/',
+        detachInactiveRoutes: true,
+    };
+
+    declare props: DeclareProps<Props, typeof Router.defaultProps>;
+
+    constructor(props: Props) {
+        super(props);
+        routerRef.current = this;
+        this.createRefs();
+    }
+
+    componentDidMount() {
+        window.document.addEventListener('keydown', this.onKeyDown, false);
+        window.addEventListener('hashchange', this.onHashChange, false);
+        this.goToDefaultPath();
+    }
+
+    componentWillUnmount() {
+        window.document.removeEventListener('keydown', this.onKeyDown, false);
+        window.removeEventListener('hashchange', this.onHashChange, false);
+    }
+
+    onHashChange = () => {
+        this.setPathsVisibility();
+    };
+
+    onKeyDown = (event: KeyboardEvent) => {
+        if (history.length > 1 && device.isBackOrEscape(event)) {
+            back();
+            stopEventImmediately(event);
+        }
+    };
+
+    setPathsVisibility() {
+        const hash = getCurrentHash();
+        let routePathToShow: RoutePath | null = null;
+        let routePathToHide: RoutePath | null = null;
+
+        forEach(Object.keys(this.paths), (path) => {
+            const route = this.paths[path];
+            if (!routePathToShow && isPathVisible(hash, route.regexpPath)) {
+                routePathToShow = route;
+            }
+            if (route.isVisible) {
+                routePathToHide = route;
+            }
+        });
+
+        const routeToHide = routePathToHide ? (routePathToHide as RoutePath).ref.current : null;
+        const routeToShow = routePathToShow ? (routePathToShow as RoutePath).ref.current : null;
+
+        this.switchRoutes(routePathToHide, routePathToShow, routeToHide, routeToShow);
+    }
+
+    getActiveRoute() {
+        const activeRoutePath = Object.values(this.paths).find((routePath: RoutePath) => (
+            routePath.isVisible
+        ));
+        return activeRoutePath?.ref.current || null;
+    }
+
+    switchRoutes(
+        routePathToHide: RoutePath | null,
+        routePathToShow: RoutePath | null,
+        routeToHide: Route | null,
+        routeToShow: Route | null,
+    ) {
+        const { detachInactiveRoutes } = this.props;
+        if (routePathToHide) {
+            if (routePathToShow && routeToHide === routeToShow) {
+                routeToHide!.deactivate();
+            } else if (routePathToShow) {
+                routeToHide!.hide();
+                routePathToHide.isVisible = false;
+                if (detachInactiveRoutes) routeToHide!.replace(routeToShow!);
+                routeToShow!.show();
+                routePathToShow.isVisible = true;
+                return;
+            } else {
+                routeToHide!.hide();
+                routePathToHide.isVisible = false;
+                if (detachInactiveRoutes) routeToHide!.detach();
+            }
+        }
+        if (routePathToShow) {
+            if (detachInactiveRoutes) routeToShow!.attach();
+            routeToShow!.show();
+            routePathToShow.isVisible = true;
+        }
+    }
+
+    focus() {
+        this.getActiveRoute()?.focus();
+    }
+
+    createRefs() {
+        const { children } = this.props;
+        forEach(children, (child: JSX.Element) => {
+            if (child.type === Route) {
+                const { path } = child.props;
+                const { regexpPath, paramNames } = pathToRegExp(path);
+                this.paths[path] = {
+                    ref: createRef<Route>(),
+                    isVisible: false,
+                    regexpPath,
+                    paramNames,
+                };
+            }
+        });
+    }
+
+    goToDefaultPath() {
+        const { defaultPath } = this.props;
+        const isAlreadyThere = defaultPath === getCurrentHash();
+        go(defaultPath);
+        if (isAlreadyThere) {
+            // Hash remains same so we need to trigger it manually
+            this.onHashChange();
+        }
+    }
+
+    render() {
+        const { children, detachInactiveRoutes } = this.props;
+        return filterNulls(map(children, (child: JSX.Element) => {
+            if (child.type === Route) {
+                const { path, Component: RouteComponent } = child.props;
+                const route = this.paths[path];
+                return (
+                    <Route
+                        ref={route.ref}
+                        path={path}
+                        regexpPath={route.regexpPath}
+                        Component={RouteComponent}
+                        paramNames={route.paramNames}
+                        isDetachable={detachInactiveRoutes}
+                    />
+                );
+            }
+            return null;
+        }));
+    }
+}

package/packages/router/src/focusActiveRoute.ts

@@ -0,0 +1,5 @@
+import { routerRef } from './Router';
+
+export const focusActiveRoute = () => {
+    routerRef.current?.focus();
+};

package/packages/router/src/history.ts

@@ -0,0 +1,24 @@
+import { NavigationConfig } from './types';
+
+export const history: string[] = [];
+
+const navigate = (path: string) => {
+    window.location.href = `#${path}`;
+};
+
+export const go = (path: string, { skipHistory, replaceHistory }: NavigationConfig = {}) => {
+    if (!skipHistory && !replaceHistory) history.push(path);
+    if (replaceHistory) history[history.length - 1] = path;
+    navigate(path);
+};
+
+export const back = () => {
+    if (history.length > 1) {
+        history.pop(); // remove current path
+        navigate(history[history.length - 1]);
+    }
+};
+
+export const clearHistory = () => {
+    history.length = 0;
+};

package/packages/router/src/index.ts

@@ -0,0 +1,5 @@
+export { Router } from './Router';
+export { Route } from './Route';
+export type { IRoute } from './types';
+export { history, go, back, clearHistory } from './history';
+export { focusActiveRoute } from './focusActiveRoute';

package/packages/router/src/types.ts

@@ -0,0 +1,13 @@
+export type RouteParams = Record<string, string>;
+
+export interface IRoute<T extends RouteParams = {}> {
+    activate: (params: T) => void,
+    reactivate: (params: T) => void,
+    deactivate: () => void,
+    focus: () => void,
+}
+
+export type NavigationConfig = {
+    skipHistory?: boolean,
+    replaceHistory?: boolean,
+};

package/packages/router/src/utils.ts

@@ -0,0 +1,24 @@
+import { forEach } from '@24i/bigscreen-sdk/perf-utils/array';
+
+export const isPathVisible = (hash: string, regexpPath?: RegExp) => (
+    !!regexpPath && !!hash.match(regexpPath)
+);
+
+export const getCurrentHash = () => window.location.href.split('#')[1] || '';
+
+const PARAM = '([a-zA-Z0-9-.:%_()\\[\\]{}]+)';
+
+export const pathToRegExp = (path: string) => {
+    const regexpParts: string[] = [];
+    const paramNames: string[] = [];
+    forEach(path.split('/'), (pathPart) => {
+        if (pathPart.indexOf(':') === 0) {
+            regexpParts.push(PARAM);
+            paramNames.push(pathPart.replace(':', ''));
+        } else regexpParts.push(pathPart);
+    });
+    return {
+        regexpPath: new RegExp(`^${regexpParts.join('\\/')}$`),
+        paramNames,
+    };
+};

package/packages/runtime-config/README.md

@@ -0,0 +1,37 @@
+---
+id: README
+title: Runtime Config
+hide_title: true
+sidebar_label: Runtime Config
+---
+
+# Runtime Config
+This package manages runtime configuration through external JSON file.
+
+## Setup in project
+If you use the BIGscreen template, it should be prepared.
+The location of the `config.json` is in `src` folder. After the build it is located inside `assets`
+folder together with other files. So the default path to config.json is `./assets/config.json`.
+This path can be changed in init function like this:
+```ts
+config.init('custom/path/to/config.json');
+```
+In your `main` function you first need to init the package:
+```ts
+import { config } from '@24i/bigscreen-sdk/runtime-config';
+
+const main = () => {
+    await config.init(); // This should be first
+    // ... other stuff like device init, render, etc.
+};
+```
+
+## Usage in packages
+```ts
+import { config } from '@24i/bigscreen-sdk/runtime-config';
+
+const backgroundColor = config.get('branding.background');
+```
+
+`config.get('path.to.key')` goes through the config object and
+either returns found value or undefined.

package/packages/runtime-config/src/Config.ts

@@ -0,0 +1,44 @@
+const DEFAULT_PATH = './assets/config.json';
+
+class Config {
+    private config: Record<string, any> = {};
+
+    async init(path: string = DEFAULT_PATH) {
+        return new Promise<void>((resolve, reject) => {
+            const xhr = new XMLHttpRequest();
+            xhr.onload = () => {
+                try {
+                    this.setConfig(JSON.parse(xhr.response));
+                    resolve();
+                } catch (error) {
+                    reject(error);
+                }
+            };
+
+            xhr.onerror = function (error) {
+                reject(error);
+            };
+
+            xhr.open('GET', path);
+            xhr.send();
+        });
+    }
+
+    setConfig(configObject: Record<string, any>) {
+        this.config = configObject;
+    }
+
+    get<T>(path: string): T | undefined {
+        const pathParts = path.split('.');
+        const pathPartsLength = pathParts.length;
+        let subConfig = this.config;
+        for (let i = 0; i < pathPartsLength; i++) {
+            const part = pathParts[i];
+            subConfig = subConfig[part];
+            if (typeof subConfig === 'undefined') return undefined;
+        }
+        return subConfig as T;
+    }
+}
+
+export const config = new Config();

package/packages/runtime-config/src/index.ts

@@ -0,0 +1 @@
+export { config } from './Config';