Merge 72d130f into 9d102f6

CONTRIBUTING.md

@@ -50,6 +50,7 @@ Please note that if you use `npm run test-dev` as above, Karma will use port `80
 ### Before submitting a PR...
 
 Thanks for taking the time to help us make Radium even better! Before you go ahead and submit a PR, make sure that you have done the following:
+
 - Run the tests (you did add tests, right?) using `npm run test-dev`.
 - Run lint and flow using `npm run lint`
 
@@ -135,3 +136,43 @@ available at [http://contributor-covenant.org/version/1/4][version]
 
 [homepage]: http://contributor-covenant.org
 [version]: http://contributor-covenant.org/version/1/4/
+[version]: http://contributor-covenant.org/version/1/4/
+
+### Architecture
+
+#### Enhancer HOC
+
+- Component is wrapped by `Radium` which runs it through `enhancer.js::enhanceWithRadium()`.
+- A composed component is created
+  - ES modules - `Reflect` is used to create enhanced component from prototype of original component
+  - Stateless components - a simple wrapper component is created which calls the original component
+  - Everything else - enhanced component is created by shallow copying the original component
+- An enhanced component is created
+  - static `_isRadiumEnhanced = true` property is added
+  - `_radiumStyleState = {}` is added to component state
+  - In render, `resolveStyles.js:resolveStyles` is called on the original rendered elements before they are returned. (see resolveStyles section)
+  - in componentDidUpdate, unused state keys are removed if necessary
+  - in componentWillUnmount, mouse and media query listeners are removed
+
+#### Style Resolver `resolveStyles.js:resolveStyles`
+
+- Called on the original rendered elements before they are returned. It iterates over the elements and children, rewriting props to add event handlers required to capture user interactions (e.g. mouse over). It also replaces the style prop because it adds in the various interaction styles (e.g. :hover).
+- extraStateKeyMap is created by determining which state fields are no longer needed [?]
+- If the rendered elements are an array, they are recursively mapped over with resolveStyles
+- New children are resolved
+  - Recurse into children and call `resolveStyles` on each one
+- New props are resolved
+  - Recurse through props and call `resolveStyles` on any React components in props. Otherwise return props as-is
+- Plugins are run ONLY on simple ReactDOM elements that have a style prop
+  - plugins are called with the component, its props and a bunch of helper functions
+  - if the props were changed/added by any plugin, then return those
+  - see plugins section for more
+- If anything changed, clone the element and return that. Otherwise just return the element.
+
+#### Plugins
+
+##### merge-styles-array-plugin
+
+If the component styles are an array, it deeply merges them. Otherwise, it returns them unmodified.
+
+[work in progress]