gralculator/README.md

Gralculator

Gralculator — Greg's Calculator. A terminal UI calculator.

Portmanteau of "Greg" + "calculator". A fast, keyboard-centric TUI inspired by the visual layout of galculator (the GTK programmer's calculator), with a wide integrated display row and tactile keypad.

All calculations are performed in decimal. Display bases (DEC / HEX / BIN / OCT) are purely for formatting the current value. A single Tab (BASE) key cycles the display format. Non-integer values trigger a brief "CERR" (conversion error) flash instead of silently truncating.

Features (v0.1 MVP)

• Wide display row: [BASE] indicator on the left + large, right-aligned number area (LCD-style with green-on-dark styling and subtle borders).
• Base cycling via Tab (or the visual BASE key if present in your build).
• Core operations: + - * / and MOD (modulo).
• Clear controls: Backspace for Clear Entry (C), Delete for All Clear (AC).
• Decimal point, sign change (+/-), and standard digit entry.
• Tactile visual keypad: individually bordered buttons with color-coded groups (numbers, operators, clears, MOD, BASE), height for "key" feel, and press-flash feedback (bright 63 background).
• Minimal non-wrapping hint row at the bottom.
• Content-sized, centered card layout (no stretching) using lipgloss patterns refined in the gostations project.
• Pure, testable calculation engine (internal/calc) separate from the Bubble Tea UI.
• Cross-platform static binary.

Requirements

• Linux or macOS (Windows via installers or WSL)
• For running the binary: a modern terminal (kitty, WezTerm, Ghostty, etc. recommended for Unicode and color)
• For building from source: Go 1.24.2+

Install (for normal users)

The easiest way is the one-liner installer attached to each release:

Linux / macOS

curl -L https://repos.gmgauthier.com/gmgauthier/gralculator/releases/download/v0.1.0/gralculator-install.sh \
  | VERSION=0.1.0 bash

Windows (PowerShell) / macOS / Linux with PowerShell

irm https://repos.gmgauthier.com/gmgauthier/gralculator/releases/download/v0.1.0/gralculator-install.ps1 | iex

The installer:

• Detects your OS and architecture.
• Downloads the matching gralculator-OS-ARCH-vX.Y.Z.tar.gz (verifies checksum when possible).
• Installs the binary to ~/.local/bin/gralculator (.exe on Windows).
• Prints PATH advice if needed and runs gralculator -v.

After installation, just run gralculator.

Usage

Run with no arguments to launch the TUI.

Display

A single wide row inside a bordered LCD-style panel:

• Left: current base indicator (e.g. [DEC], [HEX], [BIN], or [OCT])
• Right: the current value, right-aligned and filling the available width

Keypad

Tactile visual buttons below the display (numbers, operators, MOD, C, AC, +/-, etc.). The BASE action is keyboard-driven via Tab (the visual button was removed in favor of a clean grid + hint).

Key Bindings

• Tab — cycle display base (DEC → HEX → BIN → OCT → DEC). Flashes "CERR" on the number area if the current value is non-integer.
• m / M — MOD (modulo)
• Backspace — Clear Entry (C)
• Delete — All Clear (AC)
• 0-9 — digits
• . — decimal point
• + - * / — operators
• = or Enter — equals / commit pending operation
• +/- — change sign
• q, Ctrl+C, Esc — quit

The hint row at the bottom always shows the essentials.

Building from Source

git clone https://repos.gmgauthier.com/gmgauthier/gralculator.git
cd gralculator
make build          # produces build/gralculator
make install        # installs to ~/.local/bin/gralculator
make test           # or make test-short

The Makefile supports cross-compilation (make cross), ldflags for version injection, and matches the conventions used by gostations and grokkit.

Development

• spec.md — living high-level specification and design decisions (MVP scope, CERR policy, single BASE cycle, etc.).
• docs/ARCHITECTURE.md — package structure, key decisions, and future-proofing notes.
• docs/UI_DESIGN.md — detailed notes on the display row, keypad styling, and rendering approach.
• Workflows in .gitea/workflows/ (CI on push/PR + release on v* tags) are modeled after gostations and grokkit.
• Pure engine in internal/calc/ (easy to test independently of the UI).
• UI in internal/ui/ uses Bubble Tea + lipgloss (reuses patterns from gostations: centered cards, button cells, 140 ms color-63 flashes, minimal hints).

The project is part of a personal collection of console apps (see the REXX ~/.local/bin/apps launcher). It is designed to be keyboard-primary and pleasant to use in a modern terminal.

License

See the UNLICENSE file (or equivalent in the root) for this personal project.

---

Built as an exercise in Bubble Tea TUI design, with heavy reuse of patterns from the gostations radio player. Feedback and iteration welcome!