## Events

Track product events with `MyApp.Events.track/2`:

```elixir

Events.track("user.signed_up", user: user)

Events.track("user.confirmed", user: user, metadata: %{"source" => "magic_link"})

```

Events are automatically tracked for user registration and email confirmation. The admin dashboard at `/admin` displays stat cards, bar charts, stacked charts, and a conversion funnel. A real-time event feed is available at `/admin/events`.

To extend the system, implement the `MyApp.Events.Handler` behaviour and register it in config:

```elixir

config :my_app, MyApp.Events, handlers: [MyApp.SomeHandler]

```

Seed demo data with `mix run priv/repo/seeds.exs`.

import BarHook from "./hooks/bar_hook"

import FunnelHook from "./hooks/funnel_hook"

import PieHook from "./hooks/pie_hook"

  hooks: {...colocatedHooks, CopyToClipboard: CopyToClipboardHook(), Bar: BarHook, Funnel: FunnelHook, Pie: PieHook},

function formatLabel(label) {

  if (/^\d{4}-\d{2}-\d{2}$/.test(label)) {

    const d = new Date(label + "T00:00:00")

    return d.toLocaleDateString("en-GB", {

      weekday: "short", day: "numeric", month: "short", year: "numeric"

    })

  }

  if (/^\d{4}-\d{2}(-01)?$/.test(label)) {

    const d = new Date(label.slice(0, 7) + "-15T00:00:00")

    return d.toLocaleDateString("en-GB", { month: "long", year: "numeric" })

  }

  return label

}

const BarHook = {

  mounted() {

    this.tooltip = this.el.querySelector("[data-bar-tooltip]")

    this.sections = this.el.querySelectorAll("[data-bar-section]")

    for (const section of this.sections) {

      section.addEventListener("mouseenter", (e) => this.showTooltip(e, section))

      section.addEventListener("mousemove", (e) => this.positionTooltip(e))

      section.addEventListener("mouseleave", () => this.hideTooltip())

    }

  },

  showTooltip(e, section) {

    const dateLabel = section.dataset.barLabel

    const count = section.dataset.barCount

    const dataset = section.dataset.barDataset

    const titleEl = this.tooltip.querySelector("[data-tooltip-title]")

    const valueEl = this.tooltip.querySelector("[data-tooltip-value]")

    titleEl.textContent = formatLabel(dateLabel)

    if (dataset) {

      valueEl.textContent = `${dataset}: ${count}`

    } else {

      valueEl.textContent = count

    }

    this.tooltip.classList.remove("hidden")

    this.positionTooltip(e)

  },

  positionTooltip(e) {

    const rect = this.el.getBoundingClientRect()

    const x = e.clientX - rect.left

    const y = e.clientY - rect.top

    this.tooltip.style.left = x + "px"

    this.tooltip.style.top = (y - 8) + "px"

  },

  hideTooltip() {

    this.tooltip.classList.add("hidden")

  },

  destroyed() {}

}

export default BarHook

const FunnelHook = {

  mounted() {

    this.tooltip = this.el.querySelector("[data-funnel-tooltip]")

    this.sections = this.el.querySelectorAll("[data-funnel-section]")

    for (const section of this.sections) {

      section.addEventListener("mouseenter", (e) => this.showTooltip(e, section))

      section.addEventListener("mousemove", (e) => this.positionTooltip(e))

      section.addEventListener("mouseleave", () => this.hideTooltip())

    }

  },

  showTooltip(e, section) {

    const label = section.dataset.funnelLabel

    const count = section.dataset.funnelCount

    const rate = section.dataset.funnelRate

    this.tooltip.querySelector("[data-tooltip-label]").textContent = label

    this.tooltip.querySelector("[data-tooltip-count]").textContent = count

    this.tooltip.querySelector("[data-tooltip-rate]").textContent = rate + "%"

    this.tooltip.classList.remove("hidden")

    this.positionTooltip(e)

  },

  positionTooltip(e) {

    const rect = this.el.getBoundingClientRect()

    const x = e.clientX - rect.left

    const y = e.clientY - rect.top

    this.tooltip.style.left = x + "px"

    this.tooltip.style.top = (y - 8) + "px"

  },

  hideTooltip() {

    this.tooltip.classList.add("hidden")

  },

  destroyed() {}

}

export default FunnelHook

const PieHook = {

  mounted() {

    this.tooltip = this.el.querySelector("[data-pie-tooltip]")

    this.sections = this.el.querySelectorAll("[data-pie-section]")

    for (const section of this.sections) {

      section.addEventListener("mouseenter", (e) => this.showTooltip(e, section))

      section.addEventListener("mousemove", (e) => this.positionTooltip(e))

      section.addEventListener("mouseleave", () => this.hideTooltip())

    }

  },

  showTooltip(e, section) {

    const label = section.dataset.pieLabel

    const count = section.dataset.pieCount

    const pct = section.dataset.piePct

    this.tooltip.querySelector("[data-tooltip-label]").textContent = label

    this.tooltip.querySelector("[data-tooltip-count]").textContent = count

    this.tooltip.querySelector("[data-tooltip-pct]").textContent = pct + "%"

    this.tooltip.classList.remove("hidden")

    this.positionTooltip(e)

  },

  positionTooltip(e) {

    const rect = this.el.getBoundingClientRect()

    const x = e.clientX - rect.left

    const y = e.clientY - rect.top

    this.tooltip.style.left = x + "px"

    this.tooltip.style.top = (y - 8) + "px"

  },

  hideTooltip() {

    this.tooltip.classList.add("hidden")

  },

  destroyed() {}

}

export default PieHook

  alias MyApp.Events

    with {:ok, user} <- %User{} |> User.email_changeset(attrs) |> Repo.insert() do

      Events.track("user.signed_up", user: user)

      {:ok, user}

    end

        with {:ok, {user, tokens}} <-

               user

               |> User.confirm_changeset()

               |> update_user_and_delete_all_tokens() do

          Events.track("user.confirmed", user: user)

          {:ok, {user, tokens}}

        end

defmodule MyApp.Events do

  @moduledoc """

  Context for tracking and querying product events.

  ## Tracking events

      MyApp.Events.track("user.signed_up", user: user)

      MyApp.Events.track("user.confirmed", user: user)

  ## Subscribing to events

  Other modules can subscribe to events by implementing the `MyApp.Events.Handler`

  behaviour and registering in config:

      config :my_app, MyApp.Events, handlers: [MyApp.SomeHandler]

  Handlers receive the persisted event after insert and run synchronously.

  """

  require Logger

  alias MyApp.Repo

  alias MyApp.Events.Event

  @doc """

  Tracks a named event.

  ## Options

    * `:user` - user struct

    * `:organization_id` - binary_id of the organization (optional)

    * `:metadata` - map of arbitrary metadata (optional)

  """

  def track(name, opts) when is_binary(name) do

    user =

      Keyword.get(opts, :user) ||

        raise "Events.track/2 missing :user opt, events must be tracked to a user"

    attrs = %{

      name: name,

      organization_id: Keyword.get(opts, :organization_id),

      metadata: Keyword.get(opts, :metadata, %{})

    }

    %Event{user: user}

    |> Event.changeset(attrs)

    |> Repo.insert()

    |> case do

      {:ok, event} ->

        broadcast(event)

        notify_handlers(event)

        :ok

      {:error, reason} ->

        Logger.error("Events.track/2 failed to track event: #{inspect(reason)}")

        :ok

    end

  end

  defp notify_handlers(event) do

    config = Application.get_env(:my_app, __MODULE__, [])

    for handler <- Keyword.get(config, :handlers, []) do

      handler.handle_event(event)

    end

  end

  @doc """

  Subscribes the caller to real-time event notifications.

  """

  def subscribe do

    Phoenix.PubSub.subscribe(MyApp.PubSub, "events")

  end

  @doc """

  Broadcasts a new event to all subscribers.

  """

  def broadcast(event) do

    Phoenix.PubSub.broadcast(MyApp.PubSub, "events", {:event_created, event})

  end

end

defmodule MyApp.Events.Catalog do

  @moduledoc """

  Static definitions of event display properties.

  Maps event names to their title, icon, and description function.

  The description function receives the event struct and returns a string.

  ## Example

      catalog = MyApp.Events.Catalog.get("user.signed_up")

      catalog.title

      #=> "User Signed Up"

      catalog.description.(event)

      #=> "user@example.com created an account"

  """

  alias MyApp.Events.Event

  defstruct [:title, :icon, :description]

  @type t :: %__MODULE__{

          title: String.t() | nil,

          icon: String.t() | nil,

          description: (Event.t() -> String.t() | nil)

        }

  @doc """

  Returns the catalog entry for the given event name.

  """

  @spec get(String.t()) :: t()

  def get("user.signed_up") do

    %__MODULE__{

      title: "User Signed Up",

      icon: "🎉",

      description: fn e -> user_label(e) <> " created an account" end

    }

  end

  def get("user.confirmed") do

    %__MODULE__{

      title: "Email Confirmed",

      icon: "✅",

      description: fn e -> user_label(e) <> " confirmed their email" end

    }

  end

  def get(_name) do

    %__MODULE__{

      title: nil,

      icon: nil,

      description: fn _ -> nil end

    }

  end

  defp user_label(%Event{user: %{email: email}}), do: email

  defp user_label(%Event{user_id: id}) when not is_nil(id), do: id

  defp user_label(_), do: "Someone"

end

defmodule MyApp.Events.Event do

  use Ecto.Schema

  import Ecto.Changeset

  @name_format ~r/^[a-z0-9]+(\.[a-z0-9_]+)*$/

  @primary_key {:id, :binary_id, autogenerate: true}

  @foreign_key_type :binary_id

  schema "events" do

    field :name, :string

    field :metadata, :map, default: %{}

    belongs_to :user, MyApp.Accounts.User

    field :organization_id, :binary_id

    timestamps(updated_at: false, type: :utc_datetime)

  end

  def changeset(event, attrs) do

    event

    |> cast(attrs, [:name, :metadata, :user_id, :organization_id])

    |> validate_required([:name])

    |> validate_format(:name, @name_format)

  end

end

defmodule MyApp.Events.Handler do

  @moduledoc """

  Behaviour for modules that react to tracked events.

  ## Example

      defmodule MyApp.Notifications.EventHandler do

        @behaviour MyApp.Events.Handler

        @impl true

        def handle_event(%MyApp.Events.Event{name: "user.signed_up"} = event) do

          # Send welcome notification, etc.

          :ok

        end

        def handle_event(_event), do: :ok

      end

  Then register in config:

      config :my_app, MyApp.Events, handlers: [MyApp.Notifications.EventHandler]

  """

  @callback handle_event(MyApp.Events.Event.t()) :: :ok | {:error, term()}

end

defmodule MyAppAdmin.Query.Events do

  @moduledoc """

  Admin queries for event data: listing, detail, and chart analytics.

  Chart buckets and stat windows read on the admin clock: a "day" is a

  `MyAppAdmin.Timezone` calendar day, matching rendered timestamps.

  """

  import Ecto.Query

  require MyAppAdmin.Timezone, as: Timezone

  alias MyApp.Repo

  alias MyApp.Events.{Catalog, Event}

  @doc """

  Gets a single event by ID. Raises if not found.

  """

  def get_event!(id) do

    Event

    |> Repo.get!(id)

    |> Repo.preload(:user)

  end

  @doc """

  Returns the latest events, ordered by most recent first.

  ## Options

    * `:name` - filter by event name

    * `:user_id` - filter by user ID

    * `:date` - filter to a single admin-timezone calendar day

    * `:limit` - max events to return (default 100)

  """

  def list_latest(opts \\ []) do

    limit = Keyword.get(opts, :limit, 100)

    from(e in Event,

      order_by: [desc: e.inserted_at],

      limit: ^limit,

      preload: [:user]

    )

    |> filter_by_name(Keyword.get(opts, :name))

    |> filter_by_user(Keyword.get(opts, :user_id))

    |> filter_by_date(Keyword.get(opts, :date))

    |> Repo.all()

  end

  @doc "Events per admin-timezone day for a user in a date range: %{Date => count}."

  def activity_by_day(user_id, from_date, to_date) do

    from(e in Event,

      where: e.user_id == ^user_id,

      where: Timezone.local_date(e.inserted_at) >= ^from_date,

      where: Timezone.local_date(e.inserted_at) <= ^to_date,

      group_by: Timezone.local_date(e.inserted_at),

      select: {Timezone.local_date(e.inserted_at), count(e.id)}

    )

    |> Repo.all()

    |> Map.new()

  end

  @doc "A user's all-time event counts by name, descending."

  def counts_by_name(user_id, limit \\ 6) do

    Repo.all(

      from(e in Event,

        where: e.user_id == ^user_id,

        group_by: e.name,

        order_by: [desc: count(e.id)],

        limit: ^limit,

        select: {e.name, count(e.id)}

      )

    )

  end

  defp filter_by_name(query, nil), do: query

  defp filter_by_name(query, ""), do: query

  defp filter_by_name(query, name), do: where(query, [e], e.name == ^name)

  defp filter_by_user(query, nil), do: query

  defp filter_by_user(query, ""), do: query

  defp filter_by_user(query, user_id), do: where(query, [e], e.user_id == ^user_id)

  defp filter_by_date(query, nil), do: query

  defp filter_by_date(query, %Date{} = date),

    do: where(query, [e], Timezone.local_date(e.inserted_at) == ^date)

  @doc """

  Returns a map with aggregate counts and period-over-period change.

      metric = aggregate("user.signed_up", ~D[2026-02-04], ~D[2026-03-05])

      metric.current  #=> 42

      metric.previous #=> 38

      metric.change   #=> 10.5

  """

  def aggregate(name, from_date, to_date) do

    days = Date.diff(to_date, from_date)

    prev_to = Date.add(from_date, -1)

    prev_from = Date.add(prev_to, -days)

    by_day = count_by_day(name, from_date, to_date)

    prev_by_day = count_by_day(name, prev_from, prev_to)

    current = Enum.reduce(by_day, 0, fn {_, c}, acc -> acc + c end)

    previous = Enum.reduce(prev_by_day, 0, fn {_, c}, acc -> acc + c end)

    change =

      if previous > 0,

        do: Float.round((current - previous) / previous * 100, 1),

        else: 0.0

    %{

      current: current,

      previous: previous,

      change: change,

      by_day: by_day,

      prev_by_day: prev_by_day

    }

  end

  @doc """

  Returns data shaped for a `<.bar_chart>` component.

  ## Options

    * `:period` - `:day` (default) or `:month`

  """

  def bar_chart(name, from_date, to_date, opts \\ []) do

    period = Keyword.get(opts, :period, :day)

    {data, prev_data} =

      case period do

        :day ->

          metric = aggregate(name, from_date, to_date)

          {metric.by_day, metric.prev_by_day}

        :month ->

          months = months_between(from_date, to_date)

          prev_months =

            months_between(shift_months(from_date, -length(months)), Date.add(from_date, -1))

          {count_by_month(name, months), count_by_month(name, prev_months)}

      end

    current = Enum.reduce(data, 0, fn {_, c}, acc -> acc + c end)

    previous = Enum.reduce(prev_data, 0, fn {_, c}, acc -> acc + c end)

    change =

      if previous > 0,

        do: Float.round((current - previous) / previous * 100, 1),

        else: 0.0

    %{

      data: data,

      period: period,

      stat_value: current,

      stat_change: change,

      stat_prev_value: previous

    }

  end

  @doc """

  Returns data shaped for a `<.stacked_bar_chart>` component.

  Uses catalog titles as dataset labels.

  """

  def stacked_bar_chart(names, from_date, to_date) do

    by_day = count_multiple_by_day(names, from_date, to_date)

    first = hd(names)

    labels =

      case by_day do

        %{^first => pairs} -> Enum.map(pairs, fn {date, _} -> to_string(date) end)

        _ -> []

      end

    datasets =

      Enum.map(names, fn name ->

        %{

          label: Catalog.get(name).title || name,

          data: Enum.map(by_day[name], &elem(&1, 1))

        }

      end)

    %{labels: labels, datasets: datasets}

  end

  @doc """

  Returns data shaped for a `<.pie_chart>` component.

  With a date range, includes period-over-period stats so the chart can

  render a "N in the last X days (±Y%)" subtitle (matching `bar_chart/3,4`).

  Without one, returns just `data` + `stat_value` — the chart's subtitle

  then falls back to "N total".

  """

  def pie_chart(names, from_date \\ nil, to_date \\ nil)

  def pie_chart(names, nil, nil) do

    data = slice_data(names, count_by_name(names))

    %{data: data, stat_value: Enum.reduce(data, 0, fn s, acc -> acc + s.count end)}

  end

  def pie_chart(names, from_date, to_date) do

    days = Date.diff(to_date, from_date) + 1

    prev_to = Date.add(from_date, -1)

    prev_from = Date.add(prev_to, days - 1)

    data = slice_data(names, count_by_name(names, from_date, to_date))

    prev_counts = count_by_name(names, prev_from, prev_to)

    current = Enum.reduce(data, 0, fn s, acc -> acc + s.count end)

    previous = Enum.reduce(names, 0, fn n, acc -> acc + Map.get(prev_counts, n, 0) end)

    change =

      if previous > 0,

        do: Float.round((current - previous) / previous * 100, 1),

        else: 0.0

    %{

      data: data,

      stat_value: current,

      stat_change: change,

      stat_prev_value: previous,

      period_count: days

    }

  end

  defp slice_data(names, counts) do

    Enum.map(names, fn name ->

      %{label: Catalog.get(name).title || name, count: Map.get(counts, name, 0)}

    end)

  end

  defp count_by_name(names, from_date \\ nil, to_date \\ nil) do

    from(e in Event, where: e.name in ^names, group_by: e.name, select: {e.name, count()})

    |> apply_date_range(from_date, to_date)

    |> Repo.all()

    |> Map.new()

  end

  defp apply_date_range(query, nil, nil), do: query

  defp apply_date_range(query, from_date, to_date) do

    from_dt = Timezone.day_start_utc(from_date)

    to_dt = Timezone.day_start_utc(Date.add(to_date, 1))

    where(query, [e], e.inserted_at >= ^from_dt and e.inserted_at < ^to_dt)

  end

  @doc """

  Returns funnel chart steps for a list of sequential event names.

  Each step counts distinct users who performed that event AND all previous

  events. Uses catalog titles as labels when available.

  """

  def funnel_chart(names, from_date, to_date) do

    from_dt = Timezone.day_start_utc(from_date)

    to_dt = Timezone.day_start_utc(Date.add(to_date, 1))

    user_sets =

      Map.new(names, fn name ->

        users =

          from(e in Event,

            where: e.name == ^name,

            where: e.inserted_at >= ^from_dt and e.inserted_at < ^to_dt,

            where: not is_nil(e.user_id),

            distinct: e.user_id,

            select: e.user_id

          )

          |> Repo.all()

          |> MapSet.new()

        {name, users}

      end)

    {steps, _} =

      Enum.map_reduce(names, nil, fn name, acc ->

        current = Map.fetch!(user_sets, name)

        intersected = if acc, do: MapSet.intersection(acc, current), else: current

        label = Catalog.get(name).title || name

        {%{label: label, count: MapSet.size(intersected)}, intersected}

      end)

    steps

  end

  # ------------------------------------------------------------------

  # Internal query helpers

  # ------------------------------------------------------------------

  defp count_by_day(name, from_date, to_date) do

    from_dt = Timezone.day_start_utc(from_date)

    to_dt = Timezone.day_start_utc(Date.add(to_date, 1))

    counts =

      from(e in Event,

        where: e.name == ^name,

        where: e.inserted_at >= ^from_dt and e.inserted_at < ^to_dt,

        group_by: Timezone.local_date(e.inserted_at),

        select: {Timezone.local_date(e.inserted_at), count()}

      )

      |> Repo.all()

      |> Map.new()

    zero_fill(from_date, to_date, counts)

  end

  defp count_multiple_by_day(names, from_date, to_date) do

    from_dt = Timezone.day_start_utc(from_date)

    to_dt = Timezone.day_start_utc(Date.add(to_date, 1))

    rows =

      from(e in Event,

        where: e.name in ^names,

        where: e.inserted_at >= ^from_dt and e.inserted_at < ^to_dt,

        group_by: [e.name, Timezone.local_date(e.inserted_at)],

        select: {e.name, Timezone.local_date(e.inserted_at), count()}

      )

      |> Repo.all()

    by_name =

      Enum.group_by(rows, &elem(&1, 0), fn {_, date, count} -> {date, count} end)

      |> Map.new(fn {name, pairs} -> {name, Map.new(pairs)} end)

    Map.new(names, fn name ->

      {name, zero_fill(from_date, to_date, Map.get(by_name, name, %{}))}

    end)

  end

  defp count_by_month(name, months) do

    from_dt = Timezone.day_start_utc(hd(months))

    last_month = List.last(months)

    to_dt = Timezone.day_start_utc(Date.add(Date.end_of_month(last_month), 1))

    counts =

      from(e in Event,

        where: e.name == ^name,

        where: e.inserted_at >= ^from_dt and e.inserted_at < ^to_dt,

        group_by: Timezone.local_month(e.inserted_at),

        select: {Timezone.local_month(e.inserted_at), count()}

      )

      |> Repo.all()

      |> Map.new()

    Enum.map(months, fn date -> {date, Map.get(counts, date, 0)} end)

  end

  defp months_between(from_date, to_date) do

    first = Date.beginning_of_month(from_date)

    Stream.iterate(first, fn date -> Date.shift(date, month: 1) end)

    |> Enum.take_while(&(Date.compare(&1, to_date) != :gt))

  end

  defp shift_months(date, n), do: Date.shift(date, month: n)

  defp zero_fill(from_date, to_date, counts) do

    Date.range(from_date, to_date)

    |> Enum.map(fn date -> {date, Map.get(counts, date, 0)} end)

  end

end

      import MyAppAdminWeb.ChartComponents

defmodule MyAppAdminWeb.ChartComponents do

  @moduledoc """

  Chart and data visualization components for the admin UI.

  """

  use Phoenix.Component

  import MyAppAdminWeb.CoreComponents, only: [icon: 1]

  # Warm amber gradient shared by stacked bar and funnel charts.

  # Steps from light to dark; wraps if more than 5 series.

  @series_colors [

    "oklch(0.87 0.08 75)",

    "oklch(0.82 0.11 68)",

    "oklch(0.77 0.14 60)",

    "oklch(0.72 0.16 55)",

    "oklch(0.67 0.18 50)"

  ]

  # ------------------------------------------------------------------

  # Chart card wrapper

  # ------------------------------------------------------------------

  @doc """

  Renders a titled card with an icon header and subtitle bar, the shared

  frame for chart and stat panels. With no title, renders a bare card.

  ## Examples

      <.chart_card title="Top Events" icon="hero-trophy-solid">

        <:subtitle>Most frequent events, all time</:subtitle>

        ...

      </.chart_card>

  """

  attr :title, :string, default: nil

  attr :icon, :string, default: "hero-chart-bar-solid"

  slot :subtitle

  slot :inner_block, required: true

  def chart_card(assigns) do

    ~H"""

    <div class={["border border-base-content/5 rounded-box overflow-visible", @title == nil && "p-0"]}>

      <div :if={@title}>

        <div class="flex items-center gap-2.5 px-4 pt-4 pb-3 sm:gap-3 sm:px-6 sm:pt-6 sm:pb-4">

          <div class="flex shrink-0 items-center justify-center size-8 rounded-lg bg-base-content/10 sm:size-10">

            <.icon name={@icon} class="size-4 text-base-content/70 sm:size-5" />

          </div>

          <h3 class="min-w-0 text-base font-bold sm:text-lg">{@title}</h3>

        </div>

        <div class="border-t border-base-content/5 mx-0">

          <p class="flex flex-wrap items-center gap-x-2 gap-y-0.5 px-4 py-3 text-sm text-base-content/70 sm:px-6">

            {render_slot(@subtitle) || Phoenix.HTML.raw(" ")}

          </p>

        </div>

      </div>

      {render_slot(@inner_block)}

    </div>

    """

  end

  # ------------------------------------------------------------------

  # Bar tooltip (shared by bar_chart and stacked_bar_chart)

  # ------------------------------------------------------------------

  defp bar_tooltip(assigns) do

    ~H"""

    <div

      data-bar-tooltip

      class="hidden absolute pointer-events-none -translate-x-1/2 -translate-y-full z-10"

    >

      <div

        class="rounded-xl px-3 py-2 text-sm shadow-lg whitespace-nowrap"

        style="background: oklch(0.15 0 0); border: 1px solid oklch(0.3 0 0)"

      >

        <div data-tooltip-title class="text-neutral-300 text-xs"></div>

        <div data-tooltip-value class="font-semibold text-white mt-0.5"></div>

      </div>

    </div>

    """

  end

  # ------------------------------------------------------------------

  # Bar chart

  # ------------------------------------------------------------------

  @doc """

  Renders a single-series bar chart, optionally as a self-contained card with

  an integrated stat summary (Logsnag-style).

  ## Examples

      <.bar_chart id="signups" data={@signups_by_day} label="Sign ups" />

      <.bar_chart

        id="signups"

        data={@signups_by_day}

        label="Sign ups"

        title="Users Registered"

        stat_value={4852}

        stat_change={-48.0}

        stat_prev_value={9257}

      />

  """

  attr :id, :string, required: true

  attr :data, :list, required: true, doc: "list of {date, count} tuples"

  attr :label, :string, default: ""

  attr :title, :string, default: nil, doc: "card title, enables unified card mode"

  attr :stat_value, :integer, default: nil, doc: "current period total"

  attr :stat_change, :float, default: nil, doc: "percent change vs previous period"

  attr :stat_prev_value, :integer, default: nil, doc: "previous period total"

  attr :period, :atom, default: :day, values: [:day, :month], doc: "time granularity"

  attr :class, :any, default: nil

  def bar_chart(assigns) do

    values = Enum.map(assigns.data, fn {_, count} -> count end)

    max_val = Enum.max(values, fn -> 1 end) |> max(1)

    n = length(values)

    # SVG layout (legend_h pads bottom to match stacked_bar_chart viewBox height)

    vw = 800

    bar_area_h = 160

    label_h = 40

    legend_h = 30

    vh = bar_area_h + label_h + legend_h

    pad_x = 4

    usable_w = vw - pad_x * 2

    bar_gap_ratio = 0.82

    bar_w = if n > 0, do: usable_w / n * bar_gap_ratio, else: 0

    step = if n > 0, do: usable_w / n, else: 0

    bars =

      assigns.data

      |> Enum.with_index()

      |> Enum.map(fn {{date, count}, i} ->

        t = count / max_val

        # Warm color interpolation

        l = Float.round(0.85 - 0.15 * t, 3)

        c = Float.round(0.08 + 0.08 * t, 3)

        h = Float.round(75.0 - 20.0 * t, 1)

        bar_h = max(t * bar_area_h, 2)

        x = pad_x + i * step + (step - bar_w) / 2

        y = bar_area_h - bar_h

        tick =

          case assigns.period do

            :month -> Calendar.strftime(date, "%b")

            :day -> date |> to_string() |> String.split("-") |> List.last() |> String.to_integer()

          end

        %{

          x: f(x),

          y: f(y),

          width: f(bar_w),

          height: f(bar_h),

          color: "oklch(#{l} #{c} #{h})",

          label: to_string(date),

          count: count,

          tick: tick,

          index: i,

          x_center: f(pad_x + i * step + step / 2)

        }

      end)

    tick_interval = if n > 20, do: 3, else: if(n > 10, do: 2, else: 1)

    assigns =

      assigns

      |> assign(:bars, bars)

      |> assign(:vw, vw)

      |> assign(:vh, vh)

      |> assign(:bar_area_h, bar_area_h)

      |> assign(:label_y, f(bar_area_h + 25.0))

      |> assign(:tick_interval, tick_interval)

      |> assign(:formatted_stat, format_number(assigns.stat_value))

    ~H"""

    <.chart_card title={@title}>

      <:subtitle :if={@stat_value}>

        <span class="font-semibold text-base-content">{@formatted_stat}</span>

        <span>{stat_period_label(@period, length(@bars))}</span>

        <span

          :if={@stat_change}

          class={["inline-flex items-center gap-0.5", change_color(@stat_change)]}

        >

          <.icon name={change_icon(@stat_change)} class="size-4" />

          {format_percent(abs(@stat_change))}%

        </span>

        <span :if={@stat_prev_value}>vs {format_number(@stat_prev_value)}</span>

      </:subtitle>

      <div class={["relative px-4 py-4", @class]} id={@id} phx-hook="Bar">

        <svg viewBox={"0 0 #{@vw} #{@vh}"} class="w-full h-full" preserveAspectRatio="xMidYMid meet">

          <rect

            :for={bar <- @bars}

            x={bar.x}

            y={bar.y}

            width={bar.width}

            height={bar.height}

            rx="4"

            fill={bar.color}

            class="transition-all duration-200 cursor-pointer"

            style="filter: brightness(1)"

            onmouseenter="this.style.filter='brightness(1.15)'"

            onmouseleave="this.style.filter='brightness(1)'"

            data-bar-section

            data-bar-label={bar.label}

            data-bar-count={format_number(bar.count)}

          />

          <text

            :for={bar <- @bars}

            :if={rem(bar.index, @tick_interval) == 0}

            x={bar.x_center}

            y={@label_y}

            text-anchor="middle"

            fill="currentColor"

            fill-opacity="0.5"

            font-size="12"

          >

            {bar.tick}

          </text>

        </svg>

        <.bar_tooltip />

      </div>

    </.chart_card>

    """

  end

  # ------------------------------------------------------------------

  # Stacked bar chart

  # ------------------------------------------------------------------

  @doc """

  Renders a multi-series stacked bar chart.

  ## Examples

      <.stacked_bar_chart

        id="events"

        labels={@dates}

        datasets={[%{label: "Sign ups", data: @signups, color: "#4F46E5"}]}

      />

  """

  attr :id, :string, required: true

  attr :labels, :list, required: true, doc: "list of date strings"

  attr :datasets, :list, required: true, doc: "list of %{label, data, color}"

  attr :title, :string, default: nil, doc: "card title, enables unified card mode"

  attr :class, :any, default: nil

  def stacked_bar_chart(assigns) do

    n = length(assigns.labels)

    datasets =

      assigns.datasets

      |> Enum.with_index()

      |> Enum.map(fn {ds, i} ->

        Map.put_new(ds, :color, series_color(i))

      end)

    gap = 4

    # Compute max stacked total across all columns

    max_total =

      0..(n - 1)

      |> Enum.map(fn i ->

        Enum.reduce(datasets, 0, fn ds, acc -> acc + Enum.at(ds.data, i, 0) end)

      end)

      |> Enum.max(fn -> 1 end)

      |> max(1)

    # SVG layout

    vw = 800

    bar_area_h = 160

    label_h = 40

    legend_h = 30

    vh = bar_area_h + label_h + legend_h

    pad_x = 4

    usable_w = vw - pad_x * 2

    bar_gap_ratio = 0.82

    bar_w = if n > 0, do: usable_w / n * bar_gap_ratio, else: 0

    step = if n > 0, do: usable_w / n, else: 0

    # Build stacked rects for each column

    stacked_rects =

      assigns.labels

      |> Enum.with_index()

      |> Enum.flat_map(fn {date_label, col_i} ->

        x = pad_x + col_i * step + (step - bar_w) / 2

        total = Enum.reduce(datasets, 0, fn ds, acc -> acc + Enum.at(ds.data, col_i, 0) end)

        total_h = total / max_total * bar_area_h

        # Stack bottom-up: first dataset is at bottom

        {rects, _} =

          datasets

          |> Enum.reduce({[], 0}, fn ds, {acc, y_offset} ->

            val = Enum.at(ds.data, col_i, 0)

            seg_h = if total > 0, do: val / total * total_h, else: 0

            # Add gap above every segment except the first

            actual_gap = if y_offset > 0 and seg_h > 0, do: gap, else: 0

            y = bar_area_h - y_offset - seg_h - actual_gap

            rect = %{

              x: f(x),

              y: f(y),

              width: f(bar_w),

              height: f(seg_h),

              color: ds.color,

              dataset_label: ds.label,

              value: val,

              date_label: date_label,

              col_index: col_i

            }

            {[rect | acc], y_offset + seg_h + actual_gap}

          end)

        Enum.reverse(rects)

      end)

    tick_interval = if n > 20, do: 3, else: if(n > 10, do: 2, else: 1)

    tick_labels =

      assigns.labels

      |> Enum.with_index()

      |> Enum.filter(fn {_, i} -> rem(i, tick_interval) == 0 end)

      |> Enum.map(fn {iso, i} ->

        day = iso |> String.split("-") |> List.last() |> String.to_integer()

        x_center = pad_x + i * step + step / 2

        %{day: day, x_center: f(x_center)}

      end)

    legend_items =

      datasets

      |> Enum.with_index()

      |> Enum.map(fn {ds, i} ->

        %{label: ds.label, color: ds.color, index: i}

      end)

    legend_y = bar_area_h + label_h + 18

    assigns =

      assigns

      |> assign(:stacked_rects, stacked_rects)

      |> assign(:tick_labels, tick_labels)

      |> assign(:legend_items, legend_items)

      |> assign(:vw, vw)

      |> assign(:vh, vh)

      |> assign(:label_y, f(bar_area_h + 25.0))

      |> assign(:legend_y, legend_y)

    ~H"""

    <.chart_card title={@title}>

      <div class={["relative px-4 py-4", @class]} id={@id} phx-hook="Bar">

        <svg viewBox={"0 0 #{@vw} #{@vh}"} class="w-full h-full" preserveAspectRatio="xMidYMid meet">

          <rect

            :for={rect <- @stacked_rects}

            x={rect.x}

            y={rect.y}

            width={rect.width}

            height={rect.height}

            rx="4"

            fill={rect.color}

            class="transition-all duration-200 cursor-pointer"

            style="filter: brightness(1)"

            onmouseenter="this.style.filter='brightness(1.15)'"

            onmouseleave="this.style.filter='brightness(1)'"

            data-bar-section

            data-bar-label={rect.date_label}

            data-bar-count={format_number(rect.value)}

            data-bar-dataset={rect.dataset_label}

          />

          <text

            :for={tick <- @tick_labels}

            x={tick.x_center}

            y={@label_y}

            text-anchor="middle"

            fill="currentColor"

            fill-opacity="0.5"

            font-size="12"

          >

            {tick.day}

          </text>

          <.stacked_legend

            :for={item <- @legend_items}

            item={item}

            y={@legend_y}

            vw={@vw}

            total={length(@legend_items)}

          />

        </svg>

        <.bar_tooltip />

      </div>

    </.chart_card>

    """

  end

  defp stacked_legend(assigns) do

    spacing = 180

    total_w = assigns.total * spacing

    start_x = (assigns.vw - total_w) / 2 + spacing / 2

    x = start_x + assigns.item.index * spacing

    assigns =

      assigns

      |> assign(:cx, f(x - 8))

      |> assign(:tx, f(x))

      |> assign(:cy, f(assigns.y * 1.0))

    ~H"""

    <circle cx={@cx} cy={@cy} r="4" fill={@item.color} />

    <text

      x={@tx}

      y={@cy}

      dominant-baseline="central"

      fill="currentColor"

      fill-opacity="0.6"

      font-size="12"

    >

      {@item.label}

    </text>

    """

  end

  # ------------------------------------------------------------------

  # Funnel chart

  # ------------------------------------------------------------------

  @doc """

  Renders a horizontal SVG funnel chart with smooth curved transitions

  between steps.

  ## Examples

      <.funnel_chart

        id="funnel"

        title="Registration Funnel"

        steps={[%{label: "Visited", count: 1000}, %{label: "Signed up", count: 200}]}

      />

  """

  attr :id, :string, required: true

  attr :steps, :list, required: true, doc: "list of %{label, count}"

  attr :title, :string, default: nil, doc: "card title"

  attr :class, :any, default: nil

  def funnel_chart(assigns) do

    steps = assigns.steps

    n = length(steps)

    first_count =

      case steps do

        [%{count: c} | _] -> max(c, 1)

        _ -> 1

      end

    # SVG dimensions — funnel area + label area below

    vw = 800

    funnel_h = 140

    label_h = 50

    vh = funnel_h + label_h

    cy = funnel_h / 2

    max_h = funnel_h * 0.85

    pad_x = 4

    usable_w = vw - pad_x * 2

    section_w = if n > 0, do: usable_w / n, else: usable_w

    # Normalized heights (min 5% so zero-count steps are still visible)

    heights =

      Enum.map(steps, fn s ->

        max(s.count / first_count, 0.04) * max_h

      end)

    sections =

      steps

      |> Enum.with_index()

      |> Enum.map(fn {step, i} ->

        x1 = pad_x + i * section_w

        x2 = pad_x + (i + 1) * section_w

        h1 = Enum.at(heights, i)

        h2 = if i < n - 1, do: Enum.at(heights, i + 1), else: h1

        # Bezier control point offset — controls curve smoothness

        cp = section_w * 0.45

        path =

          "M #{f(x1)} #{f(cy - h1 / 2)} " <>

            "C #{f(x1 + cp)} #{f(cy - h1 / 2)} #{f(x2 - cp)} #{f(cy - h2 / 2)} #{f(x2)} #{f(cy - h2 / 2)} " <>

            "L #{f(x2)} #{f(cy + h2 / 2)} " <>

            "C #{f(x2 - cp)} #{f(cy + h2 / 2)} #{f(x1 + cp)} #{f(cy + h1 / 2)} #{f(x1)} #{f(cy + h1 / 2)} Z"

        rate =

          cond do

            i == 0 -> 100.0

            first_count > 0 -> Float.round(step.count / first_count * 100, 1)

            true -> 0.0

          end

        color = series_color(i)

        x_center = (x1 + x2) / 2

        %{path: path, step: step, index: i, rate: rate, color: color, x_center: f(x_center)}

      end)

    dividers =

      for i <- 1..(n - 1)//1 do

        %{x: f(pad_x + i * section_w)}

      end

    assigns =

      assigns

      |> assign(:sections, sections)

      |> assign(:dividers, dividers)

      |> assign(:vw, vw)

      |> assign(:vh, vh)

      |> assign(:funnel_h, f(funnel_h * 1.0))

      |> assign(:label_y1, f(funnel_h + 20.0))

      |> assign(:label_y2, f(funnel_h + 38.0))

    ~H"""

    <.chart_card title={@title} icon="hero-funnel-solid">

      <div class={["relative px-4 py-4", @class]} id={@id} phx-hook="Funnel">

        <svg viewBox={"0 0 #{@vw} #{@vh}"} class="w-full h-full" preserveAspectRatio="xMidYMid meet">

          <path

            :for={section <- @sections}

            d={section.path}

            fill={section.color}

            class="transition-all duration-200 cursor-pointer origin-center"

            style="filter: brightness(1)"

            onmouseenter="this.style.filter='brightness(1.15)'; this.style.transform='scaleY(1.06)'"

            onmouseleave="this.style.filter='brightness(1)'; this.style.transform='scaleY(1)'"

            data-funnel-section

            data-funnel-label={section.step.label}

            data-funnel-count={format_number(section.step.count)}

            data-funnel-rate={format_percent(section.rate)}

          />

          <line

            :for={div <- @dividers}

            x1={div.x}

            y1="0"

            x2={div.x}

            y2={@funnel_h}

            stroke="currentColor"

            stroke-opacity="0.2"

            stroke-width="1"

          />

          <text

            :for={section <- @sections}

            x={section.x_center}

            y={@label_y1}

            text-anchor="middle"

            fill="currentColor"

            fill-opacity="0.7"

            font-size="14"

            font-weight="500"

          >

            {section.step.label}

          </text>

          <text

            :for={section <- @sections}

            x={section.x_center}

            y={@label_y2}

            text-anchor="middle"

            fill="currentColor"

            fill-opacity="0.45"

            font-size="12"

          >

            {format_number(section.step.count)}

            <%= if section.index > 0 do %>

              ({format_percent(section.rate)}%)

            <% end %>

          </text>

        </svg>

        <div

          data-funnel-tooltip

          class="hidden absolute pointer-events-none -translate-x-1/2 -translate-y-full z-10"

        >

          <div

            class="rounded-xl px-3 py-2 text-sm shadow-lg whitespace-nowrap"

            style="background: oklch(0.15 0 0); border: 1px solid oklch(0.3 0 0)"

          >

            <div data-tooltip-label class="text-neutral-300 text-xs"></div>

            <div class="flex items-center gap-2 mt-0.5">

              <span data-tooltip-count class="font-semibold text-white"></span>

              <span data-tooltip-rate class="text-neutral-400"></span>

            </div>

          </div>

        </div>

      </div>

    </.chart_card>

    """

  end

  # ------------------------------------------------------------------

  # Pie chart

  # ------------------------------------------------------------------

  @doc """

  Renders a pie or donut chart with a side legend.

  ## Examples

      <.pie_chart

        id="events-by-type"

        data={[%{label: "Sign ups", count: 120}, %{label: "Confirmed", count: 80}]}

      />

      <.pie_chart

        id="events-by-type"

        title="Events by Type"

        style={:donut}

        data={@events_by_type}

      />

  """

  attr :id, :string, required: true

  attr :data, :list, required: true, doc: "list of %{label, count} or {label, count}"

  attr :title, :string, default: nil

  attr :style, :atom, default: :pie, values: [:pie, :donut]

  attr :stat_value, :integer, default: nil, doc: "current period total"

  attr :stat_change, :float, default: nil, doc: "percent change vs previous period"

  attr :stat_prev_value, :integer, default: nil, doc: "previous period total"

  attr :period, :atom, default: :day, values: [:day, :month], doc: "time granularity"

  attr :period_count, :integer, default: nil, doc: "number of days/months covered"

  attr :class, :any, default: nil

  slot :subtitle

  def pie_chart(assigns) do

    legend_items =

      assigns.data

      |> Enum.map(&normalize_slice/1)

      |> Enum.with_index()

      |> Enum.map(fn {s, i} -> Map.put(s, :color, series_color(i)) end)

    total = Enum.reduce(legend_items, 0, fn s, acc -> acc + s.count end)

    legend_items =

      Enum.map(legend_items, fn s ->

        pct = if total > 0, do: Float.round(s.count / total * 100, 1), else: 0.0

        Map.put(s, :pct, pct)

      end)

    # Square SVG so the pie can fill the card's vertical space; legend is HTML beside it.

    size = 240.0

    cx = size / 2

    cy = size / 2

    radius = size / 2 - 8

    inner_radius = if assigns.style == :donut, do: radius * 0.58, else: 0.0

    slices = build_pie_slices(legend_items, total, cx, cy, radius, inner_radius)

    assigns =

      assigns

      |> assign(:slices, slices)

      |> assign(:legend_items, legend_items)

      |> assign(:total, total)

      |> assign(:formatted_total, format_number(total))

      |> assign(:size, size)

      |> assign(:cx, f(cx))

      |> assign(:cy, f(cy))

      |> assign(:radius, f(radius))

      |> assign(:show_center_total, assigns.style == :donut and total > 0)

      |> assign(:center_total_y, f(cy - 6))

      |> assign(:center_label_y, f(cy + 18))

    ~H"""

    <.chart_card title={@title} icon="hero-chart-pie-solid">

      <:subtitle :if={@subtitle != []}>{render_slot(@subtitle)}</:subtitle>

      <:subtitle :if={(@subtitle == [] and @stat_value) && @period_count}>

        <span class="font-semibold text-base-content">{format_number(@stat_value)}</span>

        <span>{stat_period_label(@period, @period_count)}</span>

        <span

          :if={@stat_change}

          class={["inline-flex items-center gap-0.5", change_color(@stat_change)]}

        >

          <.icon name={change_icon(@stat_change)} class="size-4" />

          {format_percent(abs(@stat_change))}%

        </span>

        <span :if={@stat_prev_value}>vs {format_number(@stat_prev_value)}</span>

      </:subtitle>

      <:subtitle :if={@subtitle == [] and !(@stat_value && @period_count) and @total > 0}>

        <span class="font-semibold text-base-content">{@formatted_total}</span>

        <span>total</span>

      </:subtitle>

      <div class={["relative px-4 py-4", @class]} id={@id} phx-hook="Pie">

        <%!-- Phones stack donut-over-legend (side by side overflows the

             viewport); sm+ restores the row. Callers pass sm:h-64 so

             mobile height is content-led. --%>

        <div class="flex flex-col items-center gap-4 sm:flex-row sm:gap-6 h-full">

          <svg

            viewBox={"0 0 #{@size} #{@size}"}

            class="h-44 aspect-square shrink-0 sm:h-full"

            preserveAspectRatio="xMidYMid meet"

          >

            <g :if={@total == 0}>

              <circle

                cx={@cx}

                cy={@cy}

                r={@radius}

                fill="none"

                stroke="currentColor"

                stroke-opacity="0.1"

                stroke-width="2"

              />

              <text

                x={@cx}