@pie-players/pie-assessment-toolkit 0.3.74 → 1.0.0-beta.0

package/dist/services/ToolCoordinator.js

@@ -1,19 +1,17 @@
 /**
  * ToolCoordinator
  *
- * Manages z-index layering and visibility for floating tools.
- * Prevents conflicts between calculator, ruler, protractor, etc.
+ * Holds the visibility state of floating tools and stacks their elements.
  *
- * 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.
+ * Visibility is state: the coordinator records it and notifies subscribers, and
+ * whoever renders a tool shows or hides it from that state. Stacking is the
+ * coordinator's alone: an element bound to a tool (`registerTool` with an
+ * element, or `updateToolElement`) takes a z-index in the tool's layer and comes
+ * to the front of that layer when shown or pressed.
  */
-import { createLogger } from "../utils/logger.js";
-const log = createLogger("ToolCoordinator");
+import { createPieLogger, isGlobalDebugEnabled, } from "@pie-players/pie-players-shared/pie";
+import { parseScopedToolId } from "./tool-instance-id.js";
+const logger = createPieLogger("ToolCoordinator", isGlobalDebugEnabled);
 /**
  * Z-index layers for assessment components
  */
@@ -25,27 +23,23 @@ export var ZIndexLayer;
     ZIndexLayer[ZIndexLayer["CONTROL"] = 3000] = "CONTROL";
     ZIndexLayer[ZIndexLayer["HIGHLIGHT"] = 4000] = "HIGHLIGHT";
 })(ZIndexLayer || (ZIndexLayer = {}));
+function matchesFilter(id, filter) {
+    if (!filter?.baseId)
+        return true;
+    return (parseScopedToolId(id)?.baseToolId ?? id) === filter.baseId;
+}
+function toToolState(entry) {
+    return {
+        id: entry.id,
+        name: entry.name,
+        isVisible: entry.isVisible,
+        element: entry.element,
+        layer: entry.layer,
+    };
+}
 export class ToolCoordinator {
     tools = new Map();
-    layerCounters = new Map();
     listeners = new Set();
-    /**
-     * Activation (on/off) state keyed by tool id, kept independent of the
-     * element registration lifecycle. A tool's DOM element can be unregistered
-     * and re-registered as the item re-renders (e.g. a model change re-mounts
-     * the toolbar overlay); when that happens the on/off state must survive so
-     * that only an explicit toggle — the toolbar button — turns a tool off.
-     * Cleared on genuine teardown via {@link releaseTool}.
-     */
-    visibilityState = new Map();
-    constructor() {
-        // 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
@@ -56,303 +50,231 @@ export class ToolCoordinator {
             this.listeners.delete(listener);
         };
     }
-    /**
-     * Notify all listeners of state change
-     */
     notifyListeners() {
-        this.listeners.forEach((listener) => listener());
+        for (const listener of this.listeners) {
+            try {
+                listener();
+            }
+            catch (error) {
+                console.warn("[ToolCoordinator] listener failed:", error);
+            }
+        }
     }
     /**
-     * Register a tool with the coordinator
-     *
-     * @param id Unique tool identifier
-     * @param name Display name
-     * @param element DOM element for the tool (optional)
-     * @param layer Z-index layer (defaults to MODAL)
+     * Register a tool with the coordinator. Registering a known id keeps its
+     * on/off state and takes the name, the element when one is given, and the
+     * layer when none was declared before. Without a `layer` the tool stacks on
+     * TOOL until a registration names one.
      */
-    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;
-        }
-        // Restore prior on/off state. A re-registration (e.g. after an item
-        // re-render unmounts and re-mounts the tool element) must preserve the
-        // tool's activation state so only an explicit toggle can turn it off.
-        const isVisible = this.visibilityState.get(id) ?? false;
-        // If no element provided, create a placeholder registration
-        if (!element) {
-            this.tools.set(id, {
-                id,
-                name,
-                element: null,
-                layer,
-                isVisible,
-                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);
-        // Reflect restored visibility onto the freshly registered element.
-        element.style.display = isVisible ? "" : "none";
-        // 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, {
+    registerTool(id, name, element, layer) {
+        logger.debug("registerTool called:", {
             id,
             name,
-            element,
+            hasElement: !!element,
             layer,
-            isVisible,
-            baseZIndex,
-            mouseDownHandler,
         });
-        if (isVisible) {
-            this.bringToFront(element);
+        let entry = this.tools.get(id);
+        if (entry) {
+            entry.name = name;
+            const wasRegistered = entry.registered;
+            entry.registered = true;
+            if (layer !== undefined && !entry.layerDeclared) {
+                entry.layer = layer;
+                entry.layerDeclared = true;
+                this.stackOnTop(entry);
+            }
+            else if (!wasRegistered) {
+                this.stackOnTop(entry);
+            }
+        }
+        else {
+            entry = {
+                id,
+                name,
+                registered: true,
+                element: null,
+                layer: layer ?? ZIndexLayer.TOOL,
+                layerDeclared: layer !== undefined,
+                isVisible: false,
+                baseZIndex: 0,
+            };
+            this.tools.set(id, entry);
+            this.stackOnTop(entry);
         }
-        log("Tool registered with element:", id);
+        if (element)
+            this.updateToolElement(id, element);
     }
     /**
-     * Unregister a tool
-     *
-     * Detaches the element binding (listeners, registration) but intentionally
-     * preserves the tool's activation state in {@link visibilityState}, so a
-     * subsequent re-registration of the same id (e.g. after an item re-render)
-     * restores whether the tool was on or off. Use {@link releaseTool} to also
-     * discard the activation state on genuine teardown.
-     *
-     * @param id Tool identifier
+     * Unregister a tool's element binding, keeping its on/off state so a
+     * re-registration of the same id (an item re-render) restores it. Use
+     * {@link releaseTool} on genuine teardown.
      */
     unregisterTool(id) {
-        const tool = this.tools.get(id);
-        if (!tool)
+        const entry = this.tools.get(id);
+        if (!entry?.registered)
             return;
-        // Remove event listeners using stored handler reference
-        if (tool.element && tool.mouseDownHandler) {
-            tool.element.removeEventListener("mousedown", tool.mouseDownHandler);
-        }
-        this.tools.delete(id);
+        this.detachElement(entry);
+        entry.registered = false;
     }
     /**
-     * Fully release a tool: unregister its element binding AND discard its
-     * preserved activation state. Call this on genuine teardown (e.g. leaving
-     * the item/section that owns the tool) rather than {@link unregisterTool},
-     * which keeps the on/off state alive across element re-registration.
-     *
-     * @param id Tool identifier
+     * Fully release a tool: unregister its element binding and discard its
+     * on/off state. Call this on genuine teardown (leaving the item or section
+     * that owns the tool).
      */
     releaseTool(id) {
-        this.unregisterTool(id);
-        this.visibilityState.delete(id);
+        const entry = this.tools.get(id);
+        if (!entry)
+            return;
+        this.detachElement(entry);
+        this.tools.delete(id);
+        if (entry.isVisible)
+            this.notifyListeners();
     }
-    /**
-     * Show a tool
-     *
-     * @param id Tool identifier
-     */
     showTool(id) {
-        const tool = this.tools.get(id);
-        if (!tool) {
-            log(`Tool ${id} not found`);
+        const entry = this.tools.get(id);
+        if (!entry) {
+            logger.debug(`Tool ${id} not found`);
             return;
         }
-        if (tool.element) {
-            tool.element.style.display = "";
-            this.bringToFront(tool.element);
-        }
-        tool.isVisible = true;
-        this.visibilityState.set(id, true);
-        this.notifyListeners();
+        if (entry.element)
+            this.bringToFront(entry.element);
+        this.setVisible(entry, true);
     }
-    /**
-     * Hide a tool
-     *
-     * @param id Tool identifier
-     */
     hideTool(id) {
-        const tool = this.tools.get(id);
-        if (!tool) {
-            log(`Tool ${id} not found`);
+        const entry = this.tools.get(id);
+        if (!entry) {
+            logger.debug(`Tool ${id} not found`);
             return;
         }
-        if (tool.element) {
-            tool.element.style.display = "none";
-        }
-        tool.isVisible = false;
-        this.visibilityState.set(id, false);
-        this.notifyListeners();
+        this.setVisible(entry, false);
     }
-    /**
-     * 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()));
+        const entry = this.tools.get(id);
+        if (!entry) {
+            logger.debug(`Tool ${id} not found`);
             return;
         }
-        log("Tool found, current visibility:", tool.isVisible);
-        if (tool.isVisible) {
+        if (entry.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);
-        if (tool)
-            return tool.isVisible;
-        // No live element registration (e.g. mid re-render, between unmount and
-        // re-mount): fall back to the preserved activation state so the tool
-        // doesn't read as "off" during the gap.
-        return this.visibilityState.get(id) ?? false;
+        return this.tools.get(id)?.isVisible ?? false;
     }
     /**
-     * Bring element to front of its layer
-     *
-     * @param element DOM element to bring forward
+     * Bring a bound element to the front of its tool's layer. An element no tool
+     * is bound to is left alone.
      */
     bringToFront(element) {
-        // Find tool registration
-        const tool = Array.from(this.tools.values()).find((t) => t.element === element);
-        if (!tool)
+        const entry = Array.from(this.tools.values()).find((t) => t.element === element);
+        if (!entry)
             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());
+        this.stackOnTop(entry);
     }
     /**
-     * Get tool element by ID
+     * Release every tool, registered or not, and drop the subscribers. The
+     * owning toolkit coordinator calls this when it is disposed.
      */
-    getToolElement(id) {
-        return this.tools.get(id)?.element ?? null;
+    destroy() {
+        const anyVisible = Array.from(this.tools.values()).some((entry) => entry.isVisible);
+        for (const entry of this.tools.values())
+            this.detachElement(entry);
+        this.tools.clear();
+        if (anyVisible)
+            this.notifyListeners();
+        this.listeners.clear();
     }
-    /**
-     * Get next offset within a layer
-     */
-    getNextLayerOffset(layer) {
-        const current = this.layerCounters.get(layer) ?? 0;
-        this.layerCounters.set(layer, current + 1);
-        return current;
+    setVisible(entry, visible) {
+        if (entry.isVisible === visible)
+            return;
+        entry.isVisible = visible;
+        this.notifyListeners();
     }
-    /**
-     * 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);
-            }
+    detachElement(entry) {
+        if (entry.element && entry.mouseDownHandler) {
+            entry.element.removeEventListener("mousedown", entry.mouseDownHandler);
         }
-        return max;
+        entry.element = null;
+        entry.mouseDownHandler = undefined;
     }
     /**
-     * Reset all tools to their base z-indices
+     * Put `entry` in front of its layer. The layer is renumbered from its base on
+     * every move, so its z-indices stay within it however often tools are raised.
      */
-    resetZIndices() {
-        for (const tool of this.tools.values()) {
-            if (tool.element) {
-                tool.element.style.zIndex = String(tool.baseZIndex);
-            }
+    stackOnTop(entry) {
+        const others = Array.from(this.tools.values())
+            .filter((other) => other.registered && other.layer === entry.layer && other !== entry)
+            .sort((a, b) => a.baseZIndex - b.baseZIndex);
+        const top = entry.layer + others.length + 1;
+        if (entry.baseZIndex === top &&
+            others.every((other) => other.baseZIndex < top)) {
+            return;
         }
+        [...others, entry].forEach((stacked, index) => {
+            stacked.baseZIndex = entry.layer + 1 + index;
+            if (stacked.element) {
+                stacked.element.style.zIndex = String(stacked.baseZIndex);
+            }
+        });
     }
     /**
-     * Update tool element reference
+     * Bind the element a tool stacks by. It takes the tool's z-index and comes to
+     * the front of the layer when pressed, and when bound while the tool is shown.
      *
-     * @param id Tool identifier
-     * @param element New DOM element
+     * The outermost element stacks: binding an element inside the bound one keeps
+     * the binding, so a tool rendered inside a toolbar's floating window stacks
+     * by that window whichever binds first.
      */
     updateToolElement(id, element) {
-        const tool = this.tools.get(id);
-        if (!tool) {
-            log(`Tool ${id} not found`);
+        const entry = this.tools.get(id);
+        if (!entry?.registered) {
+            logger.debug(`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
+        if (entry.element === element)
+            return;
+        if (entry.element?.isConnected && entry.element.contains(element))
+            return;
+        this.detachElement(entry);
         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";
-        }
+        entry.element = element;
+        entry.mouseDownHandler = mouseDownHandler;
+        element.style.zIndex = String(entry.baseZIndex);
+        if (entry.isVisible)
+            this.bringToFront(element);
     }
     /**
-     * Hide all tools
+     * Hide every visible tool, or every instance of one tool with
+     * `{ baseId }`, notifying subscribers once.
      */
-    hideAllTools() {
-        for (const id of this.tools.keys()) {
-            this.hideTool(id);
+    hideAllTools(filter) {
+        let changed = false;
+        for (const entry of this.tools.values()) {
+            if (!entry.isVisible || !matchesFilter(entry.id, filter))
+                continue;
+            entry.isVisible = false;
+            changed = true;
         }
-        this.notifyListeners();
+        if (changed)
+            this.notifyListeners();
     }
-    /**
-     * Get tool state (interface method)
-     *
-     * @param id Tool identifier
-     * @returns Tool state or undefined
-     */
+    /** State of a tool an element registration holds. */
     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,
-        };
+        const entry = this.tools.get(id);
+        return entry?.registered ? toToolState(entry) : undefined;
     }
     /**
-     * Get all visible tools (interface method)
-     *
-     * @returns Array of visible tool states
+     * Every visible tool, or every visible instance of one tool with
+     * `{ baseId }`. A tool shown while its element re-renders counts, as
+     * {@link isToolVisible} counts it.
      */
-    getVisibleTools() {
+    getVisibleTools(filter) {
         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,
-        }));
+            .filter((entry) => entry.isVisible && matchesFilter(entry.id, filter))
+            .map(toToolState);
     }
 }