From 9b000fcadc4c4b235af9199fe8de7bf233cfc74b Mon Sep 17 00:00:00 2001
From: Damien LAGAE <damienlagae@gmail.com>
Date: Mon, 27 Apr 2026 20:02:26 +0200
Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20Add=20UserMenu=20navigation=20compo?=
 =?UTF-8?q?nent?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Introduce a ready-to-use user menu component for the navbar, plus minor
tweaks to the Menu component to keep items vertically aligned when their
heights differ.

UserMenu features:
- Circular avatar (3rem / 48px) rendered from a profile picture or
  auto-derived colored initials when no image is provided
- Initials derived from the `name` parameter (first + last word, or
  two first chars for single-word names), uppercase, multibyte-safe
- Background color picked deterministically from a curated palette via
  CRC32 hash of `name`, so avatars stay stable across pages
- Right-aligned dropdown by default, with the user name as header
- Items support a `visible` flag to express conditional entries
  (e.g. permission-gated links) without surrounding `{% if %}` blocks
- Auto-detection of active state on items, consistent with MenuItem

Menu adjustment:
- Add `align-items-center` to the rendered `<ul>` so menu items of
  different heights (LocaleSwitcher, MenuItem, UserMenu avatar) stay
  vertically centered on the same row
---
 config/services.yaml                        |   6 +
 docs/Navigation/userMenu.md                 | 135 ++++++++
 docs/index.md                               |   1 +
 src/Component/Navigation/UserMenu.php       | 184 +++++++++++
 templates/navigation/menu.html.twig         |   2 +-
 templates/navigation/user_menu.html.twig    |  40 +++
 tests/Component/Navigation/UserMenuTest.php | 329 ++++++++++++++++++++
 7 files changed, 696 insertions(+), 1 deletion(-)
 create mode 100644 docs/Navigation/userMenu.md
 create mode 100644 src/Component/Navigation/UserMenu.php
 create mode 100644 templates/navigation/user_menu.html.twig
 create mode 100644 tests/Component/Navigation/UserMenuTest.php

diff --git a/config/services.yaml b/config/services.yaml
index 767af26..3854036 100644
--- a/config/services.yaml
+++ b/config/services.yaml
@@ -33,6 +33,12 @@ services:
   Enabel\Ux\Component\Navigation\Navbar:
     tags:
       - { name: 'twig.component', key: 'Enabel:Ux:Navbar', template: '@EnabelUx/navigation/navbar.html.twig', expose_public_props: true }
+
+  Enabel\Ux\Component\Navigation\UserMenu:
+    arguments:
+      - '@request_stack'
+    tags:
+      - { name: 'twig.component', key: 'Enabel:Ux:UserMenu', template: '@EnabelUx/navigation/user_menu.html.twig', expose_public_props: true }
   
   Enabel\Ux\Component\Navigation\Tab:
     tags:
diff --git a/docs/Navigation/userMenu.md b/docs/Navigation/userMenu.md
new file mode 100644
index 0000000..aafd909
--- /dev/null
+++ b/docs/Navigation/userMenu.md
@@ -0,0 +1,135 @@
+# UserMenu Component
+
+## Description
+
+A ready-to-use Bootstrap user menu for the navbar. Renders a circular avatar (photo or auto-derived colored initials) that opens a right-aligned dropdown with the user name as header and a configurable list of items (links, dividers, headers).
+
+This component is intended to be nested inside a [Menu](menu.md) component aligned to the end of the [Navbar](navbar.md).
+
+**Component Nesting:**
+- **Navbar** is the top-level container
+  - Contains one or more **Menu** components inside its `content` block
+    - A **Menu** can contain a **UserMenu** (this component) alongside [MenuItem](menuItem.md) components
+
+## Parameters
+
+| Parameter       | Type                | Description                                                                                       | Default                |
+|:----------------|:--------------------|:--------------------------------------------------------------------------------------------------|:-----------------------|
+| `name`          | `string` (required) | The user display name. Used for the dropdown header, the toggle `aria-label`, and to derive default initials/color | —                      |
+| `image`         | `?string`           | URL or data-URI of the user picture. When set, the avatar renders the image instead of initials   | `null`                 |
+| `initials`      | `?string`           | Override of the auto-derived initials                                                             | derived from `name`    |
+| `initialsColor` | `?string`           | Override of the auto-derived background color (CSS color). Used only when no `image` is provided  | derived from `name`    |
+| `dropdownAlign` | `string`            | Dropdown alignment, `start` or `end`                                                              | `'end'`                |
+| `hideName`      | `bool`              | Hide the user name next to the avatar in the toggle (the name is still in the dropdown header)    | `true`                 |
+| `items`         | `array`             | Dropdown items (each with `label`, `link`, `icon`, `divider`, `header`, `active`, `disabled`, `visible`) | `[]`                   |
+
+## Initials derivation
+
+When `initials` is not provided, they are derived from `name`:
+- Two or more words → first letter of the first word + first letter of the last word (e.g., `Damien Lagae` → `DL`, `John Ronald Reuel Tolkien` → `JT`)
+- One word → first two characters of the word (e.g., `Damien` → `DA`)
+- Always uppercase, multibyte-safe (e.g., `éric Dübois` → `ÉD`)
+- Empty/whitespace name → empty string
+
+## Color derivation
+
+When `initialsColor` is not provided, a deterministic color is picked from a curated palette using a CRC32 hash of `name`. The same name always gets the same color, which keeps avatars visually stable across pages and sessions.
+
+## Visible flag for items
+
+Each dropdown item supports a `visible: bool` flag. When `visible` is explicitly `false`, the item is filtered out before rendering. This lets you express conditional items (e.g., admin links protected by a permission check) directly in the items array, without surrounding `{% if %}` blocks:
+
+```twig
+{{ component('Enabel:Ux:UserMenu', {
+    name: app.user.displayName,
+    items: [
+        {label: 'Profile', link: path('app_profile'), icon: 'bi:person-circle'},
+        {label: 'Admin', link: path('admin_dashboard'), icon: 'bi:gear-fill', visible: is_granted('ROLE_ADMIN')},
+        {divider: true},
+        {label: 'Logout', link: path('app_logout'), icon: 'bi:box-arrow-right'},
+    ],
+}) }}
+```
+
+## Automatic active detection
+
+Same behavior as [MenuItem](menuItem.md): each item with a `link` is automatically marked active when its link matches the current request path (exact match, or prefix match for non-root paths). Manual `active` always overrides auto-detection. Dividers and headers are skipped.
+
+## Usage
+
+### Minimal usage (auto-derived initials and color)
+
+```twig
+{% component 'Enabel:Ux:Navbar' with { name: 'My App' } %}
+    {% block content %}
+        {% component 'Enabel:Ux:Menu' with { align: 'end' } %}
+            {% block content %}
+                {{ component('Enabel:Ux:UserMenu', {
+                    name: app.user.displayName,
+                    items: [
+                        {label: 'Profile', link: path('app_profile'), icon: 'bi:person-circle'},
+                        {label: 'Logout', link: path('app_logout'), icon: 'bi:box-arrow-right'},
+                    ],
+                }) }}
+            {% endblock %}
+        {% endcomponent %}
+    {% endblock %}
+{% endcomponent %}
+```
+
+### With a profile picture
+
+```twig
+{{ component('Enabel:Ux:UserMenu', {
+    name: app.user.displayName,
+    image: app.user.profilePictureDataUri,
+    items: [
+        {label: 'Profile', link: path('app_profile'), icon: 'bi:person-circle'},
+        {label: 'Logout', link: path('app_logout'), icon: 'bi:box-arrow-right'},
+    ],
+}) }}
+```
+
+### With pre-computed initials and color
+
+If your `User` entity already exposes initials and a brand color, override the derivation:
+
+```twig
+{{ component('Enabel:Ux:UserMenu', {
+    name: app.user.displayName,
+    initials: app.user.initials,
+    initialsColor: app.user.avatarColor,
+    items: [...],
+}) }}
+```
+
+### Conditional items
+
+```twig
+{{ component('Enabel:Ux:UserMenu', {
+    name: app.user.displayName,
+    items: [
+        {label: 'Profile', link: path('app_profile'), icon: 'bi:person-circle'},
+        {label: 'Configuration', link: path('admin_dashboard'), icon: 'bi:gear-fill', visible: is_granted('ROLE_ADMIN')},
+        {divider: true},
+        {label: 'Logout', link: path('app_logout'), icon: 'bi:box-arrow-right'},
+    ],
+}) }}
+```
+
+### Show the user name next to the avatar
+
+```twig
+{{ component('Enabel:Ux:UserMenu', {
+    name: app.user.displayName,
+    hideName: false,
+    items: [...],
+}) }}
+```
+
+## See Also
+
+- [Navbar Component](navbar.md) - Main navigation container
+- [Menu Component](menu.md) - Container for organizing navigation items
+- [MenuItem Component](menuItem.md) - Individual navigation links or dropdowns
+- [LocaleSwitcher Component](localeSwitcher.md) - Locale switcher dropdown
diff --git a/docs/index.md b/docs/index.md
index cbbc056..acbd1fd 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -18,6 +18,7 @@ https://github.com/Enabel/Ux
   - [Navbar](Navigation/navbar.md) - Main navigation container with logo, name, and link configuration
   - [Menu](Navigation/menu.md) - Menu container for organizing navigation items
   - [MenuItem](Navigation/menuItem.md) - Individual navigation links or items
+  - [UserMenu](Navigation/userMenu.md) - User menu with avatar (photo or auto-derived colored initials) and dropdown
   - [LocaleSwitcher](Navigation/localeSwitcher.md) - A locale switcher dropdown for Bootstrap navbar
   - [Tab](Navigation/tab.md) - A Bootstrap nav-tabs/nav-pills component for creating tabbed navigation
 
diff --git a/src/Component/Navigation/UserMenu.php b/src/Component/Navigation/UserMenu.php
new file mode 100644
index 0000000..2010064
--- /dev/null
+++ b/src/Component/Navigation/UserMenu.php
@@ -0,0 +1,184 @@
+<?php
+
+/*
+ * This file is part of the Enabel UX package.
+ * Copyright (c) Enabel <https://enabel.be/>
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Enabel\Ux\Component\Navigation;
+
+use Symfony\Component\HttpFoundation\RequestStack;
+use Symfony\Component\OptionsResolver\OptionsResolver;
+use Symfony\UX\TwigComponent\Attribute\PreMount;
+
+class UserMenu
+{
+    /**
+     * Predefined palette used to derive a stable background color from the user name
+     * when no explicit `initialsColor` is provided.
+     */
+    private const COLOR_PALETTE = [
+        '#0ea5e9',
+        '#10b981',
+        '#f59e0b',
+        '#ef4444',
+        '#8b5cf6',
+        '#ec4899',
+        '#14b8a6',
+        '#f97316',
+        '#6366f1',
+        '#84cc16',
+    ];
+
+    public string $name;
+    public ?string $image;
+    public string $initials;
+    public string $initialsColor;
+    public string $dropdownAlign;
+    public bool $hideName;
+    /**
+     * @var array<int, array<string, mixed>>
+     */
+    public array $items;
+
+    public function __construct(
+        private readonly RequestStack $requestStack,
+    ) {
+    }
+
+    /**
+     * @param array<string, mixed> $data
+     *
+     * @return array<string, mixed>
+     */
+    #[PreMount]
+    public function preMount(array $data): array
+    {
+        $resolver = new OptionsResolver();
+        $this->configureOptions($resolver);
+
+        $resolved = $resolver->resolve($data);
+
+        // Auto-derive initials from name if not explicitly provided
+        if (null === $resolved['initials']) {
+            $resolved['initials'] = $this->deriveInitials($resolved['name']);
+        }
+
+        // Auto-derive a stable background color from the name if not explicitly provided
+        if (null === $resolved['initialsColor']) {
+            $resolved['initialsColor'] = $this->deriveColor($resolved['name']);
+        }
+
+        // Filter items by visibility and auto-detect active state
+        $resolved['items'] = $this->processItems($resolved['items']);
+
+        return $resolved + $data;
+    }
+
+    public function configureOptions(OptionsResolver $resolver): void
+    {
+        $resolver->setIgnoreUndefined();
+        $resolver->setRequired('name');
+        $resolver->setDefaults([
+            'image' => null,
+            'initials' => null,
+            'initialsColor' => null,
+            'dropdownAlign' => 'end',
+            'hideName' => true,
+            'items' => [],
+        ]);
+
+        $resolver->setAllowedTypes('name', 'string');
+        $resolver->setAllowedTypes('image', ['string', 'null']);
+        $resolver->setAllowedTypes('initials', ['string', 'null']);
+        $resolver->setAllowedTypes('initialsColor', ['string', 'null']);
+        $resolver->setAllowedTypes('dropdownAlign', 'string');
+        $resolver->setAllowedTypes('hideName', 'bool');
+        $resolver->setAllowedTypes('items', 'array');
+
+        $resolver->setAllowedValues('dropdownAlign', ['start', 'end']);
+    }
+
+    private function deriveInitials(string $name): string
+    {
+        $name = trim($name);
+        if ('' === $name) {
+            return '';
+        }
+
+        $parts = preg_split('/\s+/u', $name) ?: [];
+
+        if (1 === \count($parts)) {
+            return mb_strtoupper(mb_substr($parts[0], 0, 2));
+        }
+
+        $first = mb_strtoupper(mb_substr($parts[0], 0, 1));
+        $last = mb_strtoupper(mb_substr((string) end($parts), 0, 1));
+
+        return $first.$last;
+    }
+
+    private function deriveColor(string $name): string
+    {
+        if ('' === trim($name)) {
+            return self::COLOR_PALETTE[0];
+        }
+
+        $hash = crc32($name);
+
+        return self::COLOR_PALETTE[$hash % \count(self::COLOR_PALETTE)];
+    }
+
+    /**
+     * @param array<int, array<string, mixed>> $items
+     *
+     * @return array<int, array<string, mixed>>
+     */
+    private function processItems(array $items): array
+    {
+        $processed = [];
+        foreach ($items as $item) {
+            // Filter out items explicitly marked as not visible
+            if (isset($item['visible']) && false === $item['visible']) {
+                continue;
+            }
+
+            // Skip dividers and headers (no active state, no link processing)
+            if (isset($item['divider']) || isset($item['header'])) {
+                $processed[] = $item;
+                continue;
+            }
+
+            // Auto-detect active state if not explicitly set and link is provided
+            if (!isset($item['active']) && isset($item['link']) && $item['link']) {
+                $item['active'] = $this->isCurrentRoute((string) $item['link']);
+            }
+
+            $processed[] = $item;
+        }
+
+        return $processed;
+    }
+
+    private function isCurrentRoute(string $href): bool
+    {
+        $request = $this->requestStack->getCurrentRequest();
+        if (!$request) {
+            return false;
+        }
+
+        $currentPath = $request->getPathInfo();
+
+        if ($currentPath === $href) {
+            return true;
+        }
+
+        if ('/' !== $href && str_starts_with($currentPath, $href)) {
+            return true;
+        }
+
+        return false;
+    }
+}
diff --git a/templates/navigation/menu.html.twig b/templates/navigation/menu.html.twig
index c5855a8..c94722d 100644
--- a/templates/navigation/menu.html.twig
+++ b/templates/navigation/menu.html.twig
@@ -1,7 +1,7 @@
 {# Menu component #}
 {% set alignClass = align == 'center' ? 'mx-auto justify-content-center' : (align == 'end' ? 'd-flex justify-content-end ms-auto' : 'me-auto') %}
 
-<ul class="navbar-nav mb-2 mb-lg-0 {{ alignClass }} {{ attributes.render('class') }}" {{ attributes.defaults({}) }}>
+<ul class="navbar-nav align-items-center mb-2 mb-lg-0 {{ alignClass }} {{ attributes.render('class') }}" {{ attributes.defaults({}) }}>
     {% block content %}
     {% endblock %}
 </ul>
diff --git a/templates/navigation/user_menu.html.twig b/templates/navigation/user_menu.html.twig
new file mode 100644
index 0000000..eda17c7
--- /dev/null
+++ b/templates/navigation/user_menu.html.twig
@@ -0,0 +1,40 @@
+{# UserMenu component #}
+{% set dropdownAlignClass = dropdownAlign == 'end' ? 'dropdown-menu-end' : 'dropdown-menu-start' %}
+
+<li class="nav-item dropdown {{ attributes.render('class') }}" {{ attributes.defaults({}) }}>
+    <a class="nav-link dropdown-toggle d-flex align-items-center gap-2 py-1" href="#" role="button" data-bs-toggle="dropdown" aria-expanded="false" aria-label="{{ name }}">
+        {% if image %}
+            <img src="{{ image }}" alt="" class="rounded-circle" style="width: 3rem; height: 3rem; object-fit: cover; border: 2px solid rgba(255, 255, 255, 0.4);">
+        {% else %}
+            <span class="rounded-circle d-inline-flex align-items-center justify-content-center text-white fw-bold" style="width: 3rem; height: 3rem; background: {{ initialsColor }}; font-size: 1.125rem;" aria-hidden="true">{{ initials }}</span>
+        {% endif %}
+        {% if not hideName %}
+            <span>{{ name }}</span>
+        {% endif %}
+    </a>
+    <ul class="dropdown-menu {{ dropdownAlignClass }}">
+        <li><h6 class="dropdown-header">{{ name }}</h6></li>
+        {% if items|length > 0 %}
+            <li><hr class="dropdown-divider"></li>
+            {% for item in items %}
+                {% if item.divider|default(false) %}
+                    <li><hr class="dropdown-divider"></li>
+                {% elseif item.header|default(false) %}
+                    <li><h6 class="dropdown-header">{{ item.label }}</h6></li>
+                {% else %}
+                    <li>
+                        <a class="dropdown-item{% if item.active|default(false) %} active{% endif %}{% if item.disabled|default(false) %} disabled{% endif %}"
+                           {% if item.link|default(null) and not item.disabled|default(false) %}href="{{ item.link }}"{% endif %}
+                           {% if item.active|default(false) %}aria-current="page"{% endif %}
+                           {% if item.disabled|default(false) %}aria-disabled="true" tabindex="-1"{% endif %}>
+                            {% if item.icon|default(null) %}
+                                <twig:ux:icon name="{{ item.icon }}" class="me-2" style="width: 1.1rem; height: 1.1rem;" />
+                            {% endif %}
+                            {{ item.label }}
+                        </a>
+                    </li>
+                {% endif %}
+            {% endfor %}
+        {% endif %}
+    </ul>
+</li>
\ No newline at end of file
diff --git a/tests/Component/Navigation/UserMenuTest.php b/tests/Component/Navigation/UserMenuTest.php
new file mode 100644
index 0000000..b6b82b8
--- /dev/null
+++ b/tests/Component/Navigation/UserMenuTest.php
@@ -0,0 +1,329 @@
+<?php
+
+/*
+ * This file is part of the Enabel UX package.
+ * Copyright (c) Enabel <https://enabel.be/>
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Enabel\Ux\Tests\Component\Navigation;
+
+use Enabel\Ux\Component\Navigation\UserMenu;
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\RequestStack;
+use Symfony\Component\OptionsResolver\Exception\InvalidOptionsException;
+use Symfony\Component\OptionsResolver\Exception\MissingOptionsException;
+
+class UserMenuTest extends TestCase
+{
+    private function createUserMenu(?Request $request = null): UserMenu
+    {
+        $requestStack = new RequestStack();
+        if ($request) {
+            $requestStack->push($request);
+        }
+
+        return new UserMenu($requestStack);
+    }
+
+    public function testNameIsRequired(): void
+    {
+        $this->expectException(MissingOptionsException::class);
+
+        $component = $this->createUserMenu();
+        $component->preMount([]);
+    }
+
+    public function testDefaultsAreApplied(): void
+    {
+        $component = $this->createUserMenu();
+        $data = $component->preMount(['name' => 'Damien Lagae']);
+
+        $this->assertSame('Damien Lagae', $data['name']);
+        $this->assertNull($data['image']);
+        $this->assertSame('end', $data['dropdownAlign']);
+        $this->assertTrue($data['hideName']);
+        $this->assertSame([], $data['items']);
+    }
+
+    public function testInitialsAreDerivedFromTwoWordName(): void
+    {
+        $component = $this->createUserMenu();
+        $data = $component->preMount(['name' => 'Damien Lagae']);
+
+        $this->assertSame('DL', $data['initials']);
+    }
+
+    public function testInitialsUseFirstAndLastWordOnly(): void
+    {
+        $component = $this->createUserMenu();
+        $data = $component->preMount(['name' => 'John Ronald Reuel Tolkien']);
+
+        $this->assertSame('JT', $data['initials']);
+    }
+
+    public function testInitialsAreDerivedFromSingleWordName(): void
+    {
+        $component = $this->createUserMenu();
+        $data = $component->preMount(['name' => 'Damien']);
+
+        $this->assertSame('DA', $data['initials']);
+    }
+
+    public function testInitialsAreUppercaseAndMultibyteSafe(): void
+    {
+        $component = $this->createUserMenu();
+        $data = $component->preMount(['name' => 'éric Dübois']);
+
+        $this->assertSame('ÉD', $data['initials']);
+    }
+
+    public function testEmptyNameProducesEmptyInitials(): void
+    {
+        $component = $this->createUserMenu();
+        $data = $component->preMount(['name' => '   ']);
+
+        $this->assertSame('', $data['initials']);
+    }
+
+    public function testInitialsCanBeOverridden(): void
+    {
+        $component = $this->createUserMenu();
+        $data = $component->preMount([
+            'name' => 'Damien Lagae',
+            'initials' => 'XY',
+        ]);
+
+        $this->assertSame('XY', $data['initials']);
+    }
+
+    public function testInitialsColorIsDerivedFromName(): void
+    {
+        $component = $this->createUserMenu();
+        $data = $component->preMount(['name' => 'Damien Lagae']);
+
+        $this->assertMatchesRegularExpression('/^#[0-9a-f]{6}$/i', $data['initialsColor']);
+    }
+
+    public function testInitialsColorIsStableForSameName(): void
+    {
+        $component = $this->createUserMenu();
+        $first = $component->preMount(['name' => 'Damien Lagae']);
+        $second = $component->preMount(['name' => 'Damien Lagae']);
+
+        $this->assertSame($first['initialsColor'], $second['initialsColor']);
+    }
+
+    public function testInitialsColorCanBeOverridden(): void
+    {
+        $component = $this->createUserMenu();
+        $data = $component->preMount([
+            'name' => 'Damien Lagae',
+            'initialsColor' => '#123456',
+        ]);
+
+        $this->assertSame('#123456', $data['initialsColor']);
+    }
+
+    public function testImageIsAccepted(): void
+    {
+        $component = $this->createUserMenu();
+        $data = $component->preMount([
+            'name' => 'Damien Lagae',
+            'image' => 'data:image/png;base64,AAAA',
+        ]);
+
+        $this->assertSame('data:image/png;base64,AAAA', $data['image']);
+    }
+
+    public function testItemsAreKeptByDefault(): void
+    {
+        $component = $this->createUserMenu();
+        $data = $component->preMount([
+            'name' => 'Damien Lagae',
+            'items' => [
+                ['label' => 'Profile', 'link' => '/profile'],
+                ['label' => 'Logout', 'link' => '/logout'],
+            ],
+        ]);
+
+        $this->assertCount(2, $data['items']);
+    }
+
+    public function testItemsWithVisibleFalseAreFiltered(): void
+    {
+        $component = $this->createUserMenu();
+        $data = $component->preMount([
+            'name' => 'Damien Lagae',
+            'items' => [
+                ['label' => 'Profile', 'link' => '/profile'],
+                ['label' => 'Admin', 'link' => '/admin', 'visible' => false],
+                ['label' => 'Logout', 'link' => '/logout'],
+            ],
+        ]);
+
+        $this->assertCount(2, $data['items']);
+        $this->assertSame('Profile', $data['items'][0]['label']);
+        $this->assertSame('Logout', $data['items'][1]['label']);
+    }
+
+    public function testItemsWithVisibleTrueAreKept(): void
+    {
+        $component = $this->createUserMenu();
+        $data = $component->preMount([
+            'name' => 'Damien Lagae',
+            'items' => [
+                ['label' => 'Profile', 'link' => '/profile', 'visible' => true],
+            ],
+        ]);
+
+        $this->assertCount(1, $data['items']);
+    }
+
+    public function testDividersAndHeadersArePreserved(): void
+    {
+        $component = $this->createUserMenu();
+        $data = $component->preMount([
+            'name' => 'Damien Lagae',
+            'items' => [
+                ['header' => true, 'label' => 'Section'],
+                ['label' => 'Profile', 'link' => '/profile'],
+                ['divider' => true],
+                ['label' => 'Logout', 'link' => '/logout'],
+            ],
+        ]);
+
+        $this->assertCount(4, $data['items']);
+        $this->assertTrue($data['items'][0]['header']);
+        $this->assertTrue($data['items'][2]['divider']);
+    }
+
+    public function testItemsAutoDetectActiveState(): void
+    {
+        $request = Request::create('/profile');
+        $component = $this->createUserMenu($request);
+        $data = $component->preMount([
+            'name' => 'Damien Lagae',
+            'items' => [
+                ['label' => 'Profile', 'link' => '/profile'],
+                ['label' => 'Logout', 'link' => '/logout'],
+            ],
+        ]);
+
+        $this->assertTrue($data['items'][0]['active']);
+        $this->assertFalse($data['items'][1]['active']);
+    }
+
+    public function testItemsAutoDetectActiveStateWithPrefix(): void
+    {
+        $request = Request::create('/admin/users/123');
+        $component = $this->createUserMenu($request);
+        $data = $component->preMount([
+            'name' => 'Damien Lagae',
+            'items' => [
+                ['label' => 'Admin', 'link' => '/admin'],
+            ],
+        ]);
+
+        $this->assertTrue($data['items'][0]['active']);
+    }
+
+    public function testItemsManualActiveOverridesAutoDetection(): void
+    {
+        $request = Request::create('/profile');
+        $component = $this->createUserMenu($request);
+        $data = $component->preMount([
+            'name' => 'Damien Lagae',
+            'items' => [
+                ['label' => 'Profile', 'link' => '/profile', 'active' => false],
+            ],
+        ]);
+
+        $this->assertFalse($data['items'][0]['active']);
+    }
+
+    public function testHideNameCanBeDisabled(): void
+    {
+        $component = $this->createUserMenu();
+        $data = $component->preMount([
+            'name' => 'Damien Lagae',
+            'hideName' => false,
+        ]);
+
+        $this->assertFalse($data['hideName']);
+    }
+
+    public function testDropdownAlignDefaultsToEnd(): void
+    {
+        $component = $this->createUserMenu();
+        $data = $component->preMount(['name' => 'Damien Lagae']);
+
+        $this->assertSame('end', $data['dropdownAlign']);
+    }
+
+    public function testDropdownAlignCanBeStart(): void
+    {
+        $component = $this->createUserMenu();
+        $data = $component->preMount([
+            'name' => 'Damien Lagae',
+            'dropdownAlign' => 'start',
+        ]);
+
+        $this->assertSame('start', $data['dropdownAlign']);
+    }
+
+    public function testInvalidDropdownAlignThrows(): void
+    {
+        $this->expectException(InvalidOptionsException::class);
+
+        $component = $this->createUserMenu();
+        $component->preMount([
+            'name' => 'Damien Lagae',
+            'dropdownAlign' => 'middle',
+        ]);
+    }
+
+    public function testInvalidNameTypeThrows(): void
+    {
+        $this->expectException(InvalidOptionsException::class);
+
+        $component = $this->createUserMenu();
+        $component->preMount(['name' => 123]);
+    }
+
+    public function testInvalidImageTypeThrows(): void
+    {
+        $this->expectException(InvalidOptionsException::class);
+
+        $component = $this->createUserMenu();
+        $component->preMount([
+            'name' => 'Damien Lagae',
+            'image' => 123,
+        ]);
+    }
+
+    public function testInvalidItemsTypeThrows(): void
+    {
+        $this->expectException(InvalidOptionsException::class);
+
+        $component = $this->createUserMenu();
+        $component->preMount([
+            'name' => 'Damien Lagae',
+            'items' => 'not-an-array',
+        ]);
+    }
+
+    public function testPreMountPreservesAdditionalData(): void
+    {
+        $component = $this->createUserMenu();
+        $data = $component->preMount([
+            'name' => 'Damien Lagae',
+            'custom_attribute' => 'value',
+        ]);
+
+        $this->assertArrayHasKey('custom_attribute', $data);
+        $this->assertSame('value', $data['custom_attribute']);
+    }
+}