feat(dropdown-menu,select): persistent items, a search query hook, and one search implementation

[tmccoy14]

What

Follow-up to #163, from a review of Guardian Studio's adoption of 4.3.x. It adds what Studio was hand-rolling around in-menu search, and closes the gaps left between DropdownMenu and Select search.

Added

• A persistent prop on DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioItem, DropdownMenuSeparator, SelectItem and SelectSeparator. A persistent item stays visible while searching but is never a result. It doesn't count towards the empty state or the result count, and Enter in the search box skips it.
• useDropdownMenuSearchQuery(), which returns { query, isSearching, matches } to components inside a DropdownMenu. Studio's project picker uses it so "Select all" selects only the projects a search shows.
• useSelectSearchQuery(), the same hook for components inside a Select.

Changed

• DropdownMenuSearch shows on open by default, as SelectSearch does. alwaysVisible={false} keeps reveal-on-typing.
• A searchable FilterDropdown keeps "Clear all" visible during a search, as a persistent item. Previously the footer's padding stayed behind as an empty strip.

Fixed

• Side flip during search. A searchable DropdownMenu, and so FilterDropdown and RadioDropdown, flipped sides mid-search, the same bug fix(select,filter-dropdown): keep Clear all's menu open and a searching Select's side #163 fixed for Select. In Studio at 1280×560, the Activity Logs project filter opened above its trigger, dropped below on a query with no matches, and went back on clear.
• Backspace. With a DropdownMenu item focused, Backspace now edits the query, as in Select.
• Dialog focus. Opening inside a Dialog now reliably focuses the search. The 4.3.1 fix only reacted to the menu's first focus event, and the input could claim that before the dialog's focus trap pulled focus back out. In Studio's Manage Roles dialog it failed 2–4 of every 20 opens. It now pulls focus back whenever the menu itself is focused before any interaction, as SelectContent does.

Structure

• The side lock (useSearchSideLock), the interacted-since-open flag, the query hook (useSearchQuery) and the key handling on list items (handleListKeyDown) now live in list-search.ts, so Select and DropdownMenu share one implementation of each. resetForOpen clears the lock and the flag. DropdownMenuContent and SelectContent now have the same shape.
• useFilterableItem and useSearchSideLock take options objects rather than trailing positional arguments.
• Resetting the flag after a controlled open happens in an effect rather than during render, to satisfy react-hooks/refs.
• data-persistent is set after {...props} on every item, so consumer props can't override it.
• Each hook is exported from its component's file in its own export { … } under an eslint-disable-next-line react-refresh/only-export-components, as form.tsx exports useFormField, so the barrel stays export *.
• The redundant alwaysVisible props are gone from FilterDropdown and RadioDropdown. The docs VersionSwitcher keeps it: @eqtylab/docs declares a ^4.1.0 peer range, and before 4.4.0 the default is reveal-on-typing.

Docs

• The DropdownMenu and Select pages have Persistent items sections, each with a live demo and a snippet that matches it, and the props tables are updated in Slots order. The hooks are documented in prose, as useFormField is, including that they throw outside their root.
• The DropdownMenu demo variants are renamed to match Select (with-search is the default, with-search-reveal reveals on typing).
• The empty state now sits directly after the search box in every example, the docs VersionSwitcher and the test fixtures.
• Removed a stale claim on the Select page that only Select shows its search by default. Fixed the FilterDropdown page, which still said "Clear all" closes the menu.
• Added a row to the skill's name translation table for a footer action, "Select all" or "Other" that should stay visible while searching.

Tests

63 passing (was 40). New coverage:

• persistent items and separators, for both components, including the result count and Enter;
• useDropdownMenuSearchQuery and useSelectSearchQuery, including throwing outside their root;
• DropdownMenu reveal-on-keystroke with alwaysVisible={false};
• Backspace from a focused item, for both components;
• ↑ from the first DropdownMenu item back to the search box;
• the side lock, including release on resetForOpen, via renderHook, since jsdom has no layout;
• interaction tracking, including its reset when a controlled open becomes true;
• focus recovery when the menu itself is focused before any interaction. This test fails against the 4.3.1 first-focus logic.

Verification

• pnpm format:check, pnpm lint, pnpm test, tsc --noEmit, and the ui and demo builds.
• In Studio with this build (eqtylab/guardian#275): 46 affected e2e specs passed, and a full suite run passed 227 of 228. The one failure was a histogram test unrelated to dropdowns, which passed on its own. Menus inside dialogs focused their search in 30 of 30 opens.

4.4.0, with a CHANGELOG entry.

🤖 Generated with Claude Code