From 3d14551111100b7275a2cd0bb8b2e7bd0eafee23 Mon Sep 17 00:00:00 2001
From: BryanFRD <bryanferrando59@gmail.com>
Date: Sun, 25 Oct 2026 10:53:07 +0100
Subject: [PATCH 1/5] fix(ui-ng): make flr-menu keyboard navigable

Focus the first item on open, add arrow/Home/End navigation, close on Tab and restore focus to the trigger. Drop role=menu from the inline brand dropdown, which is a plain list of links.
---
 packages/showcase/src/stories/Menu.stories.ts | 30 ++++++++++
 .../brand-dropdown.component.ts               |  4 +-
 packages/ui-ng/src/lib/menu/menu.component.ts | 59 ++++++++++++++++++-
 3 files changed, 88 insertions(+), 5 deletions(-)

diff --git a/packages/showcase/src/stories/Menu.stories.ts b/packages/showcase/src/stories/Menu.stories.ts
index 78289708..b91b0808 100644
--- a/packages/showcase/src/stories/Menu.stories.ts
+++ b/packages/showcase/src/stories/Menu.stories.ts
@@ -7,6 +7,7 @@ import {
 } from '@ferrlabs/ui-ng';
 import type { Meta, StoryObj } from '@storybook/angular';
 import { moduleMetadata } from '@storybook/angular';
+import { expect, userEvent, waitFor, within } from 'storybook/test';
 
 const meta: Meta<MenuComponent> = {
   title: 'Overlays/Menu',
@@ -50,3 +51,32 @@ type Story = StoryObj<MenuComponent>;
 export const Default: Story = {};
 
 export const AlignEnd: Story = { args: { align: 'end' } };
+
+export const KeyboardNavigation: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const overlay = within(canvasElement.ownerDocument.body);
+    const trigger = canvas.getByRole('button', { name: 'Actions' });
+
+    trigger.focus();
+    await userEvent.keyboard('{Enter}');
+    const first = await overlay.findByRole('menuitem', { name: 'Trigger now' });
+    await waitFor(() => expect(first).toHaveFocus());
+
+    await userEvent.keyboard('{ArrowDown}');
+    await expect(overlay.getByRole('menuitem', { name: 'Trigger with overrides' })).toHaveFocus();
+
+    await userEvent.keyboard('{End}');
+    await expect(overlay.getByRole('menuitem', { name: 'Delete agent' })).toHaveFocus();
+
+    await userEvent.keyboard('{ArrowDown}');
+    await expect(first).toHaveFocus();
+
+    await userEvent.keyboard('{Home}{ArrowUp}');
+    await expect(overlay.getByRole('menuitem', { name: 'Delete agent' })).toHaveFocus();
+
+    await userEvent.keyboard('{Escape}');
+    await waitFor(() => expect(overlay.queryByRole('menu')).toBeNull());
+    await expect(trigger).toHaveFocus();
+  },
+};
diff --git a/packages/ui-ng/src/lib/brand-dropdown/brand-dropdown.component.ts b/packages/ui-ng/src/lib/brand-dropdown/brand-dropdown.component.ts
index 5d183b57..7801ac48 100644
--- a/packages/ui-ng/src/lib/brand-dropdown/brand-dropdown.component.ts
+++ b/packages/ui-ng/src/lib/brand-dropdown/brand-dropdown.component.ts
@@ -59,7 +59,6 @@ interface BrandRow {
     <button
       type="button"
       class="flr-bd__trigger"
-      [attr.aria-haspopup]="'menu'"
       [attr.aria-expanded]="open()"
       [title]="triggerTitle()"
       (click)="open.set(!open())"
@@ -71,7 +70,7 @@ interface BrandRow {
     </button>
 
     @if (open()) {
-      <div class="flr-bd__panel" role="menu">
+      <div class="flr-bd__panel">
         @if (!collapsed()) {
           <div class="mono flr-bd__eyebrow">Switch app</div>
         }
@@ -86,7 +85,6 @@ interface BrandRow {
             [class.flr-bd__app--current]="row.app.id === current()"
             [class.flr-bd__app--collapsed]="collapsed()"
             [href]="row.app.href"
-            role="menuitem"
             [attr.target]="row.app.newTab ? '_blank' : null"
             [attr.rel]="row.app.newTab ? 'noreferrer noopener' : null"
             [attr.aria-current]="row.app.id === current() ? 'page' : null"
diff --git a/packages/ui-ng/src/lib/menu/menu.component.ts b/packages/ui-ng/src/lib/menu/menu.component.ts
index 6a1023b8..ad0e81ab 100644
--- a/packages/ui-ng/src/lib/menu/menu.component.ts
+++ b/packages/ui-ng/src/lib/menu/menu.component.ts
@@ -1,11 +1,13 @@
 import { NgTemplateOutlet } from '@angular/common';
 import {
+  afterNextRender,
   afterRenderEffect,
   ChangeDetectionStrategy,
   Component,
   computed,
   ElementRef,
   inject,
+  Injector,
   input,
   model,
   output,
@@ -36,20 +38,23 @@ export type MenuDirection = 'down' | 'up';
 
     <ng-template
       cdkConnectedOverlay
+      #overlay="cdkConnectedOverlay"
       [cdkConnectedOverlayOrigin]="origin"
       [cdkConnectedOverlayOpen]="open()"
       [cdkConnectedOverlayPositions]="positions()"
       [cdkConnectedOverlayHasBackdrop]="true"
       cdkConnectedOverlayBackdropClass="cdk-overlay-transparent-backdrop"
       (backdropClick)="open.set(false)"
-      (detach)="open.set(false)"
+      (attach)="onAttach(overlay.overlayRef.overlayElement)"
+      (detach)="onDetach()"
     >
-      <!-- eslint-disable-next-line @angular-eslint/template/click-events-have-key-events, @angular-eslint/template/interactive-supports-focus -->
+      <!-- eslint-disable-next-line @angular-eslint/template/interactive-supports-focus -->
       <div
         class="flr-menu__panel"
         role="menu"
         [style.min-width.px]="minWidth()"
         (click)="open.set(false)"
+        (keydown)="onKeydown($event)"
       >
         <ng-content select="[flr-menu-content]" />
       </div>
@@ -82,6 +87,7 @@ export class MenuComponent {
   readonly open = model(false);
 
   private readonly host = inject<ElementRef<HTMLElement>>(ElementRef);
+  private readonly injector = inject(Injector);
 
   constructor() {
     afterRenderEffect(() => {
@@ -117,6 +123,55 @@ export class MenuComponent {
   protected toggle(): void {
     this.open.set(!this.open());
   }
+
+  private panel: HTMLElement | null = null;
+
+  protected onAttach(overlayElement: HTMLElement): void {
+    afterNextRender(
+      () => {
+        this.panel = overlayElement.querySelector<HTMLElement>('.flr-menu__panel');
+        this.items()[0]?.focus();
+      },
+      { injector: this.injector },
+    );
+  }
+
+  protected onDetach(): void {
+    this.panel = null;
+    this.open.set(false);
+    this.host.nativeElement.querySelector<HTMLElement>('[flr-menu-trigger]')?.focus();
+  }
+
+  protected onKeydown(event: KeyboardEvent): void {
+    const items = this.items();
+    const current = items.indexOf(document.activeElement as HTMLElement);
+    switch (event.key) {
+      case 'ArrowDown':
+        items[(current + 1) % items.length]?.focus();
+        break;
+      case 'ArrowUp':
+        items[(current - 1 + items.length) % items.length]?.focus();
+        break;
+      case 'Home':
+        items[0]?.focus();
+        break;
+      case 'End':
+        items.at(-1)?.focus();
+        break;
+      case 'Tab':
+        this.open.set(false);
+        return;
+      default:
+        return;
+    }
+    event.preventDefault();
+  }
+
+  private items(): HTMLElement[] {
+    return Array.from(
+      this.panel?.querySelectorAll<HTMLElement>('[role="menuitem"]:not(:disabled)') ?? [],
+    );
+  }
 }
 
 @Component({

From 41f6956ba73f63159db23716dc3fe7373b4af688 Mon Sep 17 00:00:00 2001
From: BryanFRD <bryanferrando59@gmail.com>
Date: Sun, 25 Oct 2026 10:57:09 +0100
Subject: [PATCH 2/5] refactor(ui-ng): use FocusKeyManager for menu focus
 handling

---
 packages/ui-ng/src/lib/menu/menu.component.ts | 76 +++++++++----------
 1 file changed, 36 insertions(+), 40 deletions(-)

diff --git a/packages/ui-ng/src/lib/menu/menu.component.ts b/packages/ui-ng/src/lib/menu/menu.component.ts
index ad0e81ab..e7a8dcc1 100644
--- a/packages/ui-ng/src/lib/menu/menu.component.ts
+++ b/packages/ui-ng/src/lib/menu/menu.component.ts
@@ -5,14 +5,17 @@ import {
   ChangeDetectionStrategy,
   Component,
   computed,
+  contentChildren,
   ElementRef,
   inject,
   Injector,
   input,
   model,
   output,
+  viewChild,
   ViewEncapsulation,
 } from '@angular/core';
+import { FocusKeyManager, type FocusableOption } from '@angular/cdk/a11y';
 import { type ConnectedPosition, OverlayModule } from '@angular/cdk/overlay';
 
 export type MenuAlign = 'start' | 'end';
@@ -38,14 +41,13 @@ export type MenuDirection = 'down' | 'up';
 
     <ng-template
       cdkConnectedOverlay
-      #overlay="cdkConnectedOverlay"
       [cdkConnectedOverlayOrigin]="origin"
       [cdkConnectedOverlayOpen]="open()"
       [cdkConnectedOverlayPositions]="positions()"
       [cdkConnectedOverlayHasBackdrop]="true"
       cdkConnectedOverlayBackdropClass="cdk-overlay-transparent-backdrop"
       (backdropClick)="open.set(false)"
-      (attach)="onAttach(overlay.overlayRef.overlayElement)"
+      (attach)="onAttach()"
       (detach)="onDetach()"
     >
       <!-- eslint-disable-next-line @angular-eslint/template/interactive-supports-focus -->
@@ -124,53 +126,39 @@ export class MenuComponent {
     this.open.set(!this.open());
   }
 
-  private panel: HTMLElement | null = null;
+  private readonly items = contentChildren(MenuItemComponent, { descendants: true });
 
-  protected onAttach(overlayElement: HTMLElement): void {
-    afterNextRender(
-      () => {
-        this.panel = overlayElement.querySelector<HTMLElement>('.flr-menu__panel');
-        this.items()[0]?.focus();
-      },
-      { injector: this.injector },
-    );
+  private readonly options = computed<FocusableOption[]>(() =>
+    this.items().map((item) => ({
+      focus: () => item.focus(),
+      disabled: item.disabled(),
+    })),
+  );
+
+  private readonly keyManager = new FocusKeyManager(this.options, this.injector)
+    .withWrap()
+    .withHomeAndEnd()
+    .withTypeAhead()
+    .skipPredicate((item) => item.disabled === true);
+
+  protected onAttach(): void {
+    afterNextRender(() => this.keyManager.setFirstItemActive(), { injector: this.injector });
   }
 
   protected onDetach(): void {
-    this.panel = null;
     this.open.set(false);
-    this.host.nativeElement.querySelector<HTMLElement>('[flr-menu-trigger]')?.focus();
+    const active = document.activeElement;
+    if (!active || active === document.body) {
+      this.host.nativeElement.querySelector<HTMLElement>('[flr-menu-trigger]')?.focus();
+    }
   }
 
   protected onKeydown(event: KeyboardEvent): void {
-    const items = this.items();
-    const current = items.indexOf(document.activeElement as HTMLElement);
-    switch (event.key) {
-      case 'ArrowDown':
-        items[(current + 1) % items.length]?.focus();
-        break;
-      case 'ArrowUp':
-        items[(current - 1 + items.length) % items.length]?.focus();
-        break;
-      case 'Home':
-        items[0]?.focus();
-        break;
-      case 'End':
-        items.at(-1)?.focus();
-        break;
-      case 'Tab':
-        this.open.set(false);
-        return;
-      default:
-        return;
+    if (event.key === 'Tab') {
+      this.open.set(false);
+      return;
     }
-    event.preventDefault();
-  }
-
-  private items(): HTMLElement[] {
-    return Array.from(
-      this.panel?.querySelectorAll<HTMLElement>('[role="menuitem"]:not(:disabled)') ?? [],
-    );
+    this.keyManager.onKeydown(event);
   }
 }
 
@@ -185,6 +173,7 @@ export class MenuComponent {
         [class.flr-menu-item--danger]="destructive()"
         [href]="href()"
         role="menuitem"
+        #control
       >
         <ng-container [ngTemplateOutlet]="body" />
       </a>
@@ -194,6 +183,7 @@ export class MenuComponent {
         class="flr-menu-item"
         [class.flr-menu-item--danger]="destructive()"
         role="menuitem"
+        #control
         [disabled]="disabled()"
         (click)="onClick()"
       >
@@ -288,6 +278,12 @@ export class MenuItemComponent {
 
   readonly selected = output<void>();
 
+  private readonly control = viewChild<ElementRef<HTMLElement>>('control');
+
+  focus(): void {
+    this.control()?.nativeElement.focus();
+  }
+
   protected onClick(): void {
     if (this.disabled()) return;
     this.selected.emit();

From ae9fb3a53f57e98f9e54b35c0ba8edeed8e749e7 Mon Sep 17 00:00:00 2001
From: BryanFRD <bryanferrando59@gmail.com>
Date: Sun, 25 Oct 2026 11:01:51 +0100
Subject: [PATCH 3/5] fix(ui-ng): keep menu focus options stable across item
 updates

---
 packages/ui-ng/src/lib/menu/menu.component.ts | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/packages/ui-ng/src/lib/menu/menu.component.ts b/packages/ui-ng/src/lib/menu/menu.component.ts
index e7a8dcc1..7e004e12 100644
--- a/packages/ui-ng/src/lib/menu/menu.component.ts
+++ b/packages/ui-ng/src/lib/menu/menu.component.ts
@@ -128,11 +128,19 @@ export class MenuComponent {
 
   private readonly items = contentChildren(MenuItemComponent, { descendants: true });
 
+  private readonly optionsByItem = new WeakMap<MenuItemComponent, FocusableOption>();
+
   private readonly options = computed<FocusableOption[]>(() =>
-    this.items().map((item) => ({
-      focus: () => item.focus(),
-      disabled: item.disabled(),
-    })),
+    this.items().map((item) => {
+      const option = this.optionsByItem.get(item) ?? {
+        focus: () => item.focus(),
+        get disabled() {
+          return item.disabled();
+        },
+      };
+      this.optionsByItem.set(item, option);
+      return option;
+    }),
   );
 
   private readonly keyManager = new FocusKeyManager(this.options, this.injector)

From 49b5ab38541b2e0027ee961a236dddb1d6e003b4 Mon Sep 17 00:00:00 2001
From: BryanFRD <bryanferrando59@gmail.com>
Date: Sun, 25 Oct 2026 11:09:37 +0100
Subject: [PATCH 4/5] test(showcase): send keyCode in menu keyboard story

---
 packages/showcase/src/stories/Menu.stories.ts | 22 ++++++++++++++-----
 1 file changed, 16 insertions(+), 6 deletions(-)

diff --git a/packages/showcase/src/stories/Menu.stories.ts b/packages/showcase/src/stories/Menu.stories.ts
index b91b0808..2beb49b8 100644
--- a/packages/showcase/src/stories/Menu.stories.ts
+++ b/packages/showcase/src/stories/Menu.stories.ts
@@ -52,30 +52,40 @@ export const Default: Story = {};
 
 export const AlignEnd: Story = { args: { align: 'end' } };
 
+const keyboardMap = [
+  { code: 'Enter', key: 'Enter', keyCode: 13 },
+  { code: 'Escape', key: 'Escape', keyCode: 27 },
+  { code: 'End', key: 'End', keyCode: 35 },
+  { code: 'Home', key: 'Home', keyCode: 36 },
+  { code: 'ArrowUp', key: 'ArrowUp', keyCode: 38 },
+  { code: 'ArrowDown', key: 'ArrowDown', keyCode: 40 },
+];
+
 export const KeyboardNavigation: Story = {
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
     const overlay = within(canvasElement.ownerDocument.body);
+    const user = userEvent.setup({ keyboardMap });
     const trigger = canvas.getByRole('button', { name: 'Actions' });
 
     trigger.focus();
-    await userEvent.keyboard('{Enter}');
+    await user.keyboard('{Enter}');
     const first = await overlay.findByRole('menuitem', { name: 'Trigger now' });
     await waitFor(() => expect(first).toHaveFocus());
 
-    await userEvent.keyboard('{ArrowDown}');
+    await user.keyboard('{ArrowDown}');
     await expect(overlay.getByRole('menuitem', { name: 'Trigger with overrides' })).toHaveFocus();
 
-    await userEvent.keyboard('{End}');
+    await user.keyboard('{End}');
     await expect(overlay.getByRole('menuitem', { name: 'Delete agent' })).toHaveFocus();
 
-    await userEvent.keyboard('{ArrowDown}');
+    await user.keyboard('{ArrowDown}');
     await expect(first).toHaveFocus();
 
-    await userEvent.keyboard('{Home}{ArrowUp}');
+    await user.keyboard('{Home}{ArrowUp}');
     await expect(overlay.getByRole('menuitem', { name: 'Delete agent' })).toHaveFocus();
 
-    await userEvent.keyboard('{Escape}');
+    await user.keyboard('{Escape}');
     await waitFor(() => expect(overlay.queryByRole('menu')).toBeNull());
     await expect(trigger).toHaveFocus();
   },

From a41b9084f06806ff7b3ac596cf6180522ca5e4ce Mon Sep 17 00:00:00 2001
From: BryanFRD <bryanferrando59@gmail.com>
Date: Sun, 25 Oct 2026 11:15:22 +0100
Subject: [PATCH 5/5] fix(ui-ng): return menu focus to the inner trigger
 control

The trigger host is a custom element and not focusable. Story now dispatches keydown with keyCode, which user-event omits.
---
 packages/showcase/src/stories/Menu.stories.ts | 40 ++++++++++++-------
 packages/ui-ng/src/lib/menu/menu.component.ts |  8 +++-
 2 files changed, 32 insertions(+), 16 deletions(-)

diff --git a/packages/showcase/src/stories/Menu.stories.ts b/packages/showcase/src/stories/Menu.stories.ts
index 2beb49b8..3590c023 100644
--- a/packages/showcase/src/stories/Menu.stories.ts
+++ b/packages/showcase/src/stories/Menu.stories.ts
@@ -52,40 +52,50 @@ export const Default: Story = {};
 
 export const AlignEnd: Story = { args: { align: 'end' } };
 
-const keyboardMap = [
-  { code: 'Enter', key: 'Enter', keyCode: 13 },
-  { code: 'Escape', key: 'Escape', keyCode: 27 },
-  { code: 'End', key: 'End', keyCode: 35 },
-  { code: 'Home', key: 'Home', keyCode: 36 },
-  { code: 'ArrowUp', key: 'ArrowUp', keyCode: 38 },
-  { code: 'ArrowDown', key: 'ArrowDown', keyCode: 40 },
-];
+const keyCodes: Record<string, number> = {
+  Escape: 27,
+  End: 35,
+  Home: 36,
+  ArrowUp: 38,
+  ArrowDown: 40,
+};
+
+function press(key: string): void {
+  document.activeElement?.dispatchEvent(
+    new KeyboardEvent('keydown', {
+      key,
+      keyCode: keyCodes[key],
+      bubbles: true,
+      cancelable: true,
+    }),
+  );
+}
 
 export const KeyboardNavigation: Story = {
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
     const overlay = within(canvasElement.ownerDocument.body);
-    const user = userEvent.setup({ keyboardMap });
     const trigger = canvas.getByRole('button', { name: 'Actions' });
 
     trigger.focus();
-    await user.keyboard('{Enter}');
+    await userEvent.keyboard('{Enter}');
     const first = await overlay.findByRole('menuitem', { name: 'Trigger now' });
     await waitFor(() => expect(first).toHaveFocus());
 
-    await user.keyboard('{ArrowDown}');
+    press('ArrowDown');
     await expect(overlay.getByRole('menuitem', { name: 'Trigger with overrides' })).toHaveFocus();
 
-    await user.keyboard('{End}');
+    press('End');
     await expect(overlay.getByRole('menuitem', { name: 'Delete agent' })).toHaveFocus();
 
-    await user.keyboard('{ArrowDown}');
+    press('ArrowDown');
     await expect(first).toHaveFocus();
 
-    await user.keyboard('{Home}{ArrowUp}');
+    press('Home');
+    press('ArrowUp');
     await expect(overlay.getByRole('menuitem', { name: 'Delete agent' })).toHaveFocus();
 
-    await user.keyboard('{Escape}');
+    press('Escape');
     await waitFor(() => expect(overlay.queryByRole('menu')).toBeNull());
     await expect(trigger).toHaveFocus();
   },
diff --git a/packages/ui-ng/src/lib/menu/menu.component.ts b/packages/ui-ng/src/lib/menu/menu.component.ts
index 7e004e12..c54c4bd2 100644
--- a/packages/ui-ng/src/lib/menu/menu.component.ts
+++ b/packages/ui-ng/src/lib/menu/menu.component.ts
@@ -18,6 +18,8 @@ import {
 import { FocusKeyManager, type FocusableOption } from '@angular/cdk/a11y';
 import { type ConnectedPosition, OverlayModule } from '@angular/cdk/overlay';
 
+const FOCUSABLE = 'button, a[href], input, select, textarea, [tabindex]';
+
 export type MenuAlign = 'start' | 'end';
 export type MenuDirection = 'down' | 'up';
 
@@ -157,7 +159,11 @@ export class MenuComponent {
     this.open.set(false);
     const active = document.activeElement;
     if (!active || active === document.body) {
-      this.host.nativeElement.querySelector<HTMLElement>('[flr-menu-trigger]')?.focus();
+      const trigger = this.host.nativeElement.querySelector<HTMLElement>('[flr-menu-trigger]');
+      const target = trigger?.matches(FOCUSABLE)
+        ? trigger
+        : trigger?.querySelector<HTMLElement>(FOCUSABLE);
+      target?.focus();
     }
   }