Doc updates

Author: Michael Trotter

generated-docs/React/Basic/DOM.md

@@ -3,9 +3,9 @@
 This module defines helper functions for creating virtual DOM elements
 safely.
 
-Note: DOM element props are provided as records, and checked using `Union`
-constraints. This means that we don't need to provide all props, but any we
-do provide must have the correct types.
+__*Note:* DOM element props are provided as records, and checked using `Union`
+  constraints. This means that we don't need to provide all props, but any we
+  do provide must have the correct types.__
 
 #### `render`
 
@@ -16,7 +16,7 @@ render :: JSX -> Element -> Effect Unit
 Render or update/re-render a component tree into
 a DOM element.
 
-Note: Relies on `ReactDOM.render`
+__*Note:* Relies on `ReactDOM.render`__
 
 #### `render'`
 
@@ -28,7 +28,7 @@ Render or update/re-render a component tree into
 a DOM element. The given Effect is run once the
 DOM update is complete.
 
-Note: Relies on `ReactDOM.render`
+__*Note:* Relies on `ReactDOM.render`__
 
 #### `hydrate`
 
@@ -40,9 +40,9 @@ Render or update/re-render a component tree into
 a DOM element, attempting to reuse the existing
 DOM tree.
 
-Note: Relies on `ReactDOM.hydrate`, generally only
+__*Note:* Relies on `ReactDOM.hydrate`, generally only
   used with `ReactDOMServer.renderToNodeStream` or
-  `ReactDOMServer.renderToString`
+  `ReactDOMServer.renderToString`__
 
 #### `hydrate'`
 
@@ -55,9 +55,9 @@ a DOM element, attempting to reuse the existing
 DOM tree. The given Effect is run once the
 DOM update is complete.
 
-Note: Relies on `ReactDOM.hydrate`, generally only
+__*Note:* Relies on `ReactDOM.hydrate`, generally only
   used with `ReactDOMServer.renderToNodeStream` or
-  `ReactDOMServer.renderToString`
+  `ReactDOMServer.renderToString`__
 
 #### `unmount`
 
@@ -69,7 +69,7 @@ Attempt to unmount and clean up the React app
 rendered into the given element. Returns `true`
 if an app existed and was unmounted successfully.
 
-Note: Relies on `ReactDOM.unmountComponentAtNode`
+__*Note:* Relies on `ReactDOM.unmountComponentAtNode`__
 
 #### `findDOMNode`
 
@@ -81,7 +81,10 @@ Returns the current DOM node associated with the given
 instance, or an Error if no node was found or the given
 instance was not mounted.
 
-Note: Relies on `ReactDOM.findDOMNode`
+__*Note:* This function can be *very* slow -- prefer
+`React.Basic.DOM.Components.Ref` where possible__
+
+__*Note:* Relies on `ReactDOM.findDOMNode`__
 
 #### `createPortal`
 
@@ -110,7 +113,7 @@ css :: forall css. {  | css } -> CSS
 Create a value of type `CSS` (which can be provided to the `style` property)
 from a plain record of CSS attributes.
 
-E.g.
+For example:
 
 ```
 div { style: css { padding: "5px" } } [ text "This text is padded." ]
@@ -124,7 +127,7 @@ mergeStyles :: Array CSS -> CSS
 
 Merge styles from right to left. Uses `Object.assign`.
 
-E.g.
+For example:
 
 ```
 style: mergeCSS [ (css { padding: "5px" }), props.style ]

generated-docs/React/Basic/DOM/Components/Ref.md

@@ -4,19 +4,14 @@ This module provides an efficient (no `ReactDOM.findDOMNode`) and
 declarative way to aquire a `Node` for an element in your render
 tree.
 
-For both type safety and performance reasons, `ref` will always
-provide a reference to its own `<react-basic-ref>` `Node`, but you
-can use this `Node` with `querySelector` to find more specific local
-elements.
-
 For example:
 
 ```purs
 render self =
   ref \myRef ->
     case myRef of
-      Nothing -> R.text "DOM render in progress..."
-      Just _  -> R.text "DOM render complete."
+      Nothing -> R.text "First DOM render in progress..."
+      Just _  -> R.text "First DOM render complete."
 ```
 
 #### `ref`
@@ -25,4 +20,26 @@ render self =
 ref :: (Maybe Node -> JSX) -> JSX
 ```
 
+#### `selectorRef`
+
+``` purescript
+selectorRef :: QuerySelector -> (Maybe Node -> JSX) -> JSX
+```
+
+
+### Re-exported from Web.DOM.ParentNode:
+
+#### `QuerySelector`
+
+``` purescript
+newtype QuerySelector
+  = QuerySelector String
+```
+
+##### Instances
+``` purescript
+Eq QuerySelector
+Ord QuerySelector
+Newtype QuerySelector _
+```
 

src/React/Basic/DOM.purs

@@ -1,9 +1,9 @@
 -- | This module defines helper functions for creating virtual DOM elements
 -- | safely.
 -- |
--- | Note: DOM element props are provided as records, and checked using `Union`
--- | constraints. This means that we don't need to provide all props, but any we
--- | do provide must have the correct types.
+-- | __*Note:* DOM element props are provided as records, and checked using `Union`
+-- |   constraints. This means that we don't need to provide all props, but any we
+-- |   do provide must have the correct types.__
 
 module React.Basic.DOM
   ( module Internal
@@ -38,15 +38,15 @@ import Web.DOM (Element, Node)
 -- | Render or update/re-render a component tree into
 -- | a DOM element.
 -- |
--- | Note: Relies on `ReactDOM.render`
+-- | __*Note:* Relies on `ReactDOM.render`__
 render :: JSX -> Element -> Effect Unit
 render jsx node = render' jsx node (pure unit)
 
 -- | Render or update/re-render a component tree into
 -- | a DOM element. The given Effect is run once the
 -- | DOM update is complete.
 -- |
--- | Note: Relies on `ReactDOM.render`
+-- | __*Note:* Relies on `ReactDOM.render`__
 render' :: JSX -> Element -> Effect Unit -> Effect Unit
 render' = runEffectFn3 render_
 
@@ -56,9 +56,9 @@ foreign import render_ :: EffectFn3 JSX Element (Effect Unit) Unit
 -- | a DOM element, attempting to reuse the existing
 -- | DOM tree.
 -- |
--- | Note: Relies on `ReactDOM.hydrate`, generally only
+-- | __*Note:* Relies on `ReactDOM.hydrate`, generally only
 -- |   used with `ReactDOMServer.renderToNodeStream` or
--- |   `ReactDOMServer.renderToString`
+-- |   `ReactDOMServer.renderToString`__
 hydrate :: JSX -> Element -> Effect Unit
 hydrate jsx node = hydrate' jsx node (pure unit)
 
@@ -67,9 +67,9 @@ hydrate jsx node = hydrate' jsx node (pure unit)
 -- | DOM tree. The given Effect is run once the
 -- | DOM update is complete.
 -- |
--- | Note: Relies on `ReactDOM.hydrate`, generally only
+-- | __*Note:* Relies on `ReactDOM.hydrate`, generally only
 -- |   used with `ReactDOMServer.renderToNodeStream` or
--- |   `ReactDOMServer.renderToString`
+-- |   `ReactDOMServer.renderToString`__
 hydrate' :: JSX -> Element -> Effect Unit -> Effect Unit
 hydrate' = runEffectFn3 hydrate_
 
@@ -79,7 +79,7 @@ foreign import hydrate_ :: EffectFn3 JSX Element (Effect Unit) Unit
 -- | rendered into the given element. Returns `true`
 -- | if an app existed and was unmounted successfully.
 -- |
--- | Note: Relies on `ReactDOM.unmountComponentAtNode`
+-- | __*Note:* Relies on `ReactDOM.unmountComponentAtNode`__
 unmount :: Element -> Effect Boolean
 unmount = runEffectFn1 unmountComponentAtNode_
 
@@ -89,7 +89,10 @@ foreign import unmountComponentAtNode_ :: EffectFn1 Element Boolean
 -- | instance, or an Error if no node was found or the given
 -- | instance was not mounted.
 -- |
--- | Note: Relies on `ReactDOM.findDOMNode`
+-- | __*Note:* This function can be *very* slow -- prefer
+-- | `React.Basic.DOM.Components.Ref` where possible__
+-- |
+-- | __*Note:* Relies on `ReactDOM.findDOMNode`__
 findDOMNode :: ReactComponentInstance -> Effect (Either Error Node)
 findDOMNode instance_ = try do
   node <- runEffectFn1 findDOMNode_ instance_
@@ -115,7 +118,7 @@ text = unsafeCoerce
 -- | Create a value of type `CSS` (which can be provided to the `style` property)
 -- | from a plain record of CSS attributes.
 -- |
--- | E.g.
+-- | For example:
 -- |
 -- | ```
 -- | div { style: css { padding: "5px" } } [ text "This text is padded." ]
@@ -125,7 +128,7 @@ css = unsafeCoerce
 
 -- | Merge styles from right to left. Uses `Object.assign`.
 -- |
--- | E.g.
+-- | For example:
 -- |
 -- | ```
 -- | style: mergeCSS [ (css { padding: "5px" }), props.style ]

src/React/Basic/DOM/Components/Ref.purs

@@ -2,19 +2,14 @@
 -- | declarative way to aquire a `Node` for an element in your render
 -- | tree.
 -- |
--- | For both type safety and performance reasons, `ref` will always
--- | provide a reference to its own `<react-basic-ref>` `Node`, but you
--- | can use this `Node` with `querySelector` to find more specific local
--- | elements.
--- |
 -- | For example:
 -- |
 -- | ```purs
 -- | render self =
 -- |   ref \myRef ->
 -- |     case myRef of
--- |       Nothing -> R.text "DOM render in progress..."
--- |       Just _  -> R.text "DOM render complete."
+-- |       Nothing -> R.text "First DOM render in progress..."
+-- |       Just _  -> R.text "First DOM render complete."
 -- | ```
 module React.Basic.DOM.Components.Ref
   ( ref