@pie-players/pie-assessment-toolkit 0.2.0

package/dist/services/ToolConfigResolver.js

@@ -0,0 +1,230 @@
+/**
+ * ToolConfigResolver
+ *
+ * Implements 3-tier hierarchy for tool configuration:
+ * Item requirements > Roster allowances > Student accommodations
+ *
+ * Ensures IEP/504 compliance by properly handling accommodation requirements
+ * while respecting item-level and test-level restrictions.
+ *
+ * Features:
+ * - 3-tier configuration hierarchy
+ * - IEP/504 accommodation support
+ * - Item-specific tool requirements
+ * - Test-level tool restrictions
+ * - Type-safe configuration
+ *
+ * Part of PIE Assessment Toolkit.
+ */
+export class ToolConfigResolver {
+    /**
+     * Resolve configuration for a specific tool
+     *
+     * Hierarchy (highest to lowest priority):
+     * 1. Item level: Item requires scientific calculator → must provide
+     * 2. Roster level: Test blocks dictionary → blocked regardless of accommodation
+     * 3. Student level: IEP requires TTS → enabled unless blocked above
+     *
+     * @param toolId Tool identifier
+     * @param itemConfig Item-level tool configuration
+     * @param rosterConfig Roster-level tool allowances
+     * @param studentProfile Student accommodation profile
+     * @returns Resolved configuration or null if tool not available
+     */
+    resolveTool(toolId, itemConfig, rosterConfig, studentProfile) {
+        // Check item level (highest priority)
+        const itemTool = itemConfig?.[toolId];
+        if (itemTool) {
+            // Item explicitly configures this tool
+            return {
+                enabled: true,
+                type: itemTool.type,
+                required: itemTool.required ?? false,
+                settings: itemTool.settings,
+                source: "item",
+            };
+        }
+        // Check roster level (blocks take precedence)
+        const rosterAllowance = rosterConfig?.[toolId];
+        if (rosterAllowance === "0") {
+            // Roster explicitly blocks this tool
+            return null;
+        }
+        if (rosterAllowance === "1") {
+            // Roster allows this tool
+            return {
+                enabled: true,
+                required: false,
+                source: "roster",
+            };
+        }
+        // Check student level (lowest priority)
+        const hasAccommodation = studentProfile?.accommodations.includes(toolId) ?? false;
+        if (hasAccommodation) {
+            // Student has accommodation for this tool
+            return {
+                enabled: true,
+                required: false,
+                source: "student",
+            };
+        }
+        // Tool not configured at any level
+        return null;
+    }
+    /**
+     * Resolve all tools from configuration
+     *
+     * @param input Configuration input
+     * @returns Map of tool ID to resolved configuration
+     */
+    resolveAll(input) {
+        const resolved = new Map();
+        // Collect all tool IDs from all levels
+        const allToolIds = new Set();
+        // From item config
+        if (input.itemConfig) {
+            Object.keys(input.itemConfig).forEach((id) => allToolIds.add(id));
+        }
+        // From roster config
+        if (input.rosterConfig) {
+            Object.keys(input.rosterConfig).forEach((id) => allToolIds.add(id));
+        }
+        // From student accommodations
+        if (input.studentProfile) {
+            input.studentProfile.accommodations.forEach((id) => allToolIds.add(id));
+        }
+        // Resolve each tool
+        for (const toolId of allToolIds) {
+            const config = this.resolveTool(toolId, input.itemConfig, input.rosterConfig, input.studentProfile);
+            if (config) {
+                resolved.set(toolId, config);
+            }
+        }
+        return resolved;
+    }
+    /**
+     * Check if a tool is enabled
+     *
+     * @param toolId Tool identifier
+     * @param input Configuration input
+     * @returns true if tool is enabled
+     */
+    isToolEnabled(toolId, input) {
+        const config = this.resolveTool(toolId, input.itemConfig, input.rosterConfig, input.studentProfile);
+        return config?.enabled ?? false;
+    }
+    /**
+     * Check if a tool is required
+     *
+     * @param toolId Tool identifier
+     * @param input Configuration input
+     * @returns true if tool is required
+     */
+    isToolRequired(toolId, input) {
+        const config = this.resolveTool(toolId, input.itemConfig, input.rosterConfig, input.studentProfile);
+        return config?.required ?? false;
+    }
+    /**
+     * Get tool type (e.g., 'scientific' for calculator)
+     *
+     * @param toolId Tool identifier
+     * @param input Configuration input
+     * @returns Tool type or null
+     */
+    getToolType(toolId, input) {
+        const config = this.resolveTool(toolId, input.itemConfig, input.rosterConfig, input.studentProfile);
+        return config?.type ?? null;
+    }
+    /**
+     * Get tool settings
+     *
+     * @param toolId Tool identifier
+     * @param input Configuration input
+     * @returns Tool settings or null
+     */
+    getToolSettings(toolId, input) {
+        const config = this.resolveTool(toolId, input.itemConfig, input.rosterConfig, input.studentProfile);
+        return config?.settings ?? null;
+    }
+    /**
+     * Get list of all enabled tools
+     *
+     * @param input Configuration input
+     * @returns Array of enabled tool IDs
+     */
+    getEnabledTools(input) {
+        const resolved = this.resolveAll(input);
+        return Array.from(resolved.entries())
+            .filter(([_, config]) => config.enabled)
+            .map(([toolId]) => toolId);
+    }
+    /**
+     * Get list of required tools
+     *
+     * @param input Configuration input
+     * @returns Array of required tool IDs
+     */
+    getRequiredTools(input) {
+        const resolved = this.resolveAll(input);
+        return Array.from(resolved.entries())
+            .filter(([_, config]) => config.required)
+            .map(([toolId]) => toolId);
+    }
+    /**
+     * Validate that all required tools are available
+     *
+     * @param availableTools Set of available tool IDs
+     * @param input Configuration input
+     * @returns Object with validation result
+     */
+    validate(availableTools, input) {
+        const requiredTools = this.getRequiredTools(input);
+        const missingTools = requiredTools.filter((toolId) => !availableTools.has(toolId));
+        return {
+            valid: missingTools.length === 0,
+            missingTools,
+        };
+    }
+    /**
+     * Merge multiple roster configurations (for complex assessments)
+     *
+     * More restrictive settings win (blocked > allowed).
+     *
+     * @param configs Array of roster configurations
+     * @returns Merged configuration
+     */
+    mergeRosterConfigs(...configs) {
+        const merged = {};
+        for (const config of configs) {
+            for (const [toolId, allowance] of Object.entries(config)) {
+                // If any config blocks the tool, it's blocked
+                if (allowance === "0") {
+                    merged[toolId] = "0";
+                }
+                else if (!merged[toolId]) {
+                    // If not already set, use this allowance
+                    merged[toolId] = allowance;
+                }
+            }
+        }
+        return merged;
+    }
+    /**
+     * Merge multiple student accommodation profiles
+     *
+     * Union of all accommodations.
+     *
+     * @param profiles Array of student profiles
+     * @returns Merged profile
+     */
+    mergeStudentProfiles(...profiles) {
+        const allAccommodations = new Set();
+        for (const profile of profiles) {
+            profile.accommodations.forEach((acc) => allAccommodations.add(acc));
+        }
+        return {
+            accommodations: Array.from(allAccommodations),
+        };
+    }
+}
+//# sourceMappingURL=ToolConfigResolver.js.map

package/dist/services/ToolConfigResolver.js.map

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

package/dist/services/ToolCoordinator.d.ts

@@ -0,0 +1,137 @@
+/**
+ * ToolCoordinator
+ *
+ * Manages z-index layering and visibility for floating tools.
+ * Prevents conflicts between calculator, ruler, protractor, etc.
+ *
+ * Features:
+ * - Centralized z-index management with defined layers
+ * - Tool visibility state tracking
+ * - Bring-to-front on interaction
+ * - Framework-agnostic (works with any DOM element)
+ *
+ * Part of PIE Assessment Toolkit.
+ */
+import type { IToolCoordinator, ToolState } from "./interfaces";
+/**
+ * Z-index layers for assessment components
+ */
+export declare enum ZIndexLayer {
+    BASE = 0,// PIE content, player chrome (0-999)
+    TOOL = 1000,// Non-modal tools (ruler, protractor) (1000-1999)
+    MODAL = 2000,// Modal tools (calculator, dictionary) (2000-2999)
+    CONTROL = 3000,// Drag handles, resize controls (3000-3999)
+    HIGHLIGHT = 4000
+}
+/**
+ * Configuration for ToolCoordinator
+ * Currently empty but allows future extension without breaking changes
+ */
+export type ToolCoordinatorConfig = Record<string, never>;
+export declare class ToolCoordinator implements IToolCoordinator {
+    private config;
+    private tools;
+    private layerCounters;
+    private listeners;
+    constructor(config?: ToolCoordinatorConfig);
+    /**
+     * Subscribe to tool state changes
+     * Returns unsubscribe function
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Notify all listeners of state change
+     */
+    private notifyListeners;
+    /**
+     * Register a tool with the coordinator
+     *
+     * @param id Unique tool identifier
+     * @param name Display name
+     * @param element DOM element for the tool (optional for backward compatibility)
+     * @param layer Z-index layer (defaults to MODAL)
+     */
+    registerTool(id: string, name: string, element?: HTMLElement, layer?: ZIndexLayer): void;
+    /**
+     * Unregister a tool
+     *
+     * @param id Tool identifier
+     */
+    unregisterTool(id: string): void;
+    /**
+     * Show a tool
+     *
+     * @param id Tool identifier
+     */
+    showTool(id: string): void;
+    /**
+     * Hide a tool
+     *
+     * @param id Tool identifier
+     */
+    hideTool(id: string): void;
+    /**
+     * Toggle tool visibility
+     *
+     * @param id Tool identifier
+     */
+    toggleTool(id: string): void;
+    /**
+     * Check if tool is visible
+     *
+     * @param id Tool identifier
+     * @returns true if tool is visible
+     */
+    isToolVisible(id: string): boolean;
+    /**
+     * Bring element to front of its layer
+     *
+     * @param element DOM element to bring forward
+     */
+    bringToFront(element: HTMLElement): void;
+    /**
+     * Get all registered tool IDs
+     */
+    getRegisteredTools(): string[];
+    /**
+     * Get tool element by ID
+     */
+    getToolElement(id: string): HTMLElement | null;
+    /**
+     * Get next offset within a layer
+     */
+    private getNextLayerOffset;
+    /**
+     * Get maximum z-index currently in use in a layer
+     */
+    private getMaxZIndexInLayer;
+    /**
+     * Reset all tools to their base z-indices
+     */
+    resetZIndices(): void;
+    /**
+     * Update tool element reference (backward compatibility)
+     *
+     * @param id Tool identifier
+     * @param element New DOM element
+     */
+    updateToolElement(id: string, element: HTMLElement): void;
+    /**
+     * Hide all tools (backward compatibility)
+     */
+    hideAllTools(): void;
+    /**
+     * Get tool state (interface method)
+     *
+     * @param id Tool identifier
+     * @returns Tool state or undefined
+     */
+    getToolState(id: string): ToolState | undefined;
+    /**
+     * Get all visible tools (interface method)
+     *
+     * @returns Array of visible tool states
+     */
+    getVisibleTools(): ToolState[];
+}
+//# sourceMappingURL=ToolCoordinator.d.ts.map

package/dist/services/ToolCoordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolCoordinator.d.ts","sourceRoot":"","sources":["../../src/services/ToolCoordinator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAIhE;;GAEG;AACH,oBAAY,WAAW;IACtB,IAAI,IAAI,CAAE,qCAAqC;IAC/C,IAAI,OAAO,CAAE,kDAAkD;IAC/D,KAAK,OAAO,CAAE,mDAAmD;IACjE,OAAO,OAAO,CAAE,4CAA4C;IAC5D,SAAS,OAAO;CAChB;AAeD;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE1D,qBAAa,eAAgB,YAAW,gBAAgB;IACvD,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,KAAK,CAAuC;IACpD,OAAO,CAAC,aAAa,CAAkC;IACvD,OAAO,CAAC,SAAS,CAAyB;gBAE9B,MAAM,GAAE,qBAA0B;IAU9C;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAO3C;;OAEG;IACH,OAAO,CAAC,eAAe;IAIvB;;;;;;;OAOG;IACH,YAAY,CACX,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,WAAW,EACrB,KAAK,GAAE,WAA+B,GACpC,IAAI;IA8CP;;;;OAIG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAYhC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAe1B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAc1B;;;;OAIG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAmB5B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAKlC;;;;OAIG;IACH,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IAgBxC;;OAEG;IACH,kBAAkB,IAAI,MAAM,EAAE;IAI9B;;OAEG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAI9C;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAM1B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAY3B;;OAEG;IACH,aAAa,IAAI,IAAI;IAQrB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI;IA6BzD;;OAEG;IACH,YAAY,IAAI,IAAI;IAOpB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAa/C;;;;OAIG;IACH,eAAe,IAAI,SAAS,EAAE;CAW9B"}

package/dist/services/ToolCoordinator.js

@@ -0,0 +1,318 @@
+/**
+ * ToolCoordinator
+ *
+ * Manages z-index layering and visibility for floating tools.
+ * Prevents conflicts between calculator, ruler, protractor, etc.
+ *
+ * Features:
+ * - Centralized z-index management with defined layers
+ * - Tool visibility state tracking
+ * - Bring-to-front on interaction
+ * - Framework-agnostic (works with any DOM element)
+ *
+ * Part of PIE Assessment Toolkit.
+ */
+import { createLogger } from "../utils/logger";
+const log = createLogger("ToolCoordinator");
+/**
+ * Z-index layers for assessment components
+ */
+export var ZIndexLayer;
+(function (ZIndexLayer) {
+    ZIndexLayer[ZIndexLayer["BASE"] = 0] = "BASE";
+    ZIndexLayer[ZIndexLayer["TOOL"] = 1000] = "TOOL";
+    ZIndexLayer[ZIndexLayer["MODAL"] = 2000] = "MODAL";
+    ZIndexLayer[ZIndexLayer["CONTROL"] = 3000] = "CONTROL";
+    ZIndexLayer[ZIndexLayer["HIGHLIGHT"] = 4000] = "HIGHLIGHT";
+})(ZIndexLayer || (ZIndexLayer = {}));
+export class ToolCoordinator {
+    config;
+    tools = new Map();
+    layerCounters = new Map();
+    listeners = new Set();
+    constructor(config = {}) {
+        this.config = config;
+        // Initialize layer counters
+        this.layerCounters.set(ZIndexLayer.BASE, 0);
+        this.layerCounters.set(ZIndexLayer.TOOL, 0);
+        this.layerCounters.set(ZIndexLayer.MODAL, 0);
+        this.layerCounters.set(ZIndexLayer.CONTROL, 0);
+        this.layerCounters.set(ZIndexLayer.HIGHLIGHT, 0);
+    }
+    /**
+     * Subscribe to tool state changes
+     * Returns unsubscribe function
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /**
+     * Notify all listeners of state change
+     */
+    notifyListeners() {
+        this.listeners.forEach((listener) => listener());
+    }
+    /**
+     * Register a tool with the coordinator
+     *
+     * @param id Unique tool identifier
+     * @param name Display name
+     * @param element DOM element for the tool (optional for backward compatibility)
+     * @param layer Z-index layer (defaults to MODAL)
+     */
+    registerTool(id, name, element, layer = ZIndexLayer.MODAL) {
+        log("registerTool called:", { id, name, hasElement: !!element, layer });
+        if (this.tools.has(id)) {
+            log(`Tool ${id} is already registered`);
+            return;
+        }
+        // If no element provided, create a placeholder registration
+        if (!element) {
+            this.tools.set(id, {
+                id,
+                name,
+                element: null,
+                layer,
+                isVisible: false,
+                baseZIndex: layer,
+            });
+            log("Tool registered without element:", id);
+            return;
+        }
+        // Calculate base z-index for this layer
+        const baseZIndex = layer + this.getNextLayerOffset(layer);
+        // Apply z-index
+        element.style.zIndex = String(baseZIndex);
+        // Create and store event handler to enable proper cleanup
+        const mouseDownHandler = () => this.bringToFront(element);
+        element.addEventListener("mousedown", mouseDownHandler);
+        // Register tool with handler reference
+        this.tools.set(id, {
+            id,
+            name,
+            element,
+            layer,
+            isVisible: false,
+            baseZIndex,
+            mouseDownHandler,
+        });
+        log("Tool registered with element:", id);
+    }
+    /**
+     * Unregister a tool
+     *
+     * @param id Tool identifier
+     */
+    unregisterTool(id) {
+        const tool = this.tools.get(id);
+        if (!tool)
+            return;
+        // Remove event listeners using stored handler reference
+        if (tool.element && tool.mouseDownHandler) {
+            tool.element.removeEventListener("mousedown", tool.mouseDownHandler);
+        }
+        this.tools.delete(id);
+    }
+    /**
+     * Show a tool
+     *
+     * @param id Tool identifier
+     */
+    showTool(id) {
+        const tool = this.tools.get(id);
+        if (!tool) {
+            log(`Tool ${id} not found`);
+            return;
+        }
+        if (tool.element) {
+            tool.element.style.display = "";
+            this.bringToFront(tool.element);
+        }
+        tool.isVisible = true;
+        this.notifyListeners();
+    }
+    /**
+     * Hide a tool
+     *
+     * @param id Tool identifier
+     */
+    hideTool(id) {
+        const tool = this.tools.get(id);
+        if (!tool) {
+            log(`Tool ${id} not found`);
+            return;
+        }
+        if (tool.element) {
+            tool.element.style.display = "none";
+        }
+        tool.isVisible = false;
+        this.notifyListeners();
+    }
+    /**
+     * Toggle tool visibility
+     *
+     * @param id Tool identifier
+     */
+    toggleTool(id) {
+        log("toggleTool called for:", id);
+        const tool = this.tools.get(id);
+        if (!tool) {
+            log(`Tool ${id} not found. Registered tools:`, Array.from(this.tools.keys()));
+            return;
+        }
+        log("Tool found, current visibility:", tool.isVisible);
+        if (tool.isVisible) {
+            this.hideTool(id);
+        }
+        else {
+            this.showTool(id);
+        }
+    }
+    /**
+     * Check if tool is visible
+     *
+     * @param id Tool identifier
+     * @returns true if tool is visible
+     */
+    isToolVisible(id) {
+        const tool = this.tools.get(id);
+        return tool?.isVisible ?? false;
+    }
+    /**
+     * Bring element to front of its layer
+     *
+     * @param element DOM element to bring forward
+     */
+    bringToFront(element) {
+        // Find tool registration
+        const tool = Array.from(this.tools.values()).find((t) => t.element === element);
+        if (!tool)
+            return;
+        // Calculate new z-index (highest in layer + 1)
+        const maxZIndexInLayer = this.getMaxZIndexInLayer(tool.layer);
+        const newZIndex = Math.max(maxZIndexInLayer + 1, tool.layer + 1);
+        // Update z-index
+        element.style.zIndex = String(newZIndex);
+        tool.baseZIndex = newZIndex;
+    }
+    /**
+     * Get all registered tool IDs
+     */
+    getRegisteredTools() {
+        return Array.from(this.tools.keys());
+    }
+    /**
+     * Get tool element by ID
+     */
+    getToolElement(id) {
+        return this.tools.get(id)?.element ?? null;
+    }
+    /**
+     * Get next offset within a layer
+     */
+    getNextLayerOffset(layer) {
+        const current = this.layerCounters.get(layer) ?? 0;
+        this.layerCounters.set(layer, current + 1);
+        return current;
+    }
+    /**
+     * Get maximum z-index currently in use in a layer
+     */
+    getMaxZIndexInLayer(layer) {
+        let max = layer;
+        for (const tool of this.tools.values()) {
+            if (tool.layer === layer) {
+                max = Math.max(max, tool.baseZIndex);
+            }
+        }
+        return max;
+    }
+    /**
+     * Reset all tools to their base z-indices
+     */
+    resetZIndices() {
+        for (const tool of this.tools.values()) {
+            if (tool.element) {
+                tool.element.style.zIndex = String(tool.baseZIndex);
+            }
+        }
+    }
+    /**
+     * Update tool element reference (backward compatibility)
+     *
+     * @param id Tool identifier
+     * @param element New DOM element
+     */
+    updateToolElement(id, element) {
+        const tool = this.tools.get(id);
+        if (!tool) {
+            log(`Tool ${id} not found`);
+            return;
+        }
+        // Remove old event listener using stored handler reference
+        if (tool.element && tool.mouseDownHandler) {
+            tool.element.removeEventListener("mousedown", tool.mouseDownHandler);
+        }
+        // Create new handler and add listener
+        const mouseDownHandler = () => this.bringToFront(element);
+        element.addEventListener("mousedown", mouseDownHandler);
+        // Update element and handler reference
+        tool.element = element;
+        tool.mouseDownHandler = mouseDownHandler;
+        // Apply z-index to new element
+        element.style.zIndex = String(tool.baseZIndex);
+        if (tool.isVisible) {
+            element.style.display = "";
+        }
+        else {
+            element.style.display = "none";
+        }
+    }
+    /**
+     * Hide all tools (backward compatibility)
+     */
+    hideAllTools() {
+        for (const id of this.tools.keys()) {
+            this.hideTool(id);
+        }
+        this.notifyListeners();
+    }
+    /**
+     * Get tool state (interface method)
+     *
+     * @param id Tool identifier
+     * @returns Tool state or undefined
+     */
+    getToolState(id) {
+        const tool = this.tools.get(id);
+        if (!tool)
+            return undefined;
+        return {
+            id: tool.id,
+            name: tool.name,
+            isVisible: tool.isVisible,
+            element: tool.element ?? null,
+            layer: tool.layer,
+        };
+    }
+    /**
+     * Get all visible tools (interface method)
+     *
+     * @returns Array of visible tool states
+     */
+    getVisibleTools() {
+        return Array.from(this.tools.values())
+            .filter((tool) => tool.isVisible)
+            .map((tool) => ({
+            id: tool.id,
+            name: tool.name,
+            isVisible: tool.isVisible,
+            element: tool.element ?? null,
+            layer: tool.layer,
+        }));
+    }
+}
+//# sourceMappingURL=ToolCoordinator.js.map