diff --git a/package.json b/package.json
index 73a14aa7f41..fed945b6fdc 100644
--- a/package.json
+++ b/package.json
@@ -98,7 +98,20 @@
"printWidth": 120
},
"version": "0.0.0",
+ "packageExtensionsNotes": {
+ "@json-render/ink@0.19.0": "The published manifest omits its zod runtime dependency; pinning zod 4 prevents Ink from resolving zod 3 while core uses zod 4."
+ },
"pnpm": {
+ "overrides": {
+ "@types/react": "18.3.12"
+ },
+ "packageExtensions": {
+ "@json-render/ink@0.19.0": {
+ "dependencies": {
+ "zod": "^4.3.6"
+ }
+ }
+ },
"peerDependencyRules": {
"allowedVersions": {
"@shopify/cli-hydrogen>@graphql-codegen/cli": "6.0.1",
diff --git a/packages/cli-kit/src/private/node/ui/components/DescriptionPanel.tsx b/packages/cli-kit/src/private/node/ui/components/DescriptionPanel.tsx
new file mode 100644
index 00000000000..795dc4276f9
--- /dev/null
+++ b/packages/cli-kit/src/private/node/ui/components/DescriptionPanel.tsx
@@ -0,0 +1,46 @@
+import React from 'react'
+import {Box, Text} from 'ink'
+
+// Minimum readable width (in columns) for the description panel when placed beside the list.
+// Below this the panel is stacked under the list instead. Shared by SelectInput and
+// MultiSelectInput so both make the same responsive decision.
+export const MIN_SIDE_PANEL_WIDTH = 24
+
+export interface DescriptionPanelProps {
+ /**
+ * Optional bold heading shown above the description (typically the highlighted item's label).
+ */
+ title?: string
+ /**
+ * The description text to show. Wrapped within the panel width and clipped to `maxLines`.
+ */
+ description?: string
+ /**
+ * Width of the panel in columns. Includes the panel's left padding.
+ */
+ width: number
+ /**
+ * Maximum number of physical lines the panel may occupy. The panel always reserves this
+ * height so the surrounding layout stays stable while the highlighted item changes, and any
+ * overflow is clipped to keep the total render height within the viewport.
+ */
+ maxLines: number
+}
+
+/**
+ * A responsive, height-bounded panel that shows the description of the currently highlighted
+ * item beside or below a `SelectInput`/`MultiSelectInput` list. Kept intentionally small and
+ * self-contained so both selection components can share it.
+ */
+export function DescriptionPanel({title, description, width, maxLines}: DescriptionPanelProps): React.ReactElement {
+ return (
+
+ {title ? (
+
+ {title}
+
+ ) : null}
+ {description ? {description} : null}
+
+ )
+}
diff --git a/packages/cli-kit/src/private/node/ui/components/MultiSelectInput.description.test.tsx b/packages/cli-kit/src/private/node/ui/components/MultiSelectInput.description.test.tsx
new file mode 100644
index 00000000000..4ac0417db0e
--- /dev/null
+++ b/packages/cli-kit/src/private/node/ui/components/MultiSelectInput.description.test.tsx
@@ -0,0 +1,339 @@
+import {MultiSelectInput} from './MultiSelectInput.js'
+import {render, waitForInputsToBeReady} from '../../testing/ui.js'
+import {Stdout} from '../../ui.js'
+import {unstyled} from '../../../../public/node/output.js'
+import {describe, expect, test} from 'vitest'
+
+import React from 'react'
+
+const ARROW_DOWN = '[B'
+
+// Ink parses CSI Z (ESC [ Z, "back-tab") as Shift+Tab, which TextInput deliberately ignores, so it
+// is the free toggle key for the full-description overlay.
+const SHIFT_TAB = '[Z'
+
+// The default testing `render` helper hard-codes an 80/100-column stdout and reads frames from an
+// internal stdout instance. To exercise the responsive description panel we need to control the
+// terminal width and read frames from the same stdout that drives `useLayout`, so we pass our own
+// width-controlled Stdout and read its frames directly.
+function renderWithWidth(tree: React.ReactElement, columns: number) {
+ const stdout = new Stdout({columns, rows: 100})
+ const renderInstance = render(tree, {stdout: stdout as unknown as NodeJS.WriteStream})
+ return {renderInstance, stdout}
+}
+
+function lastUnstyledFrame(stdout: Stdout): string {
+ return unstyled(stdout.lastFrame() ?? '')
+}
+
+// Waits until the width-controlled stdout produces a frame different from the current one after
+// running `action`, then yields once more so React's scheduler can flush follow-up effects.
+async function sendAndWaitForFrameChange(stdout: Stdout, action: () => void) {
+ const initialFrame = stdout.lastFrame()
+ action()
+ while (stdout.lastFrame() === initialFrame) {
+ // eslint-disable-next-line no-await-in-loop
+ await new Promise((resolve) => setImmediate(() => setTimeout(resolve, 0)))
+ }
+ await new Promise((resolve) => setImmediate(() => setTimeout(resolve, 0)))
+}
+
+// Physical rows the stacked hint (preview line + its gap) reserves out of the list budget. Mirror
+// of `STACKED_HINT_RESERVE` in MultiSelectInput.tsx (not exported, kept in sync deliberately).
+const STACKED_HINT_RESERVE = 2
+
+const itemsWithDescriptions = [
+ {label: 'read_products', value: 'read_products', description: 'Read-only access to products.'},
+ {label: 'read_orders', value: 'read_orders', description: 'Read-only access to orders.'},
+ {label: 'read_customers', value: 'read_customers', description: 'Read-only access to customers.'},
+]
+
+describe('MultiSelectInput with descriptions', () => {
+ test('shows the focused item description in a panel', async () => {
+ const {stdout} = renderWithWidth( {}} />, 120)
+
+ await waitForInputsToBeReady()
+
+ const frame = lastUnstyledFrame(stdout)
+ expect(frame).toContain('Read-only access to products.')
+ // The other items' descriptions are not shown until they become focused.
+ expect(frame).not.toContain('Read-only access to orders.')
+ })
+
+ test('updates the shown description when arrowing focus', async () => {
+ const {renderInstance, stdout} = renderWithWidth(
+ {}} />,
+ 120,
+ )
+
+ await waitForInputsToBeReady()
+ await sendAndWaitForFrameChange(stdout, () => renderInstance.stdin.write(ARROW_DOWN))
+
+ const frame = lastUnstyledFrame(stdout)
+ expect(frame).toContain('Read-only access to orders.')
+ expect(frame).not.toContain('Read-only access to products.')
+ })
+
+ test('places the panel beside the list on wide terminals and below on narrow ones', async () => {
+ const description = 'Read-only access to products.'
+
+ const {stdout: wideStdout} = renderWithWidth(
+ {}} />,
+ 120,
+ )
+ const {stdout: narrowStdout} = renderWithWidth(
+ {}} />,
+ 80,
+ )
+
+ await waitForInputsToBeReady()
+
+ const wideLines = lastUnstyledFrame(wideStdout).split('\n')
+ const narrowLines = lastUnstyledFrame(narrowStdout).split('\n')
+
+ const wideDescriptionLine = wideLines.findIndex((line) => line.includes(description))
+ const narrowDescriptionLine = narrowLines.findIndex((line) => line.includes(description))
+
+ // Side-by-side: the description sits on one of the first rows, aligned with the list.
+ // Stacked: the description appears only after all three list rows.
+ expect(wideDescriptionLine).toBeLessThan(3)
+ expect(narrowDescriptionLine).toBeGreaterThanOrEqual(3)
+
+ // When beside, the focused label appears twice on the same physical line: once as the list row
+ // and once as the panel title.
+ expect(wideLines[wideDescriptionLine - 1]).toContain('read_products')
+ })
+
+ test('truncates long labels to a single physical line', async () => {
+ const longLabelItems = [
+ {
+ label: `read_products ${'very-long-suffix '.repeat(20)}`.trim(),
+ value: 'read_products',
+ description: 'Read-only access to products.',
+ },
+ {label: 'read_orders', value: 'read_orders', description: 'Read-only access to orders.'},
+ ]
+
+ const {stdout} = renderWithWidth( {}} />, 120)
+
+ await waitForInputsToBeReady()
+
+ const frame = lastUnstyledFrame(stdout)
+ // The row is clipped with an ellipsis and the full label never appears in one piece.
+ expect(frame).toContain('…')
+ expect(frame).not.toContain(longLabelItems[0]!.label)
+ })
+
+ test('keeps a stable render height while scrolling through long descriptions (ghosting fix)', async () => {
+ const manyLongItems = Array.from({length: 12}, (_, index) => ({
+ label: `scope:${index}`,
+ value: `scope-${index}`,
+ description: `A very long description for scope ${index} that would previously wrap onto ${'multiple '.repeat(
+ 8,
+ )}physical lines and cause ghosting when scrolling.`,
+ }))
+
+ const {renderInstance, stdout} = renderWithWidth(
+ {}} availableLines={6} />,
+ 120,
+ )
+
+ await waitForInputsToBeReady()
+ const initialLineCount = lastUnstyledFrame(stdout).split('\n').length
+
+ // Arrowing down repeatedly must not grow the rendered block: single-line rows keep the true
+ // height equal to the option count, so nothing overflows the viewport and prior frames are
+ // fully erased.
+ for (let step = 0; step < 8; step++) {
+ // eslint-disable-next-line no-await-in-loop
+ await sendAndWaitForFrameChange(stdout, () => renderInstance.stdin.write(ARROW_DOWN))
+ expect(lastUnstyledFrame(stdout).split('\n').length).toBe(initialLineCount)
+ }
+ })
+
+ test('renders no panel and no truncation when no item has a description', async () => {
+ const items = [
+ {label: 'read_products', value: 'read_products'},
+ {label: 'read_orders', value: 'read_orders'},
+ {label: 'read_customers', value: 'read_customers'},
+ ]
+
+ const {stdout} = renderWithWidth( {}} />, 120)
+
+ await waitForInputsToBeReady()
+
+ const frame = lastUnstyledFrame(stdout)
+ expect(frame).not.toContain('…')
+ expect(frame).toContain('read_products')
+ expect(frame).toContain('read_orders')
+ expect(frame).toContain('read_customers')
+ })
+
+ test('truncates a long group title to a single physical line', async () => {
+ // Long enough to wrap to several rows if it were not truncated. No descriptions here on purpose:
+ // group-title truncation is unconditional, not gated on the descriptions feature.
+ const longGroupTitle = `Group ${'segment-'.repeat(30)}`.trim()
+ const groupedItems = [
+ {label: 'alpha', value: 'alpha', group: longGroupTitle},
+ {label: 'beta', value: 'beta', group: longGroupTitle},
+ ]
+
+ const {stdout} = renderWithWidth( {}} />, 80)
+
+ await waitForInputsToBeReady()
+
+ const lines = lastUnstyledFrame(stdout).split('\n')
+ // If the title wrapped, more than one physical line would carry a chunk of it.
+ const titleLines = lines.filter((line) => line.includes('segment-'))
+ expect(titleLines).toHaveLength(1)
+ expect(lastUnstyledFrame(stdout)).toContain('…')
+ // The option rows below the title are still visible (not clipped by an overflowing title).
+ expect(lastUnstyledFrame(stdout)).toContain('alpha')
+ expect(lastUnstyledFrame(stdout)).toContain('beta')
+ })
+
+ test('keeps the stacked layout within the vertical budget while scrolling', async () => {
+ const manyLongItems = Array.from({length: 12}, (_, index) => ({
+ label: `scope:${index}`,
+ value: `scope-${index}`,
+ description: `Long description ${index} ${'word '.repeat(30)}`.trim(),
+ }))
+
+ // Narrow width forces the stacked layout; a small budget is where the old code overflowed.
+ const {renderInstance, stdout} = renderWithWidth(
+ {}} availableLines={6} />,
+ 80,
+ )
+
+ await waitForInputsToBeReady()
+ const initialLineCount = lastUnstyledFrame(stdout).split('\n').length
+
+ // The stacked hint is reserved out of the list budget, so the whole block stays small and, more
+ // importantly, its height never grows as focus moves (which is what caused vertical ghosting).
+ expect(initialLineCount).toBeLessThanOrEqual(10)
+ for (let step = 0; step < 8; step++) {
+ // eslint-disable-next-line no-await-in-loop
+ await sendAndWaitForFrameChange(stdout, () => renderInstance.stdin.write(ARROW_DOWN))
+ expect(lastUnstyledFrame(stdout).split('\n').length).toBe(initialLineCount)
+ }
+ })
+
+ // Derive the rendered list height from a stacked-layout frame. The frame lays out as:
+ // [list rows … (sectionHeight)] [gap] [preview line] [gap] [footer]
+ // so the list height is the index of the preview line minus the one gap row above it.
+ function stackedListHeight(frame: string): number {
+ const lines = frame.split('\n')
+ const previewIndex = lines.findIndex((line) => line.includes('Long description'))
+ return previewIndex - 1
+ }
+
+ // Regression for R1: in the STACKED description layout a grouped list has `minHeight = 5`, which
+ // used to override the reduced list budget so `sectionHeight + gap + preview` overflowed the
+ // viewport (reintroducing vertical ghosting). The hard-ceiling clamp guarantees the exact
+ // invariant `listHeight + STACKED_HINT_RESERVE <= availableLines`. Pre-fix the list height was
+ // pinned at 5, so `5 + 2 = 7` blew both the 3- and 6-row budgets.
+ for (const availableLines of [3, 6]) {
+ test(`keeps a grouped stacked list within the vertical budget (availableLines=${availableLines})`, async () => {
+ const groupedItems = Array.from({length: 8}, (_, index) => ({
+ label: `scope:${index}`,
+ value: `scope-${index}`,
+ group: index % 2 === 0 ? 'Group A' : 'Group B',
+ description: `Long description ${index} ${'word '.repeat(30)}`.trim(),
+ }))
+
+ // Width 80 forces the stacked layout; grouped items give `minHeight = 5`, the pre-fix floor.
+ const {renderInstance, stdout} = renderWithWidth(
+ {}} availableLines={availableLines} />,
+ 80,
+ )
+
+ await waitForInputsToBeReady()
+
+ expect(stackedListHeight(lastUnstyledFrame(stdout)) + STACKED_HINT_RESERVE).toBeLessThanOrEqual(availableLines)
+
+ // Arrow down to the last item (length - 1 presses); a further down-arrow at the end is a
+ // no-op that would never produce a new frame. On every frame the budget invariant must hold
+ // and the block height must never grow (no ghosting).
+ const initialLineCount = lastUnstyledFrame(stdout).split('\n').length
+ for (let step = 0; step < groupedItems.length - 1; step++) {
+ // eslint-disable-next-line no-await-in-loop
+ await sendAndWaitForFrameChange(stdout, () => renderInstance.stdin.write(ARROW_DOWN))
+ expect(stackedListHeight(lastUnstyledFrame(stdout)) + STACKED_HINT_RESERVE).toBeLessThanOrEqual(availableLines)
+ expect(lastUnstyledFrame(stdout).split('\n').length).toBe(initialLineCount)
+ }
+ })
+ }
+
+ // Regression for R2 (shared `useSelectState`): a WIDTH-only resize that crosses the panel
+ // breakpoint changes `visibleOptionCount` without changing the option set. The hook must preserve
+ // the focused item instead of resetting focus to the first item.
+ test('preserves the focused item across a width-only resize (beside↔stacked)', async () => {
+ const items = Array.from({length: 8}, (_, index) => ({
+ label: `scope:${index}`,
+ value: `scope-${index}`,
+ description: `Unique description number ${index} for scope ${index}.`,
+ }))
+
+ // availableLines=6 keeps `limit` below the item count and makes it differ between stacked (4
+ // rows) and beside (6 rows), so crossing the breakpoint genuinely changes visibleOptionCount.
+ const stdout = new Stdout({columns: 80, rows: 100})
+ const renderInstance = render( {}} />, {
+ stdout: stdout as unknown as NodeJS.WriteStream,
+ })
+
+ await waitForInputsToBeReady()
+
+ // Focus scope-5 (scrolls the window in the narrow/stacked layout).
+ for (let step = 0; step < 5; step++) {
+ // eslint-disable-next-line no-await-in-loop
+ await sendAndWaitForFrameChange(stdout, () => renderInstance.stdin.write(ARROW_DOWN))
+ }
+ expect(lastUnstyledFrame(stdout)).toContain('Unique description number 5')
+
+ // Widen past the beside breakpoint: layout flips to the side panel and visibleOptionCount grows.
+ await sendAndWaitForFrameChange(stdout, () => {
+ stdout.columns = 120
+ stdout.emit('resize')
+ })
+
+ const afterResize = lastUnstyledFrame(stdout)
+ // Focus (and thus the shown description) must still be scope-5, NOT reset to item 0.
+ expect(afterResize).toContain('Unique description number 5')
+ expect(afterResize).not.toContain('Unique description number 0')
+ })
+
+ test('Shift+Tab toggles a full-description takeover', async () => {
+ // Long enough that the compact preview must truncate before the sentinel token at the end.
+ const longDescription =
+ 'This description begins here and then continues far past a single terminal line so the compact ' +
+ 'preview has to truncate it, right up to the sentinel token OMEGA_END_TOKEN.'
+ const items = [
+ {label: 'read_products', value: 'read_products', description: longDescription},
+ {label: 'read_orders', value: 'read_orders', description: 'Read-only access to orders.'},
+ ]
+
+ const {renderInstance, stdout} = renderWithWidth( {}} />, 80)
+
+ await waitForInputsToBeReady()
+
+ // The footer can wrap on narrow terminals, so normalize whitespace before matching the hint.
+ const normalizeWhitespace = (frame: string) => frame.replace(/\s+/g, ' ')
+
+ const before = lastUnstyledFrame(stdout)
+ // Compact preview: hint present, sentinel truncated away.
+ expect(normalizeWhitespace(before)).toContain('⇧⇥ full description')
+ expect(before).not.toContain('OMEGA_END_TOKEN')
+
+ await sendAndWaitForFrameChange(stdout, () => renderInstance.stdin.write(SHIFT_TAB))
+ const overlay = lastUnstyledFrame(stdout)
+ // Takeover: the full text (including the sentinel) is now shown, with a back hint.
+ expect(overlay).toContain('OMEGA_END_TOKEN')
+ expect(overlay).toContain('Press ⇧⇥ to go back.')
+
+ await sendAndWaitForFrameChange(stdout, () => renderInstance.stdin.write(SHIFT_TAB))
+ const after = lastUnstyledFrame(stdout)
+ // Back to the list: sentinel hidden again, discoverability hint restored.
+ expect(after).not.toContain('OMEGA_END_TOKEN')
+ expect(normalizeWhitespace(after)).toContain('⇧⇥ full description')
+ })
+})
diff --git a/packages/cli-kit/src/private/node/ui/components/MultiSelectInput.tsx b/packages/cli-kit/src/private/node/ui/components/MultiSelectInput.tsx
new file mode 100644
index 00000000000..a3cbe91fc3b
--- /dev/null
+++ b/packages/cli-kit/src/private/node/ui/components/MultiSelectInput.tsx
@@ -0,0 +1,391 @@
+import {Item} from './SelectInput.js'
+import {Scrollbar} from './Scrollbar.js'
+import {DescriptionPanel, MIN_SIDE_PANEL_WIDTH} from './DescriptionPanel.js'
+import {handleCtrlC} from '../../ui.js'
+import useLayout from '../hooks/use-layout.js'
+import {useSelectState} from '../hooks/use-select-state.js'
+import React, {useCallback, useState} from 'react'
+import {Box, Key, useInput, Text, DOMElement} from 'ink'
+import figures from 'figures'
+import sortBy from 'lodash/sortBy.js'
+
+export interface MultiSelectInputProps {
+ items: Item[]
+ initialItems?: Item[]
+ focus?: boolean
+ emptyMessage?: string
+ defaultValue?: T[]
+ availableLines?: number
+ onSubmit?: (items: Item[]) => void
+ inputFixedAreaRef?: React.Ref
+ ref?: React.Ref
+ groupOrder?: string[]
+}
+
+interface MultiSelectItemProps {
+ item: Item
+ previousItem: Item | undefined
+ items: Item[]
+ isFocused: boolean
+ isSelected: boolean
+ hasAnyGroup: boolean
+ index: number
+ singleLine: boolean
+}
+
+function MultiSelectItem({
+ item,
+ previousItem,
+ isFocused,
+ isSelected,
+ items,
+ hasAnyGroup,
+ index,
+ singleLine,
+}: MultiSelectItemProps): React.ReactElement {
+ let title: string | undefined
+ let labelColor
+
+ if (isFocused) {
+ labelColor = 'cyan'
+ } else if (item.disabled) {
+ labelColor = 'dim'
+ }
+
+ if (typeof previousItem === 'undefined' || item.group !== previousItem.group) {
+ title = item.group ?? (hasAnyGroup ? 'Other' : undefined)
+ }
+
+ const checkbox = isSelected ? figures.checkboxOn : figures.checkboxOff
+
+ return (
+
+ {title ? (
+ // Always keep the group title on a single physical line. Without this, a long title wraps to
+ // 2+ rows, but `minHeight={title ? 2 : 1}` and `maximumLinesLostToGroups()` both assume a
+ // one-line title, so the `overflowY="hidden"` list box would clip the focused option row.
+ // The title Box stretches to the list column width, so `truncate-end` has a bound to clip to.
+
+
+ {title}
+
+
+ ) : null}
+
+
+ {isFocused ? {`>`} : }
+
+ {checkbox}
+
+ {/* When descriptions are active, keep every row to exactly one physical line so the list's
+ true height equals the option count (what the scrollbar/sectionHeight already assume),
+ which is what prevents the wrapped-row ghosting bug. Otherwise preserve the original
+ wrapping behavior byte-for-byte. */}
+
+ {item.label}
+
+
+
+ )
+}
+
+const MAX_AVAILABLE_LINES = 25
+
+// Physical rows the stacked description hint (+ its gap) occupies below the list. Reserved out of
+// the list's vertical budget so the list never fills the whole budget and then pushes the hint past
+// the viewport (which reintroduced the vertical ghosting bug).
+const STACKED_HINT_RESERVE = 2
+
+function MultiSelectInput({
+ items: rawItems,
+ initialItems = rawItems,
+ focus = true,
+ emptyMessage = 'No items to select.',
+ defaultValue,
+ availableLines = MAX_AVAILABLE_LINES,
+ onSubmit,
+ inputFixedAreaRef,
+ ref,
+ groupOrder,
+}: MultiSelectInputProps): React.ReactElement | null {
+ let noItems = false
+
+ if (rawItems.length === 0) {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any, no-param-reassign
+ rawItems = [{label: emptyMessage, value: null as any, disabled: true}]
+ noItems = true
+ }
+
+ const hasAnyGroup = rawItems.some((item) => typeof item.group !== 'undefined')
+ const items = sortBy(rawItems, (item) => {
+ // Items without groups ("Other") always go last
+ if (!item.group) return Number.MAX_SAFE_INTEGER + 1
+ // If no groupOrder specified, use default behavior
+ if (!groupOrder) return Number.MAX_SAFE_INTEGER
+ // Items with groups get their position from groupOrder, or MAX_SAFE_INTEGER if not specified
+ const index = groupOrder.indexOf(item.group)
+ return index === -1 ? Number.MAX_SAFE_INTEGER : index
+ })
+
+ // The set of values the user has toggled on. Selecting zero items is valid,
+ // so this can legitimately be empty when the prompt is submitted.
+ const [selectedValues, setSelectedValues] = useState>(() => new Set(defaultValue ?? []))
+
+ const availableLinesToUse = Math.min(availableLines, MAX_AVAILABLE_LINES)
+
+ const {fullWidth, twoThirds} = useLayout()
+
+ // The description panel is opt-in: it only activates when at least one item provides a
+ // description. When it does, rows become single-line/truncated and the focused item's
+ // description is shown in a panel. In a multi-select the panel follows FOCUS (the `>` cursor),
+ // not the set of toggled selections.
+ const descriptionsEnabled = items.some((item) => (item.description?.length ?? 0) > 0)
+
+ // useLayout clamps both `twoThirds` and `oneThird` up to a minimum of 80 columns, so they can't
+ // be placed side-by-side on typical terminals without overflowing (which would reintroduce the
+ // wrapped-row ghosting). Instead, keep the list at `twoThirds` and give the panel exactly the
+ // remaining width, so the two columns always sum to `fullWidth`. Only place the panel beside the
+ // list when that remainder is wide enough to be readable; otherwise stack it below.
+ const sidePanelWidth = fullWidth - twoThirds
+ const showDescriptionBeside = descriptionsEnabled && sidePanelWidth >= MIN_SIDE_PANEL_WIDTH
+
+ // `availableLines` is the real remaining vertical budget above the footer (see
+ // Prompts/PromptLayout.tsx). Only the STACKED description case adds a line (+ gap) *below* the
+ // list, so in that case we shrink the budget the list sizes itself against; otherwise the list
+ // would fill the whole budget and then push the stacked hint past the viewport, reintroducing the
+ // vertical ghosting bug. The beside/wide panel is side-by-side and costs no vertical rows, and the
+ // no-description path keeps the full budget, so both stay byte-for-byte unchanged.
+ const listAvailableLines =
+ descriptionsEnabled && !showDescriptionBeside
+ ? Math.max(2, availableLinesToUse - STACKED_HINT_RESERVE)
+ : availableLinesToUse
+
+ function maximumLinesLostToGroups(items: Item[]): number {
+ // Calculate a safe estimate of the limit needed based on the space available
+ const numberOfGroups = new Set(items.map((item) => item.group).filter((group) => group)).size
+ // Add 1 to numberOfGroups because we also have a default Other group
+ const maxVisibleGroups = Math.ceil(Math.min((listAvailableLines + 1) / 3, numberOfGroups + 1))
+ // If we have x visible groups, we lose 1 line to the first group + 2 lines to the rest
+ return numberOfGroups > 0 ? (maxVisibleGroups - 1) * 2 + 1 : 0
+ }
+
+ const maxLinesLostToGroups = maximumLinesLostToGroups(items)
+ const limit = Math.max(2, listAvailableLines - maxLinesLostToGroups)
+ const hasLimit = items.length > limit
+
+ const state = useSelectState({
+ visibleOptionCount: limit,
+ options: items,
+ defaultValue: undefined,
+ })
+
+ // The panel follows FOCUS (the `>` cursor / `state.value`), not the toggled selection set.
+ const highlightedItem = descriptionsEnabled ? items.find((item) => item.value === state.value) : undefined
+
+ // Shift+Tab toggles a full-screen "detail" takeover of the focused item's description. It is only
+ // meaningful when descriptions are on and the focused item actually has one.
+ const [showFullDescription, setShowFullDescription] = useState(false)
+
+ const handleArrows = (key: Key) => {
+ if (key.upArrow) {
+ state.selectPreviousOption()
+ } else if (key.downArrow) {
+ state.selectNextOption()
+ }
+ }
+
+ const toggleFocusedOption = useCallback(() => {
+ if (typeof state.value === 'undefined') {
+ return
+ }
+
+ const focusedItem = items.find((item) => item.value === state.value)
+
+ if (!focusedItem || focusedItem.disabled) {
+ return
+ }
+
+ setSelectedValues((previousValues) => {
+ const nextValues = new Set(previousValues)
+
+ if (nextValues.has(focusedItem.value)) {
+ nextValues.delete(focusedItem.value)
+ } else {
+ nextValues.add(focusedItem.value)
+ }
+
+ return nextValues
+ })
+ }, [items, state.value])
+
+ useInput(
+ (input, key) => {
+ handleCtrlC(input, key)
+
+ // Shift+Tab toggles the full-description takeover. TextInput ignores this exact combo, so it
+ // is free to reuse across autocomplete/select/multi-select. Only react when there is a
+ // description to show; otherwise leave the key alone.
+ if (key.shift && key.tab) {
+ if (descriptionsEnabled && (highlightedItem?.description?.length ?? 0) > 0) {
+ setShowFullDescription((previous) => !previous)
+ }
+ return
+ }
+
+ if (key.return) {
+ if (onSubmit && !noItems) {
+ // Resolve in the order the choices were declared, not the order the
+ // user toggled them nor the group-sorted display order. `items` is
+ // sorted by group, so we filter `initialItems` (the original,
+ // declared-order choices) to honour the stable-result contract.
+ onSubmit(initialItems.filter((item) => selectedValues.has(item.value)))
+ }
+ return
+ }
+
+ // Space toggles the focused option. Guard against other modifiers so we
+ // don't toggle when e.g. shift or control is held.
+ if (input === ' ' && Object.values(key).every((value) => !value)) {
+ toggleFocusedOption()
+ } else {
+ handleArrows(key)
+ }
+ },
+ {isActive: focus},
+ )
+
+ const optionsHeight = initialItems.length + maximumLinesLostToGroups(initialItems)
+ const minHeight = hasAnyGroup ? 5 : 2
+ let sectionHeight = Math.max(minHeight, Math.min(listAvailableLines, optionsHeight))
+
+ // STACKED description case only: the preview line (+ its gap) render *below* the list, so the
+ // list plus that reserve must fit the real vertical budget. Treat the reserve as a HARD CEILING
+ // and clamp AFTER the `minHeight` floor — otherwise a grouped list (`minHeight=5`) in a small
+ // budget would push `sectionHeight + gap + preview` past the viewport and reintroduce the
+ // vertical ghosting the reserve was meant to prevent. A tiny budget may show fewer rows / scroll
+ // more; that tradeoff is accepted. `Math.max(1, …)` only guards against a non-positive height on
+ // a pathologically short terminal — real terminals are ≥24 rows. The no-description and beside
+ // paths are gated out here, so they stay byte-for-byte unchanged.
+ if (descriptionsEnabled && !showDescriptionBeside) {
+ sectionHeight = Math.min(sectionHeight, Math.max(1, availableLinesToUse - STACKED_HINT_RESERVE))
+ }
+
+ const listSection = (
+
+
+ {state.visibleOptions.map((item: Item, index: number) => (
+
+ ))}
+
+
+ {hasLimit ? (
+
+ ) : null}
+
+ )
+
+ const footer = (
+
+ {noItems ? (
+
+ Try again with a different keyword.
+
+ ) : (
+
+
+ {`Press ${figures.arrowUp}${figures.arrowDown} arrows to select, space to toggle, enter to confirm.${
+ descriptionsEnabled ? ' · ⇧⇥ full description' : ''
+ }`}
+
+
+ )}
+
+ )
+
+ // Shift+Tab takeover: replace the list + hint with the focused item's full description. Arrows
+ // still navigate underneath, so this updates live as the focused item changes.
+ if (descriptionsEnabled && showFullDescription && (highlightedItem?.description?.length ?? 0) > 0) {
+ const overlayWidth = showDescriptionBeside ? fullWidth : twoThirds
+ return (
+
+
+
+ Press ⇧⇥ to go back.
+
+
+ )
+ }
+
+ // No description on any item: render exactly as before (byte-for-byte).
+ if (!descriptionsEnabled) {
+ return (
+
+ {listSection}
+ {footer}
+
+ )
+ }
+
+ // Wide terminals: list and panel side-by-side. The panel matches the list's height so the
+ // combined block stays bounded to `sectionHeight`.
+ if (showDescriptionBeside) {
+ return (
+
+
+ {listSection}
+
+
+ {footer}
+
+ )
+ }
+
+ // Narrow terminals: show only a single, truncated preview line of the focused item's description
+ // below the list (the focused row already shows its label). This costs exactly one row (reserved
+ // via `listAvailableLines`), keeping the total height within the viewport. The full text is one
+ // Shift+Tab away. The box stretches to `twoThirds`, so `marginLeft` leaves a bound for
+ // `truncate-end` to clip against.
+ return (
+
+ {listSection}
+
+
+ {highlightedItem?.description}
+
+
+ {footer}
+
+ )
+}
+
+export {MultiSelectInput}
diff --git a/packages/cli-kit/src/private/node/ui/components/MultiSelectPrompt.test.tsx b/packages/cli-kit/src/private/node/ui/components/MultiSelectPrompt.test.tsx
new file mode 100644
index 00000000000..f44c82061f6
--- /dev/null
+++ b/packages/cli-kit/src/private/node/ui/components/MultiSelectPrompt.test.tsx
@@ -0,0 +1,300 @@
+import {MultiSelectPrompt} from './MultiSelectPrompt.js'
+import {getLastFrameAfterUnmount, sendInputAndWaitForChange, waitForInputsToBeReady, render} from '../../testing/ui.js'
+import {unstyled} from '../../../../public/node/output.js'
+import {Stdout} from '../../ui.js'
+import {AbortController} from '../../../../public/node/abort.js'
+import {beforeEach, describe, expect, test, vi} from 'vitest'
+
+import React from 'react'
+import {useStdout} from 'ink'
+
+vi.mock('ink', async () => {
+ const original: any = await vi.importActual('ink')
+ return {
+ ...original,
+ useStdout: vi.fn(),
+ }
+})
+
+const ARROW_DOWN = '[B'
+const ARROW_UP = '[A'
+const ENTER = '\r'
+const SPACE = ' '
+
+beforeEach(() => {
+ vi.mocked(useStdout).mockReturnValue({
+ stdout: new Stdout({
+ columns: 80,
+ rows: 80,
+ }) as any,
+ write: () => {},
+ })
+})
+
+describe('MultiSelectPrompt', async () => {
+ test('toggles and submits the selected answers', async () => {
+ const onEnter = vi.fn()
+
+ const items = [
+ {label: 'first', value: 'first'},
+ {label: 'second', value: 'second'},
+ {label: 'third', value: 'third'},
+ ]
+
+ const renderInstance = render(
+ ,
+ )
+
+ await waitForInputsToBeReady()
+ // toggle "first"
+ await sendInputAndWaitForChange(renderInstance, SPACE)
+ // move down twice and toggle "third"
+ await sendInputAndWaitForChange(renderInstance, ARROW_DOWN)
+ await sendInputAndWaitForChange(renderInstance, ARROW_DOWN)
+ await sendInputAndWaitForChange(renderInstance, SPACE)
+ await sendInputAndWaitForChange(renderInstance, ENTER)
+
+ // resolves in declared order, not toggle order
+ expect(onEnter).toHaveBeenCalledWith(['first', 'third'])
+
+ expect(getLastFrameAfterUnmount(renderInstance)).toMatchInlineSnapshot(`
+ "? Select the extensions you want to add:
+ [36m✔[39m [36mfirst, third[39m
+ "
+ `)
+ })
+
+ test('renders the checkboxes and instructions', async () => {
+ const items = [
+ {label: 'first', value: 'first'},
+ {label: 'second', value: 'second'},
+ {label: 'third', value: 'third'},
+ ]
+
+ const renderInstance = render(
+ {}} />,
+ )
+
+ expect(unstyled(renderInstance.lastFrame()!)).toMatchInlineSnapshot(`
+ "? Select the extensions you want to add:
+
+ > ☐ first
+ ☐ second
+ ☐ third
+
+ Press ↑↓ arrows to select, space to toggle, enter to confirm.
+ "
+ `)
+ })
+
+ test('resolves to an empty array when nothing is selected', async () => {
+ const onEnter = vi.fn()
+
+ const items = [
+ {label: 'first', value: 'first'},
+ {label: 'second', value: 'second'},
+ {label: 'third', value: 'third'},
+ ]
+
+ const renderInstance = render(
+ ,
+ )
+
+ await waitForInputsToBeReady()
+ await sendInputAndWaitForChange(renderInstance, ENTER)
+
+ expect(onEnter).toHaveBeenCalledWith([])
+
+ expect(getLastFrameAfterUnmount(renderInstance)).toMatchInlineSnapshot(`
+ "? Select the extensions you want to add:
+ [36m✔[39m [36mNothing selected[39m
+ "
+ `)
+ })
+
+ test('pre-selects the default values', async () => {
+ const onEnter = vi.fn()
+
+ const items = [
+ {label: 'first', value: 'first'},
+ {label: 'second', value: 'second'},
+ {label: 'third', value: 'third'},
+ ]
+
+ const renderInstance = render(
+ ,
+ )
+
+ expect(unstyled(renderInstance.lastFrame()!)).toMatchInlineSnapshot(`
+ "? Select the extensions you want to add:
+
+ > ☐ first
+ ☒ second
+ ☐ third
+
+ Press ↑↓ arrows to select, space to toggle, enter to confirm.
+ "
+ `)
+
+ await waitForInputsToBeReady()
+ // toggle "first" on, so both "first" and "second" are selected
+ await sendInputAndWaitForChange(renderInstance, SPACE)
+ await sendInputAndWaitForChange(renderInstance, ENTER)
+
+ expect(onEnter).toHaveBeenCalledWith(['first', 'second'])
+ })
+
+ test('can toggle a default value back off', async () => {
+ const onEnter = vi.fn()
+
+ const items = [
+ {label: 'first', value: 'first'},
+ {label: 'second', value: 'second'},
+ ]
+
+ const renderInstance = render(
+ ,
+ )
+
+ await waitForInputsToBeReady()
+ // "first" is focused and pre-selected; space toggles it off
+ await sendInputAndWaitForChange(renderInstance, SPACE)
+ await sendInputAndWaitForChange(renderInstance, ENTER)
+
+ expect(onEnter).toHaveBeenCalledWith([])
+ })
+
+ test('resolves in declared order even when choices are grouped and reordered for display', async () => {
+ const onEnter = vi.fn()
+
+ // Declared order is alpha, beta, gamma, delta. groupOrder puts group "A"
+ // (beta, delta) before group "B" (alpha, gamma), so the on-screen order is
+ // beta, delta, alpha, gamma — deliberately different from declared order.
+ const items = [
+ {label: 'alpha', value: 'alpha', group: 'B'},
+ {label: 'beta', value: 'beta', group: 'A'},
+ {label: 'gamma', value: 'gamma', group: 'B'},
+ {label: 'delta', value: 'delta', group: 'A'},
+ ]
+
+ const renderInstance = render(
+ ,
+ )
+
+ await waitForInputsToBeReady()
+ // Focus starts on the first displayed item ("beta"); toggle it on.
+ await sendInputAndWaitForChange(renderInstance, SPACE)
+ // Move down to "alpha" (third displayed item) and toggle it on.
+ await sendInputAndWaitForChange(renderInstance, ARROW_DOWN)
+ await sendInputAndWaitForChange(renderInstance, ARROW_DOWN)
+ await sendInputAndWaitForChange(renderInstance, SPACE)
+ await sendInputAndWaitForChange(renderInstance, ENTER)
+
+ // Declared order is alpha (index 0) then beta (index 1), NOT the display
+ // order beta, alpha.
+ expect(onEnter).toHaveBeenCalledWith(['alpha', 'beta'])
+ })
+
+ test('supports an info table', async () => {
+ const items = [
+ {label: 'first', value: 'first'},
+ {label: 'second', value: 'second'},
+ ]
+
+ const infoTable = [
+ {
+ header: 'Add',
+ items: ['new-ext'],
+ bullet: '+',
+ },
+ ]
+
+ const renderInstance = render(
+ {}}
+ />,
+ )
+
+ expect(unstyled(renderInstance.lastFrame()!)).toMatchInlineSnapshot(`
+ "? Select the extensions you want to add:
+
+ ┃ Add
+ ┃ + new-ext
+
+ > ☐ first
+ ☐ second
+
+ Press ↑↓ arrows to select, space to toggle, enter to confirm.
+ "
+ `)
+ })
+
+ test("it doesn't submit if there are no choices", async () => {
+ const onEnter = vi.fn()
+
+ const items: any[] = []
+
+ const renderInstance = render(
+ ,
+ )
+
+ expect(unstyled(getLastFrameAfterUnmount(renderInstance)!)).toContain(
+ 'ERROR MultiSelectPrompt requires at least one choice',
+ )
+ })
+
+ test('abortController can be used to exit the prompt from outside', async () => {
+ const items = [
+ {label: 'a', value: 'a'},
+ {label: 'b', value: 'b'},
+ ]
+
+ const abortController = new AbortController()
+
+ const renderInstance = render(
+ {}}
+ message="Select the extensions you want to add"
+ abortSignal={abortController.signal}
+ />,
+ )
+
+ const promise = renderInstance.waitUntilExit()
+
+ expect(unstyled(renderInstance.lastFrame()!)).toMatchInlineSnapshot(`
+ "? Select the extensions you want to add:
+
+ > ☐ a
+ ☐ b
+
+ Press ↑↓ arrows to select, space to toggle, enter to confirm.
+ "
+ `)
+
+ abortController.abort()
+
+ // wait for the onAbort promise to resolve
+ await new Promise((resolve) => setTimeout(resolve, 0))
+
+ await expect(promise).resolves.toEqual(undefined)
+ })
+})
diff --git a/packages/cli-kit/src/private/node/ui/components/MultiSelectPrompt.tsx b/packages/cli-kit/src/private/node/ui/components/MultiSelectPrompt.tsx
new file mode 100644
index 00000000000..08f54a77cf0
--- /dev/null
+++ b/packages/cli-kit/src/private/node/ui/components/MultiSelectPrompt.tsx
@@ -0,0 +1,75 @@
+import {MultiSelectInput, MultiSelectInputProps} from './MultiSelectInput.js'
+import {Item as SelectItem} from './SelectInput.js'
+import {InfoTableProps} from './Prompts/InfoTable.js'
+import {InfoMessageProps} from './Prompts/InfoMessage.js'
+import {Message, PromptLayout} from './Prompts/PromptLayout.js'
+import {AbortSignal} from '../../../../public/node/abort.js'
+import {useComplete} from '../../ui.js'
+import usePrompt, {PromptState} from '../hooks/use-prompt.js'
+
+import React, {ReactElement, useCallback, useEffect} from 'react'
+
+export interface MultiSelectPromptProps {
+ message: Message
+ choices: MultiSelectInputProps['items']
+ onSubmit: (values: T[]) => void
+ infoTable?: InfoTableProps['table']
+ defaultValue?: T[]
+ abortSignal?: AbortSignal
+ infoMessage?: InfoMessageProps['message']
+ groupOrder?: string[]
+}
+
+function MultiSelectPrompt({
+ message,
+ choices,
+ infoTable,
+ infoMessage,
+ onSubmit,
+ defaultValue,
+ abortSignal,
+ groupOrder,
+}: React.PropsWithChildren>): ReactElement | null {
+ if (choices.length === 0) {
+ throw new Error('MultiSelectPrompt requires at least one choice')
+ }
+ const complete = useComplete()
+ const {promptState, setPromptState, answer, setAnswer} = usePrompt[]>({
+ initialAnswer: [],
+ })
+
+ const submitAnswer = useCallback(
+ (answer: SelectItem[]) => {
+ setAnswer(answer)
+ setPromptState(PromptState.Submitted)
+ },
+ [setAnswer, setPromptState],
+ )
+
+ useEffect(() => {
+ if (promptState === PromptState.Submitted) {
+ onSubmit(answer.map((item) => item.value))
+ complete()
+ }
+ }, [answer, onSubmit, promptState, complete])
+
+ // Selecting zero items is valid, so fall back to a descriptive label rather
+ // than leaving the submitted state blank.
+ const submittedAnswerLabel = answer.length > 0 ? answer.map((item) => item.label).join(', ') : 'Nothing selected'
+
+ return (
+
+ }
+ />
+ )
+}
+
+export {MultiSelectPrompt}
diff --git a/packages/cli-kit/src/private/node/ui/components/SelectInput.description.test.tsx b/packages/cli-kit/src/private/node/ui/components/SelectInput.description.test.tsx
new file mode 100644
index 00000000000..a4c41d7c324
--- /dev/null
+++ b/packages/cli-kit/src/private/node/ui/components/SelectInput.description.test.tsx
@@ -0,0 +1,343 @@
+import {SelectInput} from './SelectInput.js'
+import {render, waitForInputsToBeReady} from '../../testing/ui.js'
+import {Stdout} from '../../ui.js'
+import {unstyled} from '../../../../public/node/output.js'
+import {describe, expect, test} from 'vitest'
+
+import React from 'react'
+
+const ARROW_DOWN = '[B'
+
+// Ink parses CSI Z (ESC [ Z, "back-tab") as Shift+Tab, which TextInput deliberately ignores, so it
+// is the free toggle key for the full-description overlay.
+const SHIFT_TAB = '[Z'
+
+// The default testing `render` helper hard-codes an 80/100-column stdout and reads frames from an
+// internal stdout instance. To exercise the responsive description panel we need to control the
+// terminal width and read frames from the same stdout that drives `useLayout`, so we pass our own
+// width-controlled Stdout and read its frames directly.
+function renderWithWidth(tree: React.ReactElement, columns: number) {
+ const stdout = new Stdout({columns, rows: 100})
+ const renderInstance = render(tree, {stdout: stdout as unknown as NodeJS.WriteStream})
+ return {renderInstance, stdout}
+}
+
+function lastUnstyledFrame(stdout: Stdout): string {
+ return unstyled(stdout.lastFrame() ?? '')
+}
+
+// Waits until the width-controlled stdout produces a frame different from the current one after
+// running `action`, then yields once more so React's scheduler can flush follow-up effects.
+async function sendAndWaitForFrameChange(stdout: Stdout, action: () => void) {
+ const initialFrame = stdout.lastFrame()
+ action()
+ while (stdout.lastFrame() === initialFrame) {
+ // eslint-disable-next-line no-await-in-loop
+ await new Promise((resolve) => setImmediate(() => setTimeout(resolve, 0)))
+ }
+ await new Promise((resolve) => setImmediate(() => setTimeout(resolve, 0)))
+}
+
+// Physical rows the stacked hint (preview line + its gap) reserves out of the list budget. Mirror
+// of `STACKED_HINT_RESERVE` in SelectInput.tsx (not exported, kept in sync deliberately).
+const STACKED_HINT_RESERVE = 2
+
+const itemsWithDescriptions = [
+ {label: 'doc:fetch', value: 'fetch', description: 'Fetch a documentation page by URL.'},
+ {label: 'doc:search', value: 'search', description: 'Search the docs for a keyword.'},
+ {label: 'app:dev', value: 'dev', description: 'Start a local development server.'},
+]
+
+describe('SelectInput with descriptions', () => {
+ test('shows the highlighted item description in a panel', async () => {
+ const {stdout} = renderWithWidth( {}} />, 120)
+
+ await waitForInputsToBeReady()
+
+ const frame = lastUnstyledFrame(stdout)
+ expect(frame).toContain('Fetch a documentation page by URL.')
+ // The other items' descriptions are not shown until they become highlighted.
+ expect(frame).not.toContain('Search the docs for a keyword.')
+ })
+
+ test('updates the shown description when arrowing', async () => {
+ const {renderInstance, stdout} = renderWithWidth(
+ {}} />,
+ 120,
+ )
+
+ await waitForInputsToBeReady()
+ await sendAndWaitForFrameChange(stdout, () => renderInstance.stdin.write(ARROW_DOWN))
+
+ const frame = lastUnstyledFrame(stdout)
+ expect(frame).toContain('Search the docs for a keyword.')
+ expect(frame).not.toContain('Fetch a documentation page by URL.')
+ })
+
+ test('places the panel beside the list on wide terminals and below on narrow ones', async () => {
+ const description = 'Fetch a documentation page by URL.'
+
+ const {stdout: wideStdout} = renderWithWidth( {}} />, 120)
+ const {stdout: narrowStdout} = renderWithWidth(
+ {}} />,
+ 80,
+ )
+
+ await waitForInputsToBeReady()
+
+ const wideLines = lastUnstyledFrame(wideStdout).split('\n')
+ const narrowLines = lastUnstyledFrame(narrowStdout).split('\n')
+
+ const wideDescriptionLine = wideLines.findIndex((line) => line.includes(description))
+ const narrowDescriptionLine = narrowLines.findIndex((line) => line.includes(description))
+
+ // Side-by-side: the description sits on one of the first rows, aligned with the list.
+ // Stacked: the description appears only after all three list rows.
+ expect(wideDescriptionLine).toBeLessThan(3)
+ expect(narrowDescriptionLine).toBeGreaterThanOrEqual(3)
+
+ // When beside, the highlighted label appears twice on the same physical line: once as the list
+ // row and once as the panel title.
+ expect(wideLines[wideDescriptionLine - 1]).toContain('doc:fetch')
+ })
+
+ test('truncates long labels to a single physical line', async () => {
+ const longLabelItems = [
+ {
+ label: `doc:fetch ${'very-long-suffix '.repeat(20)}`.trim(),
+ value: 'fetch',
+ description: 'Fetch a documentation page by URL.',
+ },
+ {label: 'app:dev', value: 'dev', description: 'Start a local development server.'},
+ ]
+
+ const {stdout} = renderWithWidth( {}} />, 120)
+
+ await waitForInputsToBeReady()
+
+ const frame = lastUnstyledFrame(stdout)
+ // The row is clipped with an ellipsis and the full label never appears in one piece.
+ expect(frame).toContain('…')
+ expect(frame).not.toContain(longLabelItems[0]!.label)
+ })
+
+ test('keeps a stable render height while scrolling through long descriptions (ghosting fix)', async () => {
+ const manyLongItems = Array.from({length: 12}, (_, index) => ({
+ label: `command:${index}`,
+ value: `command-${index}`,
+ description: `A very long description for command ${index} that would previously wrap onto ${'multiple '.repeat(
+ 8,
+ )}physical lines and cause ghosting when scrolling.`,
+ }))
+
+ const {renderInstance, stdout} = renderWithWidth(
+ {}} availableLines={6} />,
+ 120,
+ )
+
+ await waitForInputsToBeReady()
+ const initialLineCount = lastUnstyledFrame(stdout).split('\n').length
+
+ // Arrowing down repeatedly must not grow the rendered block: single-line rows keep the true
+ // height equal to the option count, so nothing overflows the viewport and prior frames are
+ // fully erased.
+ for (let step = 0; step < 8; step++) {
+ // eslint-disable-next-line no-await-in-loop
+ await sendAndWaitForFrameChange(stdout, () => renderInstance.stdin.write(ARROW_DOWN))
+ expect(lastUnstyledFrame(stdout).split('\n').length).toBe(initialLineCount)
+ }
+ })
+
+ test('renders no panel and no truncation when no item has a description', async () => {
+ const items = [
+ {label: 'first', value: 'first'},
+ {label: 'second', value: 'second'},
+ {label: 'third', value: 'third'},
+ ]
+
+ const {stdout} = renderWithWidth( {}} />, 120)
+
+ await waitForInputsToBeReady()
+
+ const frame = lastUnstyledFrame(stdout)
+ expect(frame).not.toContain('…')
+ expect(frame).toContain('first')
+ expect(frame).toContain('second')
+ expect(frame).toContain('third')
+ })
+
+ test('truncates a long group title to a single physical line', async () => {
+ // Long enough to wrap to several rows if it were not truncated. No descriptions here on purpose:
+ // group-title truncation is unconditional, not gated on the descriptions feature.
+ const longGroupTitle = `Group ${'segment-'.repeat(30)}`.trim()
+ const groupedItems = [
+ {label: 'alpha', value: 'alpha', group: longGroupTitle},
+ {label: 'beta', value: 'beta', group: longGroupTitle},
+ ]
+
+ const {stdout} = renderWithWidth( {}} />, 80)
+
+ await waitForInputsToBeReady()
+
+ const lines = lastUnstyledFrame(stdout).split('\n')
+ // If the title wrapped, more than one physical line would carry a chunk of it.
+ const titleLines = lines.filter((line) => line.includes('segment-'))
+ expect(titleLines).toHaveLength(1)
+ expect(lastUnstyledFrame(stdout)).toContain('…')
+ // The option rows below the title are still visible (not clipped by an overflowing title).
+ expect(lastUnstyledFrame(stdout)).toContain('alpha')
+ expect(lastUnstyledFrame(stdout)).toContain('beta')
+ })
+
+ test('keeps the stacked layout within the vertical budget while scrolling', async () => {
+ const manyLongItems = Array.from({length: 12}, (_, index) => ({
+ label: `command:${index}`,
+ value: `command-${index}`,
+ description: `Long description ${index} ${'word '.repeat(30)}`.trim(),
+ }))
+
+ // Narrow width forces the stacked layout; a small budget is where the old code overflowed.
+ const {renderInstance, stdout} = renderWithWidth(
+ {}} availableLines={6} />,
+ 80,
+ )
+
+ await waitForInputsToBeReady()
+ const initialLineCount = lastUnstyledFrame(stdout).split('\n').length
+
+ // The stacked hint is reserved out of the list budget, so the whole block stays small and, more
+ // importantly, its height never grows as focus moves (which is what caused vertical ghosting).
+ expect(initialLineCount).toBeLessThanOrEqual(10)
+ for (let step = 0; step < 8; step++) {
+ // eslint-disable-next-line no-await-in-loop
+ await sendAndWaitForFrameChange(stdout, () => renderInstance.stdin.write(ARROW_DOWN))
+ expect(lastUnstyledFrame(stdout).split('\n').length).toBe(initialLineCount)
+ }
+ })
+
+ // Derive the rendered list height from a stacked-layout frame. The frame lays out as:
+ // [list rows … (sectionHeight)] [gap] [preview line] [gap] [footer]
+ // so the list height is the index of the preview line minus the one gap row above it.
+ function stackedListHeight(frame: string): number {
+ const lines = frame.split('\n')
+ const previewIndex = lines.findIndex((line) => line.includes('Long description'))
+ return previewIndex - 1
+ }
+
+ // Regression for R1: in the STACKED description layout a grouped list has `minHeight = 5`, which
+ // used to override the reduced list budget so `sectionHeight + gap + preview` overflowed the
+ // viewport (reintroducing vertical ghosting). The hard-ceiling clamp guarantees the exact
+ // invariant `listHeight + STACKED_HINT_RESERVE <= availableLines`. Pre-fix the list height was
+ // pinned at 5, so `5 + 2 = 7` blew both the 3- and 6-row budgets.
+ for (const availableLines of [3, 6]) {
+ test(`keeps a grouped stacked list within the vertical budget (availableLines=${availableLines})`, async () => {
+ const groupedItems = Array.from({length: 8}, (_, index) => ({
+ label: `command:${index}`,
+ value: `command-${index}`,
+ group: index % 2 === 0 ? 'Group A' : 'Group B',
+ description: `Long description ${index} ${'word '.repeat(30)}`.trim(),
+ }))
+
+ // Width 80 forces the stacked layout; grouped items give `minHeight = 5`, the pre-fix floor.
+ const {renderInstance, stdout} = renderWithWidth(
+ {}} availableLines={availableLines} />,
+ 80,
+ )
+
+ await waitForInputsToBeReady()
+
+ expect(stackedListHeight(lastUnstyledFrame(stdout)) + STACKED_HINT_RESERVE).toBeLessThanOrEqual(availableLines)
+
+ // Arrow down to the last item (length - 1 presses); a further down-arrow at the end is a
+ // no-op that would never produce a new frame. On every frame the budget invariant must hold
+ // and the block height must never grow (no ghosting).
+ const initialLineCount = lastUnstyledFrame(stdout).split('\n').length
+ for (let step = 0; step < groupedItems.length - 1; step++) {
+ // eslint-disable-next-line no-await-in-loop
+ await sendAndWaitForFrameChange(stdout, () => renderInstance.stdin.write(ARROW_DOWN))
+ expect(stackedListHeight(lastUnstyledFrame(stdout)) + STACKED_HINT_RESERVE).toBeLessThanOrEqual(availableLines)
+ expect(lastUnstyledFrame(stdout).split('\n').length).toBe(initialLineCount)
+ }
+ })
+ }
+
+ // Regression for R2: a WIDTH-only resize that crosses the description-panel breakpoint changes the
+ // list's row budget (`limit` / `visibleOptionCount`) without changing the option set. The state
+ // hook used to reset to the first option on any `visibleOptionCount` change, jumping the highlight
+ // back to item 0 (so a subsequent Enter could confirm the wrong item). It must now preserve the
+ // highlight and only re-fit the scroll window.
+ test('preserves the highlighted item across a width-only resize (beside↔stacked)', async () => {
+ const items = Array.from({length: 8}, (_, index) => ({
+ label: `command:${index}`,
+ value: `command-${index}`,
+ description: `Unique description number ${index} for command ${index}.`,
+ }))
+
+ const changes: (string | undefined)[] = []
+ // availableLines=6 keeps `limit` below the item count and makes it differ between stacked
+ // (4 rows) and beside (6 rows), so crossing the breakpoint genuinely changes visibleOptionCount.
+ const stdout = new Stdout({columns: 80, rows: 100})
+ const renderInstance = render(
+ changes.push(item?.value)} />,
+ {stdout: stdout as unknown as NodeJS.WriteStream},
+ )
+
+ await waitForInputsToBeReady()
+
+ // Highlight command-5 (scrolls the window in the narrow/stacked layout).
+ for (let step = 0; step < 5; step++) {
+ // eslint-disable-next-line no-await-in-loop
+ await sendAndWaitForFrameChange(stdout, () => renderInstance.stdin.write(ARROW_DOWN))
+ }
+ expect(changes[changes.length - 1]).toBe('command-5')
+ expect(lastUnstyledFrame(stdout)).toContain('Unique description number 5')
+
+ // Widen past the beside breakpoint: layout flips to the side panel and visibleOptionCount grows.
+ await sendAndWaitForFrameChange(stdout, () => {
+ stdout.columns = 120
+ stdout.emit('resize')
+ })
+
+ const afterResize = lastUnstyledFrame(stdout)
+ // The highlight (and thus the shown description) must still be command-5, NOT reset to item 0.
+ expect(afterResize).toContain('Unique description number 5')
+ expect(afterResize).not.toContain('Unique description number 0')
+ // The resize must not have fired onChange with a different value (no silent selection jump).
+ expect(changes[changes.length - 1]).toBe('command-5')
+ })
+
+ test('Shift+Tab toggles a full-description takeover', async () => {
+ // Long enough that the compact preview must truncate before the sentinel token at the end.
+ const longDescription =
+ 'This description begins here and then continues far past a single terminal line so the compact ' +
+ 'preview has to truncate it, right up to the sentinel token OMEGA_END_TOKEN.'
+ const items = [
+ {label: 'doc:fetch', value: 'fetch', description: longDescription},
+ {label: 'app:dev', value: 'dev', description: 'Start a local development server.'},
+ ]
+
+ const {renderInstance, stdout} = renderWithWidth( {}} />, 80)
+
+ await waitForInputsToBeReady()
+
+ // The footer can wrap on narrow terminals, so normalize whitespace before matching the hint.
+ const normalizeWhitespace = (frame: string) => frame.replace(/\s+/g, ' ')
+
+ const before = lastUnstyledFrame(stdout)
+ // Compact preview: hint present, sentinel truncated away.
+ expect(normalizeWhitespace(before)).toContain('⇧⇥ full description')
+ expect(before).not.toContain('OMEGA_END_TOKEN')
+
+ await sendAndWaitForFrameChange(stdout, () => renderInstance.stdin.write(SHIFT_TAB))
+ const overlay = lastUnstyledFrame(stdout)
+ // Takeover: the full text (including the sentinel) is now shown, with a back hint.
+ expect(overlay).toContain('OMEGA_END_TOKEN')
+ expect(overlay).toContain('Press ⇧⇥ to go back.')
+
+ await sendAndWaitForFrameChange(stdout, () => renderInstance.stdin.write(SHIFT_TAB))
+ const after = lastUnstyledFrame(stdout)
+ // Back to the list: sentinel hidden again, discoverability hint restored.
+ expect(after).not.toContain('OMEGA_END_TOKEN')
+ expect(normalizeWhitespace(after)).toContain('⇧⇥ full description')
+ })
+})
diff --git a/packages/cli-kit/src/private/node/ui/components/SelectInput.tsx b/packages/cli-kit/src/private/node/ui/components/SelectInput.tsx
index e23e8d1dae5..406cc3bf759 100644
--- a/packages/cli-kit/src/private/node/ui/components/SelectInput.tsx
+++ b/packages/cli-kit/src/private/node/ui/components/SelectInput.tsx
@@ -1,8 +1,9 @@
import {Scrollbar} from './Scrollbar.js'
+import {DescriptionPanel, MIN_SIDE_PANEL_WIDTH} from './DescriptionPanel.js'
import {handleCtrlC} from '../../ui.js'
import useLayout from '../hooks/use-layout.js'
import {useSelectState} from '../hooks/use-select-state.js'
-import React, {useCallback, useEffect} from 'react'
+import React, {useCallback, useEffect, useState} from 'react'
import {Box, Key, useInput, Text, DOMElement} from 'ink'
import chalk from 'chalk'
import figures from 'figures'
@@ -35,6 +36,12 @@ export interface Item {
group?: string
helperText?: string
disabled?: boolean
+ /**
+ * Optional longer description of the item. When at least one visible item provides a
+ * description, the list renders names-only, single-line rows and shows the highlighted
+ * item's description in a responsive side/below panel.
+ */
+ description?: string
}
function highlightedLabel(label: string, term: string | undefined) {
@@ -74,6 +81,7 @@ interface ItemProps {
enableShortcuts: boolean
hasAnyGroup: boolean
index: number
+ singleLine: boolean
}
function Item({
@@ -85,6 +93,7 @@ function Item({
items,
hasAnyGroup,
index,
+ singleLine,
}: ItemProps): React.ReactElement {
const label = highlightedLabel(item.label, highlightedTerm)
let title: string | undefined
@@ -110,14 +119,24 @@ function Item({
minHeight={title ? 2 : 1}
>
{title ? (
+ // Always keep the group title on a single physical line. Without this, a long title wraps to
+ // 2+ rows, but `minHeight={title ? 2 : 1}` and `maximumLinesLostToGroups()` both assume a
+ // one-line title, so the `overflowY="hidden"` list box would clip the focused option row.
+ // The title Box stretches to the list column width, so `truncate-end` has a bound to clip to.
- {title}
+
+ {title}
+
) : null}
-
+
{isSelected ? {`>`} : }
-
+ {/* When descriptions are active, keep every row to exactly one physical line so the list's
+ true height equals the option count (what the scrollbar/sectionHeight already assume),
+ which is what prevents the wrapped-row ghosting bug. Otherwise preserve the original
+ wrapping behavior byte-for-byte. */}
+
{showKey ? `(${item.key}) ${label}` : label}
@@ -127,6 +146,11 @@ function Item({
const MAX_AVAILABLE_LINES = 25
+// Physical rows the stacked description hint (+ its gap) occupies below the list. Reserved out of
+// the list's vertical budget so the list never fills the whole budget and then pushes the hint past
+// the viewport (which reintroduced the vertical ghosting bug).
+const STACKED_HINT_RESERVE = 2
+
function SelectInput({
items: rawItems,
initialItems = rawItems,
@@ -170,17 +194,43 @@ function SelectInput({
const availableLinesToUse = Math.min(availableLines, MAX_AVAILABLE_LINES)
+ const {fullWidth, twoThirds} = useLayout()
+
+ // The description panel is opt-in: it only activates when at least one item provides a
+ // description. When it does, rows become single-line/truncated and the highlighted item's
+ // description is shown in a panel.
+ const descriptionsEnabled = items.some((item) => (item.description?.length ?? 0) > 0)
+
+ // useLayout clamps both `twoThirds` and `oneThird` up to a minimum of 80 columns, so they can't
+ // be placed side-by-side on typical terminals without overflowing (which would reintroduce the
+ // wrapped-row ghosting). Instead, keep the list at `twoThirds` and give the panel exactly the
+ // remaining width, so the two columns always sum to `fullWidth`. Only place the panel beside the
+ // list when that remainder is wide enough to be readable; otherwise stack it below.
+ const sidePanelWidth = fullWidth - twoThirds
+ const showDescriptionBeside = descriptionsEnabled && sidePanelWidth >= MIN_SIDE_PANEL_WIDTH
+
+ // `availableLines` is the real remaining vertical budget above the footer (see
+ // Prompts/PromptLayout.tsx). Only the STACKED description case adds a line (+ gap) *below* the
+ // list, so in that case we shrink the budget the list sizes itself against; otherwise the list
+ // would fill the whole budget and then push the stacked hint past the viewport, reintroducing the
+ // vertical ghosting bug. The beside/wide panel is side-by-side and costs no vertical rows, and the
+ // no-description path keeps the full budget, so both stay byte-for-byte unchanged.
+ const listAvailableLines =
+ descriptionsEnabled && !showDescriptionBeside
+ ? Math.max(2, availableLinesToUse - STACKED_HINT_RESERVE)
+ : availableLinesToUse
+
function maximumLinesLostToGroups(items: Item[]): number {
// Calculate a safe estimate of the limit needed based on the space available
const numberOfGroups = new Set(items.map((item) => item.group).filter((group) => group)).size
// Add 1 to numberOfGroups because we also have a default Other group
- const maxVisibleGroups = Math.ceil(Math.min((availableLinesToUse + 1) / 3, numberOfGroups + 1))
+ const maxVisibleGroups = Math.ceil(Math.min((listAvailableLines + 1) / 3, numberOfGroups + 1))
// If we have x visible groups, we lose 1 line to the first group + 2 lines to the rest
return numberOfGroups > 0 ? (maxVisibleGroups - 1) * 2 + 1 : 0
}
const maxLinesLostToGroups = maximumLinesLostToGroups(items)
- const limit = Math.max(2, availableLinesToUse - maxLinesLostToGroups)
+ const limit = Math.max(2, listAvailableLines - maxLinesLostToGroups)
const hasLimit = items.length > limit
const state = useSelectState({
@@ -189,6 +239,12 @@ function SelectInput({
defaultValue,
})
+ const highlightedItem = descriptionsEnabled ? items.find((item) => item.value === state.value) : undefined
+
+ // Shift+Tab toggles a full-screen "detail" takeover of the focused item's description. It is only
+ // meaningful when descriptions are on and the focused item actually has one.
+ const [showFullDescription, setShowFullDescription] = useState(false)
+
useEffect(() => {
if (typeof state.value !== 'undefined' && state.previousValue !== state.value) {
onChange?.(items.find((item) => item.value === state.value))
@@ -226,6 +282,16 @@ function SelectInput({
(input, key) => {
handleCtrlC(input, key)
+ // Shift+Tab toggles the full-description takeover. TextInput ignores this exact combo, so it
+ // is free to reuse across autocomplete/select/multi-select. Only react when there is a
+ // description to show; otherwise leave the key alone.
+ if (key.shift && key.tab) {
+ if (descriptionsEnabled && (highlightedItem?.description?.length ?? 0) > 0) {
+ setShowFullDescription((previous) => !previous)
+ }
+ return
+ }
+
if (typeof state.value !== 'undefined' && key.return) {
const item = items.find((item) => item.value === state.value)
@@ -243,7 +309,6 @@ function SelectInput({
},
{isActive: focus},
)
- const {twoThirds} = useLayout()
if (loading) {
return (
@@ -260,58 +325,136 @@ function SelectInput({
} else {
const optionsHeight = initialItems.length + maximumLinesLostToGroups(initialItems)
const minHeight = hasAnyGroup ? 5 : 2
- const sectionHeight = Math.max(minHeight, Math.min(availableLinesToUse, optionsHeight))
+ let sectionHeight = Math.max(minHeight, Math.min(listAvailableLines, optionsHeight))
+
+ // STACKED description case only: the preview line (+ its gap) render *below* the list, so the
+ // list plus that reserve must fit the real vertical budget. Treat the reserve as a HARD CEILING
+ // and clamp AFTER the `minHeight` floor — otherwise a grouped list (`minHeight=5`) in a small
+ // budget would push `sectionHeight + gap + preview` past the viewport and reintroduce the
+ // vertical ghosting the reserve was meant to prevent. A tiny budget may show fewer rows / scroll
+ // more; that tradeoff is accepted. `Math.max(1, …)` only guards against a non-positive height on
+ // a pathologically short terminal — real terminals are ≥24 rows. The no-description and beside
+ // paths are gated out here, so they stay byte-for-byte unchanged.
+ if (descriptionsEnabled && !showDescriptionBeside) {
+ sectionHeight = Math.min(sectionHeight, Math.max(1, availableLinesToUse - STACKED_HINT_RESERVE))
+ }
- return (
-
-
-
- {state.visibleOptions.map((item: Item, index: number) => (
-