# `Clarity.Content`
[🔗](https://github.com/team-alembic/clarity/blob/v0.5.1/lib/clarity/content.ex#L1)

Behavior and struct for content providers that display information about vertices.

Content providers decide whether they should be displayed for a given vertex and lens,
and can provide either static content (markdown, mermaid, graphviz) or implement a
full LiveView for interactive content.

## Static Content Providers

Static content providers implement the `c:render_static/2` callback:

    defmodule MyApp.CustomContent do
      @behaviour Clarity.Content

      @impl Clarity.Content
      def name, do: "Custom Analysis"

      @impl Clarity.Content
      def description, do: "Provides custom analysis for resources"

      @impl Clarity.Content
      def applies?(%Vertex.Ash.Resource{}, _lens), do: true
      def applies?(_vertex, _lens), do: false

      @impl Clarity.Content
      def render_static(vertex, _lens) do
        {:markdown, "# Analysis for #{inspect(vertex)}"}
      end
    end

## LiveView Content Providers

Content providers can also be LiveView modules. Simply implement `Phoenix.LiveView`
alongside the `Clarity.Content` behavior:

    defmodule MyApp.InteractiveContent do
      use Phoenix.LiveView
      @behaviour Clarity.Content

      @impl Clarity.Content
      def name, do: "Interactive Dashboard"

      @impl Clarity.Content
      def description, do: "Interactive visualization"

      @impl Clarity.Content
      def applies?(%Vertex.Ash.Resource{}, _lens), do: true
      def applies?(_vertex, _lens), do: false

      @impl Phoenix.LiveView
      def mount(_params, session, socket) do
        vertex = session["vertex"]
        lens = session["lens"]
        {:ok, assign(socket, vertex: vertex, lens: lens)}
      end

      @impl Phoenix.LiveView
      def render(assigns) do
        ~H"""
        <div>Interactive content for {@vertex}</div>
        """
      end
    end

## Configuration

Content provider configuration is managed by `Clarity.Config`. See the documentation
for `Clarity.Config` for detailed configuration options and examples.

# `provider`

```elixir
@type provider() :: module()
```

A module implementing the `Clarity.Content` behavior

# `rendered_static_content`

```elixir
@type rendered_static_content() ::
  {static_content_type(), (static_content_props() -&gt; iodata())}
```

# `static_content`

```elixir
@type static_content() ::
  {static_content_type(), iodata() | (static_content_props() -&gt; iodata())}
```

# `static_content_props`

```elixir
@type static_content_props() :: %{theme: theme(), zoom_subgraph: Clarity.Graph.t()}
```

# `static_content_type`

```elixir
@type static_content_type() :: :markdown | :mermaid | :viz
```

# `t`

```elixir
@type t() :: %Clarity.Content{
  description: String.t() | nil,
  id: String.t(),
  live_component?: boolean(),
  live_view?: boolean(),
  name: String.t(),
  provider: provider(),
  render_static: rendered_static_content() | nil,
  sort_priority: integer()
}
```

Content struct representing a content provider instance for a specific vertex and lens.

# `theme`

```elixir
@type theme() :: :light | :dark
```

# `applies?`

```elixir
@callback applies?(vertex :: Clarity.Vertex.t(), lens :: Clarity.Perspective.Lens.t()) ::
  boolean()
```

Determines whether this content should be displayed for the given vertex and lens.

Return `true` to show this content, `false` to hide it.

# `description`

```elixir
@callback description() :: String.t() | nil
```

Returns an optional description of this content provider.

This may be used in tooltips or help text.

# `name`

```elixir
@callback name() :: String.t()
```

Returns the name of this content provider.

This is displayed as the tab name in the UI.

# `render_static`
*optional* 

```elixir
@callback render_static(
  vertex :: Clarity.Vertex.t(),
  lens :: Clarity.Perspective.Lens.t()
) ::
  static_content()
```

Renders static content for the given vertex and lens.

Returns a tuple of `{type, content}` where:
- `:markdown` - Markdown text (iodata or function returning iodata)
- `:mermaid` - Mermaid diagram (iodata or function returning iodata)
- `:viz` - Graphviz DOT format (iodata or function returning iodata, or function taking theme map)

# `sort_priority`
*optional* 

```elixir
@callback sort_priority() :: integer()
```

Returns the sort priority for this content provider.

Lower values sort first. The default is `0`. Use negative values to sort
before other content (e.g., overview tabs), and positive values to sort
after (e.g., graph navigation).

---

*Consult [api-reference.md](api-reference.md) for complete listing*