@spec add_active_state([PhoenixKit.Dashboard.Tab.t()], String.t()) :: [map()]

Sets the :active key on each tab based on path matching.

@spec filter_top_level([PhoenixKit.Dashboard.Tab.t()]) :: [
  PhoenixKit.Dashboard.Tab.t()
]

Filters to only top-level tabs (no parent).

@spec get_subtabs_for(atom(), [PhoenixKit.Dashboard.Tab.t()]) :: [
  PhoenixKit.Dashboard.Tab.t()
]

Gets subtabs for a given parent tab ID, sorted by priority.

@spec group_tabs([PhoenixKit.Dashboard.Tab.t()]) :: %{
  optional(atom()) => [PhoenixKit.Dashboard.Tab.t()]
}

Groups tabs by their :group field.

@spec redirect_target(%{:path => String.t(), optional(atom()) => any()}, [
  PhoenixKit.Dashboard.Tab.t()
]) ::
  String.t() | nil

Where a parent tab flagged redirect_to_first_subtab should lead.

subtabs are the parent's subtabs the viewer can open, sorted by priority (what get_subtabs_for/2 returns from a scope-filtered tab list). The parent's own landing subtab — the one sharing the parent's path, e.g. Settings → General — wins whenever it is among them: a module subtab registered with a lower priority must not take the link from a viewer who can open the landing page. Otherwise the first subtab by priority. nil when there are no subtabs.

The one rule for every place that follows the flag: both sidebars, and the admin gate sending a visitor from a landing page they cannot open to one they can.

@spec sorted_groups([map()], map()) :: [map()]

Filters to groups that have tabs and sorts by priority.