Update README

Author: usulpro

README.md

@@ -1,72 +1,252 @@
 # Storybook Addon Development Kit
 
-Keeps in sync addon's data through the channel
+Simplifies the addons creation. Keeps in sync addon's data through the channel. Provides intelligent blocks for creating addon UI. Offer simple API for registering addons and creating decorators. It's a base to quickly build your custom brand new awesome addon
+
+## Features
+
+- Hides under the hood all the complex issues of communication through the channel and data synchronization while switching stories.
+- Connects your addon components to your addon store via HOCs and updates it only when data changes
+- Divides addon store data to global and local. Tracks story surfing in order to switch appropriate local data both on manager and preview sides simultaneously
+- Keeps immutable init data and overridable data which you mutate via actions
+- Provides redux like approach to deal with your addon store via selectors and actions (but don't worry, the default action just simply override your data)
+- Allows to connect any amount of pannels, buttons and any other addon types to the single addon store
+- Offers UI container which automatically reflects the aspect ratio of addon panel. Extremely useful to create addon UI responsive for vertical and horizontal panel positions
+
+## Usage
+
+```shell
+npm i --save @storybook/addon-devkit
+```
+
+```js
+import {
+  register,
+  createDecorator,
+  setParameters,
+  setConfig,
+  Layout,
+  Block,
+} from '@storybook/addon-devkit'
+
+```
 
 ## API
 
-### Addons Panel (Manager)
+### Register manager side Addon panel
+
+HOC to register addon UI and connect it to the addon store.
+
+```js
+// in your addon `register.js`
+import { register } from '@storybook/addon-devkit'
+
+register(
+  {
+    ...selectors,
+  },
+  ({ global, local }) => ({
+    ...globalActions,
+    ...localActions,
+  })
+)(AddonPanelUI);
+
+
+```
+
+where `selectors` is an object on functions like:
+
+```js
+{
+  deepData: store => store.path.to.deep.store.data,
+}
+
+```
+
+and `actions` could be "global" and "local". Global actions affects on the global part of store, while local only on the data related to the current story.
+
+```js
+
+({ global, local }) => ({
+    // action to manipulate with common data
+    increase: global(store => ({
+      ...store,
+      index: store.index + 1,
+    })),
+    // action to manipulate with current story data
+    // usage: setBackground('#ff66cc')
+    setBackground: local((store, color) => ({
+      ...store,
+      backgroundColor: color,
+    })),
+    // action to override data
+    // usage: update({...newData})
+    update: global(),
+  })
+
+```
+
+AddonPanelUI - is your component which appears on addon panel when you select appropriate tab
+> Note: the HOC automatically track the `active` state of addon and shows it only when it's necessary
+
+register HOC will pass the follow props to the `AddonPanelUI` component:
 
-**register(PanelComponent)**
+```js
+<AddonPanelUI
+  {...actions} // generated actions
+  {...selectors} // selected pieces of store
+  api={api} // storybook API object
+  active={active} // you don't need to do anything with it
+  store={store} // entire store. prefer to use selectors
+  kind={kind} // current story kind
+  story={story} // current story
+  ADDON_ID={ADDON_ID}
+  PANEL_ID={PANEL_ID}
+  PANEL_Title={PANEL_Title} // Title on the addon panel
+  rect={rect} // dimensions of panel area
+/>
+
+```
+
+As soon as you change the store via actions both the `AddonPanelUI` and `storyDecorator` will be re-rendered with the new data.
 
-HOC that adds your PanelComponent to the addons panel. It will register it and provides follow props:
+Same if the data will come from the story - it will be updated
 
-- **kind**, a selected story kind name
-- **story**, a selected story name
-- **api**, manager API
-- **data**, current channel data (associated with selected story)
-- **setData**, callback to set data
-- **rect**, geometric dimensions of the addon area,
-- **Layout**, Helper Component with `display: flex` to make addon's markup to fit in portrait or landscape mode by switching `flex-direction`. Could be used alone or together with Blocks.
-- **Block**, Helper Block to use inside Layout and provides flex items behavior in portrait and landscape mode
+After initialization HOC will wait for init data from story and only after it will render UI
 
->see how works Layout and Blocks in the Live Demo
 
-example:
+### Create stories side decorator
+
+HOC to create decorator and connect it to the addon store.
 
 ```js
-// your addon register.js
+// in your addon `decorator.js`
+import { createDecorator } from '@storybook/addon-devkit'
+
+export const withMyAddon = createDecorator({
+    ...selectors,
+  },
+  ({ global, local }) => ({
+    ...globalActions,
+    ...localActions,
+  })
+)(DecoratorUI, { isGlobal });
+
+```
+
+so then you can use your decorator this way:
+
+```js
+// stories.js
 
 import React from 'react';
-import { register } from '../dist/register';
+import { storiesOf, addDecorator, addParameters } from '@storybook/react';
+import { withMyAddon, myAddonParams } from 'my-addon';
+
+// add decorator globally
+addDecorator(withMyAddon({ ...initData }))
+addParameters(myAddonParams({ ...globalParams }))
+
+storiesOf('My UI Kit', module)
+  // ...or add decorator locally
+  .addDecorator(withMyAddon({ ...initData }))
+  .add(
+    'Awesome',
+    () => <Button>Make Awesome</Button>,
+    myAddonParams({ ...localParams })
+  )
+
+```
+
+`DecoratorUI` could look like this:
+
+```js
 
-const AddonPanel = ({ api, data, setData, kind, story }) => (
+const DecoratorUI = ({ context, getStory, selectedData }) => (
   <div>
-    <p>kind: {kind}</p>
-    <p>story: {story}</p>
-    <p>data ({JSON.stringify(data)})</p>
-    <button onClick={() => setData({ foo: 'bar' })}>setData</button>
+    <h1>Title: {selectedData}</h1>
+    {getStory(context)}
   </div>
 );
-
-register(AddonPanel);
 ```
 
-Then users can add your addon to Storybook like this:
+When `isGlobal = true` decorator will consider all passing data as global
+
+>Note: addon parameters will be merged with init data and available both for decorator and panel selectors
+
+
+### Pass parameters to addon
+
+Creates functions for passing parameters to your addon
+See usage above
 
 ```js
-// user's .storybook/addons.js
+import { setParameters } from '@storybook/addon-devkit'
+
+export const myAddonParams = setParameters()
 
-import 'your-addon/register';
 ```
 
-## Develop
+### Addon config
+
+In order to create addon you need to specify some unique parameters like event name, addon title, parameters key and others. They should be same on manager and preview sides. If you don't specify them addon-devkit will use the default ones.
+To specify your own use `setConfig`:
 
-scripts:
+```js
+import { setConfig } from '@storybook/addon-devkit';
+
+setConfig({
+  addId: 'dev_adk',
+  panelTitle: 'ADK DEV'
+});
+
+```
+You should run it **before** using `register`, `setParameters` and `createDecorator`
 
-`yarn start` - compiles everything, starts Storybook and watches for changes
+>Note: don't remember to use setConfig both in on manager and preview sides with the same parameters
 
-`yarn prepare` - compiles `src` to the `dist` folder by babel
 
-`yarn prepare-dev` - compiles `dev` to the `dev-dist` folder by babel
+### Addon panel UI components
 
+Components to organize UI in a row when panel in bottom position and in column when it on the right side
 
-folders:
+```js
+import { Layout, Block, register } from '@storybook/addon-devkit';
+import { styled } from '@storybook/theming';
+import './config'
+
+const LayoutBlock = styled(Layout)`
+  ...styles
+`
+
+const AddonBlock = styled(Block)`
+  ...styles
+`
+
+const AddonPanel = () => (
+  <LayoutBlock>
+    <AddonBlock size={200}>
+      {UI1}
+    </AddonBlock>
+    <AddonBlock>
+      {UI2}
+    </AddonBlock>
+    <AddonBlock>
+      {UI3}
+    </AddonBlock>
+  </LayoutBlock>
+)
+
+register()(AddonPanel)
+
+```
 
-`src` - source of the addon
+<Layout> has `display: flex` with `flex-direction: row` when bottom and `flex-direction: column` in right side.
 
-`dev` - addon usage
+You can specify the size of <Block>. In case of horizontal layout it will be the width, in case of vertical - height of element.
 
+Otherwise it will have `flex-grow: 1`
 
-how to develop:
+## Credits
 
-`yarn start` and edit files in `src` folder. To test API see `dev` folder.
+<div align="left" style="height: 16px;">Created with ❤︎ to <b>React</b> and <b>Storybook</b> by <a href="https://twitter.com/UsulPro">@usulpro</a>  [<a href="https://github.com/react-theming">React Theming</a>]
+</div>

dev/withAdk.js

@@ -1,15 +1,15 @@
 import React from 'react';
 import { createDecorator, setParameters } from '../src/decorator';
-import './config'
+import './config';
 
-const DecoratorUI = ({ context, getStory, data, parameters, theme }) => (
+const DecoratorUI = ({ context, getStory, theme }) => (
   <div>
     Theme: {theme} <br />
     {getStory(context)}
   </div>
 );
 
 export const withAdk = createDecorator({
-  theme: store => store.themes[store.currentTheme]
-})(DecoratorUI, {isGlobal: true});
-export const adkParams = setParameters()
+  theme: store => store.themes[store.currentTheme],
+})(DecoratorUI, { isGlobal: true });
+export const adkParams = setParameters();

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storybook/addon-devkit",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0",
   "description": "Storybook Addon Development Kit",
   "author": {
     "name": "Oleg Proskurin",

src/index.js

@@ -1,3 +1,4 @@
+export * from './config';
 export * from './register';
 export * from './decorator';
 export * from './Layout';

src/register.js

@@ -94,7 +94,7 @@ class PanelHOC extends React.Component {
                   {...this.props.selectors}
                   api={api}
                   active={active}
-                  data={data}
+                  store={data}
                   setData={setData}
                   kind={kind}
                   story={story}