update devcard docs for v0.1.0-beta;

src/devcards/soda_ash/a_faq_card.cljs

@@ -0,0 +1,212 @@
+(ns soda-ash.a-faq-card
+  (:require-macros [devcards.core :refer [defcard-doc
+                                          defcard-rg
+                                          mkdn-pprint-source]])
+  (:require [devcards.core]
+            [devcards.util.edn-renderer :as edn]
+            [reagent.core :as reagent]
+            [soda-ash.element :as s]))
+
+
+(defcard-doc
+  "
+[back](#!/soda_ash.an_overview_card)
+
+#  What is soda-ash?
+
+Soda-ash is an interface between clojurescript's
+[reagent](https://github.com/reagent-project/reagent) and [Semantic
+UI](http://semantic-ui.com/).
+
+# What is `:soda`?
+
+`:soda` is a special attribute that is *added* to the normal attribute
+map, and **replaces** the `:class` attribute. `:soda` takes a hash-map
+of unordered key-value pairs.
+
+For example, let's take a look at an image.")
+
+(defn image []
+  [s/image {:soda {:size :small} ;; <-- attention
+            :src "images/wireframe/image.png"}]
+
+  ;; <img src="images/wireframe/image.png" class="ui small image">
+  )
+
+(defcard-rg
+  [image])
+
+(defcard-doc
+  (mkdn-pprint-source image)
+  "
+As you can see, `:soda` is added to the normal attribute map.  The
+resulting class is `ui small image`. This is because the base class
+for the `s/image` element is `ui small` and the `{:size :small}` soda
+adds the `small` class.
+
+# How does the attribute map work with `:soda`?
+
+Continuing with the image example above, `:src` or any other normal
+attribute is defined *alongside* `:soda` and not inside `:soda`'s
+hash-map.  For example, the following **does not** work.
+  ")
+
+(defn image-bad []
+  [s/image {:soda {:size :small
+                   :src "images/wireframe/image.png"  ;; <-- attention (don't do this)
+                   }}])
+
+(defcard-doc
+  (mkdn-pprint-source image-bad)
+  "
+This will not render. Instead, soda-ash will throw an error letting
+you know the key-value pair that isn't accepted.  If you open up the
+browser's console, you will see the following error message.
+
+```
+Uncaught Error: Soda-ash :src images/wireframe/image.png doesn't exist for image element
+```
+  ")
+
+
+(defcard-doc
+  "
+# If `:soda` replaces `:class`, how do I add my own class?
+
+Soda-ash gives you an escape hatch to add your own class, with `:add-class`.
+")
+
+
+(defn image-add-class []
+  [s/image {:soda {:size :small
+                   :add-class "gadfly"} ;; <-- attention
+            :src "images/wireframe/image.png"}]
+
+  ;; <img src="images/wireframe/image.png" class="ui small gadfly image">
+  )
+
+(defcard-doc
+  (mkdn-pprint-source image-add-class))
+
+
+(defcard-doc
+  "
+# How do I make soda-ash reactive?
+
+By default, soda-ash is **not** reactive.  The `:soda`
+hash-map replaces `:class` when the component <u>*mounts*</u>, and will
+**not** update on render.
+
+To make soda-ash reactive, you need to add `:ratom` and `:path` to your `:soda`.
+")
+
+(defonce app-state (reagent/atom {}))
+
+(defn image-reactive []
+  [s/image {:soda {:ratom app-state ;; <-- attention
+                   :path :foo ;; <-- attention
+                   :size :small}
+            :src "images/wireframe/image.png"}])
+
+(defn wrap-element [ratom element]
+  [:div
+   (if (vector? element) element [element])
+   [:div [:strong "app-state"]]
+   (edn/html-edn @ratom)])
+
+(defcard-doc
+  (mkdn-pprint-source app-state)
+  (mkdn-pprint-source image-reactive))
+
+(defcard-rg
+  [wrap-element app-state
+   [image-reactive]])
+
+(defn size->tiny []
+  [s/button {:on-click #(swap! app-state assoc-in [:foo :soda :size] :tiny)}
+   "tiny"])
+
+(defn size->small []
+  [s/button {:on-click #(swap! app-state assoc-in [:foo :soda :size] :small)}
+   "Small"])
+
+(defcard-doc
+  "
+As you can see, your `:soda` is added to your `:ratom` (i.e.,
+`app-state`) at the specified `:path` (i.e., `:foo`). Now your element
+is reactive! If you `swap!` your `:soda` in the ratom, the element's
+class will update.
+"
+  (mkdn-pprint-source size->tiny)
+  (mkdn-pprint-source size->small))
+
+(defcard-rg
+  [wrap-element app-state
+   [:div
+    [image-reactive]
+    [:br]
+    [size->tiny]
+    [size->small]]])
+
+
+(defcard-doc
+  "
+# How do I read the docs?
+
+Let's look at a subset of the docs for the `image` element:
+
+---
+# image
+
+* **base class** ui image
+* **default tag** :img
+* **:state** :hidden | :disabled
+* **variations**
+    :rounded? | :size |
+
+where
+
+* **:size** :mini | :tiny | :small | :medium | :large | :big | :huge | :massive
+
+---
+
+* The **base class** let's you know what the class will be if you
+don't pass in any `:soda` to the attribute map.
+* Every element has a tag. You can set this by passing `:tag` to your
+  `:soda` (i.e., `{:soda {:tag :div}}`). However, if`:tag` is not set,
+  then it will revert to the **default tag**.
+* Many elements can have `:state`. For example `{:soda {:state :disabled}}`.
+* Most elements have variations.  For example, an image can be rounded
+  and vary in size `{:soda {:rounded? true :size :massive}}`
+
+# What is `h/fake-content` in the docs?
+
+A lot of elements need some content to look as intended ... so
+`h/fake-content` is just some lorem ipsum.
+
+```
+(defn fake-content []
+  [:div
+   \"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+  eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
+  ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
+  aliquip ex ea commodo consequat. Duis aute irure dolor in
+  reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
+  pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
+  culpa qui officia deserunt mollit anim id est laborum.\"])
+```
+
+# Do I always have to pass in an attribute map?
+
+For the time being ... yes. :(
+
+```
+[s/button {} ;; <-- note the empty attribute map
+  \"This works\"]
+```
+
+```
+[s/button ;; <-- not the lack of attribute map
+  \"This doesn't work\"]
+```
+  ")

src/devcards/soda_ash/an_overview_card.cljs

@@ -38,7 +38,7 @@
    [:div [:strong "Element State"]]
    (edn/html-edn @ratom)])
 
-(def app-state (reagent/atom {}))
+(defonce app-state (reagent/atom {}))
 
 (defn option-btn [k v]
   (let [current-v (get-in @app-state [:foo :bar :soda k])]
@@ -82,6 +82,9 @@ Soda-ash is an interface between clojurescript's [reagent](https://github.com/re
 
 --- **[github repo](https://github.com/gadfly361/soda-ash)** ---
 
+
+## [FAQs](#!/soda_ash.a_faq_card)
+
 ## Elements
 
 * [button](#!/soda_ash.elements.button_card)
@@ -128,10 +131,10 @@ What was once this:
 
 
 (defcard-doc
-"`:soda` is a new attribute that is *added* to the normal attibute map.
-`:soda` takes a hash-map of unordered key-value pairs.  Now you
-are able to take full advantage of the hash-map data structure
-... assoc, dissoc, merge etc.
+"`:soda` is a new attribute that is *added* to the normal attibute
+map, and **replaces the `:class` attribute.  `:soda` takes a hash-map
+of unordered key-value pairs.  Now you are able to take full advantage
+of the hash-map data structure ... assoc, dissoc, merge etc.
 
 Finally, soda-ash allows you to place your `:soda` inside a reagent
 atom at your desired path.  This means you can swap! Semantic UI

src/devcards/soda_ash/core_card.cljs

@@ -1,6 +1,7 @@
 (ns soda-ash.core-card
   (:require-macros [devcards.core :as dc])
-  (:require [soda-ash.an-overview-card]
+  (:require [soda-ash.a-faq-card]
+            [soda-ash.an-overview-card]
             [soda-ash.elements.button-card]
             [soda-ash.elements.container-card]
             [soda-ash.elements.divider-card]

src/devcards/soda_ash/elements/button_card.cljs

@@ -16,6 +16,7 @@
 
 # button
 
+* **base class** ui button
 * **default tag** :button
 * **:type**
     *ANIMATED* :animated | :vertical-animated | :animated-fade |
@@ -53,6 +54,7 @@ Notes:
 
 # Buttons
 
+* **base class* ui buttons
 * **default tag** :div
 
 ---

src/devcards/soda_ash/elements/container_card.cljs

@@ -15,6 +15,7 @@
 
 # container
 
+* **base class** ui container
 * **default tag** :div
 * **:type** :default | :text
 * **variations** :aligned | :fluid?

src/devcards/soda_ash/elements/divider_card.cljs

@@ -15,6 +15,7 @@
 
 # divider
 
+* **base class** ui divider
 * **default tag** :div
 * **:type**
     :default | :vertical | :horizontal

src/devcards/soda_ash/elements/flag_card.cljs

@@ -15,6 +15,7 @@
 
 # flag
 
+* **base class* flag
 * **default tag** :i
 * **:flag** see [Semantic UI docs](http://semantic-ui.com/elements/flag.html)
 

src/devcards/soda_ash/elements/header_card.cljs

@@ -15,6 +15,7 @@
 
 # header
 
+* **base class** ui header
 * **default tag** :div
 * **:type**
     :default |

src/devcards/soda_ash/elements/icon_card.cljs

@@ -15,6 +15,7 @@
 
 # icon
 
+* **base class** icon
 * **default tag** :i
 * **:icon** see [Semantic UI docs](http://semantic-ui.com/elements/icon.html)
 * **:state** :default | :disabled | :loading
@@ -36,6 +37,7 @@ where
 
 # icons
 
+* **base class** icons
 * **default tag** :i
 
 ---

src/devcards/soda_ash/elements/image_card.cljs

@@ -15,6 +15,7 @@
 
 # image
 
+* **base class** ui image
 * **default tag** :img
 * **:state** :hidden | :disabled
 * **variations**
@@ -32,6 +33,7 @@ where
 
 # images
 
+* **base class** ui images
 * **default tag** :div
 
 ---

src/devcards/soda_ash/elements/input_card.cljs

@@ -15,6 +15,7 @@
 
 # input
 
+* **base class** ui input
 * **default tag** :div
 * **:state** :focus | :loading | :disabled | :error
 * **variations**

src/devcards/soda_ash/elements/label_card.cljs

@@ -15,6 +15,7 @@
 
 # label
 
+* **base class** ui label
 * **default tag** :div
 * **:type**
     :default |
@@ -59,6 +60,7 @@ where
 
 # labels
 
+* **base class** ui labels
 * **default tag** :div
 
 ---

src/devcards/soda_ash/elements/list_card.cljs

@@ -15,6 +15,7 @@
 
 # list
 
+* **base class** ui list
 * **default tag** :div
 * **:type** :bulleted | :bulleted-link | :link | :ordered | :ordered-link
 * **variations**

src/devcards/soda_ash/elements/loader_card.cljs

@@ -15,6 +15,7 @@
 
 # loader
 
+* **base class** ui loader
 * **default tag** :i
 * **:type** :default | :text
 * **variations** :centered? | :inline | :inverted? | :size | :state

src/devcards/soda_ash/elements/rail_card.cljs

@@ -15,6 +15,7 @@
 
 # rail
 
+* **base class** ui rail
 * **default tag** :div
 * **:type** :left | :right | *INTERNAL* :left-internal | :right-internal | *DIVIDING* :left-dividing | :right-dividing
 * **variations** :attached? | :close

src/devcards/soda_ash/elements/reveal_card.cljs

@@ -15,6 +15,7 @@
 
 # reveal
 
+* **base class** ui reveal
 * **default tag** :div
 * **:type**
     *FADE* :fade |