Add information about shared component API

README.md

@@ -18,6 +18,7 @@
 * [Internationalization Guidelines](i18n.md)
 * [UI Patterns](ui/patterns.md)
 * [Report data API](ui/report_data_api.md)
+* [Shared react component API](ui/register_react_component.md)
 * [Service UI Skinning](/service_ui/skinning.md)
 * [Running Changelog for Sprints](/community/changelog/)
 * [Roadmap and Sprints](https://github.com/ManageIQ/manageiq/milestones)

ui/register_react_component.md

@@ -0,0 +1,98 @@
+### Register react component
+In ManageIq project there is a way of sharing components, getting their state and control their flow by something which is called ManageIq component.
+
+This registry and usage consists of three steps, define blueprint which holds the react component with it's props. Then you will define it inside shared components (use blueprint created in step 1). And when someone decides to use such component he will call function newInstance with custom props and element to which such component is bound to.
+
+This way using such component is abstract for user, he doesn't know if such component was written in pure JS, React, Angular or whatever.
+
+#### 1. Define react component
+This is your first step of creating shared abstract component. You may use our custom function which fits react, should you choose angular, Vue.js or whatever you'll have to write your own funcion.
+
+When using react blueprint function, just wrap your component (or HTML) with `addReact` function and as argument use callback which will be called with props. These props will be passed when new isntance of this component is created.
+
+```JSX
+import React from 'react';
+import addReact from 'helpers';
+import { YourComponent } from 'your-components/custom-component';
+
+addReact('YourComponentName', props => <YourComponent {...props} />);
+```
+
+#### 2. New instance
+When you want to create new instance of recently created component just call newInstance function with these arguments
+* name - name of component you wish to use.
+* props - object with props which will be mapped to your components (used when creating blueprint)
+* element - DOM element where this new instance of component should be rendered.
+```JS
+import newInstance from 'registry';
+
+const props = {};
+const element = document.getElementById('element-id');
+newInstance('YourComponentName', props, element);
+```
+
+### Shared component API
+Abstract shared components has API controlling active components, this way you can define and create new component, later you can access to all active components on screen and use it's shared interface to interact with it.
+
+#### Define
+When you want to define new component to be used by someone call define function with name of such component and it's blueprint.
+```JS
+import define from 'registry';
+
+define('YourComponentName', componentBlueprint);
+```
+
+#### Get definition
+To fetch definition of component you created you can call specific function. You will get name of such component and it's blueprint. With such blueprint you can call functions to update, create or remove it.
+```JS
+import getDefinition from 'registry';
+
+getDefinition('YourComponentName');
+```
+
+#### New instance
+To create new instance and mount it to DOM element call function `newInstance`. This function not only creates new instance it also gives you object over which you can update it's pros, update it or destroy it from component's drawer. Inside this object you will also find comeponent's instance ID and should the component chooses it's interact property for side channel communication.
+
+When creating new instance you have option to pass multiple parameters:
+* name - component's name under which component was defined
+* props - default props to component
+* element - DOM element under which this component should be rendered (optional)
+```JS
+import newInstance from 'registry';
+
+newInstance('YourComponentName', {}, element);
+```
+
+#### Get instance
+To receive component's instance from registery you can call function `getInstance`. You will get full information about this instance, ways to interact with it and it's name and ID.
+```JS
+import getInstance from 'registry';
+
+getInstance('YourComponentName', componentID);
+```
+
+#### Is defined
+Check if component with some name is defined in drawer. Great for checking if component's name is available.
+```JS
+import isDefined from 'registry';
+
+isDefined('YourComponentName');
+```
+
+### Component instance API
+When you create new instnace or search for instance of component you will receive object over which you can interact with this instance and observe it's properties.
+
+#### ID
+Instance's ID under which it's created.
+
+#### interact
+Should the component chooses it can supply object over which it's possible side channel communication.
+
+#### props
+Instance's props object containing public properties.
+
+#### update
+This function helps you to update component's public props. You can add new prop or update existing prop.
+
+#### destroy
+To destroy instance and remove it from DOM (no point of return) simply call this function.