doom-design-system 0.5.0 → 0.6.0

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

@@ -0,0 +1,139 @@
+/**
+ * Scheduler
+ *
+ * Manages the execution timing of engine tasks.
+ * Critical tasks (pointer down) run synchronously.
+ * Visual tasks (hover) are batched to requestAnimationFrame.
+ */
+import { TaskPriority } from "./types.js";
+/**
+ * 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 class Scheduler {
+    constructor() {
+        this.visualQueue = [];
+        this.idleQueue = [];
+        this.rafId = null;
+        this.handler = null;
+    }
+    /**
+     * Register the handler that will process events.
+     * In the full system, this is the EventBus.dispatch method.
+     */
+    setHandler(handler) {
+        this.handler = handler;
+    }
+    /**
+     * Schedule a task for execution.
+     *
+     * @param priority - The priority level of the task
+     * @param event - The engine event to dispatch
+     */
+    schedule(priority, event) {
+        const task = {
+            priority,
+            event,
+            timestamp: performance.now(),
+        };
+        switch (priority) {
+            case TaskPriority.CRITICAL:
+                // Critical tasks execute immediately (synchronously)
+                this.executeCritical(task);
+                break;
+            case TaskPriority.VISUAL:
+                // Visual tasks are batched to the next animation frame
+                this.visualQueue.push(task);
+                this.scheduleVisualFlush();
+                break;
+            case TaskPriority.IDLE:
+                // Idle tasks are deferred even further
+                this.idleQueue.push(task);
+                this.scheduleIdleFlush();
+                break;
+        }
+    }
+    /**
+     * Execute a critical task immediately.
+     * This is synchronous to allow preventDefault() on the original event.
+     */
+    executeCritical(task) {
+        if (this.handler) {
+            this.handler(task.event);
+        }
+    }
+    /**
+     * Schedule a flush of the visual queue on the next animation frame.
+     */
+    scheduleVisualFlush() {
+        if (this.rafId !== null) {
+            return;
+        } // Already scheduled
+        this.rafId = requestAnimationFrame(() => {
+            this.flushVisualQueue();
+            this.rafId = null;
+        });
+    }
+    /**
+     * Process all queued visual tasks.
+     * Only the most recent event per input ID is processed (coalescing).
+     */
+    flushVisualQueue() {
+        if (!this.handler || this.visualQueue.length === 0) {
+            return;
+        }
+        // Coalesce: Group by input ID, keep only the latest
+        const latestByInputId = new Map();
+        for (const task of this.visualQueue) {
+            const existing = latestByInputId.get(task.event.signal.id);
+            if (!existing || task.timestamp > existing.timestamp) {
+                latestByInputId.set(task.event.signal.id, task);
+            }
+        }
+        // Clear the queue
+        this.visualQueue = [];
+        // Dispatch coalesced events
+        for (const task of Array.from(latestByInputId.values())) {
+            this.handler(task.event);
+        }
+    }
+    /**
+     * Schedule a flush of the idle queue using requestIdleCallback.
+     */
+    scheduleIdleFlush() {
+        if (typeof requestIdleCallback !== "undefined") {
+            requestIdleCallback(() => this.flushIdleQueue());
+        }
+        else {
+            // Fallback for browsers without requestIdleCallback
+            setTimeout(() => this.flushIdleQueue(), 50);
+        }
+    }
+    /**
+     * Process all queued idle tasks.
+     */
+    flushIdleQueue() {
+        if (!this.handler || this.idleQueue.length === 0) {
+            return;
+        }
+        const tasks = this.idleQueue;
+        this.idleQueue = [];
+        for (const task of tasks) {
+            this.handler(task.event);
+        }
+    }
+    /**
+     * Cancel all pending tasks and clean up.
+     */
+    dispose() {
+        if (this.rafId !== null) {
+            cancelAnimationFrame(this.rafId);
+            this.rafId = null;
+        }
+        this.visualQueue = [];
+        this.idleQueue = [];
+        this.handler = null;
+    }
+}

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

@@ -0,0 +1,114 @@
+/**
+ * SpatialMap
+ *
+ * The "Hybrid Radar" that finds interaction candidates.
+ * Combines DOM-based hit testing with Quadtree spatial queries.
+ */
+import { InteractionCandidate } from "./types";
+/**
+ * Standard data attributes used to tag interactive DOM elements.
+ * These are read by the SpatialMap during DOM-based hit testing.
+ */
+export declare const CHART_DATA_ATTRS: {
+    readonly TYPE: "data-chart-type";
+    readonly SERIES_ID: "data-chart-series";
+    readonly INDEX: "data-chart-index";
+    readonly DRAGGABLE: "data-chart-draggable";
+};
+/**
+ * A point that has been indexed in the Quadtree.
+ * This is stored in memory for fast spatial queries.
+ */
+export interface IndexedPoint<T = unknown> {
+    x: number;
+    y: number;
+    data: T;
+    seriesId: string;
+    dataIndex: number;
+    seriesColor?: string;
+    draggable?: boolean;
+    suppressMarker?: boolean;
+}
+export interface SpatialMapOptions {
+    /**
+     * The radius (in pixels) for "magnetic" snapping to data points.
+     * Points within this radius will be returned as candidates.
+     * @default 20
+     */
+    magneticRadius?: number;
+    /**
+     * Whether to use DOM-based hit testing (elementsFromPoint).
+     * Disable for unit testing without a DOM.
+     * @default true
+     */
+    useDomHitTesting?: boolean;
+}
+/**
+ * SpatialMap provides the "Hybrid Radar" for finding interaction targets.
+ *
+ * It combines two strategies:
+ * 1. **DOM Hit Testing (Broad Phase):** Uses `elementsFromPoint` to find
+ *    large, complex shapes (bars, areas, labels) accurately.
+ * 2. **Quadtree (Fine Phase):** Uses a spatial tree to find nearby data
+ *    points with "magnetic" snapping (great for scatter/line charts).
+ */
+export declare class SpatialMap<T = unknown> {
+    private tree;
+    private points;
+    private xBuckets;
+    private containerElement;
+    private options;
+    constructor(options?: SpatialMapOptions);
+    /**
+     * Set the container element for DOM-based hit testing.
+     * Elements outside this container are ignored.
+     */
+    setContainer(element: Element | null): void;
+    /**
+     * Update the spatial index with new data points.
+     * Call this when data changes.
+     *
+     * @param points - The data points with their pixel coordinates
+     */
+    updateIndex(points: IndexedPoint<T>[]): void;
+    /**
+     * Clear the spatial index.
+     */
+    clear(): void;
+    /**
+     * Find all indexed points sharing the given X coordinate (O(k) bucket lookup).
+     * Returns every point at that X regardless of Y distance — intended for
+     * multi-series vertical-slice hover.
+     *
+     * @param x - The exact X pixel coordinate (as stored in the index)
+     */
+    findAllAtX(x: number): InteractionCandidate<T>[];
+    /**
+     * Find all interaction candidates near a point.
+     *
+     * @param x - X coordinate (relative to plot area for Quadtree)
+     * @param y - Y coordinate (relative to plot area for Quadtree)
+     * @param containerPoint - Optional container-relative coordinates for DOM hit testing
+     * @returns Sorted array of candidates (closest first)
+     */
+    find(x: number, y: number, containerPoint?: {
+        x: number;
+        y: number;
+    }): InteractionCandidate<T>[];
+    /**
+     * Find candidates using DOM elementsFromPoint.
+     */
+    private findFromDOM;
+    /**
+     * Convert a DOM element into an InteractionCandidate.
+     */
+    private hydrateElement;
+    /**
+     * Find candidates using the Quadtree (nearby data points).
+     */
+    private findFromTree;
+    /**
+     * Get the current options.
+     */
+    getOptions(): Required<SpatialMapOptions>;
+}

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

@@ -0,0 +1,270 @@
+/**
+ * SpatialMap
+ *
+ * The "Hybrid Radar" that finds interaction candidates.
+ * Combines DOM-based hit testing with Quadtree spatial queries.
+ */
+import { quadtree } from "d3-quadtree";
+// =============================================================================
+// DATA ATTRIBUTES (For DOM Element Tagging)
+// =============================================================================
+/**
+ * Standard data attributes used to tag interactive DOM elements.
+ * These are read by the SpatialMap during DOM-based hit testing.
+ */
+export const CHART_DATA_ATTRS = {
+    TYPE: "data-chart-type",
+    SERIES_ID: "data-chart-series",
+    INDEX: "data-chart-index",
+    DRAGGABLE: "data-chart-draggable",
+};
+/**
+ * SpatialMap provides the "Hybrid Radar" for finding interaction targets.
+ *
+ * It combines two strategies:
+ * 1. **DOM Hit Testing (Broad Phase):** Uses `elementsFromPoint` to find
+ *    large, complex shapes (bars, areas, labels) accurately.
+ * 2. **Quadtree (Fine Phase):** Uses a spatial tree to find nearby data
+ *    points with "magnetic" snapping (great for scatter/line charts).
+ */
+export class SpatialMap {
+    constructor(options = {}) {
+        var _a, _b;
+        this.tree = null;
+        this.points = [];
+        this.xBuckets = new Map();
+        this.containerElement = null;
+        this.options = {
+            magneticRadius: (_a = options.magneticRadius) !== null && _a !== void 0 ? _a : 40,
+            useDomHitTesting: (_b = options.useDomHitTesting) !== null && _b !== void 0 ? _b : true,
+        };
+    }
+    /**
+     * Set the container element for DOM-based hit testing.
+     * Elements outside this container are ignored.
+     */
+    setContainer(element) {
+        this.containerElement = element;
+    }
+    /**
+     * Update the spatial index with new data points.
+     * Call this when data changes.
+     *
+     * @param points - The data points with their pixel coordinates
+     */
+    updateIndex(points) {
+        var _a;
+        this.points = points;
+        if (points.length === 0) {
+            this.tree = null;
+            this.xBuckets = new Map();
+            return;
+        }
+        this.tree = quadtree()
+            .x((d) => d.x)
+            .y((d) => d.y)
+            .addAll(points);
+        // Build the X-bucket index for O(k) vertical-slice lookups
+        this.xBuckets = new Map();
+        for (const p of points) {
+            const bucket = (_a = this.xBuckets.get(p.x)) !== null && _a !== void 0 ? _a : [];
+            bucket.push(p);
+            this.xBuckets.set(p.x, bucket);
+        }
+    }
+    /**
+     * Clear the spatial index.
+     */
+    clear() {
+        this.points = [];
+        this.tree = null;
+        this.xBuckets = new Map();
+    }
+    /**
+     * Find all indexed points sharing the given X coordinate (O(k) bucket lookup).
+     * Returns every point at that X regardless of Y distance — intended for
+     * multi-series vertical-slice hover.
+     *
+     * @param x - The exact X pixel coordinate (as stored in the index)
+     */
+    findAllAtX(x) {
+        var _a;
+        const bucket = (_a = this.xBuckets.get(x)) !== null && _a !== void 0 ? _a : [];
+        return bucket.map((p) => ({
+            type: "data-point",
+            data: p.data,
+            seriesId: p.seriesId,
+            dataIndex: p.dataIndex,
+            coordinate: { x: p.x, y: p.y },
+            distance: 0,
+            seriesColor: p.seriesColor,
+            draggable: p.draggable,
+            suppressMarker: p.suppressMarker,
+        }));
+    }
+    /**
+     * Find all interaction candidates near a point.
+     *
+     * @param x - X coordinate (relative to plot area for Quadtree)
+     * @param y - Y coordinate (relative to plot area for Quadtree)
+     * @param containerPoint - Optional container-relative coordinates for DOM hit testing
+     * @returns Sorted array of candidates (closest first)
+     */
+    find(x, y, containerPoint) {
+        const candidates = [];
+        // Phase 1: DOM Hit Testing (Broad Phase)
+        if (this.options.useDomHitTesting) {
+            // Use container coordinates if available, otherwise assume x/y are container-relative
+            // (This fallback retains backward compatibility but might be wrong if x/y are plot-relative)
+            const domX = containerPoint ? containerPoint.x : x;
+            const domY = containerPoint ? containerPoint.y : y;
+            const domCandidates = this.findFromDOM(domX, domY);
+            candidates.push(...domCandidates);
+        }
+        // Phase 2: Quadtree (Fine Phase)
+        const treeCandidates = this.findFromTree(x, y);
+        candidates.push(...treeCandidates);
+        candidates.sort((a, b) => {
+            var _a, _b;
+            const zDiff = ((_a = b.zIndex) !== null && _a !== void 0 ? _a : 0) - ((_b = a.zIndex) !== null && _b !== void 0 ? _b : 0);
+            if (zDiff !== 0) {
+                return zDiff;
+            }
+            return a.distance - b.distance;
+        });
+        return candidates;
+    }
+    /**
+     * Find candidates using DOM elementsFromPoint.
+     */
+    findFromDOM(x, y) {
+        if (!this.containerElement) {
+            return [];
+        }
+        const rect = this.containerElement.getBoundingClientRect();
+        const viewportX = rect.left + x;
+        const viewportY = rect.top + y;
+        const elements = document.elementsFromPoint(viewportX, viewportY);
+        const candidates = [];
+        for (const element of elements) {
+            if (!this.containerElement.contains(element)) {
+                continue;
+            }
+            const chartType = element.getAttribute(CHART_DATA_ATTRS.TYPE);
+            if (!chartType) {
+                continue;
+            }
+            const candidate = this.hydrateElement(element, chartType, x, y);
+            if (candidate) {
+                candidates.push(candidate);
+            }
+        }
+        return candidates;
+    }
+    /**
+     * Convert a DOM element into an InteractionCandidate.
+     */
+    hydrateElement(element, type, pointerX, pointerY) {
+        var _a, _b;
+        const seriesId = (_a = element.getAttribute(CHART_DATA_ATTRS.SERIES_ID)) !== null && _a !== void 0 ? _a : undefined;
+        const indexStr = element.getAttribute(CHART_DATA_ATTRS.INDEX);
+        const draggable = element.getAttribute(CHART_DATA_ATTRS.DRAGGABLE) === "true";
+        const rect = element.getBoundingClientRect();
+        const containerRect = (_b = this.containerElement) === null || _b === void 0 ? void 0 : _b.getBoundingClientRect();
+        if (!containerRect) {
+            return null;
+        }
+        const elementCenterX = rect.left + rect.width / 2 - containerRect.left;
+        const elementCenterY = rect.top + rect.height / 2 - containerRect.top;
+        const distance = Math.hypot(pointerX - elementCenterX, pointerY - elementCenterY);
+        let data;
+        let dataIndex;
+        if (indexStr !== null && seriesId) {
+            dataIndex = parseInt(indexStr, 10);
+            const point = this.points.find((p) => p.seriesId === seriesId && p.dataIndex === dataIndex);
+            if (point) {
+                data = point.data;
+            }
+        }
+        // Fall back to D3's __data__ binding for custom renders that don't index their points
+        if (!data) {
+            const d3Data = element.__data__;
+            if (d3Data && !Array.isArray(d3Data)) {
+                data = d3Data;
+            }
+        }
+        const zIndex = parseZIndex(element);
+        if (!data) {
+            return null;
+        }
+        return {
+            type: type,
+            data,
+            seriesId,
+            dataIndex,
+            coordinate: { x: elementCenterX, y: elementCenterY },
+            distance,
+            element,
+            draggable,
+            zIndex,
+        };
+    }
+    /**
+     * Find candidates using the Quadtree (nearby data points).
+     */
+    findFromTree(x, y) {
+        if (!this.tree) {
+            return [];
+        }
+        const candidates = [];
+        const radius = this.options.magneticRadius;
+        this.tree.visit((node, x0, y0, x1, y1) => {
+            if (x0 > x + radius ||
+                x1 < x - radius ||
+                y0 > y + radius ||
+                y1 < y - radius) {
+                return true; // Skip this branch
+            }
+            // Leaf nodes don't have the 'length' property defined
+            if (!("length" in node)) {
+                let current = node;
+                while (current) {
+                    const point = current.data;
+                    if (point) {
+                        const distance = Math.hypot(point.x - x, point.y - y);
+                        if (distance <= radius) {
+                            candidates.push({
+                                type: "data-point",
+                                data: point.data,
+                                seriesId: point.seriesId,
+                                dataIndex: point.dataIndex,
+                                coordinate: { x: point.x, y: point.y },
+                                distance,
+                                seriesColor: point.seriesColor,
+                                draggable: point.draggable,
+                                suppressMarker: point.suppressMarker,
+                            });
+                        }
+                    }
+                    current = current.next;
+                }
+            }
+            return false; // Continue visiting
+        });
+        return candidates;
+    }
+    /**
+     * Get the current options.
+     */
+    getOptions() {
+        return Object.assign({}, this.options);
+    }
+}
+/**
+ * Parse the z-index from an element's computed style.
+ */
+function parseZIndex(element) {
+    const style = getComputedStyle(element);
+    const zIndex = parseInt(style.zIndex, 10);
+    return isNaN(zIndex) ? 0 : zIndex;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Engine Module
+ *
+ * Public API for the Chart interaction engine.
+ */
+export type { EngineOptions } from "./Engine";
+export { Engine } from "./Engine";
+export type { TaskHandler } from "./Scheduler";
+export { Scheduler } from "./Scheduler";
+export type { IndexedPoint, SpatialMapOptions } from "./SpatialMap";
+export { CHART_DATA_ATTRS, SpatialMap } from "./SpatialMap";
+export type { CandidateType, EngineEvent, InputSignal, InteractionCandidate, ScheduledTask, TaskPriority, } from "./types";
+export { InputAction, InputSource, TaskPriority as TaskPriorityEnum, } from "./types";

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

@@ -0,0 +1,9 @@
+/**
+ * Engine Module
+ *
+ * Public API for the Chart interaction engine.
+ */
+export { Engine } from "./Engine.js";
+export { Scheduler } from "./Scheduler.js";
+export { CHART_DATA_ATTRS, SpatialMap } from "./SpatialMap.js";
+export { InputAction, InputSource, TaskPriority as TaskPriorityEnum, } from "./types.js";

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

@@ -0,0 +1,137 @@
+/**
+ * Engine Type Definitions
+ *
+ * These types define the core data structures for the Hyper-Engine architecture.
+ * They are intentionally decoupled from React and DOM to enable pure logic testing.
+ */
+/**
+ * The source of an input signal. Used for multiplayer and debugging.
+ */
+export declare enum InputSource {
+    MOUSE = "mouse",
+    TOUCH = "touch",
+    KEYBOARD = "keyboard",
+    REMOTE = "remote"
+}
+/**
+ * The type of input action being performed.
+ */
+export declare enum InputAction {
+    START = "START",
+    MOVE = "MOVE",
+    END = "END",
+    CANCEL = "CANCEL",
+    KEY = "KEY"
+}
+/**
+ * InputSignal is the normalized, DOM-independent representation of a user input.
+ * This is what the Engine processes - NOT raw PointerEvents.
+ *
+ * Think of this as the "packet" that travels through the engine pipeline.
+ */
+export interface InputSignal {
+    /** Unique identifier for this input stream (e.g., pointerId for multi-touch) */
+    id: number;
+    /** The action being performed */
+    action: InputAction;
+    /** Where this input came from */
+    source: InputSource;
+    /** X coordinate relative to the chart container (NOT the viewport) */
+    x: number;
+    /** Y coordinate relative to the chart container */
+    y: number;
+    /** High-resolution timestamp (performance.now()) for frame scheduling */
+    timestamp: number;
+    /** User identifier for multiplayer support. 'local' for the current user. */
+    userId: string;
+    /** Optional: For keyboard events, the key that was pressed */
+    key?: string;
+    /** Optional: Modifier keys state */
+    modifiers?: {
+        shift: boolean;
+        ctrl: boolean;
+        alt: boolean;
+        meta: boolean;
+    };
+}
+/**
+ * The type of element that was hit by the spatial query.
+ */
+export type CandidateType = "data-point" | "bar" | "area" | "label" | "axis" | "legend-item" | "custom";
+/**
+ * InteractionCandidate is a "hydrated" hit result.
+ * It contains everything a Sensor needs to make a decision.
+ */
+export interface InteractionCandidate<T = unknown> {
+    /** What kind of element this is */
+    type: CandidateType;
+    /** The underlying data object (if applicable) */
+    data?: T;
+    /** The series this belongs to (if applicable) */
+    seriesId?: string;
+    /** The index within the series (for data points) */
+    dataIndex?: number;
+    /** The color of the series (for styling behaviors) */
+    seriesColor?: string;
+    /** The pixel coordinates of this candidate (for snapping) */
+    coordinate: {
+        x: number;
+        y: number;
+    };
+    /** Distance from the pointer (for sorting by proximity) */
+    distance: number;
+    /** The DOM element that was hit (for DOM-sourced candidates) */
+    element?: Element;
+    /** Whether this candidate is draggable */
+    draggable?: boolean;
+    /** Whether this candidate should suppress marker rendering */
+    suppressMarker?: boolean;
+    /** Z-index for layering (higher = on top) */
+    zIndex?: number;
+}
+/**
+ * EngineEvent is the fully processed event that gets dispatched to Sensors.
+ * It combines the raw input with the spatial query results.
+ */
+export interface EngineEvent<T = unknown> {
+    /** The normalized input that triggered this event */
+    signal: InputSignal;
+    /** All candidates found by the spatial query, sorted by relevance */
+    candidates: InteractionCandidate<T>[];
+    /** The primary (closest/most relevant) candidate, if any */
+    primaryCandidate?: InteractionCandidate<T>;
+    /**
+     * All indexed points sharing the primary candidate's X position, regardless
+     * of Y distance. Pre-computed via an O(k) bucket lookup (k = number of series
+     * at that X). Always an array; empty when there is no primary candidate.
+     * Intended for multi-series vertical-slice hover.
+     */
+    sliceCandidates: InteractionCandidate<T>[];
+    /** X coordinate relative to the plot area (after margins) */
+    chartX: number;
+    /** Y coordinate relative to the plot area */
+    chartY: number;
+    /** Whether the pointer is within the plot area bounds */
+    isWithinPlot: boolean;
+}
+/**
+ * Priority levels for the scheduler.
+ * Critical tasks run synchronously to enable preventDefault().
+ * Visual tasks are batched to requestAnimationFrame.
+ */
+export declare enum TaskPriority {
+    /** Must run immediately (pointer down, to enable preventDefault) */
+    CRITICAL = 0,
+    /** Can be batched to next frame (hover updates, tooltip positioning) */
+    VISUAL = 1,
+    /** Low priority, can be deferred (analytics, logging) */
+    IDLE = 2
+}
+/**
+ * A task to be scheduled by the engine.
+ */
+export interface ScheduledTask<T = unknown> {
+    priority: TaskPriority;
+    event: EngineEvent<T>;
+    timestamp: number;
+}