@spec all_column_ids(PhoenixKitCRM.UserRoleView.scope()) :: [String.t()]

All available column ids for validation.

@spec available_columns(PhoenixKitCRM.UserRoleView.scope()) :: %{
  standard: [{String.t(), map()}],
  custom: [{String.t(), map()}]
}

Available columns for a scope, split into :standard and :custom.

Each value is an ordered list of {column_id, metadata} tuples — standard columns follow the order declared in this module, custom columns follow the position ordering from PhoenixKit.Users.CustomFields.

@spec column_metadata_map(PhoenixKitCRM.UserRoleView.scope()) :: %{
  required(String.t()) => map()
}

Returns a flat %{column_id => metadata} map for a scope.

Use this once per render cycle and pass the result through render helpers (render_cell, column_label) instead of calling get_column_metadata/2 per cell — that path rebuilds available_columns/1 on every lookup.

@spec default_columns(PhoenixKitCRM.UserRoleView.scope()) :: [String.t()]

Default selected column ids for a scope.

@spec get_column_metadata(PhoenixKitCRM.UserRoleView.scope(), String.t()) ::
  map() | nil

Returns metadata for a single column id, or nil. The :label field is translated via gettext.

@spec get_columns(binary(), PhoenixKitCRM.UserRoleView.scope()) :: [String.t()]

Returns the selected column ids for a user+scope, falling back to defaults.

@spec update_columns(binary(), PhoenixKitCRM.UserRoleView.scope(), [String.t()]) ::
  {:ok, PhoenixKitCRM.UserRoleViewConfig.t()} | {:error, Ecto.Changeset.t()}

Persists the selected column ids for a user+scope. Empty list resets to defaults.

@spec validate_columns(PhoenixKitCRM.UserRoleView.scope(), [String.t()]) :: [
  String.t()
]

Filter input list to only valid column ids for the scope, preserving order.