@matrix/package-calculator

Calculator components for the Matrix framework - basic arithmetic operations with a beautiful UI.

Package Overview

This package provides a complete calculator implementation for the Matrix framework:

• calculator: A full-featured calculator component with basic arithmetic operations (add, subtract, multiply, divide)
• Digital Display: Classic calculator LCD-style display with green text
• Interactive UI: Responsive button layout with hover effects and proper styling
• State Management: Maintains calculation history and current state
• Error Handling: Handles division by zero and other edge cases

Development Workflow

Working on this Package

1. Source Location: /packages/package-calculator (this directory)
2. Production Location: /packages/matrix-repl-chat/packages/package-calculator (after deployment)
3. Deployment: Use npm run deploy:package-calculator from the demo-9 root

Development Commands

# Build this package locally
npm run build

# Run tests (if any)
npm test

# Generate code dump
npm run codedump

# Clean build artifacts
npm run clean

Deployment Process

IMPORTANT: When you make changes to this package, you must deploy them to the production location where the Matrix REPL loads them from:

# From the demo-9 root directory
npm run deploy:package-calculator

# Then build the deployed package
cd packages/matrix-repl-chat/packages/package-calculator
npm run build

Calculator Features

Arithmetic Operations

• Addition (+): Add two numbers
• Subtraction (−): Subtract second number from first
• Multiplication (×): Multiply two numbers
• Division (÷): Divide first number by second (with zero-division protection)

UI Features

• Digital Display: Black background with green LCD-style text
• Responsive Buttons: Grid layout with hover and active states
• Operation Feedback: Visual feedback for button presses
• Clear Function: Reset calculator to initial state
• Equals Processing: Complete pending operations

Event System

• CalculatorReady: Emitted when calculator initializes
• DisplayUpdated: Emitted when display value changes
• OperationSet: Emitted when an operation is selected
• EqualsComplete: Emitted when equals button completes calculation
• CalculatorCleared: Emitted when calculator is reset
• CalculationError: Emitted on errors (e.g., division by zero)

Installation

Using Matrix CLI (Recommended)

# Install from npm registry (when published)
matrix install --registry @matrix/package-calculator
matrix up package-calculator

# Install from local monorepo
matrix install --monorepo package-calculator
matrix up package-calculator

# Run directly from source (development)
matrix up --monorepo package-calculator

Traditional npm

npm install @matrix/package-calculator

Browser Usage

ES Module from CDN (Future)

// Load from unpkg or other CDN
await window.MatrixPackageRegistry.install({
  source: 'cdn',
  name: '@matrix/package-calculator',
  version: '1.0.0'
});

Current: Bundle Integration

<!-- Include the bundled package -->
<script src="/packages/package-calculator.bundle.js"></script>

<script type="module">
// Package auto-registers when loaded
// Or manually register components
window.MatrixPackageCalculator.registerCalculatorComponents(window.Matrix);
</script>

Direct Import (Build Tools)

import { registerCalculatorComponents, componentSources } from '@matrix/package-calculator/browser';

// Register all components with Matrix
registerCalculatorComponents(window.Matrix);

Server Usage

import { 
    CalculatorComponent
} from '@matrix/package-calculator';

// Components are automatically registered with matrix-cli

DSL Example

<calculator id="myCalculator" 
           onCalculatorReady="handleCalculatorReady"
           onDisplayUpdated="handleDisplayUpdate"
           onCalculationComplete="handleCalculationComplete"
           onCalculationError="handleCalculationError"
           emits="CalculatorReady,DisplayUpdated,CalculationComplete,OperationSet,EqualsComplete,CalculatorCleared,CalculationError">
</calculator>

Component Communication

The calculator uses event-driven communication:

Commands (Input)

• onNumberInput: Input a digit (0-9)
• onOperation: Set operation (add, subtract, multiply, divide)
• onEquals: Complete current calculation
• onClear: Reset calculator state
• onCalculate: Direct calculation with operation object

Events (Output)

• CalculatorReady: Calculator is initialized and ready
• DisplayUpdated: Display value has changed
• OperationSet: An operation has been selected
• EqualsComplete: Equals operation completed
• CalculatorCleared: Calculator was reset
• CalculationError: An error occurred (e.g., division by zero)

Architecture

The calculator follows Matrix framework patterns:

Component Structure

CalculatorComponent (Communication)
├── State Management
├── Arithmetic Operations  
├── Error Handling
└── Event Emission

CalculatorPresentationElement (UI)
├── Digital Display
├── Button Grid
├── User Interaction
└── Visual Feedback

State Management

• display: Current display value (string)
• currentValue: Current numeric value
• previousValue: Previous value for operations
• pendingOperation: Operation waiting to be completed
• waitingForNewValue: Flag for input state management
• history: Array of all calculations performed

Building

# Install dependencies
npm install

# Build the package
npm run build

This will:

1. Convert HTML definitions to ESM modules
2. Compile TypeScript sources
3. Create browser bundle at dist/browser-bundle.js
4. Generate type definitions and component manifest

Publishing to npm

# Using npm directly
npm publish --access public

# Or using Matrix CLI
matrix publish package-calculator

Testing the Calculator

Once deployed and loaded in the Matrix REPL:

1. Load Package: Click "package-calculator" in the packages list
2. Use Calculator: Click "Use: Calculator" to instantiate
3. Test Operations:
   • Click numbers (0-9) to input values
   • Click operations (+, −, ×, ÷) to set operations
   • Click = to complete calculations
   • Click C to clear and reset
4. Verify State: Check that display updates correctly and operations work as expected

Example Usage

// Create calculator instance
const calc = new CalculatorComponent('calc1', eventBus);

// Handle calculator events
calc.on('DisplayUpdated', (data) => {
  console.log('Display:', data.display);
});

calc.on('CalculationComplete', (data) => {
  console.log('Result:', data.result);
});

// Input numbers and operations
calc.numberInputHandler({ digit: 5 });
calc.operationHandler({ operation: 'add' });
calc.numberInputHandler({ digit: 3 });
calc.equalsHandler(); // Result: 8

Related Documentation

• Matrix CLI Documentation - Complete CLI usage guide
• Package Deployment Guide - How to create and deploy Matrix packages
• Package Coordinator - Example of multi-component package

License

MIT