Calculator User Guide
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Calculator is a web-based application designed to provide a modern, responsive, and accessible interface for performing basic arithmetic operations. It features a clean UI with support for dark mode, calculation history, and keyboard shortcuts, making it a versatile tool for desktop and mobile environments.
The system is built as a single-page application using standard web technologies: HTML5, CSS3 (utilizing modern features like CSS variables and oklch colors), and vanilla JavaScript. Its primary scope is to handle real-time mathematical expressions while maintaining a persistent session history of previous calculations.
Sources: calculator.html:1-380, README.md
User Interface and Design
The application utilizes a responsive layout with a centralized calculator card and a supplementary history panel. The design leverages modern CSS tokens for theming and fluid typography to ensure readability across different device sizes.
Display Components
The display area is split into two primary regions to provide feedback on current input and overall expression state:
- Expression Display (
#expr): Shows the current mathematical sequence being calculated (e.g., "5 + 10"). - Main Display (
#display): Shows the current input digit or the final result of an operation. It includes a "pop" animation when results are calculated.
Sources: calculator.html:128-149, calculator.html:438-444
Theme Support
The application supports Light and Dark modes. The theme can be toggled manually via the UI or follows the system preference automatically.
| Theme Attribute | Light Mode Value | Dark Mode Value |
|---|---|---|
| Background | #f7f6f2 | #171614 |
| Primary Color | #01696f | #4f98a3 |
| Surface | #f9f8f5 | #1c1b19 |
| Sources: calculator.html:12-70 |
The following diagram illustrates the theme initialization and toggle logic:
Sources: calculator.html:565-578
Operational Logic
The calculator's core logic is managed through a state machine that tracks the current input, the previous value, and the active operator.
Core State Variables
The application maintains the following internal state:
current: The string representation of the current number being typed.previous: The value stored before an operator was selected.operator: The mathematical operation to be performed (+, −, ×, ÷).shouldReset: A boolean flag indicating if the next digit input should clear the current display (used after selecting an operator or equals).
Sources: calculator.html:383-388
Calculation Flow
When a user performs a calculation, the application follows a specific sequence to ensure precision and handle edge cases like division by zero.
Sources: calculator.html:436-492
Arithmetic Operations
Mathematical logic is implemented in the compute function, which handles floating-point arithmetic.
| Operation | Implementation Logic | Note |
|---|---|---|
| Addition | a + b | Rounded to 12 digits |
| Subtraction | a - b | Rounded to 12 digits |
| Multiplication | a * b | Rounded to 12 digits |
| Division | a / b | Returns 'Error' if b === 0 |
| Percent | current / 100 | Immediate conversion |
| Sign Toggle | current * -1 | Flips positive/negative |
| Sources: calculator.html:470-484, calculator.html:499-507 |
Calculation History
The history system stores the last 20 calculations. This information is rendered in a scrollable list below the calculator.
- Persistence: Calculations are added to the top of the list (
unshift). - Interaction: Clicking a history item restores that result as the
currentvalue in the calculator display. - Capacity: The list is capped at 20 items to prevent memory issues.
Sources: calculator.html:511-544
Keyboard Support
The application provides comprehensive keyboard mappings for accessibility and power users.
| Physical Key | Calculator Action |
|---|---|
0-9 | Input Digits |
. | Decimal Point |
+, -, *, / | Arithmetic Operators |
Enter or = | Calculate (Equals) |
Escape | All Clear (AC) |
Backspace | Delete last digit |
| Sources: calculator.html:551-562 |
Deployment and CI/CD
The project is configured for automated deployment via GitHub Actions.
- GitHub Pages: The site is automatically built and deployed to GitHub Pages.
- Workflow: The
pages.ymlworkflow manages the upload of thecalculator.htmlas the entry point for the static site.
Sources: .github/workflows/pages.yml, .gitignore
Conclusion
The Calculator project provides a robust implementation of a standard utility tool. By combining a modern CSS-driven UI with a precise JavaScript calculation engine, it ensures a high-quality user experience. The inclusion of history tracking and full keyboard support makes it a complete solution for basic mathematical needs within a web browser.
Sources: calculator.html:1-584