@pie-players/pie-calculator 0.3.67 → 0.3.69

package/README.md

@@ -1,86 +1,61 @@
 # @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
+Provider-neutral calculator contracts for PIE Players. This package has no UI
+or vendor implementation code.
 
 ## Installation
 
 ```bash
-npm install @pie-players/pie-calculator
-# or
 bun add @pie-players/pie-calculator
 ```
 
-## Usage
+## Contract
+
+The package exports:
 
-### Implementing a Custom Calculator Provider
+- `CalculatorProvider`, the factory and capability contract implemented by a
+  calculator adapter;
+- `Calculator`, the lifecycle, value, state, resize, and focus contract for one
+  mounted calculator;
+- `CalculatorProviderInit`, the provider-level credential and instrumentation
+  surface;
+- `CalculatorProviderConfig`, whose `settings` object is interpreted by the
+  selected implementation; and
+- `CalculatorType`, with `basic`, `scientific`, and `graphing` modes.
 
-```typescript
+Provider-specific settings belong to the provider package. Generic code passes
+them through without importing or naming Desmos, GeoGebra, or another vendor.
+
+```ts
 import type {
-  CalculatorProvider,
   Calculator,
-  CalculatorType,
+  CalculatorProvider,
   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
-  }
+  CalculatorProviderConfig,
+  CalculatorProviderInit,
+  CalculatorType,
+} from "@pie-players/pie-calculator";
 
-  getValue(): string { return '0'; }
-  setValue(value: string): void { /* ... */ }
-  clear(): void { /* ... */ }
-  exportState(): CalculatorState { /* ... */ }
-  importState(state: CalculatorState): void { /* ... */ }
-  destroy(): void { /* ... */ }
+interface MyCalculatorProviderConfig extends CalculatorProviderConfig {
+  precision?: number;
 }
 
 export class MyCalculatorProvider implements CalculatorProvider {
-  readonly providerId = 'my-calculator';
-  readonly providerName = 'My Calculator';
-  readonly supportedTypes: CalculatorType[] = ['basic', 'scientific'];
-  readonly version = '1.0.0';
+  readonly providerId = "my-calculator";
+  readonly providerName = "My Calculator";
+  readonly supportedTypes: CalculatorType[] = ["basic", "scientific"];
+  readonly version = "1";
 
-  async initialize(): Promise<void> {
-    // Load libraries, etc.
+  async initialize(config?: CalculatorProviderInit): Promise<void> {
+    // Load libraries and initialize provider-level services.
   }
 
   async createCalculator(
     type: CalculatorType,
     container: HTMLElement,
-    config?: CalculatorProviderConfig
+    config?: MyCalculatorProviderConfig,
   ): Promise<Calculator> {
-    return new MyCalculatorImpl(this, type, container);
+    return createMyCalculator({ provider: this, type, container, config });
   }
 
   supportsType(type: CalculatorType): boolean {
@@ -93,42 +68,22 @@ export class MyCalculatorProvider implements CalculatorProvider {
       supportsGraphing: false,
       supportsExpressions: true,
       canExport: true,
-      maxPrecision: 15,
-      inputMethods: ['keyboard', 'mouse', 'touch'],
+      inputMethods: ["keyboard", "mouse", "touch"],
     };
   }
 
-  destroy(): void {
-    // Cleanup
-  }
+  destroy(): void {}
 }
 ```
 
-## Official Implementations
+## Implementations
 
-- **Desmos** (`@pie-players/pie-calculator-desmos`) - Requires API key, graphing support
+- `@pie-players/pie-calculator-desmos`
+- `@pie-players/pie-calculator-geogebra`
 
-## 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
-
-## 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**
+Each implementation and its underlying calculator product has its own package
+and licensing boundary. No vendor library is bundled by this contract package.
 
 ## License
 
-MIT
-
-## Related Packages
-
-- [@pie-players/pie-calculator-desmos](../calculator-desmos) - Desmos graphing calculator provider
+PIE-authored code in this package is MIT licensed.

package/dist/index.d.ts

@@ -4,4 +4,4 @@
  * 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, } from "./provider-interface.js";
+export type { CalculationHistoryEntry, Calculator, CalculatorProvider, CalculatorProviderCapabilities, CalculatorProviderConfig, CalculatorProviderInit, CalculatorState, CalculatorType, } from "./provider-interface.js";

package/dist/provider-interface.d.ts

@@ -11,50 +11,41 @@
  */
 export type CalculatorType = "basic" | "scientific" | "graphing";
 /**
- * Desmos-specific calculator configuration options
- * Based on production implementation patterns and Desmos API documentation
+ * Provider-level initialization: credentials and instrumentation.
+ *
+ * Distinct from `CalculatorProviderConfig`, which configures one calculator
+ * instance. A hosted calculator vendor needs a key, or a server endpoint that
+ * mints one — never both in production, since `apiKey` puts the key in the
+ * browser.
+ *
+ * Naming across adapters, so a host reading one knows where to look in the
+ * others: `<Vendor>CalculatorSettings` is the vendor option shape,
+ * `<Vendor>CalculatorProviderConfig` is `CalculatorProviderConfig` with
+ * `settings` narrowed to it, and `<Vendor>CalculatorProviderInit` appears only
+ * where the adapter narrows or extends this interface — Cortex and GeoGebra take
+ * no credential, Desmos takes this type whole and declares no alias for it.
  */
-export interface DesmosCalculatorConfig {
+export interface CalculatorProviderInit {
+    /** Vendor API key. Development only — it reaches the browser. */
     apiKey?: string;
+    /** Host endpoint that serves the vendor credential. Production. */
     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;
-    tables?: boolean;
-    expressionsCollapsed?: boolean;
-    administerSecretFolders?: boolean;
-    lockViewport?: boolean;
-    functionDefinition?: boolean;
-    brailleExpressionDownload?: boolean;
-    keypad?: boolean;
-    graphpaper?: boolean;
-    additionalFunctions?: string[];
+    /** Instrumentation callback for library-load and auth events. */
+    onTelemetry?: (eventName: string, payload?: Record<string, unknown>) => void | Promise<void>;
 }
 /**
- * Calculator provider configuration
+ * Provider-neutral calculator configuration.
+ *
+ * Adapters own the shape and interpretation of `settings`; the generic
+ * calculator seam deliberately does not name an implementation. An adapter
+ * narrows `settings` in its own `<Vendor>CalculatorProviderConfig`, which is the
+ * only reason a caller ever gets vendor option names.
  */
 export interface CalculatorProviderConfig {
-    settings?: Record<string, any>;
+    settings?: Record<string, unknown>;
     restrictedMode?: boolean;
     locale?: string;
     theme?: "light" | "dark" | "auto";
-    desmos?: DesmosCalculatorConfig;
 }
 /**
  * Calculator provider capabilities
@@ -90,6 +81,14 @@ export interface CalculatorState {
  *
  * Providers are stateless factories that create calculator implementations.
  * They describe capabilities and create configured instances.
+ *
+ * Not parameterized by its configuration type, matching `ITTSProvider` in
+ * `@pie-players/pie-tts`. An adapter extends `CalculatorProviderConfig` and
+ * narrows `createCalculator`'s argument in its own class signature — see
+ * `DesmosCalculatorProviderConfig` in `@pie-players/pie-calculator-desmos` —
+ * which is what gives a caller holding the concrete provider the precise type.
+ * A type parameter here would add one, since a provider narrowing that argument
+ * satisfies this interface either way.
  */
 export interface CalculatorProvider {
     /**
@@ -109,9 +108,9 @@ export interface CalculatorProvider {
      */
     readonly version: string;
     /**
-     * Initialize the provider (load libraries, etc.)
+     * Initialize the provider: load the vendor library and authenticate.
      */
-    initialize(): Promise<void>;
+    initialize(config?: CalculatorProviderInit): Promise<void>;
     /**
      * Create a calculator instance
      */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-calculator",
-	"version": "0.3.67",
+	"version": "0.3.69",
 	"author": "PIE Framework",
 	"repository": {
 		"type": "git",