feat(overview): add period-scoped payment filter and field-picker descriptor

lib/mv_web/live/member_live/index/payment_aging.ex

@@ -28,8 +28,11 @@ defmodule MvWeb.MemberLive.Index.PaymentAging do
 
   @type period :: %{from: Date.t() | nil, to: Date.t() | nil}
 
+  @type filter :: nil | :fully_paid | {:has_unpaid, 1..3}
+
   @payment_period_from_param Constants.payment_period_from_param()
   @payment_period_to_param Constants.payment_period_to_param()
+  @payment_filter_param Constants.payment_filter_param()
 
   @doc """
   The default period: all outstanding cycles, all time (both bounds nil).
@@ -62,6 +65,39 @@ defmodule MvWeb.MemberLive.Index.PaymentAging do
 
   def to_params(_), do: %{}
 
+  @doc """
+  Decodes the payment-count filter param.
+
+    * `"fully_paid"` → `:fully_paid` (exactly 0 unpaid cycles in the period)
+    * `"unpaid_1"` / `"unpaid_2"` / `"unpaid_3"` → `{:has_unpaid, N}`
+      (at least N unpaid cycles in the period)
+    * anything else → `nil` (no payment-count filter)
+  """
+  @spec parse_filter(term()) :: filter()
+  def parse_filter("fully_paid"), do: :fully_paid
+  def parse_filter("unpaid_1"), do: {:has_unpaid, 1}
+  def parse_filter("unpaid_2"), do: {:has_unpaid, 2}
+  def parse_filter("unpaid_3"), do: {:has_unpaid, 3}
+  def parse_filter(_), do: nil
+
+  @doc """
+  Encodes a payment-count filter into URL params. `nil` yields the empty map.
+  """
+  @spec filter_to_params(filter()) :: %{optional(String.t()) => String.t()}
+  def filter_to_params(:fully_paid), do: %{@payment_filter_param => "fully_paid"}
+
+  def filter_to_params({:has_unpaid, n}) when n in 1..3,
+    do: %{@payment_filter_param => "unpaid_#{n}"}
+
+  def filter_to_params(_), do: %{}
+
+  @doc """
+  Decodes the payment-count filter from a full params map.
+  """
+  @spec parse_filter_params(map()) :: filter()
+  def parse_filter_params(params) when is_map(params),
+    do: parse_filter(Map.get(params, @payment_filter_param))
+
   @doc """
   Badge descriptor for an unpaid-cycle count. A count of 0 reads "Paid"
   (success); a positive count reads "N unpaid" (error).