phoenix_kit

defmodule PhoenixKit.Utils.Routes do
  @moduledoc """
  Utility functions for working with PhoenixKit routes and URLs.

  This module provides helpers for constructing URLs with the correct
  PhoenixKit prefix configured in the application.
  """

  alias PhoenixKit.Config
  alias PhoenixKit.Modules.Languages.DialectMapper

  @default_locale Config.default_locale()

  # List of path prefixes that should NEVER have a locale added.
  # This should be kept in sync with @reserved_segments in LocaleExtractor plug.
  @reserved_prefixes ~w(/api /webhooks /assets /static /files /images /fonts /js /css /sitemap)

  @doc """
  Returns the configured PhoenixKit URL prefix.

  ## Examples

      iex> PhoenixKit.Utils.Routes.url_prefix()
      "/phoenix_kit"

  """
  @spec url_prefix() :: String.t()
  def url_prefix, do: Config.get_url_prefix()

  # NOTE: Locale override logic below exists for the publishing component system integration.
  # Switch to the upcoming media/storage helpers once they land.
  def path(url_path, opts \\ [])

  def path("/" <> _ = url_path, opts) do
    url_prefix = PhoenixKit.Config.get_url_prefix()
    base_path = if url_prefix === "/", do: "", else: url_prefix

    cond do
      # Admin paths ALWAYS get locale prefix to stay within the
      # :phoenix_kit_admin_locale live_session and avoid full-page reloads.
      admin_path?(url_path) ->
        locale = resolve_locale(opts)
        build_admin_path(base_path, url_path, locale)

      # Reserved paths (API, webhooks, assets) NEVER get a locale prefix.
      reserved_path?(url_path) ->
        "#{base_path}#{url_path}"

      true ->
        build_localized_path(base_path, url_path, opts)
    end
  end

  def path(_url_path, _opts) do
    raise """
    Url path must start with "/".
    """
  end

  defp build_localized_path(base_path, url_path, opts) do
    locale = resolve_locale(opts)
    build_path_with_locale(base_path, url_path, locale)
  end

  defp resolve_locale(opts) do
    case Keyword.fetch(opts, :locale) do
      {:ok, :none} -> :none
      {:ok, nil} -> determine_locale()
      {:ok, locale_value} -> locale_value
      :error -> determine_locale()
    end
  end

  defp build_path_with_locale(base_path, url_path, :none), do: "#{base_path}#{url_path}"

  defp build_path_with_locale(base_path, url_path, locale_value) do
    if default_locale?(locale_value) do
      "#{base_path}#{url_path}"
    else
      "#{base_path}/#{locale_value}#{url_path}"
    end
  end

  # Check if a path is an admin path.
  defp admin_path?(url_path), do: String.starts_with?(url_path, "/admin")

  # Admin paths ALWAYS include locale (even default locale) to match the
  # :phoenix_kit_admin_locale live_session scope (/:locale/admin/*).
  # This prevents live_session boundary crossings that cause full-page reloads.
  defp build_admin_path(base_path, url_path, :none), do: "#{base_path}#{url_path}"

  defp build_admin_path(base_path, url_path, locale) when is_binary(locale),
    do: "#{base_path}/#{locale}#{url_path}"

  defp build_admin_path(base_path, url_path, _), do: "#{base_path}#{url_path}"

  # Check if a path starts with one of the reserved prefixes.
  defp reserved_path?(path) do
    Enum.any?(@reserved_prefixes, &String.starts_with?(path, &1))
  end

  defp determine_locale do
    # Fall back to extracting base from Gettext locale
    # This is only used when locale is not explicitly passed to Routes.path
    # Gettext.get_locale/1 always returns a string
    locale = Gettext.get_locale(PhoenixKitWeb.Gettext)
    DialectMapper.extract_base(locale)
  end

  # Check if the given locale is the default (first in admin_languages list)
  # Default locale doesn't need a prefix in URLs for cleaner URLs
  defp default_locale?(locale) do
    default = get_default_admin_language()
    locale == default
  end

  defp get_default_admin_language do
    # During mix tasks (like phoenix_kit.install), the database may not have
    # the settings table yet. We detect this by checking if we're in a mix task
    # context and fall back to "en" to avoid database errors.
    if mix_task_context?() do
      "en"
    else
      case PhoenixKit.Settings.get_json_setting_cached("admin_languages", [@default_locale]) do
        nil ->
          # No setting exists, default is "en"
          "en"

        [first | _] ->
          # Extract base code from full dialect (e.g., "en-US" -> "en")
          DialectMapper.extract_base(first)

        _ ->
          "en"
      end
    end
  end

  # Detect if we're running in a mix task context where the database
  # may not be fully set up yet
  defp mix_task_context? do
    # Check if Mix is loaded and we're not in a running application context
    # The settings cache being unavailable is a reliable indicator
    case Process.get(:phoenix_kit_config_status) do
      nil -> false
      _ -> true
    end
  end

  @doc """
  Returns a locale-prefixed admin path, bypassing the reserved-path
  locale stripping that `path/2` applies.

  Admin routes use a `/:locale/admin/*` scope, so they need locale
  in the URL even though `/admin` is a reserved prefix.

  ## Examples

      iex> Routes.admin_path("/admin/users", "uk")
      "/phoenix_kit/uk/admin/users"

      iex> Routes.admin_path("/admin/users", nil)
      "/phoenix_kit/admin/users"

  """
  def admin_path(url_path, locale) when is_binary(locale) do
    url_prefix = Config.get_url_prefix()
    base_prefix = if url_prefix == "/", do: "", else: url_prefix
    "#{base_prefix}/#{locale}#{url_path}"
  end

  def admin_path(url_path, _locale), do: path(url_path)

  @doc """
  Returns a locale-aware path using locale from assigns.

  This function is specifically designed for use in component templates
  where the locale needs to be passed explicitly via assigns.

  Prefers base locale code for URL generation (current_locale_base),
  falls back to extracting base from full dialect code (current_locale).
  """
  def locale_aware_path(assigns, url_path) do
    # Prefer base code, fall back to extracting from full dialect
    locale =
      assigns[:current_locale_base] ||
        DialectMapper.extract_base(assigns[:current_locale] || @default_locale)

    path(url_path, locale: locale)
  end

  @doc """
  Returns the default admin locale (base code).

  This is the first language in the admin_languages setting list,
  extracted to its base code (e.g., "en-US" becomes "en").

  Falls back to "en" if no admin languages are configured.

  ## Examples

      iex> Routes.get_default_admin_locale()
      "en"  # or "ko" if Korean is first in admin_languages

  ## Use Case

  This is used automatically in the `on_mount` hook to set `current_locale`
  in socket assigns. LiveViews can then simply use:

      locale = params["locale"] || socket.assigns[:current_locale]
  """
  def get_default_admin_locale do
    get_default_admin_language()
  end

  @doc """
  Returns the path to the AI endpoints page.
  """
  def ai_path do
    path("/admin/ai")
  end

  @doc """
  Returns a full url with preconfigured prefix.

  This function first checks for a configured site URL in Settings,
  then automatically detects the correct URL from the running Phoenix
  application endpoint when possible, falling back to static configuration.
  This ensures that magic links and other email links work correctly in both
  development and production environments, with full control over the base URL
  through the Settings admin panel.
  """
  def url(url_path) do
    base_url = get_base_url_for_emails()
    full_path = path(url_path)

    normalized_base = String.trim_trailing(base_url, "/")
    "#{normalized_base}#{full_path}"
  end

  # Gets the base URL for email links.
  #
  # Priority:
  # 1. site_url setting from Settings (if configured)
  # 2. Dynamic URL from Phoenix endpoint
  # 3. Static configuration fallback
  #
  # This allows administrators to override the email link URLs through
  # the Settings panel, which is especially useful in production.
  defp get_base_url_for_emails do
    case PhoenixKit.Settings.get_setting("site_url", "") do
      "" ->
        PhoenixKit.Config.get_dynamic_base_url()

      site_url when is_binary(site_url) ->
        site_url
    end
  end

  @doc """
  Gets the base module name for the parent application.

  Reads from :phoenix_kit, :layouts_module config (e.g., MprojectWeb.Layouts -> MprojectWeb).

  ## Examples

      iex> PhoenixKit.Utils.Routes.phoenix_kit_app_base()
      "MprojectWeb"

  """
  @spec phoenix_kit_app_base() :: String.t()
  def phoenix_kit_app_base do
    case PhoenixKit.Config.get(:layouts_module) do
      {:ok, module} when is_atom(module) ->
        module
        |> Module.split()
        # Drop last segment (Layouts)
        |> Enum.slice(0..-2//1)
        |> Module.concat()

      _ ->
        "AppWeb"
    end
  end
end