| 1 | # Settings picker framework |
| 2 | |
| 3 | Shared settings-picker infrastructure for the underwater TUI lives in |
| 4 | `crates/tui/src/tui/settings_picker/`. |
| 5 | |
| 6 | ## What it owns |
| 7 | |
| 8 | - Option catalog with **current / default / effective**, availability + disabled |
| 9 | reason, help/detail, optional per-item actions, and narrow-layout preference |
| 10 | - Tab + search filtering with **stable visible indices** |
| 11 | - Keyboard nav (↑/↓/Home/End/digits/Tab), Esc cancel, Enter commit |
| 12 | - Nav-level **preview → commit → cancel** lifecycle via `PickerNavResult` |
| 13 | - Responsive list/detail via `SettingsPickerLayout` (side-by-side when wide; |
| 14 | stacked or list-only when narrow) |
| 15 | |
| 16 | Ocean chrome (swatches, underwater surface paint, locale copy) stays in each |
| 17 | concrete picker so shared contracts do not flatten visual character. |
| 18 | |
| 19 | ## Migration status |
| 20 | |
| 21 | | Picker | Status | |
| 22 | |--------|--------| |
| 23 | | `/theme` | Migrated — uses `SettingsPickerController` + `handle_nav_key`; keeps swatches and live preview | |
| 24 | | `/model` | Hook ready — leave full migration to TUI-DOG-009 sibling (truthful availability / performance) | |
| 25 | | `/provider` | Hook ready — same sibling; do not rewrite while availability work is open | |
| 26 | | Fleet setup | Framework only — billing/Fleet UX sibling owns flow rewrites | |
| 27 | |
| 28 | ## How to plug in |
| 29 | |
| 30 | ```rust |
| 31 | use crate::tui::settings_picker::{ |
| 32 | SettingOption, SettingsPickerController, SettingsPickerLayout, |
| 33 | handle_nav_key, PickerNavResult, |
| 34 | }; |
| 35 | |
| 36 | let mut controller = SettingsPickerController::new(options, original_id); |
| 37 | let result = handle_nav_key(&mut controller, key, /* allow_search_typing */ true); |
| 38 | match result { |
| 39 | PickerNavResult::Preview => { /* emit persist:false preview */ } |
| 40 | PickerNavResult::Commit => { /* emit persist:true and close */ } |
| 41 | PickerNavResult::Cancel => { /* rollback + close */ } |
| 42 | _ => {} |
| 43 | } |
| 44 | let layout = SettingsPickerLayout::resolve(area, 34, controller.selected_option()); |
| 45 | ``` |
| 46 | |
| 47 | Matrix coverage lives in `settings_picker` unit tests: normal, narrow, disabled, |
| 48 | filtered, previewed, and reverted. |
| 49 | |
| 50 | ## Typed Settings editor |
| 51 | |
| 52 | The complete application Settings editor is `ConfigView` in |
| 53 | `crates/tui/src/tui/views/mod.rs`. It is reachable through `F2`, bare |
| 54 | `/settings`, bare `/config`, and command discovery. `/settings text` preserves |
| 55 | the legacy plain-text diagnostic for headless and compatibility use. |
| 56 | |
| 57 | Its `SettingsRegistry` classifies every row as Boolean, choice, integer, text, |
| 58 | action, or read-only while retaining the row's category and session/saved |
| 59 | scope. Boolean rows toggle with Space or Enter; bounded choices use the chooser; |
| 60 | provider/model actions open their full pickers; integer/text rows use the inline |
| 61 | editor. Typing filters the full list, and mouse selection/activation mirrors the |
| 62 | keyboard paths. Setting labels come from the locale packs; raw config keys stay |
| 63 | visible in edit/detail surfaces for diagnostics and compatibility. |
| 64 |