From 8ea601522388a852a0e80da73399ac84f77efce3 Mon Sep 17 00:00:00 2001 From: Grok Date: Sat, 6 Jun 2026 15:38:07 +0100 Subject: [PATCH] docs: add comprehensive README.md Covers essentials modeled after gostations: - Project description and galculator GTK inspiration - MVP features (decimal math, BASE cycling via Tab, CERR policy, MOD, display layout, tactile keypad) - Requirements - Install via one-liner release scripts (Linux/macOS + PowerShell) - Usage: display row, key bindings (Tab:BASE, m:MOD, Backspace:C, Del:AC, etc.) - Building from source (make build/install/test) - Development notes (links to spec.md, docs/ARCHITECTURE.md, docs/UI_DESIGN.md, workflows, engine/UI separation) - Ties to personal apps/ ecosystem and REXX launcher All naming is now consistently 'gralculator' (folder, binary, repo). --- README.md | 106 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..2c94732 --- /dev/null +++ b/README.md @@ -0,0 +1,106 @@ +# 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! \ No newline at end of file