gralculator/docs/UI_DESIGN.md

# Gralculator UI Design

## Display (Two-Row Layout)
Directly inspired by the galculator GTK reference screenshot, simplified for terminal realities and single-BASE cycling.

Inside a single bordered "LCD" panel (dark background ~235, green/high-visibility foreground ~46 for the number, subtle inner NormalBorder color 238):

- **Large top area**: The current numeric value. Strong visual weight via extra vertical padding/height (e.g. 3-5 lines effective), bold styling, generous font-like sizing through lipgloss. Right-aligned or centered as appropriate for the base (DEC often right, hex/bin may vary). Large enough to feel like the "big number" in galculator.

- **Small bottom row**: Directly under the number, still within the same panel. Shows only the *current* base label: `DEC`, `HEX`, `BIN`, or `OCT`. The active one is highlighted (bold + background color 63 or accent green, matching gostations key badges and outer border color). No full row of four selectable bases — the single BASE action handles cycling.

Example (ASCII approximation of rendered view):

```
+--------------------------------------------------+
|                                                  |
|                   1234.56                        |  <-- large number area
|                                                  |
|                       DEC                        |  <-- small current-base row (highlighted)
+--------------------------------------------------+
```

When a non-integer conversion is attempted (e.g. 3.833... + BASE), the *large number area* temporarily renders "CERR" (with the 140ms + color 63 flash/blink style used for volume/skip/stop feedback in gostations). After the flash duration (~600ms), it reverts to the previous value in the unchanged base. The small row never changes on error.

## Keypad Grid
Sparse for MVP (no memory, no %, no bitwise, no scientific, no A-F yet).

Uses the same button-cell rendering idiom as gostations `renderPlayback` / `makeButton`:

- `lipgloss.NewStyle().Width(5).Align(lipgloss.Center).Padding(0,1).Render(label)`
- Active/pressed state uses green accent or the flashStyle (white on 63 bg, bold).
- Flash on every key action using `tea.Tick` + clearFlashMsg (140ms), exactly as tuned in gostations player.

Layout sketch (subject to refinement during spike; 4-5 columns typical):

```
  7  8  9  /  MOD
  4  5  6  *  C
  1  2  3  -  AC
  0  . +/-  +  =
         BASE
```

(Or tighter grouping. BASE is prominent because it is the distinctive "programmer display" feature.)

All important actions have direct keys (digits, operators, =/Enter, Backspace, Tab for BASE, c/C, etc.). The on-screen buttons are primarily visual + mouse targets.

## Overall Card & Polish
- The entire calculator is wrapped in a **content-sized centered card**:
  - Outer rounded border (color 63, matching gostations label/border).
  - `lipgloss.Place(width, height, lipgloss.Center, lipgloss.Center, card)`
  - No stretching to full terminal width (important lesson from gostations player polish).
- Subtle inner borders on panels where depth helps.
- Minimal non-wrapping hint row at bottom of window (lipgloss bar with key badges in 63 bg, like final gostations player): e.g. "Tab:BASE  q:quit  etc."
- Resize handling: card recenters; display and grid adapt gracefully (minimum sensible width enforced with a message if too narrow).
- Consistent dark theme, green LCD accents, flash feedback.

## Rendering & State
- UI owns transient state: current flashes, window size, focus hints.
- Engine (`internal/calc`) is queried for `FormatForDisplay()`, `CurrentBase()`, and mutated via `CycleBase()`, digit entry, operators, etc.
- View is mostly custom (JoinVertical/JoinHorizontal + lipgloss styles). Minimal use of bubbles components for MVP (possible list or table later if keypad grows).
- Update dispatches keys → engine calls + flash triggers. Tab always cycles (global, like q/quit).

## Mouse (Bonus)
Bubble Tea mouse support will be wired so clicking a rendered button cell triggers the same action as its key. Not required for first working spike.

## References & Constraints
- Must feel like the top half of the provided galculator screenshot (large number + small mode indicator) while staying practical in 80-120 col terminals.
- Reuse every hard-won gostations pattern: lipgloss.Place centering, inner 238 borders, makeButton cells, 140ms color-63 flashes, hint bar, content-sized card, tea.Tick clear messages.
- Keep the TUI responsive and fun even in the minimal keypad state.

See `spec.md` (root) for full scope and `ARCHITECTURE.md` for package and decision rationale.
---
*Created during phase 1 skeleton, 2026.*