fix(bulma-ui): add keyboard and focus support to Dropdown and Navbar.Dropdown

[bestaxbot]

Summary

Dropdown declared the ARIA menu roles (role=\"menu\"/role=\"menuitem\",
aria-haspopup/aria-expanded) but implemented none of their keyboard/focus
contract, and Navbar.Link had no aria-expanded/aria-haspopup and no way
to open its Navbar.Dropdown from the keyboard, so hoverable dropdowns were
unreachable for keyboard and touch users.

• Dropdown implements the WAI-ARIA Menu Button pattern on top of its
  existing state: ArrowDown/Enter/Space on the trigger open the menu and
  focus the first item, ArrowUp opens and focuses the last item. Inside the
  menu, ArrowDown/ArrowUp move between items and wrap around (skipping
  disabled items and dividers), Home/End jump to the first/last item,
  Escape closes the menu and restores focus to the trigger, and Tab closes
  the menu while letting focus continue naturally. onActiveChange fires on
  every transition, same as the existing click/outside-click handling.
• Navbar.Dropdown now tracks its own open state (controlled via active
  or uncontrolled, mirroring Dropdown) and gained a matching
  onActiveChange prop. It shares its state with a nested Navbar.Link
  via context, so the link automatically renders aria-haspopup="true" and
  aria-expanded synced to the dropdown, and Enter/Space toggle it while
  Escape closes it and keeps focus on the link — no hand-wiring required.
  role="button"/tabIndex={0} are added only when the link has no href
  and isn't rendered as="button" (i.e. isn't already natively interactive).
  hoverable keeps working with a mouse; the keyboard path opens/closes the
  dropdown independently of hover.
• Updated Dropdown.stories.tsx/Navbar.stories.tsx (including switching the
  navbar dropdown story triggers to Navbar.Link, matching Bulma's own
  .navbar-link structure and the docs) and the dropdown.md/navbar.md
  Accessibility sections to describe the shipped keyboard model instead of
  deferring it to the app.
• Regenerated the MCP data index and skills catalog (pnpm gen) for the new
  Navbar.Dropdown.onActiveChange prop.

Non-goals (per the issue): no typeahead, no change to hoverable semantics,
no arrow-key roving between navbar items, and no outside-click handling for
Navbar.Dropdown.

Fixes #618

Test plan

• pnpm --filter @allxsmith/bestax-bulma run typecheck
• pnpm --filter @allxsmith/bestax-bulma run lint
• pnpm --filter @allxsmith/bestax-bulma run test:coverage — 100% coverage
  on both changed files; full suite (3990 tests) green
• pnpm run format:check
• pnpm run gen:catalog:check
• pnpm run check:conformance
• pnpm --filter @allxsmith/bestax-bulma run build
• pnpm --filter @allxsmith/bestax-bulma run build-storybook
• New Jest tests cover: open-by-key (ArrowDown/ArrowUp/Enter/Space), arrow
  wrap, Home/End, Escape + focus restore, Tab close, disabled-item
  skipping, controlled mode (Dropdown); ARIA attribute derivation,
  Enter/Space toggle, Escape close + focus retention, and the
  as="button"/href branches (Navbar)

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

Next included review available in 36 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: ae3c5992-c939-499c-b912-36eb24be6801

📥 Commits

Reviewing files that changed from the base of the PR and between 108865c and a574203.

📒 Files selected for processing (11)

• bestax-mcp/data/catalog.json
• bestax-mcp/data/components/Dropdown.json
• bestax-mcp/data/components/Navbar.json
• bulma-ui/src/components/Dropdown.stories.tsx
• bulma-ui/src/components/Dropdown.tsx
• bulma-ui/src/components/Navbar.stories.tsx
• bulma-ui/src/components/Navbar.tsx
• bulma-ui/src/components/__tests__/Dropdown.test.tsx
• bulma-ui/src/components/__tests__/Navbar.test.tsx
• docs/docs/api/components/dropdown.md
• docs/docs/api/components/navbar.md

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/issue-618-20260902-0245

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Preview Deployment

Preview URL: https://b8e27c29.bestax.pages.dev

[claude]

Deep review — 0 blocking · 3 advisory

#	Severity	Area	Finding	Location
1	🔵 Advisory	Accessibility	role="menuitem" items are still not keyboard-activatable — Enter/Space on a focused item (default <a> with no href) does nothing; item activation was scoped out but remains part of the menu contract	bulma-ui/src/components/Dropdown.tsx:206
2	🔵 Advisory	API	A non-hoverable Navbar.Dropdown has no mouse-click open path — Navbar.Link has no onClick toggle, so it only opens via keyboard, hover, or a controlled active prop	bulma-ui/src/components/Navbar.tsx:464
3	🔵 Advisory	Accessibility	Navbar.Link with an href inside a dropdown: Enter/Space now preventDefault()s and toggles the dropdown instead of navigating, while the element is still semantically a link	bulma-ui/src/components/Navbar.tsx:452

Overall: The change is sound and faithfully implements the issue's scoped plan (WAI-ARIA Menu Button navigation for Dropdown, context-driven ARIA + keyboard for Navbar.Link). All 134 tests in the two suites pass, coverage claims hold, and the docs/MCP/catalog gen artifacts are consistent with the new Navbar.Dropdown.onActiveChange prop. The riskiest area is browser-only focus/activation behavior that jsdom can't exercise, but the trigger uses the canonical keydown-preventDefault approach from the APG reference (which pairs the same keydown handler with a click handler), so the Space/Enter double-activation trap does not apply here. The human should focus on whether the three advisory gaps are acceptable scope for this issue — the maintainer explicitly listed most of them as non-goals.

Residual risk:

• Double-activation on trigger (refuted): For the Dropdown <button>, Enter/Space call preventDefault() on keydown, which suppresses the synthetic click in browsers — the same pattern the APG menu-button example relies on while also wiring an onClick toggle. For Navbar.Link there is no onClick at all, so even an unsuppressed keyup-click has no handler to fire. No double-toggle.
• Empty / disabled-only menus (refuted): getMenuItems() filters disabled/aria-disabled and returns []; every handler guards if (!items.length) return or checks items.length, and tests cover empty-menu open on both Arrow keys with no throw.
• Controlled-mode focus race (refuted): The activeProp to state sync effect is declared before the focus effect, so on a controlled open the menu is is-active before the pending item is focused; the controlled keyboard-open test confirms focus lands on the first item.
• Item keyboard activation (open, advisory #1): navigating to a menuitem works, but activating it from the keyboard depends on the consumer rendering it as a link-with-href or as="button"; a bare <Dropdown.Item onClick> remains unreachable by keyboard.

🏄 Clean set, dude — the keyboard waves roll in smooth from trigger to menu and back, tests all caught the barrel, and the gen artifacts stayed in the lineup. Couple of little ripples on item activation and mouse-open, but nothing that'll wipe the merge. Send it. 🌊

[bestaxbot]

🏂 First chair, fresh corduroy, straight-lined the whole thing — converged. 0 iteration(s), CI green as a freshly groomed run at 8am, and every AI review thread buried and packed down.

The merge button lives in the wetware, brah — @allxsmith, flex those digits and squash-merge when the vibes align. Loop never merges; apparently 'ship it' needs a pulse. 🤙

[github-actions]

📸 Story screenshots at handoff — 8cfb8c6

11 stories (light + dark) from this PR's changed files under bulma-ui/src/ (workflow run · artifact story-screenshots-pr-628, 30-day retention).

components-dropdown--default · Components/Dropdown · Default

Light	Dark

components-dropdown--custom-tags · Components/Dropdown · Custom Tags

Light	Dark

components-dropdown--hoverable-and-active · Components/Dropdown · Hoverable And Active

Light	Dark

components-dropdown--right · Components/Dropdown · Right

Light	Dark

components-dropdown--keyboard-accessible · Components/Dropdown · Keyboard Accessible

Light	Dark

components-navbar--default · Components/Navbar · Default

Light	Dark

components-navbar--brand-only · Components/Navbar · Brand Only

Light	Dark

components-navbar--burger-only · Components/Navbar · Burger Only

Light	Dark

components-navbar--burger-active · Components/Navbar · Burger Active

Light	Dark

components-navbar--menu-start-end · Components/Navbar · Menu Start End

Light	Dark

components-navbar--items-nav-links-and-dropdown · Components/Navbar · Items Nav Links And Dropdown

Light	Dark

> ⚠ Failed to render: `components-dropdown--up` — see the [run log](https://github.com/allxsmith/bestax/actions/runs/33585971661). > ✂ 21 more matched stories skipped by the cap: `components-dropdown--compound-usage`, `components-navbar--transparent`, `components-navbar--fixed-top`, `components-navbar--dropdown`, `components-navbar--dropdown-right`, `components-navbar--dropup`, `components-navbar--dropdown-no-arrow`, `components-navbar--active-dropdown-item`, `components-navbar--dropdown-with-divider`, `components-navbar--keyboard-accessible-dropdown`, … — full set in the artifact.

[Copilot]

🟡 Changes recommended

Controlled state, pointer activation, and empty-menu close handling contain unresolved accessibility defects.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds keyboard and focus accessibility to Dropdown and Navbar dropdown triggers.

Changes:

• Implements keyboard navigation, focus restoration, and ARIA state.
• Adds Navbar dropdown state callbacks and context.
• Updates tests, stories, documentation, and generated indexes.

File summaries

File	Description
bulma-ui/src/components/Dropdown.tsx	Adds menu keyboard and focus handling.
bulma-ui/src/components/Navbar.tsx	Adds dropdown state and trigger behavior.
bulma-ui/src/components/__tests__/Dropdown.test.tsx	Tests keyboard navigation.
bulma-ui/src/components/__tests__/Navbar.test.tsx	Tests Navbar dropdown accessibility.
bulma-ui/src/components/Dropdown.stories.tsx	Adds keyboard-accessible example.
bulma-ui/src/components/Navbar.stories.tsx	Updates and adds dropdown examples.
docs/docs/api/components/dropdown.md	Documents Dropdown keyboard behavior.
docs/docs/api/components/navbar.md	Documents Navbar dropdown accessibility.
bestax-mcp/data/components/Dropdown.json	Regenerates Dropdown metadata.
bestax-mcp/data/components/Navbar.json	Regenerates Navbar metadata.
bestax-mcp/data/catalog.json	Updates Navbar prop count.

Review details

• Files reviewed: 11/11 changed files
• Comments generated: 3
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[allxsmith]

@bestaxbot please handle the open Copilot review threads on this PR: verify each finding against the current head, fix the ones that hold and add a test for each, reply with the reason on any you decline, and resolve every thread. Keep the change within this PR's scope.

[bestaxbot]

Worked through the three open Copilot threads — two fixed with tests, one declined with reasoning:

Fixed

• Empty/all-disabled menu couldn't be closed (Dropdown.tsx): handleMenuKeyDown returned early on an empty item list before reaching Escape/Tab. Moved those two ahead of the item-list guard so the menu always honors the close contract; only Arrow/Home/End still need a nonempty list. Tests: Escape on an item-less menu, Tab on an all-disabled menu.
• No pointer open path for a non-hoverable navbar dropdown (Navbar.tsx): a Navbar.Link with no href / not as="button" renders role="button" but had only keydown handling. Added a composed onClick on that branch — runs the caller's handler, then toggles unless preventDefault()d. Native links/buttons keep their own semantics. Tests: click toggle, onClick composition, preventDefault opt-out, href no-hijack. Docs + MCP index updated.

Partially actioned / declined

• Controlled-state note (Navbar.tsx): I did the Strict Mode half — onActiveChange is now out of the setActive updater in toggle/close, matching Dropdown, so double-invoked updaters can't double-fire it. I declined the strict-controlled redesign: Navbar.Dropdown deliberately mirrors Dropdown's documented controlled/uncontrolled hybrid, so converging both on a strict model is a library-wide decision better handled as a follow-up. Full reasoning is in the thread.

Coverage stays 100% on both changed files; typecheck/lint/format/gen all clean. Commits: 95b0a98, 77be7e3.

I've replied on each thread but left them unresolved — per the loop rules I don't resolve review threads, so please close them out when the responses look right.

[github-actions]

Preview Deployment

Preview URL: https://524942de.bestax.pages.dev

[github-actions]

Preview Deployment

Preview URL: https://63bad758.bestax.pages.dev

[Copilot]

🟡 Changes recommended

The documented disabled-item API is not type-safe, and Tab focus continuation lacks behavioral verification.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 11/11 changed files
• Comments generated: 2
• Review effort level: Balanced

[allxsmith]

@bestaxbot please handle the open review threads on this PR: verify each finding against the current head, fix the ones that hold with a test each, reply with the reason on any you decline, resolve every thread, and if the branch conflicts with main, merge main in first. Keep the change within this PR's scope.

[bestaxbot]

Worked the two new Copilot threads from the latest review, plus re-verified the still-open controlled-state one. Merge check first: GitHub reports the branch MERGEABLE against main (the BLOCKED status is just branch protection, not a conflict), so no main merge was needed.

Fixed (a574203)

• Dropdown.Item disabled wasn't type-safe (dropdown.md/Dropdown.tsx): the docs and tests use <Dropdown.Item as="button" disabled>, but DropdownItemProps extends React.HTMLAttributes<HTMLElement>, which doesn't declare disabled — it reached the DOM only via untyped passthrough and would fail a consumer's typecheck. Added a typed disabled?: boolean with TSDoc and regenerated the props table + MCP index. No runtime change (the attribute already flowed through ...rest, which is why the hasAttribute('disabled') filter worked). Test asserts the typed prop forwards to the element.
• Tab focus-continuation had no behavioral guard (Dropdown.test.tsx): jsdom doesn't move focus on Tab, but the real contract is that the handler must not block native movement — Tab closes the menu without preventDefault(), unlike Escape. Added a test that dispatches a real Tab event and asserts both the close and defaultPrevented === false, so adding preventDefault() to that branch would fail even with 100% line coverage.

Declined (re-verified, unchanged)

• Controlled-state redesign (Navbar.tsx): Navbar.Dropdown deliberately mirrors Dropdown's documented controlled/uncontrolled hybrid; the Strict Mode half is already fixed (77be7e3). Converging both components on a strict controlled model is a library-wide call, best as a follow-up. Full reasoning in the thread.

The empty-menu Escape/Tab and navbar click-open threads were already fixed with tests last round (95b0a98).

Gates: Dropdown.tsx 100% coverage, suite 99.62%/99.14% (>= 99%), 3998 tests green; typecheck, lint (0 errors), format:check, and check:conformance all clean; generators idempotent.

I've replied on each thread but left them unresolved — per the loop rules I don't resolve review threads, so please close them out when the responses look right.

[github-actions]

Preview Deployment

Preview URL: https://667de5d1.bestax.pages.dev

[bestaxbot]

Thanks for the approval! Nothing to change here — all the review threads from this round (the empty/all-disabled menu close, touch/click open path, controlled-state Strict Mode fix, the typed Dropdown.Item disabled prop, and the Tab focus-continuation test) are resolved, and CI is green across Build and Test plus both the React 18 and React 19 matrices.

[bestax-release-bot]

🎉 This PR is included in version 5.13.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[bestax-release-bot]

🎉 This PR is included in version 4.2.5 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[bestax-release-bot]

🎉 This PR is included in version 2.2.2 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[bestax-release-bot]

🎉 This PR is included in version 1.2.3 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀