Option groups, separators and disabled options

The choice widgets - select and search, single-choice or with ->multiple() - accept more than a flat list. Alongside the ->options(['value' => 'Label']) map shorthand, you can declare options one at a time, mark them disabled, and add non-selectable structure.

$p->select('item', 'Item')
  ->heading('Fruit')            // A non-selectable group heading.
  ->option('apple', 'Apple')    // value => label
  ->option('banana', 'Banana')
  ->separator()                 // A non-selectable divider row.
  ->heading('Vegetable')
  ->option('carrot', 'Carrot')
  ->option('rhubarb', 'Rhubarb', disabled: TRUE, disabled_reason: 'out of season');

Runnable scripts: playground/02-widgets/select-groups.php and select-multiple-groups.php.

Builder methods

Name	Description
`option($value, $label = '', ...)`	Add one selectable row. The label defaults to the value; re-declaring a value replaces it in place. Pass `disabled: TRUE` (with an optional `disabled_reason`) to show it but block selection.
`options([$value => $label])`	Add many selectable rows from a map - shorthand for repeated `option()`.
`heading($label)`	Add a non-selectable group-heading row.
`separator()`	Add a non-selectable divider row.

Behaviour

Headings, separators and disabled options are visual only: navigation skips them, so the cursor lands only on selectable options, and they can never be highlighted or selected. A disabled option shows its reason beside the label, dimmed. Every kind is theme-driven - override heading(), divider() or disabled() on a theme to restyle it.

Non-selectable rows never leak into the answer: a disabled value is dropped from a multiple-choice default, absent from the collected value, and excluded from the JSON schema (Tui::schema() lists selectable options only). Supplying a disabled

or otherwise unknown - option value headlessly (via --prompts JSON or an environment override) fails collection with a clear error naming the value.