The UI section lists Model's components and what each owns, the overlay interface, how the screen is composed, runCommand as the one place commands run, and the leaf packages theme, rowtext and formula.
- commit
- f68a7c7001ecee13edc472022402322250208c0a
- parent
- a7f1d8f32bb082194a510374a5f751ef36c51001
- author
- Dami <dami.etoile@gmail.com>
| M | docs/ | 65 | +++++++++++++++++++++++++----- |
@@ -10,6 +10,9 @@ internal/fileio import and export: CSV, TSV, XLSX, SQLite, Parquet, Lotus .wk1
1010 internal/chart chart layout, text rendering and kitty image encoding1111 internal/jev JEV configuration, answer cache and TypeSafe client1212 internal/ui the Bubble Tea model: modes, menus, overlays, rendering13+ theme style roles and the widgets drawn with them (frames, key chips)14+ rowtext laying out a row of cell text across the columns on screen15+ formula reading the formula being typed (F4, the word and call at the caret)1316 e2e/ end-to-end tests through libghostty (separate module, cgo)1417 oracle/ differential tests against excelize (separate module)1518 ```@@ -49,17 +52,59 @@ its computed value, and its format and style.
4952 5053 ## The UI5154 52-`internal/ui` is one Bubble Tea model. Inside the grid it follows Google53-Sheets; around it, the control panel keeps a 1-2-3 look. Every action is a54-registered command with a title and description, reached from key bindings,55-the menu bar, context menus, the command palette and the help overlay, so56-they can't disagree. Menus, the palette and pickers are overlays composited57-with Lip Gloss layers over the grid, which never shifts under them. Only the58-visible cells are rendered. Styles come from a small set of theme roles59-with dark and light variants built on the terminal's 16 ANSI colors, so the60-user's palette applies.55+`internal/ui` is a Bubble Tea program. Inside the grid it follows Google56+Sheets; around it, the control panel keeps a 1-2-3 look. See57+[UX.md](UX.md) for the rules every change follows.6158 62-See [UX.md](UX.md) for the rules every change follows.59+**Commands.** Every action is a registered command with a title and60+description (`commands.go`), reached from key bindings, the menu bar,61+context menus, the command palette, the help overlay and mouse gestures62+that stand for one (double-clicking a tab renames it through63+`sheet.rename`), so they can't disagree. `runCommand` is the one place a64+command runs: telemetry times it there, and a command log or macro65+recorder would attach there.66+67+**Model and components.** `Model` (`model.go`) is the root: it holds the68+file, the mode and the note on the context line, owns one component for69+each thing that takes input or draws part of the screen, routes each70+message to the component it's for, and composes the screen from what they71+draw. The components:72+73+| Component | Type | Owns |74+|---|---|---|75+| grid (embedded) | `grid` | the sheet shown, active cell, scroll, window size, selection; mapping rows and columns to the screen, frozen panes, moving and selecting (`grid.go`, `panes.go`, `selection.go`) |76+| edit line | `lineEdit` | the one-line editor shared by cell entries, prompts and search fields (`line.go`) |77+| cell entry | `entry`, `assist` | typing into a cell, pointing at references, other sheets while pointing, formula suggestions and signatures (`entry.go`, `assist.go`) |78+| prompt | `prompt` | a question on the context line, typed or pointed at (`prompt.go`) |79+| overlays | `overlay` | whatever has taken over input: menus (`menuoverlay.go`), the palette and pickers (`palette.go`, `names.go`), the filter picker, the find, sort and choice bars, the chart editor and selection, the shortcuts |80+| sheet tabs | `tabStrip` | where each sheet was left, the tab strip's scroll, layout and clicks (`tabstrip.go`) |81+| mouse | `mouseState` | drags, hover, double clicks, the fill handle (`mouse.go`, `fill.go`) |82+| import | `transfer` | the import in progress, its progress display and cancelling (`transfer.go`) |83+| others | `clipboard`, `trace`, `chartState`, `jevRunner`, `terminal` | what Ctrl+V pastes, a trace being shown, chart commands' target, JEV questions in flight, what the terminal supports and the chart images sent to it |84+85+Overlays implement the `overlay` interface (`overlay.go`): an indicator86+for the mode, `key` and `mouse` handlers, a `layout` of boxes to draw, and87+the status line while open; bars on the context line add a88+`contextLine`, and those with a text field a `cursor`. Like `assist` and89+`prompt`, they are handed the model when they handle input, since acting90+on it is their job. A new overlay is a new type; `Model` needs no new91+fields, only a way to open it (usually a command).92+93+**Drawing.** `View` (`panel.go`) stacks the control panel, the header,94+the grid rows and the status line, then composites the floating layers95+with Lip Gloss: charts over the grid, then the open overlay's boxes or the96+formula suggestions, so the grid never shifts under them. Only the visible97+cells are rendered; `rowtext` lays out each row's text in one pass over98+the cells that can reach the screen. Styles come from `theme`, a small set99+of roles with dark and light variants on the terminal's 16 ANSI colors,100+so the user's palette applies; its widgets (framed boxes, key chips, key101+hints) are what every overlay is drawn with.102+103+**Packages.** `theme`, `rowtext` and `formula` depend on nothing in104+`ui`, so they can be tested and measured alone. The components stay in105+package `ui` because they act on the model; moving them out would mean106+exporting most of it. New leaf packages are split off the same way when107+a part needs only the sheet or the theme.63108 64109 ## Testing65110