@matchstick-trading/primitives 0.0.10

package/dist/core/chart-gesture.js

@@ -0,0 +1,161 @@
+/**
+ * The chart's pointer and wheel gestures as plain data in, plain data out: press and drag to pan, a drag on the price
+ * labels, the wheel, a two-finger pinch and the double tap that gives the price back to the bars. The host reads
+ * coordinates off its DOM events, passes them in with the frame, viewport and bar count of the moment, and applies the
+ * change the result names. Nothing here touches a DOM, so the rules run and test without one.
+ */
+import { panViewport, zoomPriceRange, zoomViewport } from './chart-scale.js';
+export const INITIAL_CHART_GESTURE = { touches: [], drag: null, pinch: null, lastTap: null };
+const same = (state) => ({ state });
+const inGutter = (frame, point) => point.x >= frame.plotWidth && point.y >= 0 && point.y < frame.plotHeight;
+const heldRange = (frame) => [frame.priceMin, frame.priceMax];
+/** Whether a one-pointer drag (a pan or a price-label drag) is in progress. A two-finger pinch is separate: read `state.pinch`. The Plot keeps the hover price while a drag runs, as before the reducer moved to core. */
+export function isChartGestureActive(state) {
+    return state.drag !== null;
+}
+export function reduceChartGesture(event, state) {
+    switch (event.type) {
+        case 'down': return press(event, state);
+        case 'move': return move(event, state);
+        case 'up':
+        case 'cancel': return release(event, state);
+        case 'wheel': return wheel(event, state);
+    }
+}
+function press(event, state) {
+    const { pointerId, touch, point, view } = event;
+    const { frame, viewport } = view;
+    const touches = !touch ? state.touches
+        : state.touches.some((t) => t.id === pointerId) ? state.touches.map((t) => (t.id === pointerId ? { id: pointerId, ...point } : t))
+            : [...state.touches, { id: pointerId, ...point }];
+    if (touch && touches.length === 2) {
+        // The second finger turns the drag into a pinch.
+        const [a, b] = touches;
+        return {
+            state: {
+                ...state, touches, drag: null,
+                pinch: {
+                    ids: [a.id, b.id], frame, viewport, range: heldRange(frame),
+                    mid: { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 },
+                    dx: Math.abs(a.x - b.x), dy: Math.abs(a.y - b.y),
+                },
+            },
+            capture: true,
+        };
+    }
+    // A press on the price labels moves the price range instead of the time.
+    const price = inGutter(frame, point) && frame.priceBottom > frame.priceTop
+        ? { range: heldRange(frame), perPixel: (frame.priceMax - frame.priceMin) / (frame.priceBottom - frame.priceTop), moved: false }
+        : null;
+    return {
+        state: { ...state, touches, drag: { id: pointerId, x: point.x, y: point.y, viewport, touch, decided: false, vertical: false, price } },
+        capture: true,
+    };
+}
+function move(event, state) {
+    const { pointerId, point, view } = event;
+    const { frame, total, hoverBottom = frame.plotHeight } = view;
+    const touches = state.touches.some((t) => t.id === pointerId) ? state.touches.map((t) => (t.id === pointerId ? { id: pointerId, ...point } : t)) : state.touches;
+    state = touches === state.touches ? state : { ...state, touches };
+    const pinched = state.pinch;
+    if (pinched)
+        return pinched.ids.includes(pointerId) ? { state, ...movePinch(pinched, state.touches, view) } : same(state);
+    const held = state.drag;
+    if (held && held.id === pointerId && held.price) {
+        const moved = held.price.moved || Math.abs(point.y - held.y) > 4;
+        const next = moved === held.price.moved ? state : { ...state, drag: { ...held, price: { ...held.price, moved } } };
+        if (!moved)
+            return same(next);
+        // Dragging the labels down brings higher prices into view, as if the price scale were grabbed.
+        const shift = (point.y - held.y) * held.price.perPixel;
+        return { state: next, priceRange: [held.price.range[0] + shift, held.price.range[1] + shift] };
+    }
+    if (held && held.id === pointerId) {
+        // A finger drifts sideways while it scrolls the page, so a touch drag waits for 8 px, then pans only if it reads as
+        // horizontal. A mostly vertical drag never pans.
+        let drag = held;
+        if (held.touch && !held.decided) {
+            if (Math.hypot(point.x - held.x, point.y - held.y) <= 8)
+                return same(state);
+            drag = { ...held, decided: true, vertical: Math.abs(point.y - held.y) > Math.abs(point.x - held.x) };
+            state = { ...state, drag };
+        }
+        if (drag.vertical)
+            return same(state);
+        return { state, viewport: panViewport(drag.viewport, -(point.x - drag.x) / frame.barWidth, total) };
+    }
+    if (total === 0 || frame.last < frame.first)
+        return same(state);
+    // The gutters show labels, not bars: a pointer there would pick a bar that is not drawn.
+    if (point.x < 0 || point.x >= frame.plotWidth || point.y < 0 || point.y >= hoverBottom)
+        return { state, hover: { price: null } };
+    return {
+        state,
+        hover: {
+            bar: Math.min(frame.last, Math.max(frame.first, Math.round(frame.indexAt(point.x)))),
+            price: point.y >= frame.priceTop && point.y <= frame.priceBottom ? frame.priceAt(point.y) : null,
+        },
+    };
+}
+function movePinch(p, touches, view) {
+    const a = touches.find((t) => t.id === p.ids[0]);
+    const b = touches.find((t) => t.id === p.ids[1]);
+    if (!a || !b)
+        return {};
+    const { total, dataSpan } = view;
+    const dx = Math.abs(a.x - b.x);
+    const dy = Math.abs(a.y - b.y);
+    const mid = { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 };
+    // Fingers spread sideways zoom the time, fingers spread up and down zoom the price. Two fingers that start close
+    // together on one axis leave that axis alone, so a sideways pinch never fixes the price range by accident.
+    const factorX = p.dx >= 24 ? p.dx / Math.max(dx, 1) : 1;
+    let next = zoomViewport(p.viewport, factorX, p.frame.indexAt(p.mid.x), total);
+    const barWidth = p.frame.plotWidth / (next.end - next.start);
+    next = panViewport(next, -(mid.x - p.mid.x) / barWidth, total);
+    if (p.dy < 40)
+        return { viewport: next };
+    const factorY = p.dy / Math.max(dy, 1);
+    const zoomed = zoomPriceRange(p.range, factorY, p.frame.priceAt(p.mid.y), dataSpan);
+    const perPixel = (zoomed[1] - zoomed[0]) / (p.frame.priceBottom - p.frame.priceTop);
+    const shift = (mid.y - p.mid.y) * perPixel;
+    return { viewport: next, priceRange: [zoomed[0] + shift, zoomed[1] + shift] };
+}
+function release(event, state) {
+    const touches = state.touches.filter((t) => t.id !== event.pointerId);
+    state = { ...state, touches };
+    if (state.pinch?.ids.includes(event.pointerId))
+        return same({ ...state, pinch: null, drag: null }); // the finger left behind must not jump the chart
+    const held = state.drag;
+    if (held?.id !== event.pointerId)
+        return same(state);
+    state = { ...state, drag: null };
+    // A quick second tap on the price labels gives the price back to the bars.
+    if (held.price && !held.price.moved && event.type === 'up') {
+        const before = state.lastTap;
+        if (before && event.time - before.time < 400 && Math.hypot(held.x - before.x, held.y - before.y) < 24) {
+            return { state: { ...state, lastTap: null }, priceRange: null };
+        }
+        return same({ ...state, lastTap: { time: event.time, x: held.x, y: held.y } });
+    }
+    return same(state);
+}
+function wheel(event, state) {
+    const { point, deltaY, view } = event;
+    const { frame, viewport, total, dataSpan } = view;
+    if (deltaY === 0 || total === 0)
+        return same(state);
+    // Over the price labels the wheel zooms the price instead of the time.
+    if (inGutter(frame, point)) {
+        return {
+            state,
+            preventDefault: true,
+            priceRange: zoomPriceRange(heldRange(frame), deltaY > 0 ? 1.1 : 0.9, frame.priceAt(Math.min(frame.priceBottom, Math.max(frame.priceTop, point.y))), dataSpan),
+        };
+    }
+    // Only a wheel that zooms is kept from the page: over an empty chart, or at the zoom limit, the page scrolls.
+    const next = zoomViewport(viewport, deltaY > 0 ? 1.1 : 0.9, frame.indexAt(point.x), total);
+    // At the zoom limit the span stays the same but the anchor can still shift the start: that is not a zoom.
+    if (Math.abs((next.end - next.start) - (viewport.end - viewport.start)) < 1e-9)
+        return same(state);
+    return { state, preventDefault: true, viewport: next };
+}

package/dist/core/chart-scale.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The shared geometry of the chart primitives (Candles, Volume, Studies, VolumeProfile, Drawings) as plain
+ * functions. Bars are OpenCandle-shaped records: a Unix-millisecond `timestamp` and numeric OHLCV. Extra fields on a
+ * record are ignored.
+ *
+ * The x axis is the bar index, not the clock, so gaps (nights, weekends) take no space, as traders expect. A point
+ * in time between or beyond bars maps to a fractional index, so drawings anchored to a time keep their place when
+ * the chart scrolls. Nothing here throws on empty or bad input: an empty chart has a frame with no bars.
+ */
+export interface CandleBar {
+    /** Unix milliseconds, ascending and unique across the series. */
+    timestamp: number;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume: number;
+}
+/** The bars on screen: indexes [start, end), fractional while panning. */
+export interface ChartViewport {
+    start: number;
+    end: number;
+}
+export interface ChartSize {
+    width: number;
+    height: number;
+}
+export type PriceSpan = readonly [number, number];
+export type ChartInclude = readonly PriceSpan[] | ((visible: {
+    first: number;
+    last: number;
+}) => readonly PriceSpan[]);
+export interface ChartFrameOptions {
+    /** Share of the height kept for the volume pane under the prices, 0 for none. Default 0.2. */
+    volumeShare?: number;
+    /** Empty pixels above the highest and below the lowest price. Default 8. */
+    pricePadding?: number;
+    /** Width kept on the right for price labels, so they never sit on the bars. Default 56. */
+    axisRight?: number;
+    /** Height kept at the bottom for time labels. Default 18. */
+    axisBottom?: number;
+    /**
+     * Extra prices that must stay in view (study lines, drawings), as [low, high] pairs, or a function of the whole
+     * bars in view that returns them (so a study can measure only what is on screen, e.g. with studyRange).
+     */
+    include?: ChartInclude;
+    /**
+     * A fixed price range [low, high] in place of the autoscale. With it set, the bars and `include` no longer decide
+     * the range, so the view can be moved to any price (a drawing placed above or below the bars).
+     */
+    priceRange?: PriceSpan | null;
+}
+export interface ChartFrame {
+    width: number;
+    height: number;
+    /** Where the bars end and the price-label gutter begins (width minus axisRight). */
+    plotWidth: number;
+    /** Where the panes end and the time-label gutter begins (height minus axisBottom). */
+    plotHeight: number;
+    viewport: ChartViewport;
+    /** The whole bars inside the viewport, clamped to the series. */
+    first: number;
+    last: number;
+    /** Pixels per bar. */
+    barWidth: number;
+    /** Price pane: y runs from priceTop to priceBottom. */
+    priceTop: number;
+    priceBottom: number;
+    priceMin: number;
+    priceMax: number;
+    /** True when the price range is a fixed one a person set, false when it follows the bars. */
+    manualPrice: boolean;
+    /** Volume pane under the prices; empty (volumeTop === volumeBottom) when volumeShare is 0. */
+    volumeTop: number;
+    volumeBottom: number;
+    volumeMax: number;
+    /** Bar index (fractional allowed) to the x of that bar's centre. */
+    x: (index: number) => number;
+    /** x to a fractional bar index. */
+    indexAt: (x: number) => number;
+    y: (price: number) => number;
+    priceAt: (y: number) => number;
+    /** Volume to the y of the top of its bar in the volume pane. */
+    volumeY: (volume: number) => number;
+}
+/** A viewport showing the last `count` bars (all of them when there are fewer). */
+export declare function lastBars(total: number, count: number): ChartViewport;
+/**
+ * The view after the series grows (or shrinks) from `seenTotal` to `total` bars. A view that showed the whole series reopens on the
+ * default window (a chart that starts with 1 or 2 bars must not stay 1 or 2 bars wide), a view at the newest bar keeps its span and
+ * follows, and a view the user moved away from the end stays put. A view past the data is pulled back.
+ */
+export declare function growViewport(view: ChartViewport, seenTotal: number, total: number, span?: number): ChartViewport;
+export declare function chartFrame(bars: readonly CandleBar[], viewport: ChartViewport, size: ChartSize, options?: ChartFrameOptions): ChartFrame;
+/** The usual gap between bars in milliseconds (the median), or 60 000 when there are fewer than two bars. */
+export declare function barInterval(bars: readonly CandleBar[]): number;
+/**
+ * A time to a fractional bar index: exact on a bar, interpolated between two bars, and extrapolated by the usual
+ * interval before the first or after the last bar. This is what keeps a drawing on its time as bars arrive.
+ */
+export declare function indexOfTime(bars: readonly CandleBar[], timestamp: number): number;
+/** The inverse of indexOfTime. */
+export declare function timeOfIndex(bars: readonly CandleBar[], index: number): number;
+/** Round, readable price ticks for the axis: about `count` steps of 1, 2 or 5 times a power of ten. */
+export declare function priceTicks(min: number, max: number, count?: number): number[];
+/** Decimals needed to print a tick step without noise (0.25 needs 2, 5 needs 0), up to the chart's 20. */
+export declare function tickDecimals(ticks: readonly number[]): number;
+export type ChartKeyAction = 'pan-left' | 'pan-right' | 'zoom-in' | 'zoom-out' | 'price-up' | 'price-down' | 'price-zoom-in' | 'price-zoom-out' | 'first' | 'last' | 'previous-bar' | 'next-bar' | 'clear';
+/**
+ * Chart keys: ArrowLeft/Right move the crosshair bar by bar, Shift+Arrow pans a screen tenth, + and - zoom, ArrowUp/Down move the price range a tenth and Shift+ArrowUp/Down zoom it (the first of them leaves the autoscale), Home and
+ * End jump to the first and last bar, Escape clears the crosshair.
+ */
+export declare function resolveChartKey(event: {
+    key: string;
+    altKey: boolean;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    shiftKey: boolean;
+}): ChartKeyAction | null;
+/**
+ * Zoom around a point in bar-index space, where bar i is centred on the integer i (the space frame.x() and
+ * frame.indexAt() use). A pointer passes frame.indexAt(x); the keyboard passes the active bar's index, which is that
+ * bar's centre, so neither needs converting. The point keeps its share of the plot width, so whatever is under the
+ * pointer, and any drawing anchored there, stays put. factor < 1 zooms in. Keeps 5..total+50 bars.
+ */
+export declare function zoomViewport(viewport: ChartViewport, factor: number, around: number, total: number): ChartViewport;
+/** Move the viewport by `bars` (negative is back in time), keeping at least 5 bars of the series in view. */
+export declare function panViewport(viewport: ChartViewport, bars: number, total: number): ChartViewport;
+/** The lowest low and highest high of the whole series (padded like the autoscale when they are equal), or null when it has no finite prices. */
+export declare function dataPriceSpan(bars: readonly CandleBar[]): PriceSpan | null;
+/**
+ * Keeps a hand-set price range usable: its height between a fiftieth and twenty times the height of all the bars, and
+ * its middle no further from the bars than half its own height, so the bars can always be found again. With no bars
+ * there is nothing to measure against and the range passes through unchanged.
+ */
+export declare function clampPriceRange(range: PriceSpan, data: PriceSpan | null): PriceSpan;
+/** Zoom a price range around a price: factor < 1 zooms in, and `around` keeps its share of the height. */
+export declare function zoomPriceRange(range: PriceSpan, factor: number, around: number, data: PriceSpan | null): PriceSpan;
+/** Move a price range by `delta` price units (positive is up). */
+export declare function panPriceRange(range: PriceSpan, delta: number, data: PriceSpan | null): PriceSpan;
+//# sourceMappingURL=chart-scale.d.ts.map

package/dist/core/chart-scale.js

@@ -0,0 +1,302 @@
+/**
+ * The shared geometry of the chart primitives (Candles, Volume, Studies, VolumeProfile, Drawings) as plain
+ * functions. Bars are OpenCandle-shaped records: a Unix-millisecond `timestamp` and numeric OHLCV. Extra fields on a
+ * record are ignored.
+ *
+ * The x axis is the bar index, not the clock, so gaps (nights, weekends) take no space, as traders expect. A point
+ * in time between or beyond bars maps to a fractional index, so drawings anchored to a time keep their place when
+ * the chart scrolls. Nothing here throws on empty or bad input: an empty chart has a frame with no bars.
+ */
+const finite = (n, fallback) => (Number.isFinite(n) ? n : fallback);
+/** A viewport showing the last `count` bars (all of them when there are fewer). */
+export function lastBars(total, count) {
+    const n = Math.max(1, Math.floor(finite(count, 1)));
+    const end = Math.max(0, Math.floor(finite(total, 0)));
+    // A short history shows just its bars; an empty one keeps a nonzero span so the frame stays finite.
+    return { start: Math.max(0, end - n), end: end === 0 ? n : end };
+}
+/**
+ * The view after the series grows (or shrinks) from `seenTotal` to `total` bars. A view that showed the whole series reopens on the
+ * default window (a chart that starts with 1 or 2 bars must not stay 1 or 2 bars wide), a view at the newest bar keeps its span and
+ * follows, and a view the user moved away from the end stays put. A view past the data is pulled back.
+ */
+export function growViewport(view, seenTotal, total, span = 120) {
+    if (view.start <= 0 && view.end >= seenTotal)
+        return lastBars(total, span);
+    if (view.end >= seenTotal || view.end > total)
+        return lastBars(total, view.end - view.start);
+    return view;
+}
+export function chartFrame(bars, viewport, size, options = {}) {
+    const width = Math.max(1, finite(size.width, 1));
+    const height = Math.max(1, finite(size.height, 1));
+    let start = finite(viewport.start, 0);
+    let end = finite(viewport.end, start + 1);
+    if (end - start < 1)
+        end = start + 1;
+    const span = end - start;
+    const plotWidth = Math.max(1, width - Math.max(0, finite(options.axisRight ?? 56, 56)));
+    const plotHeight = Math.max(1, height - Math.max(0, finite(options.axisBottom ?? 18, 18)));
+    const barWidth = plotWidth / span;
+    const first = Math.max(0, Math.floor(start));
+    const last = Math.min(bars.length - 1, Math.ceil(end) - 1);
+    const volumeShare = Math.min(0.6, Math.max(0, finite(options.volumeShare ?? 0.2, 0.2)));
+    const padding = Math.max(0, finite(options.pricePadding ?? 8, 8));
+    const volumeHeight = Math.round(plotHeight * volumeShare);
+    const priceTop = padding;
+    const priceBottom = Math.max(priceTop + 1, plotHeight - volumeHeight - padding);
+    const volumeTop = plotHeight - volumeHeight;
+    const volumeBottom = plotHeight;
+    const fixed = options.priceRange;
+    const manualPrice = !!fixed && Number.isFinite(fixed[0]) && Number.isFinite(fixed[1]) && fixed[1] > fixed[0];
+    let priceMin = Infinity;
+    let priceMax = -Infinity;
+    let volumeMax = 0;
+    for (let i = first; i <= last; i++) {
+        const bar = bars[i];
+        if (!manualPrice) {
+            if (Number.isFinite(bar.low) && bar.low < priceMin)
+                priceMin = bar.low;
+            if (Number.isFinite(bar.high) && bar.high > priceMax)
+                priceMax = bar.high;
+        }
+        if (Number.isFinite(bar.volume) && bar.volume > volumeMax)
+            volumeMax = bar.volume;
+    }
+    if (manualPrice) {
+        priceMin = fixed[0];
+        priceMax = fixed[1];
+    }
+    else {
+        const include = typeof options.include === 'function' ? safeInclude(options.include, first, last) : options.include ?? [];
+        for (const [low, high] of include) {
+            if (Number.isFinite(low) && low < priceMin)
+                priceMin = low;
+            if (Number.isFinite(high) && high > priceMax)
+                priceMax = high;
+        }
+        if (!Number.isFinite(priceMin) || !Number.isFinite(priceMax)) {
+            priceMin = 0;
+            priceMax = 1;
+        }
+        else if (priceMin === priceMax) {
+            const pad = Math.abs(priceMin) * 0.01 || 1;
+            priceMin -= pad;
+            priceMax += pad;
+        }
+    }
+    if (volumeMax <= 0)
+        volumeMax = 1;
+    const priceRange = priceMax - priceMin;
+    const priceSpan = priceBottom - priceTop;
+    const x = (index) => (index - start + 0.5) * barWidth;
+    const indexAt = (px) => px / barWidth + start - 0.5;
+    const y = (price) => priceBottom - ((price - priceMin) / priceRange) * priceSpan;
+    const priceAt = (py) => priceMin + ((priceBottom - py) / priceSpan) * priceRange;
+    const volumeY = (volume) => volumeBottom - (Math.max(0, volume) / volumeMax) * (volumeBottom - volumeTop);
+    return {
+        width, height, plotWidth, plotHeight, viewport: { start, end }, first, last, barWidth,
+        priceTop, priceBottom, priceMin, priceMax, manualPrice, volumeTop, volumeBottom, volumeMax,
+        x, indexAt, y, priceAt, volumeY,
+    };
+}
+function safeInclude(include, first, last) {
+    try {
+        const out = include({ first, last });
+        return Array.isArray(out) ? out : [];
+    }
+    catch {
+        return [];
+    }
+}
+const intervals = new WeakMap();
+/** The usual gap between bars in milliseconds (the median), or 60 000 when there are fewer than two bars. */
+export function barInterval(bars) {
+    if (bars.length < 2)
+        return 60000;
+    const known = intervals.get(bars);
+    if (known?.length === bars.length)
+        return known.interval; // a host that pushes onto the same array gets a fresh one
+    // Every gap, not a sample: gaps that repeat (a weekend every fifth bar) would fool a sample taken at a fixed stride.
+    // Sorted once per series and remembered, so the drawings and the readout can ask as often as they like.
+    const gaps = new Float64Array(bars.length - 1);
+    for (let i = 1; i < bars.length; i++)
+        gaps[i - 1] = bars[i].timestamp - bars[i - 1].timestamp;
+    gaps.sort();
+    const median = gaps[gaps.length >> 1];
+    const interval = median > 0 && Number.isFinite(median) ? median : 60000;
+    intervals.set(bars, { length: bars.length, interval });
+    return interval;
+}
+/**
+ * A time to a fractional bar index: exact on a bar, interpolated between two bars, and extrapolated by the usual
+ * interval before the first or after the last bar. This is what keeps a drawing on its time as bars arrive.
+ */
+export function indexOfTime(bars, timestamp) {
+    const n = bars.length;
+    if (n === 0 || !Number.isFinite(timestamp))
+        return 0;
+    if (timestamp <= bars[0].timestamp)
+        return (timestamp - bars[0].timestamp) / barInterval(bars);
+    if (timestamp >= bars[n - 1].timestamp)
+        return n - 1 + (timestamp - bars[n - 1].timestamp) / barInterval(bars);
+    let lo = 0;
+    let hi = n - 1;
+    while (hi - lo > 1) {
+        const mid = (lo + hi) >> 1;
+        if (bars[mid].timestamp <= timestamp)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    const a = bars[lo].timestamp;
+    const b = bars[hi].timestamp;
+    return lo + (b === a ? 0 : (timestamp - a) / (b - a));
+}
+/** The inverse of indexOfTime. */
+export function timeOfIndex(bars, index) {
+    const n = bars.length;
+    if (n === 0 || !Number.isFinite(index))
+        return 0;
+    if (index <= 0)
+        return bars[0].timestamp + index * barInterval(bars);
+    if (index >= n - 1)
+        return bars[n - 1].timestamp + (index - (n - 1)) * barInterval(bars);
+    const lo = Math.floor(index);
+    const a = bars[lo].timestamp;
+    return a + (index - lo) * (bars[lo + 1].timestamp - a);
+}
+/** Round, readable price ticks for the axis: about `count` steps of 1, 2 or 5 times a power of ten. */
+export function priceTicks(min, max, count = 6) {
+    if (!Number.isFinite(min) || !Number.isFinite(max) || max <= min)
+        return [];
+    const raw = (max - min) / Math.max(1, count);
+    const power = 10 ** Math.floor(Math.log10(raw));
+    const step = [1, 2, 5, 10].map((m) => m * power).find((s) => s >= raw) ?? 10 * power;
+    // Each tick is a whole number of steps, rounded to the step's own places, so float noise goes and a range of
+    // 1e-14 still gets distinct ticks (a fixed 12 places would round them all to 0).
+    const places = Math.min(100, Math.max(0, 1 - Math.floor(Math.log10(step))));
+    const ticks = [];
+    for (let i = Math.ceil(min / step); i * step <= max + step * 1e-9 && ticks.length < 50; i += 1)
+        ticks.push(Number((i * step).toFixed(places)));
+    return ticks;
+}
+/** Decimals needed to print a tick step without noise (0.25 needs 2, 5 needs 0), up to the chart's 20. */
+export function tickDecimals(ticks) {
+    if (ticks.length < 2)
+        return 2;
+    const step = Math.abs(ticks[1] - ticks[0]);
+    if (!Number.isFinite(step) || step === 0)
+        return 2;
+    // The fewest places that print the step exactly (0.25 needs 2, 2.5 needs 1), not only its order of magnitude. A
+    // step below one at these places is not yet printed, however small it is (2e-10 needs 10, not 0).
+    for (let places = 0; places < 20; places += 1) {
+        const scaled = step * 10 ** places;
+        if (Math.round(scaled) >= 1 && Math.abs(scaled - Math.round(scaled)) < 1e-6 * scaled)
+            return places;
+    }
+    return 20;
+}
+/**
+ * Chart keys: ArrowLeft/Right move the crosshair bar by bar, Shift+Arrow pans a screen tenth, + and - zoom, ArrowUp/Down move the price range a tenth and Shift+ArrowUp/Down zoom it (the first of them leaves the autoscale), Home and
+ * End jump to the first and last bar, Escape clears the crosshair.
+ */
+export function resolveChartKey(event) {
+    if (event.altKey || event.ctrlKey || event.metaKey)
+        return null;
+    switch (event.key) {
+        case 'ArrowLeft': return event.shiftKey ? 'pan-left' : 'previous-bar';
+        case 'ArrowRight': return event.shiftKey ? 'pan-right' : 'next-bar';
+        case '+':
+        case '=': return 'zoom-in';
+        case '-':
+        case '_': return 'zoom-out';
+        case 'ArrowUp': return event.shiftKey ? 'price-zoom-in' : 'price-up';
+        case 'ArrowDown': return event.shiftKey ? 'price-zoom-out' : 'price-down';
+        case 'Home': return event.shiftKey ? null : 'first';
+        case 'End': return event.shiftKey ? null : 'last';
+        case 'Escape': return 'clear';
+        default: return null;
+    }
+}
+/**
+ * Zoom around a point in bar-index space, where bar i is centred on the integer i (the space frame.x() and
+ * frame.indexAt() use). A pointer passes frame.indexAt(x); the keyboard passes the active bar's index, which is that
+ * bar's centre, so neither needs converting. The point keeps its share of the plot width, so whatever is under the
+ * pointer, and any drawing anchored there, stays put. factor < 1 zooms in. Keeps 5..total+50 bars.
+ */
+export function zoomViewport(viewport, factor, around, total) {
+    const span = viewport.end - viewport.start;
+    const next = Math.min(Math.max(5, total + 50), Math.max(5, span * (Number.isFinite(factor) && factor > 0 ? factor : 1)));
+    // x() puts bar i's centre half a bar in from the left edge, so the share is measured from start - 0.5.
+    const share = span > 0 ? (around - viewport.start + 0.5) / span : 0.5;
+    const start = around + 0.5 - next * Math.min(1, Math.max(0, share));
+    return clampViewport({ start, end: start + next }, total);
+}
+/** Move the viewport by `bars` (negative is back in time), keeping at least 5 bars of the series in view. */
+export function panViewport(viewport, bars, total) {
+    const shift = Number.isFinite(bars) ? bars : 0;
+    return clampViewport({ start: viewport.start + shift, end: viewport.end + shift }, total);
+}
+function clampViewport(viewport, total) {
+    const span = viewport.end - viewport.start;
+    const keep = Math.min(5, Math.max(1, total));
+    let start = viewport.start;
+    if (start > total - keep)
+        start = total - keep;
+    if (start + span < keep)
+        start = keep - span;
+    return { start, end: start + span };
+}
+/** The lowest low and highest high of the whole series (padded like the autoscale when they are equal), or null when it has no finite prices. */
+export function dataPriceSpan(bars) {
+    let low = Infinity;
+    let high = -Infinity;
+    for (const bar of bars) {
+        if (Number.isFinite(bar.low) && bar.low < low)
+            low = bar.low;
+        if (Number.isFinite(bar.high) && bar.high > high)
+            high = bar.high;
+    }
+    if (!(low <= high))
+        return null;
+    // Flat data gets the same padding the autoscale gives it, so a first pan or zoom keeps its direction and size.
+    if (low === high) {
+        const pad = Math.abs(low) * 0.01 || 1;
+        return [low - pad, high + pad];
+    }
+    return [low, high];
+}
+/**
+ * Keeps a hand-set price range usable: its height between a fiftieth and twenty times the height of all the bars, and
+ * its middle no further from the bars than half its own height, so the bars can always be found again. With no bars
+ * there is nothing to measure against and the range passes through unchanged.
+ */
+export function clampPriceRange(range, data) {
+    let [low, high] = range;
+    if (!Number.isFinite(low) || !Number.isFinite(high) || high <= low)
+        return range;
+    if (!data)
+        return [low, high];
+    const dataHeight = Math.max(data[1] - data[0], Math.abs(data[1]) * 1e-6, 1e-9);
+    const height = Math.min(dataHeight * 20, Math.max(dataHeight / 50, high - low));
+    let middle = (low + high) / 2;
+    middle = Math.min(data[1] + height / 2, Math.max(data[0] - height / 2, middle));
+    low = middle - height / 2;
+    high = middle + height / 2;
+    return [low, high];
+}
+/** Zoom a price range around a price: factor < 1 zooms in, and `around` keeps its share of the height. */
+export function zoomPriceRange(range, factor, around, data) {
+    const height = range[1] - range[0];
+    const f = Number.isFinite(factor) && factor > 0 ? factor : 1;
+    const share = height > 0 ? (around - range[0]) / height : 0.5;
+    const next = height * f;
+    const low = around - next * Math.min(1, Math.max(0, share));
+    return clampPriceRange([low, low + next], data);
+}
+/** Move a price range by `delta` price units (positive is up). */
+export function panPriceRange(range, delta, data) {
+    const d = Number.isFinite(delta) ? delta : 0;
+    return clampPriceRange([range[0] + d, range[1] + d], data);
+}

package/dist/core/csv-bars.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Turns a CSV file the user drops in into chart bars, so a chart can show the user's own data with no feed behind
+ * it. It reads the common shapes: a header row with names in any case and order (Date, Open, High, Low, Close,
+ * Adj Close, Volume, ...), separate Date and Time columns, a header-less file in time-open-high-low-close-volume
+ * order, comma, semicolon or tab delimiters, and decimal commas in semicolon or tab files.
+ *
+ * Times are read as UTC: an ISO date or date-time (an explicit offset is honoured), or a Unix time. A Unix time is read
+ * in the first unit that puts it before the year 2100: seconds, then milliseconds, then microseconds; anything later is
+ * refused. So a millisecond time in the first seven weeks of 1970 would be misread as seconds. Day-first or month-first dates like 02/01/2024 are refused rather than guessed. A row that doesn't
+ * make sense (a missing number, a high below the close, a repeated time) is reported by line, never fixed; the rest
+ * of the file still loads. Nothing here throws.
+ */
+import type { CandleBar } from './chart-scale.js';
+export interface CsvBarsError {
+    /** The 1-based line in the file. 0 for the file as a whole. */
+    line: number;
+    message: string;
+}
+/** `sorted`: the file was newest first. `no-volume`: no volume column, so volume is 0. `no-header`: read by position. */
+export type CsvBarsNote = 'sorted' | 'no-volume' | 'no-header';
+/** A column besides time and the prices that holds only numbers (an indicator, a spread), read beside the bars. */
+export interface CsvExtraColumn {
+    /** The header text as written. */
+    header: string;
+    /** One entry per kept bar, in time order: a number, or `null` when the cell said nothing (empty, `-`, `NA`, `NaN`, `null`). */
+    values: Array<number | null>;
+}
+export interface CsvBarsResult {
+    bars: CandleBar[];
+    errors: CsvBarsError[];
+    notes: CsvBarsNote[];
+    /** Only when `extraColumns` was asked for. */
+    extras?: CsvExtraColumn[];
+    /** Only when `extraColumns` was asked for: headers of columns left out because a cell was not a number or a "no value" word. */
+    skippedColumns?: string[];
+    /** How many bars had a time written without a zone (so `utcOffsetMinutes` applied to them). */
+    zoneless?: number;
+}
+export interface CsvBarsOptions {
+    /** More data rows than this are refused, so a wrong file can't freeze the page. Default 500,000. */
+    maxRows?: number;
+    /**
+     * Minutes east of UTC for times written without a zone (a time with an explicit offset or `Z`, and a Unix time, keep
+     * their own meaning). Default 0: UTC. For a file in New York winter time, pass -300. A fixed offset only; a file that
+     * crosses a daylight-saving change needs the zone written on each row.
+     */
+    utcOffsetMinutes?: number;
+    /** Also read every other all-number column as a series beside the bars. Default false. */
+    extraColumns?: boolean;
+}
+export declare function parseBarsCsv(text: string, options?: CsvBarsOptions): CsvBarsResult;
+/** One plain sentence or two about a parse, for a status line: how many bars loaded and what was skipped. */
+export declare function describeBarsCsv(result: CsvBarsResult, fileName?: string): string;
+//# sourceMappingURL=csv-bars.d.ts.map