doom-design-system 0.5.0 → 0.6.0

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

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ */
+// =============================================================================
+// INPUT SIGNAL (The Universal Input Format)
+// =============================================================================
+/**
+ * The source of an input signal. Used for multiplayer and debugging.
+ */
+export var InputSource;
+(function (InputSource) {
+    InputSource["MOUSE"] = "mouse";
+    InputSource["TOUCH"] = "touch";
+    InputSource["KEYBOARD"] = "keyboard";
+    InputSource["REMOTE"] = "remote";
+})(InputSource || (InputSource = {}));
+/**
+ * The type of input action being performed.
+ */
+export var InputAction;
+(function (InputAction) {
+    InputAction["START"] = "START";
+    InputAction["MOVE"] = "MOVE";
+    InputAction["END"] = "END";
+    InputAction["CANCEL"] = "CANCEL";
+    InputAction["KEY"] = "KEY";
+})(InputAction || (InputAction = {}));
+// =============================================================================
+// SCHEDULER TYPES
+// =============================================================================
+/**
+ * Priority levels for the scheduler.
+ * Critical tasks run synchronously to enable preventDefault().
+ * Visual tasks are batched to requestAnimationFrame.
+ */
+export var TaskPriority;
+(function (TaskPriority) {
+    /** Must run immediately (pointer down, to enable preventDefault) */
+    TaskPriority[TaskPriority["CRITICAL"] = 0] = "CRITICAL";
+    /** Can be batched to next frame (hover updates, tooltip positioning) */
+    TaskPriority[TaskPriority["VISUAL"] = 1] = "VISUAL";
+    /** Low priority, can be deferred (analytics, logging) */
+    TaskPriority[TaskPriority["IDLE"] = 2] = "IDLE";
+})(TaskPriority || (TaskPriority = {}));

package/dist/components/Chart/hooks/useEngine.d.ts

@@ -0,0 +1,43 @@
+/**
+ * useEngine Hook
+ *
+ * React hook that manages the Engine lifecycle, connecting the
+ * pure Engine to React's component tree.
+ *
+ * Responsibilities:
+ * - Create and dispose Engine instance
+ * - Sync data to spatial index
+ * - Handle container attachment and resize
+ * - Wire up event handler with stable callback pattern
+ */
+import { Engine, EngineEvent } from "../engine";
+export interface UseEngineOptions<T = unknown> {
+    /** Data points to index for spatial queries */
+    data?: T[];
+    /** Function to get X coordinate from data item */
+    getX?: (d: T) => number;
+    /** Function to get Y coordinate from data item */
+    getY?: (d: T) => number;
+    /** Function to get series ID from data item */
+    getSeriesId?: (d: T) => string;
+    /** Function to get data index from data item */
+    getDataIndex?: (d: T, index: number) => number;
+    /** Plot bounds for coordinate calculations */
+    plotBounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Event handler for engine events */
+    onEvent?: (event: EngineEvent<T>) => void;
+    /** Magnetic radius for snapping (pixels) */
+    magneticRadius?: number;
+}
+export interface UseEngineResult<T = unknown> {
+    /** The Engine instance */
+    engine: Engine<T>;
+    /** Ref to attach to the container element */
+    containerRef: React.RefObject<HTMLElement | null>;
+}
+export declare function useEngine<T = unknown>(options?: UseEngineOptions<T>): UseEngineResult<T>;

package/dist/components/Chart/hooks/useEngine.js

@@ -0,0 +1,128 @@
+/**
+ * useEngine Hook
+ *
+ * React hook that manages the Engine lifecycle, connecting the
+ * pure Engine to React's component tree.
+ *
+ * Responsibilities:
+ * - Create and dispose Engine instance
+ * - Sync data to spatial index
+ * - Handle container attachment and resize
+ * - Wire up event handler with stable callback pattern
+ */
+import { useEffect, useMemo, useRef, useState } from "react";
+import { Engine } from "../engine/index.js";
+// =============================================================================
+// HOOK IMPLEMENTATION
+// =============================================================================
+export function useEngine(options = {}) {
+    const { data, getX, getY, getSeriesId, getDataIndex, plotBounds, onEvent, magneticRadius, } = options;
+    // Container ref for DOM attachment
+    const containerRef = useRef(null);
+    // Track container element state for triggering effects
+    const [containerElement, setContainerElement] = useState(null);
+    // =========================================================================
+    // Engine Creation (Stable)
+    // =========================================================================
+    const engine = useMemo(() => new Engine({
+        magneticRadius,
+        useDomHitTesting: true,
+    }), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    []);
+    // =========================================================================
+    // Event Handler (Stable Callback Pattern)
+    // =========================================================================
+    const onEventRef = useRef(onEvent);
+    onEventRef.current = onEvent;
+    useEffect(() => {
+        engine.setHandler((event) => {
+            var _a;
+            (_a = onEventRef.current) === null || _a === void 0 ? void 0 : _a.call(onEventRef, event);
+        });
+    }, [engine]);
+    // =========================================================================
+    // Plot Bounds Sync
+    // =========================================================================
+    useEffect(() => {
+        if (!plotBounds) {
+            return;
+        }
+        const currentRect = engine.getContainerRect();
+        if (currentRect) {
+            engine.updateBounds(currentRect, plotBounds);
+        }
+        else {
+            engine.setContainer(null, null, plotBounds);
+        }
+    }, [engine, plotBounds]);
+    // =========================================================================
+    // Data Sync to Spatial Index
+    // =========================================================================
+    useEffect(() => {
+        if (!data || !getX || !getY) {
+            engine.updateData([]);
+            return;
+        }
+        const points = data.map((d, i) => {
+            var _a, _b;
+            return ({
+                x: getX(d),
+                y: getY(d),
+                data: d,
+                seriesId: (_a = getSeriesId === null || getSeriesId === void 0 ? void 0 : getSeriesId(d)) !== null && _a !== void 0 ? _a : "default",
+                dataIndex: (_b = getDataIndex === null || getDataIndex === void 0 ? void 0 : getDataIndex(d, i)) !== null && _b !== void 0 ? _b : i,
+            });
+        });
+        engine.updateData(points);
+    }, [engine, data, getX, getY, getSeriesId, getDataIndex]);
+    // =========================================================================
+    // Container Ref Detection
+    // Refs don't trigger re-renders, so we poll on RAF to detect changes
+    // =========================================================================
+    useEffect(() => {
+        if (containerRef.current && containerRef.current !== containerElement) {
+            setContainerElement(containerRef.current);
+        }
+        const rafId = requestAnimationFrame(() => {
+            if (containerRef.current !== containerElement) {
+                setContainerElement(containerRef.current);
+            }
+        });
+        return () => cancelAnimationFrame(rafId);
+    }, [containerElement]);
+    // =========================================================================
+    // Container Attachment & ResizeObserver
+    // =========================================================================
+    useEffect(() => {
+        if (!containerElement) {
+            return;
+        }
+        engine.setContainer(containerElement, null, plotBounds);
+        const resizeObserver = new ResizeObserver((entries) => {
+            for (const entry of entries) {
+                const rect = entry.target.getBoundingClientRect();
+                engine.updateBounds(rect, plotBounds);
+            }
+        });
+        resizeObserver.observe(containerElement);
+        return () => {
+            resizeObserver.disconnect();
+        };
+    }, [engine, containerElement, plotBounds]);
+    // =========================================================================
+    // Cleanup on Unmount
+    // =========================================================================
+    useEffect(() => {
+        return () => {
+            engine.dispose();
+        };
+    }, [engine]);
+    // =========================================================================
+    // Return Value
+    // =========================================================================
+    return {
+        engine,
+        containerRef,
+    };
+}

package/dist/components/Chart/sensors/DataHoverSensor/DataHoverSensor.d.ts

@@ -1,31 +1,29 @@
 import { Sensor } from "../../types/events";
-import { HoverMode, InteractionChannel } from "../../types/interaction";
+import { InteractionChannel } from "../../types/interaction";
 export interface HoverSensorOptions {
-    /**
-     * How to find the target.
-     */
-    mode: HoverMode;
     /**
      * Name for the interaction channel.
      * Defaults to 'primary-hover'.
      */
     name?: InteractionChannel | string;
+    /**
+     * When true, only fire when the pointer is directly over a tagged DOM element
+     * (DOM hit-test match). Proximal quadtree candidates that have no backing
+     * element are ignored. Useful for area-fill charts like treemaps where
+     * magnetic snapping across empty gaps is undesirable.
+     * @default false
+     */
+    exactHit?: boolean;
+    /**
+     * When true, all series at the primary candidate's X position are included
+     * as targets (vertical-slice behaviour). Useful for multi-series line/bar/area
+     * charts where series share the same X domain values.
+     * @default false
+     */
+    verticalSlice?: boolean;
 }
 /**
  * The DataHoverSensor detects pointer movements over the chart plot
- * and identifies the closest data targets based on the specified mode.
- *
- * It coordinates with the interaction store to trigger hover-based
- * behaviors like tooltips and markers.
- *
- * @example
- * ```tsx
- * Root({ sensors: [DataHoverSensor()] })
- * ```
- *
- * @example
- * ```tsx
- * DataHoverSensor({ mode: 'exact' })
- * ```
+ * and identifies the closest data targets.
  */
 export declare const DataHoverSensor: (options?: HoverSensorOptions) => Sensor;

package/dist/components/Chart/sensors/DataHoverSensor/DataHoverSensor.js

@@ -1,58 +1,45 @@
+import { InputAction } from "../../engine/index.js";
 import { InteractionChannel } from "../../types/interaction.js";
-import { findClosestTargets } from "../utils/search.js";
 /**
  * The DataHoverSensor detects pointer movements over the chart plot
- * and identifies the closest data targets based on the specified mode.
- *
- * It coordinates with the interaction store to trigger hover-based
- * behaviors like tooltips and markers.
- *
- * @example
- * ```tsx
- * Root({ sensors: [DataHoverSensor()] })
- * ```
- *
- * @example
- * ```tsx
- * DataHoverSensor({ mode: 'exact' })
- * ```
+ * and identifies the closest data targets.
  */
-export const DataHoverSensor = (options = { mode: "nearest-x" }) => {
-    const { mode, name = InteractionChannel.PRIMARY_HOVER } = options;
-    return ({ on, off, getChartContext, upsertInteraction, removeInteraction, }) => {
-        const handleMove = (event) => {
-            const ctx = getChartContext();
-            if (!ctx || !ctx.chartStore) {
-                return;
-            }
-            const state = ctx.chartStore.getState();
-            const targets = findClosestTargets(event, mode, state);
-            if (targets.length > 0) {
-                const isTouch = "touches" in event.nativeEvent ||
-                    "changedTouches" in event.nativeEvent;
-                upsertInteraction(name, {
-                    pointer: {
-                        x: event.coordinates.chartX,
-                        y: event.coordinates.chartY,
-                        containerX: event.coordinates.containerX,
-                        containerY: event.coordinates.containerY,
-                        isTouch,
-                    },
-                    targets,
-                });
-            }
-            else {
-                removeInteraction(name);
-            }
-        };
-        const handleLeave = () => {
+export const DataHoverSensor = (options = {}) => {
+    const { name = InteractionChannel.PRIMARY_HOVER, exactHit = false, verticalSlice = false, } = options;
+    return (event, { upsertInteraction, removeInteraction }) => {
+        const { signal, primaryCandidate, sliceCandidates, chartX, chartY, isWithinPlot, } = event;
+        if (signal.action !== InputAction.MOVE &&
+            signal.action !== InputAction.CANCEL) {
+            return;
+        }
+        if (signal.action === InputAction.CANCEL ||
+            (!isWithinPlot && signal.source !== "touch")) {
             removeInteraction(name);
-        };
-        on("CHART_POINTER_MOVE", handleMove);
-        on("CHART_POINTER_LEAVE", handleLeave);
-        return () => {
-            off("CHART_POINTER_MOVE", handleMove);
-            off("CHART_POINTER_LEAVE", handleLeave);
-        };
+            return;
+        }
+        // When exactHit is true, discard proximal (quadtree-only) candidates that
+        // have no backing DOM element — the pointer is over empty space.
+        const candidate = exactHit && primaryCandidate && !primaryCandidate.element
+            ? undefined
+            : primaryCandidate;
+        if (candidate) {
+            const isTouch = signal.source === "touch";
+            const targets = verticalSlice && sliceCandidates.length > 0
+                ? sliceCandidates
+                : [candidate];
+            upsertInteraction(name, {
+                pointer: {
+                    x: chartX,
+                    y: chartY,
+                    containerX: signal.x,
+                    containerY: signal.y,
+                    isTouch,
+                },
+                targets,
+            });
+        }
+        else {
+            removeInteraction(name);
+        }
     };
 };

package/dist/components/Chart/sensors/DragSensor/DragSensor.d.ts

@@ -0,0 +1,38 @@
+import { Sensor } from "../../types/events";
+import { InteractionChannel } from "../../types/interaction";
+export interface DragSensorOptions<T = any> {
+    /**
+     * Interaction channel name.
+     * @default InteractionChannel.DRAG
+     */
+    name?: InteractionChannel | string;
+    /**
+     * Callback fired when a drag ends.
+     */
+    onDragEnd?: (originalData: T, newValue: {
+        x: any;
+        y: any;
+    }, pixelPosition: {
+        x: number;
+        y: number;
+    }) => void;
+    /**
+     * Callback fired during drag.
+     */
+    onDrag?: (originalData: T, currentValue: {
+        x: any;
+        y: any;
+    }, pixelPosition: {
+        x: number;
+        y: number;
+    }) => void;
+    /**
+     * Radius in pixels for hit detection.
+     * @default 20
+     */
+    hitRadius?: number;
+}
+/**
+ * DragSensor enables dragging data points ("pucks") on a chart.
+ */
+export declare const DragSensor: <T = any>(options?: DragSensorOptions<T>) => Sensor<T>;

package/dist/components/Chart/sensors/DragSensor/DragSensor.js

@@ -0,0 +1,105 @@
+import { InputAction } from "../../engine/index.js";
+import { InteractionChannel, } from "../../types/interaction.js";
+/**
+ * DragSensor enables dragging data points ("pucks") on a chart.
+ */
+export const DragSensor = (options = {}) => {
+    const { name = InteractionChannel.DRAG, onDragEnd, onDrag, hitRadius = 20, } = options;
+    let isDragging = false;
+    let dragTarget = null;
+    let startPosition = null;
+    return (event, { getChartContext, upsertInteraction, removeInteraction }) => {
+        const { signal, primaryCandidate, chartX, chartY } = event;
+        // 1. START DRAG
+        if (signal.action === InputAction.START) {
+            if (primaryCandidate && primaryCandidate.distance <= hitRadius) {
+                // Start dragging exact target
+                const target = primaryCandidate;
+                const initialData = target.data;
+                if (initialData) {
+                    isDragging = true;
+                    startPosition = { x: chartX, y: chartY };
+                    const interactionTarget = {
+                        data: initialData,
+                        coordinate: target.coordinate,
+                        seriesId: target.seriesId,
+                    };
+                    dragTarget = interactionTarget;
+                    // Register interaction
+                    const interaction = {
+                        target: interactionTarget,
+                        startPosition,
+                        currentPosition: startPosition,
+                        currentValue: { x: null, y: null },
+                        isDragging: true,
+                    };
+                    upsertInteraction(name, interaction);
+                }
+            }
+            return;
+        }
+        // 2. MOVE DRAG
+        if (signal.action === InputAction.MOVE) {
+            if (!isDragging || !dragTarget || !startPosition) {
+                return;
+            }
+            const currentPosition = { x: chartX, y: chartY };
+            const ctx = getChartContext();
+            if (!ctx || !ctx.chartStore) {
+                return;
+            }
+            const state = ctx.chartStore.getState();
+            const { x: xScale, y: yScale } = state.scales;
+            // Invert
+            let xValue = null;
+            let yValue = null;
+            if (xScale && "invert" in xScale) {
+                xValue = xScale.invert(currentPosition.x);
+            }
+            if (yScale && "invert" in yScale) {
+                yValue = yScale.invert(currentPosition.y);
+            }
+            const currentValue = { x: xValue, y: yValue };
+            // Update interaction
+            const interaction = {
+                target: dragTarget,
+                startPosition,
+                currentPosition,
+                currentValue,
+                isDragging: true,
+            };
+            upsertInteraction(name, interaction);
+            if (onDrag) {
+                onDrag(dragTarget.data, currentValue, currentPosition);
+            }
+            return;
+        }
+        // 3. END / CANCEL DRAG
+        if (signal.action === InputAction.END ||
+            signal.action === InputAction.CANCEL) {
+            if (!isDragging || !dragTarget) {
+                return;
+            }
+            const finalPosition = { x: chartX, y: chartY };
+            const ctx = getChartContext();
+            const state = ctx.chartStore.getState();
+            const { x: xScale, y: yScale } = state.scales;
+            let xValue = null;
+            let yValue = null;
+            if (xScale && "invert" in xScale) {
+                xValue = xScale.invert(finalPosition.x);
+            }
+            if (yScale && "invert" in yScale) {
+                yValue = yScale.invert(finalPosition.y);
+            }
+            if (signal.action === InputAction.END && onDragEnd) {
+                onDragEnd(dragTarget.data, { x: xValue, y: yValue }, finalPosition);
+            }
+            // Cleanup
+            isDragging = false;
+            dragTarget = null;
+            startPosition = null;
+            removeInteraction(name);
+        }
+    };
+};

package/dist/components/Chart/sensors/DragSensor/index.d.ts

@@ -0,0 +1,2 @@
+export type { DragSensorOptions } from "./DragSensor";
+export { DragSensor } from "./DragSensor";

package/dist/components/Chart/sensors/DragSensor/index.js

@@ -0,0 +1 @@
+export { DragSensor } from "./DragSensor.js";

package/dist/components/Chart/sensors/{KeyboardSensor.d.ts → KeyboardSensor/KeyboardSensor.d.ts}

@@ -1,4 +1,4 @@
-import { Sensor } from "../types/events";
+import { Sensor } from "../../types/events";
 /**
  * Professional-grade Keyboard Sensor for A11y.
  * Allows navigating data points using ArrowKeys.

package/dist/components/Chart/sensors/KeyboardSensor/KeyboardSensor.js

@@ -0,0 +1,86 @@
+import { InputAction } from "../../engine/index.js";
+import { resolveAccessor } from "../../types/accessors.js";
+import { InteractionChannel } from "../../types/interaction.js";
+/**
+ * Professional-grade Keyboard Sensor for A11y.
+ * Allows navigating data points using ArrowKeys.
+ */
+export const KeyboardSensor = (options = {}) => {
+    const { name = InteractionChannel.PRIMARY_HOVER } = options;
+    let focusedIndex = -1;
+    return (event, { getChartContext, upsertInteraction, removeInteraction }) => {
+        const { signal } = event;
+        // Only handle KEY actions
+        if (signal.action !== InputAction.KEY || !signal.key) {
+            return;
+        }
+        const ctx = getChartContext();
+        const { chartStore } = ctx;
+        const state = chartStore.getState();
+        const { data, scales, config } = state;
+        if (!data || data.length === 0 || !scales.x) {
+            return;
+        }
+        // Update Focus
+        let changed = false;
+        if (signal.key === "ArrowRight") {
+            focusedIndex = Math.min(focusedIndex + 1, data.length - 1);
+            changed = true;
+        }
+        else if (signal.key === "ArrowLeft") {
+            focusedIndex = Math.max(focusedIndex - 1, 0);
+            changed = true;
+            if (focusedIndex < 0) {
+                focusedIndex = 0;
+            }
+        }
+        else if (signal.key === "Escape") {
+            focusedIndex = -1;
+            removeInteraction(name);
+            return;
+        }
+        if (changed && focusedIndex >= 0) {
+            const d = data[focusedIndex];
+            const { x: xScale, y: yScale } = scales;
+            // Resolve coordinates
+            // TODO: Accessor resolution should be centralized or consistent with Root
+            const xAcc = config.x || ((v) => v[0]); // fallback
+            const yAcc = config.y || ((v) => v[1]);
+            const getX = resolveAccessor(xAcc);
+            const getY = resolveAccessor(yAcc);
+            const xVal = getX(d);
+            const yVal = getY(d);
+            const xPos = xScale(xVal) || 0;
+            const yPos = yScale(yVal) || 0;
+            // Query Engine for targets at this location (Vertical Slice)
+            // We use a small search radius to mimic "nearest" behavior if needed,
+            // but typically we want everything at this X.
+            // The spatial index might be quadtree.
+            // For now, let's use the primary data point we just found as the target
+            // + any others the engine finds nearby.
+            // Simplest interaction: Just highlight the data point we navigated to.
+            // If we want multi-series, we should query engine.
+            // const candidates = engine.spatialIndex?.find(xPos, yPos, 10) || [];
+            // Construct target manually since we know the data point
+            const primaryTarget = {
+                type: "data-point",
+                data: d,
+                seriesId: "default", // TODO: Multi-series support
+                dataIndex: focusedIndex,
+                coordinate: { x: xPos, y: yPos },
+                distance: 0,
+            };
+            upsertInteraction(name, {
+                pointer: {
+                    x: xPos,
+                    y: yPos,
+                    containerX: xPos + state.dimensions.margin.left,
+                    containerY: yPos + state.dimensions.margin.top,
+                    isTouch: false,
+                },
+                targets: [primaryTarget], // Cast to InteractionTarget
+                target: primaryTarget,
+            });
+        }
+    };
+};

package/dist/components/Chart/sensors/KeyboardSensor/index.d.ts

@@ -0,0 +1 @@
+export * from "./KeyboardSensor";

package/dist/components/Chart/sensors/KeyboardSensor/index.js

@@ -0,0 +1 @@
+export * from "./KeyboardSensor.js";

package/dist/components/Chart/sensors/{SelectionSensor.d.ts → SelectionSensor/SelectionSensor.d.ts}

@@ -1,7 +1,7 @@
-import { Sensor } from "../types/events";
+import { Sensor } from "../../types/events";
 /**
  * Professional-grade Selection Sensor.
- * Coordinates with search logic to choose data points on click.
+ * Coordinates with Engine to choose data points on click/start.
  */
 export declare const SelectionSensor: (options?: {
     name?: string;

package/dist/components/Chart/sensors/SelectionSensor/SelectionSensor.js

@@ -0,0 +1,39 @@
+import { InputAction } from "../../engine/index.js";
+import { InteractionChannel } from "../../types/interaction.js";
+/**
+ * Professional-grade Selection Sensor.
+ * Coordinates with Engine to choose data points on click/start.
+ */
+export const SelectionSensor = (options = {}) => {
+    const { name = InteractionChannel.SELECTION } = options;
+    return ({ signal, primaryCandidate }, { getChartContext, upsertInteraction }) => {
+        // Only handle START action (roughly equivalent to mouse down)
+        if (signal.action !== InputAction.START) {
+            return;
+        }
+        if (!primaryCandidate) {
+            return;
+        }
+        const ctx = getChartContext();
+        const { chartStore } = ctx;
+        const state = chartStore.getState();
+        const selectedDatum = primaryCandidate.data;
+        const currentInteraction = state.interactions.get(name);
+        const currentSelection = (currentInteraction === null || currentInteraction === void 0 ? void 0 : currentInteraction.selection) || [];
+        // Simple toggle logic
+        // TODO: support multi-select with shift key?
+        // signal.originalEvent is the native event if we need modifiers.
+        const isAlreadySelected = currentSelection.includes(selectedDatum);
+        let nextSelection;
+        if (isAlreadySelected) {
+            nextSelection = currentSelection.filter((d) => d !== selectedDatum);
+        }
+        else {
+            nextSelection = [...currentSelection, selectedDatum];
+        }
+        upsertInteraction(name, {
+            selection: nextSelection,
+            mode: "discrete", // or "continuous"
+        });
+    };
+};

package/dist/components/Chart/sensors/SelectionSensor/index.d.ts

@@ -0,0 +1 @@
+export * from "./SelectionSensor";