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.