# `PhoenixKit.Config.UserDashboardCategories`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.165/lib/phoenix_kit/config/user_dashboard_categories.ex#L1)

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: []
          }
        ]
      }
    ]

# `get_categories`

```elixir
@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`

```elixir
@spec to_groups(list()) :: [PhoenixKit.Dashboard.Group.t()]
```

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`

```elixir
@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`

```elixir
@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}

---

*Consult [api-reference.md](api-reference.md) for complete listing*