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

package/packages/jsx/README.md

@@ -1,388 +1,388 @@
----
-id: README
-title: BIGscreen JSX
-hide_title: true
-sidebar_label: BIGscreen JSX
----
-
-# BIGscreen JSX
-BIGscreen JSX is a set of tools that allow you to write JSX and converts it to JS Dom API.
-
-This package also exports a set of testing utils. You can import them with `/test-utils` import path. Documentation is here: [BIGscreen JSX Test Utils](./src/test-utils/README.md);
-
-## Supported features
-- HTML Elements with its props including event listeners and dataset props
-- Custom functional components
-- Custom class components that extend base Component
-- createRef
-- forwardRef
-- defaultProps
-- Fragment
-
-## It is not a React!
-Even though you write JSX and you can have the same types of components (HTML, function, class), the philosophy is completely different.
-BIGscreen JSX does not handle any state or rerenders by itself. It is meant to make your life easier and not to force you to write all JS DOM calls by hand.
-
-## HTMLElements
-```jsx
-    <div className="screen detail" ref={this.detailWrap} />
-```
-
-## Functional Components
-```jsx
-const Bold = ({ children }) => (
-    <b>{children}</b>
-);
-
-const Greet = ({ name }) => (
-    <h1>
-        Hello, <Bold>{name}</Bold>
-    </h1>
-);
-
-const App = () => (
-    <Greet name="John" />
-);
-```
-
-## Class Components
-Class components are similar to React class components, but they do not have any state or state handling.
-
-They have these lifecycle methods:
-- constructor
-- render
-- componentDidMount
-- componentWillUnmount
-
-### constructor
-This is a good place to initialize your component, bind methods, etc.
-
-### render
-This method must return the initial render.
-
-### componentDidMount
-At this point, all references should be available and you can add event listeners here.
-
-### componentWillUnmount
-At this point, the component was removed and you should clean after yourself.
-
-It also provides two methods for changing the content.
-- clearMount
-- appendMount
-
-### clearMount
-Takes two parameters. The first one is a JSX to render. The second one is a reference to HTMLElement to render to.
-It clears all the content before render.
-
-### appendMount
-Same use as **clearMount**. It does not clear the contents before render.
-
-```tsx
-import { Component, createRef, Children } from '@24i/bigscreen-sdk/jsx';
-
-type Props = {
-    children: Children,
-};
-
-class Greet extends Component<Props> {
-    constructor(props) {
-        super(props);
-        this.screenWidth = createRef();
-    }
-
-    componentDidMount() {
-        window.addEventListener('resize', this.onResize);
-    }
-
-    componentWillUnmount() {
-        window.removeEventListener('resize', this.onResize);
-    }
-
-    onResize = () => {
-        this.clearMount(<>{window.innerWidth}</>, this.screenWidth);
-    }
-
-    render() {
-        const { children } = this.props;
-        return (
-            <>
-                {children}
-                Screen width: <span ref={this.screenWidth}>{window.innerWidth}</span>
-            </>
-        )
-    }
-}
-```
-
-## createRef
-Returns object same as React version `{ current: null /* or reference to class instance or dom element */ }`
-
-## forwardRef
-Same as React version. Use with functional components to forward reference lower
-```jsx
-const ItalicH1 = forwardRef(({ children }, ref) => {
-    <h1 ref={ref}><i>{children}</i></h1>
-});
-```
-
-## static defaultProps
-Same as in React, components support default props. Unlike React they need to be explicitly typed.
-The other option is to just use them with a bang which might be also doable.
-```ts
-type Props = {
-    name: string,
-    detail?: string,
-    onFocus?: () => void,
-};
-export class MyComponent extends Component<Props> {
-    static defaultProps = {
-        detail: 'No more information',
-        onFocus: noop,
-    }
-
-    // If you omit this line, you have to use optional props with !
-    declare props: DeclareProps<Props, typeof MyComponent.defaultProps>;
-
-    // rest of the component...
-}
-```
-
-## Fragment
-As all components must render 1 JSX.Element or null you will need Fragment in cases:
-- you want to render an array
-- you want to render a string/number
-```tsx
-// array
-return (
-    <>
-        {data.map((item) => <Item data={item} />)}
-    </>
-)
-
-// string
-return <>Wassup!</>
-```
-
-## mount
-`mount` takes a JSX and appends to the given element.
-```js
-mount(<App />, document.getElementById('root')):
-```
-
-## mountBefore
-`mountBefore` takes a JSX and insert before given element.
-```js
-mountBefore(<App />, document.getElementById('inner')):
-```
-
-## Clearing functions
-JSX rendered content needs to be removed by specific functions. These functions are using lifecycle methods from created nodes and **will call** `componentWillUnmount` above element content. Every content created with JSX needs to use these methods. Function works also with elements which are not in the DOM and will unmount all their content as well.
-
-### clearNode
-Function to clear a node (equivalent of `innerHTML = ''`). Use this as it is platform optimized and works with the VDOM.
-```ts
-clearNode(this.wrapper); // passing Reference<HTMLElement>
-clearNode(document.getElementById('root')); // passing HTMLElement
-```
-
-### removeNode
-Function to remove one specific node (equivalent of `removeChild` function).
-```ts
-removeNode(this.element); // passing HTMLElement or Reference<HTMLElement>
-```
-
-## Manipulation functions
-These functions are not using lifecycle methods and they are meant for more specific manipulations. `componentWillUnmount` is **not called** and the VDOM is updated according to modification. All manipulation functions take as its parameters HTML elements or references to HTML elements. Every content created with JSX needs to use these methods. Manipulations could be performed under detached DOM structure, but need to respect conditions of each function.
-
-### attachNode
-Function will append node into target element. Appended node cannot be part of any DOM.
-```ts
-attachNode(this.element, this.targetElement);
-```
-
-### attachNodeBefore
-Function to insert node before specific element. Appended node cannot be part of any DOM.
-```ts
-attachNodeBefore(this.element, this.elementBefore);
-```
-
-### detachNode
-Opposite function to attachNode. Element is removed from the DOM and kept in memory.
-```ts
-detachNode(this.element);
-```
-
-### replaceNode
-Function to replace one node with another. Replacing node cannot be part of any DOM.
-```ts
-replaceNode(this.elementNew, this.elementOld);
-```
-
-### swapNodes
-Function for swapping two elements. Both elements needs to be part of the DOM.
-```ts
-swapNodes(this.elementNew, this.elementOld);
-```
-
-## Possible errors during node manipulation
-```
-"... is missing nxgvNode":
-
-If manipulated element does not have nxgvNode property, there are two options:
-- The elements you are working with are DOM root elements of the the VDOM. These elements are only partly in the VDOM, because they are not created through JSX, but still contains nxgvChildNodes of its VDOMs.
-- The elements you are working with are TextNodes. TextNodes are elements on the very end of the VDOM branch and they don't have their own nxgvNode so they cant be manipulated with manipulation methods.
-
-"... is not part of the VirtualDOM":
-
-Every element used in attachNode, attachNodeBefore, detachNode, replaceNode and swapNodes needs to match ExtendedHTMLElement type. These are all elements created with JSX except TextNodes and plain text. Error means that one or more elements (in some cases also elements parents) are not valid part of the virtual DOM or does not exist at all.
-```
-
-## setText
-Function to change a text value of the element. Use this as it is platform-optimized.
-First parameter is `HTMLElement` or `Reference<HTMLElement>`, second is string to set.
-```ts
-setText(this.time, formatTime(time, format));
-```
-
-## How to do things
-### E.g. Simple component that loads and displays movie detail
-
-**Equivalent in React**
-```jsx
-import React, { Component } from 'react';
-
-export default class Detail extends Component {
-    constructor(props) {
-        super(props);
-        this.state = { data: null };
-    }
-
-    componentDidMount() {
-        const { dataProvider, params: { id } } = this.props;
-        dataProvider.getMovie({ id }).then((data) => {
-            this.setState({ data });
-        });
-    }
-
-    renderDetail() {
-        const { data } = this.state;
-        return (
-            <div className="detail">
-                <div className="movie">
-                    <h1>{data.title}</h1>
-                    <p>{data.description}</p>
-                </div>
-            </div>
-        );
-    }
-
-    renderLoading() {
-        return (
-            <div className="detail">
-                <Loader />
-            </div>
-        );
-    }
-
-    render() {
-        const { data } = this.state;
-        return data ? this.renderDetail() : this.renderLoading();
-    }
-}
-```
-
-**BIGscreen JSX version**
-```tsx
-import { Component, createRef, DeclareProps } from '@24i/bigscreen-sdk/jsx';
-import { noop } from '@24i/bigscreen-sdk/utils/noop';
-
-type Props = {
-    params: { id: string },
-    dataProvider: DataProvider,
-    sceneName?: string,
-    onDataLoaded?: (data: Data) => void,
-}
-
-export default class Detail extends Component {
-    static defaultProps = {
-        sceneName: 'Movie Detail',
-        onDataLoaded: noop,
-    };
-
-    declare props: DeclareProps<Props, typeof Detail.defaultProps>;
-
-    constructor(props) {
-        super(props);
-        this.wrap = createRef();
-    }
-
-    componentDidMount() {
-        this.loadData();
-    }
-
-    loadData() {
-        const { dataProvider, params: { id }, onDataLoaded } = this.props;
-        dataProvider.getMovie({ id }).then((data) => {
-            this.renderDetail(data)
-            onDataLoaded(data);
-        });
-    }
-
-    renderDetail(data) {
-        this.clearMount((
-            <>
-                <h1>{sceneName}</h1>
-                <div className="movie">
-                    <h1>{data.title}</h1>
-                    <p>{data.description}</p>
-                </div>
-            </>
-        ), this.wrap);
-    }
-
-    render() {
-        const { sceneName } = this.props;
-        return (
-            <div className="detail" ref={this.wrap}>
-                <h1>{sceneName}</h1>
-                <Loader />
-            </div>
-        );
-    }
-}
-```
-
-As you can see from the above examples the React way is classic with state change and React auto-updating the DOM based on changes in Virtual DOM.
-
-The way you are supposed to do this in BIGscreen JSX is that you prepare a basic skeleton and you create references on containers whose content or props are going to change during the lifetime of the component.
-For changing props on HTMLElement simply access it through the reference. If the reference is on a custom component then you can access its instance through the ref as well.
-For changing the content you can use either `this.clearMount` or `this.appendMount` that take JSX as the first param and HTMLElement reference as the second one.
-
-## Extra
-There are some extra features that will not work in React but are done for performance reasons.
-
-## TextNode
-Adds referenced TextNode. Use it if you need to change the text on some event and you cannot afford to wrap it inside div or span.
-```ts
-class Translation extends Component<Props> {
-    textNode = createRef<Text>();
-
-    componentDidMount() {
-        i18n.addEventListener('languagechange', this.onLanguageChange);
-    }
-
-    componentWillUnmount() {
-        i18n.removeEventListener('languagechange', this.onLanguageChange);
-    }
-
-    onLanguageChange = () => {
-        const { translationKey } = this.props;
-        this.textNode.current.nodeValue = i18n.t(translationKey);
-    }
-
-    render() {
-        const { translationKey } = this.props;
-        return <TextNode ref={this.textNode}>{i18n.t(translationKey, options)}</TextNode>;
-    }
-}
-```
+---
+id: README
+title: BIGscreen JSX
+hide_title: true
+sidebar_label: BIGscreen JSX
+---
+
+# BIGscreen JSX
+BIGscreen JSX is a set of tools that allow you to write JSX and converts it to JS Dom API.
+
+This package also exports a set of testing utils. You can import them with `/test-utils` import path. Documentation is here: [BIGscreen JSX Test Utils](./src/test-utils/README.md);
+
+## Supported features
+- HTML Elements with its props including event listeners and dataset props
+- Custom functional components
+- Custom class components that extend base Component
+- createRef
+- forwardRef
+- defaultProps
+- Fragment
+
+## It is not a React!
+Even though you write JSX and you can have the same types of components (HTML, function, class), the philosophy is completely different.
+BIGscreen JSX does not handle any state or rerenders by itself. It is meant to make your life easier and not to force you to write all JS DOM calls by hand.
+
+## HTMLElements
+```jsx
+    <div className="screen detail" ref={this.detailWrap} />
+```
+
+## Functional Components
+```jsx
+const Bold = ({ children }) => (
+    <b>{children}</b>
+);
+
+const Greet = ({ name }) => (
+    <h1>
+        Hello, <Bold>{name}</Bold>
+    </h1>
+);
+
+const App = () => (
+    <Greet name="John" />
+);
+```
+
+## Class Components
+Class components are similar to React class components, but they do not have any state or state handling.
+
+They have these lifecycle methods:
+- constructor
+- render
+- componentDidMount
+- componentWillUnmount
+
+### constructor
+This is a good place to initialize your component, bind methods, etc.
+
+### render
+This method must return the initial render.
+
+### componentDidMount
+At this point, all references should be available and you can add event listeners here.
+
+### componentWillUnmount
+At this point, the component was removed and you should clean after yourself.
+
+It also provides two methods for changing the content.
+- clearMount
+- appendMount
+
+### clearMount
+Takes two parameters. The first one is a JSX to render. The second one is a reference to HTMLElement to render to.
+It clears all the content before render.
+
+### appendMount
+Same use as **clearMount**. It does not clear the contents before render.
+
+```tsx
+import { Component, createRef, Children } from '@24i/bigscreen-sdk/jsx';
+
+type Props = {
+    children: Children,
+};
+
+class Greet extends Component<Props> {
+    constructor(props) {
+        super(props);
+        this.screenWidth = createRef();
+    }
+
+    componentDidMount() {
+        window.addEventListener('resize', this.onResize);
+    }
+
+    componentWillUnmount() {
+        window.removeEventListener('resize', this.onResize);
+    }
+
+    onResize = () => {
+        this.clearMount(<>{window.innerWidth}</>, this.screenWidth);
+    }
+
+    render() {
+        const { children } = this.props;
+        return (
+            <>
+                {children}
+                Screen width: <span ref={this.screenWidth}>{window.innerWidth}</span>
+            </>
+        )
+    }
+}
+```
+
+## createRef
+Returns object same as React version `{ current: null /* or reference to class instance or dom element */ }`
+
+## forwardRef
+Same as React version. Use with functional components to forward reference lower
+```jsx
+const ItalicH1 = forwardRef(({ children }, ref) => {
+    <h1 ref={ref}><i>{children}</i></h1>
+});
+```
+
+## static defaultProps
+Same as in React, components support default props. Unlike React they need to be explicitly typed.
+The other option is to just use them with a bang which might be also doable.
+```ts
+type Props = {
+    name: string,
+    detail?: string,
+    onFocus?: () => void,
+};
+export class MyComponent extends Component<Props> {
+    static defaultProps = {
+        detail: 'No more information',
+        onFocus: noop,
+    }
+
+    // If you omit this line, you have to use optional props with !
+    declare props: DeclareProps<Props, typeof MyComponent.defaultProps>;
+
+    // rest of the component...
+}
+```
+
+## Fragment
+As all components must render 1 JSX.Element or null you will need Fragment in cases:
+- you want to render an array
+- you want to render a string/number
+```tsx
+// array
+return (
+    <>
+        {data.map((item) => <Item data={item} />)}
+    </>
+)
+
+// string
+return <>Wassup!</>
+```
+
+## mount
+`mount` takes a JSX and appends to the given element.
+```js
+mount(<App />, document.getElementById('root')):
+```
+
+## mountBefore
+`mountBefore` takes a JSX and insert before given element.
+```js
+mountBefore(<App />, document.getElementById('inner')):
+```
+
+## Clearing functions
+JSX rendered content needs to be removed by specific functions. These functions are using lifecycle methods from created nodes and **will call** `componentWillUnmount` above element content. Every content created with JSX needs to use these methods. Function works also with elements which are not in the DOM and will unmount all their content as well.
+
+### clearNode
+Function to clear a node (equivalent of `innerHTML = ''`). Use this as it is platform optimized and works with the VDOM.
+```ts
+clearNode(this.wrapper); // passing Reference<HTMLElement>
+clearNode(document.getElementById('root')); // passing HTMLElement
+```
+
+### removeNode
+Function to remove one specific node (equivalent of `removeChild` function).
+```ts
+removeNode(this.element); // passing HTMLElement or Reference<HTMLElement>
+```
+
+## Manipulation functions
+These functions are not using lifecycle methods and they are meant for more specific manipulations. `componentWillUnmount` is **not called** and the VDOM is updated according to modification. All manipulation functions take as its parameters HTML elements or references to HTML elements. Every content created with JSX needs to use these methods. Manipulations could be performed under detached DOM structure, but need to respect conditions of each function.
+
+### attachNode
+Function will append node into target element. Appended node cannot be part of any DOM.
+```ts
+attachNode(this.element, this.targetElement);
+```
+
+### attachNodeBefore
+Function to insert node before specific element. Appended node cannot be part of any DOM.
+```ts
+attachNodeBefore(this.element, this.elementBefore);
+```
+
+### detachNode
+Opposite function to attachNode. Element is removed from the DOM and kept in memory.
+```ts
+detachNode(this.element);
+```
+
+### replaceNode
+Function to replace one node with another. Replacing node cannot be part of any DOM.
+```ts
+replaceNode(this.elementNew, this.elementOld);
+```
+
+### swapNodes
+Function for swapping two elements. Both elements needs to be part of the DOM.
+```ts
+swapNodes(this.elementNew, this.elementOld);
+```
+
+## Possible errors during node manipulation
+```
+"... is missing nxgvNode":
+
+If manipulated element does not have nxgvNode property, there are two options:
+- The elements you are working with are DOM root elements of the the VDOM. These elements are only partly in the VDOM, because they are not created through JSX, but still contains nxgvChildNodes of its VDOMs.
+- The elements you are working with are TextNodes. TextNodes are elements on the very end of the VDOM branch and they don't have their own nxgvNode so they cant be manipulated with manipulation methods.
+
+"... is not part of the VirtualDOM":
+
+Every element used in attachNode, attachNodeBefore, detachNode, replaceNode and swapNodes needs to match ExtendedHTMLElement type. These are all elements created with JSX except TextNodes and plain text. Error means that one or more elements (in some cases also elements parents) are not valid part of the virtual DOM or does not exist at all.
+```
+
+## setText
+Function to change a text value of the element. Use this as it is platform-optimized.
+First parameter is `HTMLElement` or `Reference<HTMLElement>`, second is string to set.
+```ts
+setText(this.time, formatTime(time, format));
+```
+
+## How to do things
+### E.g. Simple component that loads and displays movie detail
+
+**Equivalent in React**
+```jsx
+import React, { Component } from 'react';
+
+export default class Detail extends Component {
+    constructor(props) {
+        super(props);
+        this.state = { data: null };
+    }
+
+    componentDidMount() {
+        const { dataProvider, params: { id } } = this.props;
+        dataProvider.getMovie({ id }).then((data) => {
+            this.setState({ data });
+        });
+    }
+
+    renderDetail() {
+        const { data } = this.state;
+        return (
+            <div className="detail">
+                <div className="movie">
+                    <h1>{data.title}</h1>
+                    <p>{data.description}</p>
+                </div>
+            </div>
+        );
+    }
+
+    renderLoading() {
+        return (
+            <div className="detail">
+                <Loader />
+            </div>
+        );
+    }
+
+    render() {
+        const { data } = this.state;
+        return data ? this.renderDetail() : this.renderLoading();
+    }
+}
+```
+
+**BIGscreen JSX version**
+```tsx
+import { Component, createRef, DeclareProps } from '@24i/bigscreen-sdk/jsx';
+import { noop } from '@24i/bigscreen-sdk/utils/noop';
+
+type Props = {
+    params: { id: string },
+    dataProvider: DataProvider,
+    sceneName?: string,
+    onDataLoaded?: (data: Data) => void,
+}
+
+export default class Detail extends Component {
+    static defaultProps = {
+        sceneName: 'Movie Detail',
+        onDataLoaded: noop,
+    };
+
+    declare props: DeclareProps<Props, typeof Detail.defaultProps>;
+
+    constructor(props) {
+        super(props);
+        this.wrap = createRef();
+    }
+
+    componentDidMount() {
+        this.loadData();
+    }
+
+    loadData() {
+        const { dataProvider, params: { id }, onDataLoaded } = this.props;
+        dataProvider.getMovie({ id }).then((data) => {
+            this.renderDetail(data)
+            onDataLoaded(data);
+        });
+    }
+
+    renderDetail(data) {
+        this.clearMount((
+            <>
+                <h1>{sceneName}</h1>
+                <div className="movie">
+                    <h1>{data.title}</h1>
+                    <p>{data.description}</p>
+                </div>
+            </>
+        ), this.wrap);
+    }
+
+    render() {
+        const { sceneName } = this.props;
+        return (
+            <div className="detail" ref={this.wrap}>
+                <h1>{sceneName}</h1>
+                <Loader />
+            </div>
+        );
+    }
+}
+```
+
+As you can see from the above examples the React way is classic with state change and React auto-updating the DOM based on changes in Virtual DOM.
+
+The way you are supposed to do this in BIGscreen JSX is that you prepare a basic skeleton and you create references on containers whose content or props are going to change during the lifetime of the component.
+For changing props on HTMLElement simply access it through the reference. If the reference is on a custom component then you can access its instance through the ref as well.
+For changing the content you can use either `this.clearMount` or `this.appendMount` that take JSX as the first param and HTMLElement reference as the second one.
+
+## Extra
+There are some extra features that will not work in React but are done for performance reasons.
+
+## TextNode
+Adds referenced TextNode. Use it if you need to change the text on some event and you cannot afford to wrap it inside div or span.
+```ts
+class Translation extends Component<Props> {
+    textNode = createRef<Text>();
+
+    componentDidMount() {
+        i18n.addEventListener('languagechange', this.onLanguageChange);
+    }
+
+    componentWillUnmount() {
+        i18n.removeEventListener('languagechange', this.onLanguageChange);
+    }
+
+    onLanguageChange = () => {
+        const { translationKey } = this.props;
+        this.textNode.current.nodeValue = i18n.t(translationKey);
+    }
+
+    render() {
+        const { translationKey } = this.props;
+        return <TextNode ref={this.textNode}>{i18n.t(translationKey, options)}</TextNode>;
+    }
+}
+```