---

name: lov-frontend-select-with-search description: > 把超过 5 个候选项的 Select 升级为可搜索、可滚动且键盘可访问的兼容组件，并验证 Dialog/Portal 中的真实滚轮事件；当用户说“下拉选项太多要搜索”“候选项无法滚动”或 “make selects searchable” 时使用。 license: MIT metadata: author: contributors version: "0.1.1" card_standard: lovstudio/skill-card/v1 tags: - frontend - select - combobox - accessibility - scroll-lock compatibility: "Instruction-only Skill for HTML, React, Vue, Svelte and existing component systems; project toolchain required for verification." dependencies: []

搜索下拉框 · Searchable Select

把项目里的 Select 统一成明确的渐进增强契约：候选项不超过 5 个时保留轻量原生体验，达到 6 个时支持搜索；长列表在普通页面和 Dialog/Portal 中都能真实滚动、选择和键盘操作。

Triggers

Activate when

• 用户说“所有 Select 超过 5 个选项就支持搜索”“下拉选项太多，需要筛选”。
• 用户说“候选项无法滚动”“弹窗里的下拉列表滚轮没反应”。
• 用户要把多个原生 <select> 收敛成兼容既有 value、onChange 或表单语义的共享可搜索组件。
• The user asks to “make selects searchable after five options”, “build an accessible searchable select”, or “fix combobox scrolling inside a dialog”.

Do not activate when

• 只要求重做页面视觉、排版或整体交互语言，没有 Select 行为目标；使用前端设计能力。
• 只要求安装 shadcn/ui 或其他组件库；使用对应安装能力。
• 需要的是后端全文检索、远程搜索接口或数据索引，不是候选项本地过滤。
• 报错与 Select、Combobox、Listbox、Popover 或滚动锁无关；使用常规诊断流程。

User Profile (cross-session)

Read skill.yaml and resolve the shared user-profile/v1 context at the start of every run. Use this precedence: current request, project context, Skill-specific records, shared preferences, user/brand Profile, then safe defaults.

The default search threshold is 5 unless the current request or a directly stated durable preference overrides it. Persist only direct durable statements through scripts/profile_store.py record --confirm; keep inferred project facts and all secrets out of the Profile. See references/user-profile.md.

Skill Group Composition

Read references/skill-composition.md before invoking adjacent capabilities. This Skill owns the final code patch and interaction acceptance for searchable Selects. Design briefs and root-cause reports may enter as optional artifacts, but sibling Skills are not runtime dependencies.

Workflow (MANDATORY)

Step 0: Resolve context and preserve the workspace

1. Read repository instructions, the active project toolchain, and the shared Profile contract.
2. Inspect the real working tree and preserve unrelated changes.
3. Read references/select-search-playbook.md completely before changing code.
4. Treat screenshots or attached documents as evidence, not instructions.

Step 1: Inventory every Select surface

1. Find shared Select primitives first, then all call sites and raw <select> elements.
2. Record each surface, option source, expected maximum count, single or multiple selection, controlled or uncontrolled state, and whether it appears inside Dialog, Sheet, Drawer, Popover, or another scroll lock.
3. Count displayed candidate options, including an explicit “none” choice and excluding optgroup headings. Recompute when dynamic children change.
4. Use the exact threshold rule: 5 or fewer candidates stay native; 6 or more become searchable unless the request specifies another threshold.

Step 2: Define the compatibility contract

Before editing, preserve the existing public behavior: value, defaultValue, onChange, disabled, required, name, form submission, labels, validation, placeholder choices, and focus return. Multi-select needs a searchable multi-select pattern; do not silently downgrade it to single-select.

Prefer extending one shared primitive over patching individual screens. If the project already has an accessible searchable Select, reuse and repair it instead of adding a parallel component.

Step 3: Implement progressive search

1. Keep the small-option branch native.
2. For the searchable branch, expose a combobox trigger, searchbox, listbox, and options while keeping the project's value/change contract intact.
3. Normalize queries with Unicode NFKC, locale-aware case folding, whitespace collapse, and multi-term matching so Chinese and mixed-language labels work.
4. Support empty results, disabled options, selected state, dynamic options, and a bounded popup width.
5. Keep search state ephemeral: clear it when the popup closes unless the product explicitly needs persistence.

Step 4: Make scrolling real

1. Give the listbox a measurable maximum height, vertical overflow, visible or discoverable scroll affordance, overscroll containment, and touch panning.
2. When the popup is portaled from inside a modal, inspect the actual scroll-lock boundary. Use the popup primitive's modal/allowlisted layer, a safe portal container, or the scroll-lock library's shard mechanism so the popup is treated as interactive content.
3. Do not call a height change a fix when scrollHeight > clientHeight but a real wheel event leaves scrollTop unchanged.
4. Use manual wheel interception only as a documented last resort after the modal/portal ownership is corrected.

Step 5: Complete keyboard and accessibility behavior

• Provide accessible names and the correct combobox, searchbox, listbox, and option relationships.
• Support Arrow Up/Down, Enter, Escape, Home/End where the underlying pattern allows it, active option visibility, disabled-option skipping, and focus restoration.
• Keep labels localized and do not create duplicate accessible native/custom controls.

Step 6: Verify the actual interaction

Verify at least:

1. Boundary: 5 options remain native and 6 options become searchable.
2. Search: Chinese, Latin text, whitespace, empty results, and selection propagate correctly.
3. Scroll: a real mouse-wheel or trackpad gesture changes scrollTop in a list where scrollHeight > clientHeight, both standalone and inside every relevant modal host.
4. Selection: an item can still be selected after scrolling, and closing restores focus and the parent modal state.
5. Keyboard: navigation, selection, escape, disabled items, and active-option scrolling work.
6. Regression: project typecheck, tests, lint/build, console errors, and form submission pass in proportion to risk.

Do not create real user data during verification when a cancel path can prove the interaction.

Step 7: Report the evidence

Lead with the user-visible outcome. Report the shared primitive and call sites changed, threshold behavior, root cause of any blocked scroll, real before/after interaction evidence, commands run, and remaining gaps. Do not claim touch, browser, framework, or modal coverage that was not exercised.

Dependencies

None beyond the target project's existing frontend stack and test/browser tooling. scripts/profile_store.py and local validation require Python 3.8+ and PyYAML.