feat(FEC-8696): allow adding/changing discrete components in UI (#399)

allow adding/changing discrete components in UI
related PRs:
kaltura/playkit-js#387
kaltura/kaltura-player-js#264

.flowconfig

@@ -2,7 +2,7 @@
 .*/node_modules
 [include]
 [libs]
-node_modules/playkit-js/flow-typed/
+node_modules/@playkit-js/playkit-js/flow-typed/
 [options]
 unsafe.enable_getters_and_setters=true
 esproposal.decorators=ignore

docs/components/fullscreen/README.md

@@ -12,11 +12,11 @@ Component that toggles fullscreen state.
 
 ```html
 //@flow
-import { h, FullscreenControl } from 'playkit-js-ui';
+import { h, Fullscreen } from 'playkit-js-ui';
 
 export default function customUIPreset(props: any) {
   return (
-    <FullscreenControl player={props.player} />
+    <Fullscreen player={props.player} />
   )
 }
 ```

docs/components/seekbar/README.md

@@ -14,15 +14,15 @@ A component that changes the seekbar state.
 
 ```html
 //@flow
-import { h, SeekBarControl } from 'playkit-js-ui';
+import { h, SeekBar } from 'playkit-js-ui';
 
 export default function customUIPreset(props: any) {
   return (
     // show both frame preview and time bubble
-    <SeekBarControl showFramePreview showTimeBubble player={props.player} />
+    <SeekBar showFramePreview showTimeBubble player={props.player} />
 
     // show only time bubble
-    <SeekBarControl showTimeBubble player={props.player} />
+    <SeekBar showTimeBubble player={props.player} />
   )
 }
 ```

docs/configuration.md

@@ -14,12 +14,13 @@ var uiManager = new playkit.ui.UIManager(player, config);
 ```js
 {
   targetId: string,
-  debugActions: boolean, // optional
-  forceTouchUI: boolean, // optional
+  debugActions?: boolean, // optional
+  forceTouchUI?: boolean, // optional
   log?: UILogConfigObject, // optional
-  components: Object, // optional
+  components?: Object, // optional
+  uiComponents: Array<Object>, //optional
   translations: Object, // optional
-  locale: Object // optional
+  locale: Object // optional  
 }
 ```
 
@@ -248,3 +249,27 @@ var uiManager = new playkit.ui.UIManager(player, config);
 > > > ##### Default: `false`
 > > >
 > > > ##### Description: Gives the ability to choose an in-browser fullscreen experience on iOS devices which will replace the native fullscreen of the AV player.
+
+##
+
+> ### config.uiComponents
+>
+> ##### Type: `Object`
+>
+> ```
+>  Array<{
+>  label: string,
+>  presets: Array<string>,
+>  container: string,
+>  get: Function 
+>  props?: {} 
+>  beforeComponent?: string,
+>  afterComponent?: string,
+>  replaceComponent?: string
+>  }>
+>  ```
+>
+>
+> ##### Description: Defines ui components to be injected into the player ui.
+>
+> See guide [ui-components](./ui-components.md)

docs/create-new-component.md → docs/create-ui-component.md

@@ -1,20 +1,54 @@
-## Create New Component
+## Create UI Component
 
-### Dumb component
+### Dumb component 
 
-This component will just be a div wrapper with a className
+> Use this technique for simple use-cases when you don't need to manage state or intercept mounting/destroying of the component.
+
+This component will just be a div wrapper with a className.
+
+```javascript
+const h = KalturaPlayer.ui.h;
+
+const DumpComponent = h('div', {className: 'dumb-component'});
+
+export default DumpComponent;
+```
+
+If you want to use JSX follow this [guide](./custom-ui-preset.md#using-jsx), and use following JSX syntax:
+
+```javascript
+const h = KalturaPlayer.ui.h;
+
+const DumpComponent = <div className="dumb-component"></div>;
+
+export default DumpComponent;
+```
+
+## Component with state and life-cycle interception
+
+> Use this technique when the component need to manage state, register to event handlers or perform async operations.
+
+This component is using the player bundled PReact to manage state and intercept mount events.
 
 ```javascript
 const h = KalturaPlayer.ui.h;
 const BaseComponent = KalturaPlayer.ui.Components.BaseComponent;
 
-class DumbComponent extends Component {
+class SampleComponent extends BaseComponent {
+  componentDidMount() {
+    // register to event handlers and other stuff here
+  }
+
+  componentWillUnount() {
+    // free resources here
+  }
+
   render(props) {
     return h('div', {className: 'dumb-component'}, props.children);
   }
 }
 
-export default DumbComponent;
+export default SampleComponent;
 ```
 
 If you want to use JSX follow this [guide](./custom-ui-preset.md#using-jsx), and use following JSX syntax:
@@ -23,7 +57,7 @@ If you want to use JSX follow this [guide](./custom-ui-preset.md#using-jsx), and
 const h = KalturaPlayer.ui.h;
 const BaseComponent = KalturaPlayer.ui.Components.BaseComponent;
 
-class DumbComponent extends Component {
+class DumbComponent extends BaseComponent {
   render(props) {
     return <div className="dumb-component">{props.children}</div>;
   }
@@ -47,6 +81,22 @@ Or again, if using JSX:
 </DumbComponent>
 ```
 
+## (P)React component
+Any component that is added to the player is exposed to internal API of the player.
+
+This shouldn't bother you unless you are trying to add (P)React components. If this is the case you have two options:
+1. The player exposes the bundled PReact instance it is using, use that one instead of your own. This might work fine for simple use-cases.
+2. In more advanced use-cases you might want to bundle your own version of PReact or in cases that you are using React, you must isolate your component from the player PReact tree:
+
+   [ ] create new component that is using (extending) the PReact instance exposed by the player `KalturaPlayer.ui.preact.Component`
+
+   [ ] inject the new component to the player 
+
+   [ ] use `shouldComponentUpdate` to always prevent updating
+
+   [ ] render a div and append render your PReact component into that div on `ComponentDidMount`  
+
+
 ### Redux-Store Connected Component
 
 This component will log all player state changes (based on the redux store) and print them as a log.

docs/custom-ui-preset.md

@@ -29,7 +29,7 @@ A preset is a simple function that returns a tree that defines the compoentns st
 
 For example- Let's say that we want our fullscreen UI to have only the bottom bar with the fullscreen control. nothing else.
 
-this is a UI preset that will define the look of fullscreen state, which uses the built-in components `BottomBar` and `FullscreenControl`
+this is a UI preset that will define the look of fullscreen state, which uses the built-in components `BottomBar` and `Fullscreen`
 
 ```javascript
 //fullscreen-preset.js
@@ -42,7 +42,7 @@ const fullscreenUI = function(props){
     h(
       components.BottomBar,
       h(
-        components.FullscreenControl, { player: props.player },
+        components.Fullscreen, { player: props.player },
         { className: "playkit-left-controls" }
       )
     )
@@ -85,7 +85,7 @@ const fullscreenUI = function(props) {
   return (
     <div className="playback-gui-wrapper" style="height: 100%">
       <BottomBar>
-        <FullscreenControl player={props.player} />
+        <Fullscreen player={props.player} />
       </BottomBar>
     </div>
   );
@@ -101,13 +101,13 @@ const fullscreenUI = function(props) {
 ```javascript
 //fullscreen-preset.js
 //@flow
-import { h, BottomBar, FullscreenControl  } from 'playkit-js-ui';
+import { h, BottomBar, Fullscreen  } from 'playkit-js-ui';
 
 export default function fullscreenUI(props: any) {
 return (
 <div className='playback-gui-wrapper' style='height: 100%'>
 <BottomBar>
-<FullscreenControl player={props.player} />
+<Fullscreen player={props.player} />
 </BottomBar>
 </div>
 )
@@ -176,5 +176,5 @@ The UI Manager has three pre-defined conditions:
 ## Using custom components
 Presets can be created by using the player default library components, but you can also create and use your own components to define the layout.
 
-See example on how to create and use your own compoentns [here](create-new-component.md)
+See example on how to create and use your own components [here](create-ui-component.md)
 ```

docs/guides.md

@@ -1,5 +1,6 @@
 # Guides
 
-* [Create New Component](./create-new-component.md)
+* [Create UI Component](./create-ui-component.md)
 * [Customizing the Player CSS](./css-classes-override.md)
 * [Custom UI Preset](./custom-ui-preset.md)
+* [Inject UI Component](./ui-components.md)