dify - 💡(How to fix) Fix [Web] Migrate searchable pickers to dify-ui Combobox and Autocomplete primitives [4 pull requests]

Background

Follow-up to #32767. That issue tracks the broader legacy overlay migration to semantic Base UI primitives. During the review, several business components were identified where the remaining gap is not just the outer overlay (Popover/legacy portal), but the inner search-and-select primitive semantics.

Per packages/dify-ui/AGENTS.md:

• Combobox is for searching and selecting one or more predefined values from a collection.
• Autocomplete is for free-form text input with suggestions, where the final input value can be custom.
• Select should remain for small closed lists without text entry/filtering.

Combobox migration candidates

These components currently implement searchable entity selection manually, often with Popover, PortalToFollowElem, custom input filtering, async search, selected state, or multi-select checkbox behavior. Their semantics are Combobox rather than Select.

P0

• web/app/components/plugins/plugin-detail-panel/app-selector/index.tsx

• web/app/components/plugins/plugin-detail-panel/app-selector/app-picker.tsx

  • Remote paginated app search, single selected app, selected value needs to be preserved even when not present in the current page.

• web/app/components/datasets/common/document-picker/index.tsx

• web/app/components/datasets/common/document-picker/document-list.tsx

  • Remote document keyword search and single document selection.

• web/features/tag-management/components/tag-selector.tsx

• web/features/tag-management/components/tag-panel.tsx

  • Multi-select tag picker with draft selected state, filtering, and create-new-tag action.

• web/app/components/app/app-access-control/add-member-or-group-pop.tsx

  • Async user/group search, infinite loading, multi-select checkbox behavior, and group breadcrumb navigation.

P1

• web/app/components/header/account-setting/model-provider-page/model-selector/index.tsx

• web/app/components/header/account-setting/model-provider-page/model-selector/popup.tsx

• web/app/components/header/account-setting/model-provider-page/model-selector/popup-layout.tsx

  • Provider/model search and selection. Marketplace actions, notices, and footer should remain as custom content around the Combobox list.

• web/app/components/workflow/nodes/human-input/components/delivery-method/recipient/member-selector.tsx

• web/app/components/workflow/nodes/human-input/components/delivery-method/recipient/member-list.tsx

  • Local member search and single member selection with disabled/already-added rows.

• web/app/components/workflow/nodes/_base/components/variable/var-reference-vars.tsx

  • Variable search, grouped options, custom keyboard navigation, selected index, and nested object child panels. This is semantically Combobox, but migration is higher risk because selection returns ValueSelector + Var, supports hideSearch, and contains child popovers.

• web/app/components/plugins/reference-setting-modal/auto-update-setting/tool-picker.tsx

  • Installed plugin multi-select with search, tags, category tabs, and checkbox state.

• web/app/components/app/configuration/dataset-config/select-dataset/index.tsx

  • Dataset multi-select with async pagination and selected draft state. It is currently a dialog; if changed to a picker surface, use Combobox semantics for searchable dataset selection.

P2

• web/app/components/tools/labels/selector.tsx

  • Multi-select label picker with local search. Good low-risk migration sample.

• web/features/tag-management/components/tag-filter.tsx

  • Multi-select tag filter with local search and selected-count trigger.

• web/app/components/workflow/block-selector/tool-picker.tsx

  • Searchable multi-select tool picker with tags, custom tool creation, and marketplace recommendations. This is semantically close to Combobox, but the feature surface is large, so it should not be the first migration target.

Autocomplete / editor typeahead candidates

These are free-form editor or textarea suggestion flows. They should not be migrated as ordinary Combobox controls. They likely need an editor-aware wrapper such as MentionAutocomplete or EditorTypeaheadPopup, possibly using Autocomplete list/item semantics internally.

• web/app/components/workflow/comment/mention-input.tsx

  • Textarea mention insertion at caret, free-form comment text, @ query detection, custom keyboard navigation, and portal dropdown. Semantics are Autocomplete/typeahead, not Select or Combobox.

• web/app/components/workflow/nodes/_base/components/editor/code-editor/editor-support-vars.tsx

  • Monaco virtual caret popup and variable insertion. The main blocker is virtual anchor integration; the inner variable list can benefit after VarReferenceVars is migrated.

• web/app/components/base/prompt-editor/plugins/component-picker-block/index.tsx

• web/app/components/base/prompt-editor/plugins/component-picker-block/menu.tsx

• web/app/components/base/prompt-editor/plugins/component-picker-block/prompt-option.tsx

• web/app/components/base/prompt-editor/plugins/component-picker-block/variable-option.tsx

  • Lexical typeahead menu. Lexical already owns trigger matching, range anchoring, option selection, and cleanup. Do not replace the whole plugin with Combobox/Autocomplete directly; only reuse migrated item/list primitives where compatible.

• web/app/components/base/prompt-editor/plugins/shortcuts-popup-plugin/index.tsx

  • Hotkey-triggered arbitrary popup anchored to a DOM Range. This is not Combobox/Autocomplete; it is closer to a virtual-anchor Popover/Menu problem.

Not Combobox/Autocomplete priorities

Keep these out of this migration unless their behavior changes to searchable entity selection:

• web/app/components/header/account-dropdown/workplace-selector/index.tsx

  • Already uses @langgenius/dify-ui/select; small closed list, no search.

• web/app/components/base/notion-page-selector/credential-selector/index.tsx

  • Short credential/workspace list. Prefer Select if migrating, not Combobox.

• web/app/components/header/app-selector/index.tsx

  • Header navigation menu plus create-app action. It currently uses Headless UI, but the semantics are menu/select-like rather than searchable Combobox.

Suggested order

1. Start with low-risk Combobox samples: LabelSelector or MemberSelector.
2. Migrate DocumentPicker and AppPicker to validate remote search / selected value preservation.
3. Migrate TagSelector / TagFilter once multiple selection and custom action rows are settled.
4. Treat VarReferenceVars as a separate focused refactor because it unlocks downstream improvements in Monaco and Lexical editor popups.

Acceptance criteria

• New or modified searchable entity pickers use @langgenius/dify-ui/combobox for predefined selected values.
• Free-form editor suggestions use @langgenius/dify-ui/autocomplete only through an editor/textarea-aware wrapper where needed.
• Select remains reserved for small closed lists without text input.
• No new legacy overlay imports are introduced; existing legacy usage should shrink as part of each touched migration.
• Paths above are either migrated or explicitly documented as deferred with a concrete reason.