Document that viewers can be embedded inside of hiccup code (#439)

Updated the Book of Clerk in both the hiccup section and "composing
viewers" section with better examples.

Co-authored-by: Philippa Markovics <[email protected]>

Author: dackerman

book.clj

@@ -168,11 +168,17 @@
 ;; You can style elements, using [Tailwind CSS](https://tailwindcss.com/docs/utility-first).
 (clerk/html [:button.bg-sky-500.hover:bg-sky-700.text-white.rounded-xl.px-2.py-1 "✨ Tailwind CSS"])
 
-;; The `html` viewer is also able to display SVG, taking either a hiccup vector or a SVG string.
+;; The `html` viewer is able to display SVG, taking either a hiccup vector or a SVG string.
 (clerk/html [:svg {:width 500 :height 100}
              [:circle {:cx  25 :cy 50 :r 25 :fill "blue"}]
              [:circle {:cx 100 :cy 75 :r 25 :fill "red"}]])
 
+;; You can also embed other viewers inside of hiccup.
+
+(clerk/html [:div.flex.justify-center.space-x-6
+             [:p "a table is next to me"]
+             (clerk/table [[1 2] [3 4]])])
+
 ;; ### 🔢 Tables
 
 ;; Clerk provides a built-in data table viewer that supports the three
@@ -339,37 +345,60 @@
 
 ;; ### 🍱 Composing Viewers
 
-;; Viewers compose, so you can for example use the plotly viewer inside the grid viewers.
+;; Viewers compose, so, for example, you can lay out multiple independent Vega charts using Clerk’s grid viewers:
 
 ^{::clerk/visibility {:code :fold}}
 (do
-  (def donut-chart
-    (clerk/plotly {:data [{:values [27 11 25 8 1 3 25]
-                           :labels ["US" "China" "European Union" "Russian Federation" "Brazil" "India" "Rest of World"]
-                           :text "CO2"
-                           :textposition "inside"
-                           :domain {:column 1}
-                           :hoverinfo "label+percent+name"
-                           :hole 0.4
-                           :type "pie"}]
-                   :layout {:showlegend false
-                            :width 200
-                            :height 200
-                            :margin {:t 0 :b 0 :r 0 :l 0}
-                            :annotations [{:font {:size 20} :showarrow false :x 0.5 :y 0.5 :text "CO2"}]}
-                   :config {:responsive true}}))
-
-  (def contour-plot
-    (clerk/plotly {:data [{:z [[10 10.625 12.5 15.625 20]
-                               [5.625 6.25 8.125 11.25 15.625]
-                               [2.5 3.125 5.0 8.125 12.5]
-                               [0.625 1.25 3.125 6.25 10.625]
-                               [0 0.625 2.5 5.625 10]]
-                           :type "contour"}]
-                   :layout {:margin {:t 0 :b 0 :r 0 :l 0}}})))
-
-(clerk/col (clerk/row donut-chart donut-chart donut-chart)
-           contour-plot)
+  (def stock-colors
+    {"AAPL" "#4c78a8" "AMZN" "#f58518" "GOOG" "#e45756" "IBM" "#72b7b2" "MSFT" "#54a24b"})
+  (def combined-stocks-chart
+    (clerk/vl {:width 600
+               :height 200
+               :data {:url "https://vega.github.io/vega-lite/examples/data/stocks.csv"}
+               :mark "area"
+               :encoding {:x {:timeUnit "yearmonth" :field "date" :axis {:format "%Y"}}
+                          :y {:aggregate "sum" :field "price"}
+                          :color {:field "symbol"
+                                  :scale {:domain (keys stock-colors) :range (vals stock-colors)}}}
+               :embed/opts {:actions false}}))
+  (defn stock-chart [symbol]
+    (clerk/vl {:title symbol
+               :width 100
+               :height 40
+               :mark "area"
+               :data {:url "https://vega.github.io/vega-lite/examples/data/stocks.csv"}
+               :transform [{:filter (str "datum.symbol == '" symbol "'")}]
+               :encoding {:x {:field "date" :type "temporal" :title nil :axis {:grid false}}
+                          :y {:field "price" :type "quantitative" :title nil :axis {:grid false} :scale {:domain [0 700]}}
+                          :color {:field "symbol" :type "nominal" :legend nil :scale {:domain [symbol]
+                                                                                      :range [(get stock-colors symbol)]}}}
+               :embed/opts {:actions false}})))
+
+(clerk/col
+ (clerk/row (stock-chart "AAPL")
+            (stock-chart "AMZN")
+            (stock-chart "GOOG")
+            (stock-chart "IBM")
+            (stock-chart "MSFT"))
+ combined-stocks-chart)
+
+;; Viewers can also be embedded in Hiccup. The following example shows
+;; how this is used to provide a custom callout for a `clerk/image`.
+
+(clerk/html
+ [:div.relative
+  (clerk/image "https://images.unsplash.com/photo-1608993659399-6508f918dfde?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=2070&q=80")
+  [:div.absolute
+   {:class "left-[25%] top-[21%]"}
+   [:div.border-4.border-emerald-400.rounded-full.shadow
+    {:class "w-8 h-8"}]
+   [:div.border-t-4.border-emerald-400.absolute
+    {:class "w-[80px] rotate-[30deg] left-4 translate-x-[10px] translate-y-[10px]"}]
+   [:div.border-4.border-emerald-400.absolute.text-white.font-sans.p-3.rounded-md
+    {:class "bg-black bg-opacity-60 text-[13px] w-[280px] top-[66px]"}
+    "Cat's paws are adapted to climbing and jumping, walking and running, and have protractible claws for self-defense and hunting."]]])
+
+#_(clerk/html [:div.flex.justify-around donut-chart donut-chart donut-chart])
 
 ;; ### 🤹🏻 Applying Viewers
 
@@ -475,7 +504,7 @@ v/default-viewers
 
 ;; #### ⚙️ Transform
 
-;; When writing your own viewer, the first extention point you should reach for is `:tranform-fn`. 
+;; When writing your own viewer, the first extention point you should reach for is `:tranform-fn`.
 
 #_ "exercise: wrap this in `v/present` and call it at the REPL"
 (v/with-viewer {:transform-fn #(clerk/html [:pre (pr-str %)])}
@@ -502,7 +531,7 @@ v/default-viewers
              "James Clerk Maxwell"))
 
 
-;; **Passing modified viewers down the tree** 
+;; **Passing modified viewers down the tree**
 
 #_ "TODO: move this into clerk?"
 (defn add-child-viewers [viewer viewers]
@@ -705,7 +734,7 @@ v/table-viewer
 ;; ## 🙈 Controlling Visibility
 
 ;; Visibility for code and results can be controlled document-wide and
-;; per top-level form. By default, Clerk will always show code and 
+;; per top-level form. By default, Clerk will always show code and
 ;; results for a notebook.
 
 ;; You can use a map of the following shape to set the visibility of
@@ -736,7 +765,7 @@ v/table-viewer
 ;;
 ;;    ^{::clerk/visibility {:code :hide}} (shuffle (range 25))
 ;;
-;; This will hide the code but only show the result: 
+;; This will hide the code but only show the result:
 
 ^{::clerk/visibility {:code :hide}} (shuffle (range 25))