feat: MUI 4 to BUI migration - replace Menu and Popover patterns with BUI Menu

[schultzp2020]

Summary

Add a codemod that migrates the common MUI menu/popover trigger pattern to the BUI MenuTrigger / Menu / MenuItem structure.

This codemod should focus on local trigger + menu + action-item trees. More specialized data-hosted or extension-driven menu systems can stay out of scope for the initial implementation.

Detection Criteria

• Menu, MenuItem, Popover, or MenuList imports from @material-ui/core
• local trigger elements such as IconButton or Button that open the menu or popover
• MenuItem children with local onClick handlers and plain text labels

Transformation Logic

1. Replace the MUI menu/popover imports with MenuTrigger, Menu, and MenuItem from @backstage/ui.
2. Collapse the local trigger + popover/menu structure into a MenuTrigger wrapper when the relationship is fully local and static.
3. Map MenuItem onClick to onAction when the callback is a local handler.
4. Preserve the trigger element and allow other codemods to migrate IconButton or Button itself.
5. Insert TODO(backstage-codemod): finish menu host migration manually when the menu depends on anchor elements, portal positioning, extension data, or nonlocal close behavior.

Before / After Example

Local action menu:

// Before
<IconButton onClick={handleOpen}>
  <MoreVertIcon />
</IconButton>
<Popover open={open} anchorEl={anchorEl} onClose={handleClose}>
  <MenuList>
    <MenuItem onClick={handleAction}>Action</MenuItem>
  </MenuList>
</Popover>

// After
<MenuTrigger>
  <IconButton>
    <MoreVertIcon />
  </IconButton>
  <Menu>
    <MenuItem onAction={handleAction}>Action</MenuItem>
  </Menu>
</MenuTrigger>

Notes / Edge Cases

• This codemod should not absorb the broader new-frontend-system context-menu data model changes from catalog; those are a different migration boundary.
• Anchor-positioning props and custom popover offsets are likely to need manual review after the structural rewrite.
• If the trigger element is itself an IconButton, let the icon-button codemod run either before or after without conflict.
• The migration skill and the catalog context-menu PR provide representative destination shapes.

Changeset (when implementing)

• Package: @backstage/migrate-mui-menu-popover-to-bui-menu
• Bump: minor (initial release)
• Summary example: Add codemod to migrate mui menu popover to bui menu for the Backstage MUI 4 to BUI migration

Implementation notes

• Target directory: codemods/misc/migrate-mui-menu-popover-to-bui-menu/
• Branch/worktree: .worktrees/feat/mui4-to-bui/migrate-mui-menu-popover-to-bui-menu
• Open PR when ready; one PR per codemod