feat(clarity): Clarity content provider for state diagrams

documentation/topics/charts.md

@@ -18,3 +18,12 @@ on_its_way --> error: error
 confirmed --> error: error
 pending --> error: error
 ```
+
+## Clarity integration
+
+If [`clarity`](https://hex.pm/packages/clarity) is a dependency of your
+project, every resource that uses `AshStateMachine` automatically gains
+a "State Machine" tab in the Clarity UI rendering the live Mermaid
+diagram. No configuration is required — the content provider is
+registered via the library's own application environment and
+discovered by Clarity on startup.

lib/clarity/state_machine_diagram.ex

@@ -0,0 +1,51 @@
+# SPDX-FileCopyrightText: 2023 ash_state_machine contributors <https://github.com/ash-project/ash_state_machine/graphs/contributors>
+#
+# SPDX-License-Identifier: MIT
+
+with {:module, _} <- Code.ensure_loaded(Clarity.Content),
+     {:module, _} <- Code.ensure_loaded(Clarity.Vertex.Ash.Resource) do
+  defmodule AshStateMachine.Clarity.StateMachineDiagram do
+    @moduledoc """
+    Clarity content provider that renders a Mermaid state diagram for any
+    Ash resource that uses `AshStateMachine`.
+
+    This module is only compiled when [`:clarity`](https://hex.pm/packages/clarity)
+    is a dependency of the current project. When it is, the module is
+    registered as a content provider via the `:clarity_content_providers`
+    key in this library's `application/0` environment and is discovered
+    automatically by Clarity — no configuration required in the host app.
+
+    The rendered diagram is produced by
+    `AshStateMachine.Charts.mermaid_state_diagram/1` — the same function
+    backing `mix ash_state_machine.generate_flow_charts` — so the UI is
+    always in lock-step with the DSL.
+    """
+
+    @behaviour Clarity.Content
+
+    alias Clarity.Vertex.Ash.Resource
+
+    @impl Clarity.Content
+    def name, do: "State Machine"
+
+    @impl Clarity.Content
+    def description, do: "Mermaid state diagram generated from the AshStateMachine DSL."
+
+    @impl Clarity.Content
+    def applies?(%Resource{resource: resource}, _lens),
+      do: uses_state_machine?(resource)
+
+    def applies?(_vertex, _lens), do: false
+
+    @impl Clarity.Content
+    def render_static(%Resource{resource: resource}, _lens) do
+      {:mermaid, fn _props -> AshStateMachine.Charts.mermaid_state_diagram(resource) end}
+    end
+
+    defp uses_state_machine?(resource) do
+      Code.ensure_loaded?(resource) and AshStateMachine in Spark.extensions(resource)
+    rescue
+      _ -> false
+    end
+  end
+end

mix.exs

@@ -133,14 +133,20 @@ defmodule AshStateMachine.MixProject do
   # Run "mix help compile.app" to learn about applications.
   def application do
     [
-      extra_applications: [:logger]
+      extra_applications: [:logger],
+      env: [
+        clarity_content_providers: [
+          AshStateMachine.Clarity.StateMachineDiagram
+        ]
+      ]
     ]
   end
 
   # Run "mix help deps" to learn about dependencies.
   defp deps do
     [
       {:ash, ash_version("~> 3.0 and >= 3.4.66")},
+      {:clarity, "~> 0.3", optional: true},
       {:igniter, "~> 0.5", only: [:dev, :test]},
       {:simple_sat, "~> 0.1", only: [:dev, :test], runtime: false},
       {:ex_doc, "~> 0.36", only: [:dev, :test]},