NavBuddy (NavBuddy v0.4.0)

View Source

NavBuddy - Advanced Configurable Navigation Component for Phoenix LiveView

NavBuddy provides comprehensive navigation components for Phoenix LiveView applications, featuring dropdowns, mega menus, mobile-responsive design, and accessibility support.

Basic Usage

defmodule MyAppWeb.LayoutView do
  import NavBuddy.Component

  def navigation_items do
    [
      %{id: "home", label: "Home", navigate: "/"},
      %{id: "about", label: "About", navigate: "/about"},
      %{
        id: "products",
        label: "Products",
        navigate: "/products",
        dropdown: [
          %{id: "web", label: "Web Apps", navigate: "/products/web"},
          %{id: "mobile", label: "Mobile Apps", navigate: "/products/mobile"}
        ]
      }
    ]
  end
end

In your LiveView template:

<.nav_menu items={navigation_items()} config={NavBuddy.default_config()} />

Configuration

NavBuddy supports extensive configuration options:

config = %NavBuddy.Config{
  orientation: :horizontal,        # :horizontal | :vertical
  theme: :auto,                   # :light | :dark | :auto
  dropdown_trigger: :hover,       # :hover | :click
  mobile_behavior: :drawer,       # :drawer | :collapse | :overlay
  animations: true,               # boolean
  accessibility: true             # boolean
}

Navigation Structure

Navigation items support multiple levels of nesting and different types. All navigation uses the navigate field which triggers LiveView's push_navigate to maintain the LiveView connection without page reloads.

%{id: "home", label: "Home", navigate: "/"}

Dropdown Menus

%{
  id: "products",
  label: "Products",
  navigate: "/products",
  dropdown: [
    %{id: "web", label: "Web Development", navigate: "/products/web"},
    %{id: "mobile", label: "Mobile Apps", navigate: "/products/mobile"}
  ]
}

Multi-level Dropdowns

%{
  id: "services",
  label: "Services",
  dropdown: [
    %{
      id: "development",
      label: "Development",
      dropdown: [
        %{id: "frontend", label: "Frontend", navigate: "/services/frontend"},
        %{id: "backend", label: "Backend", navigate: "/services/backend"}
      ]
    }
  ]
}

Mega Menus

%{
  id: "solutions",
  label: "Solutions",
  mega_menu: %{
    title: "Our Solutions",
    description: "Comprehensive business solutions",
    sections: [
      %{
        title: "For Small Business",
        items: [
          %{id: "starter", label: "Starter Package", navigate: "/solutions/starter"},
          %{id: "growth", label: "Growth Package", navigate: "/solutions/growth"}
        ]
      },
      %{
        title: "For Enterprise",
        items: [
          %{id: "enterprise", label: "Enterprise Suite", navigate: "/solutions/enterprise"},
          %{id: "custom", label: "Custom Solutions", navigate: "/solutions/custom"}
        ]
      }
    ]
  }
}

Permissions-based Navigation

%{
  id: "admin",
  label: "Admin Panel",
  navigate: "/admin",
  permissions: "admin"  # Only visible to users with "admin" permission
}

%{
  id: "reports",
  label: "Reports",
  navigate: "/reports",
  permissions: ["manager", "admin"]  # Visible to users with either permission
}

%{
  id: "profile",
  label: "Profile",
  navigate: "/profile"  # No permissions = visible to everyone
}

Accessibility Features

NavBuddy includes comprehensive accessibility support:

  • ARIA attributes for screen readers
  • Keyboard navigation (arrow keys, enter, escape, tab)
  • Focus management
  • High contrast theme support
  • Reduced motion support

Mobile Optimization

Multiple mobile behaviors are supported:

  • Drawer: Slide-out navigation drawer
  • Collapse: Collapsible menu sections
  • Overlay: Full-screen navigation overlay

Theming

NavBuddy supports automatic theme detection and manual theme selection:

  • Light theme
  • Dark theme
  • Auto (follows system preference)
  • Custom themes via CSS custom properties

Summary

Types

mega_menu()
mega_menu_section()
nav_item()
simple_mega_menu()

Functions

default_config()

Returns the default configuration for NavBuddy.

dropdown_item(id, label, dropdown_items, opts \\ [])

Creates a navigation item with dropdown.

example_navigation()

Example navigation items showcasing all features.

filter_by_permissions(items, user_permissions)

Filters navigation items based on user permissions.

find_active_item(items, current_path)

Finds the active navigation item based on the current path.

generate_breadcrumbs(items, current_path)

Generates breadcrumb navigation from the active path.

generate_menu_id(nav_id, item_id)

Generates a unique menu ID for accessibility.

mega_menu_item(id, label, categories, opts \\ [])

Creates a navigation item with simple mega menu.

nav_item(id, label, navigate \\ nil, opts \\ [])

Creates a simple navigation item.

validate_nav_item(item)

Validates a navigation item structure.

validate_nav_items(items)

Validates a list of navigation items.

Types

mega_menu()

@type mega_menu() :: %{
  :title => String.t(),
  optional(:description) => String.t(),
  sections: [mega_menu_section()]
}

mega_menu_section()

@type mega_menu_section() :: %{
  :title => String.t(),
  optional(:description) => String.t(),
  items: [nav_item()]
}

nav_item()

@type nav_item() :: %{
  :id => String.t(),
  :label => String.t(),
  optional(:navigate) => String.t(),
  optional(:icon) => String.t(),
  optional(:dropdown) => [nav_item()],
  optional(:mega_menu) => mega_menu() | simple_mega_menu(),
  optional(:active) => boolean(),
  optional(:disabled) => boolean(),
  optional(:permissions) => String.t() | [String.t()]
}

simple_mega_menu()

@type simple_mega_menu() :: %{required(String.t()) => [nav_item()]}

Functions

default_config()

Returns the default configuration for NavBuddy.

Examples

iex> config = NavBuddy.default_config()
iex> config.orientation
:horizontal

iex> config = NavBuddy.default_config()
iex> config.theme
:auto

example_navigation()

Example navigation items showcasing all features.

Returns a comprehensive navigation structure demonstrating:

  • Simple links
  • Single-level dropdowns
  • Multi-level dropdowns
  • Mega menus
  • Icons and descriptions

filter_by_permissions(items, user_permissions)

Filters navigation items based on user permissions.

Removes items that the user doesn't have permission to see. Items without permissions are always visible. When an item has a list of permissions, the user must have ALL of them to see the item.

Examples

iex> items = [
...>   %{id: "home", label: "Home", navigate: "/"},
...>   %{id: "admin", label: "Admin", navigate: "/admin", permissions: "admin"},
...>   %{id: "user", label: "Profile", navigate: "/profile", permissions: "user"}
...> ]
iex> NavBuddy.filter_by_permissions(items, ["user"])
[
  %{id: "home", label: "Home", navigate: "/"},
  %{id: "user", label: "Profile", navigate: "/profile", permissions: "user"}
]

find_active_item(items, current_path)

Finds the active navigation item based on the current path.

Examples

iex> items = [%{id: "home", navigate: "/"}, %{id: "about", navigate: "/about"}]
iex> NavBuddy.find_active_item(items, "/about")
[%{id: "home", navigate: "/", active: false}, %{id: "about", navigate: "/about", active: true}]

generate_breadcrumbs(items, current_path)

Generates breadcrumb navigation from the active path.

Examples

iex> items = [%{id: "home", label: "Home", navigate: "/"}]
iex> NavBuddy.generate_breadcrumbs(items, "/")
[%{id: "home", label: "Home", navigate: "/"}]

generate_menu_id(nav_id, item_id)

Generates a unique menu ID for accessibility.

Examples

iex> NavBuddy.generate_menu_id("main-nav", "products")
"main-nav-products-menu"

mega_menu_item(id, label, categories, opts \\ [])

Creates a navigation item with simple mega menu.

Examples

iex> categories = %{
...>   "Frontend" => [%{id: "react", label: "React", navigate: "/tools/react"}],
...>   "Backend" => [%{id: "elixir", label: "Elixir", navigate: "/tools/elixir"}]
...> }
iex> NavBuddy.mega_menu_item("tools", "Tools", categories)
%{id: "tools", label: "Tools", mega_menu: %{"Frontend" => [%{id: "react", label: "React", navigate: "/tools/react"}], "Backend" => [%{id: "elixir", label: "Elixir", navigate: "/tools/elixir"}]}}

validate_nav_item(item)

Validates a navigation item structure.

Returns {:ok, item} if valid, {:error, reason} if invalid.

Examples

iex> item = %{id: "home", label: "Home", navigate: "/"}
iex> NavBuddy.validate_nav_item(item)
{:ok, %{id: "home", label: "Home", navigate: "/"}}

iex> NavBuddy.validate_nav_item(%{label: "Home"})
{:error, "Navigation item missing required field 'id'. Required fields: id (string), label (string). Optional fields: navigate, icon, dropdown, mega_menu, active, disabled, permissions"}

validate_nav_items(items)

Validates a list of navigation items.

Examples

iex> items = [%{id: "home", label: "Home"}]
iex> NavBuddy.validate_nav_items(items)
{:ok, [%{id: "home", label: "Home"}]}