@dschz/solid-uplot/dist/index/index.d.ts

SolidJS wrapper for uPlot — ultra-fast, tiny time-series & charting library

import { V as VoidStruct, S as SolidUplotPluginBus, U as UplotPluginFactory } from '../createPluginBus-DdrjQANs.js';
export { a as UplotPluginFactoryContext, c as createPluginBus } from '../createPluginBus-DdrjQANs.js';
import { ParentProps, JSX, Ref } from 'solid-js';
import uPlot$1 from 'uplot';
import { C as CursorData, S as SeriesDatum } from '../getSeriesData-04wGQord.js';
import 'solid-js/store';

type OnCursorMoveParams = {
    /** The uPlot instance */
    readonly u: uPlot;
    /** The cursor data */
    readonly cursor: CursorData;
    /** Array of series data extracted from the chart configuration */
    readonly seriesData: SeriesDatum[];
};

/** Placement options for children components relative to the chart */
type ChildrenPlacement = "top" | "bottom";
/**
 * A SolidJS-compatible uPlot plugin that can be either a standard uPlot plugin
 * or a factory function that creates a plugin with access to the plugin bus
 *
 * @template T - The type of the plugin bus data structure
 */
type SolidUplotPlugin<T extends VoidStruct = VoidStruct> = uPlot$1.Plugin | UplotPluginFactory<T>;
/**
 * Configuration options for the SolidUplot component, extending uPlot.Options
 * with SolidJS-specific enhancements
 *
 * @template T - The type of the plugin bus data structure
 */
type SolidUplotOptions<T extends VoidStruct = VoidStruct> = Omit<uPlot$1.Options, "plugins" | "width" | "height" | "data"> & {
    /**
     * Chart width in pixels.
     *
     * Used as a fixed dimension when `autoResize` is disabled.
     * Ignored when `autoResize` is enabled — the chart fills its
     * container's width automatically.
     *
     * @default 600
     */
    readonly width?: number;
    /**
     * Chart height in pixels.
     *
     * Used as a fixed dimension when `autoResize` is disabled.
     * Ignored when `autoResize` is enabled — the chart fills its
     * container's height automatically.
     *
     * @default 300
     */
    readonly height?: number;
    /** Chart data - accepts AlignedData or number[][] */
    readonly data?: uPlot$1.AlignedData | number[][];
    /** Plugin communication bus for coordinating between plugins */
    readonly pluginBus?: SolidUplotPluginBus<T>;
    /** Array of plugins to apply to the chart */
    readonly plugins?: SolidUplotPlugin<T>[];
};
/**
 * Metadata provided to the onCreate callback when the chart is initialized
 */
type OnCreateMeta = {
    /** Array of series data extracted from the chart configuration */
    readonly seriesData: SeriesDatum[];
};
/**
 * Events that can be passed to the SolidUplot component
 */
type SolidUplotEvents = {
    /** Callback fired when the uPlot instance is created */
    readonly onCreate?: (u: uPlot$1, meta: OnCreateMeta) => void;
    /** Callback fired when the cursor moves */
    readonly onCursorMove?: (params: OnCursorMoveParams) => void;
};
/**
 * Props for the SolidUplot component
 *
 * @template T - The type of the plugin bus data structure
 */
type SolidUplotProps<T extends VoidStruct = VoidStruct> = SolidUplotOptions<T> & SolidUplotEvents & {
    /** Class name for the chart container */
    readonly class?: string;
    /** CSS styles for the chart container (position is managed internally) */
    readonly style?: Omit<JSX.CSSProperties, "position">;
    /** Ref callback to access the chart container element */
    readonly ref?: Ref<HTMLDivElement>;
    /**
     * Enable automatic resizing to fit container.
     *
     * When enabled, the chart uses a ResizeObserver to continuously
     * match its container's dimensions. The `width` and `height` props
     * are ignored — the chart fills whatever space its container provides.
     *
     * The container **must** have defined dimensions (explicit height/width,
     * flex layout, grid layout, etc.). If the container has no height, the
     * chart will render at 0px and a development-mode warning will be logged.
     *
     * @default false
     */
    readonly autoResize?: boolean;
    /**
     * Whether to reset scales when chart data is updated
     * @default true
     */
    readonly resetScales?: boolean;
    /**
     * Where to place children components relative to the chart
     * @default "top"
     */
    readonly childrenPlacement?: ChildrenPlacement;
};
/**
 * A SolidJS wrapper component for uPlot charts with enhanced features
 *
 * This component provides:
 * - Reactive data updates
 * - Plugin system with communication bus
 * - Automatic resizing capabilities
 * - Flexible children placement
 * - TypeScript support with generics
 *
 * @template T - The type of the plugin bus data structure for type-safe plugin communication
 *
 * @param props - Component props extending uPlot options with SolidJS enhancements
 * @returns JSX element containing the chart and any children components
 *
 * @example
 * ```tsx
 * // Fixed size
 * <SolidUplot
 *   data={chartData}
 *   width={600}
 *   height={400}
 *   series={[{}, { label: "Series 1", stroke: "red" }]}
 * />
 *
 * // Auto resize (container must have dimensions)
 * <div style={{ height: "400px" }}>
 *   <SolidUplot
 *     data={chartData}
 *     autoResize
 *     series={[{}, { label: "Series 1", stroke: "red" }]}
 *   />
 * </div>
 * ```
 */
declare const SolidUplot: <T extends VoidStruct = VoidStruct>(props: ParentProps<SolidUplotProps<T>>) => JSX.Element;

export { SolidUplot, SolidUplotPluginBus, UplotPluginFactory };