phoenix_kit

defmodule PhoenixKitWeb.Components.MultilangForm do
  @moduledoc """
  Shared multilang form components and helpers for PhoenixKit modules.

  Provides the language tab switcher UI, skeleton loading placeholders,
  translatable field components, and Elixir-side helpers for merging
  multilang data in LiveView forms.

  Designed for two main use cases:

  1. **Whole-form translation** — wrap all translatable fields in a card with
     language tabs. The tab bar, skeleton placeholders, and field wrappers
     are handled automatically.

  2. **Single-field translation** — drop a `<.translatable_field>` into any
     form to make one field translatable, with no tab UI required (the caller
     manages `current_lang` however they like).

  ## Usage in a LiveView

  ### Mount

      import PhoenixKitWeb.Components.MultilangForm

      def mount(params, session, socket) do
        # ... load your record and changeset ...
        {:ok, mount_multilang(socket)}
      end

  ### Events

  `mount_multilang/2` auto-handles the `"switch_language"` event, so you do
  NOT need a `handle_event("switch_language", …)` clause — you only wire your
  own form events:

      def handle_event("validate", %{"record" => params}, socket) do
        params = merge_translatable_params(params, socket, ["name", "description"],
          changeset: socket.assigns.changeset)
        changeset = MySchema.changeset(socket.assigns.record, params)
        {:noreply, assign(socket, :changeset, changeset)}
      end

  ## Storage caveat — the helper OWNS the `data` column

  `merge_translatable_params/4` (and `put_language_data/3`) store translations
  by RESTRUCTURING the schema's `data` JSONB into a multilang shape
  (`%{"_primary_language" => "en", "en" => %{…}, "et" => %{…}}`). On a schema
  whose `data` column already holds unrelated keys (e.g. per-record settings),
  this MOVES those keys into the primary-language sub-map and every top-level
  reader breaks. In that case do NOT point `merge_translatable_params` at
  `data`: keep translations in an isolated sub-key and use `translatable_field`
  in its settings-translations mode (`secondary_name` + `lang_data_key`) with
  your own small merge. See the `translatable_field` docs.

  ### Template — whole-form translation

      <.multilang_tabs
        multilang_enabled={@multilang_enabled}
        language_tabs={@language_tabs}
        current_lang={@current_lang}
      />

      <.multilang_fields_wrapper
        multilang_enabled={@multilang_enabled}
        current_lang={@current_lang}
      >
        <.translatable_field
          field_name="name"
          form_prefix="catalogue"
          changeset={@changeset}
          schema_field={:name}
          multilang_enabled={@multilang_enabled}
          current_lang={@current_lang}
          primary_language={@primary_language}
          lang_data={@lang_data}
          label={gettext("Name")}
          required
        />
      </.multilang_fields_wrapper>

  ### Template — single-field translation (no tabs needed)

      <.translatable_field
        field_name="description"
        form_prefix="product"
        changeset={@changeset}
        schema_field={:description}
        multilang_enabled={@multilang_enabled}
        current_lang={@current_lang}
        primary_language={@primary_language}
        lang_data={@lang_data}
        label={gettext("Description")}
        type="textarea"
        rows={5}
      />
  """

  use Phoenix.Component
  use Gettext, backend: PhoenixKitWeb.Gettext

  import PhoenixKitWeb.Components.Core.Icon
  import PhoenixKitWeb.Components.Core.FormFieldError, only: [error: 1]
  import PhoenixKitWeb.Components.Core.Input, only: [translate_error: 1]
  import PhoenixKitWeb.Components.LanguageSwitcher, only: [language_switcher: 1]

  alias Phoenix.LiveView.JS
  # PhoenixKit.Utils.Multilang is in an external package — referenced by full name
  # with Code.ensure_loaded?/rescue guards throughout this module.

  # ═══════════════════════════════════════════════════════════════════
  # Mount & Event Helpers
  # ═══════════════════════════════════════════════════════════════════

  @doc """
  Adds multilang assigns to the socket. Call from `mount/3`.

  Adds: `:multilang_enabled`, `:primary_language`, `:current_lang`,
  `:language_tabs`, `:show_multilang_tabs`, `:switching_lang` (no-op
  compat assign — kept because consumer templates pass it through to
  the wrapper).

  Also attaches two internal LiveView hooks so consumers don't have to
  wire the language-switching protocol by hand:

    * a `:handle_info` hook for the debounced language-switch timer, and
    * a `:handle_event` hook for the `"switch_language"` event that
      `<.multilang_tabs>` pushes — it calls `handle_switch_language/2`
      and halts, so **you no longer need to add**
      `def handle_event("switch_language", …)` yourself. Forgetting that
      clause used to crash the LiveView on the first tab click.

  ## Options

    * `:auto_switch_language` — when `false`, skips the `"switch_language"`
      event hook so you can handle the event yourself (e.g. to switch
      language immediately without the debounce). Default `true`.
  """
  def mount_multilang(socket, opts \\ []) do
    multilang_enabled = multilang_enabled?()
    primary_language = if multilang_enabled, do: safe_primary_language(), else: nil

    language_tabs = if(multilang_enabled, do: safe_build_language_tabs(), else: [])

    socket
    |> Phoenix.Component.assign(
      multilang_enabled: multilang_enabled,
      primary_language: primary_language,
      current_lang: primary_language,
      language_tabs: language_tabs,
      show_multilang_tabs: multilang_enabled and length(language_tabs) > 1,
      # Kept for backwards compat with consumer templates that still pass
      # `switching_lang={@switching_lang}` to `<.multilang_fields_wrapper>`.
      # The wrapper no longer reads it — visibility is client-side JS.
      switching_lang: false
    )
    |> attach_multilang_hooks(opts)
  end

  # Attaches the internal hooks. Both are idempotent-by-name within a
  # process — re-running `mount_multilang/2` (e.g. across reconnects) with
  # the same hook ids simply replaces the prior callbacks, so no guard is
  # needed. `attach_hook/4` only works on LiveView sockets (not
  # LiveComponents), so each attach is guarded — a LiveComponent consumer
  # would need to wire the handlers itself.
  defp attach_multilang_hooks(socket, opts) do
    socket = attach_apply_lang_hook(socket)

    if Keyword.get(opts, :auto_switch_language, true),
      do: attach_switch_language_hook(socket),
      else: socket
  end

  # Intercepts the debounced `{:__multilang_apply_lang__, lang}` message so
  # the consumer needs no `handle_info/2` clause. Other messages pass
  # through with `{:cont, socket}`.
  defp attach_apply_lang_hook(socket) do
    Phoenix.LiveView.attach_hook(
      socket,
      :__phoenix_kit_multilang_apply_lang__,
      :handle_info,
      fn
        {:__multilang_apply_lang__, lang_code}, socket ->
          {:halt, handle_multilang_apply_lang(socket, lang_code)}

        _msg, socket ->
          {:cont, socket}
      end
    )
  rescue
    ArgumentError -> socket
  end

  # Intercepts the `"switch_language"` event that `<.multilang_tabs>`
  # pushes, so the consumer needs no `handle_event/3` clause. Halting stops
  # propagation to the consumer's own callbacks; every other event passes
  # through with `{:cont, socket}`.
  defp attach_switch_language_hook(socket) do
    Phoenix.LiveView.attach_hook(
      socket,
      :__phoenix_kit_multilang_switch_language__,
      :handle_event,
      fn
        "switch_language", %{"lang" => lang_code}, socket ->
          {:halt, handle_switch_language(socket, lang_code)}

        _event, _params, socket ->
          {:cont, socket}
      end
    )
  rescue
    ArgumentError -> socket
  end

  @doc """
  Refreshes multilang assigns after external changes (e.g. entity schema update).

  Unlike `mount_multilang/1`, this preserves `current_lang` when it's still valid,
  and resets it to the primary language if it was removed.
  """
  def refresh_multilang(socket) do
    multilang_enabled = multilang_enabled?()
    primary_language = if multilang_enabled, do: safe_primary_language(), else: nil
    language_tabs = if multilang_enabled, do: safe_build_language_tabs(), else: []

    current_lang = socket.assigns[:current_lang]
    enabled_langs = if multilang_enabled, do: safe_enabled_languages(), else: []

    current_lang =
      cond do
        not multilang_enabled -> nil
        current_lang not in enabled_langs -> primary_language
        true -> current_lang
      end

    Phoenix.Component.assign(socket,
      multilang_enabled: multilang_enabled,
      primary_language: primary_language,
      current_lang: current_lang,
      language_tabs: language_tabs,
      show_multilang_tabs: multilang_enabled and length(language_tabs) > 1
    )
  end

  @doc """
  Handles the `"switch_language"` event. Call from `handle_event/3`.

  Returns a socket that **defers** applying `:current_lang` via a short
  trailing debounce (150 ms). Rapid click-through (EN → JA → FR → DE)
  keeps rescheduling the timer; only the last click actually updates
  `:current_lang` and triggers a content re-render. Without this, every
  intermediate event caused its own server render and the client
  briefly flashed each language's content before landing on the final
  one.

  Nothing to do on the consumer's end — `mount_multilang/1` attaches a
  `:handle_info` hook via `Phoenix.LiveView.attach_hook/4` that
  intercepts the internal `{:__multilang_apply_lang__, lang}` message
  and applies the language transparently. Calling code never sees the
  message.

  Ignores unknown language codes.
  """
  @multilang_debounce_ms 150
  # The timer ref lives in `socket.private` (not `socket.assigns`) so
  # that storing it doesn't trigger a render+diff cycle that would fight
  # the client-side skeleton/fields visibility toggles. Private state
  # is per-socket — visible only inside the LV process — and survives
  # the LV's lifecycle the same way assigns do, but with zero diff cost.
  @multilang_timer_private_key :__phoenix_kit_multilang_timer__

  def handle_switch_language(socket, lang_code) do
    if lang_code in safe_enabled_languages() do
      socket = cancel_multilang_timer(socket)

      timer_ref =
        Process.send_after(
          self(),
          {:__multilang_apply_lang__, lang_code},
          @multilang_debounce_ms
        )

      # Skeleton/fields visibility is driven entirely by
      # `switch_lang_js/2`'s client-side class toggles. The server just
      # holds off applying the new `current_lang` until the debounce
      # fires, which is what causes the final morphdom swap that
      # restores the fields (with new-lang content) and hides the
      # skeleton again.
      Phoenix.LiveView.put_private(socket, @multilang_timer_private_key, timer_ref)
    else
      socket
    end
  end

  @doc """
  Applies a debounced language change. Call from `handle_info/2` when
  `{:__multilang_apply_lang__, lang_code}` is received.
  """
  def handle_multilang_apply_lang(socket, lang_code) do
    socket
    |> Phoenix.LiveView.put_private(@multilang_timer_private_key, nil)
    |> Phoenix.Component.assign(:current_lang, lang_code)
  end

  defp cancel_multilang_timer(socket) do
    case Map.get(socket.private, @multilang_timer_private_key) do
      ref when is_reference(ref) ->
        Process.cancel_timer(ref)
        Phoenix.LiveView.put_private(socket, @multilang_timer_private_key, nil)

      _ ->
        socket
    end
  end

  @doc """
  Merges translatable field params into the multilang `data` JSONB structure.

  Takes the raw form params, the socket, and a list of translatable field names
  (the DB column names, e.g. `["name", "description"]`). Returns updated params
  with the `"data"` key set to the merged multilang structure.

  On primary language tabs, reads from `params["name"]`.
  On secondary language tabs, reads from `params["lang_name"]`.

  Also preserves primary language values for non-translatable fields when on
  secondary tabs via the `preserve_fields` option.

  ## Options

    * `:changeset` — the current changeset (required)
    * `:preserve_fields` — map of `%{"field_name" => :schema_field}` for fields
      that should keep their primary language DB column value on secondary tabs.
      Defaults to `%{}`.
  """
  def merge_translatable_params(params, socket, translatable_fields, opts \\ []) do
    changeset = Keyword.fetch!(opts, :changeset)
    preserve_fields = Keyword.get(opts, :preserve_fields, %{})
    assigns = socket.assigns
    current_lang = assigns[:current_lang]
    primary = assigns[:primary_language]

    params =
      if assigns[:multilang_enabled] do
        form_data = extract_translatable_data(params, translatable_fields, current_lang, primary)
        final_data = do_merge_multilang_data(changeset, current_lang, form_data, assigns)
        Map.put(params, "data", final_data)
      else
        params
      end

    params
    |> preserve_translatable_primaries(changeset, assigns, translatable_fields)
    |> do_preserve_primary_fields(changeset, assigns, preserve_fields)
  end

  # On a secondary language tab the form submits only `lang_<field>` —
  # the PRIMARY columns are absent from params, so a validate/save that
  # rebuilds the changeset from the pristine struct silently drops the
  # primary text typed earlier (fatal on :new, where nothing else holds
  # it). The translatable fields ALWAYS need this preservation, so it no
  # longer depends on each consumer remembering `preserve_fields`.
  defp preserve_translatable_primaries(params, changeset, assigns, translatable_fields) do
    if assigns[:multilang_enabled] && assigns[:current_lang] != assigns[:primary_language] do
      Enum.reduce(translatable_fields, params, fn field, acc ->
        preserve_field_value(acc, changeset, field, safe_existing_atom(field))
      end)
    else
      params
    end
  end

  defp safe_existing_atom(field) when is_binary(field) do
    String.to_existing_atom(field)
  rescue
    ArgumentError -> nil
  end

  defp safe_existing_atom(field) when is_atom(field), do: field

  @doc """
  Injects a DB column value into the JSONB `data` field for multilang storage.

  This handles the common pattern where a field exists both as a top-level DB
  column (for queries/sorting) and inside the JSONB `data` (for translations).

  On the primary language tab, reads from `params[field_name]` (the DB column input).
  On secondary language tabs, reads from `params["lang_" <> field_name]` (the translation input).

  The value is stored in the data map under `"_" <> field_name` (e.g. `"_title"`).

  If no value is submitted (field not in form), preserves the existing value from
  the changeset's JSONB data.

  ## Requirements

  `assigns` must contain:
  - `:multilang_enabled` — boolean
  - `:primary_language` — the primary language code
  - `:changeset` — an `Ecto.Changeset` with a `:data` field (JSONB)

  ## Examples

      # In handle_event("validate", ...)
      form_data =
        form_data
        |> inject_db_field_into_data("title", data_params, current_lang, socket.assigns)
        |> inject_db_field_into_data("slug", data_params, current_lang, socket.assigns)
  """
  def inject_db_field_into_data(form_data, field_name, params, current_lang, assigns) do
    if assigns[:multilang_enabled] == true do
      primary = assigns[:primary_language]

      value =
        if current_lang == primary,
          do: params[field_name],
          else: params["lang_#{field_name}"]

      data_key = "_#{field_name}"

      if is_binary(value) do
        Map.put(form_data, data_key, value)
      else
        # No value submitted — preserve existing from JSONB data
        existing_data = safe_get_changeset_data(assigns.changeset)

        case PhoenixKit.Utils.Multilang.get_raw_language_data(existing_data, current_lang) do
          %{^data_key => existing} -> Map.put(form_data, data_key, existing)
          _ -> form_data
        end
      end
    else
      form_data
    end
  end

  @doc """
  Merges language-specific validated data into the full multilang JSONB structure.

  Reads existing data from the changeset's `:data` field, then merges the new
  `validated_data` for the given `lang_code`.

  Handles three cases:
  - Multilang enabled: uses `PhoenixKit.Utils.Multilang.put_language_data/3`
  - Multilang disabled but data has multilang structure: preserves translations
  - Flat data, no multilang: passes through as-is

  The `changeset` must be an `Ecto.Changeset` with a `:data` field.
  `assigns` must contain `:multilang_enabled`.
  """
  def merge_multilang_data(changeset, lang_code, validated_data, assigns) do
    do_merge_multilang_data(changeset, lang_code, validated_data, assigns)
  end

  @doc """
  Gets the raw language data for the current language from a changeset.

  Use this in templates to read override-only values for secondary language tabs.
  Returns `%{}` when multilang is disabled.
  """
  def get_lang_data(changeset, current_lang, multilang_enabled) do
    if multilang_enabled && changeset do
      PhoenixKit.Utils.Multilang.get_raw_language_data(
        Ecto.Changeset.get_field(changeset, :data),
        current_lang
      )
    else
      %{}
    end
  end

  @doc """
  Returns true when on the primary language tab (or multilang is disabled).
  """
  def primary_tab?(assigns) do
    !assigns[:multilang_enabled] || assigns[:current_lang] == assigns[:primary_language]
  end

  @doc """
  Preserves primary-language DB field values when on a secondary language tab.

  On secondary tabs, some fields (like title, slug) are absent from form params
  because they're replaced by `lang_*` inputs. This function fills in the missing
  values from the changeset so the DB columns keep their primary-language values.

  `preserve_fields` is a map of `%{"field_name" => :schema_field}`.

  No-ops when multilang is disabled or on the primary tab.
  """
  def preserve_primary_fields(params, changeset, assigns, preserve_fields) do
    do_preserve_primary_fields(params, changeset, assigns, preserve_fields)
  end

  @doc "Returns true when the Languages module is enabled with 2+ languages."
  def multilang_enabled? do
    Code.ensure_loaded?(PhoenixKit.Utils.Multilang) and PhoenixKit.Utils.Multilang.enabled?()
  rescue
    _ -> false
  end

  defp safe_primary_language do
    PhoenixKit.Utils.Multilang.primary_language()
  rescue
    _ -> "en-US"
  end

  defp safe_enabled_languages do
    PhoenixKit.Utils.Multilang.enabled_languages()
  rescue
    _ -> []
  end

  defp safe_build_language_tabs do
    PhoenixKit.Utils.Multilang.build_language_tabs()
  rescue
    _ -> []
  end

  # Bare-key fallback: overrides written outside the form helper
  # (seeds, API imports, `set_translation` callers using plain "name")
  # must not render as an empty input — saving that empty field would
  # wipe the existing translation.
  defp lang_override_value(lang_data, data_key, field_name) do
    case Map.get(lang_data, data_key) do
      nil -> Map.get(lang_data, field_name)
      value -> value
    end
  end

  # Safely reads a field from a changeset, returning "" on any error.
  defp safe_get_field(%Ecto.Changeset{} = changeset, field) when is_atom(field) do
    Ecto.Changeset.get_field(changeset, field) || ""
  rescue
    _ -> ""
  end

  defp safe_get_field(_changeset, _field), do: ""

  # Safely reads the :data field from a changeset, returning %{} on any error.
  defp safe_get_changeset_data(%Ecto.Changeset{} = changeset) do
    Ecto.Changeset.get_field(changeset, :data) || %{}
  rescue
    _ -> %{}
  end

  defp safe_get_changeset_data(_), do: %{}

  # ── Private helpers ────────────────────────────────────────────

  defp extract_translatable_data(params, fields, current_lang, primary) do
    Enum.reduce(fields, %{}, fn field, acc ->
      value =
        if current_lang == primary,
          do: params[field],
          else: params["lang_#{field}"]

      if is_binary(value), do: Map.put(acc, "_#{field}", value), else: acc
    end)
  end

  defp do_merge_multilang_data(changeset, lang_code, validated_data, assigns) do
    existing_data = safe_get_changeset_data(changeset)

    cond do
      assigns[:multilang_enabled] == true ->
        PhoenixKit.Utils.Multilang.put_language_data(existing_data, lang_code, validated_data)

      PhoenixKit.Utils.Multilang.multilang_data?(existing_data) ->
        PhoenixKit.Utils.Multilang.put_language_data(existing_data, lang_code, validated_data)

      true ->
        validated_data
    end
  end

  defp do_preserve_primary_fields(params, _changeset, assigns, preserve_fields)
       when map_size(preserve_fields) == 0 or
              not is_map_key(assigns, :multilang_enabled) do
    params
  end

  defp do_preserve_primary_fields(params, changeset, assigns, preserve_fields) do
    if assigns[:multilang_enabled] && assigns[:current_lang] != assigns[:primary_language] do
      Enum.reduce(preserve_fields, params, fn {str_key, atom_key}, acc ->
        preserve_field_value(acc, changeset, str_key, atom_key)
      end)
    else
      params
    end
  end

  defp preserve_field_value(params, _changeset, _str_key, nil), do: params

  defp preserve_field_value(params, changeset, str_key, atom_key) do
    if Map.has_key?(params, str_key) do
      params
    else
      case Ecto.Changeset.get_field(changeset, atom_key) do
        nil -> params
        value -> Map.put(params, str_key, value)
      end
    end
  end

  # ═══════════════════════════════════════════════════════════════════
  # Components
  # ═══════════════════════════════════════════════════════════════════

  @doc """
  Renders the language tab bar with compact/full mode.

  Shows a header with language icon, an info alert explaining the translation
  workflow, and the shared `<.language_switcher>` in `:tabs` variant with flags,
  names, and primary star indicator.

  Display mode:
  - `compact: nil` (default) — auto: full names when ≤ 5 languages, short codes when more
  - `compact: true` — always short codes
  - `compact: false` — always full names

  Delegates to `PhoenixKitWeb.Components.LanguageSwitcher.language_switcher/1`
  for the tab bar rendering.

  ## Attributes

    * `multilang_enabled` — boolean, whether multilang is active
    * `language_tabs` — list of tab maps from `PhoenixKit.Utils.Multilang.build_language_tabs/0`
    * `current_lang` — the currently selected language code
    * `compact` — force compact mode (short codes). Default: nil (auto)
    * `show_header` — show the "Content Language" header row (title +
      info tooltip + "Primary: …" label). Default: **false** — removed as
      a deliberate product call (2026-08-15): the tab strip itself says
      "languages", and the primary language is already marked by the star
      on its tab, so the row was redundant chrome that pushed the actual
      fields down. The attr remains as an opt-in escape hatch.
    * `show_info` — show an info tooltip next to the header. Default:
      false (it anchors inside the header, so it follows the same call);
      requires `show_header: true` to have an anchor element.
  """
  attr :multilang_enabled, :boolean, required: true
  attr :language_tabs, :list, required: true
  attr :current_lang, :string, required: true
  attr :compact, :boolean, default: nil
  attr :show_header, :boolean, default: false
  attr :show_info, :boolean, default: false
  attr :class, :string, default: "card-body pb-0"

  def multilang_tabs(assigns) do
    display =
      cond do
        assigns.compact == true -> :compact
        assigns.compact == false -> :full
        true -> :auto
      end

    assigns = assign(assigns, :display, display)

    ~H"""
    <div :if={@multilang_enabled && match?([_, _ | _], @language_tabs)} class={@class}>
      <div :if={@show_header} class="flex items-center justify-between mb-3">
        <div class="flex items-center gap-2">
          <.icon name="hero-language" class="w-5 h-5 text-primary" />
          <h2 class="card-title text-lg m-0">{gettext("Content Language")}</h2>
          <%!-- Info tooltip replaces the standalone alert block that
               used to live below the header. Boss feedback was that
               the wall of text was too prominent for what is mostly
               static explanation; hide it behind an info icon that
               reveals on hover/focus. The `[--tooltip-color:…]`
               override is needed because daisyUI's default tooltip
               background can be too dark for small body text on some
               themes — explicit base-300 keeps contrast readable. --%>
          <span
            :if={@show_info}
            class="tooltip tooltip-right cursor-help text-base-content/60 hover:text-base-content [--tooltip-max-width:24rem]"
            data-tip={
              gettext(
                "Use the language tabs below to translate this record's content. The primary language (marked with a star) is required. Other languages are optional — any empty fields will fall back to the primary language value."
              )
            }
          >
            <.icon name="hero-information-circle" class="w-4 h-4" />
          </span>
        </div>
        <% primary_tab = Enum.find(@language_tabs, fn t -> t.is_primary end) %>
        <div :if={primary_tab} class="flex items-center gap-1.5 text-xs text-base-content/60">
          <.icon name="hero-star-solid" class="w-3.5 h-3.5 text-primary" />
          <span>{gettext("Primary: %{lang}", lang: primary_tab.name)}</span>
        </div>
      </div>

      <div class="mb-4">
        <.language_switcher
          languages={@language_tabs}
          current_language={@current_lang}
          on_click_js={&switch_lang_js(&1, @current_lang)}
          display={@display}
          auto_threshold={5}
          show_flags={true}
          show_primary={true}
          primary_divider={true}
          variant={:tabs}
          size={:sm}
          class="w-full"
        />
      </div>
    </div>
    """
  end

  @doc """
  Renders skeleton loading placeholders and a content wrapper for translatable fields.

  The skeleton is shown instantly on tab switch via JS, then hidden when LiveView
  re-renders with the new language data.

  Wrap your translatable form fields inside this component's inner block.

  ## Customizing skeletons

  Use the `:skeleton` slot to provide custom skeleton markup that matches
  your form layout. If omitted, a default two-field skeleton is rendered.

  ## Attributes

    * `multilang_enabled` — boolean
    * `current_lang` — current language code (used in element IDs for morphdom)
    * `skeleton_class` — CSS class for the skeleton container. Default: `"card-body pt-4"`
    * `fields_class` — CSS class for the fields container. Default: nil

  ## Example — default skeleton (card context)

      <.multilang_fields_wrapper multilang_enabled={@multilang_enabled} current_lang={@current_lang}>
        <%!-- translatable fields here --%>
      </.multilang_fields_wrapper>

  ## Example — custom skeleton and classes (non-card context)

      <.multilang_fields_wrapper
        multilang_enabled={@multilang_enabled}
        current_lang={@current_lang}
        skeleton_class="space-y-6"
        fields_class="space-y-6"
      >
        <:skeleton>
          <div class="grid grid-cols-2 gap-6">
            <div class="skeleton h-12 w-full"></div>
            <div class="skeleton h-12 w-full"></div>
          </div>
        </:skeleton>
        <%!-- translatable fields here --%>
      </.multilang_fields_wrapper>
  """
  attr :multilang_enabled, :boolean, required: true
  attr :current_lang, :string, required: true

  attr :switching_lang, :boolean,
    default: false,
    doc:
      "accepted for backwards compatibility but no longer used — skeleton/fields visibility is client-side via `switch_lang_js/2`."

  attr :skeleton_class, :string, default: "card-body pt-4"
  attr :fields_class, :string, default: nil
  slot :skeleton
  slot :inner_block, required: true

  def multilang_fields_wrapper(assigns) do
    ~H"""
    <%!-- Skeleton placeholders (shown instantly on tab click via JS).
         IDs include current_lang so that when the debounce fires and
         current_lang changes, morphdom treats these as new elements
         and replaces them — which resets the skeleton back to `hidden`
         and inserts the fields with new-language content. --%>
    <div
      :if={@multilang_enabled}
      id={"translatable-skeletons-#{@current_lang}"}
      data-translatable="skeletons"
      class={["hidden", @skeleton_class]}
      aria-busy="true"
      aria-label={gettext("Loading language content")}
    >
      <%= if @skeleton != [] do %>
        {render_slot(@skeleton)}
      <% else %>
        <div class="space-y-4">
          <%!-- Default skeleton uses `bg-base-content/15 animate-pulse`
               instead of daisyUI's `.skeleton` because the latter's
               ~8%-opacity base-content grey is nearly invisible on a
               `bg-base-100` card — multiple consumers reported the
               loading state looking like a "blank page". Theme-safe
               via base-content opacity (dark-on-light AND
               light-on-dark themes both render visibly). --%>
          <div class="space-y-2">
            <div class="bg-base-content/15 rounded h-4 w-24 animate-pulse"></div>
            <div class="bg-base-content/15 rounded h-12 w-full animate-pulse"></div>
          </div>
          <div class="space-y-2">
            <div class="bg-base-content/15 rounded h-4 w-32 animate-pulse"></div>
            <div class="bg-base-content/15 rounded h-24 w-full animate-pulse"></div>
          </div>
        </div>
      <% end %>
    </div>

    <div
      id={if @multilang_enabled, do: "translatable-fields-#{@current_lang}", else: "form-fields"}
      data-translatable="fields"
      class={@fields_class}
    >
      {render_slot(@inner_block)}
    </div>
    """
  end

  @doc """
  Renders a translatable text input or textarea field.

  On the primary language tab, renders a standard input reading from the changeset.
  On secondary language tabs, renders with a language-specific name and uses the
  primary language value as placeholder text.

  Works both inside a `<.multilang_fields_wrapper>` (whole-form translation) and
  standalone (single-field translation).

  ## Translation models

  Supports two naming patterns for secondary language inputs:

  **Default (JSONB data column)** — used by entity data records:
  - Secondary name: `form_prefix[lang_field_name]`
  - Lang data key: `"_field_name"`

  **Settings translations** — used by entity definitions and other models
  that store translations in a `settings["translations"]` map. Set
  `secondary_name` and `lang_data_key` to override the defaults:

      <.translatable_field
        field_name="display_name"
        form_prefix="entities"
        secondary_name={"entities[translations][\#{@current_lang}][display_name]"}
        lang_data_key="display_name"
        ...
      />

  ## Attributes

    * `field_name` — the DB column name (e.g., "name")
    * `form_prefix` — the form name prefix (e.g., "catalogue")
    * `changeset` — the Ecto changeset
    * `schema_field` — the schema field atom (e.g., `:name`)
    * `multilang_enabled` — boolean
    * `current_lang` — current language code
    * `primary_language` — primary language code
    * `lang_data` — raw language data map for the current language
    * `label` — field label text
    * `placeholder` — placeholder for primary language (optional)
    * `type` — "input" or "textarea". Default: "input"
    * `rows` — textarea rows (only for type="textarea"). Default: 3
    * `required` — marks the primary language field as required. Default: false
    * `disabled` — disables the field. Default: false
    * `class` — additional CSS class(es) for the input element. Default: nil
    * `pattern` — HTML pattern attribute for input validation. Default: nil
    * `title` — HTML title attribute (for pattern validation message). Default: nil
    * `hint` — hint text shown below the field. Default: nil
    * `secondary_hint` — hint text shown only on secondary language tabs. Default: nil
    * `secondary_name` — override the secondary tab input name. Default: `"form_prefix[lang_field_name]"`
    * `lang_data_key` — key to look up in `lang_data` for secondary value.
      Default: `"_field_name"`. Set to `"field_name"` for settings translations.
  """
  attr :field_name, :string, required: true
  attr :form_prefix, :string, required: true
  attr :changeset, :any, required: true
  attr :schema_field, :atom, required: true
  attr :multilang_enabled, :boolean, required: true
  attr :current_lang, :string, required: true
  attr :primary_language, :string, required: true
  attr :lang_data, :map, required: true
  attr :label, :string, required: true
  attr :placeholder, :string, default: nil
  attr :type, :string, default: "input"
  attr :rows, :integer, default: 3
  attr :required, :boolean, default: false
  attr :disabled, :boolean, default: false
  attr :class, :string, default: nil
  attr :pattern, :string, default: nil
  attr :title, :string, default: nil

  attr :debounce, :string,
    default: "300",
    doc: """
    Value for `phx-debounce` on the field's input. Defaults to `"300"`, the
    delay every caller had baked in before this was configurable. Pass `nil`
    to omit the attribute entirely — do that when the server DERIVES
    something from this field as you type (a slug from a title, say), where
    waiting for a pause makes the derived value feel laggy.
    """

  attr :hint, :string, default: nil
  attr :secondary_hint, :string, default: nil

  attr :rest, :global,
    doc: """
    Anything else lands on the input itself — `phx-hook`, `data-*`, `aria-*`.
    Without this the component silently swallowed such attributes: they
    reached its assigns and were never rendered, so a caller wiring a JS
    hook to a translated field got no hook and no warning.

    Don't pass `id` here — the input's id is derived internally from
    `field_name`/`form_prefix`/`current_lang`, and `id` is a global HTML
    attribute the compiler won't stop you from spreading; doing so renders
    two conflicting `id` attributes on the same tag.
    """

  attr :mentions, :boolean,
    default: false,
    doc:
      "offer `@` people and `#` records while typing (textarea only). Needs " <>
        "`use PhoenixKit.Mentions.Live` on the LiveView"

  attr :secondary_name, :string, default: nil
  attr :lang_data_key, :string, default: nil
  slot :label_extra

  def translatable_field(assigns) do
    # Coerce lang_data to map if nil/invalid
    assigns =
      if is_map(assigns.lang_data), do: assigns, else: assign(assigns, :lang_data, %{})

    is_primary = !assigns.multilang_enabled || assigns.current_lang == assigns.primary_language

    # Opt-in AND site-enabled AND a textarea: the typeahead has nowhere to
    # go in a single-line input, and a hint promising a feature that is
    # switched off is worse than no hint.
    assigns =
      assign(
        assigns,
        :mentions_on,
        assigns.mentions and assigns.type == "textarea" and PhoenixKit.Mentions.enabled?()
      )

    # Resolve the lang_data lookup key: custom or default "_field_name"
    data_key = assigns.lang_data_key || "_#{assigns.field_name}"

    # Resolve the secondary input name: custom or default "prefix[lang_field]"
    sec_name =
      assigns.secondary_name || "#{assigns.form_prefix}[lang_#{assigns.field_name}]"

    # Extract changeset errors for this field (primary tab only)
    errors = field_errors(assigns.changeset, assigns.schema_field, is_primary)

    assigns =
      assigns
      |> assign(:is_primary, is_primary)
      |> assign(:errors, errors)
      |> assign_new(:primary_value, fn ->
        safe_get_field(assigns.changeset, assigns.schema_field)
      end)
      |> assign_new(:lang_value, fn ->
        lang_override_value(assigns.lang_data, data_key, assigns.field_name)
      end)
      |> assign(:secondary_input_name, sec_name)
      |> assign_new(:input_id, fn ->
        if is_primary do
          "#{assigns.form_prefix}_#{assigns.field_name}"
        else
          "#{assigns.form_prefix}_#{assigns.field_name}_#{assigns.current_lang}"
        end
      end)
      |> assign_new(:input_class, fn ->
        # `w-full` for parity with the regular `<.input>` core component
        # — daisyUI 5's `.input` / `.textarea` classes don't include
        # full-width by default, so without this the field shrinks to
        # the input's intrinsic content width.
        base =
          if assigns.type == "textarea",
            do: "textarea w-full",
            else: "input w-full"

        base = if assigns.class, do: "#{base} #{assigns.class}", else: base
        if errors != [], do: "#{base} input-error", else: base
      end)

    ~H"""
    <%!-- `flex flex-col` because daisyUI 5's `.label` is `inline-flex`
         and `.input`/`.textarea` are `inline-block` — without forcing
         column direction here they sit on the same row. The `gap-1`
         puts a small breathing room between label and field that
         matches the `<.input>` core component's `mb-2`. --%>
    <div
      class="flex flex-col gap-1"
      phx-feedback-for={if @is_primary, do: "#{@form_prefix}[#{@field_name}]"}
    >
      <%!-- Plain font-semibold like <.input>'s label. The 0.75rem these
           labels used to render at came from THIS wrapper's own `fieldset`
           class, not from `fieldset-legend` (which sets no font-size at
           all) — so the size is fixed by dropping `fieldset` above, and the
           span is then byte-identical to Input's. Its grid/gap were already
           overridden by `flex`/`gap-1`; only 0.25rem of padding-block goes
           with it. --%>
      <label for={@input_id} class="label">
        <span class="font-semibold">
          {@label}
          <%= if @required && @is_primary do %>
            *
          <% end %>
        </span>
        {render_slot(@label_extra)}
      </label>
      <%= if @type == "textarea" do %>
        <%= if @is_primary do %>
          <textarea
            name={"#{@form_prefix}[#{@field_name}]"}
            id={@input_id}
            class={@input_class}
            rows={@rows}
            phx-debounce={@debounce}
            phx-hook={@mentions_on && "MentionInput"}
            required={@required}
            disabled={@disabled}
            {@rest}
          >{@primary_value}</textarea>
        <% else %>
          <textarea
            name={@secondary_input_name}
            id={@input_id}
            class={@input_class}
            rows={@rows}
            placeholder={@primary_value}
            phx-debounce={@debounce}
            phx-hook={@mentions_on && "MentionInput"}
            disabled={@disabled}
            {@rest}
          >{@lang_value || ""}</textarea>
        <% end %>
        <p :if={@mentions_on} class="mt-1 text-xs opacity-50">
          {gettext("Type @ to mention someone, # to link a record.")}
        </p>
      <% else %>
        <%= if @is_primary do %>
          <input
            type="text"
            name={"#{@form_prefix}[#{@field_name}]"}
            id={@input_id}
            value={@primary_value}
            class={@input_class}
            placeholder={@placeholder}
            phx-debounce={@debounce}
            required={@required}
            disabled={@disabled}
            pattern={@pattern}
            title={@title}
            {@rest}
          />
        <% else %>
          <input
            type="text"
            name={@secondary_input_name}
            id={@input_id}
            value={@lang_value}
            placeholder={@primary_value}
            class={@input_class}
            phx-debounce={@debounce}
            disabled={@disabled}
            pattern={@pattern}
            title={@title}
            {@rest}
          />
        <% end %>
      <% end %>
      <.error :for={msg <- @errors}>{msg}</.error>
      <label :if={@hint && @is_primary && @errors == []} class="label">
        <span class="fieldset-label">{@hint}</span>
      </label>
      <label :if={@secondary_hint && !@is_primary} class="label">
        <span class="fieldset-label">{@secondary_hint}</span>
      </label>
    </div>
    """
  end

  # Extracts translated error messages for a field from the changeset.
  # Only returns errors on the primary tab — secondary tabs don't validate DB columns.
  defp field_errors(%Ecto.Changeset{action: action, errors: errors}, field, true = _is_primary)
       when not is_nil(action) do
    errors
    |> Keyword.get_values(field)
    |> Enum.map(&translate_error/1)
  end

  defp field_errors(_changeset, _field, _is_primary), do: []

  # ── JS helper ──────────────────────────────────────────────────

  @doc """
  Returns a `Phoenix.LiveView.JS` command that switches languages.

  Toggles skeleton/fields visibility **client-side, instantly** (hides
  `[data-translatable=fields]`, reveals `[data-translatable=skeletons]`)
  and pushes `"switch_language"` to the server. The server side holds
  the class state untouched — `handle_switch_language/2` just schedules
  a 150 ms debounced timer that eventually updates `:current_lang`,
  which changes the wrapper div ids and makes morphdom replace both
  divs with their new-language versions (skeleton back to `hidden`,
  fields visible with new content). Nothing on the server renders
  `hidden` on the fields or removes `hidden` from the skeleton, so the
  JS toggles never fight a server diff.

  Returns a no-op when `lang_code == current_lang` — clicking the
  already-active tab doesn't push and doesn't flash the skeleton.
  """
  def switch_lang_js(lang_code, current_lang) do
    if lang_code == current_lang do
      # Same-lang click during an in-flight debounce: we need to cancel
      # the pending server timer (which would otherwise still fire and
      # flip to the wrong lang) AND revert the skeleton/fields toggles
      # on the client (so the UI doesn't sit stuck in skeleton-visible
      # state after the no-op server render). Pushing with the current
      # lang hits `handle_switch_language/2`'s `cancel_multilang_timer`
      # and reschedules a no-op `current_lang` set.
      JS.push("switch_language", value: %{lang: lang_code})
      |> JS.remove_class("hidden", to: "[data-translatable=fields]")
      |> JS.add_class("hidden", to: "[data-translatable=skeletons]")
    else
      JS.push("switch_language", value: %{lang: lang_code})
      |> JS.add_class("hidden", to: "[data-translatable=fields]")
      |> JS.remove_class("hidden", to: "[data-translatable=skeletons]")
    end
  end
end