From 02b127b4db1c1a9e8fb2633bf87dc584fabc1226 Mon Sep 17 00:00:00 2001
From: Chris Keele <christhekeele@gmail.com>
Date: Sun, 13 Oct 2024 17:41:13 -0500
Subject: [PATCH] Add captions to `Kino.Process` diagrams, normalize `opts` var
 name.

---
 lib/kino/mermaid.ex | 12 ++++-----
 lib/kino/process.ex | 59 +++++++++++++++++++++++++++++++--------------
 2 files changed, 47 insertions(+), 24 deletions(-)

diff --git a/lib/kino/mermaid.ex b/lib/kino/mermaid.ex
index f94ebe04..5f57bd0a 100644
--- a/lib/kino/mermaid.ex
+++ b/lib/kino/mermaid.ex
@@ -44,22 +44,22 @@ defmodule Kino.Mermaid do
 
   """
   @spec new(binary(), Keyword.t()) :: t()
-  def new(diagram, options \\ []) do
-    options = Keyword.validate!(options, caption: false, download: true)
+  def new(diagram, opts \\ []) do
+    opts = Keyword.validate!(opts, caption: false, download: true)
 
     download =
-      if download = Keyword.fetch!(options, :download) do
+      if download = Keyword.fetch!(opts, :download) do
         case download do
           true ->
             @download_defaults
 
-          download_options when is_list(download_options) ->
-            Keyword.validate!(download_options, @download_defaults)
+          download_opts when is_list(download_opts) ->
+            Keyword.validate!(download_opts, @download_defaults)
         end
         |> Map.new()
       end
 
-    caption = Keyword.fetch!(options, :caption)
+    caption = Keyword.fetch!(opts, :caption)
 
     Kino.JS.new(__MODULE__, %{diagram: diagram, caption: caption, download: download},
       export: fn diagram -> {"mermaid", diagram} end
diff --git a/lib/kino/process.ex b/lib/kino/process.ex
index b5d7cb50..d7ca976a 100644
--- a/lib/kino/process.ex
+++ b/lib/kino/process.ex
@@ -35,6 +35,9 @@ defmodule Kino.Process do
     * `:render_ets_tables` - determines whether ETS tables associated with the
       supervision tree are rendered. Defaults to `false`.
 
+    * `:caption` - an optional caption for the diagram.
+      Defaults to the provided `application` name.
+
   ## Examples
 
   To view the applications running in your instance run:
@@ -86,13 +89,18 @@ defmodule Kino.Process do
     {:dictionary, dictionary} = process_info(root_supervisor, :dictionary)
     [ancestor] = dictionary[:"$ancestors"]
 
-    Mermaid.new("""
-    graph #{direction};
-    application_master(#{inspect(master)}):::supervisor ---> supervisor_ancestor;
-    supervisor_ancestor(#{inspect(ancestor)}):::supervisor ---> 0;
-    #{edges}
-    #{@mermaid_classdefs}
-    """)
+    caption = Keyword.get(opts, :caption, "Application tree for #{inspect(application)}")
+
+    Mermaid.new(
+      """
+      graph #{direction};
+      application_master(#{inspect(master)}):::supervisor ---> supervisor_ancestor;
+      supervisor_ancestor(#{inspect(ancestor)}):::supervisor ---> 0;
+      #{edges}
+      #{@mermaid_classdefs}
+      """,
+      caption: caption
+    )
   end
 
   @doc """
@@ -108,6 +116,9 @@ defmodule Kino.Process do
     * `:direction` - defines the direction of the graph visual. The
       value can either be `:top_down` or `:left_right`. Defaults to `:top_down`.
 
+    * `:caption` - an optional caption for the diagram.
+      Defaults to the provided `supervisor`.
+
   ## Examples
 
   With a supervisor definition like so:
@@ -161,12 +172,16 @@ defmodule Kino.Process do
       end
 
     edges = traverse_supervisor(supervisor_pid, opts)
+    caption = Keyword.get(opts, :caption, "Supervisor tree for #{inspect(supervisor)}")
 
-    Mermaid.new("""
-    graph #{direction};
-    #{edges}
-    #{@mermaid_classdefs}
-    """)
+    Mermaid.new(
+      """
+      graph #{direction};
+      #{edges}
+      #{@mermaid_classdefs}
+      """,
+      caption: caption
+    )
   end
 
   @doc """
@@ -236,6 +251,9 @@ defmodule Kino.Process do
       is used. However, if the function returns a `String.t()`, then
       that will be used for the label.
 
+    * `:caption` - an optional caption for the diagram.
+      Defaults to the provided `trace_target`.
+
   ## Examples
 
   To generate a trace of all the messages occurring during the execution of the
@@ -412,13 +430,18 @@ defmodule Kino.Process do
       |> Enum.reverse()
       |> Enum.join("\n")
 
+    caption = Keyword.get(opts, :caption, "Messages traced from #{inspect(trace_pids)}")
+
     sequence_diagram =
-      Mermaid.new("""
-      %%{init: {'themeCSS': '.actor:last-of-type:not(:only-of-type) {dominant-baseline: hanging;}'} }%%
-      sequenceDiagram
-      #{participants}
-      #{messages}
-      """)
+      Mermaid.new(
+        """
+        %%{init: {'themeCSS': '.actor:last-of-type:not(:only-of-type) {dominant-baseline: hanging;}'} }%%
+        sequenceDiagram
+        #{participants}
+        #{messages}
+        """,
+        caption: caption
+      )
 
     {func_result, sequence_diagram}
   end