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

package/dist/services/ToolCoordinator.d.ts

@@ -1,154 +1,94 @@
 /**
  * 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 type { ToolCoordinatorApi, ToolState } from "./interfaces.js";
+import type { ToolCoordinatorApi, ToolState, ToolStateFilter } from "./interfaces.js";
 /**
  * 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) (2000-2999)
+    TOOL = 1000,// Floating tools and their windows (1000-1999)
+    MODAL = 2000,// Modal tool surfaces (2000-2999)
     CONTROL = 3000,// Drag handles, resize controls (3000-3999)
     HIGHLIGHT = 4000
 }
 export declare class ToolCoordinator implements ToolCoordinatorApi {
     private tools;
-    private layerCounters;
     private listeners;
-    /**
-     * 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}.
-     */
-    private visibilityState;
-    constructor();
     /**
      * 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)
-     * @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: string, name: string, element?: HTMLElement, layer?: ZIndexLayer): void;
     /**
-     * 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: string): void;
     /**
-     * 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: 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
+     * Bring a bound element to the front of its tool's layer. An element no tool
+     * is bound to is left alone.
      */
     bringToFront(element: HTMLElement): void;
     /**
-     * Get all registered tool IDs
-     */
-    getRegisteredTools(): string[];
-    /**
-     * 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: string): HTMLElement | null;
+    destroy(): void;
+    private setVisible;
+    private detachElement;
     /**
-     * Get next offset within a layer
+     * 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.
      */
-    private getNextLayerOffset;
+    private stackOnTop;
     /**
-     * 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
+     * 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: string, element: HTMLElement): void;
     /**
-     * Hide all tools
-     */
-    hideAllTools(): void;
-    /**
-     * Get tool state (interface method)
-     *
-     * @param id Tool identifier
-     * @returns Tool state or undefined
+     * Hide every visible tool, or every instance of one tool with
+     * `{ baseId }`, notifying subscribers once.
      */
+    hideAllTools(filter?: ToolStateFilter): void;
+    /** State of a tool an element registration holds. */
     getToolState(id: string): ToolState | 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(): ToolState[];
+    getVisibleTools(filter?: ToolStateFilter): ToolState[];
 }