@photonviz/core 0.1.1 → 0.2.1

package/README.md

@@ -0,0 +1,70 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/coredumpdev/photon/master/assets/banner.png" alt="Photon" width="100%" />
+</p>
+
+# @photonviz/core
+
+**GPU-accelerated scientific plotting for the web — WebGL2, zero dependencies.**
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/coredumpdev/photon/master/assets/streaming.gif" alt="Live streaming WebGL2 charts at 60fps" width="100%" />
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/coredumpdev/photon/master/assets/gallery-full.png" alt="Photon chart gallery" width="100%" />
+</p>
+
+The framework-agnostic core of [Photon](https://github.com/coredumpdev/photon).
+Renders geometry on the GPU (instanced WebGL2 + min/max decimation) and draws
+axes, ticks, and labels on a crisp Canvas2D overlay — so you get both **scale**
+(millions of points at 60fps) and **sharp text**.
+
+```bash
+npm i @photonviz/core
+```
+
+> Framework bindings: [`@photonviz/react`](https://www.npmjs.com/package/@photonviz/react) · [`@photonviz/vue`](https://www.npmjs.com/package/@photonviz/vue) · [`@photonviz/svelte`](https://www.npmjs.com/package/@photonviz/svelte)
+> Vector maps: [`@photonviz/map`](https://www.npmjs.com/package/@photonviz/map)
+
+## Quick start
+
+```ts
+import { Plot } from "@photonviz/core";
+
+const plot = new Plot(document.getElementById("chart")!, {
+  theme: "dark",
+  scales: { y: { type: "log" } },
+});
+
+plot.addLine({ x: xs, y: ys, color: "#60a5fa", width: 2, name: "signal" });
+// wheel to zoom · drag to pan · box-zoom + home from the toolbar · hover for tooltips
+```
+
+## Chart types
+
+| Type | API |
+| --- | --- |
+| Line / Step | `plot.addLine({ x, y, color, width, step })` — real thick lines, round/miter/bevel joins |
+| Scatter | `plot.addScatter({ x, y, size, colorBy })` — instanced, colormap by value |
+| Bar | `plot.addBar({ x, y, width, offset, base })` — grouped / stacked |
+| Area | `plot.addArea({ x, y, base })` |
+| Histogram | `plot.addHistogram(values, { bins })` |
+| Box / Violin | `plot.addBox({ groups, violin })` — Tukey quartiles, KDE |
+| Heatmap | `plot.addHeatmap({ values, cols, rows, extent, colormap })` |
+| Contour | `plot.addContour({ values, cols, rows, extent, levels })` |
+| Hexbin | `plot.addHexbin({ x, y, radius, colormap })` |
+| Error bar / Stem / Quiver / Candlestick | `plot.addErrorBar` · `addStem` · `addQuiver` · `addCandlestick` |
+
+**Polar** — `new PolarPlot(el)` with `addLine` / `addScatter` (drag to rotate, wheel to zoom).
+**3D** — `new Plot3D(el)` with `addSurface` / `addPointCloud` (orbit camera).
+
+## Features
+
+- **Scales** — linear, log (decade ticks + GPU log transform), time (large epoch timestamps via per-layer reference offsets).
+- **Streaming** — line/scatter/bar/area expose `setData()` to re-upload GPU buffers each frame.
+- **Interaction** — wheel-zoom, pan, box/X/Y zoom, hover crosshair + tooltips, multiple Y axes, custom ticks.
+- **Many charts, one context** — a single shared WebGL2 context backs every plot, so a page can hold dozens.
+
+## License
+
+[MIT](https://github.com/coredumpdev/photon/blob/master/LICENSE) — full docs & source at [github.com/coredumpdev/photon](https://github.com/coredumpdev/photon).

package/dist/index.d.ts

@@ -40,12 +40,29 @@ interface Bounds {
 /** RGBA in 0..1. */
 type Color = readonly [number, number, number, number];
 
+/**
+ * Shared data→clip transform used by every layer's vertex shader.
+ *
+ * Two subtleties it handles:
+ *  - **Log axes** — when `uLogX/uLogY` is set, the real coordinate is
+ *    log10-transformed on the GPU.
+ *  - **Float32 precision** — vertex buffers are float32 (~7 significant digits),
+ *    which is not enough for large values like epoch-millisecond timestamps.
+ *    Layers upload coordinates *relative to a reference* (`x - xRef`) and pass
+ *    `uXRef`; the domain is passed in the same offset space, so the subtraction
+ *    that computes the normalized position never suffers catastrophic
+ *    cancellation. For log axes the reference is added back before log10.
+ */
+declare const TRANSFORM_GLSL = "\nuniform vec2 uDomainX;   // linear: (lo-ref, hi-ref) ; log: (log10 lo, log10 hi)\nuniform vec2 uDomainY;\nuniform float uXRef;\nuniform float uYRef;\nuniform float uLogX;     // >0.5 => log axis\nuniform float uLogY;\n\nvec2 dataToNorm(vec2 p) {\n  float cx = (uLogX > 0.5) ? log(p.x + uXRef) / 2.302585092994046 : p.x;\n  float cy = (uLogY > 0.5) ? log(p.y + uYRef) / 2.302585092994046 : p.y;\n  float nx = (cx - uDomainX.x) / (uDomainX.y - uDomainX.x);\n  float ny = (cy - uDomainY.x) / (uDomainY.y - uDomainY.x);\n  return vec2(nx, ny);\n}\n\nvec2 dataToClip(vec2 p) {\n  return dataToNorm(p) * 2.0 - 1.0;\n}\n";
 /** Per-axis view state handed to a layer each frame. `lo`/`hi` are raw data-space. */
 interface AxisFrame {
     lo: number;
     hi: number;
     log: boolean;
 }
+declare const TRANSFORM_UNIFORMS: readonly ["uDomainX", "uDomainY", "uXRef", "uYRef", "uLogX", "uLogY"];
+/** Set the shared transform uniforms for a layer given its per-axis references. */
+declare function setTransformUniforms(gl: WebGL2RenderingContext, u: Record<string, WebGLUniformLocation | null>, x: AxisFrame, y: AxisFrame, xRef: number, yRef: number): void;
 
 /** State handed to a layer each frame so it can transform data to clip space. */
 interface DrawState {
@@ -416,6 +433,26 @@ declare class HexbinLayer implements Layer {
     dispose(): void;
 }
 
+/**
+ * Shared hover-picking used by point/series layers (line, scatter, stem).
+ *
+ * The mode decides which pixel-space distance is minimized:
+ *  - `"x"`  — nearest by horizontal distance (classic crosshair-along-x)
+ *  - `"y"`  — nearest by vertical distance
+ *  - `"xy"` — nearest by true 2D distance (checks both axes; right for point
+ *             clouds / maps, where an x-only match would highlight the wrong
+ *             point)
+ *
+ * Distances are computed in pixels via `project`, so x and y are compared on
+ * the same footing regardless of each axis's data range.
+ */
+type PickMode = "x" | "y" | "xy";
+interface Picked {
+    x: number;
+    y: number;
+    index: number;
+}
+
 /** How adjacent segments meet at a vertex. */
 type LineJoin = "round" | "miter" | "bevel" | "butt";
 interface LineOptions {
@@ -491,11 +528,7 @@ declare class LineLayer implements Layer {
         x: Range;
         y: Range;
     } | null;
-    nearestByX(x: number): {
-        x: number;
-        y: number;
-        index: number;
-    } | null;
+    pick(mode: PickMode, cursorPx: number, cursorPy: number, project: (x: number, y: number) => [number, number]): Picked | null;
     /** Replace the series data and re-upload the GPU buffer (for streaming). */
     setData(x: ArrayLike<number>, y: ArrayLike<number>): void;
     /**
@@ -569,6 +602,12 @@ interface ScatterOptions {
     size?: number;
     name?: string;
     yAxis?: string;
+    /**
+     * Optional per-point text shown when a point is clicked (one entry per point,
+     * parallel to `x`/`y`). Lets you attach your own info instead of the default
+     * coordinate readout.
+     */
+    labels?: ArrayLike<string>;
     /** Color each point by a value through a colormap. */
     colorBy?: {
         values: ArrayLike<number>;
@@ -591,6 +630,7 @@ declare class ScatterLayer implements Layer {
     private size;
     private color;
     private useVertexColor;
+    private labels?;
     private xRef;
     private yRef;
     private xs;
@@ -602,11 +642,9 @@ declare class ScatterLayer implements Layer {
         x: Range;
         y: Range;
     } | null;
-    nearestByX(x: number): {
-        x: number;
-        y: number;
-        index: number;
-    } | null;
+    pick(mode: PickMode, cursorPx: number, cursorPy: number, project: (x: number, y: number) => [number, number]): Picked | null;
+    /** User-supplied text for a point, shown when it is clicked. */
+    infoAt(index: number): string[] | null;
     /** Replace point positions and re-upload (for streaming). Keeps uniform color. */
     setData(x: ArrayLike<number>, y: ArrayLike<number>): void;
     draw(state: DrawState): void;
@@ -654,11 +692,7 @@ declare class StemLayer implements Layer {
         x: Range;
         y: Range;
     } | null;
-    nearestByX(x: number): {
-        x: number;
-        y: number;
-        index: number;
-    } | null;
+    pick(mode: PickMode, cursorPx: number, cursorPy: number, project: (x: number, y: number) => [number, number]): Picked | null;
     draw(state: DrawState): void;
     dispose(): void;
 }
@@ -751,6 +785,11 @@ interface YAxisOptions extends AxisConfig {
     /** Axis + label color (secondary axes often match their series). */
     color?: string;
 }
+/** One line of the hover tooltip header, produced by {@link PlotOptions.hoverReadout}. */
+interface HoverReadoutRow {
+    label: string;
+    value: string;
+}
 interface PlotOptions {
     scales?: {
         x?: AxisScaleOptions;
@@ -765,11 +804,47 @@ interface PlotOptions {
     /** Enable wheel-zoom and drag interaction. Default true. */
     interactive?: boolean;
     /** Show the built-in toolbar (home + pan/box/X/Y zoom modes). Default true. */
-    toolbar?: boolean;
-    /** Initial interaction mode. Default `"box"`. */
+    showToolbar?: boolean;
+    /** Initial interaction mode. Default `"pan"`. */
     mode?: InteractionMode;
     /** Enable hover crosshair + tooltip. Default true. */
     hover?: boolean;
+    /**
+     * How hover selects the highlighted point: `"x"` nearest by x (classic),
+     * `"y"` nearest by y, or `"xy"` nearest by 2D distance — the last checks both
+     * axes, which is what a scatter/map needs. Default `"x"`.
+     */
+    pick?: PickMode;
+    /**
+     * When a point's pinned detail box appears: `"click"` pins it on click (until
+     * you click empty space), `"hover"` shows it while the cursor is over a point.
+     * Default `"click"`.
+     */
+    pointInfo?: "hover" | "click";
+    /**
+     * Show dashed guide lines on *both* the X and Y axes at the cursor — on hover
+     * and while the pointer is pressed. When false, hover shows only the vertical
+     * (X) line and there are no press guides. Default true.
+     */
+    crosshair?: boolean;
+    /**
+     * Keep data-units-per-pixel equal on both axes so nothing is distorted (the
+     * looser axis is expanded to match). Essential for maps. Default false.
+     */
+    equalAspect?: boolean;
+    /**
+     * Constrain panning/zooming so the view can't move outside the data bounds
+     * (the union of all layers' extents). Zoom still works; the view is just
+     * kept inside the limits. Default false (a map turns it on).
+     */
+    boundedPan?: boolean;
+    /**
+     * Customize the tooltip header shown on hover. Given the cursor's data-space
+     * X and Y (primary y axis), return the lines to display above the series
+     * rows — e.g. a map converts world coords to `lon`/`lat`. When omitted, the
+     * header is the default single `x = …` line. Default undefined.
+     */
+    hoverReadout?: (dataX: number, dataY: number) => HoverReadoutRow[];
 }
 /**
  * The imperative core plot. Owns a stack of three canvases (grid / WebGL data /
@@ -805,7 +880,18 @@ declare class Plot {
     private toolbarHandle;
     private hoverEnabled;
     private hoverPx;
+    private pickMode;
+    private pointInfo;
+    private crosshair;
+    private equalAspect;
+    private boundedPan;
+    private hoverReadout?;
+    /** Cursor position while the pointer is pressed, when `crosshair`. */
+    private pressPx;
     private tooltip;
+    /** A point clicked to pin its details, until another click clears it. */
+    private selected;
+    private infoBox;
     constructor(container: HTMLElement, options?: PlotOptions);
     private makeCanvas;
     /** Margins grow to make room for extra y axes on each side. */
@@ -814,6 +900,22 @@ declare class Plot {
     /** Pixel x-position (and title x) for each y axis, by draw order per side. */
     private yAxisPositions;
     private register;
+    /**
+     * Register a layer built outside core (e.g. `@photonviz/map`). Use with
+     * {@link context} to construct the layer against this plot's WebGL2 context.
+     */
+    add<T extends Layer>(layer: T): T;
+    /** The shared WebGL2 context, for constructing custom layers. */
+    get context(): WebGL2RenderingContext;
+    /**
+     * Convert a client (screen) coordinate to data space — the shared x and the
+     * primary y. Returns null if the point is outside the plot region. Useful for
+     * custom hit-testing (e.g. map feature picking on click).
+     */
+    dataAt(clientX: number, clientY: number): {
+        x: number;
+        y: number;
+    } | null;
     addLine(opts: LineOptions): LineLayer;
     addScatter(opts: ScatterOptions): ScatterLayer;
     addBar(opts: BarOptions): BarLayer;
@@ -879,6 +981,26 @@ declare class Plot {
     private panY;
     private attachInteraction;
     private setHover;
+    /** Update the press-crosshair position and redraw. */
+    private setPress;
+    /** Nearest point (2D, within a small radius) under the cursor, or null. */
+    private pickPoint;
+    /** Click handler: in `pointInfo:"click"` mode, pin the point under the cursor. */
+    private handleClick;
+    /** Draw the pinned point's marker and position its info box (or hide it). */
+    private updateInfoBox;
+    /** Data-space x extent across all layers, or null if empty. */
+    private layerBoundsX;
+    /** Data-space y extent across the layers bound to axis `id`, or null. */
+    private layerBoundsY;
+    /** Keep the view inside the data bounds (used when `boundedPan`). */
+    private clampView;
+    /**
+     * Expand the looser axis so both axes share the same data-units-per-pixel,
+     * preventing distortion (maps set `equalAspect`). Linear axes only; balances
+     * the primary y against x, and is idempotent once balanced.
+     */
+    private applyAspect;
     private drawSelection;
     private applySelection;
     private zoomAround;
@@ -912,6 +1034,18 @@ interface PolarOptions {
     /** Fixed max radius. If omitted, autoscales to the data. */
     maxRadius?: number;
     margin?: number;
+    /** Enable wheel-zoom (r scale) and drag-rotate interaction. Default true. */
+    interactive?: boolean;
+    /** Enable hover: highlight the nearest point + show a tooltip. Default true. */
+    hover?: boolean;
+    /** Show the built-in home (reset) button. Default true. */
+    showToolbar?: boolean;
+    /**
+     * How the pinned point-info box is triggered: `"click"` pins a point until
+     * empty space is clicked; `"hover"` shows the point under the cursor
+     * automatically (no click). Default `"click"`.
+     */
+    pointInfo?: "hover" | "click";
 }
 interface PolarLineOptions {
     theta: ArrayLike<number>;
@@ -926,6 +1060,8 @@ interface PolarScatterOptions {
     r: ArrayLike<number>;
     color?: string | Color;
     size?: number;
+    /** Optional per-point labels (one per point), shown as the title of the click-pinned info box. */
+    labels?: ArrayLike<string>;
 }
 /** A live handle to update a polar series with new (theta, r) data. */
 interface PolarSeries {
@@ -936,19 +1072,37 @@ declare class PolarPlot {
     private container;
     private gridCanvas;
     private dataCanvas;
+    private overlayCanvas;
     private gridCtx;
     private dataCtx;
+    private overlayCtx;
     private gl;
     private sharedCanvas;
     private theme;
+    private isDark;
     private toRad;
     private fixedR?;
     private margin;
     private entries;
     private R;
+    private baseR;
     private dpr;
     private resizeObserver;
     private frameRequested;
+    private interactive;
+    private hoverEnabled;
+    /** Multiplier on the fitted radius: <1 zooms in (smaller r-domain), >1 out. */
+    private zoom;
+    /** Angular offset (radians, CCW) applied to all series + gridlines. */
+    private rotation;
+    private hoverPx;
+    private tooltip;
+    private homeButton;
+    /** A point clicked to pin its details, until another click clears it. */
+    private selected;
+    private infoBox;
+    /** Whether the info box is triggered by `"click"` (pinned) or `"hover"`. */
+    private pointInfo;
     constructor(container: HTMLElement, options?: PolarOptions);
     private makeCanvas;
     private toXY;
@@ -956,6 +1110,14 @@ declare class PolarPlot {
     addScatter(opts: PolarScatterOptions): PolarSeries;
     private handle;
     private refit;
+    /** Re-project every series with the current rotation (called when rotation changes). */
+    private retransform;
+    /** Reset zoom (r-domain) and rotation back to the initial view. */
+    home(): void;
+    /** Current rotation offset in radians (CCW). */
+    getRotation(): number;
+    /** Set the rotation offset (radians, CCW) and redraw. */
+    setRotation(rad: number): void;
     destroy(): void;
     private resize;
     requestRender(): void;
@@ -963,6 +1125,19 @@ declare class PolarPlot {
     private square;
     render(): void;
     private drawGrid;
+    private setHover;
+    /** Nearest data point (across all series) to a cursor position, in CSS px. */
+    private pickNearest;
+    /** Draw a filled, white-ringed marker on the overlay at a screen position. */
+    private drawPointMarker;
+    private renderHover;
+    /** Click handler: pin the nearest point's details, or clear on empty space. */
+    private handleClick;
+    /** Draw the pinned point's marker and position its info box (or hide it). */
+    private updateInfoBox;
+    private updateTooltip;
+    private attachInteraction;
+    private makeHomeButton;
 }
 
 /** Minimal column-major 4×4 matrix helpers for the 3D plots (WebGL convention). */
@@ -1192,9 +1367,14 @@ interface Density {
  */
 declare function kde(values: ArrayLike<number>, lo: number, hi: number, points?: number, bandwidth?: number): Density;
 
+/** Compile + link a vertex/fragment program. */
+declare function createProgram(gl: WebGL2RenderingContext, vert: string, frag: string): WebGLProgram;
+/** Cache uniform locations for a program by name. */
+declare function uniformLocations(gl: WebGL2RenderingContext, program: WebGLProgram, names: string[]): Record<string, WebGLUniformLocation | null>;
+
 /** Parse a CSS hex/rgb color string into normalized RGBA (0..1). */
 declare function parseColor(input: string): [number, number, number, number];
 /** Normalized RGBA (0..1) back to a CSS `rgba(...)` string. */
 declare function toColorCss(c: readonly [number, number, number, number]): string;
 
-export { AreaLayer, type AreaOptions, Axis, type AxisConfig, type AxisFrame, type AxisScaleOptions, BarLayer, type BarOptions, type Bounds, type Bounds3, type BoxGroup, BoxLayer, type BoxOptions, type BoxStats, CandlestickLayer, type CandlestickOptions, type Color, type ColormapName, ContourLayer, type ContourOptions, type Density, type Dim, type DrawState, ErrorBarLayer, type ErrorBarOptions, HeatmapLayer, type HeatmapOptions, HexbinLayer, type HexbinOptions, type Histogram, type InteractionMode, type Layer, type Layer3D, type Layout, LineLayer, type LineOptions, LinearScale, LogScale, Plot, Plot3D, type Plot3DOptions, type PlotOptions, PointCloudLayer, type PointCloudOptions, type PolarLineOptions, type PolarOptions, PolarPlot, type PolarScatterOptions, type PolarSeries, QuiverLayer, type QuiverOptions, type RGB, type Range, type Scale, type ScaleType, ScatterLayer, type ScatterOptions, type Spectrogram, StemLayer, type StemOptions, SurfaceLayer, type SurfaceOptions, type Theme, type Tick, type TicksSpec, TimeScale, type ToolbarHost, type ToolbarTheme, type YAxisOptions, autoTicks, boxStats, colormap, createToolbar, darkTheme, defaultFormat, fft, histogram, kde, lightTheme, makeScale, parseColor, quantileSorted, resolveTicks, spectrogram, toColorCss, withMinorTicks };
+export { AreaLayer, type AreaOptions, Axis, type AxisConfig, type AxisFrame, type AxisScaleOptions, BarLayer, type BarOptions, type Bounds, type Bounds3, type BoxGroup, BoxLayer, type BoxOptions, type BoxStats, CandlestickLayer, type CandlestickOptions, type Color, type ColormapName, ContourLayer, type ContourOptions, type Density, type Dim, type DrawState, ErrorBarLayer, type ErrorBarOptions, HeatmapLayer, type HeatmapOptions, HexbinLayer, type HexbinOptions, type Histogram, type HoverReadoutRow, type InteractionMode, type Layer, type Layer3D, type Layout, LineLayer, type LineOptions, LinearScale, LogScale, type PickMode, Plot, Plot3D, type Plot3DOptions, type PlotOptions, PointCloudLayer, type PointCloudOptions, type PolarLineOptions, type PolarOptions, PolarPlot, type PolarScatterOptions, type PolarSeries, QuiverLayer, type QuiverOptions, type RGB, type Range, type Scale, type ScaleType, ScatterLayer, type ScatterOptions, type Spectrogram, StemLayer, type StemOptions, SurfaceLayer, type SurfaceOptions, TRANSFORM_GLSL, TRANSFORM_UNIFORMS, type Theme, type Tick, type TicksSpec, TimeScale, type ToolbarHost, type ToolbarTheme, type YAxisOptions, autoTicks, boxStats, colormap, createProgram, createToolbar, darkTheme, defaultFormat, fft, histogram, kde, lightTheme, makeScale, parseColor, quantileSorted, resolveTicks, setTransformUniforms, spectrogram, toColorCss, uniformLocations, withMinorTicks };