Doc updates

Author: dmohs

CHANGELOG.md

@@ -2,5 +2,10 @@
 
 - Hot reloading now replaces methods in a React component's prototype instead of saving and
   restoring. This is safer and doesn't cause `component-did-mount` to fire.
-- A component now implements the IFn protocol, allowing method calls, e.g.,
+- Components now implement the `IFn` protocol, allowing method calls, e.g.,
   `(react/call instance :do-stuff)`, to be shortened to, e.g., `(instance :do-stuff)`.
+- State and props are duplicated as plain JavaScript objects to make them easy to view in React's
+  developer tools for Chrome.
+- Including `:trace? true` when creating a class will cause the component to log every method call.
+- `create-element` will now accept a plain JavaScript React element.
+- Safer internal variable handling to make sure things don't break with advanced optimizations.

README.md

@@ -4,22 +4,20 @@ A ClojureScript wrapper for React.
 
 There are a number of React-like libraries for ClojureScript (e.g., Om, Reagent, Rum). Many use React under the covers.
 
-By contrast, this library simply exposes an interface to React in a ClojureScript-friendly way. It is for developers who, like myself, want to use React directly from a ClojureScript application.
+By contrast, this library simply exposes an interface to React in a ClojureScript-friendly way. It is for developers who, like myself, want to use React directly from ClojureScript.
+
+## Goodies
+
+- **Built-in support for hot-reloading**. If you use, for example, Figwheel to hot-reload files on change, React components created with the `defc` macro will be patched automatically.
+- **Method tracing**. Including `:trace? true` in the class definition map will cause every method call to emit a message to the console. This also attempts to break infinite loops by setting a ceiling on the number of traces in a short time period.
+- **React Developer Tools support**. Copies component state and props into plain JavaScript in non-optimized compilation modes so it is easier to use React Developer Tools (Chrome extension) to inspect components.
 
 ### Add dependency:
 
 ```clj
 [dmohs/react "0.2.12"]
 ```
 
-### Quickstart Template:
-
-```bash
-lein new dmohs.cljs-react my-project
-```
-
-See [dmohs.cljs-react template](https://github.com/dmohs/cljs-react-template) for usage.
-
 ## Top-Level API
 
 The Top-Level API closely follows React's Top-Level API:
@@ -49,7 +47,7 @@ https://facebook.github.io/react/docs/top-level-api.html
       (.focus (@refs "clickable-div")))}))
 ```
 
-or, using the `defc` macro:
+or, using the `defc` macro (preferred and supports hot-reloading):
 
 ```clj
 (react/defc MyComponent
@@ -58,20 +56,31 @@ or, using the `defc` macro:
    ...})
 ```
 
-The `render` method can return either an element or a vector (as in the above example).
+The `render` method can return either an element or a vector (as in the above example). Pass `:trace? true` for method tracing:
+
+```clj
+(react/defc MyComponent
+  {:trace? true
+   :get-initial-state ...
+   :render ...
+   ...})
+```
 
 ### React.createElement
 
 ```clj
-(def component (react/create-element MyComponent {:initial-click-count 15}))
+(react/defc MyComponent ...)
+(def PlainReactComponent (js/React.createClass ...))
 (react/create-element
  :div {:className "alert" :style {:backgroundColor "red"}}
- component)
+ (react/create-element MyComponent {:foo "foo"})
+ (react/create-element PlainReactComponent {:bar "bar"}))
 
 ;; Vector syntax
 (react/create-element [:div {:className "alert"}
                        "Child 1" "Child 2"
-                       [MyComponent {:initial-click-count 15}]])
+                       [MyComponent {:initial-click-count 15}]
+                       [PlainReactComponent {:initial-click-count 21}]])
 ```
 
 ### React.cloneElement
@@ -93,11 +102,9 @@ The `render` method can return either an element or a vector (as in the above ex
 ### ReactDOM.render
 
 ```clj
-(react/render element container callback hot-reload?)
+(react/render element container callback)
 ```
 
-If `hot-reload?` is true, component state will be preserved before unmounting and loaded into the newly-rendered tree. This makes Figwheel usage quite easy. I usually pass `goog.DEBUG` as this parameter so it is automatically turned off for minimized/production builds.
-
 ### ReactDOM.unmountComponentAtNode
 
 ```clj
@@ -107,7 +114,7 @@ If `hot-reload?` is true, component state will be preserved before unmounting an
 ### ReactDOM.findDOMNode
 
 ```clj
-(create/find-dom-node element)
+(react/find-dom-node element)
 ```
 
 ## Component Specifications
@@ -116,16 +123,18 @@ Component specifications closely follow React's Component Specifications:
 
 https://facebook.github.io/react/docs/component-specs.html
 
-React methods are defined using Clojure naming conventions (`:get-initial-state` corresponds to `getInitialState`). Additional methods become part of the object, so `:add-foo` can be called like so:
+React methods are defined using Clojure naming conventions (`:get-initial-state` corresponds to `getInitialState`). Additional methods become part of the object (as in React), so `:add-foo` can be called like so:
 ```clj
 (react/call :add-foo this "argument 1" "argument 2")
 ;; or
 (react/call :add-foo (@refs "some-child") "argument 1" "argument 2")
 ```
 
-The special case of calling `this` can be shortened to:
+Additionally, components implement `IFn`, so the above calls can be shortened to:
 ```clj
-(react/call-self :add-foo "argument 1" ...)
+(this :add-foo "argument 1" "argument 2")
+;; and
+((@refs "some-child") :add-foo "argument 1" "argument 2")
 ```
 
 Methods are passed a map with the appropriate keys defined:
@@ -144,12 +153,18 @@ Methods are passed a map with the appropriate keys defined:
  }
 ```
 
-1. This is used when you would pass a callback to `setState`, e.g., `(after-update #(.focus (react/find-dom-node this)))`.
-2. The `refs` atom allows accessing `this.refs` as a map (e.g., `(.focus (@refs "my-text-box"))`).
-3. Convenience atom for local variables. Instead of, e.g., `(set! (.-myTimer this) (js/setTimeout ...))`, you can do `(swap! locals assoc :my-timer (js/setTimeout ...))`.
+1. This is used when you would pass a callback to `setState`, e.g.,
+
+   `(after-update #(.focus (react/find-dom-node this)))`.
+2. The `refs` atom allows accessing `this.refs` as a map, e.g., `(.focus (@refs "my-text-box"))`.
+3. Convenience atom for local variables. Instead of, e.g.,
+
+   `(set! (.-myTimer this) (js/setTimeout ...))`, you can do
+
+   `(swap! locals assoc :my-timer (js/setTimeout ...))`.
 
 Note: for non-api methods (like `:add-foo` above), this map is the first argument before any arguments passed when calling the method using `react/call`.
 
 Modifying the `state` atom implicitly calls `this.setState`. This maintains the behavior of React's `this.state` in the way that updates (via `swap!` or `reset!`) are not visible in `@state` until after the component is re-rendered.
 
-Note that `propTypes`, `statics`, and `mixins` are not yet implemented.
+Note that `propTypes`, `statics`, and `mixins` are not yet implemented. They may never be, since Clojure to some extent obviates the need for some of these utilities.