@24i/bigscreen-sdk 1.0.34 → 1.0.35-alpha.2578

package/packages/focus/README.md

@@ -1,348 +1,348 @@
----
-id: README
-title: Focus
-hide_title: true
-sidebar_label: Focus
----
-
-# Focus
-This package takes care of focus in SmartApps BIGscreen apps. It contains layout components and modules for handling focus candidates and focus limiting.
-
-## IFocusable
-IFocusable is an interface that should be implemented by anything that can be focused.
-```ts
-interface IFocusable {
-    focus(options?: FocusOptions): void,
-    hasDom?(element: HTMLElement): boolean,
-    hasFocus?(): boolean,
-}
-```
-- focus is the main function that is called when focusing component/element.
-- hasDom is optional optimization for components to help Layout components locate the currently
-focused child.
-- hasFocus is optional check if the component has focus inside or is itself focused.
-
-## Layout components
-- Vertical: Use it to create focus between elements vertically (up/down)
-- Horizontal: Use it to create focus between elements horizontally (left/right)
-- Matrix: Use it to create focus in a matrix (keyboards, special menus, etc.)
-
-## Vertical/Horizontal
-
-Both of these components share the same props;
-
-### Props
-- children: Children will be rendered as is.
-- focusableChildren: Array of references between which the focus moves.
-- domRef: Reference to a dom element that corresponds to closest dom wrapper.
-It will listen onKeyDown on this element.
-- onFocusChanged: Optional callback after focus has changed. It receives a reference
-to the focused element and its index. Ideal place to change other elements
-(e.g. header changing with focused movie)
-- onBeforeFocusChange: Optional callback just before focus change. It receives a reference
-to the focused element and its index. Ideal place for preparing for the change
-(e.g. moving the container to fit new element in the screen)
-- circular: makes focus circular, e.g. when pressing left at leftmost element focus will go to rightmost element
-- dir: Optional forceful setting of the component direction. Defaults to `'auto'` which follows
-the direction of the app.
-`'ltr'` always forces left-to-right layout,
-`'rtl'` always forces right-to-left.
-
-### Usage
-```jsx
-import { createRef, forwardRef } from '@24i/bigscreen-sdk/jsx';
-import { Vertical, Horizontal } from '@24i/bigscreen-sdk/focus';
-
-const Item = forwardRef(({ data }: Item, ref) => (
-    <div className="item" ref={ref} tabIndex={0}>
-        {/* item render */}
-    </div>
-));
-
-const Gallery = (data: { [key: string]: { title: string, items: Item[] } }) => {
-    const rootRef = createRef();
-    const categories = [];
-    return (
-        <div className="gallery" ref={rootRef}>
-            <Vertical
-                focusableChildren={categories}
-                domRef={rootRef}
-            >
-                {Object.keys(data).map((key) => {
-                    const category = data[key];
-                    const lineRef = createRef();
-                    categories.push(lineRef);
-                    const items = [];
-                    return (
-                        <div className="line" ref={lineRef}>
-                            <h3>{category.title}</h3>
-                            <Horizontal
-                                focusableChildren={items}
-                                domRef={lineRef}
-                            >
-                                {category.items.map((item) => {
-                                    const itemRef = createRef();
-                                    items.push(itemRef);
-                                    return (
-                                        <Item data={item} ref={itemRef} />
-                                    );
-                                })}
-                            </Horizontal>
-                        </div>
-                    );
-                })}
-            </Vertical>
-        </div>
-    );
-}
-```
-
-## Matrix
-This is a special kind of layout. It takes a matrix of focusable elements and provides navigation inside this matrix.
-It is useful for building keyboards, special layouts with atypically sized element, etc.
-
-### Props
-- children: Children will be rendered as is.
-- matrix: Array of arrays of references between which the focus moves.
-- domRef: Reference to a dom element that corresponds to closest dom wrapper. It will listen onKeyDown on this element.
-- onFocusChanged: Optional callback after focus has changed. It receives reference to focused element and its index. Ideal place to change other elements (e.g. header changing with focused movie)
-- onBeforeFocusChange: Optional callback just before focus change. It receives reference to focused element and its index. Ideal place for preparing for the change (e.g. moving the container to fit new element in the screen)
-- circular: makes focus circular, e.g. when pressing left at leftmost element focus will go to rightmost element, can be vertical, horizontal or all (vertical + horizontal), union with circularity direction is exported from focus
-
-### Usage
-Similar to Vertical/Horizontal. Define matrices like this:
-```ts
-// keyboard
-const matrix = [
-    [A, B, C, D, E],
-    [F, G, H, I, J],
-    [K, L, M, N, O],
-    [P, Q, R, S, T],
-    [U, V, W, X, Y],
-    [Z, SPACE, SPACE, BACKSPACE, CLEAR],
-];
-```
-```ts
-// Static grid with 2x3 HERO item
-const matrix = [
-    [H , H , H , A1],
-    [H , H , H , B1],
-    [C1, C2, C3, C4],
-];
-```
-
-## Prevent blur on long press
-When the user holds a navigation key, he usually scrolls to the boundary of the layout
-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 layout will propagate to another component
-or another layout. In some cases, we don't want this behavior and for those situations and
-to have better control above the layout navigation, there is a prop `preventBlurOnLongPress`.
-When the user scrolls to the boundary of the layout while holding a navigation key,
-he needs to release the key and press it again to propagate the event higher and focus
-another component or layout.
-
-## Limitations
-For the div to properly receive keydown events it needs to have set `tabIndex`. If you do not set `tabIndex` then it won't receive keydown events and those will not propagate to the Vertical/Horizontal component.
-
-`tabIndex` needs to be set only on those elements that are focused (`Item` in the example below). It does not need to be on the div that is referenced as `domRef` by Horizontal/Vertical.
-
-It can be set to 0.
-
-## Focus candidate
-During focusing, we are facing classic issues of keeping last focused element for refocusing back after our
-own focusing and logic for example in dialogs. This saved element is called **candidate**.
-This module brings set of functionalities for operating with candidates in one place instead of separate logic in each component.
-By this, something as "focus history" is stored in stack and shared among components in the application.
-
-### Functionality explanation
-
-Most basic type of usage is following:
-```
-some element in the app is focused and you need to open dialog
-  |<save last focused element (candidate) from document.activeElement>
-  |  dialog opening
-  |    focus dialog buttons and do something in the dialog...
-  |    // focusing something here is important
-  |    // because without it, candidate is not needed
-  |  dialog closing
-  |<focus candidate back in one candidate layer>
-continue your work with previously focused element as before
-```
-
-Remember one important thing again - candidate is **the last thing where your focus was**.
-You can also save candidates as currently focused elements (or components), but they would not be focused back right away,
-because you can't focus candidate which is currently focused element. Yet you can store it as next candidate for another layers.
-
-### What could be a candidate?
-Candidate is everything which can be focused or a reference to something which we can focus. This means that candidate could be anything which is compatible with `IFocusable` interface:
-```ts
-type ICandidate = {
-    isMounted?: boolean;
-} & IFocusable;
-
-type FocusCandidate = ICandidate | Reference<ICandidate>;
-```
-Most common candidates:
-- HTMLElement
-- Component (prop `isMounted` refers to availability of a component candidate)
-- Reference to HTMLElement
-- Reference to Component
-
-### Functions
-
-There are four main methods for working with focus candidate:
-
-```ts
-setActiveElementAsFocusCandidate()
-```
-This is the main method, which saves **document.activeElement** as a new candidate.
-This method should be used every time you need to save the last focused element from activeElement.
-In most cases, saving activeElement as a focus candidate is enough and it is the most common way how to save candidates.
-
-```ts
-setFocusCandidate(candidate: FocusCandidate)
-```
-Same as the first method, but now you need to specify manually, which candidate you want to save. Remember, a candidate needs to be always from previously focused content.
-
-```ts
-setNextFocusCandidate(candidate: FocusCandidate)
-```
-Next candidate is candidate for future layers. Candidate in previous methods was last focused content,
-but the next candidate is currently focused content. In short, the next candidate is remembered and it will be skipped when focusing the candidate back. Adding another candidate (or another next candidate) clears the current
-next candidate and now it is available.
-
-This functionality is used for example when your focusable content could
-change completely during its lifetime, so you need to set your whole component as the next candidate because your currently focused element on it, saved as another candidate, would not exist after your content changes.
-This is also achievable with references to your dynamic focusable elements.
-
-### Example
-
-Opening TechnicalInfo component
-```
-focus and logic in EPG
-    opening technical info component
-    <set candidate1 as epg cell>
-    <set next candidate2 as tech. info component>
-    focus technical info scroller, data are loading
-    data are loaded, re-rendering scroller element
-    closing tech. info
-    <focus candidate2 - skipped, because its current next candidate>
-    <focus candidate1 - epg cell>
-focus is back in EPG
-```
-And now when the asynchronous data are loaded and a modal pops-up
-```
-focus and logic in EPG
-    opening technical info component
-    <set candidate1 as epg cell>
-    <set next candidate2 as tech. info component>
-    focus technical info scroller, data are loading
-        modal pops up
-        <set candidate3 as tech. info scroller element>
-        focus dialog buttons
-    data are loaded, re-rendering scroller element 
-        modal closed
-        <focus candidate3 - can't be focused, its different now (not available), skipped>
-        <focus candidate2 - focus method on tech.info component with proper scroller element>
-    closing tech. info
-    <focus candidate1 - epg cell>
-focus is back in EPG
-```
-This can be used also in cooperation with `setActiveElementAsFocusCandidate` (or `setFocusCandidate`) when you need to save the previously focused element and then set manually the currently focused component or element as the next candidate.
-
-```ts
-focusCandidate(options?: FocusOptions)
-```
-This is the last method that closes the candidate circle. By calling `focusCandidate` you are focusing the last available candidate in the candidate stack. There is some logic behind candidate popping and it needs to fulfil these statements:
-
-- the last candidate can't be the current next candidate because it would focus current content again
-- candidate needs to exist and be available and it can't be the last focused element
-- (testing after candidate focus happened) newly focused candidate needs to be fully visible and can't be the same as previously focused one
-
-If none of those statements is fulfilled, another last candidate from the stack is taken. If there are no candidates available, candidate fallback is focused.
-
-### Candidate availability
-The candidate needs to be fully visible (not `display: none` or `visibility: hidden`), the same applies to its parents and it needs to be inserted in the attached DOM branch.
-
-### Candidate fallback
-```ts
-setCandidateFallback(candidate: FocusCandidate);
-```
-Candidate fallback is basically another focus candidate which will be focused when there are no other candidates in the stack. In most scenarios, it is the current scene or the Router component.
-
-### Other methods
-
-- getCandidateFallback — returns fallback
-- getLastCandidate — returns last candidate from candidate stack without any statements as in focusCandidate method
-- getCandidateStack — returns full candidate stack
-- clearCandidateStack — clears whole candidate stack and next candidate
-
-## safeFocus
-If you are working with asynchronous operations such as API calls, promises or timeouts a situation can occur,
-in which focus suddenly jumps to a completely different part of the app. When this happens, you can't continue in focusing
-after your async operations are done, because focus could be somewhere else and it could break the app focus flow.
-To prevent these situations, there is `safeFocus` utility.
-
-```ts
-const safeFocus = (focusWrapperElement: Reference<HTMLElement> | HTMLElement) => (component: IFocusable, options?: FocusOptions) => void
-```
-
-The whole mechanism works with the last `document.activeElement`, which during safe focusing needs to be inside the `focusWrapperElement`
-(or be the wrapper element) you define (in most of the cases it is your scene element). By this, you will prevent breaking the
-focus flow, and focusing (if it jumped outside of your scene during your async operation) will remain on the last activeElement outside of
-the scene, instead of going back after your operations were finished. This util uses currying so you can store `safeFocus` function in your
-scene and call it inside of your scene without the need of filling the wrapper element param each time.
-
-```ts
-class MyScene extends Component<Props> {
-    safeFocus = safeFocus(this.sceneWrapper);
-
-    async loadScene() {
-        const data = await fetchData();
-        this.renderGrid(data);
-        this.safeFocus(this.button);
-    }
-}
-```
-
-There is only one condition. The util will not work on your scene if something was not focused there before. It means that if
-calling `safeFocus` is your first focusing operation on the scene, you need to focus the scene wrapper or some element inside first.
-
-## focusFirstExisting
-Method to focus between multiple focusable components. The first existing (non-null) reference is focused.
-
-```ts
-const focusFirstExisting = (...toFocus: Reference<IFocusable>[]) => () => void;
-```
-
-If you need to enable `preventScroll` in element focus options, wrap your reference with `preventScrollOnFocus` function like this:
-```ts
-focusFirstExisting(this.navigation, preventScrollOnFocus(this.div))
-```
-
-## refocusAfterHashChange
-When the hash is changed, the browser automatically blurs the currently focused element and focuses body.
-This can be problematic when the overlay component is active (development tools, modals). Focus is lost and
-the app is uncontrollable. To prevent this, there is special util used in `hashchange` event handler. The mechanism behind is very easy,
-in the `hashchange` handler the `activeElement` is still the last focused element. This element is memoized and then asynchronously
-focused again. We just need to specify the wrapper element in which the focused element should be, otherwise it is
-outside of the component and not focused.
-
-```ts
-const refocusAfterHashChange = (focusWrapperOrReference: HTMLElement | Reference<HTMLElement>) => void;
-```
-
-## hasFocus
-Test if the element (or element in the reference) has the `activeElement` inside or optionally,
-if the element itself is the `activeElement`.
-
-```ts
-const hasFocus = (elementOrReference: HTMLElement | Reference<HTMLElement>, includeElementItself = false) => boolean;
-```
-
-## isFocused
-Test if the element (or element in the reference) is the `activeElement`.
-
-```ts
-const isFocused = (elementOrReference: HTMLElement | Reference<HTMLElement>) => boolean;
-```
+---
+id: README
+title: Focus
+hide_title: true
+sidebar_label: Focus
+---
+
+# Focus
+This package takes care of focus in SmartApps BIGscreen apps. It contains layout components and modules for handling focus candidates and focus limiting.
+
+## IFocusable
+IFocusable is an interface that should be implemented by anything that can be focused.
+```ts
+interface IFocusable {
+    focus(options?: FocusOptions): void,
+    hasDom?(element: HTMLElement): boolean,
+    hasFocus?(): boolean,
+}
+```
+- focus is the main function that is called when focusing component/element.
+- hasDom is optional optimization for components to help Layout components locate the currently
+focused child.
+- hasFocus is optional check if the component has focus inside or is itself focused.
+
+## Layout components
+- Vertical: Use it to create focus between elements vertically (up/down)
+- Horizontal: Use it to create focus between elements horizontally (left/right)
+- Matrix: Use it to create focus in a matrix (keyboards, special menus, etc.)
+
+## Vertical/Horizontal
+
+Both of these components share the same props;
+
+### Props
+- children: Children will be rendered as is.
+- focusableChildren: Array of references between which the focus moves.
+- domRef: Reference to a dom element that corresponds to closest dom wrapper.
+It will listen onKeyDown on this element.
+- onFocusChanged: Optional callback after focus has changed. It receives a reference
+to the focused element and its index. Ideal place to change other elements
+(e.g. header changing with focused movie)
+- onBeforeFocusChange: Optional callback just before focus change. It receives a reference
+to the focused element and its index. Ideal place for preparing for the change
+(e.g. moving the container to fit new element in the screen)
+- circular: makes focus circular, e.g. when pressing left at leftmost element focus will go to rightmost element
+- dir: Optional forceful setting of the component direction. Defaults to `'auto'` which follows
+the direction of the app.
+`'ltr'` always forces left-to-right layout,
+`'rtl'` always forces right-to-left.
+
+### Usage
+```jsx
+import { createRef, forwardRef } from '@24i/bigscreen-sdk/jsx';
+import { Vertical, Horizontal } from '@24i/bigscreen-sdk/focus';
+
+const Item = forwardRef(({ data }: Item, ref) => (
+    <div className="item" ref={ref} tabIndex={0}>
+        {/* item render */}
+    </div>
+));
+
+const Gallery = (data: { [key: string]: { title: string, items: Item[] } }) => {
+    const rootRef = createRef();
+    const categories = [];
+    return (
+        <div className="gallery" ref={rootRef}>
+            <Vertical
+                focusableChildren={categories}
+                domRef={rootRef}
+            >
+                {Object.keys(data).map((key) => {
+                    const category = data[key];
+                    const lineRef = createRef();
+                    categories.push(lineRef);
+                    const items = [];
+                    return (
+                        <div className="line" ref={lineRef}>
+                            <h3>{category.title}</h3>
+                            <Horizontal
+                                focusableChildren={items}
+                                domRef={lineRef}
+                            >
+                                {category.items.map((item) => {
+                                    const itemRef = createRef();
+                                    items.push(itemRef);
+                                    return (
+                                        <Item data={item} ref={itemRef} />
+                                    );
+                                })}
+                            </Horizontal>
+                        </div>
+                    );
+                })}
+            </Vertical>
+        </div>
+    );
+}
+```
+
+## Matrix
+This is a special kind of layout. It takes a matrix of focusable elements and provides navigation inside this matrix.
+It is useful for building keyboards, special layouts with atypically sized element, etc.
+
+### Props
+- children: Children will be rendered as is.
+- matrix: Array of arrays of references between which the focus moves.
+- domRef: Reference to a dom element that corresponds to closest dom wrapper. It will listen onKeyDown on this element.
+- onFocusChanged: Optional callback after focus has changed. It receives reference to focused element and its index. Ideal place to change other elements (e.g. header changing with focused movie)
+- onBeforeFocusChange: Optional callback just before focus change. It receives reference to focused element and its index. Ideal place for preparing for the change (e.g. moving the container to fit new element in the screen)
+- circular: makes focus circular, e.g. when pressing left at leftmost element focus will go to rightmost element, can be vertical, horizontal or all (vertical + horizontal), union with circularity direction is exported from focus
+
+### Usage
+Similar to Vertical/Horizontal. Define matrices like this:
+```ts
+// keyboard
+const matrix = [
+    [A, B, C, D, E],
+    [F, G, H, I, J],
+    [K, L, M, N, O],
+    [P, Q, R, S, T],
+    [U, V, W, X, Y],
+    [Z, SPACE, SPACE, BACKSPACE, CLEAR],
+];
+```
+```ts
+// Static grid with 2x3 HERO item
+const matrix = [
+    [H , H , H , A1],
+    [H , H , H , B1],
+    [C1, C2, C3, C4],
+];
+```
+
+## Prevent blur on long press
+When the user holds a navigation key, he usually scrolls to the boundary of the layout
+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 layout will propagate to another component
+or another layout. In some cases, we don't want this behavior and for those situations and
+to have better control above the layout navigation, there is a prop `preventBlurOnLongPress`.
+When the user scrolls to the boundary of the layout while holding a navigation key,
+he needs to release the key and press it again to propagate the event higher and focus
+another component or layout.
+
+## Limitations
+For the div to properly receive keydown events it needs to have set `tabIndex`. If you do not set `tabIndex` then it won't receive keydown events and those will not propagate to the Vertical/Horizontal component.
+
+`tabIndex` needs to be set only on those elements that are focused (`Item` in the example below). It does not need to be on the div that is referenced as `domRef` by Horizontal/Vertical.
+
+It can be set to 0.
+
+## Focus candidate
+During focusing, we are facing classic issues of keeping last focused element for refocusing back after our
+own focusing and logic for example in dialogs. This saved element is called **candidate**.
+This module brings set of functionalities for operating with candidates in one place instead of separate logic in each component.
+By this, something as "focus history" is stored in stack and shared among components in the application.
+
+### Functionality explanation
+
+Most basic type of usage is following:
+```
+some element in the app is focused and you need to open dialog
+  |<save last focused element (candidate) from document.activeElement>
+  |  dialog opening
+  |    focus dialog buttons and do something in the dialog...
+  |    // focusing something here is important
+  |    // because without it, candidate is not needed
+  |  dialog closing
+  |<focus candidate back in one candidate layer>
+continue your work with previously focused element as before
+```
+
+Remember one important thing again - candidate is **the last thing where your focus was**.
+You can also save candidates as currently focused elements (or components), but they would not be focused back right away,
+because you can't focus candidate which is currently focused element. Yet you can store it as next candidate for another layers.
+
+### What could be a candidate?
+Candidate is everything which can be focused or a reference to something which we can focus. This means that candidate could be anything which is compatible with `IFocusable` interface:
+```ts
+type ICandidate = {
+    isMounted?: boolean;
+} & IFocusable;
+
+type FocusCandidate = ICandidate | Reference<ICandidate>;
+```
+Most common candidates:
+- HTMLElement
+- Component (prop `isMounted` refers to availability of a component candidate)
+- Reference to HTMLElement
+- Reference to Component
+
+### Functions
+
+There are four main methods for working with focus candidate:
+
+```ts
+setActiveElementAsFocusCandidate()
+```
+This is the main method, which saves **document.activeElement** as a new candidate.
+This method should be used every time you need to save the last focused element from activeElement.
+In most cases, saving activeElement as a focus candidate is enough and it is the most common way how to save candidates.
+
+```ts
+setFocusCandidate(candidate: FocusCandidate)
+```
+Same as the first method, but now you need to specify manually, which candidate you want to save. Remember, a candidate needs to be always from previously focused content.
+
+```ts
+setNextFocusCandidate(candidate: FocusCandidate)
+```
+Next candidate is candidate for future layers. Candidate in previous methods was last focused content,
+but the next candidate is currently focused content. In short, the next candidate is remembered and it will be skipped when focusing the candidate back. Adding another candidate (or another next candidate) clears the current
+next candidate and now it is available.
+
+This functionality is used for example when your focusable content could
+change completely during its lifetime, so you need to set your whole component as the next candidate because your currently focused element on it, saved as another candidate, would not exist after your content changes.
+This is also achievable with references to your dynamic focusable elements.
+
+### Example
+
+Opening TechnicalInfo component
+```
+focus and logic in EPG
+    opening technical info component
+    <set candidate1 as epg cell>
+    <set next candidate2 as tech. info component>
+    focus technical info scroller, data are loading
+    data are loaded, re-rendering scroller element
+    closing tech. info
+    <focus candidate2 - skipped, because its current next candidate>
+    <focus candidate1 - epg cell>
+focus is back in EPG
+```
+And now when the asynchronous data are loaded and a modal pops-up
+```
+focus and logic in EPG
+    opening technical info component
+    <set candidate1 as epg cell>
+    <set next candidate2 as tech. info component>
+    focus technical info scroller, data are loading
+        modal pops up
+        <set candidate3 as tech. info scroller element>
+        focus dialog buttons
+    data are loaded, re-rendering scroller element 
+        modal closed
+        <focus candidate3 - can't be focused, its different now (not available), skipped>
+        <focus candidate2 - focus method on tech.info component with proper scroller element>
+    closing tech. info
+    <focus candidate1 - epg cell>
+focus is back in EPG
+```
+This can be used also in cooperation with `setActiveElementAsFocusCandidate` (or `setFocusCandidate`) when you need to save the previously focused element and then set manually the currently focused component or element as the next candidate.
+
+```ts
+focusCandidate(options?: FocusOptions)
+```
+This is the last method that closes the candidate circle. By calling `focusCandidate` you are focusing the last available candidate in the candidate stack. There is some logic behind candidate popping and it needs to fulfil these statements:
+
+- the last candidate can't be the current next candidate because it would focus current content again
+- candidate needs to exist and be available and it can't be the last focused element
+- (testing after candidate focus happened) newly focused candidate needs to be fully visible and can't be the same as previously focused one
+
+If none of those statements is fulfilled, another last candidate from the stack is taken. If there are no candidates available, candidate fallback is focused.
+
+### Candidate availability
+The candidate needs to be fully visible (not `display: none` or `visibility: hidden`), the same applies to its parents and it needs to be inserted in the attached DOM branch.
+
+### Candidate fallback
+```ts
+setCandidateFallback(candidate: FocusCandidate);
+```
+Candidate fallback is basically another focus candidate which will be focused when there are no other candidates in the stack. In most scenarios, it is the current scene or the Router component.
+
+### Other methods
+
+- getCandidateFallback — returns fallback
+- getLastCandidate — returns last candidate from candidate stack without any statements as in focusCandidate method
+- getCandidateStack — returns full candidate stack
+- clearCandidateStack — clears whole candidate stack and next candidate
+
+## safeFocus
+If you are working with asynchronous operations such as API calls, promises or timeouts a situation can occur,
+in which focus suddenly jumps to a completely different part of the app. When this happens, you can't continue in focusing
+after your async operations are done, because focus could be somewhere else and it could break the app focus flow.
+To prevent these situations, there is `safeFocus` utility.
+
+```ts
+const safeFocus = (focusWrapperElement: Reference<HTMLElement> | HTMLElement) => (component: IFocusable, options?: FocusOptions) => void
+```
+
+The whole mechanism works with the last `document.activeElement`, which during safe focusing needs to be inside the `focusWrapperElement`
+(or be the wrapper element) you define (in most of the cases it is your scene element). By this, you will prevent breaking the
+focus flow, and focusing (if it jumped outside of your scene during your async operation) will remain on the last activeElement outside of
+the scene, instead of going back after your operations were finished. This util uses currying so you can store `safeFocus` function in your
+scene and call it inside of your scene without the need of filling the wrapper element param each time.
+
+```ts
+class MyScene extends Component<Props> {
+    safeFocus = safeFocus(this.sceneWrapper);
+
+    async loadScene() {
+        const data = await fetchData();
+        this.renderGrid(data);
+        this.safeFocus(this.button);
+    }
+}
+```
+
+There is only one condition. The util will not work on your scene if something was not focused there before. It means that if
+calling `safeFocus` is your first focusing operation on the scene, you need to focus the scene wrapper or some element inside first.
+
+## focusFirstExisting
+Method to focus between multiple focusable components. The first existing (non-null) reference is focused.
+
+```ts
+const focusFirstExisting = (...toFocus: Reference<IFocusable>[]) => () => void;
+```
+
+If you need to enable `preventScroll` in element focus options, wrap your reference with `preventScrollOnFocus` function like this:
+```ts
+focusFirstExisting(this.navigation, preventScrollOnFocus(this.div))
+```
+
+## refocusAfterHashChange
+When the hash is changed, the browser automatically blurs the currently focused element and focuses body.
+This can be problematic when the overlay component is active (development tools, modals). Focus is lost and
+the app is uncontrollable. To prevent this, there is special util used in `hashchange` event handler. The mechanism behind is very easy,
+in the `hashchange` handler the `activeElement` is still the last focused element. This element is memoized and then asynchronously
+focused again. We just need to specify the wrapper element in which the focused element should be, otherwise it is
+outside of the component and not focused.
+
+```ts
+const refocusAfterHashChange = (focusWrapperOrReference: HTMLElement | Reference<HTMLElement>) => void;
+```
+
+## hasFocus
+Test if the element (or element in the reference) has the `activeElement` inside or optionally,
+if the element itself is the `activeElement`.
+
+```ts
+const hasFocus = (elementOrReference: HTMLElement | Reference<HTMLElement>, includeElementItself = false) => boolean;
+```
+
+## isFocused
+Test if the element (or element in the reference) is the `activeElement`.
+
+```ts
+const isFocused = (elementOrReference: HTMLElement | Reference<HTMLElement>) => boolean;
+```