Grok 4f58ee9f2d ui: integrate base indicator into main wide display row + full width span

- Refactored View() display to a single wide row inside the LCD panel:
  - Leading base indicator on the left: [BIN], [HEX], etc. (flashes on successful cycle)
  - Number (or CERR) right-aligned in the remaining maximal width (spans full available inside the card)
  - LCD container uses full dispW (based on terminal width) + vertical padding for visual weight
  - CERR still flashes the number slot (base label remains visible on left)
- Keypad grid and hint now also respect the wide dispW and are centered under the display
- Updated docs/UI_DESIGN.md and ARCHITECTURE.md with the new integrated layout (replaced old separate two-row description and ASCII)
- Matches user request: main display spans full maximal width; base begins the main display row (e.g. [ [BIN] [              3465... ] ] inside the panel)

This is iterative polish on the phase 3 spike. Paper trail updated.

2026-06-06 14:43:08 +01:00

5.3 KiB

Raw Blame History

Gralculator Architecture

Overview

Gralculator is a terminal UI calculator inspired by the visual density and layout of galculator (GTK), but adapted for Bubble Tea + lipgloss in a keyboard-first, content-centered style consistent with the gostations project.

Core philosophy for v0.1 (MVP):

All math is performed in decimal (float64 for simplicity).
Display bases (DEC/HEX/BIN/OCT) are purely for formatting the current value in the large display area.
A single "BASE" action (on-screen button + Tab key) cycles the display format: DEC → HEX → BIN → OCT → DEC.
Non-integer values cannot be displayed in non-DEC bases. Pressing BASE on a fractional result triggers a brief "CERR" (conversion error) flash in the large display and leaves the base unchanged. This is an explicit design choice over galculator's silent truncation.
Future iterations will add full hex digit entry (A-F), at which point letter keys will be reserved. This is why Tab was chosen for BASE cycling instead of a letter key.

Package Structure

internal/calc — Pure Go calculation engine. No TUI dependencies. Handles value state, pending operations, base cycling with integer checks, formatting, and arithmetic (+ - * / MOD). Fully unit-testable.
internal/ui — Bubble Tea model, view, and update logic. Renders the integrated wide display row (base indicator at start of the row like [BIN], followed by maximal-width right-aligned number) + keypad grid. Reuses lipgloss patterns, centering (Place), subtle borders, flash animations (tea.Tick + 140ms color 63 style), and content-sized card layout refined in gostations. The display spans full available width inside the card.
internal/version — Version string injection (ldflags), matching gostations.
main.go — Entry point, flags (-v), tea.NewProgram wiring, pre-flight checks if any.
Root: spec.md (living high-level spec), docs/ (detailed architecture and design notes), Makefile, .gitignore.

Key Design Decisions (v0.1)

Internal representation: float64 + pending operator state (classic four-function calculator model). Simpler and sufficient for MVP. Floating-point MOD via math.Mod.
Base handling: CycleBase() returns error/sentinel on non-integer to drive UI "CERR" flash. CurrentBase() and FormatForDisplay() for the view. No base-aware digit entry yet (reserved for future hex support).
Error on conversion: When value has fractional part and BASE is pressed, large display shows "CERR" briefly (~600ms with flash styling), base does not change, then reverts to previous formatted value.
Single BASE key: Reduces rendered keys. On-screen button labeled "BASE". Direct key is Tab (chosen to leave A-F free for future hex digits).
Display layout:
- Integrated main display row inside bordered LCD panel: base indicator (e.g. [BIN]) at the left of the row, followed by the number right-aligned and spanning the maximal remaining width. Vertical padding on the container gives visual weight. (Updated from earlier separate two-row design.)
- Small bottom row inside the same panel showing only the current base ("DEC", "HEX", "BIN", or "OCT"), highlighted when active.
Keypad: Sparse 4-5 column grid for MVP (digits, operators, MOD, C, AC, single BASE button). Uses the same makeButton + Width().Align(Center) lipgloss idiom as gostations playback controls.
Card layout: Entire UI is a content-sized, centered card (lipgloss.Place + rounded outer border color 63). Matches gostations Winamp-style player polish (subtle inner 238 borders, no stretching).
Feedback: 140ms timed flashes (color 63 bg + white fg bold) on key actions, exactly as tuned for volume/skip/stop in gostations.
Hint row: Minimal, non-wrapping, full-width (like final gostations player).
No persistence / config in v0.1: Session-only current base.
Testing: Engine has high-value unit tests (especially the CERR path). UI tests will focus on rendering and key-driven state transitions.
Future-proofing notes:
- Hex entry (A-F) planned for later release → letter keys kept free.
- Scientific functions, memory, %, bitwise, word size, RPN, history, etc. explicitly deferred.
- Potential later addition of clipboard, persistent settings (XDG), scripting subcommand.

Build & Integration

Matches gostations conventions: make build, make install (to ~/.local/bin/gralculator), cross-compile support, ldflags for version.
Binary name: gralculator
Will eventually be wired into the personal REXX ~/.local/bin/apps launcher (likely a new letter or replacement for the current "l. Terminal Calculator" / tcalc entry).
Go 1.24+ (consistent with other apps/ projects).

References

Root spec.md — original living specification and iteration history.
gostations (apps/gostations) — primary source for TUI patterns, lipgloss idioms, centering, flashes, Makefile, release hygiene, todo/ process (to be adopted later).
galculator GTK screenshot — primary visual reference for the "large number + small mode row" display density.

5.3 KiB Raw Blame History