@pie-players/pie-calculator-geogebra 0.3.68

package/README.md

@@ -0,0 +1,59 @@
+# @pie-players/pie-calculator-geogebra
+
+GeoGebra adapter for the provider-neutral `@pie-players/pie-calculator`
+interface. It supports PIE's `scientific` and `graphing` modes and maps `basic`
+to GeoGebra's Scientific Calculator because GeoGebra does not expose a separate
+four-function app through the embedding interface.
+
+The package contains PIE-authored adapter code only. By default it loads
+`https://www.geogebra.org/apps/deployggb.js` at runtime; it does not bundle or
+redistribute the GeoGebra application.
+
+## Licensing
+
+PIE's adapter is MIT licensed, but GeoGebra is separately licensed. GeoGebra's
+web services and complete application are free for qualifying non-commercial
+use with attribution; commercial use requires a License and Collaboration
+Agreement. Review the current [GeoGebra License](https://www.geogebra.org/license)
+and contact `office@geogebra.org` when the intended use is commercial.
+
+## Usage
+
+```ts
+import { GeoGebraCalculatorProvider } from "@pie-players/pie-calculator-geogebra";
+
+const provider = new GeoGebraCalculatorProvider();
+await provider.initialize();
+
+const calculator = await provider.createCalculator("graphing", container, {
+  restrictedMode: true,
+  locale: "en-US",
+  settings: {
+    showResetIcon: true,
+    showZoomButtons: true,
+  },
+});
+```
+
+A licensed self-hosted deployment may provide its own loader URL:
+
+```ts
+await provider.initialize({ scriptUrl: "/licensed-geogebra/deployggb.js" });
+```
+
+`initialize()` takes `GeoGebraCalculatorProviderInit` -- `scriptUrl`,
+`appletTimeoutMs`, and `onTelemetry` from the shared `CalculatorProviderInit`.
+The embed takes no credential, so `apiKey` and `proxyEndpoint` are deliberately
+absent. `createCalculator()` takes `GeoGebraCalculatorProviderConfig`, which is
+the provider-neutral configuration with `settings` typed as
+`GeoGebraCalculatorSettings`.
+
+The adapter uses GeoGebra's documented `appletOnLoad` API object, Base64 state
+methods, resize methods, and `remove()` cleanup.
+
+## References
+
+- [GeoGebra Apps Embedding](https://geogebra.github.io/docs/reference/en/GeoGebra_Apps_Embedding/)
+- [GeoGebra App Parameters](https://geogebra.github.io/docs/reference/en/GeoGebra_App_Parameters/)
+- [GeoGebra Apps API](https://geogebra.github.io/docs/reference/en/GeoGebra_Apps_API/)
+- [GeoGebra License](https://www.geogebra.org/license)

package/dist/geogebra-provider.d.ts

@@ -0,0 +1,94 @@
+import type { Calculator, CalculatorProvider, CalculatorProviderCapabilities, CalculatorProviderConfig, CalculatorProviderInit, CalculatorType } from "@pie-players/pie-calculator";
+interface GeoGebraAppletApi {
+    evalCommand?(expression: string): boolean;
+    evalCommandCAS?(expression: string): string;
+    evalCommandGetLabels?(expression: string): string;
+    getBase64?(): string;
+    setBase64?(value: string, callback?: () => void): void;
+    getEditorState?(): unknown;
+    setEditorState?(state: unknown): void;
+    newConstruction?(): void;
+    setSize?(width: number, height: number): void;
+    recalculateEnvironments?(): void;
+    remove?(): void;
+}
+interface GeoGebraAppletParameters extends Record<string, unknown> {
+    appName: "graphing" | "scientific";
+    width: number;
+    height: number;
+    id: string;
+    appletOnLoad: (api: GeoGebraAppletApi) => void;
+}
+interface GeoGebraAppletEmbed {
+    inject(target: string): void;
+}
+interface GeoGebraAppletConstructor {
+    new (parameters: GeoGebraAppletParameters, useBrowserForJavaScript?: boolean): GeoGebraAppletEmbed;
+}
+declare global {
+    interface Window {
+        GGBApplet?: GeoGebraAppletConstructor;
+    }
+}
+/**
+ * GeoGebra's `initialize()` argument.
+ *
+ * Narrowed to `onTelemetry`: GeoGebra's embed takes no credential, so `apiKey`
+ * and `proxyEndpoint` would name a parameter this adapter cannot honour.
+ */
+export interface GeoGebraCalculatorProviderInit extends Pick<CalculatorProviderInit, "onTelemetry"> {
+    /** Override only when the deployment's GeoGebra license permits that source. */
+    scriptUrl?: string;
+    /** Maximum time to wait for `appletOnLoad` after injection. */
+    appletTimeoutMs?: number;
+}
+/** GeoGebra app parameters accepted through `CalculatorProviderConfig.settings`. */
+export interface GeoGebraCalculatorSettings extends Record<string, unknown> {
+    width?: number;
+    height?: number;
+    borderColor?: string;
+    borderRadius?: number;
+    enableRightClick?: boolean;
+    enableLabelDrags?: boolean;
+    enableShiftDragZoom?: boolean;
+    showZoomButtons?: boolean;
+    errorDialogsActive?: boolean;
+    showMenuBar?: boolean;
+    showToolBar?: boolean;
+    showToolBarHelp?: boolean;
+    showAlgebraInput?: boolean;
+    showResetIcon?: boolean;
+    language?: string;
+    country?: string;
+    allowStyleBar?: boolean;
+    enableFileFeatures?: boolean;
+    enableUndoRedo?: boolean;
+    enableCAS?: boolean;
+    enable3d?: boolean;
+    preventFocus?: boolean;
+}
+/**
+ * GeoGebra's `createCalculator()` argument: the provider-neutral shape with
+ * `settings` naming what it holds.
+ */
+export interface GeoGebraCalculatorProviderConfig extends Omit<CalculatorProviderConfig, "settings"> {
+    settings?: GeoGebraCalculatorSettings;
+}
+export declare class GeoGebraCalculatorProvider implements CalculatorProvider {
+    readonly providerId = "geogebra";
+    readonly providerName = "GeoGebra";
+    readonly supportedTypes: CalculatorType[];
+    readonly version = "6";
+    private initialized;
+    private appletTimeoutMs;
+    private readonly instances;
+    private onTelemetry;
+    private emitTelemetry;
+    private loadGeoGebraScript;
+    initialize(config?: GeoGebraCalculatorProviderInit): Promise<void>;
+    createCalculator(type: CalculatorType, container: HTMLElement, config?: GeoGebraCalculatorProviderConfig): Promise<Calculator>;
+    supportsType(type: CalculatorType): boolean;
+    destroy(): void;
+    getCapabilities(): CalculatorProviderCapabilities;
+}
+export {};

package/dist/geogebra-provider.js

@@ -0,0 +1,302 @@
+const DEFAULT_SCRIPT_URL = "https://www.geogebra.org/apps/deployggb.js";
+const DEFAULT_APPLET_TIMEOUT_MS = 20_000;
+let nextAppletId = 0;
+export class GeoGebraCalculatorProvider {
+    providerId = "geogebra";
+    providerName = "GeoGebra";
+    supportedTypes = [
+        "basic",
+        "scientific",
+        "graphing",
+    ];
+    version = "6";
+    initialized = false;
+    appletTimeoutMs = DEFAULT_APPLET_TIMEOUT_MS;
+    /*
+     * Every calculator this provider handed out and that has not destroyed itself.
+     *
+     * `destroy()` is a host's one call to release the provider, and without this it
+     * released only the provider's own fields: every applet it created kept running
+     * with its container populated and, where the id was generated here, renamed.
+     */
+    instances = new Set();
+    onTelemetry;
+    async emitTelemetry(eventName, payload) {
+        try {
+            await this.onTelemetry?.(eventName, payload);
+        }
+        catch (error) {
+            console.warn("[GeoGebraProvider] telemetry callback failed:", error);
+        }
+    }
+    async loadGeoGebraScript(scriptUrl) {
+        await new Promise((resolve, reject) => {
+            const script = document.createElement("script");
+            script.src = scriptUrl;
+            script.async = true;
+            script.dataset.pieCalculatorProvider = "geogebra";
+            script.onload = () => {
+                if (window.GGBApplet)
+                    resolve();
+                else {
+                    reject(new Error("GeoGebra deploy script loaded but window.GGBApplet is undefined"));
+                }
+            };
+            script.onerror = () => {
+                reject(new Error(`Failed to load GeoGebra from ${scriptUrl}`));
+            };
+            document.head.appendChild(script);
+        });
+    }
+    async initialize(config = {}) {
+        if (this.initialized)
+            return;
+        if (typeof window === "undefined") {
+            throw new Error("GeoGebra calculators can only be initialized in the browser");
+        }
+        this.onTelemetry = config.onTelemetry;
+        this.appletTimeoutMs =
+            typeof config.appletTimeoutMs === "number" && config.appletTimeoutMs > 0
+                ? config.appletTimeoutMs
+                : DEFAULT_APPLET_TIMEOUT_MS;
+        if (!window.GGBApplet) {
+            const scriptUrl = config.scriptUrl?.trim() || DEFAULT_SCRIPT_URL;
+            const startedAt = Date.now();
+            await this.emitTelemetry("pie-tool-library-load-start", {
+                toolId: "calculator",
+                backend: "geogebra",
+                operation: "geogebra-script-load",
+            });
+            try {
+                await this.loadGeoGebraScript(scriptUrl);
+                await this.emitTelemetry("pie-tool-library-load-success", {
+                    toolId: "calculator",
+                    backend: "geogebra",
+                    operation: "geogebra-script-load",
+                    duration: Date.now() - startedAt,
+                });
+            }
+            catch (error) {
+                await this.emitTelemetry("pie-tool-library-load-error", {
+                    toolId: "calculator",
+                    backend: "geogebra",
+                    operation: "geogebra-script-load",
+                    duration: Date.now() - startedAt,
+                    errorType: "ToolLibraryLoadError",
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                throw error;
+            }
+        }
+        this.initialized = true;
+    }
+    async createCalculator(type, container, config) {
+        if (!this.initialized)
+            await this.initialize();
+        if (!this.supportsType(type)) {
+            throw new Error(`GeoGebra does not support calculator type: ${type}`);
+        }
+        const calculator = await GeoGebraCalculator.create(this, type, container, config, this.appletTimeoutMs, () => this.instances.delete(calculator));
+        this.instances.add(calculator);
+        return calculator;
+    }
+    supportsType(type) {
+        return this.supportedTypes.includes(type);
+    }
+    destroy() {
+        // A copy: each `destroy()` calls back to remove itself from the set.
+        for (const instance of [...this.instances])
+            instance.destroy();
+        this.instances.clear();
+        this.initialized = false;
+        this.appletTimeoutMs = DEFAULT_APPLET_TIMEOUT_MS;
+        this.onTelemetry = undefined;
+    }
+    getCapabilities() {
+        return {
+            supportsHistory: false,
+            supportsGraphing: true,
+            supportsExpressions: true,
+            canExport: true,
+            inputMethods: ["keyboard", "mouse", "touch"],
+        };
+    }
+}
+class GeoGebraCalculator {
+    container;
+    onDestroy;
+    provider;
+    type;
+    api = null;
+    applet = null;
+    generatedContainerId = null;
+    destroyed = false;
+    constructor(provider, type, container, onDestroy) {
+        this.container = container;
+        this.onDestroy = onDestroy;
+        this.provider = provider;
+        this.type = type;
+    }
+    static async create(provider, type, container, config, timeoutMs, onDestroy) {
+        const Constructor = window.GGBApplet;
+        if (!Constructor)
+            throw new Error("GeoGebra API not available");
+        const calculator = new GeoGebraCalculator(provider, type, container, onDestroy);
+        const settings = {
+            ...(config?.settings || {}),
+        };
+        delete settings.appName;
+        delete settings.id;
+        delete settings.appletOnLoad;
+        const width = typeof settings.width === "number"
+            ? settings.width
+            : Math.max(container.clientWidth || 0, 320);
+        const height = typeof settings.height === "number"
+            ? settings.height
+            : Math.max(container.clientHeight || 0, 320);
+        delete settings.width;
+        delete settings.height;
+        const isRestricted = config?.restrictedMode === true;
+        const appName = type === "graphing" ? "graphing" : "scientific";
+        const appletId = `pie-geogebra-${Date.now()}-${++nextAppletId}`;
+        if (!container.id) {
+            calculator.generatedContainerId = `${appletId}-container`;
+            container.id = calculator.generatedContainerId;
+        }
+        const clearGeneratedContainerId = () => {
+            if (calculator.generatedContainerId &&
+                container.id === calculator.generatedContainerId) {
+                container.id = "";
+            }
+            calculator.generatedContainerId = null;
+        };
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const timer = setTimeout(() => {
+                settled = true;
+                container.replaceChildren();
+                clearGeneratedContainerId();
+                reject(new Error(`GeoGebra applet did not initialize within ${timeoutMs}ms`));
+            }, timeoutMs);
+            const parameters = {
+                showMenuBar: false,
+                showToolBar: false,
+                // GeoGebra's scientific embed otherwise renders an empty algebra view:
+                // the input row is the calculator's primary interaction surface.
+                showAlgebraInput: true,
+                showZoomButtons: appName === "graphing",
+                ...settings,
+                enable3d: false,
+                preventFocus: true,
+                ...(isRestricted
+                    ? {
+                        showMenuBar: false,
+                        showToolBar: false,
+                        enableFileFeatures: false,
+                        enableCAS: false,
+                        enableRightClick: false,
+                    }
+                    : {}),
+                appName,
+                width,
+                height,
+                id: appletId,
+                appletOnLoad: (api) => {
+                    clearTimeout(timer);
+                    if (settled) {
+                        api.remove?.();
+                        return;
+                    }
+                    settled = true;
+                    calculator.api = api;
+                    resolve();
+                },
+            };
+            try {
+                container.replaceChildren();
+                calculator.applet = new Constructor(parameters, true);
+                calculator.applet.inject(container.id);
+            }
+            catch (error) {
+                clearTimeout(timer);
+                settled = true;
+                container.replaceChildren();
+                clearGeneratedContainerId();
+                reject(error);
+            }
+        });
+        return calculator;
+    }
+    getValue() {
+        const editorState = this.api?.getEditorState?.();
+        return editorState === undefined ? "" : JSON.stringify(editorState);
+    }
+    setValue(value) {
+        if (!value || !this.api?.setEditorState)
+            return;
+        try {
+            this.api.setEditorState(JSON.parse(value));
+        }
+        catch (error) {
+            console.warn("[GeoGebraCalculator] Failed to restore editor state:", error);
+        }
+    }
+    clear() {
+        this.api?.newConstruction?.();
+    }
+    async evaluate(expression) {
+        const casResult = this.api?.evalCommandCAS?.(expression);
+        if (typeof casResult === "string" && casResult.length > 0)
+            return casResult;
+        const labels = this.api?.evalCommandGetLabels?.(expression);
+        if (typeof labels === "string" && labels.length > 0)
+            return labels;
+        return this.api?.evalCommand?.(expression) ? expression : "";
+    }
+    resize() {
+        if (!this.api)
+            return;
+        const width = Math.max(this.container.clientWidth || 0, 1);
+        const height = Math.max(this.container.clientHeight || 0, 1);
+        this.api.setSize?.(width, height);
+        this.api.recalculateEnvironments?.();
+    }
+    focus() {
+        const target = this.container.querySelector('input, textarea, [contenteditable="true"], [tabindex]:not([tabindex="-1"])');
+        target?.focus();
+    }
+    exportState() {
+        return {
+            type: this.type,
+            provider: "geogebra",
+            value: this.getValue(),
+            providerState: this.api?.getBase64?.() || "",
+        };
+    }
+    importState(state) {
+        if (state.provider !== "geogebra") {
+            throw new Error(`Cannot import state from provider: ${state.provider}`);
+        }
+        if (typeof state.providerState === "string" && state.providerState) {
+            this.api?.setBase64?.(state.providerState);
+        }
+        else if (state.value) {
+            this.setValue(state.value);
+        }
+    }
+    destroy() {
+        if (this.destroyed)
+            return;
+        this.destroyed = true;
+        this.api?.remove?.();
+        this.api = null;
+        this.applet = null;
+        this.container.replaceChildren();
+        if (this.generatedContainerId &&
+            this.container.id === this.generatedContainerId) {
+            this.container.id = "";
+        }
+        this.generatedContainerId = null;
+        this.onDestroy();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+/** GeoGebra adapter for the provider-neutral PIE calculator seam. */
+export { GeoGebraCalculatorProvider } from "./geogebra-provider.js";
+export type { GeoGebraCalculatorProviderConfig, GeoGebraCalculatorProviderInit, GeoGebraCalculatorSettings, } from "./geogebra-provider.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+/** GeoGebra adapter for the provider-neutral PIE calculator seam. */
+export { GeoGebraCalculatorProvider } from "./geogebra-provider.js";

package/package.json

@@ -0,0 +1,56 @@
+{
+	"name": "@pie-players/pie-calculator-geogebra",
+	"version": "0.3.68",
+	"description": "GeoGebra calculator provider adapter for PIE assessment tools",
+	"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",
+		"test": "bun test tests",
+		"typecheck": "tsc --noEmit"
+	},
+	"keywords": [
+		"pie",
+		"calculator",
+		"geogebra",
+		"graphing",
+		"scientific",
+		"math",
+		"accessibility"
+	],
+	"author": "PIE Framework",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/pie-framework/pie-players.git",
+		"directory": "packages/calculator-geogebra"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@pie-players/pie-calculator": "0.3.68"
+	},
+	"devDependencies": {
+		"typescript": "^5.9.3"
+	},
+	"sideEffects": false,
+	"homepage": "https://github.com/pie-framework/pie-players/tree/master/packages/calculator-geogebra#readme",
+	"bugs": {
+		"url": "https://github.com/pie-framework/pie-players/issues"
+	},
+	"engines": {
+		"node": ">=20.0.0"
+	}
+}