;; In a Clojure environment, the above snippet expands to:
(createElement Component
(merge {:foo "bar"} parent-props)
"Baz")

;; Whereas in ClojureScript, the expansion includes JS conversion code
(if (cljsx.core/js? createElement)
;; If createElement is a JavaScript function,
(apply createElement
;; If the tag (in this case Component) is a JavaScript function,
(if (cljsx.core/js? Component)
;; no conversion is needed, because the props are a JS object already.
Component
;; Otherwise (if it is a Clojure function),
;; the tag function needs to be intercepted,
(fn [props__38180__auto__]
;; so the props passed by the JS createElement function can be
;; converted to a Clojure map so they don't need to be manually
;; converted in each component implementation.
(Component (js->clj props__38180__auto__
:keywordize-keys true))))
;; The props and children both need to be converted to JS before they
;; are passed to the JS createElement
(clj->js (merge {:foo "bar"} parent-props))
(map clj->js ["Baz"]))
;; If createElement is a Clojure function, no conversion happens.
(createElement Component
(merge {:foo "bar"} parent-props)
"Baz"))
```

If `createElement` resolves to a JavaScript function, there are two places where
the JavaScript conversion happens:

* First all props are converted to JavaScript objects recursively with [clj->js].
* Then all _reference tags_ which resolve to Clojure functions are intercepted
so that the props passed to them by `createElement` can be converted back to
Clojure maps with [js->clj] before they are passed to them.

If the Clojure _tag_ functions were not intercepted, you would need to treat the
props in your components as JavaScript objects and could not destructure them:

```clj
;; Without automatic conversion your components would be rather verbose.
(defn MyButton [js-props]
(jsx>
;; cljsx is expecting the props to be a Clojure map
(clj js-props)
:className (str "my-button " (.-class js-props)) >)))

;; With automatic conversion, your components should be nice and readable.
(defn MyButton [{:keys [class] :as clj-props}]
(jsx>
()))
```

#### JavaScript Function Detection Pitfalls

In ClojureScript, testing whether whether a function is a JavaScript or Clojure
function is not trivial and not always possible. `cljsx` has it's own
`cljsx.core/clj-fn?` macro for this purpose. The function returns `true` if it
is certain that the object passed to it is a Clojure function, `false` if it is
certain that it's a JavaScript function, and `nil` if it can't be determined.
Following are cases when `cljsx.core/clj-fn?` returns `nil` and thus
*favours JavaScript conversion*:

A function is reassigned to a let binding:

```clj
(defn f [])

(let [f' f ; Metadata is lost on reassignment.
;; But fresh assignmet still works.
g (fn [])
h #(identity %)]
[(clj-fn? f')
(clj-fn? g)
(clj-fn? h)])
;; => [nil true true]
```

A function is passed as an argument to another function:

```clj
(defn f [])

(defn g [x]
(clj-fn? x))

(g f)
;; => nil

(clj-fn? (identity f))
;; => nil
```

A function is returned from another function:

```clj
(defn f [])

(clj-fn? ((fn [] f)))
;; => nil
```

A function is defined or reassigned in the same `cljsx` macro where it is used:

```clj
(defn f [])
(def g f)

(jsx>
(defn f' [])
(def g' f'))

(jsx>
(defn f'' [])
(def g'' f'')

[(clj-fn? f) ; true
(clj-fn? g) ; true
(clj-fn? f') ; true
(clj-fn? g') ; true
;; Only definitions inside this very jsx> block are indeterminate
(clj-fn? f'') ; nil
(clj-fn? g'') ; nil
])
;; => [true true true true nil nil]
```

#### Taking JavaScript Conversion Under Control

There are various ways how you can ensure that your functions called by [React]
will always be either Clojure data structures of JavaScript objects.

##### Setting a Var's Tag Meta

The `cljsx.core/clj-fn?` is consulting the var's metadata `:tag`
value (among other things), which is lost in all of the cases when the function
returns `nil`. You can manually set the _tag_ and thus controll the conversion
of its arguments. If the tag value is `js`, or it is not set at all, it will be
treated as a JavaScript function. If the _tag_ is set to any value other than
`js` or `nil`, it will be treated as a Clojure function.

```clj
(defn f [])
(defn ^js f-js [])

(let [^cljs f-clj]
[(clj-fn? f)
(clj-fn? f-js)
(clj-fn f-clj)])
;; => [true false true]
```

This approach however is rather verbose and it doesn't work in the case when a
function is defined inside the same jsx macro call where it is used.

##### Conversion Decorators

Since the JavaScript conversion favours JavaScript when the result of the
underlying `clj-fn?` function is `nil`, you should only be concerned about what
is passed to the components you defined and which you have under control.

There are number of utilities which you can use to make sure that your
components will always receive their props as a Clojure map or a JavaScript
object.

###### The `with-js-args` and `with-clj-args` Decorators

The `with-js-args` decorator takes a function and returns the same function for
which each argument will be passed trhough [clj->js]. Conversely the
`with-clj-args` function takes a function and returns the same function for
which all arguments will be passed trhough [js->clj].

```clj
(ns my-react-app.main
(:require [cljsx.core :refer [react> with-clj-args]]
[react :as react]
[react-dom :as react-dom]))

(react>
(defn Component [props]
(js/console.log "Clojure props:" (map? props))
(

"Hello!"))

(def ComponentWithCLJProps (with-clj-args Component))

(react-dom/render
(

() ; Clojure props: false
() ; Clojure props: true
(js/document.querySelector "#mount-point"))))
```

##### Function Definition Macros

Wrapping every component you write in a decorator is tedious and annoying.
But fear not, `cljsx` comes with a bunch of macros which simplify definition of
functions with predictable data format.

###### The `fn-clj` And `defn-clj` Macros

The `fn-clj` and `defn-clj` macros have the same signature and work the same as
their `fn` and `defn` counterparts, except that the functions they define will
always receive JavaScript arguments converted to Clojure data structures using
[js->clj] with `:keywordize-keys true`.

Functions defined with `fn-clj` and `defn-clj` work predictably everywhere,
even in the same `jsx>` macro where they are defined.

```clj
((fn-clj [x y & z] [x y z])
#js{"x" 11} #js{"x" 22} #js{"z" 33})
;; => [{:x 11} {:x 22} ({:z 33})]

;; You can define multiple arities
(def multi-arity-fn (fn-clj ([] "nullary")
([x] ["unary" x])
([x y] ["binary" x y])
([x y & z] ["variadic" x y z])))

(multi-arity-fn)
;; => "nullary"

(multi-arity-fn #js{"x" 11})
;; => ["unary" {:x 11}]

(multi-arity-fn #js{"x" 11} #js{"x" 22})
;; => ["binary" {:x 11} {:x 22}]

(multi-arity-fn #js{"x" 11} #js{"x" 22} #js{"z" 33})
;; => [{:x 11} {:x 22} ({:z 33})]
```
These macros are especially usefull for defining callbacks for JavaScript
libraries like [React Router].

```clj
(ns shadow-cljs-example.main
(:require ["react" :as react]
["react-dom" :as react-dom]
["react-router-dom" :as rr]
[cljsx.core :refer [defn-clj fn-clj react>]]))

(react>
;; This function will always receive a Clojure map, eventhough
;; its defined in the same react> call where it is used.
(defn-clj Link [{:keys [href active children]}]
(if active
children
(
children)))

(react-dom/render
(
(
;; We can destructure the React Router route props, which are passed as a
;; JavaScript object because we are using fn-clj and not just fn.
(fn-clj [{{path :pathname} :location :as x}]
(js/console.log (subs path 1))
(

(map #(
• 
  ;; React will pass the props to Link as a JS object,
  ;; but since Link is defined with def-clj,
  ;; it will recieve the props as a Clojure map.
  (
  %))
  ["foo" "bar" "baz"])))))
  (js/document.querySelector "#mount-point")))
  ```

  ###### The `component` and `defcomponent` Macros

  The `component` and `defcomponent` macros are just a stripped-out version of the
  `fn-clj` and `defn-clj` macros. The only difference is that they define a
  _unary_ function with _props_ as the only argument, which can be a map, `nil` or
  a plain JavaScript object, in which case, similarly as with `def-clj` the
  functions will receive the argument converted using [js->clj] with
  `:keywordize-keys true`.

  The `component` and `defcomponent` signatures are the same as the signatures of
  `fn-clj` and `defn-clj` (or [fn] and [defn]) respectively with these rather
  cosmetic differences:

  * Since both define unary functions there's no point in supporting multiple
  arities.
  * For the same reason, we don't need the argument vector, but only the single
  argument symbol or a destructuring map.
  * In `defcomponent`, metadata can only be set with the `^` reader macro in front
  of the component name and not with the metadata map before the argument vector
  as is possible in `defn-clj` and [defn].
  * Both `fn-clj` and [fn] accept an optional _name_ parameter i.e. a symbol in
  of the _argument vector_ e.g `(fn my-name [x] fn-body)`. In the `component`
  macro, the _name_ must be a _qouted_ symbol so that it can be distinguished
  from the possible _prop_ symbol e.g. `(component 'my-name props fn-body)`.

  ```clj
  (defcomponent MyComponent props
  (map? props))

  ;; The above statement is equivalent to this.
  ;; The only difference is the missing square brackets of the argument vector.
  (defn-clj MyComponent' [props]
  (map? props))

  (MyComponent {:a "A"}) ; true
  ;; Even if you call it with a JS object, it still receives a Clojure map
  (MyComponent #js{:a "A"}) ; true

  (react>
  ;; Even if you define the component in the same JSX macro call as it is used,
  ;; it will still predictably receive its props as a Clojure map.
  (defcomponent ^:before-load StyledButton
  "A button which adds the .my-button class to its class name list."
  ;; Destructuring stil works on the single argument.
  {:keys [className] :or {className ""} :as props}
  ;; Pre and post conditions work the same as in defn
  {:pre [(string? className)]}
  ())

  (react-dom-server/renderToStaticMarkup
  ;; The component will receive a Clojure map, eve though
  ;; React passes the props to it as a JavaScript object.
  (
  "Click me!")))
  ;; => "Click me!"
  ```

  ### Example

  And finally an example of a simple application which uses [Material-UI] and
  [React Router] written in JSX, `cljsx` and [reagent].

  #### JavaScript With JSX

  ```jsx
  import React from 'react'
  import ReactDOM from 'react-dom'
  import { BrowserRouter, Link, Route } from 'react-router-dom'
  import { Avatar, Card, CardContent, CardHeader, IconButton } from '@material-ui/core'
  import * as icons from '@material-ui/icons'

  const IconButtonLink = props =>
  

  const App = () =>
  
  
  {({location: {pathname: path}}) => {
  const activeIconName = path.slice(1)
  const ActiveIcon = icons[activeIconName]
  const title = ActiveIcon ? activeIconName : "Click the icons"
  return (
  
  }/>
  
  {Object.keys(icons)
  .filter(iconName => iconName.endsWith('TwoTone'))
  .map(iconName => {
  const Icon = icons[iconName]
  const color = iconName === activeIconName
  ? "secondary"
  : "default"
  return (
  
  
  
  )
  })}
  
  
  )
  }}
  
  

  ReactDOM.render(
  ,
  document.querySelector('#mount-point'),
  )
  ```

  #### ClojureScript With CLJSX

  ```clj
  (ns shadow-cljs-example.main
  (:require ["react" :as react]
  ["react-dom" :as react-dom]
  ["react-router-dom" :as rr]
  ["@material-ui/core" :as mui]
  ["@material-ui/icons" :as mui-icons]
  [cljsx.core :refer [defcomponent fn-clj react>]]))

  (react>
  (defcomponent IconButtonLink props
  ())

  (defcomponent App _
  (
  (
  (fn-clj [{{path :pathname} :location}]
  (let [active-icon-name (subs path 1)
  ^js ActiveIcon (aget mui-icons active-icon-name)]
  (
  (
  ())) >)
  (
  (for [icon-name (js/Object.keys mui-icons)
  :when (.endsWith icon-name "TwoTone")
  :let [^js Icon (aget mui-icons icon-name)]]
  (
  ())))))))))

  (react-dom/render
  ()
  (js/document.querySelector "#mount-point")))
  ```

  #### ClojureScript With Reagent

  ```clj
  (ns shadow-cljs-example.main
  (:require ["react-router-dom" :as rr]
  ["@material-ui/core" :as mui]
  ["@material-ui/icons" :as mui-icons]
  [reagent.core :as r]))

  (defn icon-button-link [props & children]
  (into [:> mui/IconButton (merge props {:component rr/Link})]
  children))

  (defn app []
  [:> rr/BrowserRouter
  [:> rr/Route
  (fn [js-route-props]
  (let [path (-> js-route-props .-location .-pathname)
  active-icon-name (subs path 1)
  ActiveIcon (aget mui-icons active-icon-name)]
  (r/as-element
  [:> mui/Card
  [:> mui/CardHeader {:title (if ActiveIcon
  active-icon-name
  "Click the icons")
  :avatar (r/as-element
  [:> mui/Avatar
  (when ActiveIcon
  [:> mui/Avatar
  [:> ActiveIcon]])])}]
  [:> mui/CardContent
  (for [icon-name (js/Object.keys icons)
  :when (.endsWith icon-name "TwoTone")
  :let [Icon (aget mui-icons icon-name)]]
  ^{:key icon-name}
  [icon-button-link {:to icon-name
  :color (if (= icon-name active-icon-name)
  "secondary"
  "default")}
  [:> Icon]])]])))]])

  (r/render
  [app]
  (js/document.querySelector "#mount-point"))
  ```

  [fn]: https://clojuredocs.org/clojure.core/fn
  [defn]: https://clojuredocs.org/clojure.core/defn
  [clj->js]: https://cljs.github.io/api/cljs.core/clj-GTjs
  [hiccups]: https://github.com/teropa/hiccups
  [js->clj]: https://cljs.github.io/api/cljs.core/js-GTclj
  [Figwheel]: https://figwheel.org/
  [Inferno]: https://infernojs.org/
  [JSX]: https://reactjs.org/docs/introducing-jsx.html
  [Material-UI]: https://material-ui.com/
  [merge]: https://clojuredocs.org/clojure.core/merge
  [Nerv]: https://nerv.aotu.io/
  [Preact]: https://preactjs.com/
  [React]: https://reactjs.org/
  [React Router]: https://reacttraining.com/react-router/
  [_render props_]: https://reactjs.org/docs/render-props.html
  [reagent]: http://reagent-project.github.io/
  [shadow-cljs]: http://shadow-cljs.org/
  [Snabbdom]: https://github.com/snabbdom/snabbdom
  [spec]: https://clojure.org/about/spec