wick-charts 0.3.0

package/dist/scale.d.ts

@@ -0,0 +1,20 @@
+/**
+ * JS placeholder for domain→pixel scaling.
+ *
+ * This mirrors `Scale` in crates/wickchart-core/src/lib.rs exactly. It's
+ * the seam where the WASM build gets wired in: once the crate is compiled
+ * with wasm-pack and published as an internal dependency, `LinearScale`
+ * gets replaced by a thin wrapper around the WASM `Scale` for series above
+ * whatever point size profiling says the JS↔WASM call overhead pays for
+ * itself. Small series stay on this plain implementation — there's no
+ * reason to pay a WASM boundary cost to scale a handful of points.
+ */
+export declare class LinearScale {
+    private domainMin;
+    private domainMax;
+    private rangeMin;
+    private rangeMax;
+    constructor(domainMin: number, domainMax: number, rangeMin: number, rangeMax: number);
+    map(value: number): number;
+    mapMany(values: number[]): number[];
+}

package/dist/scale.js

@@ -0,0 +1,29 @@
+/**
+ * JS placeholder for domain→pixel scaling.
+ *
+ * This mirrors `Scale` in crates/wickchart-core/src/lib.rs exactly. It's
+ * the seam where the WASM build gets wired in: once the crate is compiled
+ * with wasm-pack and published as an internal dependency, `LinearScale`
+ * gets replaced by a thin wrapper around the WASM `Scale` for series above
+ * whatever point size profiling says the JS↔WASM call overhead pays for
+ * itself. Small series stay on this plain implementation — there's no
+ * reason to pay a WASM boundary cost to scale a handful of points.
+ */
+export class LinearScale {
+    constructor(domainMin, domainMax, rangeMin, rangeMax) {
+        this.domainMin = domainMin;
+        this.domainMax = domainMax;
+        this.rangeMin = rangeMin;
+        this.rangeMax = rangeMax;
+    }
+    map(value) {
+        const span = this.domainMax - this.domainMin;
+        if (span === 0)
+            return this.rangeMin;
+        const t = (value - this.domainMin) / span;
+        return this.rangeMin + t * (this.rangeMax - this.rangeMin);
+    }
+    mapMany(values) {
+        return values.map((v) => this.map(v));
+    }
+}

package/dist/series/candlestick.d.ts

@@ -0,0 +1,20 @@
+import type { Candle } from '../types.js';
+import type { SeriesDefinition } from './types.js';
+export interface CandlestickStyle {
+    /** Candle body/wick color for up (close >= open) bars. */
+    upColor: string;
+    /** Candle body/wick color for down (close < open) bars. */
+    downColor: string;
+    /** Candle body/wick width as a fraction of the available per-candle slot
+     * width (the rest is inter-candle gap). Defaults to 0.6. */
+    bodyWidthRatio: number;
+    /** Fraction of the chart's full height that volume bars occupy, measured
+     * up from the bottom. Candles still use the full height for their own
+     * price scale regardless of this value — the bars sit in this bottom
+     * margin, layered underneath. Defaults to 0.2. */
+    volumeAreaHeightRatio: number;
+    /** Opacity (0-1) of the volume bars, so they read as a backdrop rather
+     * than competing with the candles drawn over them. Defaults to 0.5. */
+    volumeBarOpacity: number;
+}
+export declare const candlestickSeries: SeriesDefinition<Candle, CandlestickStyle>;

package/dist/series/candlestick.js

@@ -0,0 +1,88 @@
+import { fitRange } from '../priceRange.js';
+import { registerSeries } from './registry.js';
+const DEFAULT_STYLE = {
+    upColor: '#26a69a',
+    downColor: '#ef5350',
+    bodyWidthRatio: 0.6,
+    volumeAreaHeightRatio: 0.2,
+    volumeBarOpacity: 0.5,
+};
+function getValueRange(visible, scaleFactor) {
+    const rawMin = Math.min(...visible.map((c) => c.low));
+    const rawMax = Math.max(...visible.map((c) => c.high));
+    return fitRange(rawMin, rawMax, scaleFactor);
+}
+/** Draws a volume bar per candle that has one, scaled against the largest
+ * volume currently visible. A no-op — nothing reserved, nothing drawn —
+ * when not a single visible candle has `volume` set, so charts built from
+ * OHLC-only data look exactly as they did before this existed. */
+function drawVolumeBars(context, style) {
+    const { ctx, visible, startIndex, xForIndex, slotWidth, chartHeight } = context;
+    const maxVolume = visible.reduce((max, c) => (c.volume !== undefined ? Math.max(max, c.volume) : max), 0);
+    if (maxVolume <= 0)
+        return;
+    const areaHeight = chartHeight * style.volumeAreaHeightRatio;
+    const bodyWidth = Math.max(1, slotWidth * style.bodyWidthRatio);
+    ctx.globalAlpha = style.volumeBarOpacity;
+    visible.forEach((candle, i) => {
+        if (candle.volume === undefined)
+            return;
+        const x = xForIndex(startIndex + i);
+        const barHeight = Math.max(1, (candle.volume / maxVolume) * areaHeight);
+        ctx.fillStyle = candle.close >= candle.open ? style.upColor : style.downColor;
+        ctx.fillRect(x - bodyWidth / 2, chartHeight - barHeight, bodyWidth, barHeight);
+    });
+    ctx.globalAlpha = 1;
+}
+function draw(context, style) {
+    const { ctx, visible, startIndex, xForIndex, slotWidth, yScale } = context;
+    const bodyWidth = Math.max(1, slotWidth * style.bodyWidthRatio);
+    // Drawn first so the (opaque) candles render on top of the (translucent)
+    // volume bars where the two overlap near the bottom of the chart.
+    drawVolumeBars(context, style);
+    // Batched through mapMany (one call per array) rather than four map()
+    // calls per candle in the loop below — the batch is what lets the WASM
+    // path pay the JS<->WASM boundary cost once per frame instead of once
+    // per point.
+    const yHighs = yScale.mapMany(visible.map((c) => c.high));
+    const yLows = yScale.mapMany(visible.map((c) => c.low));
+    const yOpens = yScale.mapMany(visible.map((c) => c.open));
+    const yCloses = yScale.mapMany(visible.map((c) => c.close));
+    visible.forEach((candle, i) => {
+        const x = xForIndex(startIndex + i);
+        const isUp = candle.close >= candle.open;
+        ctx.strokeStyle = ctx.fillStyle = isUp ? style.upColor : style.downColor;
+        ctx.beginPath();
+        ctx.moveTo(x, yHighs[i]);
+        ctx.lineTo(x, yLows[i]);
+        ctx.stroke();
+        const yOpen = yOpens[i];
+        const yClose = yCloses[i];
+        const top = Math.min(yOpen, yClose);
+        const bodyHeight = Math.max(1, Math.abs(yClose - yOpen));
+        ctx.fillRect(x - bodyWidth / 2, top, bodyWidth, bodyHeight);
+    });
+}
+function formatLegend(candle) {
+    const parts = [
+        `O ${candle.open.toLocaleString('en-US')}`,
+        `H ${candle.high.toLocaleString('en-US')}`,
+        `L ${candle.low.toLocaleString('en-US')}`,
+        `C ${candle.close.toLocaleString('en-US')}`,
+    ];
+    if (candle.volume !== undefined) {
+        parts.push(`Vol ${candle.volume.toLocaleString('en-US')}`);
+    }
+    return parts;
+}
+export const candlestickSeries = {
+    type: 'candlestick',
+    defaultStyle: DEFAULT_STYLE,
+    getValueRange,
+    draw,
+    formatLegend,
+};
+// Registered as a module-level side effect so importing this file (which
+// src/index.ts always does) is enough to make 'candlestick' available —
+// callers never register the built-in type themselves.
+registerSeries(candlestickSeries);

package/dist/series/registry.d.ts

@@ -0,0 +1,13 @@
+import type { SeriesPoint } from '../types.js';
+import type { SeriesDefinition } from './types.js';
+/** Registers a series type, making it available to `new WickChart(canvas,
+ * { type: definition.type })`. Call this once per definition — typically as
+ * a module-level side effect in the file that defines it (see
+ * `src/series/candlestick.ts`) so importing the module is enough to make
+ * the type available. */
+export declare function registerSeries<TPoint extends SeriesPoint, TStyle>(definition: SeriesDefinition<TPoint, TStyle>): void;
+/** Resolves a `type` string to its registered definition. Throws rather
+ * than returning `undefined` — an unknown type is a caller mistake (typo,
+ * or forgetting to import the module that registers it), not a state
+ * `WickChart` should silently tolerate. */
+export declare function getSeries<TPoint extends SeriesPoint, TStyle>(type: string): SeriesDefinition<TPoint, TStyle>;

package/dist/series/registry.js

@@ -0,0 +1,30 @@
+/**
+ * Keyed by `SeriesDefinition.type`. Deliberately untyped-at-rest
+ * (`SeriesDefinition<any, any>`) — a registry that must hold arbitrarily
+ * different point/style shapes side by side can't statically relate a
+ * runtime string key to a specific `TPoint`/`TStyle` pair, so the type
+ * safety is pushed to the two functions below instead: `registerSeries`
+ * checks a definition against the type parameters it's called with, and
+ * `getSeries`'s caller asserts what it expects back (exactly like
+ * `JSON.parse`'s return type, or a DI container's `resolve<T>()`).
+ */
+const registry = new Map();
+/** Registers a series type, making it available to `new WickChart(canvas,
+ * { type: definition.type })`. Call this once per definition — typically as
+ * a module-level side effect in the file that defines it (see
+ * `src/series/candlestick.ts`) so importing the module is enough to make
+ * the type available. */
+export function registerSeries(definition) {
+    registry.set(definition.type, definition);
+}
+/** Resolves a `type` string to its registered definition. Throws rather
+ * than returning `undefined` — an unknown type is a caller mistake (typo,
+ * or forgetting to import the module that registers it), not a state
+ * `WickChart` should silently tolerate. */
+export function getSeries(type) {
+    const definition = registry.get(type);
+    if (!definition) {
+        throw new Error(`wick-charts: unknown series type "${type}" — is it registered (registerSeries) and imported?`);
+    }
+    return definition;
+}

package/dist/series/types.d.ts

@@ -0,0 +1,56 @@
+import type { Scale } from '../hybridScale.js';
+import type { SeriesPoint, ValueRange } from '../types.js';
+export type { ValueRange } from '../types.js';
+/**
+ * Everything a series's `draw` needs to turn its visible points into
+ * pixels, precomputed once per frame by `ChartRenderer` so every series
+ * type shares the exact same geometry (no series recomputes its own x
+ * positions or re-derives the y scale).
+ */
+export interface SeriesDrawContext<TPoint extends SeriesPoint> {
+    ctx: CanvasRenderingContext2D;
+    /** The points currently in view, already sliced from the full sorted set. */
+    visible: TPoint[];
+    /** Global (full sorted-array) index of `visible[0]` — add a local offset
+     * to it before calling `xForIndex`. */
+    startIndex: number;
+    /** Global-index -> x pixel. Already accounts for the viewport's
+     * (possibly fractional) pan position, so panning stays pixel-smooth. */
+    xForIndex: (globalIndex: number) => number;
+    /** Pixel width of one candle/point's slot — series that draw a body
+     * width or bar width derive it from this. */
+    slotWidth: number;
+    /** Value (price) -> y pixel for the current frame's domain. */
+    yScale: Scale;
+    chartHeight: number;
+}
+/**
+ * The single seam a new chart type has to implement. `WickChart` and
+ * `ChartRenderer` are written only against this interface — pan/zoom,
+ * touch/mouse handling, on-demand data loading, and axis rendering never
+ * need to know which concrete series is active. Adding a new chart type
+ * (line, area, bar, ...) means writing one file that implements this
+ * interface and calling `registerSeries` on it — see
+ * `src/series/candlestick.ts` for the reference implementation and
+ * `src/series/registry.ts` for how `type` strings resolve to a definition.
+ */
+export interface SeriesDefinition<TPoint extends SeriesPoint, TStyle> {
+    /** Unique key — what `WickChartOptions.type` matches against. */
+    readonly type: string;
+    /** Style used when the caller doesn't override it via `WickChartOptions.style`. */
+    readonly defaultStyle: TStyle;
+    /** Computes the y-domain to auto-fit for the currently visible points,
+     * before the user has manually panned/scaled the value axis (see
+     * `Viewport.valueRangeOverride`). `scaleFactor` is the user's manual
+     * vertical-zoom multiplier and should widen/narrow the fitted range
+     * around its center, not replace it. */
+    getValueRange(visible: TPoint[], scaleFactor: number): ValueRange;
+    /** Draws the visible points for one frame. Must not read or mutate
+     * anything outside `context` and `style` — `ChartRenderer` owns the
+     * canvas lifecycle (clear/background/axes) around this call. */
+    draw(context: SeriesDrawContext<TPoint>, style: TStyle): void;
+    /** Builds the hover/crosshair legend text for one point, one string per
+     * segment (joined with spacing by the renderer). Omit to draw the
+     * crosshair line with no legend text. */
+    formatLegend?(point: TPoint, style: TStyle): string[];
+}

package/dist/series/types.js

@@ -0,0 +1 @@
+export {};

package/dist/testHelpers.d.ts

@@ -0,0 +1,38 @@
+import { vi } from 'vitest';
+/** Minimal fake of the subset of CanvasRenderingContext2D the renderer
+ * actually calls — jsdom implements `<canvas>` as an element but not its
+ * 2D drawing context, so real code under test needs this stood in for
+ * `getContext('2d')`. */
+export interface FakeContext2D {
+    clearRect: ReturnType<typeof vi.fn>;
+    fillRect: ReturnType<typeof vi.fn>;
+    beginPath: ReturnType<typeof vi.fn>;
+    closePath: ReturnType<typeof vi.fn>;
+    moveTo: ReturnType<typeof vi.fn>;
+    lineTo: ReturnType<typeof vi.fn>;
+    stroke: ReturnType<typeof vi.fn>;
+    fill: ReturnType<typeof vi.fn>;
+    fillText: ReturnType<typeof vi.fn>;
+    measureText: ReturnType<typeof vi.fn>;
+    save: ReturnType<typeof vi.fn>;
+    restore: ReturnType<typeof vi.fn>;
+    setLineDash: ReturnType<typeof vi.fn>;
+    fillStyle: string;
+    strokeStyle: string;
+    font: string;
+    textAlign: string;
+    textBaseline: string;
+    globalAlpha: number;
+    lineWidth: number;
+}
+export declare function createFakeContext(): FakeContext2D;
+/** A real jsdom `<canvas>` element (so `addEventListener`/`dispatchEvent`/
+ * `getBoundingClientRect` all behave like a normal DOM node) with its 2D
+ * context stubbed to `createFakeContext()`'s spies. `width`/`height` are
+ * the backing-store size; `getBoundingClientRect` is stubbed to the same
+ * values by default (devicePixelRatio 1) — pass a different `cssWidth`/
+ * `cssHeight` to simulate a scaled display. */
+export declare function createTestCanvas(width?: number, height?: number, cssWidth?: number, cssHeight?: number): {
+    canvas: HTMLCanvasElement;
+    ctx: FakeContext2D;
+};

package/dist/testHelpers.js

@@ -0,0 +1,50 @@
+import { vi } from 'vitest';
+export function createFakeContext() {
+    return {
+        clearRect: vi.fn(),
+        fillRect: vi.fn(),
+        beginPath: vi.fn(),
+        closePath: vi.fn(),
+        moveTo: vi.fn(),
+        lineTo: vi.fn(),
+        stroke: vi.fn(),
+        fill: vi.fn(),
+        fillText: vi.fn(),
+        measureText: vi.fn().mockReturnValue({ width: 40 }),
+        save: vi.fn(),
+        restore: vi.fn(),
+        setLineDash: vi.fn(),
+        fillStyle: '',
+        strokeStyle: '',
+        font: '',
+        textAlign: '',
+        textBaseline: '',
+        globalAlpha: 1,
+        lineWidth: 1,
+    };
+}
+/** A real jsdom `<canvas>` element (so `addEventListener`/`dispatchEvent`/
+ * `getBoundingClientRect` all behave like a normal DOM node) with its 2D
+ * context stubbed to `createFakeContext()`'s spies. `width`/`height` are
+ * the backing-store size; `getBoundingClientRect` is stubbed to the same
+ * values by default (devicePixelRatio 1) — pass a different `cssWidth`/
+ * `cssHeight` to simulate a scaled display. */
+export function createTestCanvas(width = 800, height = 400, cssWidth = width, cssHeight = height) {
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    const ctx = createFakeContext();
+    vi.spyOn(canvas, 'getContext').mockReturnValue(ctx);
+    vi.spyOn(canvas, 'getBoundingClientRect').mockReturnValue({
+        left: 0,
+        top: 0,
+        right: cssWidth,
+        bottom: cssHeight,
+        width: cssWidth,
+        height: cssHeight,
+        x: 0,
+        y: 0,
+        toJSON: () => ({}),
+    });
+    return { canvas, ctx };
+}

package/dist/time.d.ts

@@ -0,0 +1,6 @@
+import type { WickTime } from './types.js';
+/**
+ * Normalizes any supported `WickTime` shape to unix seconds — the single
+ * unit every downstream consumer (sorting, scaling, rendering) works in.
+ */
+export declare function toUnixSeconds(time: WickTime): number;

package/dist/time.js

@@ -0,0 +1,58 @@
+function isUnixMillis(time) {
+    return typeof time === 'object' && time !== null && 'unixMs' in time;
+}
+function isBusinessDay(time) {
+    return typeof time === 'object' && time !== null && 'businessDay' in time;
+}
+function businessDayToUnixSeconds({ year, month, day }) {
+    // BusinessDay has no time-of-day — anchor it at UTC midnight.
+    return Date.UTC(year, month - 1, day) / 1000;
+}
+/**
+ * Registered in the order they should be checked. To support a new source
+ * format (e.g. a vendor that sends `{ ns: bigint }`), add a strategy here —
+ * nothing else in the codebase needs to change.
+ */
+const strategies = [
+    {
+        name: 'unix-seconds',
+        test: (time) => typeof time === 'number',
+        toUnixSeconds: (time) => time,
+    },
+    {
+        name: 'unix-millis',
+        test: isUnixMillis,
+        toUnixSeconds: (time) => time.unixMs / 1000,
+    },
+    {
+        name: 'business-day',
+        test: isBusinessDay,
+        toUnixSeconds: (time) => businessDayToUnixSeconds(time.businessDay),
+    },
+    {
+        name: 'iso-string',
+        test: (time) => typeof time === 'string',
+        toUnixSeconds: (time) => {
+            const parsedMs = Date.parse(time);
+            if (Number.isNaN(parsedMs)) {
+                throw new Error(`wick-charts: could not parse time string "${String(time)}" as ISO 8601`);
+            }
+            return parsedMs / 1000;
+        },
+    },
+];
+/**
+ * Normalizes any supported `WickTime` shape to unix seconds — the single
+ * unit every downstream consumer (sorting, scaling, rendering) works in.
+ */
+export function toUnixSeconds(time) {
+    const strategy = strategies.find((s) => s.test(time));
+    if (!strategy) {
+        throw new Error(`wick-charts: unrecognized time value ${JSON.stringify(time)}`);
+    }
+    const seconds = strategy.toUnixSeconds(time);
+    if (!Number.isFinite(seconds)) {
+        throw new Error(`wick-charts: "${strategy.name}" strategy produced a non-finite time for ${JSON.stringify(time)}`);
+    }
+    return seconds;
+}

package/dist/types.d.ts

@@ -0,0 +1,151 @@
+/** A calendar day with no time-of-day component. */
+export interface BusinessDay {
+    year: number;
+    month: number;
+    day: number;
+}
+/** Explicit unix-milliseconds wrapper — disambiguates from the implicit
+ * unix-*seconds* convention that a bare `number` carries (see src/time.ts).
+ * Millisecond timestamps are a common source format in the wild. */
+export interface UnixMillis {
+    unixMs: number;
+}
+/**
+ * A point in time for any plotted point (candle, line point, etc.).
+ * Deliberately a union of several shapes instead of one
+ * flexible-but-ambiguous type, because time representation is not
+ * universal across data sources:
+ *  - a bare `number`: unix timestamp in **seconds**
+ *  - `{ unixMs }`: unix timestamp in **milliseconds**
+ *  - `{ businessDay }`: a calendar day with no time-of-day
+ *  - a `string`: ISO 8601
+ *
+ * Adding a new source format means adding one case to `src/time.ts`'s
+ * strategy list — this type and the call sites that consume `SeriesPoint`
+ * never need to change.
+ */
+export type WickTime = number | string | UnixMillis | {
+    businessDay: BusinessDay;
+};
+/**
+ * The minimum shape every plotted point must have, regardless of chart
+ * type — a time to place it on the x-axis. `Candle` (OHLC) is one instance
+ * of this; a future line/area/bar series point is another. Everything in
+ * the engine that doesn't need to know *what* is plotted (pan/zoom, event
+ * handling, data loading, merging) is written against this shape, not
+ * against `Candle` — see `src/series/types.ts` for where the per-type
+ * behavior (drawing, value-range, legend text) actually lives.
+ */
+export interface SeriesPoint {
+    time: WickTime;
+}
+/**
+ * A y-domain — a value axis range. The single `{min, max}` shape shared by
+ * `SeriesDefinition.getValueRange`'s result, `Viewport.valueRangeOverride`,
+ * and `src/priceRange.ts`'s `fitRange` helper, so all three talk about "the
+ * currently plotted range" the same way regardless of which series (or
+ * whether the user has manually overridden the axis) produced it.
+ */
+export interface ValueRange {
+    min: number;
+    max: number;
+}
+export interface Candle extends SeriesPoint {
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume?: number;
+}
+/** Text styling shared by every label the chart draws — axis ticks,
+ * crosshair axis labels, and the hover legend. `axisSize`/`legendSize` are
+ * separate since the legend has historically been drawn one px larger to
+ * stand out as the "primary" hover readout; override either independently. */
+export interface ChartFontOptions {
+    /** CSS font family. Defaults to `'sans-serif'`. */
+    family?: string;
+    /** Size, in px, of price/time axis tick labels and crosshair axis labels. Defaults to 10. */
+    axisSize?: number;
+    /** Size, in px, of the hover legend text. Defaults to 11. */
+    legendSize?: number;
+}
+/** Sizing and coloring for the price/time axis strips and their grid lines
+ * — engine-level, not part of any series's own style, since every series
+ * type shares the same two axes regardless of what it plots. */
+export interface ChartAxisOptions {
+    /** Width, in px, of the price-axis strip on the right. Defaults to 64. */
+    priceWidth?: number;
+    /** Height, in px, of the time-axis strip at the bottom. Defaults to 24. */
+    timeHeight?: number;
+    /** Target number of price-axis tick labels. Defaults to 5. */
+    priceTickCount?: number;
+    /** Maximum number of time-axis tick labels. Defaults to 6. */
+    timeMaxTicks?: number;
+    /** Tick label color. Defaults to `'#787878'`. */
+    textColor?: string;
+    /** Color of the two axis boundary lines. Defaults to `'#33333333'`. */
+    lineColor?: string;
+    /** Color of the horizontal price gridlines. Defaults to `'#2a2a2a55'`. */
+    gridLineColor?: string;
+}
+/** Coloring and padding for the hover crosshair's lines and its two
+ * highlighted axis-label chips. */
+export interface ChartCrosshairOptions {
+    /** Dashed crosshair line color. Defaults to `'#9090904d'`. */
+    lineColor?: string;
+    /** Background fill of the price/time label chips. Defaults to `'#3a3a3a'`. */
+    labelBackground?: string;
+    /** Text color inside the label chips. Defaults to `'#f0f0f0'`. */
+    labelTextColor?: string;
+    /** Horizontal padding, in px, inside each label chip. Defaults to 4. */
+    labelPaddingX?: number;
+    /** Vertical padding, in px, inside each label chip. Defaults to 3. */
+    labelPaddingY?: number;
+}
+/** Styling for the hover legend — a tooltip that follows the cursor/finger
+ * showing the OHLC(+volume) breakdown for the hovered point, offset up and
+ * to the right of it and clamped so it never runs off the chart edge. */
+export interface ChartLegendOptions {
+    /** Legend text color. Defaults to `'#f0f0f0'`. */
+    textColor?: string;
+    /** Tooltip background fill. Defaults to `'#3a3a3a'`. */
+    background?: string;
+    /** Horizontal padding, in px, inside the tooltip. Defaults to 8. */
+    paddingX?: number;
+    /** Vertical padding, in px, inside the tooltip. Defaults to 6. */
+    paddingY?: number;
+    /** Gap, in px, between the hovered pixel and the tooltip's nearest edge.
+     * Defaults to 12. */
+    cursorGap?: number;
+}
+export interface WickChartOptions {
+    /**
+     * Which registered series type to render this chart as (see
+     * `registerSeries` in `src/series/registry.ts`). Defaults to
+     * `'candlestick'`, the only type built into the library today — adding a
+     * new one is a matter of implementing `SeriesDefinition` and registering
+     * it, without changing `WickChart` or `ChartRenderer` at all.
+     */
+    type?: string;
+    /** Background color of the canvas. Defaults to transparent. Chart-wide
+     * (the renderer clears/fills the whole canvas with it), not part of any
+     * series's own style. */
+    background?: string;
+    /**
+     * Style overrides specific to the chosen `type` — shape depends on which
+     * series is active (candlestick's is `CandlestickStyle`). Merged over the
+     * series definition's `defaultStyle`.
+     */
+    style?: Record<string, unknown>;
+    /** Font family/sizes for every label the chart draws. Merged over the
+     * built-in defaults field by field — set only what you want to change. */
+    font?: ChartFontOptions;
+    /** Price/time axis sizing, tick counts, and coloring. Merged over the
+     * built-in defaults field by field. */
+    axis?: ChartAxisOptions;
+    /** Hover crosshair line/label coloring and padding. Merged over the
+     * built-in defaults field by field. */
+    crosshair?: ChartCrosshairOptions;
+    /** Hover legend coloring. Merged over the built-in defaults field by field. */
+    legend?: ChartLegendOptions;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/viewport.d.ts

@@ -0,0 +1,52 @@
+import type { ValueRange } from './types.js';
+/**
+ * Pure pan/zoom/value-scale state — no DOM, no canvas. `WickChart` owns
+ * translating pixel deltas (drag distance, wheel delta) into calls here;
+ * this class only owns the resulting numbers, which keeps it unit-testable
+ * without a canvas. Generic across series types: "value" here is whatever
+ * the active `SeriesDefinition.getValueRange` returns for the y-axis —
+ * price for candlesticks, but no different in kind for a future line or
+ * bar series's own value domain.
+ */
+export declare class Viewport {
+    startIndex: number;
+    visibleCount: number;
+    /** 1 = auto-fit value range. >1 widens it (the series looks
+     * shorter/compressed). <1 narrows it (the series looks taller), clamped
+     * so real data never clips off-screen. Sign of drag->factor mapping
+     * lives in WickChart, not here. */
+    valueScaleFactor: number;
+    /** Manually-set value range from a vertical drag or value-axis scale.
+     * `null` until the user first touches the value axis — while `null` the
+     * renderer auto-fits (see `SeriesDefinition.getValueRange`) using
+     * `valueScaleFactor` alone. Once set, auto-fit stops applying: the user
+     * has taken explicit control of the axis, so the chart stops
+     * recentering it under them. */
+    valueRangeOverride: ValueRange | null;
+    constructor(totalCount: number, visibleCount?: number);
+    get endIndex(): number;
+    /** Shifts the visible window. Positive `deltaPoints` moves forward in
+     * time (later points come into view on the right). Clamped so the
+     * window never leaves [0, totalCount] — no overscroll past the data. */
+    pan(deltaPoints: number, totalCount: number): void;
+    /** Scales the visible window by `factor` (>1 zooms out, <1 zooms in),
+     * keeping the point at `anchorIndex` under the same relative position —
+     * the standard "zoom toward the cursor" feel. */
+    zoom(factor: number, anchorIndex: number, totalCount: number): void;
+    /** Multiplies the value-scale factor, clamped to a sane range so the
+     * value axis can't be dragged into showing nothing or clipping data.
+     * Only affects the auto-fit path — a no-op once `valueRangeOverride` is
+     * set, at which point `scaleValueRange` takes over. */
+    scaleValue(factor: number): void;
+    /** Switches the value axis to manual mode, pinned at `range`. Call once,
+     * lazily, the first time the user drags vertically — see `WickChart`. */
+    setValueRangeOverride(range: ValueRange): void;
+    /** Shifts the manual value range by an absolute amount (same units as
+     * the plotted value). No-op until `setValueRangeOverride` has been
+     * called at least once — there is nothing to shift relative to
+     * otherwise. */
+    panValueRange(deltaAbsolute: number): void;
+    /** Scales the manual value range around its own center. No-op until
+     * `setValueRangeOverride` has been called at least once. */
+    scaleValueRange(factor: number): void;
+}