doom-design-system 0.5.0 → 0.6.0

package/dist/components/Chart/engine/CoordinateSystem.d.ts

@@ -0,0 +1,59 @@
+export interface ContainerStyle {
+    borderLeft: number;
+    borderTop: number;
+    paddingLeft: number;
+    paddingTop: number;
+}
+export interface PlotBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface ChartCoordinates {
+    chartX: number;
+    chartY: number;
+    isWithinPlot: boolean;
+}
+/**
+ * CoordinateSystem
+ *
+ * Handles the complexity of mapping screen coordinates (ClientX/Y)
+ * to Chart coordinates (PlotX/Y), accounting for:
+ * - Container position (getBoundingClientRect)
+ * - CSS Borders and Padding
+ * - Layout offsets (e.g. Headers pushing the plot down)
+ */
+export declare class CoordinateSystem {
+    private containerRect;
+    private containerStyle;
+    private plotOffset;
+    private plotBounds;
+    /**
+     * Set the container element and its bounds.
+     * Call this on mount and when the container resizes.
+     */
+    setContainer(element: Element | null, plotElement?: Element | null, plotBounds?: PlotBounds): void;
+    /**
+     * Update the container bounds explicitly (e.g. from ResizeObserver).
+     */
+    updateBounds(rect: DOMRect, plotBounds?: PlotBounds): void;
+    getContainerRect(): DOMRect | null;
+    getContainerStyle(): ContainerStyle;
+    getPlotOffset(): {
+        x: number;
+        y: number;
+    };
+    getPlotBounds(): PlotBounds | null;
+    /**
+     * Resolve a pointer event to container-relative (padding-box) coordinates.
+     */
+    resolvePointerCoordinates(clientX: number, clientY: number): {
+        x: number;
+        y: number;
+    } | null;
+    /**
+     * Calculate coordinates relative to the plot area.
+     */
+    resolveChartCoordinates(containerX: number, containerY: number): ChartCoordinates;
+}

package/dist/components/Chart/engine/CoordinateSystem.js

@@ -0,0 +1,126 @@
+/**
+ * CoordinateSystem
+ *
+ * Handles the complexity of mapping screen coordinates (ClientX/Y)
+ * to Chart coordinates (PlotX/Y), accounting for:
+ * - Container position (getBoundingClientRect)
+ * - CSS Borders and Padding
+ * - Layout offsets (e.g. Headers pushing the plot down)
+ */
+export class CoordinateSystem {
+    constructor() {
+        this.containerRect = null;
+        this.containerStyle = {
+            borderLeft: 0,
+            borderTop: 0,
+            paddingLeft: 0,
+            paddingTop: 0,
+        };
+        this.plotOffset = { x: 0, y: 0 };
+        this.plotBounds = null;
+    }
+    /**
+     * Set the container element and its bounds.
+     * Call this on mount and when the container resizes.
+     */
+    setContainer(element, plotElement = null, plotBounds) {
+        if (element) {
+            this.containerRect = element.getBoundingClientRect();
+            const style = window.getComputedStyle(element);
+            this.containerStyle = {
+                borderLeft: parseFloat(style.borderLeftWidth) || 0,
+                borderTop: parseFloat(style.borderTopWidth) || 0,
+                paddingLeft: parseFloat(style.paddingLeft) || 0,
+                paddingTop: parseFloat(style.paddingTop) || 0,
+            };
+            // Calculate plot offset if plotElement is provided
+            if (plotElement) {
+                const plotRect = plotElement.getBoundingClientRect();
+                this.plotOffset = {
+                    x: plotRect.left -
+                        this.containerRect.left -
+                        this.containerStyle.borderLeft,
+                    y: plotRect.top -
+                        this.containerRect.top -
+                        this.containerStyle.borderTop,
+                };
+            }
+            else {
+                // Fallback to padding
+                this.plotOffset = {
+                    x: this.containerStyle.paddingLeft,
+                    y: this.containerStyle.paddingTop,
+                };
+            }
+        }
+        else {
+            this.containerRect = null;
+            this.containerStyle = {
+                borderLeft: 0,
+                borderTop: 0,
+                paddingLeft: 0,
+                paddingTop: 0,
+            };
+            this.plotOffset = { x: 0, y: 0 };
+        }
+        if (plotBounds) {
+            this.plotBounds = plotBounds;
+        }
+    }
+    /**
+     * Update the container bounds explicitly (e.g. from ResizeObserver).
+     */
+    updateBounds(rect, plotBounds) {
+        this.containerRect = rect;
+        if (plotBounds) {
+            this.plotBounds = plotBounds;
+        }
+    }
+    getContainerRect() {
+        return this.containerRect;
+    }
+    getContainerStyle() {
+        return this.containerStyle;
+    }
+    getPlotOffset() {
+        return this.plotOffset;
+    }
+    getPlotBounds() {
+        return this.plotBounds;
+    }
+    /**
+     * Resolve a pointer event to container-relative (padding-box) coordinates.
+     */
+    resolvePointerCoordinates(clientX, clientY) {
+        if (!this.containerRect) {
+            return null;
+        }
+        return {
+            x: clientX - this.containerRect.left - this.containerStyle.borderLeft,
+            y: clientY - this.containerRect.top - this.containerStyle.borderTop,
+        };
+    }
+    /**
+     * Calculate coordinates relative to the plot area.
+     */
+    resolveChartCoordinates(containerX, containerY) {
+        // If we have plot bounds (from d3 scales/margin), use them for plotting
+        // Note: containerX/Y here are expected to be relative to the Plot Offset already?
+        // Wait, the previous implementation passed "searchX/Y" which were (signal.x - plotOffset).
+        // Let's keep it consistent.
+        if (!this.plotBounds) {
+            // If no plot bounds defined, assume full container? OR just return relative coords
+            return { chartX: containerX, chartY: containerY, isWithinPlot: true };
+        }
+        // plotBounds.x/y are usually the margin.left/top
+        // If containerX is already relative to the visual plot origin (wrapper),
+        // and margin is inside that wrapper (SVG g transform), then we need to subtract margin.
+        const chartX = containerX - this.plotBounds.x;
+        const chartY = containerY - this.plotBounds.y;
+        const isWithinPlot = chartX >= 0 &&
+            chartX <= this.plotBounds.width &&
+            chartY >= 0 &&
+            chartY <= this.plotBounds.height;
+        return { chartX, chartY, isWithinPlot };
+    }
+}

package/dist/components/Chart/engine/Engine.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Engine
+ *
+ * The central brain of the Chart interaction system.
+ * Receives InputSignals, queries the SpatialIndex, and dispatches to the Scheduler.
+ */
+import { TaskHandler } from "./Scheduler";
+import { IndexedPoint, SpatialMapOptions } from "./SpatialMap";
+import { InputAction, InputSignal } from "./types";
+export interface EngineOptions extends SpatialMapOptions {
+    /**
+     * Called when an engine event is ready for dispatch.
+     * In the full system, this connects to the EventBus.
+     */
+    onEvent?: TaskHandler;
+}
+/**
+ * The Engine is the core of the Hyper-Engine architecture.
+ *
+ * Responsibilities:
+ * 1. Receive InputSignals from the InteractionLayer (or remote sources)
+ * 2. Normalize coordinates (client -> container)
+ * 3. Query the SpatialMap to find candidates
+ * 4. Schedule events based on priority
+ * 5. Dispatch to sensors via the configured handler
+ */
+export declare class Engine<T = unknown> {
+    private spatialMap;
+    private scheduler;
+    private coords;
+    private disposed;
+    constructor(options?: EngineOptions);
+    /**
+     * Set the container element and its bounds.
+     * Call this on mount and when the container resizes.
+     */
+    setContainer(element: Element | null, plotElement?: Element | null, plotBounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): void;
+    /**
+     * Update the container bounds without changing the element reference.
+     * Useful for resize handling.
+     */
+    updateBounds(rect: DOMRect, plotBounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): void;
+    /**
+     * Update the spatial index with new data points.
+     */
+    updateData(points: IndexedPoint<T>[]): void;
+    /**
+     * Set the event handler.
+     */
+    setHandler(handler: TaskHandler<T>): void;
+    /**
+     * Clean up all resources.
+     */
+    dispose(): void;
+    /**
+     * Process an InputSignal.
+     * This is the main entry point for all user interactions.
+     *
+     * @param signal - The normalized input signal
+     */
+    input(signal: InputSignal): void;
+    /**
+     * Create an InputSignal from a native PointerEvent.
+     * Convenience method for the InteractionLayer.
+     */
+    createSignal(event: PointerEvent | MouseEvent | TouchEvent, action: InputAction, userId?: string): InputSignal | null;
+    /**
+     * Create an InputSignal from a KeyboardEvent.
+     */
+    createKeySignal(event: KeyboardEvent, userId?: string): InputSignal;
+    /**
+     * Determine the scheduling priority for an action.
+     */
+    private determinePriority;
+    /**
+     * Get the current container bounds.
+     */
+    getContainerRect(): DOMRect | null;
+    /**
+     * Get the current plot bounds.
+     */
+    getPlotBounds(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    /**
+     * Check if the engine has been disposed.
+     */
+    isDisposed(): boolean;
+}

package/dist/components/Chart/engine/Engine.js

@@ -0,0 +1,226 @@
+/**
+ * Engine
+ *
+ * The central brain of the Chart interaction system.
+ * Receives InputSignals, queries the SpatialIndex, and dispatches to the Scheduler.
+ */
+import { CoordinateSystem } from "./CoordinateSystem.js";
+import { Scheduler } from "./Scheduler.js";
+import { SpatialMap } from "./SpatialMap.js";
+import { InputAction, InputSource, TaskPriority, } from "./types.js";
+// =============================================================================
+// ENGINE CLASS
+// =============================================================================
+/**
+ * The Engine is the core of the Hyper-Engine architecture.
+ *
+ * Responsibilities:
+ * 1. Receive InputSignals from the InteractionLayer (or remote sources)
+ * 2. Normalize coordinates (client -> container)
+ * 3. Query the SpatialMap to find candidates
+ * 4. Schedule events based on priority
+ * 5. Dispatch to sensors via the configured handler
+ */
+export class Engine {
+    constructor(options = {}) {
+        this.disposed = false;
+        this.spatialMap = new SpatialMap(options);
+        this.scheduler = new Scheduler();
+        this.coords = new CoordinateSystem();
+        if (options.onEvent) {
+            this.scheduler.setHandler(options.onEvent);
+        }
+    }
+    // ===========================================================================
+    // LIFECYCLE
+    // ===========================================================================
+    /**
+     * Set the container element and its bounds.
+     * Call this on mount and when the container resizes.
+     */
+    setContainer(element, plotElement = null, plotBounds) {
+        if (element) {
+            this.spatialMap.setContainer(element);
+        }
+        else {
+            this.spatialMap.setContainer(null);
+        }
+        this.coords.setContainer(element, plotElement, plotBounds);
+    }
+    /**
+     * Update the container bounds without changing the element reference.
+     * Useful for resize handling.
+     */
+    updateBounds(rect, plotBounds) {
+        this.coords.updateBounds(rect, plotBounds);
+    }
+    /**
+     * Update the spatial index with new data points.
+     */
+    updateData(points) {
+        this.spatialMap.updateIndex(points);
+    }
+    /**
+     * Set the event handler.
+     */
+    setHandler(handler) {
+        this.scheduler.setHandler(handler);
+    }
+    /**
+     * Clean up all resources.
+     */
+    dispose() {
+        if (this.disposed) {
+            return;
+        }
+        this.disposed = true;
+        this.scheduler.dispose();
+        this.spatialMap.clear();
+    }
+    // ===========================================================================
+    // INPUT PROCESSING
+    // ===========================================================================
+    /**
+     * Process an InputSignal.
+     * This is the main entry point for all user interactions.
+     *
+     * @param signal - The normalized input signal
+     */
+    input(signal) {
+        if (this.disposed) {
+            return;
+        }
+        const plotOffset = this.coords.getPlotOffset();
+        const searchX = signal.x - plotOffset.x;
+        const searchY = signal.y - plotOffset.y;
+        const candidates = this.spatialMap.find(searchX, searchY, {
+            x: signal.x,
+            y: signal.y,
+        });
+        const { chartX, chartY, isWithinPlot } = this.coords.resolveChartCoordinates(searchX, searchY);
+        const primaryCandidate = candidates[0];
+        const sliceCandidates = primaryCandidate
+            ? this.spatialMap.findAllAtX(primaryCandidate.coordinate.x)
+            : [];
+        const event = {
+            signal,
+            candidates,
+            primaryCandidate,
+            sliceCandidates,
+            chartX,
+            chartY,
+            isWithinPlot,
+        };
+        const priority = this.determinePriority(signal.action);
+        this.scheduler.schedule(priority, event);
+    }
+    /**
+     * Create an InputSignal from a native PointerEvent.
+     * Convenience method for the InteractionLayer.
+     */
+    createSignal(event, action, userId = "local") {
+        let clientX;
+        let clientY;
+        if ("touches" in event && event.touches.length > 0) {
+            clientX = event.touches[0].clientX;
+            clientY = event.touches[0].clientY;
+        }
+        else if ("clientX" in event) {
+            clientX = event.clientX;
+            clientY = event.clientY;
+        }
+        else {
+            return null;
+        }
+        const resolved = this.coords.resolvePointerCoordinates(clientX, clientY);
+        if (!resolved) {
+            return null;
+        }
+        let source = InputSource.MOUSE;
+        if ("pointerType" in event) {
+            source =
+                event.pointerType === "touch" ? InputSource.TOUCH : InputSource.MOUSE;
+        }
+        else if ("touches" in event) {
+            source = InputSource.TOUCH;
+        }
+        return {
+            id: "pointerId" in event ? event.pointerId : 0,
+            action,
+            source,
+            x: resolved.x,
+            y: resolved.y,
+            timestamp: performance.now(),
+            userId,
+            modifiers: {
+                shift: event.shiftKey || false,
+                ctrl: event.ctrlKey || false,
+                alt: event.altKey || false,
+                meta: event.metaKey || false,
+            },
+        };
+    }
+    /**
+     * Create an InputSignal from a KeyboardEvent.
+     */
+    createKeySignal(event, userId = "local") {
+        return {
+            id: 0,
+            action: InputAction.KEY,
+            source: InputSource.KEYBOARD,
+            x: 0,
+            y: 0,
+            timestamp: performance.now(),
+            userId,
+            key: event.key,
+            modifiers: {
+                shift: event.shiftKey,
+                ctrl: event.ctrlKey,
+                alt: event.altKey,
+                meta: event.metaKey,
+            },
+        };
+    }
+    // ===========================================================================
+    // INTERNAL HELPERS
+    // ===========================================================================
+    /**
+     * Determine the scheduling priority for an action.
+     */
+    determinePriority(action) {
+        switch (action) {
+            case InputAction.START:
+            case InputAction.END:
+            case InputAction.CANCEL:
+            case InputAction.KEY:
+                // These need immediate processing (for preventDefault, state changes)
+                return TaskPriority.CRITICAL;
+            case InputAction.MOVE:
+                // Move events can be batched for performance
+                return TaskPriority.VISUAL;
+            default:
+                return TaskPriority.VISUAL;
+        }
+    }
+    // ===========================================================================
+    // GETTERS (For Testing/Debugging)
+    // ===========================================================================
+    /**
+     * Get the current container bounds.
+     */
+    getContainerRect() {
+        return this.coords.getContainerRect();
+    }
+    /**
+     * Get the current plot bounds.
+     */
+    getPlotBounds() {
+        return this.coords.getPlotBounds();
+    }
+    /**
+     * Check if the engine has been disposed.
+     */
+    isDisposed() {
+        return this.disposed;
+    }
+}

package/dist/components/Chart/engine/Scheduler.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Scheduler
+ *
+ * Manages the execution timing of engine tasks.
+ * Critical tasks (pointer down) run synchronously.
+ * Visual tasks (hover) are batched to requestAnimationFrame.
+ */
+import { EngineEvent, TaskPriority } from "./types";
+export type TaskHandler<T = unknown> = (event: EngineEvent<T>) => void;
+/**
+ * The Scheduler controls when events are dispatched to sensors.
+ * It uses a priority-based system to ensure critical interactions
+ * (like drag start) happen immediately, while visual updates
+ * (like hover highlights) are batched for performance.
+ */
+export declare class Scheduler<T = unknown> {
+    private visualQueue;
+    private idleQueue;
+    private rafId;
+    private handler;
+    /**
+     * Register the handler that will process events.
+     * In the full system, this is the EventBus.dispatch method.
+     */
+    setHandler(handler: TaskHandler<T>): void;
+    /**
+     * Schedule a task for execution.
+     *
+     * @param priority - The priority level of the task
+     * @param event - The engine event to dispatch
+     */
+    schedule(priority: TaskPriority, event: EngineEvent<T>): void;
+    /**
+     * Execute a critical task immediately.
+     * This is synchronous to allow preventDefault() on the original event.
+     */
+    private executeCritical;
+    /**
+     * Schedule a flush of the visual queue on the next animation frame.
+     */
+    private scheduleVisualFlush;
+    /**
+     * Process all queued visual tasks.
+     * Only the most recent event per input ID is processed (coalescing).
+     */
+    private flushVisualQueue;
+    /**
+     * Schedule a flush of the idle queue using requestIdleCallback.
+     */
+    private scheduleIdleFlush;
+    /**
+     * Process all queued idle tasks.
+     */
+    private flushIdleQueue;
+    /**
+     * Cancel all pending tasks and clean up.
+     */
+    dispose(): void;
+}