pulsar-select-list 1.0.0

package/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright (c) 2011-2017 GitHub Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,444 @@
+# pulsar-select-list
+
+This module is an [etch component](https://github.com/atom/etch) that can be used in Pulsar packages to show a select list with fuzzy filtering, keyboard/mouse navigation and other cool features.
+
+## Installation
+
+```json
+"dependencies": {
+  "pulsar-select-list": "^1.0.0"
+}
+```
+
+## Usage
+
+After installing the module, you can simply require it and use it as a standalone component:
+
+```js
+const SelectListView = require('pulsar-select-list')
+
+const usersSelectList = new SelectListView({
+  items: ['Alice', 'Bob', 'Carol'],
+  elementForItem: (item) => {
+    const li = document.createElement('li')
+    li.textContent = item
+    return li
+  },
+  didConfirmSelection: (item) => {
+    console.log('Selected:', item)
+  }
+})
+
+// Show as modal panel
+usersSelectList.show()
+```
+
+Or within another etch component:
+
+```jsx
+render () {
+  return (
+    <SelectListView items={this.items} />
+  )
+}
+```
+
+## API
+
+### Constructor Props
+
+When creating a new instance of a select list, or when calling `update` on an existing one, you can supply a JavaScript object that can contain any of the following properties:
+
+#### Required
+
+* `items: [Object]`: an array containing the objects you want to show in the select list.
+* `elementForItem: (item: Object, options: Object) -> HTMLElement`: a function that is called whenever an item needs to be displayed.
+  * `options: Object`:
+    * `selected: Boolean`: indicating whether item is selected or not.
+    * `index: Number`: item's index.
+    * `visible: Boolean`: indicating whether item is visible in viewport or not.
+
+#### Optional
+
+* `className: String`: CSS class name(s) to add to the select list element. Multiple classes can be space-separated.
+* `maxResults: Number`: the number of maximum items that are shown.
+* `filter: (items: [Object], query: String) -> [Object]`: a function that allows to decide which items to show whenever the query changes. By default, it uses Pulsar's built-in fuzzy matcher.
+* `filterKeyForItem: (item: Object) -> String`: when `filter` is not provided, this function will be called to retrieve a string property on each item and that will be used to filter them.
+* `filterQuery: (query: String) -> String`: a function that allows to apply a transformation to the user query and whose return value will be used to filter items.
+* `replaceDiacritics: Boolean`: when `true` (default), removes diacritical marks from both the query and item text before filtering, enabling accent-insensitive matching (e.g., "cafe" matches "café"). Set to `false` to disable.
+* `filterScoreModifier: (score: Number, item: Object) -> Number`: a function to modify the fuzzy match score for each item. Useful for applying custom ranking factors (e.g., boosting by recency or proximity).
+* `filterThreshold: Number`: minimum score required for an item to be included in results; defaults to `0`. Scores at or below this threshold are filtered out.
+* `query: String`: a string that will replace the contents of the query editor.
+* `selectQuery: Boolean`: a boolean indicating whether the query text should be selected or not.
+* `order: (item1: Object, item2: Object) -> Number`: a function that allows to change the order in which items are shown.
+* `emptyMessage: String`: a string shown when the list is empty.
+* `errorMessage: String`: a string that needs to be set when you want to notify the user that an error occurred.
+* `infoMessage: String`: a string that needs to be set when you want to provide some information to the user.
+* `helpMessage: String|Array`: content to display when help is toggled. Use `toggleHelp()` to show/hide. Can be a string or JSX array for rich formatting.
+* `helpMarkdown: String`: markdown content to display when help is toggled. Rendered using Pulsar's built-in markdown renderer. Preferred over `helpMessage` for simple help text stored in `.md` files.
+* `loadingMessage: String`: a string that needs to be set when you are loading items in the background.
+* `loadingBadge: String/Number`: a string or number that needs to be set when the progress status changes.
+* `itemsClassList: [String]`: an array of strings that will be added as class names to the items element.
+* `initialSelectionIndex: Number`: the index of the item to initially select; defaults to `0`.
+* `initiallyVisibleItemCount: Number`: When provided, `SelectListView` observes visibility of items in viewport, visibility state is passed as `visible` option to `elementForItem`.
+* `placeholderText: String`: placeholder text to display in the query editor when empty.
+* `skipCommandsRegistration: Boolean`: when `true`, skips registering default keyboard commands.
+
+### Registered Commands
+
+By default, the component registers these commands on its element:
+
+* `core:move-up` / `core:move-down`: Navigate items
+* `core:move-to-top` / `core:move-to-bottom`: Jump to first/last item
+* `core:confirm`: Confirm selection
+* `core:cancel`: Cancel selection
+* `select-list:help`: Toggle help message visibility (requires `helpMessage` or `helpMarkdown`)
+
+#### Callbacks
+
+* `didChangeQuery: (query: String) -> Void`: called when the query changes.
+* `didChangeSelection: (item: Object) -> Void`: called when the selected item changes.
+* `didConfirmSelection: (item: Object) -> Void`: called when the user clicks or presses Enter on an item.
+* `didConfirmEmptySelection: () -> Void`: called when the user presses Enter but the list is empty.
+* `didCancelSelection: () -> Void`: called when the user presses Esc or the list loses focus.
+* `willShow: () -> Void`: called when transitioning from hidden to visible, useful for data preparation.
+
+### Instance Properties
+
+* `processedQuery: String`: The cached result of `getFilterQuery()`, updated after each query change. Useful in `elementForItem` to avoid calling `getFilterQuery()` multiple times.
+* `refs.queryEditor`: The underlying TextEditor component for the query input.
+
+### Instance Methods
+
+#### Panel Management
+
+* `show()`: Shows the select list as a modal panel and focuses the query editor. Calls `willShow` callback if provided.
+* `hide()`: Hides the panel and restores focus to the previously focused element.
+* `toggle()`: Toggles the visibility of the panel.
+* `isVisible()`: Returns `true` if the panel is currently visible.
+* `isHelpMode()`: Returns `true` if help is currently displayed.
+* `toggleHelp()`: Toggles help message visibility. Only works if `helpMessage` is set.
+* `hideHelp()`: Hides help message if currently shown.
+
+#### Other Methods
+
+* `focus()`: Focuses the query editor.
+* `reset()`: Clears the query editor text.
+* `destroy()`: Disposes of the component and cleans up resources.
+* `update(props)`: Updates the component with new props.
+* `getQuery()`: Returns the current query string.
+* `getFilterQuery()`: Returns the filtered query string (applies `filterQuery` transformation).
+* `setQueryFromSelection()`: Sets the query text from the active editor's selection. Returns `true` if successful, `false` if no editor, no selection, or selection contains newlines.
+* `getSelectedItem()`: Returns the currently selected item.
+* `selectPrevious()`: Selects the previous item.
+* `selectNext()`: Selects the next item.
+* `selectFirst()`: Selects the first item.
+* `selectLast()`: Selects the last item.
+* `selectNone()`: Deselects all items.
+* `selectIndex(index)`: Selects the item at the given index.
+* `selectItem(item)`: Selects the given item.
+* `confirmSelection()`: Confirms the current selection.
+* `cancelSelection()`: Cancels the selection.
+
+### Static Methods
+
+#### `SelectListView.highlightMatches(text, matchIndices, options)`
+
+Creates a DocumentFragment with highlighted match characters.
+
+```js
+const matches = atom.ui.fuzzyMatcher.match(query, text, {
+  recordMatchIndexes: true
+}).matchIndexes
+
+const fragment = SelectListView.highlightMatches(text, matches)
+element.appendChild(fragment)
+
+// With custom class name
+const fragment = SelectListView.highlightMatches(text, matches, {
+  className: 'my-highlight'
+})
+```
+
+* `text: String`: the text to highlight.
+* `matchIndices: [Number]`: array of character indices to highlight.
+* `options: Object` (optional):
+  * `className: String`: CSS class for highlighted spans; defaults to `'character-match'`.
+
+Returns a `DocumentFragment` containing text nodes and `<span>` elements with the specified class.
+
+#### `SelectListView.replaceDiacritics(str)`
+
+Removes diacritical marks (accents) from a string.
+
+```js
+SelectListView.replaceDiacritics('café') // => 'cafe'
+SelectListView.replaceDiacritics('naïve') // => 'naive'
+SelectListView.replaceDiacritics('Müller') // => 'Muller'
+```
+
+* `str: String`: the string to process.
+
+Returns the string with diacritical marks removed. Uses `String.normalize('NFD')` internally.
+
+#### `SelectListView.createTwoLineItem(options)`
+
+Creates a two-line list item element with primary and optional secondary lines. This is a convenience helper for the common Atom/Pulsar two-line item pattern.
+
+```js
+const li = SelectListView.createTwoLineItem({
+  primary: SelectListView.highlightMatches(item.name, matches),
+  secondary: item.description,
+  icon: ['icon-file-text']
+})
+```
+
+* `options: Object`:
+  * `primary: String|Node`: Primary line content (text string or DOM node)
+  * `secondary: String|Node` (optional): Secondary line content
+  * `icon: [String]` (optional): Icon class names to add to primary line (adds `icon` class automatically)
+
+Returns an `HTMLLIElement` with the structure:
+```html
+<li class="two-lines">
+  <div class="primary-line icon [icon]">[primary]</div>
+  <div class="secondary-line">[secondary]</div>
+</li>
+```
+
+#### `SelectListView.setScheduler(scheduler)`
+
+Sets the etch scheduler.
+
+#### `SelectListView.getScheduler()`
+
+Gets the current etch scheduler.
+
+## Example
+
+```js
+const SelectListView = require('pulsar-select-list')
+const fs = require('fs')
+const path = require('path')
+
+class MyFileList {
+  constructor() {
+    this.selectList = new SelectListView({
+      className: 'my-package my-file-list',
+      items: [],
+      filterKeyForItem: (item) => item.name,
+      emptyMessage: 'No files found',
+      helpMarkdown: fs.readFileSync(path.join(__dirname, 'help.md'), 'utf8'),
+
+      willShow: () => {
+        this.previouslyFocusedElement = document.activeElement
+        this.loadFiles()
+      },
+
+      elementForItem: (item, options) => {
+        const li = document.createElement('li')
+        if (!options.visible) {
+          return li
+        }
+
+        const query = this.selectList.processedQuery || ''
+        const matches = query
+          ? atom.ui.fuzzyMatcher.match(item.name, query, {
+              recordMatchIndexes: true
+            }).matchIndexes
+          : []
+
+        li.appendChild(SelectListView.highlightMatches(item.name, matches))
+
+        li.addEventListener('contextmenu', () => {
+          this.selectList.selectIndex(options.index)
+        })
+
+        return li
+      },
+
+      didConfirmSelection: (item) => {
+        atom.workspace.open(item.path)
+        this.selectList.hide()
+      },
+
+      didCancelSelection: () => {
+        this.selectList.hide()
+      },
+    })
+  }
+
+  loadFiles() {
+    // Load files and update items
+    this.selectList.update({ items: this.files })
+  }
+
+  toggle() {
+    this.selectList.toggle()
+  }
+
+  destroy() {
+    this.selectList.destroy()
+  }
+}
+```
+
+### Advanced: Custom Score Modifier
+
+Use `filterScoreModifier` and `filterThreshold` to customize ranking:
+
+```js
+const selectList = new SelectListView({
+  items: files,
+  elementForItem: (item) => {
+    const li = document.createElement('li')
+    li.textContent = item.path
+    return li
+  },
+  filterKeyForItem: (item) => item.path,
+  // Boost score by proximity (items closer to current file rank higher)
+  filterScoreModifier: (score, item) => score / item.distance,
+  // Only show items with meaningful scores
+  filterThreshold: 0.01,
+  didConfirmSelection: (item) => {
+    atom.workspace.open(item.path)
+  }
+})
+```
+
+## Migration from atom-select-list
+
+If you're migrating from `atom-select-list`, here are the key changes:
+
+### Package.json
+
+```diff
+"dependencies": {
+-  "atom-select-list": "^0.8.1",
++  "pulsar-select-list": "^1.0.0"
+}
+```
+
+### Import
+
+```diff
+-const SelectListView = require('atom-select-list')
++const SelectListView = require('pulsar-select-list')
+```
+
+### Panel Management
+
+The component now manages its own panel. Remove custom panel handling:
+
+```diff
+-this.panel = null
+-this.previouslyFocusedElement = null
+
+this.slv = new SelectListView({
++  className: 'my-list',
+   items: [],
++  willShow: () => this.onWillShow(),
+   // ...
+})
+-this.slv.element.classList.add('my-list')
+
+-showView() {
+-  this.previouslyFocusedElement = document.activeElement
+-  if (!this.panel) {
+-    this.panel = atom.workspace.addModalPanel({ item: this.slv })
+-  }
+-  this.panel.show()
+-  this.slv.focus()
+-}
+-
+-hideView() {
+-  this.panel.hide()
+-  if (this.previouslyFocusedElement) {
+-    this.previouslyFocusedElement.focus()
+-  }
+-}
+-
+-toggleView() {
+-  if (this.panel && this.panel.isVisible()) {
+-    this.hideView()
+-  } else {
+-    this.showView()
+-  }
+-}
+
+// Use built-in methods:
+-this.toggleView()
++this.slv.toggle()
+
+-this.hideView()
++this.slv.hide()
+```
+
+### Diacritics
+
+Replace external diacritics library with built-in static method:
+
+```diff
+-const Diacritics = require('diacritic')
+
+-Diacritics.clean(text)
++SelectListView.replaceDiacritics(text)
+```
+
+### Query Access
+
+Use `processedQuery` instead of storing query in filter:
+
+```diff
+filter(items, query) {
+-  this.query = query
++  // query is passed to filter, use this.slv.processedQuery in elementForItem
+}
+
+elementForItem(item, options) {
+-  const query = this.query
++  const query = this.slv.processedQuery || ''
+}
+```
+
+### Highlighting
+
+Use built-in `highlightMatches` static method:
+
+```diff
+-this.highlightInElement(el, text, indices)
++el.appendChild(SelectListView.highlightMatches(text, indices))
+```
+
+
+### Help Message
+
+Replace `infoMessage` with `helpMarkdown` and the built-in `select-list:help` command:
+
+```diff
+this.slv = new SelectListView({
+-  // No help by default
++  helpMarkdown: fs.readFileSync(path.join(__dirname, 'help.md'), 'utf8'),
+})
+
+-atom.config.observe('my-package.showKeystrokes', (value) => {
+-  this.slv.update({ infoMessage: value ? [...] : null })
+-})
+```
+
+Create a `help.md` file with your help content:
+
+```markdown
+- **Enter** — Confirm selection
+- **Alt+Enter** — Alternative action
+- **F12** — Toggle this help
+```
+
+Add F12 keybinding to toggle help (keymaps/my-package.cson):
+
+```cson
+'.my-list atom-text-editor[mini]':
+  'f12': 'select-list:help'
+```
+
+The `select-list:help` command is registered automatically by the component.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "pulsar-select-list",
+  "version": "1.0.0",
+  "description": "A general-purpose select list for use in Pulsar packages",
+  "main": "select.js",
+  "license": "MIT",
+  "keywords": [
+    "pulsar",
+    "atom",
+    "select-list",
+    "fuzzy",
+    "filter",
+    "ui"
+  ],
+  "files": [
+    "select.js",
+    "select.less",
+    "LICENSE.md",
+    "README.md"
+  ],
+  "dependencies": {
+    "etch": "^0.14.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asiloisad/pulsar-select-list.git"
+  },
+  "bugs": {
+    "url": "https://github.com/asiloisad/pulsar-select-list/issues"
+  },
+  "homepage": "https://github.com/asiloisad/pulsar-select-list#readme"
+}

package/select.js

@@ -0,0 +1,806 @@
+'use strict'
+
+const { Disposable, CompositeDisposable, TextEditor } = require('atom')
+const etch = require('etch')
+const $ = etch.dom
+
+class SelectListView {
+  static setScheduler(scheduler) {
+    etch.setScheduler(scheduler)
+  }
+
+  static getScheduler() {
+    return etch.getScheduler()
+  }
+
+  static replaceDiacritics(str) {
+    if (!str) return ''
+    return str.normalize('NFD').replace(/[\u0300-\u036f]/g, '')
+  }
+
+  static highlightMatches(text, matchIndices, options = {}) {
+    const { className = 'character-match' } = options
+    const fragment = document.createDocumentFragment()
+
+    if (!matchIndices || matchIndices.length === 0) {
+      fragment.appendChild(document.createTextNode(text))
+      return fragment
+    }
+
+    // Filter out invalid indices (negative or out of range)
+    const validIndices = matchIndices.filter((i) => i >= 0 && i < text.length)
+
+    if (validIndices.length === 0) {
+      fragment.appendChild(document.createTextNode(text))
+      return fragment
+    }
+
+    let lastIndex = 0
+    let matchChars = ''
+
+    for (const index of validIndices) {
+      if (index > lastIndex) {
+        if (matchChars) {
+          const span = document.createElement('span')
+          span.className = className
+          span.textContent = matchChars
+          fragment.appendChild(span)
+          matchChars = ''
+        }
+        fragment.appendChild(document.createTextNode(text.slice(lastIndex, index)))
+      }
+      matchChars += text[index]
+      lastIndex = index + 1
+    }
+
+    if (matchChars) {
+      const span = document.createElement('span')
+      span.className = className
+      span.textContent = matchChars
+      fragment.appendChild(span)
+    }
+
+    if (lastIndex < text.length) {
+      fragment.appendChild(document.createTextNode(text.slice(lastIndex)))
+    }
+
+    return fragment
+  }
+
+  /**
+   * Creates a two-line list item element with primary and optional secondary lines.
+   * @param {Object} options - Configuration options
+   * @param {string|Node} options.primary - Primary line content (text or DOM node)
+   * @param {string|Node} [options.secondary] - Secondary line content (optional)
+   * @param {string[]} [options.icon] - Icon class names to add to primary line
+   * @returns {HTMLLIElement} The created list item element
+   */
+  static createTwoLineItem({ primary, secondary, icon }) {
+    const li = document.createElement('li')
+    li.classList.add('two-lines')
+
+    const priLine = document.createElement('div')
+    priLine.classList.add('primary-line')
+    if (icon && icon.length > 0) {
+      priLine.classList.add('icon', ...icon)
+    }
+    if (typeof primary === 'string') {
+      priLine.textContent = primary
+    } else if (primary) {
+      priLine.appendChild(primary)
+    }
+    li.appendChild(priLine)
+
+    if (secondary !== undefined && secondary !== null) {
+      const secLine = document.createElement('div')
+      secLine.classList.add('secondary-line')
+      if (typeof secondary === 'string') {
+        secLine.textContent = secondary
+      } else {
+        secLine.appendChild(secondary)
+      }
+      li.appendChild(secLine)
+    }
+
+    return li
+  }
+
+  constructor(props) {
+    this.props = props
+    if (!this.props.hasOwnProperty('initialSelectionIndex')) {
+      this.props.initialSelectionIndex = 0
+    }
+    if (props.initiallyVisibleItemCount) {
+      this.initializeVisibilityObserver()
+    }
+    this.computeItems(false)
+    this.showHelp = false
+    this.helpMarkdownHtml = null
+    this.renderHelpMarkdownOnce()
+    this.disposables = new CompositeDisposable()
+    etch.initialize(this)
+    this.element.classList.add('select-list')
+    if (props.className) {
+      this.element.classList.add(...props.className.split(/\s+/).filter(Boolean))
+    }
+    this.disposables.add(this.refs.queryEditor.onDidChange(this.didChangeQuery.bind(this)))
+    this.disposables.add(this.refs.queryEditor.onWillInsertText((event) => {
+      if (event.text === '`') {
+        event.cancel()
+        this.toggleHelp()
+      }
+    }))
+    if (props.placeholderText) {
+      this.refs.queryEditor.setPlaceholderText(props.placeholderText)
+    }
+    if (!props.skipCommandsRegistration) {
+      this.disposables.add(this.registerAtomCommands())
+    }
+    const editorElement = this.refs.queryEditor.element
+    const didLoseFocus = this.didLoseFocus.bind(this)
+    editorElement.addEventListener('blur', didLoseFocus)
+
+    this.didClickInside = false
+    this.didMouseDown = () => {
+      this.didClickInside = true
+    }
+    this.element.addEventListener('mousedown', this.didMouseDown)
+    this.disposables.add(new Disposable(() => {
+      editorElement.removeEventListener('blur', didLoseFocus)
+      this.element.removeEventListener('mousedown', this.didMouseDown)
+    }))
+  }
+
+  initializeVisibilityObserver() {
+    this.visibilityObserver = new IntersectionObserver(changes => {
+      for (const change of changes) {
+        if (change.intersectionRatio > 0) {
+          const element = change.target
+          this.visibilityObserver.unobserve(element)
+          const index = Array.from(this.refs.items.children).indexOf(element)
+          if (index >= 0) {
+            this.renderItemAtIndex(index)
+          }
+        }
+      }
+    })
+  }
+
+  focus() {
+    this.refs.queryEditor.element.focus()
+  }
+
+  didLoseFocus(event) {
+    if (this.didClickInside || this.element.contains(event.relatedTarget)) {
+      this.didClickInside = false
+      this.refs.queryEditor.element.focus()
+    } else if (document.hasFocus() && this.isVisible()) {
+      this.cancelSelection()
+    }
+  }
+
+  reset() {
+    this.refs.queryEditor.setText('')
+  }
+
+  destroy() {
+    this.disposables.dispose()
+    if (this.visibilityObserver) this.visibilityObserver.disconnect()
+    if (this.panel) {
+      this.panel.destroy()
+      this.panel = null
+    }
+    return etch.destroy(this)
+  }
+
+  show() {
+    if (this.isVisible()) { return }
+
+    // Call willShow callback only when transitioning from hidden to visible
+    if (this.props.willShow) {
+      this.props.willShow()
+    }
+
+    // Store previously focused element, but skip other select-list inputs
+    const active = document.activeElement
+    if (active && !active.closest('.select-list')) {
+      this.previouslyFocusedElement = active
+    }
+
+    this.refs.queryEditor.selectAll()
+
+    if (!this.panel) {
+      this.panel = atom.workspace.addModalPanel({ item: this, visible: false })
+    }
+
+    this.panel.show()
+    this.focus()
+  }
+
+  hide() {
+    if (!this.isVisible()) { return }
+
+    if (this.panel) {
+      this.panel.hide()
+    }
+
+    if (this.previouslyFocusedElement) {
+      this.previouslyFocusedElement.focus()
+      this.previouslyFocusedElement = null
+    }
+  }
+
+  toggle() {
+    if (this.isVisible()) {
+      this.hide()
+    } else {
+      this.show()
+    }
+  }
+
+  isVisible() {
+    return this.panel && this.panel.isVisible()
+  }
+
+  registerAtomCommands() {
+    return atom.commands.add(this.element, {
+      'core:move-up': (event) => {
+        if (this.isHelpMode()) return
+        this.selectPrevious()
+        event.stopPropagation()
+      },
+      'core:move-down': (event) => {
+        if (this.isHelpMode()) return
+        this.selectNext()
+        event.stopPropagation()
+      },
+      'core:move-to-top': (event) => {
+        if (this.isHelpMode()) return
+        this.selectFirst()
+        event.stopPropagation()
+      },
+      'core:move-to-bottom': (event) => {
+        if (this.isHelpMode()) return
+        this.selectLast()
+        event.stopPropagation()
+      },
+      'core:confirm': (event) => {
+        this.confirmSelection()
+        event.stopPropagation()
+      },
+      'core:cancel': (event) => {
+        this.cancelSelection()
+        event.stopPropagation()
+      },
+      'select-list:help': (event) => {
+        this.toggleHelp()
+        event.stopPropagation()
+      }
+    })
+  }
+
+  update(props = {}) {
+    let shouldComputeItems = false
+
+    if ('items' in props) {
+      this.props.items = props.items
+      shouldComputeItems = true
+    }
+
+    if ('maxResults' in props) {
+      this.props.maxResults = props.maxResults
+      shouldComputeItems = true
+    }
+
+    if ('filter' in props) {
+      this.props.filter = props.filter
+      shouldComputeItems = true
+    }
+
+    if ('filterQuery' in props) {
+      this.props.filterQuery = props.filterQuery
+      shouldComputeItems = true
+    }
+
+    if ('replaceDiacritics' in props) {
+      this.props.replaceDiacritics = props.replaceDiacritics
+      shouldComputeItems = true
+    }
+
+    if ('filterKeyForItem' in props) {
+      this.props.filterKeyForItem = props.filterKeyForItem
+      shouldComputeItems = true
+    }
+
+    if ('filterScoreModifier' in props) {
+      this.props.filterScoreModifier = props.filterScoreModifier
+      shouldComputeItems = true
+    }
+
+    if ('filterThreshold' in props) {
+      this.props.filterThreshold = props.filterThreshold
+      shouldComputeItems = true
+    }
+
+    if ('query' in props) {
+      this.refs.queryEditor.setText(props.query)
+      shouldComputeItems = false
+    }
+
+    if ('selectQuery' in props) {
+      if (props.selectQuery) {
+        this.refs.queryEditor.selectAll()
+      } else {
+        this.refs.queryEditor.clearSelections()
+      }
+    }
+
+    if ('order' in props) {
+      this.props.order = props.order
+    }
+
+    if ('emptyMessage' in props) {
+      this.props.emptyMessage = props.emptyMessage
+    }
+
+    if ('errorMessage' in props) {
+      this.props.errorMessage = props.errorMessage
+    }
+
+    if ('infoMessage' in props) {
+      this.props.infoMessage = props.infoMessage
+    }
+
+    if ('helpMessage' in props) {
+      this.props.helpMessage = props.helpMessage
+    }
+
+    if ('helpMarkdown' in props) {
+      this.props.helpMarkdown = props.helpMarkdown
+      this.helpMarkdownHtml = null
+      this.renderHelpMarkdownOnce()
+    }
+
+    if ('loadingMessage' in props) {
+      this.props.loadingMessage = props.loadingMessage
+    }
+
+    if ('loadingBadge' in props) {
+      this.props.loadingBadge = props.loadingBadge
+    }
+
+    if ('itemsClassList' in props) {
+      this.props.itemsClassList = props.itemsClassList
+    }
+
+    if ('initialSelectionIndex' in props) {
+      this.props.initialSelectionIndex = props.initialSelectionIndex
+    }
+
+    if ('placeholderText' in props) {
+      this.props.placeholderText = props.placeholderText
+      this.refs.queryEditor.setPlaceholderText(props.placeholderText || '')
+    }
+
+    if (shouldComputeItems) {
+      this.computeItems()
+    }
+
+    return etch.update(this)
+  }
+
+  render() {
+    return $.div(
+      {},
+      this.renderQueryRow(),
+      this.renderLoadingMessage(),
+      this.renderInfoMessage(),
+      this.renderErrorMessage(),
+      this.renderHelpMessage(),
+      this.renderItems()
+    )
+  }
+
+  renderQueryRow() {
+    if (this.props.helpMessage || this.props.helpMarkdown) {
+      return $.div(
+        { className: 'select-list-query-row' },
+        $(TextEditor, { ref: 'queryEditor', mini: true }),
+        $.span({
+          className: 'select-list-help-toggle icon-question',
+          on: { click: () => this.toggleHelp() }
+        })
+      )
+    }
+    return $(TextEditor, { ref: 'queryEditor', mini: true })
+  }
+
+  renderItems() {
+    if (this.isHelpMode()) {
+      return ''
+    }
+    if (this.items.length > 0) {
+      const className = ['list-group'].concat(this.props.itemsClassList || []).join(' ')
+
+      if (this.visibilityObserver) {
+        etch.getScheduler().updateDocument(() => {
+          Array.from(this.refs.items.children).slice(this.props.initiallyVisibleItemCount).forEach((element) => {
+            this.visibilityObserver.observe(element)
+          })
+        })
+      }
+
+      this.listItems = this.items.map((item, index) => {
+        const selected = this.getSelectedItem() === item
+        const visible = !this.props.initiallyVisibleItemCount || index < this.props.initiallyVisibleItemCount
+        return $(ListItemView, {
+          element: this.props.elementForItem(item, { selected, index, visible }),
+          selected: selected,
+          onclick: () => this.didClickItem(index),
+          oncontextmenu: () => this.selectIndex(index)
+        })
+      })
+
+      return $.ol(
+        { className, ref: 'items' },
+        ...this.listItems
+      )
+    } else if (!this.props.loadingMessage && !this.isHelpMode() && this.props.emptyMessage) {
+      return $.div({ ref: 'emptyMessage', className: 'empty-message' }, this.props.emptyMessage)
+    } else {
+      return ""
+    }
+  }
+
+  renderErrorMessage() {
+    if (this.props.errorMessage) {
+      return $.div({ ref: 'errorMessage', className: 'error-message' }, this.props.errorMessage)
+    } else {
+      return ''
+    }
+  }
+
+  renderInfoMessage() {
+    if (this.props.infoMessage) {
+      return $.div({ ref: 'infoMessage', className: 'info-message' }, this.props.infoMessage)
+    } else {
+      return ''
+    }
+  }
+
+  renderLoadingMessage() {
+    if (this.props.loadingMessage) {
+      return $.div(
+        { className: 'loading' },
+        $.div({ ref: 'loadingMessage', className: 'loading-message' }, this.props.loadingMessage),
+        $.span({ className: 'loading loading-spinner-tiny inline-block' }),
+        this.props.loadingBadge ? $.span({ ref: 'loadingBadge', className: 'badge' }, this.props.loadingBadge) : ''
+      )
+    } else {
+      return ''
+    }
+  }
+
+  renderHelpMessage() {
+    if (!this.showHelp) {
+      return ''
+    }
+    if (this.props.helpMarkdown) {
+      return $.div({ ref: 'helpMarkdownContainer', className: 'help-message' })
+    }
+    if (this.props.helpMessage) {
+      return $.div({ ref: 'helpMessage', className: 'help-message' }, this.props.helpMessage)
+    }
+    return ''
+  }
+
+  renderHelpMarkdownOnce() {
+    if (this.props.helpMarkdown && !this.helpMarkdownHtml) {
+      if (atom.ui && atom.ui.markdown && atom.ui.markdown.render) {
+        this.helpMarkdownHtml = atom.ui.markdown.render(this.props.helpMarkdown)
+      } else {
+        // Fallback: escape and wrap as text
+        const escaped = this.props.helpMarkdown.replace(/</g, '&lt;').replace(/>/g, '&gt;')
+        this.helpMarkdownHtml = `<p>${escaped}</p>`
+      }
+    }
+  }
+
+  updateHelpMarkdown() {
+    const container = this.element.querySelector('.help-message')
+    if (container && this.helpMarkdownHtml) {
+      container.innerHTML = this.helpMarkdownHtml
+    }
+  }
+
+  isHelpMode() {
+    return (this.props.helpMessage || this.props.helpMarkdown) && this.showHelp
+  }
+
+  toggleHelp() {
+    if (!this.props.helpMessage && !this.props.helpMarkdown) return
+    this.showHelp = !this.showHelp
+    return etch.update(this).then(() => {
+      // Use requestAnimationFrame to ensure DOM is fully rendered
+      requestAnimationFrame(() => {
+        this.updateHelpMarkdown()
+      })
+    })
+  }
+
+  hideHelp() {
+    if (this.showHelp) {
+      this.showHelp = false
+      return etch.update(this)
+    }
+    return Promise.resolve()
+  }
+
+  getQuery() {
+    if (this.refs && this.refs.queryEditor) {
+      return this.refs.queryEditor.getText()
+    } else {
+      return ''
+    }
+  }
+
+  getFilterQuery() {
+    return this.props.filterQuery ? this.props.filterQuery(this.getQuery()) : this.getQuery()
+  }
+
+  setQueryFromSelection() {
+    const editor = atom.workspace.getActiveTextEditor()
+    if (!editor) return false
+    const text = editor.getSelectedText()
+    if (!text || /\n/.test(text)) return false
+    this.refs.queryEditor.setText(text)
+    this.refs.queryEditor.selectAll()
+    return true
+  }
+
+  didChangeQuery() {
+    if (this.props.didChangeQuery) {
+      this.props.didChangeQuery(this.getFilterQuery())
+    }
+
+    this.hideHelp()
+    this.computeItems()
+  }
+
+  didClickItem(itemIndex) {
+    this.selectIndex(itemIndex)
+    this.confirmSelection()
+  }
+
+  computeItems(updateComponent) {
+    this.listItems = null
+    this.matchIndicesMap = new Map()
+    if (this.visibilityObserver) this.visibilityObserver.disconnect()
+    const filterFn = this.props.filter || this.fuzzyFilter.bind(this)
+    this.processedQuery = this.getFilterQuery()
+    this.items = filterFn(this.props.items.slice(), this.processedQuery)
+    if (this.props.order) {
+      this.items.sort(this.props.order)
+    }
+    if (this.props.maxResults) {
+      this.items = this.items.slice(0, this.props.maxResults)
+    }
+
+    this.selectIndex(this.props.initialSelectionIndex, updateComponent)
+  }
+
+  fuzzyFilter(items, query) {
+    if (query.length === 0) {
+      return items
+    }
+
+    const replaceDiacritics = this.props.replaceDiacritics ?? true
+    if (replaceDiacritics) {
+      query = SelectListView.replaceDiacritics(query)
+    }
+
+    const threshold = this.props.filterThreshold ?? 0
+    const modifyScore = this.props.filterScoreModifier
+    const scoredItems = []
+
+    for (const item of items) {
+      let string = this.props.filterKeyForItem ? this.props.filterKeyForItem(item) : item
+      if (replaceDiacritics) {
+        string = SelectListView.replaceDiacritics(string)
+      }
+      const result = atom.ui.fuzzyMatcher.match(string, query, { recordMatchIndexes: true })
+      if (!result) continue
+      let score = result.score
+      if (modifyScore) {
+        score = modifyScore(score, item)
+      }
+      if (score > threshold) {
+        scoredItems.push({ item, score, matchIndexes: result.matchIndexes })
+      }
+    }
+
+    scoredItems.sort((a, b) => b.score - a.score)
+    for (const { item, matchIndexes } of scoredItems) {
+      this.matchIndicesMap.set(item, matchIndexes)
+    }
+    return scoredItems.map((i) => i.item)
+  }
+
+  getMatchIndices(item) {
+    return this.matchIndicesMap ? this.matchIndicesMap.get(item) : null
+  }
+
+  getSelectedItem() {
+    if (this.selectionIndex === undefined) return null
+    return this.items[this.selectionIndex]
+  }
+
+  renderItemAtIndex(index) {
+    const item = this.items[index]
+    const selected = this.getSelectedItem() === item
+    const component = this.listItems[index].component
+    if (this.visibilityObserver) this.visibilityObserver.unobserve(component.element)
+    component.update({
+      element: this.props.elementForItem(item, { selected, index, visible: true }),
+      selected: selected,
+      onclick: () => this.didClickItem(index),
+      oncontextmenu: () => this.selectIndex(index)
+    })
+  }
+
+  selectPrevious() {
+    if (this.selectionIndex === undefined) return this.selectLast()
+    return this.selectIndex(this.selectionIndex - 1)
+  }
+
+  selectNext() {
+    if (this.selectionIndex === undefined) return this.selectFirst()
+    return this.selectIndex(this.selectionIndex + 1)
+  }
+
+  selectFirst() {
+    return this.selectIndex(0)
+  }
+
+  selectLast() {
+    return this.selectIndex(this.items.length - 1)
+  }
+
+  selectNone() {
+    return this.selectIndex(undefined)
+  }
+
+  selectIndex(index, updateComponent = true) {
+    if (index >= this.items.length) {
+      index = 0
+    } else if (index < 0) {
+      index = this.items.length - 1
+    }
+
+    const oldIndex = this.selectionIndex
+
+    this.selectionIndex = index
+    if (index !== undefined && this.props.didChangeSelection) {
+      this.props.didChangeSelection(this.getSelectedItem())
+    }
+
+    if (updateComponent) {
+      if (this.listItems) {
+        if (oldIndex >= 0) this.renderItemAtIndex(oldIndex)
+        if (index >= 0) this.renderItemAtIndex(index)
+        return etch.getScheduler().getNextUpdatePromise()
+      } else {
+        return etch.update(this)
+      }
+    } else {
+      return Promise.resolve()
+    }
+  }
+
+  selectItem(item) {
+    const index = this.items.indexOf(item)
+    if (index === -1) {
+      throw new Error('Cannot select the specified item because it does not exist.')
+    } else {
+      return this.selectIndex(index)
+    }
+  }
+
+  confirmSelection() {
+    const selectedItem = this.getSelectedItem()
+    if (selectedItem != null) {
+      if (this.props.didConfirmSelection) {
+        this.props.didConfirmSelection(selectedItem)
+      }
+    } else {
+      if (this.props.didConfirmEmptySelection) {
+        this.props.didConfirmEmptySelection()
+      }
+    }
+  }
+
+  cancelSelection() {
+    if (this.props.didCancelSelection) {
+      this.props.didCancelSelection()
+    }
+  }
+}
+
+class ListItemView {
+  constructor(props) {
+    this.mouseDown = this.mouseDown.bind(this)
+    this.mouseUp = this.mouseUp.bind(this)
+    this.didClick = this.didClick.bind(this)
+    this.didContextMenu = this.didContextMenu.bind(this)
+    this.selected = props.selected
+    this.onclick = props.onclick
+    this.oncontextmenu = props.oncontextmenu
+    this.element = props.element
+    this.element.addEventListener('mousedown', this.mouseDown)
+    this.element.addEventListener('mouseup', this.mouseUp)
+    this.element.addEventListener('click', this.didClick)
+    this.element.addEventListener('contextmenu', this.didContextMenu)
+    if (this.selected) {
+      this.element.classList.add('selected')
+    }
+    this.domEventsDisposable = new Disposable(() => {
+      this.element.removeEventListener('mousedown', this.mouseDown)
+      this.element.removeEventListener('mouseup', this.mouseUp)
+      this.element.removeEventListener('click', this.didClick)
+      this.element.removeEventListener('contextmenu', this.didContextMenu)
+    })
+    etch.getScheduler().updateDocument(this.scrollIntoViewIfNeeded.bind(this))
+  }
+
+  mouseDown(event) {
+    event.preventDefault()
+  }
+
+  mouseUp(event) {
+    event.preventDefault()
+  }
+
+  didClick(event) {
+    event.preventDefault()
+    this.onclick()
+  }
+
+  didContextMenu() {
+    this.oncontextmenu()
+  }
+
+  destroy() {
+    this.element.remove()
+    this.domEventsDisposable.dispose()
+  }
+
+  update(props) {
+    this.element.removeEventListener('mousedown', this.mouseDown)
+    this.element.removeEventListener('mouseup', this.mouseUp)
+    this.element.removeEventListener('click', this.didClick)
+    this.element.removeEventListener('contextmenu', this.didContextMenu)
+
+    this.element.parentNode.replaceChild(props.element, this.element)
+    this.element = props.element
+    this.element.addEventListener('mousedown', this.mouseDown)
+    this.element.addEventListener('mouseup', this.mouseUp)
+    this.element.addEventListener('click', this.didClick)
+    this.element.addEventListener('contextmenu', this.didContextMenu)
+    if (props.selected) {
+      this.element.classList.add('selected')
+    }
+
+    this.selected = props.selected
+    this.onclick = props.onclick
+    this.oncontextmenu = props.oncontextmenu
+    etch.getScheduler().updateDocument(this.scrollIntoViewIfNeeded.bind(this))
+  }
+
+  scrollIntoViewIfNeeded() {
+    if (this.selected) {
+      this.element.scrollIntoViewIfNeeded(false)
+    }
+  }
+}
+
+module.exports = SelectListView

package/select.less

@@ -0,0 +1,53 @@
+.select-list-query-row {
+  position: relative;
+  .select-list-help-toggle {
+    position: absolute;
+    right: 8px;
+    top: 50%;
+    transform: translateY(-50%);
+    cursor: pointer;
+    opacity: 0.5;
+    z-index: 1;
+    &:hover {
+      opacity: 1;
+    }
+  }
+}
+
+.select-list .list-group {
+  overflow-x: hidden;
+}
+
+.select-list .empty-message {
+  color: @text-color-info;
+  margin-top: 10px;
+}
+
+.select-list .error-message {
+  color: @text-color-error;
+  margin-top: 10px;
+}
+
+.select-list .loading {
+  display: flex;
+  align-items: center;
+}
+
+.select-list .keystroke {
+  border: solid 1px;
+  padding: .2em .4em;
+  border-radius: 4px;
+}
+
+.select-list .help-message {
+  p, ul, ol {
+    margin: 0;
+  }
+  ul, ol {
+    padding-left: 1.5em;
+  }
+  .help-note {
+    color: @text-color-subtle;
+    font-size: 0.9em;
+  }
+}