live_interaction_contracts

defmodule LiveInteractionContracts do
  @moduledoc """
  Dev/test-only conformance harness for Phoenix LiveView browser-native
  interaction contracts. **Not a UI component library.**

  It answers, with real browsers (Chromium/Firefox/WebKit) over a real
  LiveSocket, whether browser-native interaction state survives LiveView
  patching: popover openness, dialog/details open state, focus/selection,
  scroll, and combobox `aria-activedescendant` / Channel staleness.

  ## Tasks

    * `mix live_interaction_contracts.test`   — run the harness, assert the fuse
    * `mix live_interaction_contracts.ledger` — regenerate the delegation ledger

  Runtime users can import all conformance-backed reference components with:

      use LiveInteractionContracts.Components

  See `SPEC.md`, `KERNEL.md`, and the `*_CONTRACT.md` files for the durable
  invariants. The generated `delegation-ledger.{md,json}` carries the
  version-specific classification.
  """

  @doc "Resolve the bundled fixture/priv directory (works in-project and as a dep)."
  def priv_dir do
    from_app =
      case :code.priv_dir(:live_interaction_contracts) do
        {:error, _} -> nil
        path -> to_string(path)
      end

    cond do
      from_app && File.dir?(from_app) -> from_app
      File.dir?(Path.join(File.cwd!(), "priv")) -> Path.join(File.cwd!(), "priv")
      true -> Mix.raise("could not locate live_interaction_contracts priv dir")
    end
  end

  @doc """
  Detect the LiveView version to test against.

  Order: explicit `--lv` / `LV_SPEC` env, else the host project's loaded
  `:phoenix_live_view` version (so the harness tests the consumer's real
  version), else a pinned default.
  """
  def resolve_lv_spec(override \\ nil) do
    cond do
      is_binary(override) && override != "" -> override
      (env = System.get_env("LV_SPEC")) && env != "" -> env
      vsn = host_lv_version() -> to_string(vsn)
      true -> "1.2.7"
    end
  end

  defp host_lv_version do
    case Application.spec(:phoenix_live_view, :vsn) do
      nil -> nil
      vsn -> vsn
    end
  end
end