# 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
```bash
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
```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

```bash
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!