minerva-design 1.0.2 → 1.2.0

package/dist/charts/engine/controller.d.cts

@@ -0,0 +1,182 @@
+import { Rect } from './layout.cjs';
+import { ChartModel } from './model.cjs';
+import { PointLabel, ResolvedAnnotation } from './overlay.cjs';
+import { ChartLayout, HoverMark, TooltipContent } from './scene.cjs';
+import { ChartTheme, ChartThemeInput } from './theme.cjs';
+import { ChartEventMap, ChartHoverEvent, ChartOptions, ChartRect, ChartView } from './types.cjs';
+/** Events of a controller (no renderer events: hosts draw themselves) */
+export type ChartControllerEventMap = Omit<ChartEventMap, "renderer">;
+export interface ChartControllerConfig {
+    options: ChartOptions;
+    /** Colors and fonts (Minerva variables); light defaults when omitted */
+    theme?: ChartThemeInput;
+    /** Width in pixels of `text` drawn with the CSS `font` */
+    measureText: (text: string, font: string) => number;
+    /** Called when the scene changed and must be drawn again */
+    onInvalidate?: () => void;
+}
+export interface ChartLegendEntry {
+    id: string;
+    name: string;
+    /** CSS color */
+    color: string;
+    shape: "dot" | "line" | "square";
+    hidden: boolean;
+    /** Hit / draw box of the entry, pixels of the chart */
+    box: Rect;
+}
+export interface ChartLegendLayout {
+    entries: ChartLegendEntry[];
+    position: "top" | "bottom";
+    /** Whether a tap toggles the series */
+    toggle: boolean;
+    /** Height taken by the legend */
+    height: number;
+}
+export interface ChartTooltipLayout {
+    /** Default content (`text` is set instead when `tooltip.render` returns a string) */
+    content: TooltipContent;
+    /** Lines of a custom string tooltip */
+    text: string[] | null;
+    /** Box of the tooltip, pixels of the chart */
+    box: Rect;
+    /** Line height used to lay the box out */
+    lineHeight: number;
+    padding: number;
+}
+export interface ChartHoverLayout {
+    event: ChartHoverEvent;
+    marks: HoverMark[];
+    /** X pixel of the guide line (`null` when hidden) */
+    crosshairX: number | null;
+    tooltip: ChartTooltipLayout | null;
+}
+/** Everything a host draws, in CSS pixels of the chart */
+export interface ChartScene {
+    width: number;
+    height: number;
+    theme: ChartTheme;
+    model: ChartModel;
+    view: ChartView;
+    layout: ChartLayout;
+    annotations: ResolvedAnnotation[];
+    /** Labels of the dots that found a free slot */
+    pointLabels: {
+        label: PointLabel;
+        box: Rect;
+    }[];
+    legend: ChartLegendLayout | null;
+    hover: ChartHoverLayout | null;
+    /** Point being dragged (`interaction.dragPoints`) */
+    dragging: {
+        x: number;
+        y: number;
+        color: string;
+        size: number;
+    } | null;
+}
+export interface ChartPointerOptions {
+    /** Pointer id (touch identifier); 0 by default */
+    id?: number;
+    /** Touch input: the tooltip follows the finger and stays after a tap */
+    touch?: boolean;
+}
+export interface ChartController {
+    setOptions(options: ChartOptions): void;
+    setTheme(theme: ChartThemeInput | undefined): void;
+    /** Size of the chart in CSS pixels */
+    setSize(width: number, height: number): void;
+    /** What to draw (`null` until the size is known) */
+    getScene(): ChartScene | null;
+    pointerDown(x: number, y: number, options?: ChartPointerOptions): void;
+    pointerMove(x: number, y: number, options?: ChartPointerOptions): void;
+    pointerUp(x: number, y: number, options?: ChartPointerOptions): void;
+    pointerCancel(options?: ChartPointerOptions): void;
+    /** The mouse left the chart */
+    pointerLeave(): void;
+    /** Zooms around a pixel (factor < 1 zooms in) */
+    zoomAt(x: number, y: number, factor: number): void;
+    resetZoom(): void;
+    getView(): ChartView;
+    setView(view: Partial<ChartView>): void;
+    /** Shows / hides a series (like a legend click) */
+    toggleSeries(id: string): void;
+    /** Hides the tooltip */
+    clearHover(): void;
+    getPlotRect(): ChartRect | null;
+    toPixel(x: number, y: number): {
+        x: number;
+        y: number;
+    } | null;
+    fromPixel(x: number, y: number): {
+        x: number;
+        y: number;
+    } | null;
+    on<K extends keyof ChartControllerEventMap>(type: K, listener: (event: ChartControllerEventMap[K]) => void): () => void;
+    destroy(): void;
+}
+export declare const createChartController: (config: ChartControllerConfig) => ChartController;
+/** A polyline (pixels of the chart): interleaved x, y */
+export interface ChartLinePrimitive {
+    kind: "line";
+    seriesIndex: number;
+    color: string;
+    width: number;
+    /** Runs of points without gaps */
+    segments: number[][];
+}
+export interface ChartAreaPrimitive {
+    kind: "area";
+    seriesIndex: number;
+    color: string;
+    opacity: number;
+    /** Y pixel of the baseline */
+    baseline: number;
+    segments: number[][];
+}
+export interface ChartBarPrimitive {
+    kind: "bars";
+    seriesIndex: number;
+    color: string;
+    /** Interleaved x, y, width, height */
+    rects: number[];
+}
+export interface ChartDotPrimitive {
+    kind: "dots";
+    seriesIndex: number;
+    opacity: number;
+    /** Interleaved x, y, diameter */
+    dots: number[];
+    /** CSS color of every dot */
+    colors: string[];
+}
+export type ChartPrimitive = ChartLinePrimitive | ChartAreaPrimitive | ChartBarPrimitive | ChartDotPrimitive;
+export interface ChartPrimitiveOptions {
+    /**
+     * Upper bound of the dots drawn per series: above it the dots are merged
+     * into one per occupied cell of their size
+     * @default 4000
+     */
+    maxDots?: number;
+    /**
+     * Upper bound of the bars drawn per series: above it neighboring bars
+     * sharing a pixel column are merged
+     * @default 2000
+     */
+    maxBars?: number;
+    /**
+     * Width in pixels of the columns lines are decimated to (at most four
+     * points per column); larger values mean fewer shapes
+     * @default 1
+     */
+    columnWidth?: number;
+    /** Size of the cells dots are merged into (the dot size by default) */
+    dotCell?: number;
+}
+/**
+ * Data of a scene as simple shapes in pixels of the chart, for hosts
+ * without a canvas (React Native views, SVG): lines are decimated to a few
+ * points per pixel column and large point sets are merged per cell, so the
+ * number of shapes stays bounded by the size of the chart.
+ */
+export declare const scenePrimitives: (scene: ChartScene, limits?: ChartPrimitiveOptions) => ChartPrimitive[];

package/dist/charts/engine/controller.d.ts

@@ -0,0 +1,182 @@
+import { Rect } from './layout.js';
+import { ChartModel } from './model.js';
+import { PointLabel, ResolvedAnnotation } from './overlay.js';
+import { ChartLayout, HoverMark, TooltipContent } from './scene.js';
+import { ChartTheme, ChartThemeInput } from './theme.js';
+import { ChartEventMap, ChartHoverEvent, ChartOptions, ChartRect, ChartView } from './types.js';
+/** Events of a controller (no renderer events: hosts draw themselves) */
+export type ChartControllerEventMap = Omit<ChartEventMap, "renderer">;
+export interface ChartControllerConfig {
+    options: ChartOptions;
+    /** Colors and fonts (Minerva variables); light defaults when omitted */
+    theme?: ChartThemeInput;
+    /** Width in pixels of `text` drawn with the CSS `font` */
+    measureText: (text: string, font: string) => number;
+    /** Called when the scene changed and must be drawn again */
+    onInvalidate?: () => void;
+}
+export interface ChartLegendEntry {
+    id: string;
+    name: string;
+    /** CSS color */
+    color: string;
+    shape: "dot" | "line" | "square";
+    hidden: boolean;
+    /** Hit / draw box of the entry, pixels of the chart */
+    box: Rect;
+}
+export interface ChartLegendLayout {
+    entries: ChartLegendEntry[];
+    position: "top" | "bottom";
+    /** Whether a tap toggles the series */
+    toggle: boolean;
+    /** Height taken by the legend */
+    height: number;
+}
+export interface ChartTooltipLayout {
+    /** Default content (`text` is set instead when `tooltip.render` returns a string) */
+    content: TooltipContent;
+    /** Lines of a custom string tooltip */
+    text: string[] | null;
+    /** Box of the tooltip, pixels of the chart */
+    box: Rect;
+    /** Line height used to lay the box out */
+    lineHeight: number;
+    padding: number;
+}
+export interface ChartHoverLayout {
+    event: ChartHoverEvent;
+    marks: HoverMark[];
+    /** X pixel of the guide line (`null` when hidden) */
+    crosshairX: number | null;
+    tooltip: ChartTooltipLayout | null;
+}
+/** Everything a host draws, in CSS pixels of the chart */
+export interface ChartScene {
+    width: number;
+    height: number;
+    theme: ChartTheme;
+    model: ChartModel;
+    view: ChartView;
+    layout: ChartLayout;
+    annotations: ResolvedAnnotation[];
+    /** Labels of the dots that found a free slot */
+    pointLabels: {
+        label: PointLabel;
+        box: Rect;
+    }[];
+    legend: ChartLegendLayout | null;
+    hover: ChartHoverLayout | null;
+    /** Point being dragged (`interaction.dragPoints`) */
+    dragging: {
+        x: number;
+        y: number;
+        color: string;
+        size: number;
+    } | null;
+}
+export interface ChartPointerOptions {
+    /** Pointer id (touch identifier); 0 by default */
+    id?: number;
+    /** Touch input: the tooltip follows the finger and stays after a tap */
+    touch?: boolean;
+}
+export interface ChartController {
+    setOptions(options: ChartOptions): void;
+    setTheme(theme: ChartThemeInput | undefined): void;
+    /** Size of the chart in CSS pixels */
+    setSize(width: number, height: number): void;
+    /** What to draw (`null` until the size is known) */
+    getScene(): ChartScene | null;
+    pointerDown(x: number, y: number, options?: ChartPointerOptions): void;
+    pointerMove(x: number, y: number, options?: ChartPointerOptions): void;
+    pointerUp(x: number, y: number, options?: ChartPointerOptions): void;
+    pointerCancel(options?: ChartPointerOptions): void;
+    /** The mouse left the chart */
+    pointerLeave(): void;
+    /** Zooms around a pixel (factor < 1 zooms in) */
+    zoomAt(x: number, y: number, factor: number): void;
+    resetZoom(): void;
+    getView(): ChartView;
+    setView(view: Partial<ChartView>): void;
+    /** Shows / hides a series (like a legend click) */
+    toggleSeries(id: string): void;
+    /** Hides the tooltip */
+    clearHover(): void;
+    getPlotRect(): ChartRect | null;
+    toPixel(x: number, y: number): {
+        x: number;
+        y: number;
+    } | null;
+    fromPixel(x: number, y: number): {
+        x: number;
+        y: number;
+    } | null;
+    on<K extends keyof ChartControllerEventMap>(type: K, listener: (event: ChartControllerEventMap[K]) => void): () => void;
+    destroy(): void;
+}
+export declare const createChartController: (config: ChartControllerConfig) => ChartController;
+/** A polyline (pixels of the chart): interleaved x, y */
+export interface ChartLinePrimitive {
+    kind: "line";
+    seriesIndex: number;
+    color: string;
+    width: number;
+    /** Runs of points without gaps */
+    segments: number[][];
+}
+export interface ChartAreaPrimitive {
+    kind: "area";
+    seriesIndex: number;
+    color: string;
+    opacity: number;
+    /** Y pixel of the baseline */
+    baseline: number;
+    segments: number[][];
+}
+export interface ChartBarPrimitive {
+    kind: "bars";
+    seriesIndex: number;
+    color: string;
+    /** Interleaved x, y, width, height */
+    rects: number[];
+}
+export interface ChartDotPrimitive {
+    kind: "dots";
+    seriesIndex: number;
+    opacity: number;
+    /** Interleaved x, y, diameter */
+    dots: number[];
+    /** CSS color of every dot */
+    colors: string[];
+}
+export type ChartPrimitive = ChartLinePrimitive | ChartAreaPrimitive | ChartBarPrimitive | ChartDotPrimitive;
+export interface ChartPrimitiveOptions {
+    /**
+     * Upper bound of the dots drawn per series: above it the dots are merged
+     * into one per occupied cell of their size
+     * @default 4000
+     */
+    maxDots?: number;
+    /**
+     * Upper bound of the bars drawn per series: above it neighboring bars
+     * sharing a pixel column are merged
+     * @default 2000
+     */
+    maxBars?: number;
+    /**
+     * Width in pixels of the columns lines are decimated to (at most four
+     * points per column); larger values mean fewer shapes
+     * @default 1
+     */
+    columnWidth?: number;
+    /** Size of the cells dots are merged into (the dot size by default) */
+    dotCell?: number;
+}
+/**
+ * Data of a scene as simple shapes in pixels of the chart, for hosts
+ * without a canvas (React Native views, SVG): lines are decimated to a few
+ * points per pixel column and large point sets are merged per cell, so the
+ * number of shapes stays bounded by the size of the chart.
+ */
+export declare const scenePrimitives: (scene: ChartScene, limits?: ChartPrimitiveOptions) => ChartPrimitive[];