Choice Selection Prompts

const prompts = require('prompts');

{
  /** Prompt type identifier */
  type: 'select',
  /** Property name for response object */
  name: string,
  /** Display message for user */
  message: string,
  /** Array of choice objects or strings */
  choices: Choice[],
  /** Index of default selected choice */
  initial?: number,
  /** Hint text displayed to user */
  hint?: string,
  /** Warning message when selecting disabled option */
  warn?: string,
  /** Custom formatter for selected value */
  format?: (value: any, values: Answers) => any,
  /** Render callback with kleur styling */
  onRender?: (kleur: any) => void,
  /** State change callback */
  onState?: (state: { value: any; aborted: boolean }) => void,
  /** Input stream */
  stdin?: NodeJS.ReadableStream,
  /** Output stream */
  stdout?: NodeJS.WritableStream
}

interface Choice {
  /** Display title for the choice */
  title: string;
  /** Value to store when selected. Defaults to array index if not specified */
  value?: any;
  /** Optional description text shown below title */
  description?: string;
  /** Whether this choice is disabled and cannot be selected */
  disabled?: boolean;
}

const prompts = require('prompts');

// Basic select prompt
const response = await prompts({
  type: 'select',
  name: 'color',
  message: 'Pick a color',
  choices: [
    { title: 'Red', value: '#ff0000' },
    { title: 'Green', value: '#00ff00' },
    { title: 'Blue', value: '#0000ff' }
  ],
  initial: 1
});

// Select with descriptions and disabled option
const response = await prompts({
  type: 'select',
  name: 'plan',
  message: 'Choose your plan',
  choices: [
    { 
      title: 'Free', 
      description: 'Basic features with usage limits',
      value: 'free' 
    },
    { 
      title: 'Pro', 
      description: 'Advanced features with higher limits',
      value: 'pro' 
    },
    { 
      title: 'Enterprise', 
      description: 'Full features with unlimited usage',
      value: 'enterprise',
      disabled: true
    }
  ],
  hint: '- Use arrow keys. Return to submit',
  warn: 'This option is not available in your region'
});

{
  /** Prompt type identifier */
  type: 'multiselect',
  /** Property name for response object */
  name: string,
  /** Display message for user */
  message: string,
  /** Array of choice objects with optional pre-selection */
  choices: MultiselectChoice[],
  /** Maximum number of selections allowed */
  max?: number,
  /** Minimum number of selections required */
  min?: number,
  /** Hint text displayed to user */
  hint?: string,
  /** Warning message when selecting disabled option */
  warn?: string,
  /** Instructions text or boolean to show/hide default instructions */
  instructions?: string | boolean,
  /** Number of options to display per page. Defaults to 10 */
  optionsPerPage?: number,
  /** Custom formatter for selected values array */
  format?: (values: any[], allValues: Answers) => any,
  /** Render callback with kleur styling */
  onRender?: (kleur: any) => void,
  /** State change callback */
  onState?: (state: { value: any[]; aborted: boolean }) => void,
  /** Input stream */
  stdin?: NodeJS.ReadableStream,
  /** Output stream */
  stdout?: NodeJS.WritableStream
}

interface MultiselectChoice {
  /** Display title for the choice */
  title: string;
  /** Value to store when selected. Defaults to array index if not specified */
  value?: any;
  /** Optional description text shown below title */
  description?: string;
  /** Whether this choice is disabled and cannot be selected */
  disabled?: boolean;
  /** Whether this choice is pre-selected. Defaults to false */
  selected?: boolean;
}

// Basic multiselect prompt
const response = await prompts({
  type: 'multiselect',
  name: 'technologies',
  message: 'Select technologies you use',
  choices: [
    { title: 'JavaScript', value: 'js' },
    { title: 'TypeScript', value: 'ts', selected: true },
    { title: 'Python', value: 'py' },
    { title: 'Java', value: 'java' },
    { title: 'C#', value: 'csharp' }
  ],
  max: 3,
  hint: '- Space to select. Return to submit'
});

// Multiselect with validation and formatting
const response = await prompts({
  type: 'multiselect',
  name: 'features',
  message: 'Select features to enable',
  choices: [
    { title: 'Authentication', value: 'auth', selected: true },
    { title: 'Database', value: 'db' },
    { title: 'File Upload', value: 'upload' },
    { title: 'Email Service', value: 'email' },
    { title: 'Premium Feature', value: 'premium', disabled: true }
  ],
  min: 1,
  instructions: 'Select at least one feature',
  format: values => values.map(v => v.toUpperCase())
});

{
  /** Prompt type identifier */
  type: 'autocomplete',
  /** Property name for response object */
  name: string,
  /** Display message for user */
  message: string,
  /** Array of choice objects for autocomplete */
  choices: Choice[],
  /** Function to filter choices based on input. Defaults to title-based filtering */
  suggest?: (input: string, choices: Choice[]) => Promise<Choice[]>,
  /** Maximum number of results to show. Defaults to 10 */
  limit?: number,
  /** Input style */
  style?: 'default' | 'password' | 'invisible' | 'emoji',
  /** Default initial value (string or choice index) */
  initial?: string | number,
  /** First ESCAPE keypress clears input if true */
  clearFirst?: boolean,
  /** Message when no matches found. Defaults to initial value */
  fallback?: string,
  /** Custom formatter for selected value */
  format?: (value: any, values: Answers) => any,
  /** Render callback with kleur styling */
  onRender?: (kleur: any) => void,
  /** State change callback */
  onState?: (state: { value: any; aborted: boolean; exited?: boolean }) => void,
  /** Input stream */
  stdin?: NodeJS.ReadableStream,
  /** Output stream */
  stdout?: NodeJS.WritableStream
}

// Basic autocomplete prompt
const response = await prompts({
  type: 'autocomplete',
  name: 'actor',
  message: 'Pick your favorite actor',
  choices: [
    { title: 'Cage', value: 'nicolas-cage' },
    { title: 'Clooney', value: 'george-clooney' },
    { title: 'Gyllenhaal', value: 'jake-gyllenhaal' },
    { title: 'Gibson', value: 'mel-gibson' },
    { title: 'Grant', value: 'hugh-grant' }
  ]
});

// Autocomplete with custom suggest function
const countries = [
  { title: 'United States', value: 'US' },
  { title: 'United Kingdom', value: 'UK' },
  { title: 'Canada', value: 'CA' },
  { title: 'Germany', value: 'DE' },
  { title: 'France', value: 'FR' }
];

const response = await prompts({
  type: 'autocomplete',
  name: 'country',
  message: 'Select your country',
  choices: countries,
  suggest: (input, choices) => {
    return Promise.resolve(
      choices.filter(choice => 
        choice.title.toLowerCase().includes(input.toLowerCase()) ||
        choice.value.toLowerCase().includes(input.toLowerCase())
      )
    );
  },
  limit: 5,
  fallback: 'No country found'
});

{
  /** Prompt type identifier */
  type: 'autocompleteMultiselect',
  /** Property name for response object */
  name: string,
  /** Display message for user */
  message: string,
  /** Array of choice objects with optional pre-selection */
  choices: MultiselectChoice[],
  /** Maximum number of selections allowed */
  max?: number,
  /** Minimum number of selections required */
  min?: number,
  /** Hint text displayed to user */
  hint?: string,
  /** Warning message when selecting disabled option */
  warn?: string,
  /** Instructions text or boolean to show/hide default instructions */
  instructions?: string | boolean,
  /** Number of options to display per page. Defaults to 10 */
  optionsPerPage?: number,
  /** Custom formatter for selected values array */
  format?: (values: any[], allValues: Answers) => any,
  /** Render callback with kleur styling */
  onRender?: (kleur: any) => void,
  /** State change callback */
  onState?: (state: { value: any[]; aborted: boolean }) => void,
  /** Input stream */
  stdin?: NodeJS.ReadableStream,
  /** Output stream */
  stdout?: NodeJS.WritableStream
}

// Searchable multiselect for large lists
const languages = [
  { title: 'JavaScript', value: 'js' },
  { title: 'TypeScript', value: 'ts' },
  { title: 'Python', value: 'py' },
  { title: 'Java', value: 'java' },
  { title: 'C++', value: 'cpp' },
  { title: 'C#', value: 'csharp' },
  { title: 'Go', value: 'go' },
  { title: 'Rust', value: 'rust' },
  { title: 'PHP', value: 'php' },
  { title: 'Ruby', value: 'ruby' }
];

const response = await prompts({
  type: 'autocompleteMultiselect',
  name: 'languages',
  message: 'Select programming languages',
  choices: languages,
  max: 5,
  hint: 'Type to search, space to select, return to submit'
});

// Choice object properties
interface Choice {
  title: string;        // Required display text
  value?: any;          // Optional value (defaults to index)
  description?: string; // Optional description text
  disabled?: boolean;   // Optional disabled state
  selected?: boolean;   // Optional pre-selection (multiselect only)
}

// String choices are automatically converted to choice objects
const choices = ['Option 1', 'Option 2', 'Option 3'];
// Equivalent to:
const choices = [
  { title: 'Option 1', value: 0 },
  { title: 'Option 2', value: 1 },
  { title: 'Option 3', value: 2 }
];

/**
 * Custom suggest function for filtering choices
 * @param input - User's search input
 * @param choices - Array of all available choices
 * @returns Promise resolving to filtered choices array
 */
type SuggestFunction = (
  input: string, 
  choices: Choice[]
) => Promise<Choice[]>;

// Example: case-insensitive search in title and value
const suggest = (input, choices) => {
  const filtered = choices.filter(choice => {
    const searchText = input.toLowerCase();
    return (
      choice.title.toLowerCase().includes(searchText) ||
      (choice.value && choice.value.toString().toLowerCase().includes(searchText))
    );
  });
  return Promise.resolve(filtered);
};