Single-Page Client Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Single-Page Client Architecture of the Calculator project is a self-contained web application delivered via a single HTML file. It integrates structural markup, complex CSS-driven design tokens for theming, and a centralized JavaScript state machine to handle arithmetic logic and user interactions without requiring server-side processing or external dependencies.
This architecture prioritizes immediate responsiveness and accessibility, utilizing native browser APIs for event handling, accessibility (ARIA), and persistent UI states like the calculation history. The entire application logic resides within the client-side script, ensuring full functionality in offline environments.
Component Overview
The application is structured into three primary architectural layers: the UI Layout, the Style Engine (Design Tokens), and the Logic/State Controller.
| Component | Description | Reference |
|---|---|---|
| Header | Contains the application branding and the theme toggle interface. | calculator.html:255-271 |
| Display | High-precision visual output area showing current expressions and results. | calculator.html:277-280 |
| Button Grid | Event-driven input matrix categorized by numbers, operators, and functions. | calculator.html:283-308 |
| History Panel | Persistent list tracking the last 20 calculations performed during the session. | calculator.html:312-320 |
Sources: calculator.html:255-320
State Management and Data Flow
The application maintains a centralized state to track current inputs and pending operations. This state is updated through a series of helper functions that validate input before updating the DOM.
Central State Variables
current: The string representation of the current operand being typed.previous: The stored value of the first operand in a binary operation.operator: The active arithmetic operator (e.g., +, -, ×, ÷).shouldReset: A boolean flag determining if the next input should overwrite the current display.history: An array of objects storing{ expr, result }pairs.
Sources: calculator.html:332-337
Calculation Flow
The following diagram illustrates the sequence of events when a user performs a calculation:
The flow ensures that the internal state remains synchronized with the visual display while maintaining a non-volatile record of operations in the history panel.
Sources: calculator.html:362-416, calculator.html:438-466
Arithmetic Logic Engine
The core logic is handled by the compute function, which performs binary operations and incorporates safety checks for edge cases such as division by zero.
Logic Functions
compute(a, b, op): Executes the basic math operations. Returns "Error" if a division by zero is attempted.round(n): Limits precision to 12 digits usingtoPrecision(12)to prevent floating-point representation errors common in JavaScript.formatNum(n): Handles localization and scientific notation for numbers exceeding $10^{12}$ or smaller than $10^{-6}$.
Sources: calculator.html:383-398, calculator.html:340-355
Design System and Theming
The architecture utilizes CSS Custom Properties (Design Tokens) defined within the :root and [data-theme="dark"] selectors. This allows for an instantaneous theme switch by toggling a single attribute on the <html> element.
The toggle logic also detects the user's system preference via prefers-color-scheme during initialization to set the default state.
Sources: calculator.html:11-105, calculator.html:484-500
Event Handling Architecture
The application implements event delegation for the button grid and a global listener for keyboard support.
Interaction Handlers
- Grid Delegation: Listens for clicks on
.btn-gridand usesdata-actionattributes to route commands toinputDigit,handleOp, orhandleEquals. - Keyboard Mapping: Maps physical keys to calculator functions (e.g.,
Entermaps tohandleEquals,EscapetohandleClear). - History Interaction: Each item in the history list is interactive; clicking a past result sets it as the
currentstate for further calculations.
Sources: calculator.html:469-481, calculator.html:502-517, calculator.html:452-457
Summary
The Calculator's Single-Page Client Architecture provides a robust, zero-dependency environment for mathematical operations. By centralizing state management and utilizing CSS variables for theming, the application achieves high performance and maintainability within a single source file. Key features include floating-point precision management, a 20-entry calculation history, and comprehensive keyboard accessibility.