Skip to content

feat: Complete FAB Menu behavior and web adaptation - #5170

Open
alpharius-ck wants to merge 12 commits into
mainfrom
refactor-fab
Open

alpharius-ck wants to merge 12 commits into
mainfrom
refactor-fab

Conversation

@alpharius-ck

@alpharius-ck alpharius-ck commented Nov 5, 2026 •

Copy link
Copy Markdown
Collaborator

Motivation

FAB.Menu did not follow the Material 3 spec or the other v6 components in a few ways. On web it did not tell assistive technology whether it was open. Collapsed items stayed in the tab order and the accessibility tree. Items had no hover, focus or press feedback, and a menu taller than the screen could not scroll.

This PR fixes those. Dismissal (Escape, Android back, outside press, screen reader escape) and focus handling (focus on open, restore on close) are intentionally left out and belong to the overlay work in #5127. A follow-up will wire FAB.Menu into that portal stack. Until then, the menu closes only through its trigger and items, as on main.

Builds on #5110 (variant rename). It also covers the aria-expanded change from #5151, so one of the two should be dropped when they land.

Related issue

https://app.notion.com/p/callstack/Complete-FAB-Menu-behavior-and-web-adaptation-3ac5d027c0f8806ba4f8f5a8cc061eac?v=3285d027c0f880a68ccb000c1ce3c56e&source=copy_link

Screenshots / Videos

fab-ios fab-general fab-android fab-web

Test plan

Use the example app: FAB → menu (yarn example web, yarn example ios, yarn example android).

Web

  1. In dev tools, the closed trigger has aria-expanded="false" and aria-haspopup="menu". After opening, it has aria-expanded="true", and the items container has role="menu".
  2. With the menu closed, Tab does not stop on any item. With it open, Tab reaches the items.
  3. With focus on an item, ArrowUp/ArrowDown, Home and End move focus through the items and then the close button, and wrap around. Arrow keys do nothing when focus is outside the menu.
  4. Hover, keyboard-focus and press an item. The state layer and elevation change. The focus ring appears for keyboard focus only, not mouse clicks. The state resets after the menu closes.
  5. Shrink the window height so the items don't fit. They scroll, the close button stays reachable, and the scroll position returns to the top each time the menu opens.

iOS / Android

  1. On a short screen or in landscape (Android: adb shell wm size 1080x1000), the items scroll to the last one. Reopening starts at the top.
  2. With VoiceOver or TalkBack on, collapsed items are not announced. Expanded items are announced, and the trigger is announced as expanded or collapsed.
  3. Press and hold an item (touch), or hover it on iPad with a pointer. The state layer shows and clears.

@github-actions

github-actions Bot commented Nov 5, 2026

Copy link
Copy Markdown

Found potential problems with the pull request:

  • The description is too long. Please keep it under 1000 characters.

alpharius-ck and others added 4 commits November 5, 2026 17:01
# Conflicts:
#	src/components/FAB/Shell.tsx
The previous merge of main kept the old versions of most files that
changed on main. Bring the tree to main plus the FAB menu changes so the
PR only shows the FAB files.

Type the FAB refs with ComponentRef<typeof View> and
ComponentRef<typeof ScrollView>, as main does, since View and ScrollView
are no longer instance types on React Native 0.88.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@Doberjohn

Copy link
Copy Markdown
Collaborator

Thanks for the videos @likevy, they look good. After I updated the branch, Typecheck and Build package fail: React Native 0.88 (from #5167) now types onKeyDown and onKeyUp on View and Pressable with its own key event, so the React DOM KeyboardEvent in useSpaceKeyPress no longer fits. Replacing it with only what the handlers read fixes it and passes the legacy types check too:

type KeyboardEvent = {
  nativeEvent: { key: string; repeat?: boolean | undefined };
  preventDefault: () => void;
};

Could you push that? Then I'll do the last checks and merge.

@alpharius-ck

Copy link
Copy Markdown
Collaborator Author

Thanks for the videos @likevy, they look good. After I updated the branch, Typecheck and Build package fail: React Native 0.88 (from #5167) now types onKeyDown and onKeyUp on View and Pressable with its own key event, so the React DOM KeyboardEvent in useSpaceKeyPress no longer fits. Replacing it with only what the handlers read fixes it and passes the legacy types check too:

type KeyboardEvent = {
  nativeEvent: { key: string; repeat?: boolean | undefined };
  preventDefault: () => void;
};

Could you push that? Then I'll do the last checks and merge.

sure - would do asap

@alpharius-ck

Copy link
Copy Markdown
Collaborator Author

@Doberjohn branch is working correctly with RN 0.88

alpharius-ck and others added 3 commits November 16, 2026 09:37
Resolve FAB.Menu against the shared `useFocusRing` from main, and make the
menu a proper overlay: Escape, Android back and the iOS escape gesture
dismiss it, focus moves to the first item on open and returns to the
trigger on close.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

@jacekAtCK jacekAtCK left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requesting changes for the rebase on main and the keyboard issues on web. Details are inline.

Comment thread src/components/FAB/Menu.tsx Outdated
// first mount doesn't animate unexpectedly.
const scaleX = useSharedValue(expanded ? 1 : 0);
const alpha = useSharedValue(expanded ? 1 : 0);
const { scale } = theme.animation;

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#5235 removed theme.animation.scale from main, so after the rebase this line and lines 308 and 510 should fail typecheck. Could you replace the * scale parts with useReduceMotion(), as other components on main do?

Comment thread src/components/FAB/Shell.tsx Outdated
>
{overlay}
<TouchableRipple
ref={buttonRef}

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Main now passes a web-only touchableRef to this same TouchableRipple to blur and restore focus when the FAB hides, so it conflicts with buttonRef here. Could you merge both refs into one during the rebase?

onHoverOut={() => setHovered(false)}
onPressIn={() => setPressed(true)}
onPressOut={() => setPressed(false)}
role={Platform.OS === 'web' ? 'menuitem' : 'button'}

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Space does nothing on a focused item on web (Enter works), because RNW presses on Space only for role="button". Could you add useSpaceKeyPress to the item, as Checkbox does?

// `aria-hidden` and `pointerEvents` don't take collapsed items
// out of the tab order.
focusable={expanded}
tabIndex={expanded ? 0 : -1}

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On web every item is a Tab stop, Tab leaves the menu while it stays open, and ArrowUp from the first item or End jumps to the close button, which is outside role="menu". Could we use a roving tabindex with aria-labelledby on the menu, or drop the menu and menuitem roles and use buttons in a labelled group?

@@ -552,12 +672,145 @@ const Menu = ({

const effectiveExpanded = triggerVisible && expanded;

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the FAB hides while the menu is open, onDismiss is not called, so parent keeps expanded=true. When I turned "Show FAB" off and on, the menu opened again by itself and focus jumped to "Send", so could we call onDismiss when the trigger hides?

expanded: boolean;
/**
* Called when the user taps the close button or taps an item.
* Called when the menu should close: the user taps the close button, an

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nothing closes the menu on an outside press (I clicked outside on web and it stayed open), and main's migration guide says on purpose that it does not. Could we drop "or outside the menu" here and "Pressing outside the menu" on line 626?


// The screen reader is sent to an element, which the test can only tell
// apart by the `testID` it was given.
const focusedTestID = () => {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we drop the eslint-disable and the cast here? toHaveBeenCalledWith(expect.objectContaining({ props: expect.objectContaining({ testID: 'item-0' }) }), 'focus') should check the same thing.

pressed: stateOpacity.pressed,
} as const satisfies Record<Interaction, number>;

export const webNoHoverTint: ViewStyle = { backgroundColor: 'transparent' };

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: is webNoHoverTint a token or more like a style? Maybe it should be in Menu itself?

@Doberjohn Doberjohn added this to the 6.0.0 milestone Nov 19, 2026
Resolve the FAB conflicts with main: the trigger ref now feeds both the
caller's `buttonRef` and the web focus handling, and the menu items drop
`theme.animation.scale`, which main removed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@apex-sentinel-staging

apex-sentinel-staging Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Apex Sentinel · ✅ Approve · review of c80b74e

2 finding(s): 2 minor.

🟡 Minor (2)

Where Finding
src/components/FAB/Menu.tsx:628 FAB.Menu docs promise outside-press dismissal that no code implements
src/components/FAB/Menu.tsx:806 New arrow-key/Home/End navigation ships with no test exercising it
Not in the reviewers' prompt (5 files)
  • docs/public/screenshots/fab-android.png: no text diff (a binary, empty or mode-only change)
  • docs/public/screenshots/fab-general.png: no text diff (a binary, empty or mode-only change)
  • docs/public/screenshots/fab-ios.png: no text diff (a binary, empty or mode-only change)
  • docs/public/screenshots/fab-web.png: no text diff (a binary, empty or mode-only change)
  • src/components/__tests__/__snapshots__/FABMenu.test.tsx.snap: generated or a lockfile, so its lines were left out

3 findings below minor hidden (user_settings.min_severity).

Reviewed with this repository's own Sentinel configuration (3d9dee332cd6).

💬 Talking to Sentinel

In a finding's thread, reply with:

Command What it does
@apex-sentinel-staging note <context> Adds context; Sentinel re-checks the cited code
@apex-sentinel-staging pivot <why> Says the finding is wrong; Sentinel re-checks the cited code
@apex-sentinel-staging like Marks the finding as useful
@apex-sentinel-staging dislike <why> Marks it as not useful, so it is not raised again

On this conversation, comment @apex-sentinel-staging review to run a full review once again.

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 2 new findings on c80b74e. The verdict and the full list are in the summary comment.

Comment on lines +628 to +633
* There is no visual scrim. Pressing outside the menu, the close button or an
* item, pressing Escape (web), the hardware back button (Android) or the
* screen reader escape gesture (iOS) calls `onDismiss`. Focus moves to the
* first item when the menu opens and returns to the trigger when it closes.
* On web, the arrow keys, Home and End move focus between the items and the
* close button.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 Major · FAB.Menu docs promise outside-press dismissal that no code implements

A reader of the FAB.Menu docs page presses outside the menu and onDismiss never fires: the container uses pointerEvents: 'box-none' with no press handler, and the PR defers outside-press dismissal to #​5127. Both the component JSDoc and MenuProps.onDismiss JSDoc nevertheless document that outside-press calls onDismiss, making the shipped public API contract wrong.

Suggested change
* There is no visual scrim. Pressing outside the menu, the close button or an
* item, pressing Escape (web), the hardware back button (Android) or the
* screen reader escape gesture (iOS) calls `onDismiss`. Focus moves to the
* first item when the menu opens and returns to the trigger when it closes.
* On web, the arrow keys, Home and End move focus between the items and the
* close button.
* There is no visual scrim, and presses outside the menu pass through to the
* content below — the menu closes through its trigger or an item. Pressing
* Escape (web), the hardware back button (Android) or the screen reader escape
* gesture (iOS) calls `onDismiss`. Focus moves to the first item when the menu
* opens and returns to the trigger when it closes. On web, the arrow keys,
* Home and End move focus between the items and the close button.

Suggested change

Drop the outside-press sentence from both the component JSDoc and the onDismiss prop doc (or land an outside-press handler) before publishing the FAB.Menu docs page.

Details

Also raised here

Also raised at this location by persona maintainability: onDismiss docs promise outside-tap dismiss that the menu does not implement — With the menu open, tapping outside it (the content under the items) does not call onDismiss — only the close button, an item, Android back, Escape and the iOS escape gesture do. The new onDismiss JSDoc and the Menu block doc both list "taps outside the menu" as a dismiss trigger, while the only dismissal wiring in this diff is useOverlayDismiss (whose own comment says "Back (Android) and Escape (web)"), onAccessibilityEscape, the trigger and the items; the items container even lets taps fall through to the content below, and the PR description defers outside press to #​5127. The published API doc is therefore wrong for the version that ships.

persona: maintainability, javascript

Useful? Reply @apex-sentinel-staging like, or @apex-sentinel-staging dislike <why> if it is not.

Reply @apex-sentinel-staging note ... to add context, or @apex-sentinel-staging pivot ... if it is wrong — I will re-check the cited code.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/note True: nothing closes the menu on an outside press, and the migration guide says so, so the two JSDoc sentences should drop it. It is a docs fix with no runtime impact, though, so minor rather than major.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated suggestion

Confirmed: nothing in the diff handles an outside press — dismissal is wired only to the close button, the items, useOverlayDismiss (Android back / web Escape) and onAccessibilityEscape, and the container is pointerEvents: 'box-none' so taps fall through to the content below. Since the 6.x migration guide already states plainly that FAB.Menu "has no backdrop and doesn't close on a tap outside it", the published guidance isn't misleading app developers — only these two JSDoc sentences contradict the shipped behavior, which supports your downgrade to minor. Agree it's a docs-only fix: drop the outside-press clause from the Menu block doc (line 628) and from MenuProps.onDismiss (line 101), or restore it when #​5127 lands.

🟡 Minor · FAB.Menu JSDoc lists outside-press as an onDismiss trigger that no code implements

With FAB.Menu expanded, a tap outside the items never calls onDismiss — the container uses pointerEvents: 'box-none' with no press handler, so the tap lands on the content below, and dismissal is wired only to the close button, an item, useOverlayDismiss (Android back / web Escape) and onAccessibilityEscape. Both the Menu block JSDoc ("Pressing outside the menu, the close button or an item ... calls onDismiss") and the MenuProps.onDismiss JSDoc ("taps the close button, an item, or outside the menu") nevertheless document outside-press as a dismiss trigger, so the generated API doc for this component is wrong for the version that ships (outside press is deferred to #​5127). The 6.x migration guide already says the opposite correctly ("has no backdrop and doesn't close on a tap outside it"), so this is a docs-only inconsistency with no runtime impact rather than a behavioral bug. Drop the outside-press clause from both JSDoc blocks, or land an outside-press handler before publishing the FAB.Menu docs page.

Suggested change
* There is no visual scrim. Pressing outside the menu, the close button or an
* item, pressing Escape (web), the hardware back button (Android) or the
* screen reader escape gesture (iOS) calls `onDismiss`. Focus moves to the
* first item when the menu opens and returns to the trigger when it closes.
* On web, the arrow keys, Home and End move focus between the items and the
* close button.
* There is no visual scrim, and presses outside the menu pass through to the
* content below — the menu closes through its trigger or an item. Pressing
* Escape (web), the hardware back button (Android) or the screen reader escape
* gesture (iOS) calls `onDismiss`. Focus moves to the first item when the menu
* opens and returns to the trigger when it closes. On web, the arrow keys,
* Home and End move focus between the items and the close button.

Suggested change

Also drop the outside-press clause from the MenuProps.onDismiss JSDoc (src/components/FAB/Menu.tsx:100-104), e.g. "Called when the menu should close: the user taps the close button or an item, presses Escape (web), the hardware back button (Android) or performs the screen reader escape gesture (iOS)."

Useful? Reply @apex-sentinel-staging like, or @apex-sentinel-staging dislike <why> if it is not.

Comment on lines +806 to +811

stops[next].focus();
};

document.addEventListener('keydown', onKeyDown);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Minor · New arrow-key/Home/End navigation ships with no test exercising it

The keydown handler for ArrowUp/ArrowDown/Home/End is never invoked in tests: the fake document.addEventListener only records listeners when capture === true, but this registration passes no capture argument, so keyDownListeners never holds it. The entire keyboard-navigation path—wrapping, Home/End, the defaultPrevented bail-out, the trigger as the last stop—can regress silently.

Suggested change

Record non-capture keydown listeners in the test's document mock and add cases for ArrowDown/ArrowUp wrapping, Home/End and the trigger as the final stop.

Details

persona: maintainability

Useful? Reply @apex-sentinel-staging like, or @apex-sentinel-staging dislike <why> if it is not.

Reply @apex-sentinel-staging note ... to add context, or @apex-sentinel-staging pivot ... if it is wrong — I will re-check the cited code.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/like

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the feedback. It helps us make these findings more useful.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants