@pie-players/pie-calculator 0.1.0

package/README.md

@@ -0,0 +1,142 @@
+# @pie-players/pie-calculator
+
+Calculator provider interfaces and types for PIE Assessment Toolkit - Pure TypeScript with no UI dependencies.
+
+## Purpose
+
+This package provides the foundational interfaces and types for building calculator providers in the PIE ecosystem. It has **zero dependencies** and no UI framework requirements, making it suitable for:
+
+- Implementing custom calculator providers
+- Type-safe calculator integration
+- Framework-agnostic calculator solutions
+
+## What's Included
+
+### Interfaces
+
+- **`CalculatorProvider`** - Stateless factory for creating calculator implementations
+- **`Calculator`** - Actual calculator instance interface
+- **`CalculatorProviderCapabilities`** - Feature support description
+- **`CalculatorProviderConfig`** - Provider configuration
+
+### Types
+
+- **`CalculatorType`** - Union type of supported calculator types
+- **`CalculatorState`** - State for persistence
+- **`CalculationHistoryEntry`** - History entry format
+- **`DesmosCalculatorConfig`** - Desmos-specific configuration
+- **`TICalculatorConfig`** - TI calculator-specific configuration
+
+## Installation
+
+```bash
+npm install @pie-players/pie-calculator
+# or
+bun add @pie-players/pie-calculator
+```
+
+## Usage
+
+### Implementing a Custom Calculator Provider
+
+```typescript
+import type {
+  CalculatorProvider,
+  Calculator,
+  CalculatorType,
+  CalculatorProviderCapabilities,
+  CalculatorProviderConfig
+} from '@pie-players/pie-calculator';
+
+class MyCalculatorImpl implements Calculator {
+  readonly provider: CalculatorProvider;
+  readonly type: CalculatorType;
+
+  constructor(provider: CalculatorProvider, type: CalculatorType, container: HTMLElement) {
+    this.provider = provider;
+    this.type = type;
+    // Initialize calculator in container
+  }
+
+  getValue(): string { return '0'; }
+  setValue(value: string): void { /* ... */ }
+  clear(): void { /* ... */ }
+  exportState(): CalculatorState { /* ... */ }
+  importState(state: CalculatorState): void { /* ... */ }
+  destroy(): void { /* ... */ }
+}
+
+export class MyCalculatorProvider implements CalculatorProvider {
+  readonly providerId = 'my-calculator';
+  readonly providerName = 'My Calculator';
+  readonly supportedTypes: CalculatorType[] = ['basic', 'scientific'];
+  readonly version = '1.0.0';
+
+  async initialize(): Promise<void> {
+    // Load libraries, etc.
+  }
+
+  async createCalculator(
+    type: CalculatorType,
+    container: HTMLElement,
+    config?: CalculatorProviderConfig
+  ): Promise<Calculator> {
+    return new MyCalculatorImpl(this, type, container);
+  }
+
+  supportsType(type: CalculatorType): boolean {
+    return this.supportedTypes.includes(type);
+  }
+
+  getCapabilities(): CalculatorProviderCapabilities {
+    return {
+      supportsHistory: true,
+      supportsGraphing: false,
+      supportsExpressions: true,
+      canExport: true,
+      maxPrecision: 15,
+      inputMethods: ['keyboard', 'mouse', 'touch'],
+    };
+  }
+
+  destroy(): void {
+    // Cleanup
+  }
+}
+```
+
+## Official Implementations
+
+- **Math.js** (`@pie-players/pie-calculator-mathjs`) - Open-source, always available (built into toolkit)
+- **Desmos** (`@pie-players/pie-calculator-desmos`) - Requires API key, graphing support
+- **TI Emulators** (`@pie-players/pie-calculator-ti`) - Requires commercial license, TI-84/108/34
+
+## Calculator Types
+
+Supported calculator types:
+
+- `"basic"` - Four-function calculator (add, subtract, multiply, divide)
+- `"scientific"` - Scientific calculator with trigonometry, logarithms, etc.
+- `"graphing"` - Graphing calculator with coordinate plane
+- `"ti-84"` - Texas Instruments TI-84 Plus CE
+- `"ti-108"` - Texas Instruments TI-108
+- `"ti-34-mv"` - Texas Instruments TI-34 MultiView
+
+## Design Philosophy
+
+This core package intentionally:
+- ✅ Has **zero runtime dependencies**
+- ✅ Contains **only TypeScript interfaces and types**
+- ✅ Is **framework-agnostic** (no React, Svelte, Vue, etc.)
+- ✅ Supports **pluggable architecture**
+- ✅ Enables **type-safe calculator implementations**
+
+## License
+
+MIT
+
+## Related Packages
+
+- [@pie-players/pie-calculator-mathjs](../calculator-mathjs) - Open-source Math.js provider (default)
+- [@pie-players/pie-calculator-desmos](../calculator-desmos) - Desmos graphing calculator provider
+- [@pie-players/pie-calculator-ti](../calculator-ti) - Texas Instruments emulator provider

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @pie-players/pie-calculator
+ *
+ * Calculator provider interfaces and types for PIE Assessment Toolkit.
+ * No UI dependencies - pure TypeScript interfaces.
+ */
+export type { CalculationHistoryEntry, Calculator, CalculatorProvider, CalculatorProviderCapabilities, CalculatorProviderConfig, CalculatorState, CalculatorType, DesmosCalculatorConfig, TICalculatorConfig, } from "./provider-interface";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EACX,uBAAuB,EACvB,UAAU,EACV,kBAAkB,EAClB,8BAA8B,EAC9B,wBAAwB,EACxB,eAAe,EACf,cAAc,EACd,sBAAsB,EACtB,kBAAkB,GAClB,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * @pie-players/pie-calculator
+ *
+ * Calculator provider interfaces and types for PIE Assessment Toolkit.
+ * No UI dependencies - pure TypeScript interfaces.
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/provider-interface.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Calculator Provider Interfaces
+ *
+ * Defines the contract for calculator providers.
+ * Providers are stateless factories that create configured calculator implementations.
+ *
+ * Part of PIE Calculator - No UI dependencies.
+ */
+/**
+ * Calculator types
+ */
+export type CalculatorType = "basic" | "scientific" | "graphing" | "ti-84" | "ti-108" | "ti-34-mv";
+/**
+ * TI-specific calculator configuration options
+ */
+export interface TICalculatorConfig {
+    restrictedMode?: boolean;
+    [key: string]: any;
+}
+/**
+ * Desmos-specific calculator configuration options
+ * Based on production implementation patterns and Desmos API documentation
+ */
+export interface DesmosCalculatorConfig {
+    apiKey?: string;
+    proxyEndpoint?: string;
+    border?: boolean;
+    degreeMode?: boolean | "degree" | "radian";
+    decimalToFraction?: boolean;
+    links?: boolean;
+    settingsMenu?: boolean;
+    expressions?: boolean;
+    zoomButtons?: boolean;
+    expressionsTopbar?: boolean;
+    notes?: boolean;
+    folders?: boolean;
+    images?: boolean;
+    qwertyKeyboard?: boolean;
+    restrictedFunctions?: boolean;
+    plotSingleVariableImplicitEquations?: boolean;
+    distributions?: boolean;
+    plotImplicits?: boolean;
+    plotInequalities?: boolean;
+    geometryComputationFunctions?: boolean;
+    sliders?: boolean;
+    expressionsCollapsed?: boolean;
+    administerSecretFolders?: boolean;
+    lockViewport?: boolean;
+    functionDefinition?: boolean;
+    brailleExpressionDownload?: boolean;
+    keypad?: boolean;
+    graphpaper?: boolean;
+    additionalFunctions?: string[];
+}
+/**
+ * Calculator provider configuration
+ */
+export interface CalculatorProviderConfig {
+    settings?: Record<string, any>;
+    restrictedMode?: boolean;
+    locale?: string;
+    theme?: "light" | "dark" | "auto";
+    desmos?: DesmosCalculatorConfig;
+    ti?: TICalculatorConfig;
+}
+/**
+ * Calculator provider capabilities
+ */
+export interface CalculatorProviderCapabilities {
+    supportsHistory: boolean;
+    supportsGraphing: boolean;
+    supportsExpressions: boolean;
+    canExport: boolean;
+    maxPrecision?: number;
+    inputMethods: ("keyboard" | "mouse" | "touch")[];
+}
+/**
+ * Calculation history entry
+ */
+export interface CalculationHistoryEntry {
+    expression: string;
+    result: string;
+    timestamp: number;
+}
+/**
+ * Calculator state for persistence
+ */
+export interface CalculatorState {
+    type: CalculatorType;
+    provider: string;
+    value: string;
+    history?: CalculationHistoryEntry[];
+    providerState?: any;
+}
+/**
+ * Calculator Provider interface
+ *
+ * Providers are stateless factories that create calculator implementations.
+ * They describe capabilities and create configured instances.
+ */
+export interface CalculatorProvider {
+    /**
+     * Unique identifier for this provider
+     */
+    readonly providerId: string;
+    /**
+     * Human-readable provider name
+     */
+    readonly providerName: string;
+    /**
+     * Supported calculator types
+     */
+    readonly supportedTypes: CalculatorType[];
+    /**
+     * Provider version
+     */
+    readonly version: string;
+    /**
+     * Initialize the provider (load libraries, etc.)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Create a calculator instance
+     */
+    createCalculator(type: CalculatorType, container: HTMLElement, config?: CalculatorProviderConfig): Promise<Calculator>;
+    /**
+     * Check if a calculator type is supported
+     */
+    supportsType(type: CalculatorType): boolean;
+    /**
+     * Clean up provider resources
+     */
+    destroy(): void;
+    /**
+     * Get provider capabilities
+     */
+    getCapabilities(): CalculatorProviderCapabilities;
+}
+/**
+ * Calculator instance interface (provider-agnostic)
+ *
+ * The actual calculator implementation that handles calculations.
+ * Created by CalculatorProvider.createCalculator()
+ */
+export interface Calculator {
+    /**
+     * The provider that created this calculator
+     */
+    readonly provider: CalculatorProvider;
+    /**
+     * The calculator type
+     */
+    readonly type: CalculatorType;
+    /**
+     * Get current value/result
+     */
+    getValue(): string;
+    /**
+     * Set value
+     */
+    setValue(value: string): void;
+    /**
+     * Clear calculator
+     */
+    clear(): void;
+    /**
+     * Get calculation history (if supported)
+     */
+    getHistory?(): CalculationHistoryEntry[];
+    /**
+     * Clear calculation history (if supported)
+     */
+    clearHistory?(): void;
+    /**
+     * Evaluate an expression (if supported)
+     */
+    evaluate?(expression: string): Promise<string>;
+    /**
+     * Resize calculator (when container size changes)
+     */
+    resize?(): void;
+    /**
+     * Export calculator state for persistence
+     */
+    exportState(): CalculatorState;
+    /**
+     * Import calculator state from persistence
+     */
+    importState(state: CalculatorState): void;
+    /**
+     * Destroy calculator and clean up resources
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=provider-interface.d.ts.map

package/dist/provider-interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-interface.d.ts","sourceRoot":"","sources":["../src/provider-interface.ts"],"names":[],"mappings":"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"}

package/dist/provider-interface.js

@@ -0,0 +1,10 @@
+/**
+ * Calculator Provider Interfaces
+ *
+ * Defines the contract for calculator providers.
+ * Providers are stateless factories that create configured calculator implementations.
+ *
+ * Part of PIE Calculator - No UI dependencies.
+ */
+export {};
+//# sourceMappingURL=provider-interface.js.map

package/dist/provider-interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-interface.js","sourceRoot":"","sources":["../src/provider-interface.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@pie-players/pie-calculator",
+  "version": "0.1.0",
+  "description": "Calculator provider interfaces and types for PIE Assessment Toolkit - No UI dependencies",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "pie",
+    "calculator",
+    "math",
+    "interfaces",
+    "accessibility"
+  ],
+  "author": "PIE Framework",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.7.2"
+  }
+}