clerk/fragment (#443)

Allow for splicing a seq of values into the document as if it were produced by results of individual cells. Useful when programmatically generating content.
---------

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

Author: 3 people

CHANGELOG.md

@@ -11,6 +11,8 @@ Changes can be:
 
     To see what's going on while waiting for a long-running computation, Clerk will now show an execution status bar on the top. For named cells (defining a var) it will show the name of the var, for anonymous expressions, a preview of the form.
 
+* 🍕 `clerk/fragment` for splicing a seq of values into the document as if it were produced by results of individual cells. Useful when programmatically generating content.
+
 * 🔌 Make websocket reconnect automatically on close to avoid having to reload the page
 * 💫 Cache expressions that return `nil` in memory
 

notebooks/fragments.clj

@@ -0,0 +1,45 @@
+;; # 🧩Fragments
+(ns fragments
+  (:require [nextjournal.clerk :as clerk]))
+
+;; With `clerk/fragment` we allow to embed a sequence of values into the document as if they were results of individual cells, nesting is allowed.
+
+(clerk/fragment
+ (clerk/table [[1 2] [3 4]])
+ (clerk/image "trees.png")
+ (clerk/plotly {::clerk/width :full} {:data [{:y [1 3 2]}]})
+ (clerk/html {::clerk/width :full} [:div.h-20.bg-amber-200])
+ (clerk/fragment (clerk/html {::clerk/width :full} [:div.h-20.bg-amber-300])
+                 (clerk/html {::clerk/width :full} [:div.h-20.bg-amber-400])))
+
+;; ## Collapsible Sections
+;; Fragments allow to hide (and in future versions of Clerk, probably fold) chunks of prose interspersed with results. That is, by using the usual visibility annotation
+;;
+;;     ^{::clerk/visibility {:code :hide :result :hide}}
+;;
+;; all the following section can be hidden.
+
+^{::clerk/visibility {:code :hide}}
+(clerk/fragment
+ (clerk/md "# Title")
+ (clerk/code 123)
+ 123
+ (clerk/md "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus condimentum accumsan lacus id laoreet. Maecenas scelerisque rutrum nunc, eu rutrum libero tincidunt eu. Etiam neque mi, sollicitudin in sodales nec, ornare nec dolor. Vivamus non vestibulum erat. Etiam sodales justo lacus, ac ullamcorper sem dignissim eu. Nunc a vehicula elit. Donec orci odio, bibendum ut imperdiet id, fermentum nec ex. Nunc venenatis est quis arcu elementum, non accumsan erat dictum. Donec vitae felis felis.
+## Some Section
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus condimentum accumsan lacus id laoreet. Maecenas scelerisque rutrum nunc, eu rutrum libero tincidunt eu. Etiam neque mi, sollicitudin in sodales nec, ornare nec dolor. Vivamus non vestibulum erat. Etiam sodales justo lacus, ac ullamcorper sem dignissim eu. Nunc a vehicula elit. Donec orci odio, bibendum ut imperdiet id, fermentum nec ex. Nunc venenatis est quis arcu elementum, non accumsan erat dictum. Donec vitae felis felis.")
+ (clerk/code '(clerk/plotly {:data [{:y [1 2 3]}]}))
+ (clerk/plotly {:data [{:y [1 2 3]}]})
+ (clerk/md "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus condimentum accumsan lacus id laoreet. Maecenas scelerisque rutrum nunc, eu rutrum libero tincidunt eu. Etiam neque mi, sollicitudin in sodales nec, ornare nec dolor. Vivamus non vestibulum erat. Etiam sodales justo lacus, ac ullamcorper sem dignissim eu. Nunc a vehicula elit. Donec orci odio, bibendum ut imperdiet id, fermentum nec ex. Nunc venenatis est quis arcu elementum, non accumsan erat dictum. Donec vitae felis felis.
+
+---"))
+
+;; And the above will look like as if produced by:
+;; # Title
+123
+;; Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus condimentum accumsan lacus id laoreet. Maecenas scelerisque rutrum nunc, eu rutrum libero tincidunt eu. Etiam neque mi, sollicitudin in sodales nec, ornare nec dolor. Vivamus non vestibulum erat. Etiam sodales justo lacus, ac ullamcorper sem dignissim eu. Nunc a vehicula elit. Donec orci odio, bibendum ut imperdiet id, fermentum nec ex. Nunc venenatis est quis arcu elementum, non accumsan erat dictum. Donec vitae felis felis.
+;; ## Some Section
+;; Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus condimentum accumsan lacus id laoreet. Maecenas scelerisque rutrum nunc, eu rutrum libero tincidunt eu. Etiam neque mi, sollicitudin in sodales nec, ornare nec dolor. Vivamus non vestibulum erat. Etiam sodales justo lacus, ac ullamcorper sem dignissim eu. Nunc a vehicula elit. Donec orci odio, bibendum ut imperdiet id, fermentum nec ex. Nunc venenatis est quis arcu elementum, non accumsan erat dictum. Donec vitae felis felis.
+(clerk/plotly {:data [{:y [1 2 3]}]})
+;; Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus condimentum accumsan lacus id laoreet. Maecenas scelerisque rutrum nunc, eu rutrum libero tincidunt eu. Etiam neque mi, sollicitudin in sodales nec, ornare nec dolor. Vivamus non vestibulum erat. Etiam sodales justo lacus, ac ullamcorper sem dignissim eu. Nunc a vehicula elit. Donec orci odio, bibendum ut imperdiet id, fermentum nec ex. Nunc venenatis est quis arcu elementum, non accumsan erat dictum. Donec vitae felis felis.
+;;
+;; ---

notebooks/viewers/markdown.clj

@@ -48,7 +48,9 @@ It's [Markdown](https://daringfireball.net/projects/markdown/), like you know it
 
 ;; ## Soft vs. Hard Line Breaks
 ;; This one ⇥
-;; ⇤ is a [soft break](https://spec.commonmark.org/0.30/#soft-line-breaks) and is rendered as a space, while this one ⇥\
+;; ⇤ is a [soft break](https://spec.commonmark.org/0.30/#soft-line-breaks) and is rendered as a space.
+;;
+;; This one instead ⇥\
 ;; ⇤ is a [hard break](https://spec.commonmark.org/0.30/#hard-line-breaks) and is rendered as a newline.
 
 ;; ## Sidenotes

resources/stylesheets/viewer.css

@@ -37,7 +37,7 @@
       h2 { @apply text-xl !important; }
       h3 { @apply text-lg !important; }
   }
-  
+
   button { @apply focus:outline-none; }
   strong { @apply font-bold; }
   em     { @apply italic; }
@@ -254,6 +254,9 @@
 .markdown-viewer blockquote p:last-of-type:after {
   @apply content-none;
 }
+.markdown-node-viewer.result-viewer.fragment-item {
+    @apply mb-0 !important;
+}
 
 /* Images */
 /* --------------------------------------------------------------- */
@@ -330,7 +333,7 @@
     @apply mt-1;
   }
   .sidenotes-layout .markdown-viewer {
-    @apply pr-[205px];
+    @apply pr-[241px];
   }
   .sidenote-container {
     @apply relative mb-0;
@@ -339,9 +342,9 @@
     @apply w-[756px] !important;
   }
 }
-.code-viewer + .viewer:not(.markdown-viewer):not(.code-viewer):not(.code-viewer-folded),
-.code-viewer-folded + .viewer:not(.markdown-viewer):not(.code-viewer):not(.code-viewer-folded),
-.result-viewer + .result-viewer {
+.code-viewer + .viewer:not(.code-viewer):not(.code-viewer-folded),
+.code-viewer-folded + .viewer:not(.code-viewer):not(.code-viewer-folded),
+.result-viewer:not(.markdown-node-viewer) + .result-viewer {
   @apply mt-2;
 }
 .code-viewer + .code-viewer-folded {
@@ -350,6 +353,9 @@
 .result-viewer {
   @apply leading-tight mb-6;
 }
+.code-viewer.fragment-item.result-viewer {
+  @apply mb-0 !important;
+}
 .result-viewer figure {
   @apply mt-0 !important;
 }

src/nextjournal/clerk.clj

@@ -327,6 +327,13 @@
   [text content]
   (v/caption text content))
 
+(defn fragment
+  "A utility function to splice the given `xs` into individual results.
+
+  Useful when prgrammatically generating content."
+  [& xs]
+  (apply v/fragment xs))
+
 (defn code
   "Displays `x` as syntax highlighted Clojure code.
 

src/nextjournal/clerk/builder.clj

@@ -20,12 +20,14 @@
          "notebooks/onwards.md"]
         (map #(str "notebooks/" % ".clj"))
         ["cards"
+         "controlling_width"
          "docs"
          "hello"
          "how_clerk_works"
          "exec_status"
          "eval_cljs"
          "example"
+         "fragments"
          "hiding_clerk_metadata"
          "js_import"
          "multiviewer"

src/nextjournal/clerk/render.cljs

@@ -114,27 +114,6 @@
 
 (defonce !eval-counter (r/atom 0))
 
-(defn render-processed-block [x]
-  (let [{viewer-name :name} (viewer/->viewer x)
-        viewer-css-class (viewer/css-class x)
-        inner-viewer-name (some-> x viewer/->value viewer/->viewer :name)
-        processed-block-id (get-in x [:nextjournal/opts :id])]
-    ^{:key (str processed-block-id "@" @!eval-counter)}
-    [:div {:data-block-id processed-block-id
-           :class (concat
-                   [(when (:nextjournal/open-graph-image-capture (viewer/->value x)) "open-graph-image-capture")]
-                   (if viewer-css-class
-                     (cond-> viewer-css-class
-                       (string? viewer-css-class) vector)
-                     ["viewer"
-                      (when viewer-name (name viewer-name))
-                      (when inner-viewer-name (name inner-viewer-name))
-                      (case (or (viewer/width x) (case viewer-name (`viewer/code-viewer `viewer/code-folded-viewer) :wide :prose))
-                        :wide "w-full max-w-wide"
-                        :full "w-full"
-                        "w-full max-w-prose px-8")]))}
-     [inspect-presented x]]))
-
 (defn exec-status [{:keys [progress status]}]
   [:div.w-full.bg-purple-200.dark:bg-purple-900.rounded.z-20 {:class "h-0.5"}
    [:div.bg-purple-600.dark:bg-purple-400 {:class "h-0.5" :style {:width (str (* progress 100) "%")}}]
@@ -147,7 +126,9 @@
    {:style {:font-size "0.5rem"} :class "left-[35px] md:left-0 mt-[7px] md:mt-1"}
    status])
 
-(defn render-notebook [{:as _doc xs :blocks :keys [bundle? css-class sidenotes? toc toc-visibility]}]
+(declare inspect-children)
+
+(defn render-notebook [{:as _doc xs :blocks :keys [bundle? css-class sidenotes? toc toc-visibility]} opts]
   (r/with-let [local-storage-key "clerk-navbar"
                navbar-width 220
                !state (r/atom {:toc (toc-items (:children toc))
@@ -197,14 +178,19 @@
            {:class "z-10 fixed right-2 top-2 md:right-auto md:left-3 md:top-[7px] text-slate-400 font-sans text-xs hover:underline cursor-pointer flex items-center bg-white dark:bg-gray-900 py-1 px-3 md:p-0 rounded-full md:rounded-none border md:border-0 border-slate-200 dark:border-gray-500 shadow md:shadow-none dark:text-slate-400 dark:hover:text-white"}]
           [navbar/panel !state [navbar/navbar !state]]])
        [:div.flex-auto.w-screen.scroll-container
-        [:> (.-div motion)
-         {:key "notebook-viewer"
-          :initial (when toc-visibility {:margin-left doc-inset})
-          :animate (when toc-visibility {:margin-left doc-inset})
-          :transition navbar/spring
-          :class (str (or css-class "flex flex-col items-center notebook-viewer flex-auto ")
-                      (when sidenotes? "sidenotes-layout"))}
-         (doall (map render-processed-block xs))]]])))
+        (into
+         [:> (.-div motion)
+          {:key "notebook-viewer"
+           :initial (when toc-visibility {:margin-left doc-inset})
+           :animate (when toc-visibility {:margin-left doc-inset})
+           :transition navbar/spring
+           :class (str (or css-class "flex flex-col items-center notebook-viewer flex-auto ")
+                       (when sidenotes? "sidenotes-layout"))}]
+
+         ;; TODO: restore react keys via block-id
+         ;; ^{:key (str processed-block-id "@" @!eval-counter)}
+
+         (inspect-children opts) xs)]])))
 
 (defn opts->query [opts]
   (->> opts
@@ -298,7 +284,28 @@
     auto-expand? (-> viewer/assign-content-lengths)
     true (-> viewer/assign-expanded-at (get :nextjournal/expanded-at {}))))
 
-(defn render-result [{:as result :nextjournal/keys [fetch-opts hash presented]} {:as opts :keys [auto-expand-results?]}]
+(defn result-css-class [x]
+  (let [{viewer-name :name} (viewer/->viewer x)
+        viewer-css-class (viewer/css-class x)
+        inner-viewer-name (some-> x viewer/->value viewer/->viewer :name)]
+    (if viewer-css-class
+      (cond-> viewer-css-class
+        (string? viewer-css-class) vector)
+      ["viewer"
+       (when (get-in x [:nextjournal/opts :fragment-item?]) "fragment-item")
+       (when viewer-name (name viewer-name))
+       (when inner-viewer-name (name inner-viewer-name))
+       (case (or (viewer/width x)
+                 (case viewer-name
+                   (`viewer/code-viewer) :wide
+                   (`viewer/markdown-node-viewer) :nested-prose
+                   :prose))
+         :wide "w-full max-w-wide"
+         :full "w-full"
+         :nested-prose "w-full max-w-prose"
+         "w-full max-w-prose px-8")])))
+
+(defn render-result [{:as result :nextjournal/keys [fetch-opts hash presented]} {:as opts :keys [id auto-expand-results? path]}]
   (let [!desc (hooks/use-state-with-deps presented [hash])
         !expanded-at (hooks/use-state (when (map? @!desc)
                                         (->expanded-at auto-expand-results? @!desc)))
@@ -324,10 +331,11 @@
     (when @!desc
       [view-context/provide {:fetch-fn fetch-fn}
        [:> ErrorBoundary {:hash hash}
-        [:div.relative
-         [:div.overflow-x-auto
-          {:ref ref-fn}
-          [inspect-presented {:!expanded-at !expanded-at} @!desc]]]]])))
+        [:div.result-viewer {:class (result-css-class @!desc) :data-block-id id :ref ref-fn}
+         [:div.relative
+          [:div.overflow-x-auto
+           {:ref ref-fn}
+           [inspect-presented {:!expanded-at !expanded-at} @!desc]]]]]])))
 
 (defn toggle-expanded [!expanded-at path event]
   (.preventDefault event)
@@ -350,11 +358,11 @@
 (defn expandable? [xs]
   (< 1 (count xs)))
 
-
 (defn inspect-children [opts]
   ;; TODO: move update function onto viewer
   (map-indexed (fn [idx x]
-                 (inspect-presented (update opts :path (fnil conj []) idx) x))))
+                 (cond-> [inspect-presented (update opts :path (fnil conj []) idx) x]
+                   (get-in x [:nextjournal/opts :id]) (with-meta {:key (str (get-in x [:nextjournal/opts :id]) "@" @!eval-counter)})))))
 
 (def expand-style
   ["cursor-pointer"
@@ -711,6 +719,9 @@
   (when react-root
     (.render react-root (r/as-element [root]))))
 
+(defn render-with-react-key [x {:as _opts :keys [id]}]
+  (with-meta x {:key id}))
+
 (defn html-render [markup]
   (r/as-element
    (if (string? markup)
@@ -810,7 +821,12 @@
   [:svg {:xmlns "http://www.w3.org/2000/svg" :viewBox "0 0 20 20" :fill "currentColor" :width 12 :height 12}
    [:path {:fill-rule "evenodd" :d "M5.293 7.293a1 1 0 011.414 0L10 10.586l3.293-3.293a1 1 0 111.414 1.414l-4 4a1 1 0 01-1.414 0l-4-4a1 1 0 010-1.414z" :clip-rule "evenodd"}]])
 
-(defn render-folded-code [code-string]
+(defn render-code-block [code-string {:keys [id]}]
+  ^{:key id}
+  [:div.viewer.code-viewer.w-full.max-w-wide {:data-block-id id}
+   [code/render-code code-string]])
+
+(defn render-folded-code-block [code-string {:keys [id]}]
   (let [!hidden? (hooks/use-state true)]
     (if @!hidden?
       [:div.relative.pl-12.font-sans.text-slate-400.cursor-pointer.flex.overflow-y-hidden.group
@@ -842,7 +858,8 @@
         [:span.ml-4.opacity-0.translate-y-full.group-hover:opacity-100.group-hover:translate-y-0.transition-all.delay-150.hover:text-slate-500
          {:class "text-[10px]"}
          "evaluated in 0.2s"]]
-       [:div.code-viewer.mb-2.relative {:style {:margin-top 0}}
+       ^{:key id}
+       [:div.code-viewer.mb-2.relative.code-viewer.w-full.max-w-wide {:data-block-id id :style {:margin-top 0}}
         [render-code code-string]]])))
 
 

src/nextjournal/clerk/render/code.cljs

@@ -87,13 +87,14 @@
                   (< pos to)
                   (concat [(.sliceString text pos to)]))))))))
 
-(defn render-code [^String code]
+(defn render-code [^String code {:as _opts :keys [id]}]
   (let [builder (RangeSetBuilder.)
         _ (highlightTree (.. clojureLanguage -parser (parse code)) highlight-style
                          (fn [from to style]
                            (.add builder from to (.mark Decoration (j/obj :class style)))))
         decorations-rangeset (.finish builder)
         text (.of Text (.split code "\n"))]
+    ^{:key id}
     [:div.cm-editor
      [:cm-scroller
       (into [:div.cm-content.whitespace-pre]

src/nextjournal/clerk/static_app.cljs

@@ -30,21 +30,22 @@
    :nextjournal/value hiccup})
 
 (defn show [{:as view-data :git/keys [sha url] :keys [bundle? doc path url->path]}]
-  (let [header [:div.mb-8.text-xs.sans-serif.text-gray-400.not-prose
-                (when (not= "" path)
-                  [:<>
-                   [:a.hover:text-indigo-500.dark:hover:text-white.font-medium.border-b.border-dotted.border-gray-300
-                    {:href (doc-url view-data "")} "Back to index"]
-                   [:span.mx-1 "/"]])
-                [:span
-                 "Generated with "
-                 [:a.hover:text-indigo-500.dark:hover:text-white.font-medium.border-b.border-dotted.border-gray-300
-                  {:href "https://github.com/nextjournal/clerk"} "Clerk"]
-                 (when (and url sha (contains? url->path path))
+  (let [header [:div.viewer.w-full.max-w-prose.px-8
+                [:div.mb-8.text-xs.sans-serif.text-gray-400.not-prose
+                 (when (not= "" path)
                    [:<>
-                    " from "
                     [:a.hover:text-indigo-500.dark:hover:text-white.font-medium.border-b.border-dotted.border-gray-300
-                     {:href (str url "/blob/" sha "/" (url->path path))} (url->path path) "@" [:span.tabular-nums (subs sha 0 7)]]])]]]
+                     {:href (doc-url view-data "")} "Back to index"]
+                    [:span.mx-1 "/"]])
+                 [:span
+                  "Generated with "
+                  [:a.hover:text-indigo-500.dark:hover:text-white.font-medium.border-b.border-dotted.border-gray-300
+                   {:href "https://github.com/nextjournal/clerk"} "Clerk"]
+                  (when (and url sha (contains? url->path path))
+                    [:<>
+                     " from "
+                     [:a.hover:text-indigo-500.dark:hover:text-white.font-medium.border-b.border-dotted.border-gray-300
+                      {:href (str url "/blob/" sha "/" (url->path path))} (url->path path) "@" [:span.tabular-nums (subs sha 0 7)]]])]]]]
     (render/set-state! {:doc (cond-> (assoc doc :bundle? bundle?)
                                (vector? (get-in doc [:nextjournal/value :blocks]))
                                (update-in [:nextjournal/value :blocks] (partial into [(hiccup header)])))})