feat(module): show descriptions and highlight matches while searching

Author: danielroe

packages/nuxt-cli/src/commands/module/_autocomplete.ts

@@ -1,6 +1,9 @@
 import type { Option } from '@clack/prompts'
 import type { NuxtModule } from './_utils'
 
+import process from 'node:process'
+
+import { styleText } from 'node:util'
 import { autocompleteMultiselect, isCancel } from '@clack/prompts'
 import fuzzysort from 'fuzzysort'
 import { hasTTY } from 'std-env'
@@ -9,6 +12,15 @@ import { logger } from '../../utils/logger'
 
 const TRAILING_DOT_RE = /\.$/
 
+/**
+ * Clack wraps each row at the terminal width less its `│  ` guide, and the row
+ * itself opens with `◻ `; the last two columns are the gap this file puts
+ * between the name and the description.
+ */
+const ROW_PREFIX_WIDTH = 3 + 2 + 2
+/** Below this there is no room left for a description worth reading. */
+const MIN_DESCRIPTION_WIDTH = 24
+
 interface AutocompleteOptions {
   modules: NuxtModule[]
   message?: string
@@ -42,11 +54,38 @@ export async function selectModulesAutocomplete(options: AutocompleteOptions): P
     category: fuzzysort.prepare(m.category),
   }))
 
-  const clackOptions: Option<string>[] = sortedModules.map(m => ({
-    value: m.npm,
-    label: m.npm,
-    hint: m.description.replace(TRAILING_DOT_RE, ''),
-  }))
+  /**
+   * Clack only renders `hint` for the focused row, so the description lives in
+   * the label instead and every row keeps it. Widths are measured on the plain
+   * text: clack hard-wraps each row, and a label that overflows the terminal
+   * costs a second line and half the visible list.
+   */
+  function buildOptions(search: string): Option<string>[] {
+    const room = (process.stdout.columns || 80) - ROW_PREFIX_WIDTH
+    return sortedModules.map((m) => {
+      const match = search ? fuzzysort.single(search, m.npm) : undefined
+      const name = match ? match.highlight(part => styleText('underline', part)).join('') : m.npm
+      const description = m.description.replace(TRAILING_DOT_RE, '')
+      const available = room - m.npm.length
+      if (!description || available < MIN_DESCRIPTION_WIDTH) {
+        return { value: m.npm, label: name }
+      }
+      const truncated = description.length > available
+        ? `${description.slice(0, available - 1).trimEnd()}…`
+        : description
+      return { value: m.npm, label: `${name}  ${styleText('dim', truncated)}` }
+    })
+  }
+
+  /**
+   * `userInput` carries the text typed so far but is not on clack's public
+   * prompt type, so a missing or renamed field degrades to unhighlighted rows
+   * rather than throwing.
+   */
+  function currentSearch(prompt: unknown): string {
+    const input = (prompt as { userInput?: unknown }).userInput
+    return typeof input === 'string' ? input : ''
+  }
 
   const matches = new Map<string, Set<string>>()
   const filter = (search: string, option: Option<string>): boolean => {
@@ -62,7 +101,9 @@ export async function selectModulesAutocomplete(options: AutocompleteOptions): P
 
   const result = await autocompleteMultiselect({
     message,
-    options: clackOptions,
+    options() {
+      return buildOptions(currentSearch(this))
+    },
     filter,
     required: false,
   })

packages/nuxt-cli/test/unit/commands/module/_autocomplete.spec.ts

@@ -1,5 +1,7 @@
 import type { NuxtModule } from '../../../../src/commands/module/_utils'
 
+import { stripVTControlCharacters as stripAnsi } from 'node:util'
+
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 // Mock std-env before importing the module
@@ -125,7 +127,7 @@ describe('selectModulesAutocomplete', () => {
       let capturedOptions: any[] = []
 
       mockAutocompleteMultiselect.mockImplementation(async (opts: any) => {
-        capturedOptions = opts.options
+        capturedOptions = opts.options.call({ userInput: '' })
         return []
       })
 
@@ -345,7 +347,7 @@ describe('selectModulesAutocomplete', () => {
 
       let capturedOptions: any[] = []
       mockAutocompleteMultiselect.mockImplementation(async (opts: any) => {
-        capturedOptions = opts.options
+        capturedOptions = opts.options.call({ userInput: '' })
         return []
       })
 
@@ -357,9 +359,82 @@ describe('selectModulesAutocomplete', () => {
 
       expect(capturedOptions[0]).toEqual({
         value: '@nuxt/test',
-        label: '@nuxt/test',
-        hint: 'A test module', // trailing period removed
+        label: expect.stringContaining('@nuxt/test'),
+      })
+      // trailing period removed
+      expect(stripAnsi(capturedOptions[0].label)).toBe('@nuxt/test  A test module')
+    })
+
+    it('should show a description on every option, not only the focused one', async () => {
+      vi.doMock('std-env', () => ({
+        hasTTY: true,
+      }))
+
+      let capturedOptions: any[] = []
+      mockAutocompleteMultiselect.mockImplementation(async (opts: any) => {
+        capturedOptions = opts.options.call({ userInput: '' })
+        return []
+      })
+
+      const { selectModulesAutocomplete } = await import('../../../../src/commands/module/_autocomplete')
+
+      await selectModulesAutocomplete({
+        modules: [
+          createMockModule({ npm: '@nuxt/one', description: 'First module' }),
+          createMockModule({ npm: '@nuxt/two', description: 'Second module' }),
+        ],
+      })
+
+      expect(capturedOptions.map((o: any) => stripAnsi(o.label))).toEqual([
+        '@nuxt/one  First module',
+        '@nuxt/two  Second module',
+      ])
+      expect(capturedOptions.every((o: any) => o.hint === undefined)).toBe(true)
+    })
+
+    it('should highlight the matched part of the name as the user types', async () => {
+      vi.doMock('std-env', () => ({
+        hasTTY: true,
+      }))
+
+      let capturedOptions: any[] = []
+      mockAutocompleteMultiselect.mockImplementation(async (opts: any) => {
+        capturedOptions = opts.options.call({ userInput: 'img' })
+        return []
+      })
+
+      const { selectModulesAutocomplete } = await import('../../../../src/commands/module/_autocomplete')
+
+      await selectModulesAutocomplete({
+        modules: [createMockModule({ npm: '@nuxt/image', description: 'Images' })],
+      })
+
+      expect(capturedOptions[0].label).not.toBe(stripAnsi(capturedOptions[0].label))
+      expect(stripAnsi(capturedOptions[0].label)).toBe('@nuxt/image  Images')
+    })
+
+    it('should truncate descriptions to the terminal width', async () => {
+      vi.doMock('std-env', () => ({
+        hasTTY: true,
+      }))
+
+      Object.defineProperty(process.stdout, 'columns', { value: 60, writable: true, configurable: true })
+
+      let capturedOptions: any[] = []
+      mockAutocompleteMultiselect.mockImplementation(async (opts: any) => {
+        capturedOptions = opts.options.call({ userInput: '' })
+        return []
       })
+
+      const { selectModulesAutocomplete } = await import('../../../../src/commands/module/_autocomplete')
+
+      await selectModulesAutocomplete({
+        modules: [createMockModule({ npm: '@nuxt/test', description: 'A'.repeat(200) })],
+      })
+
+      const label = stripAnsi(capturedOptions[0].label)
+      expect(label.length).toBeLessThanOrEqual(60 - 5)
+      expect(label.endsWith('…')).toBe(true)
     })
 
     it('should set required to false', async () => {