From 4df99d07389474db42bfb8322e17c3f130b689f5 Mon Sep 17 00:00:00 2001 From: MatMoul Date: Sat, 16 May 2026 05:01:17 +0200 Subject: [PATCH] docs: update README for default demo and command aliases --- .memory/state.md | 7 +- README.md | 35 +++--- README.tmp.md | 289 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 310 insertions(+), 21 deletions(-) create mode 100644 README.tmp.md diff --git a/.memory/state.md b/.memory/state.md index ab8a5cf..ccb6647 100644 --- a/.memory/state.md +++ b/.memory/state.md @@ -1,9 +1,8 @@ # State - Core engine: `src/rpn-calculator.js` -- Active demo: `samples/calc-02/` portrait-only HP48GX layout; display-adjacent button row stays in 4 columns and now shares the same base button styling as the function keys -- Mode button shows the current angle mode only; selecting a mode uses a popup menu +- Default demo: `samples/dev/` classic browser demo; `samples/calc-02/` remains the portrait-first HP48GX-inspired reference - Public API: `push`, `pop`, `clear`, `swap`, `remove`, `edit`, `isValidIndex`, `input`, `command`, `getOperationsByCategory`, `getConstants`, `listConstants`, `setConstant`, `removeConstant`, `hasConstant` - Config: `maxSize`, `base`, `angleMode`, `enabledCommands` -- Commands: arithmetic, stack, trigonometry, constants `pi`, `e`, `phi`, `g`, and `c`; arithmetic now includes `root` for y-th roots; constants can now be added or removed dynamically through the core API -- Demo actions: keyboard focus is kept on the hidden input on desktop so typing keeps working; the keypad layout places Enter in the bottom-left, ± in the former Enter position, and Esc before Clear for safety; paste parses clipboard text as a number before pushing it to the stack; Ctrl+V is supported via the hidden input paste event; backspace is ignored when the stack is empty; operation errors are shown as an overlay bar on top of the calculator with a shorter timeout and darker red; the display button row uses a 4-column grid with a spacer cell to preserve alignment +- Commands: arithmetic, stack, trigonometry, constants `pi`, `e`, `phi`, `g`, and `c`; arithmetic includes `root` with `y√x`, `yroot`, and `nroot` aliases; constants can be added or removed dynamically through the core API +- Demo behavior: `samples/dev/` keeps hidden input focus on desktop and supports clipboard paste; `samples/calc-02/` uses compact mode/constants popups, a 4-column display-adjacent row, stack selection/move mode, and paste through the hidden input - Exports: browser `window.RpnCalculator`, CommonJS `module.exports` diff --git a/README.md b/README.md index 864fed1..7cedfbd 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,16 @@ # RPN Virtual Calculator -A browser-friendly RPN calculator built around a small, generic JavaScript API. +A browser-friendly RPN calculator built around a small JavaScript API. ## Overview This project provides: - a reusable JavaScript RPN engine in `src/rpn-calculator.js` -- browser demos in `samples/dev/` and `samples/calc-02/` -- a command system centralized in a single operation dictionary -- a small public API focused on stack operations and generic command dispatch +- a classic browser demo in `samples/dev/` +- a portrait-first HP48GX-inspired demo in `samples/calc-02/` +- a centralized command system with aliases +- a compact public API focused on stack operations, editing, and command dispatch The main class is `RpnCalculator`. @@ -19,9 +20,6 @@ The main class is `RpnCalculator`. - `samples/dev/index.html`: browser demo entry point - `samples/dev/index.css`: demo styles - `samples/dev/index.js`: demo UI and keyboard logic -- `samples/calc-01/index.html`: active browser demo entry point -- `samples/calc-01/index.css`: demo styles -- `samples/calc-01/index.js`: demo UI and keyboard logic - `samples/calc-02/index.html`: portrait-first HP48GX-style demo entry point - `samples/calc-02/index.css`: portrait-first demo styles - `samples/calc-02/index.js`: portrait-first HP48GX-style demo UI and keyboard logic @@ -68,10 +66,10 @@ State exposed on instances: ```js README.md const calc = new RpnCalculator({ - maxSize: 2048, - base: 10, - angleMode: 'deg', - enabledCommands: ['add', 'sub', 'mul', 'div'] + maxSize: 2048, + base: 10, + angleMode: 'deg', + enabledCommands: ['add', 'sub', 'mul', 'div'] }); ``` @@ -88,6 +86,9 @@ Available constants: - `pi` - `e` +- `phi` +- `g` +- `c` - plus any user-defined constants added through the engine API They can be used through `command(...)`: @@ -194,10 +195,10 @@ console.log(calc.pop()); // 5 ```html README.md ``` @@ -239,7 +240,7 @@ console.log(calc.pop()); // 0.5 ## Demo -The active demo lives in `samples/dev/`. +The default demo lives in `samples/dev/`. Main UI features: @@ -249,7 +250,7 @@ Main UI features: - angle mode selector for `deg`, `rad`, and `grad` - status pills for `inputValue` and `isEditing` - grouped panels for `Stack`, `Arithmetic`, `Trigonometry`, and `Constants` -- error display area +- keyboard-friendly hidden input on desktop ## Calc 02 demo diff --git a/README.tmp.md b/README.tmp.md new file mode 100644 index 0000000..7cedfbd --- /dev/null +++ b/README.tmp.md @@ -0,0 +1,289 @@ +# RPN Virtual Calculator + +A browser-friendly RPN calculator built around a small JavaScript API. + +## Overview + +This project provides: + +- a reusable JavaScript RPN engine in `src/rpn-calculator.js` +- a classic browser demo in `samples/dev/` +- a portrait-first HP48GX-inspired demo in `samples/calc-02/` +- a centralized command system with aliases +- a compact public API focused on stack operations, editing, and command dispatch + +The main class is `RpnCalculator`. + +## Project structure + +- `src/rpn-calculator.js`: calculator engine +- `samples/dev/index.html`: browser demo entry point +- `samples/dev/index.css`: demo styles +- `samples/dev/index.js`: demo UI and keyboard logic +- `samples/calc-02/index.html`: portrait-first HP48GX-style demo entry point +- `samples/calc-02/index.css`: portrait-first demo styles +- `samples/calc-02/index.js`: portrait-first HP48GX-style demo UI and keyboard logic +- `samples/calc-XX/`: placeholder name for future demo variants + +## Public API + +The calculator API is centered on these methods: + +- `push(value)` +- `pop()` +- `clear()` +- `swap(index1, index2)` +- `remove(index)` +- `edit(index)` +- `isValidIndex(index)` +- `input(command)` +- `command(name, ...args)` + +Instance helpers also available: + +- `getOperationsByCategory()` +- `getConstants()` +- `listConstants()` +- `setConstant(name, value)` +- `removeConstant(name)` +- `hasConstant(name)` + +Static helpers also available: + +- `RpnCalculator.getOperationCategories()` +- `RpnCalculator.getOperationsByCategory()` + +State exposed on instances: + +- `inputValue` as a string +- `isEditing` as a boolean +- `stack` as the current internal stack array used by the demo +- `angleMode` +- `base` +- `maxSize` + +## Constructor options + +```js README.md +const calc = new RpnCalculator({ + maxSize: 2048, + base: 10, + angleMode: 'deg', + enabledCommands: ['add', 'sub', 'mul', 'div'] +}); +``` + +Supported options: + +- `maxSize`: maximum stack size, default `2048` +- `base`: numeric base, default `10`, accepted range `2..16` +- `angleMode`: `deg`, `rad`, or `grad`, default `deg` +- `enabledCommands`: optional whitelist of enabled commands and aliases + +## Constants + +Available constants: + +- `pi` +- `e` +- `phi` +- `g` +- `c` +- plus any user-defined constants added through the engine API + +They can be used through `command(...)`: + +```js README.md +calc.command('pi'); +calc.command('e'); +``` + +## Supported commands + +### Stack + +- `enter` +- `dup` +- `drop` +- `swap` +- `clear` + +### Arithmetic + +- `add` alias: `+` +- `sub` alias: `-` +- `mul` alias: `*` +- `div` alias: `/` +- `mod` alias: `%` +- `pow` aliases: `^`, `y^x` +- `root` aliases: `y√x`, `yroot`, `nroot` +- `sqr` +- `neg` +- `sqrt` alias: `sqrt(x)` +- `recip` alias: `1/x` +- `log` +- `ln` + +### Trigonometry + +- `sin` +- `cos` +- `tan` +- `asin` +- `acos` +- `atan` + +## Behavior notes + +- `mod` is a percentage operator: + - `a b % => (a * b) / 100` +- `pow` accepts aliases `^` and `y^x` +- `sqrt` accepts alias `sqrt(x)` +- `recip` accepts alias `1/x` +- `div` and `recip` throw `Division by zero` when needed +- `root` computes the y-th root as `x^(1/y)` and throws `Invalid input for root` for invalid inputs +- `sqrt` throws `Invalid input for sqrt` for negative values +- `asin` and `acos` throw explicit domain errors outside `[-1, 1]` +- `log` throws `Invalid input for log` for values `<= 0` +- `ln` throws `Invalid input for ln` for values `<= 0` +- `log` uses `Math.log10` +- `ln` uses `Math.log` +- direct trigonometric functions convert input using `toRadians(...)` +- inverse trigonometric functions convert results back using the current angle mode +- `angleMode` supports `deg`, `rad`, and `grad` +- formatted numeric values are rounded to 12 decimal places +- `-0` is normalized to `0` +- `inputValue` remains a string to preserve future non-decimal input support +- base 10 input is parsed with `Number(...)` +- non-decimal input currently uses `parseInt(..., base)` + +## Input handling + +`input(command)` supports two modes: + +- single-character editing input +- command dispatch + +Accepted single-character editing input currently includes: + +- `0-9` +- `A-F` +- `a-f` +- `+` +- `-` +- `.` + +Everything else is forwarded to `command(...)`. + +## Basic usage + +### CommonJS + +```js README.md +const RpnCalculator = require('./src/rpn-calculator'); + +const calc = new RpnCalculator(); +calc.push(2); +calc.push(3); +calc.command('add'); + +console.log(calc.pop()); // 5 +``` + +### Browser + +```html README.md + + +``` + +### Editing values through `input(...)` + +```js README.md +const calc = new RpnCalculator(); + +calc.input('1'); +calc.input('2'); +calc.input('.'); +calc.input('5'); +calc.command('enter'); + +console.log(calc.pop()); // 12.5 +``` + +### Aliases + +```js README.md +const calc = new RpnCalculator(); +calc.push(6); +calc.push(7); +calc.command('+'); +console.log(calc.pop()); // 13 +``` + +### Constants and trigonometry + +```js README.md +const calc = new RpnCalculator({ angleMode: 'deg' }); +calc.command('pi'); +console.log(calc.pop()); + +calc.push(30); +calc.command('sin'); +console.log(calc.pop()); // 0.5 +``` + +## Demo + +The default demo lives in `samples/dev/`. + +Main UI features: + +- four visible stack lines +- main display/status area +- visible angle mode indicator +- angle mode selector for `deg`, `rad`, and `grad` +- status pills for `inputValue` and `isEditing` +- grouped panels for `Stack`, `Arithmetic`, `Trigonometry`, and `Constants` +- keyboard-friendly hidden input on desktop + +## Calc 02 demo + +`samples/calc-02/` is a portrait-first HP48GX-inspired demo. +It keeps the display-adjacent button row aligned in four columns, uses compact popup menus for mode and constants, and supports clipboard paste plus the `y√x` root operation. + +The demo loads the engine from: + +```html README.md + +``` + +### Demo keyboard support + +The current demo supports: + +- digits and decimal point +- numpad digits and numpad arithmetic keys +- `Enter` +- `Backspace` +- `Delete` +- `Escape` +- `ArrowUp`, `ArrowDown`, `ArrowRight` +- `+`, `-`, `*`, `/`, `%`, `^` +- `q`, `n`, `r`, `i`, `g`, `l`, `s`, `c`, `S`, `C` +- `x`, `y`, `z`, `t` + +The demo also implements stack selection and stack-item move mode in its UI layer using the public calculator methods. +It keeps the calculator screen focused and updates the visible stack window as the selection moves. + +## Exports + +`RpnCalculator` is exposed in both environments: + +- browser: `window.RpnCalculator` +- CommonJS: `module.exports = RpnCalculator`