PhoenixKit.Config.UserDashboardCategories (phoenix_kit v1.7.38)

User dashboard categories configuration and validation for PhoenixKit.

This module provides a comprehensive system for configuring custom user dashboard categories with tabs (including subtabs), including validation, type safety, and fallback to built-in categories.

Category Structure

Each category should have the following structure:

%{
  title: "Category Title",
  icon: "hero-icon-name",          # Optional Heroicon name
  tabs: [
    %{
      title: "Tab Title",
      url: "/dashboard/some-path",
      icon: "hero-icon-name",       # Optional Heroicon name
      description: "Brief description", # Optional
      subtabs: [                    # Optional nested tabs
        %{
          title: "Subtab Title",
          url: "/dashboard/some-path/sub",
          icon: "hero-icon-name"
        }
      ]
    }
  ]
}

Field Validation

title: Required string, max 100 characters
icon: Optional string, validated to be a reasonable Heroicon name
tabs: Required list, can be empty
tab.title: Required string, max 100 characters
tab.url: Required string, must start with "/"
tab.icon: Optional Heroicon name validation
tab.description: Optional string, max 200 characters
tab.subtabs: Optional list of subtab definitions

Usage in config/config.exs

config :phoenix_kit, :user_dashboard_categories, [
  %{
    title: "Farm Management",
    icon: "hero-cube",
    tabs: [
      %{
        title: "Printers",
        url: "/dashboard/printers",
        icon: "hero-printer",
        description: "Manage your 3D printers"
      },
      %{
        title: "History",
        url: "/dashboard/history",
        icon: "hero-chart-bar",
        description: "View print history"
      }
    ]
  },
  %{
    title: "Account",
    icon: "hero-user",
    tabs: [
      %{
        title: "Settings",
        url: "/dashboard/settings",
        icon: "hero-cog-6-tooth"
      }
    ]
  }
]

Usage in Code

# Get all configured categories with validation
categories = PhoenixKit.Config.UserDashboardCategories.get_categories()

# Returns validated list like:
[
  %{
    title: "Farm Management",
    icon: "hero-cube",
    tabs: [
      %{
        title: "Printers",
        url: "/dashboard/printers",
        icon: "hero-printer",
        description: "Manage your 3D printers",
        subtabs: []
      }
    ]
  }
]

Summary

Functions

get_categories()

Gets user dashboard categories with comprehensive validation and defaults.

to_groups(categories)

Converts categories to group definitions for the Dashboard system.

to_tabs(categories)

Converts categories to the Tab struct format used by the Dashboard system.

validate_categories(categories)

Validates user dashboard categories structure and content.

Functions

get_categories()

@spec get_categories() :: list()

Gets user dashboard categories with comprehensive validation and defaults.

This function provides a fully validated list of user dashboard categories with proper structure validation and fallback to built-in categories.

Examples

iex> PhoenixKit.Config.UserDashboardCategories.get_categories()
[
  %{
    title: "Farm Management",
    icon: "hero-cube",
    tabs: [
      %{
        title: "Printers",
        url: "/dashboard/printers",
        icon: "hero-printer",
        description: "Manage your 3D printers"
      }
    ]
  }
]

to_groups(categories)

@spec to_groups(list()) :: list()

Converts categories to group definitions for the Dashboard system.

Examples

iex> categories = PhoenixKit.Config.UserDashboardCategories.get_categories()
iex> PhoenixKit.Config.UserDashboardCategories.to_groups(categories)
[%{id: :farm_management, label: "Farm Management", ...}, ...]

to_tabs(categories)

@spec to_tabs(list()) :: list()

Converts categories to the Tab struct format used by the Dashboard system.

This bridges the config-based categories to the Tab registry system.

Examples

iex> categories = PhoenixKit.Config.UserDashboardCategories.get_categories()
iex> PhoenixKit.Config.UserDashboardCategories.to_tabs(categories)
[%PhoenixKit.Dashboard.Tab{...}, ...]

validate_categories(categories)

@spec validate_categories(list()) :: {:ok, list()} | {:error, String.t()}

Validates user dashboard categories structure and content.

This function can be used to validate custom categories before setting them in the configuration.

Examples

iex> categories = [
...>   %{
...>     title: "My Category",
...>     tabs: [
...>       %{
...>         title: "My Tab",
...>         url: "/dashboard/my-path"
...>       }
...>     ]
...>   }
...> ]
iex> PhoenixKit.Config.UserDashboardCategories.validate_categories(categories)
{:ok, validated_categories}