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

package/src/scale/__tests__/originShift.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect } from 'vitest'
+import { createOriginShiftPolicy } from '../originShift'
+
+describe('createOriginShiftPolicy', () => {
+    it('starts with ref equal to initialRef', () => {
+        const p = createOriginShiftPolicy(67000)
+        expect(p.ref).toBe(67000)
+    })
+
+    it('shift(value) returns value - ref', () => {
+        const p = createOriginShiftPolicy(67000)
+        expect(p.shift(67000.5)).toBeCloseTo(0.5, 10)
+        expect(p.shift(66999.25)).toBeCloseTo(-0.75, 10)
+    })
+
+    it('below threshold → no rebase (uses required 0.005 normalized drift, threshold default 0.01)', () => {
+        // Visible range 100, mid drifts to 100.5 → drift = 0.5, normalized 0.005 (= 0.5 / 100).
+        // Default threshold 0.01 → 0.005 is BELOW → no rebase.
+        const p = createOriginShiftPolicy(100)
+        const changed = p.maybeRebaseline(100.5, 100)
+        expect(changed).toBe(false)
+        expect(p.ref).toBe(100)
+    })
+
+    it('above threshold → rebase to new mid (uses required 0.02 normalized drift)', () => {
+        // Visible range 100, mid drifts to 102 → drift 2, normalized 0.02 (= 2 / 100).
+        // 0.02 > 0.01 → REBASE.
+        const p = createOriginShiftPolicy(100)
+        const changed = p.maybeRebaseline(102, 100)
+        expect(changed).toBe(true)
+        expect(p.ref).toBe(102)
+    })
+
+    it('threshold === 0 → always rebases when there is any drift', () => {
+        const p = createOriginShiftPolicy(50, 0)
+        // Any drift at all triggers the rebase.
+        expect(p.maybeRebaseline(50.0001, 100)).toBe(true)
+        expect(p.ref).toBe(50.0001)
+        // ...but a zero-drift call still doesn't rebase (division yields 0, which
+        // is not > 0).
+        expect(p.maybeRebaseline(50.0001, 100)).toBe(false)
+    })
+
+    it('threshold === 1 → never rebases for any in-range drift', () => {
+        const p = createOriginShiftPolicy(50, 1)
+        // Even a near-full-range drift can't exceed 1.
+        expect(p.maybeRebaseline(149, 100)).toBe(false)
+        expect(p.ref).toBe(50)
+    })
+
+    it('multiple maybeRebaseline calls produce monotonic ref tracking the drift', () => {
+        const p = createOriginShiftPolicy(0, 0.01)
+        const history: number[] = []
+
+        // Walk the mid forward in 0.02 * range steps; each step crosses the threshold.
+        let mid = 0
+        const range = 100
+        for (let i = 0; i < 10; i++) {
+            mid += 0.02 * range // +2 per step → 0.02 normalized → above threshold
+            if (p.maybeRebaseline(mid, range)) history.push(p.ref)
+        }
+
+        expect(history.length).toBe(10)
+        // All recorded refs must be strictly increasing.
+        for (let i = 1; i < history.length; i++) {
+            expect(history[i]).toBeGreaterThan(history[i - 1])
+        }
+    })
+
+    it('degenerate range (currentRange <= 0) refuses to rebase', () => {
+        const p = createOriginShiftPolicy(50)
+        expect(p.maybeRebaseline(60, 0)).toBe(false)
+        expect(p.maybeRebaseline(60, -10)).toBe(false)
+        expect(p.ref).toBe(50)
+    })
+
+    it('non-finite inputs do not corrupt ref', () => {
+        const p = createOriginShiftPolicy(50)
+        expect(p.maybeRebaseline(Number.NaN, 100)).toBe(false)
+        expect(p.maybeRebaseline(60, Number.POSITIVE_INFINITY)).toBe(false)
+        expect(p.ref).toBe(50)
+    })
+
+    it('rejects non-finite initialRef and negative threshold', () => {
+        expect(() => createOriginShiftPolicy(Number.NaN)).toThrow(/finite/)
+        expect(() => createOriginShiftPolicy(0, -0.1)).toThrow(/threshold/)
+    })
+
+    it('exactly at threshold → does NOT rebase (strict `>`)', () => {
+        // Important contract: the comparison is `>`, not `>=`. A drift of
+        // exactly 1% of range should sit on the fence and not trigger.
+        const p = createOriginShiftPolicy(100, 0.01)
+        const changed = p.maybeRebaseline(101, 100) // normalized 0.01 === threshold
+        expect(changed).toBe(false)
+        expect(p.ref).toBe(100)
+    })
+})

package/src/scale/__tests__/priceScale.test.ts

@@ -0,0 +1,219 @@
+import { describe, it, expect, vi } from 'vitest'
+import { createPriceScale } from '../createPriceScale'
+
+describe('createPriceScale — linear mode', () => {
+    it('forward & inverse linear round-trip', () => {
+        const s = createPriceScale({
+            initialMode: 'linear',
+            initialVisibleMin: 100,
+            initialVisibleMax: 200,
+            initialHeight: 400,
+        })
+        for (const p of [100, 120.5, 150, 180.25, 200]) {
+            expect(s.yToPrice(s.priceToY(p))).toBeCloseTo(p, 8)
+        }
+        for (const y of [0, 100, 200, 300, 400]) {
+            expect(s.priceToY(s.yToPrice(y))).toBeCloseTo(y, 8)
+        }
+    })
+
+    it('linear: max maps to y=0 and min maps to y=height (Y grows downward)', () => {
+        const s = createPriceScale({
+            initialMode: 'linear',
+            initialVisibleMin: 100,
+            initialVisibleMax: 200,
+            initialHeight: 400,
+        })
+        expect(s.priceToY(200)).toBeCloseTo(0, 10)
+        expect(s.priceToY(100)).toBeCloseTo(400, 10)
+        expect(s.priceToY(150)).toBeCloseTo(200, 10)
+    })
+
+    it('setHeight changes the mapping proportionally', () => {
+        const s = createPriceScale({
+            initialMode: 'linear',
+            initialVisibleMin: 0,
+            initialVisibleMax: 100,
+            initialHeight: 400,
+        })
+        expect(s.priceToY(50)).toBeCloseTo(200, 10)
+        s.setHeight(800)
+        expect(s.priceToY(50)).toBeCloseTo(400, 10)
+    })
+
+    it('degenerate range (min === max) is clamped to center, not NaN', () => {
+        const s = createPriceScale({
+            initialMode: 'linear',
+            initialVisibleMin: 100,
+            initialVisibleMax: 100,
+            initialHeight: 400,
+        })
+        // Documented behaviour: anything maps to the geometric middle of the canvas.
+        expect(s.priceToY(100)).toBe(200)
+        expect(s.priceToY(50)).toBe(200) // still pinned to middle
+        expect(s.priceToY(150)).toBe(200)
+    })
+})
+
+describe('createPriceScale — log mode', () => {
+    it('forward & inverse log round-trip', () => {
+        const s = createPriceScale({
+            initialMode: 'log',
+            initialVisibleMin: 1,
+            initialVisibleMax: 1000,
+            initialHeight: 600,
+        })
+        for (const p of [1, 10, 100, 333.33, 1000]) {
+            expect(s.yToPrice(s.priceToY(p))).toBeCloseTo(p, 6)
+        }
+    })
+
+    it('log: equal log-distances produce equal pixel distances', () => {
+        // 1 → 10 → 100 → 1000 are each one decade apart.
+        // In log mode they must be at equal Y intervals.
+        const s = createPriceScale({
+            initialMode: 'log',
+            initialVisibleMin: 1,
+            initialVisibleMax: 1000,
+            initialHeight: 600,
+        })
+        const y1 = s.priceToY(1)
+        const y10 = s.priceToY(10)
+        const y100 = s.priceToY(100)
+        const y1000 = s.priceToY(1000)
+        const d1 = y1 - y10
+        const d2 = y10 - y100
+        const d3 = y100 - y1000
+        expect(d1).toBeCloseTo(d2, 8)
+        expect(d2).toBeCloseTo(d3, 8)
+    })
+
+    it('setMode("log") rejects when visibleMin <= 0', () => {
+        const s = createPriceScale({
+            initialMode: 'linear',
+            initialVisibleMin: 0, // not OK for log
+            initialVisibleMax: 100,
+        })
+        expect(() => s.setMode('log')).toThrow(/visibleMin > 0/)
+    })
+
+    it('constructor rejects log + non-positive min', () => {
+        expect(() =>
+            createPriceScale({ initialMode: 'log', initialVisibleMin: 0, initialVisibleMax: 100 }),
+        ).toThrow(/log/)
+        expect(() =>
+            createPriceScale({ initialMode: 'log', initialVisibleMin: -5, initialVisibleMax: 100 }),
+        ).toThrow(/log/)
+    })
+
+    it('setVisibleRange in log mode rejects non-positive min', () => {
+        const s = createPriceScale({
+            initialMode: 'log',
+            initialVisibleMin: 1,
+            initialVisibleMax: 100,
+        })
+        expect(() => s.setVisibleRange(0, 100)).toThrow(/log/)
+        expect(() => s.setVisibleRange(-1, 100)).toThrow(/log/)
+    })
+})
+
+describe('createPriceScale — origin shift integration', () => {
+    it('toShiftedFp32 returns p - originShiftRef', () => {
+        const s = createPriceScale({
+            initialMode: 'linear',
+            initialVisibleMin: 66950,
+            initialVisibleMax: 67050,
+            initialHeight: 400,
+        })
+        // Origin starts at midpoint = 67000.
+        expect(s.originShiftRef.peek()).toBe(67000)
+        expect(s.toShiftedFp32(67000.5)).toBeCloseTo(0.5, 10)
+        expect(s.toShiftedFp32(66999.5)).toBeCloseTo(-0.5, 10)
+    })
+
+    it('setVisibleRange triggers maybeRebaseline when drift > threshold', () => {
+        const s = createPriceScale({
+            initialMode: 'linear',
+            initialVisibleMin: 100,
+            initialVisibleMax: 200,
+            initialHeight: 400,
+            originShiftThreshold: 0.01, // 1%
+        })
+        const refBefore = s.originShiftRef.peek() // = 150
+
+        // Shift mid by 0.005 of range — BELOW threshold, no rebase.
+        s.setVisibleRange(100.5, 200.5) // new mid 150.5, drift 0.5, range 100, normalized 0.005
+        expect(s.originShiftRef.peek()).toBe(refBefore)
+
+        // Shift mid by 0.02 of range — ABOVE threshold, rebase.
+        s.setVisibleRange(102, 202) // new mid 152, drift from old ref 150 = 2, normalized 0.02
+        expect(s.originShiftRef.peek()).toBe(152)
+    })
+
+    it('signal subscriptions fire on visible-range and mode changes', () => {
+        const s = createPriceScale({ initialVisibleMin: 1, initialVisibleMax: 100 })
+        const onMin = vi.fn()
+        const onMax = vi.fn()
+        const onMode = vi.fn()
+        s.visibleMin.subscribe(onMin)
+        s.visibleMax.subscribe(onMax)
+        s.mode.subscribe(onMode)
+
+        s.setVisibleRange(2, 200)
+        expect(onMin).toHaveBeenCalledTimes(1)
+        expect(onMax).toHaveBeenCalledTimes(1)
+
+        s.setMode('log')
+        expect(onMode).toHaveBeenCalledTimes(1)
+    })
+
+    it('originShiftRef signal updates when a rebase fires', () => {
+        const s = createPriceScale({
+            initialVisibleMin: 100,
+            initialVisibleMax: 200,
+            originShiftThreshold: 0.01,
+        })
+        const onRef = vi.fn()
+        s.originShiftRef.subscribe(onRef)
+
+        s.setVisibleRange(100.5, 200.5) // below threshold
+        expect(onRef).not.toHaveBeenCalled()
+
+        s.setVisibleRange(105, 205) // above threshold
+        expect(onRef).toHaveBeenCalledTimes(1)
+    })
+})
+
+describe('createPriceScale — validation & lifecycle', () => {
+    it('setVisibleRange rejects non-finite or inverted bounds', () => {
+        const s = createPriceScale()
+        expect(() => s.setVisibleRange(Number.NaN, 1)).toThrow(/finite/)
+        expect(() => s.setVisibleRange(100, 50)).toThrow(/max/)
+    })
+
+    it('setHeight rejects non-positive values', () => {
+        const s = createPriceScale()
+        expect(() => s.setHeight(0)).toThrow(/> 0/)
+        expect(() => s.setHeight(-1)).toThrow(/> 0/)
+    })
+
+    it('dispose silences subsequent writes (silent no-op, reads still work)', () => {
+        // API audit BLOCKER-004: harmonized to silent-no-op (matches the
+        // convention used by every other @klinechart-quant/core controller).
+        const s = createPriceScale({ initialVisibleMin: 0, initialVisibleMax: 100, initialHeight: 400 })
+        const minBefore = s.visibleMin()
+        const heightBefore = s.height()
+        const modeBefore = s.mode()
+        s.dispose()
+        // Mutators return undefined silently — no throw.
+        s.setVisibleRange(10, 110)
+        s.setHeight(200)
+        s.setMode('log')
+        // State frozen at pre-dispose values.
+        expect(s.visibleMin()).toBe(minBefore)
+        expect(s.height()).toBe(heightBefore)
+        expect(s.mode()).toBe(modeBefore)
+        // Pure math still returns sensible numbers.
+        expect(s.priceToY(50)).toBeCloseTo(200, 10)
+    })
+})

package/src/scale/__tests__/timeScale.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect, vi } from 'vitest'
+import { createTimeScale } from '../createTimeScale'
+
+describe('createTimeScale', () => {
+    it('barIndexToX and xToBarIndex are exact inverses', () => {
+        const s = createTimeScale({
+            initialFirstVisibleIndex: 12.5,
+            initialBarWidth: 9,
+            initialLeftPadding: 60,
+        })
+        for (const i of [0, 1, 17, 99, -3, 12.5, 100.25]) {
+            expect(s.xToBarIndex(s.barIndexToX(i))).toBeCloseTo(i, 10)
+        }
+        for (const x of [0, 60, 123.4, 1000, -50]) {
+            expect(s.barIndexToX(s.xToBarIndex(x))).toBeCloseTo(x, 10)
+        }
+    })
+
+    it('setBarWidth re-derives the X mapping correctly', () => {
+        const s = createTimeScale({
+            initialFirstVisibleIndex: 0,
+            initialBarWidth: 10,
+            initialLeftPadding: 0,
+        })
+        expect(s.barIndexToX(5)).toBe(50)
+        s.setBarWidth(20)
+        expect(s.barIndexToX(5)).toBe(100)
+    })
+
+    it('fractional firstVisibleIndex works in both directions', () => {
+        const s = createTimeScale({
+            initialFirstVisibleIndex: 10.25,
+            initialBarWidth: 8,
+            initialLeftPadding: 60,
+        })
+        // bar 11 should be at (11 - 10.25) * 8 + 60 = 0.75 * 8 + 60 = 66
+        expect(s.barIndexToX(11)).toBeCloseTo(66, 10)
+        // and the inverse round-trips
+        expect(s.xToBarIndex(66)).toBeCloseTo(11, 10)
+    })
+
+    it('with calendar present: timeToBarIndex returns the right index for known timestamps', () => {
+        const s = createTimeScale()
+        const barTimestamps = [1_700_000_000_000, 1_700_000_060_000, 1_700_000_120_000, 1_700_000_180_000]
+        s.setCalendar({ barTimestamps })
+
+        expect(s.timeToBarIndex(barTimestamps[0])).toBe(0)
+        expect(s.timeToBarIndex(barTimestamps[2])).toBe(2)
+        expect(s.timeToBarIndex(barTimestamps[3])).toBe(3)
+        // Midway between bars 1 and 2:
+        const mid = (barTimestamps[1] + barTimestamps[2]) / 2
+        expect(s.timeToBarIndex(mid)).toBeCloseTo(1.5, 10)
+    })
+
+    it('barIndexToTime linearly interpolates for fractional indices', () => {
+        const s = createTimeScale()
+        const barTimestamps = [1_000, 2_000, 4_000]
+        s.setCalendar({ barTimestamps })
+
+        expect(s.barIndexToTime(0)).toBe(1_000)
+        expect(s.barIndexToTime(2)).toBe(4_000)
+        // bar 1.5 → halfway between 2000 and 4000 → 3000
+        expect(s.barIndexToTime(1.5)).toBe(3_000)
+    })
+
+    it('without calendar: timeToBarIndex and barIndexToTime return null', () => {
+        const s = createTimeScale()
+        expect(s.timeToBarIndex(1_700_000_000_000)).toBeNull()
+        expect(s.barIndexToTime(0)).toBeNull()
+    })
+
+    it('calendar: out-of-range queries return null (no extrapolation)', () => {
+        const s = createTimeScale()
+        s.setCalendar({ barTimestamps: [100, 200, 300] })
+        expect(s.timeToBarIndex(50)).toBeNull()
+        expect(s.timeToBarIndex(400)).toBeNull()
+        expect(s.barIndexToTime(-1)).toBeNull()
+        expect(s.barIndexToTime(3.5)).toBeNull()
+    })
+
+    it('signals fire on setters and dispose silences writes', () => {
+        const s = createTimeScale({ initialFirstVisibleIndex: 0, initialBarWidth: 10, initialLeftPadding: 0 })
+        const onFvi = vi.fn()
+        const onBw = vi.fn()
+        const onLp = vi.fn()
+        s.firstVisibleIndex.subscribe(onFvi)
+        s.barWidth.subscribe(onBw)
+        s.leftPadding.subscribe(onLp)
+
+        s.setFirstVisibleIndex(5)
+        s.setBarWidth(12)
+        s.setLeftPadding(30)
+        expect(onFvi).toHaveBeenCalledTimes(1)
+        expect(onBw).toHaveBeenCalledTimes(1)
+        expect(onLp).toHaveBeenCalledTimes(1)
+
+        // dispose: subsequent writes silently no-op (API audit BLOCKER-004
+        // harmonization — every controller in core now silences post-dispose).
+        s.dispose()
+        s.setFirstVisibleIndex(0)
+        s.setBarWidth(8)
+        // State frozen at pre-dispose values.
+        expect(s.firstVisibleIndex()).toBe(5)
+        expect(s.barWidth()).toBe(12)
+        // Math still works after dispose — it's pure peek().
+        // After the writes above: firstVisibleIndex=5, barWidth=12, leftPadding=30
+        // → barIndexToX(0) = (0 - 5) * 12 + 30 = -30
+        expect(s.barIndexToX(0)).toBe(-30)
+    })
+
+    it('rejects non-positive barWidth in both constructor and setter', () => {
+        expect(() => createTimeScale({ initialBarWidth: 0 })).toThrow(/BarWidth/)
+        expect(() => createTimeScale({ initialBarWidth: -3 })).toThrow(/BarWidth/)
+
+        const s = createTimeScale()
+        expect(() => s.setBarWidth(0)).toThrow(/> 0/)
+        expect(() => s.setBarWidth(-1)).toThrow(/> 0/)
+    })
+})

package/src/scale/anchoredZoom.ts

@@ -0,0 +1,104 @@
+/**
+ * Anchored zoom — ROADMAP §1.3.
+ *
+ * Why this exists in its own file: the "data point under the mouse stays under
+ * the mouse" guarantee is the single most-felt detail of chart UX. Getting it
+ * mathematically right (so the screen-pixel offset survives sequential zooms
+ * within sub-pixel error) is the only path to a feel that matches TradingView.
+ *
+ * Forward equation, before zoom:
+ *
+ *     mouseX = (i_anchor - firstVisibleIndex) * barWidth + leftPadding
+ *
+ * Solve for `i_anchor` first (this is the bar index the user is pointing at):
+ *
+ *     i_anchor = (mouseX - leftPadding) / barWidth + firstVisibleIndex
+ *
+ * Then pick the new bar width and solve the same equation for the new first
+ * visible index so that `mouseX` still maps to `i_anchor`:
+ *
+ *     barWidth'         = clamp(barWidth * zoomFactor, minBarWidth, maxBarWidth)
+ *     firstVisibleIndex' = i_anchor - (mouseX - leftPadding) / barWidth'
+ *
+ * Two non-obvious cases worth flagging:
+ *
+ *  1. **zoomFactor === 1** is a true no-op; we short-circuit so floating-point
+ *     round-trips don't sneak a sub-ULP drift into the state on every mouse-move.
+ *
+ *  2. **barWidth' got clamped** (user keeps wheeling at the min/max). Once the
+ *     clamp engages we re-derive `firstVisibleIndex` from the clamped width.
+ *     The anchor is preserved at the clamped width, which means the visible
+ *     anchor point will *drift in screen X by the same amount the wheel tried
+ *     to push the bar width past the clamp*. This is the expected behavior —
+ *     it's how the user feels "the chart can't zoom any further" rather than
+ *     watching the wheel become a silent dead-zone.
+ */
+
+export interface AnchoredZoomOptions {
+    /** Screen X (logical px) where the wheel event fired. */
+    mouseX: number
+    /** Logical px on the left edge before bar 0. */
+    leftPadding: number
+    /** Current `firstVisibleIndex` (fractional). */
+    firstVisibleIndex: number
+    /** Current `barWidth` in logical px. */
+    barWidth: number
+    /** > 1 zoom in (wheel up), < 1 zoom out, === 1 no-op. */
+    zoomFactor: number
+    /** Lower clamp for the resulting bar width. Default 0.5 logical px. */
+    minBarWidth?: number
+    /** Upper clamp for the resulting bar width. Default 200 logical px. */
+    maxBarWidth?: number
+}
+
+export interface AnchoredZoomResult {
+    firstVisibleIndex: number
+    barWidth: number
+}
+
+const DEFAULT_MIN_BAR_WIDTH = 0.5
+const DEFAULT_MAX_BAR_WIDTH = 200
+
+/**
+ * @internal — building block used by `createTimeScale / interaction handlers`. Reachable today
+ *   via the top-level `@klinechart-quant/core` barrel but **NOT
+ *   part of the supported public API**. typedoc / api-extractor
+ *   hide it from generated docs. Prefer the controller factory
+ *   for stable user code. Closes API audit BLOCKER-002.
+ */
+export function computeAnchoredZoom(opts: AnchoredZoomOptions): AnchoredZoomResult {
+    const {
+        mouseX,
+        leftPadding,
+        firstVisibleIndex,
+        barWidth,
+        zoomFactor,
+        minBarWidth = DEFAULT_MIN_BAR_WIDTH,
+        maxBarWidth = DEFAULT_MAX_BAR_WIDTH,
+    } = opts
+
+    // No-op short-circuit — avoid round-trip rounding when not zooming.
+    if (zoomFactor === 1) {
+        return { firstVisibleIndex, barWidth }
+    }
+
+    // Defensive: a non-positive or non-finite current barWidth would blow up the
+    // inverse formula. The TimeScale itself never lets barWidth reach 0, but we
+    // belt-and-brace it here so the function is total.
+    if (!Number.isFinite(barWidth) || barWidth <= 0) {
+        return { firstVisibleIndex, barWidth }
+    }
+
+    const dx = mouseX - leftPadding
+    const iAnchor = dx / barWidth + firstVisibleIndex
+
+    const rawNewBarWidth = barWidth * zoomFactor
+    const newBarWidth = Math.min(Math.max(rawNewBarWidth, minBarWidth), maxBarWidth)
+
+    const newFirstVisibleIndex = iAnchor - dx / newBarWidth
+
+    return {
+        firstVisibleIndex: newFirstVisibleIndex,
+        barWidth: newBarWidth,
+    }
+}