@363045841yyt/klinechart-core 0.8.11-alpha.0 → 0.8.12

package/src/components/crosshairSync/__tests__/crosshairSync.test.ts

@@ -0,0 +1,261 @@
+/**
+ * Tests for `createCrosshairSync`.
+ *
+ * Coverage:
+ *   1. Single-pane register + paneCount.
+ *   2. Multi-pane register: paneCount tracks correctly.
+ *   3. Idempotent register (re-registering same id is a no-op).
+ *   4. unregister removes + drops position when it owns the source.
+ *   5. unregister of unknown id is a no-op.
+ *   6. move emits position with index + source.
+ *   7. move from unregistered pane throws KLineChartError(NOT_REGISTERED).
+ *   8. move with non-finite index throws INVALID_PARAM.
+ *   9. Index normalisation: fractional inputs round to integer.
+ *  10. Repeat move with same (index, source) is coalesced.
+ *  11. clear() resets position to null.
+ *  12. clear() when already null doesn't notify.
+ *  13. reset() empties registry + position.
+ *  14. dispose() turns everything into a no-op.
+ *  15. Loop-prevention pattern: subscribers can identify own emissions.
+ */
+
+import { describe, it, expect } from 'vitest'
+
+import { createCrosshairSync, type CrosshairPosition } from '..'
+import { isKLineChartError } from '../../../errors'
+
+function collect(s: ReturnType<typeof createCrosshairSync>): CrosshairPosition[] {
+    const out: CrosshairPosition[] = []
+    s.position.subscribe(() => {
+        const p = s.position.peek()
+        if (p !== null) out.push(p)
+    })
+    return out
+}
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+describe('register', () => {
+    it('starts with paneCount = 0 and position null', () => {
+        const s = createCrosshairSync()
+        expect(s.paneCount.peek()).toBe(0)
+        expect(s.position.peek()).toBeNull()
+    })
+
+    it('register increments paneCount', () => {
+        const s = createCrosshairSync()
+        s.register('a')
+        s.register('b')
+        s.register('c')
+        expect(s.paneCount.peek()).toBe(3)
+    })
+
+    it('re-registering same id is a no-op', () => {
+        const s = createCrosshairSync()
+        s.register('a')
+        s.register('a')
+        expect(s.paneCount.peek()).toBe(1)
+    })
+
+    it('empty paneId throws', () => {
+        const s = createCrosshairSync()
+        try {
+            s.register('')
+            expect.fail('expected throw')
+        } catch (e) {
+            expect(isKLineChartError(e, 'INVALID_PARAM')).toBe(true)
+        }
+    })
+})
+
+// ---------------------------------------------------------------------------
+// unregister
+// ---------------------------------------------------------------------------
+
+describe('unregister', () => {
+    it('removes the pane', () => {
+        const s = createCrosshairSync()
+        s.register('a')
+        s.register('b')
+        s.unregister('a')
+        expect(s.paneCount.peek()).toBe(1)
+    })
+
+    it('drops position when the source pane leaves', () => {
+        const s = createCrosshairSync()
+        s.register('a')
+        s.register('b')
+        s.move('a', 100)
+        expect(s.position.peek()).not.toBeNull()
+        s.unregister('a')
+        expect(s.position.peek()).toBeNull()
+    })
+
+    it('keeps position when a non-source pane leaves', () => {
+        const s = createCrosshairSync()
+        s.register('a')
+        s.register('b')
+        s.move('a', 100)
+        s.unregister('b')
+        expect(s.position.peek()?.index).toBe(100)
+    })
+
+    it('unregistering an unknown id is a no-op', () => {
+        const s = createCrosshairSync()
+        s.register('a')
+        expect(() => s.unregister('nope')).not.toThrow()
+        expect(s.paneCount.peek()).toBe(1)
+    })
+})
+
+// ---------------------------------------------------------------------------
+// move
+// ---------------------------------------------------------------------------
+
+describe('move', () => {
+    it('emits position with index and source', () => {
+        const s = createCrosshairSync()
+        s.register('a')
+        s.move('a', 50)
+        const p = s.position.peek()
+        expect(p?.index).toBe(50)
+        expect(p?.source).toBe('a')
+    })
+
+    it('throws NOT_REGISTERED when the producer pane is unknown', () => {
+        const s = createCrosshairSync()
+        try {
+            s.move('ghost', 50)
+            expect.fail('expected throw')
+        } catch (e) {
+            expect(isKLineChartError(e, 'NOT_REGISTERED')).toBe(true)
+        }
+    })
+
+    it('throws INVALID_PARAM on non-finite index', () => {
+        const s = createCrosshairSync()
+        s.register('a')
+        for (const bad of [Number.NaN, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY]) {
+            try {
+                s.move('a', bad)
+                expect.fail(`expected throw for ${bad}`)
+            } catch (e) {
+                expect(isKLineChartError(e, 'INVALID_PARAM')).toBe(true)
+            }
+        }
+    })
+
+    it('rounds fractional indices to integers', () => {
+        const s = createCrosshairSync()
+        s.register('a')
+        s.move('a', 50.4)
+        expect(s.position.peek()?.index).toBe(50)
+        s.move('a', 50.6)
+        expect(s.position.peek()?.index).toBe(51)
+    })
+
+    it('coalesces identical (index, source) updates', () => {
+        const s = createCrosshairSync()
+        s.register('a')
+        const events = collect(s)
+        s.move('a', 50)
+        s.move('a', 50)
+        s.move('a', 50)
+        expect(events.length).toBe(1)
+    })
+
+    it('does not coalesce when source changes even if index is same', () => {
+        const s = createCrosshairSync()
+        s.register('a')
+        s.register('b')
+        const events = collect(s)
+        s.move('a', 50)
+        s.move('b', 50)
+        expect(events.length).toBe(2)
+        expect(events[0]?.source).toBe('a')
+        expect(events[1]?.source).toBe('b')
+    })
+})
+
+// ---------------------------------------------------------------------------
+// Loop prevention pattern
+// ---------------------------------------------------------------------------
+
+describe('loop-prevention pattern', () => {
+    it('subscribers can skip their own emissions using source', () => {
+        const s = createCrosshairSync()
+        s.register('a')
+        s.register('b')
+        const aSaw: number[] = []
+        const bSaw: number[] = []
+        s.position.subscribe(() => {
+            const p = s.position.peek()
+            if (p === null || p.source === 'a') return
+            aSaw.push(p.index)
+        })
+        s.position.subscribe(() => {
+            const p = s.position.peek()
+            if (p === null || p.source === 'b') return
+            bSaw.push(p.index)
+        })
+        s.move('a', 10)
+        s.move('b', 20)
+        expect(aSaw).toEqual([20]) // a skips its own emission
+        expect(bSaw).toEqual([10]) // b skips its own emission
+    })
+})
+
+// ---------------------------------------------------------------------------
+// clear / reset
+// ---------------------------------------------------------------------------
+
+describe('clear', () => {
+    it('sets position to null', () => {
+        const s = createCrosshairSync()
+        s.register('a')
+        s.move('a', 5)
+        s.clear()
+        expect(s.position.peek()).toBeNull()
+    })
+
+    it('clear when already null does not notify', () => {
+        const s = createCrosshairSync()
+        let notifies = 0
+        s.position.subscribe(() => {
+            notifies++
+        })
+        s.clear()
+        s.clear()
+        expect(notifies).toBe(0)
+    })
+})
+
+describe('reset', () => {
+    it('empties registry and position', () => {
+        const s = createCrosshairSync()
+        s.register('a')
+        s.register('b')
+        s.move('a', 5)
+        s.reset()
+        expect(s.paneCount.peek()).toBe(0)
+        expect(s.position.peek()).toBeNull()
+    })
+})
+
+// ---------------------------------------------------------------------------
+// dispose
+// ---------------------------------------------------------------------------
+
+describe('dispose', () => {
+    it('makes register / move / unregister / clear no-ops', () => {
+        const s = createCrosshairSync()
+        s.register('a')
+        s.dispose()
+        expect(() => s.register('b')).not.toThrow()
+        expect(() => s.move('a', 5)).not.toThrow()
+        expect(() => s.clear()).not.toThrow()
+        expect(s.position.peek()).toBeNull()
+    })
+})

package/src/components/crosshairSync/createCrosshairSync.ts

@@ -0,0 +1,187 @@
+/**
+ * Crosshair sync — broadcasts crosshair position across multiple
+ * chart panes so a hover in one pane lights up the same time index
+ * in every other pane.
+ *
+ * Why this is the controller, not just a callback:
+ *
+ *   - Multi-pane layouts (price + volume + 1+ indicator panes) are
+ *     standard for finance charts. TradingView's multi-pane crosshair
+ *     is one of its iconic UX features.
+ *   - Each pane has its own scale/transform. The universal coordinate
+ *     they share is the **time index** — the integer-valued position
+ *     within the bar array. Sync on index, not pixel; the rendering
+ *     pane converts back to its own x coordinate.
+ *   - Loop prevention: a pane that consumed a sync event must not
+ *     re-emit it. We track the source identifier so the pane that
+ *     drove the update doesn't recurse.
+ *
+ * Pure data, signal-based, framework-agnostic — same shape as the
+ * rest of `@klinechart-quant/core`.
+ *
+ *   const sync = createCrosshairSync()
+ *   sync.register('price')
+ *   sync.register('volume')
+ *   sync.register('rsi')
+ *
+ *   priceContainer.addEventListener('pointermove', e => {
+ *     const idx = timeScale.xToBarIndex(e.offsetX)
+ *     sync.move('price', idx)
+ *   })
+ *
+ *   sync.position.subscribe(() => {
+ *     const p = sync.position.peek()
+ *     if (p === null) hideCrosshair()
+ *     else if (p.source !== 'volume') drawCrosshairInVolume(p.index)
+ *   })
+ */
+
+import { createSignal, type Signal } from '../../reactivity'
+import { KLineChartError } from '../../errors'
+
+// ---------------------------------------------------------------------------
+// Public shape
+// ---------------------------------------------------------------------------
+
+/**
+ * Current crosshair position broadcast across registered panes.
+ * `null` means no pane has the crosshair active (host left every chart
+ * or `clear()` was called).
+ */
+export interface CrosshairPosition {
+    /** Integer index into the canonical bar array. */
+    readonly index: number
+    /**
+     * Pane id of the pane that produced this update. Consumers MUST
+     * compare to skip handling their own emissions (loop prevention).
+     */
+    readonly source: string
+}
+
+export interface CrosshairSync {
+    /**
+     * Current position. `null` when no crosshair is active.
+     *
+     * NOTE: this is a `Signal<...>` — reading `position()` inside an
+     * `effect` tracks the subscription; reading `position.peek()` does
+     * not. Manual `subscribe` returns an unsubscribe function.
+     */
+    readonly position: Signal<CrosshairPosition | null>
+    /**
+     * Number of currently registered panes. Helpful for the
+     * "single-pane no-op" branch in adapters.
+     */
+    readonly paneCount: Signal<number>
+
+    /**
+     * Register a pane that participates in the sync. Idempotent —
+     * re-registering the same id is a no-op.
+     */
+    register(paneId: string): void
+    /**
+     * Unregister a pane. If the unregistered pane is the source of the
+     * current position, the position is cleared (the producer is gone).
+     */
+    unregister(paneId: string): void
+    /**
+     * Producer-side update — pane `paneId` is reporting that its
+     * crosshair is on bar `index`. Subscribers receive the new
+     * position; `paneId` is recorded as `source` for loop prevention.
+     *
+     * Calling `move` from a pane that has not been registered throws
+     * `KLineChartError('NOT_REGISTERED')` — the wiring contract is
+     * easy to mess up and silent ignores would mask bugs.
+     */
+    move(paneId: string, index: number): void
+    /** Clears the position. All panes see `position = null`. */
+    clear(): void
+    /** Reset to empty registry + null position. */
+    reset(): void
+    dispose(): void
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createCrosshairSync(): CrosshairSync {
+    const position = createSignal<CrosshairPosition | null>(null)
+    const paneCount = createSignal<number>(0)
+    const panes = new Set<string>()
+    let disposed = false
+
+    function publishPaneCount(): void {
+        paneCount.set(panes.size)
+    }
+
+    function register(paneId: string): void {
+        if (disposed) return
+        if (paneId === '' || typeof paneId !== 'string') {
+            throw new KLineChartError(
+                'INVALID_PARAM',
+                `CrosshairSync.register: paneId must be a non-empty string`,
+            )
+        }
+        if (panes.has(paneId)) return
+        panes.add(paneId)
+        publishPaneCount()
+    }
+
+    function unregister(paneId: string): void {
+        if (disposed) return
+        if (!panes.has(paneId)) return
+        panes.delete(paneId)
+        publishPaneCount()
+        const cur = position.peek()
+        if (cur !== null && cur.source === paneId) {
+            position.set(null)
+        }
+    }
+
+    function move(paneId: string, index: number): void {
+        if (disposed) return
+        if (!panes.has(paneId)) {
+            throw new KLineChartError(
+                'NOT_REGISTERED',
+                `CrosshairSync.move: pane ${JSON.stringify(paneId)} is not registered — call register(${JSON.stringify(paneId)}) before move()`,
+            )
+        }
+        if (!Number.isFinite(index)) {
+            throw new KLineChartError(
+                'INVALID_PARAM',
+                `CrosshairSync.move: index must be finite, got ${index}`,
+            )
+        }
+        // Normalise to integer. Sub-bar precision lives in the per-pane
+        // pixel layer, not in the shared index broadcast.
+        const idx = Math.round(index)
+        const cur = position.peek()
+        // Coalesce identical updates so subscribers don't fire on no-ops.
+        if (cur !== null && cur.index === idx && cur.source === paneId) return
+        position.set({ index: idx, source: paneId })
+    }
+
+    function clear(): void {
+        if (disposed) return
+        if (position.peek() === null) return
+        position.set(null)
+    }
+
+    function reset(): void {
+        if (disposed) return
+        panes.clear()
+        publishPaneCount()
+        if (position.peek() !== null) position.set(null)
+    }
+
+    function dispose(): void {
+        if (disposed) return
+        disposed = true
+        panes.clear()
+        // No notify on dispose — subscribers should listen for their own
+        // host lifecycle. Setting paneCount/position now would notify
+        // dead subscribers in some host frameworks.
+    }
+
+    return { position, paneCount, register, unregister, move, clear, reset, dispose }
+}

package/src/components/crosshairSync/index.ts

@@ -0,0 +1,5 @@
+export {
+    createCrosshairSync,
+    type CrosshairSync,
+    type CrosshairPosition,
+} from './createCrosshairSync'

package/src/components/footprint/__tests__/aggressor.test.ts

@@ -0,0 +1,127 @@
+/**
+ * Aggressor classifier tests — explicit flag, tick rule, Lee-Ready.
+ *
+ * Each classifier is tested in isolation; the controller-level fallback chain
+ * is tested in controller.test.ts.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+    classifyExplicit,
+    classifyTickRule,
+    classifyLeeReady,
+    type TickRuleState,
+    type LeeReadyState,
+} from '../aggressor'
+
+const trade = (price: number, size = 1, timestamp = 0): { timestamp: number; price: number; size: number } => ({
+    timestamp,
+    price,
+    size,
+})
+
+describe('classifyExplicit', () => {
+    it('isBuyerMaker=true means seller was the aggressor → sell', () => {
+        const r = classifyExplicit({ ...trade(100), isBuyerMaker: true })
+        expect(r).toEqual({ side: 'sell', inferred: false })
+    })
+
+    it('isBuyerMaker=false means buyer was the aggressor → buy', () => {
+        const r = classifyExplicit({ ...trade(100), isBuyerMaker: false })
+        expect(r).toEqual({ side: 'buy', inferred: false })
+    })
+
+    it('isBuyerMaker undefined → null (signals "no data; fall back")', () => {
+        expect(classifyExplicit(trade(100))).toBeNull()
+    })
+})
+
+describe('classifyTickRule', () => {
+    it('first trade with prevPrice=null → unknown', () => {
+        const state: TickRuleState = { prevPrice: null, prevSide: null }
+        const r = classifyTickRule(state, trade(100))
+        expect(r.side).toBe('unknown')
+        expect(r.inferred).toBe(true)
+    })
+
+    it('rising price → buy (uptick)', () => {
+        const state: TickRuleState = { prevPrice: 99, prevSide: null }
+        expect(classifyTickRule(state, trade(100)).side).toBe('buy')
+    })
+
+    it('falling price → sell (downtick)', () => {
+        const state: TickRuleState = { prevPrice: 101, prevSide: null }
+        expect(classifyTickRule(state, trade(100)).side).toBe('sell')
+    })
+
+    it('equal price with prevSide=buy → buy (zero-tick repeats)', () => {
+        const state: TickRuleState = { prevPrice: 100, prevSide: 'buy' }
+        expect(classifyTickRule(state, trade(100)).side).toBe('buy')
+    })
+
+    it('equal price with prevSide=null → unknown', () => {
+        const state: TickRuleState = { prevPrice: 100, prevSide: null }
+        expect(classifyTickRule(state, trade(100)).side).toBe('unknown')
+    })
+
+    it('mutates state.prevPrice in place', () => {
+        const state: TickRuleState = { prevPrice: 99, prevSide: null }
+        classifyTickRule(state, trade(100))
+        expect(state.prevPrice).toBe(100)
+        expect(state.prevSide).toBe('buy')
+    })
+
+    it('does NOT overwrite prevSide when result is unknown (no poisoning)', () => {
+        // Stream: trade1 establishes prevSide=buy, trade2 at same price with
+        // prev null → wouldn't happen, but documented intent is to preserve
+        // prevSide across an unknown classification.
+        const state: TickRuleState = { prevPrice: 99, prevSide: null }
+        classifyTickRule(state, trade(100)) // prevSide → 'buy'
+        expect(state.prevSide).toBe('buy')
+        classifyTickRule(state, trade(100)) // zero-tick, side stays 'buy'
+        expect(state.prevSide).toBe('buy')
+    })
+})
+
+describe('classifyLeeReady', () => {
+    it('price above mid → buy', () => {
+        const state: LeeReadyState = { prevPrice: null, prevSide: null }
+        // mid = (100+101)/2 = 100.5; price 100.6 is above → buy
+        expect(classifyLeeReady(state, trade(100.6), 100, 101).side).toBe('buy')
+    })
+
+    it('price below mid → sell', () => {
+        const state: LeeReadyState = { prevPrice: null, prevSide: null }
+        expect(classifyLeeReady(state, trade(100.3), 100, 101).side).toBe('sell')
+    })
+
+    it('price at mid → falls back to tick rule', () => {
+        const state: LeeReadyState = { prevPrice: 99, prevSide: null }
+        expect(classifyLeeReady(state, trade(100.5), 100, 101).side).toBe('buy')
+        // 100.5 == mid; price > prevPrice (99) → buy via tick rule
+    })
+
+    it('missing bid/ask → falls back to tick rule', () => {
+        // NaN bid → quotes unusable → tick-rule path.
+        // prevPrice=101, trade.price=100 → downtick → sell.
+        const state1: LeeReadyState = { prevPrice: 101, prevSide: null }
+        expect(classifyLeeReady(state1, trade(100), NaN, 101).side).toBe('sell')
+
+        // Infinity ask → also quotes unusable → tick-rule path.
+        // prevPrice=99, trade.price=100 → uptick → buy.
+        const state2: LeeReadyState = { prevPrice: 99, prevSide: null }
+        expect(classifyLeeReady(state2, trade(100), 100, Infinity).side).toBe('buy')
+    })
+
+    it('quote test updates state.prevPrice + prevSide', () => {
+        const state: LeeReadyState = { prevPrice: null, prevSide: null }
+        classifyLeeReady(state, trade(100.6), 100, 101)
+        expect(state.prevPrice).toBe(100.6)
+        expect(state.prevSide).toBe('buy')
+    })
+
+    it('marks all results as inferred=true', () => {
+        const state: LeeReadyState = { prevPrice: 99, prevSide: null }
+        expect(classifyLeeReady(state, trade(100), 99.5, 100.5).inferred).toBe(true)
+    })
+})