@dschz/solid-uplot 0.1.0

package/dist/plugins/index.d.ts

@@ -0,0 +1,443 @@
+import { P as PluginFactory, S as SolidUplotPluginBus } from '../createPluginBus-B_Gp5BCB.js';
+import { C as CursorData } from '../getCursorData-2qxURGuZ.js';
+import { Component, JSX } from 'solid-js';
+import uPlot from 'uplot';
+import { S as SeriesDatum } from '../getSeriesData-D1zBqQ9Y.js';
+import 'solid-js/store';
+
+/**
+ * Message structure for cursor plugin communication via the plugin bus.
+ */
+type CursorPluginMessage = {
+    /**
+     * The ID of the plot instance that originated this cursor message.
+     * Used to identify which chart is the source of cursor updates.
+     */
+    readonly sourceId?: string;
+    /**
+     * State object containing cursor data for each plot instance.
+     * Key is the plot ID, value is the cursor data for that plot.
+     */
+    readonly state: {
+        [plotId: string]: CursorData | undefined;
+    };
+};
+/**
+ * The message bus interface for the cursor plugin.
+ * Defines the structure of cursor-related data shared between plugins.
+ */
+type CursorPluginMessageBus = {
+    /**
+     * Cursor plugin message containing state and source information.
+     */
+    cursor?: CursorPluginMessage;
+};
+/**
+ * Creates a cursor plugin that tracks and shares cursor position and state across charts.
+ *
+ * This plugin enables cursor synchronization between multiple charts and provides
+ * cursor data to other plugins (like tooltips) via the plugin bus system.
+ *
+ * **Features:**
+ * - Tracks cursor position and x-series data indices
+ * - Transmits cursor data via plugin bus for cross-plugin synchronization
+ *
+ * **Usage:**
+ * ```typescript
+ * import { createPluginBus } from '@dschz/solid-uplot';
+ * import { cursor, type CursorPluginMessageBus } from '@dschz/solid-uplot/plugins';
+ *
+ * const bus = createPluginBus<CursorPluginMessageBus>();
+ *
+ * <SolidUplot
+ *   // ... other props
+ *   plugins={[cursor()]}
+ *   pluginBus={bus}
+ * />
+ * ```
+ *
+ * **Plugin Bus Data:**
+ * The plugin populates `bus.data.cursor` with:
+ * - `sourceId`: ID of the chart that last updated the cursor
+ * - `state[plotId]`: Cursor data for each chart instance
+ *
+ * See {@link CursorPluginMessage} for the complete data structure.
+ *
+ * @returns A plugin factory function that creates the cursor plugin instance
+ *
+ * @example
+ * ```typescript
+ * // Use with other plugins that depend on cursor data
+ * const plugins = [
+ *   cursor(),
+ *   tooltip(MyTooltipComponent),
+ *   focusSeries()
+ * ];
+ * ```
+ */
+declare const cursor: () => PluginFactory<CursorPluginMessageBus>;
+
+/**
+ * Target a series by its label.
+ */
+type SeriesByLabel = {
+    /**
+     * The label of the series.
+     */
+    readonly label: string;
+    readonly index?: never;
+    readonly zeroIndex?: never;
+};
+/**
+ * Target a series by its uPlot index.
+ */
+type SeriesByIndex = {
+    readonly label?: never;
+    /**
+     * The index of the y-series as according to uPlot.
+     *
+     * For example, if we have 3 y-series, they would have the following uPlot-based indices:
+     * - 1
+     * - 2
+     * - 3
+     *
+     * Note that the x-series is not included in this indexing (which starts at index 0 within uPlot).
+     */
+    readonly index: number;
+    readonly zeroIndex?: never;
+};
+/**
+ * Target a series by its zero-based index.
+ */
+type SeriesByZeroIndex = {
+    readonly label?: never;
+    readonly index?: never;
+    /**
+     * The zero-based index of the series.
+     *
+     * This is the index of the y-series if we were to treat them with zero-based indexing.
+     *
+     * For example, if we have 3 y-series, they would have the following zero-based indices:
+     * - 0
+     * - 1
+     * - 2
+     *
+     * Note that the x-series is not included in this zero-based indexing.
+     */
+    readonly zeroIndex: number;
+};
+/**
+ * Defines how to target a specific series for focusing.
+ * Can target by label, uPlot index, or zero-based index.
+ */
+type SeriesFocusTarget = SeriesByLabel | SeriesByIndex | SeriesByZeroIndex;
+/**
+ * Message structure for focus series plugin communication via the plugin bus.
+ */
+type FocusSeriesPluginMessage = {
+    /**
+     * The id of the source that triggered the focus series event.
+     */
+    readonly sourceId: string;
+    /**
+     * The list of target series to focus.
+     */
+    readonly targets: SeriesFocusTarget[];
+};
+/**
+ * The message bus interface for the focus series plugin.
+ * Defines the structure of focus series data shared between plugins.
+ */
+type FocusSeriesPluginMessageBus = {
+    /**
+     * Focus series plugin message containing source and target information.
+     */
+    focusSeries?: FocusSeriesPluginMessage;
+};
+/**
+ * Configuration options for the focus series plugin.
+ */
+type FocusSeriesPluginOptions = {
+    /**
+     * The vertical distance in pixels required to focus a series.
+     * If the cursor's Y position is within this threshold of a Y value, that series is considered focused.
+     *
+     * @default 5
+     */
+    readonly pxThreshold?: number;
+    /**
+     * The alpha value to set for unfocused series.
+     *
+     * @default 0.1
+     */
+    readonly unfocusedAlpha?: number;
+    /**
+     * The alpha value to set for focused series.
+     *
+     * @default 1
+     */
+    readonly focusedAlpha?: number;
+    /**
+     * Whether to rebuild the paths of the series during redraw.
+     * When set to `false`, uPlot will use the cached Path2D objects for the series.
+     *
+     * @default false
+     */
+    readonly rebuildPaths?: boolean;
+};
+/**
+ * Creates a focus series plugin that visually highlights series based on cursor proximity.
+ *
+ * This plugin dims non-focused series and highlights the series closest to the cursor position.
+ * When the cursor is within the specified pixel threshold of a series data point, that series
+ * becomes focused while others are dimmed.
+ *
+ * **Features:**
+ * - Automatic series focusing based on cursor proximity
+ * - Configurable pixel threshold for focus detection
+ * - Cross-chart focus synchronization via plugin bus
+ * - Smooth visual feedback with alpha transparency
+ * - Support for targeting series by label, index, or zero-based index
+ *
+ * **Requirements:**
+ * - Requires the cursor plugin to be active for position tracking
+ * - Needs a plugin bus for cursor data communication
+ *
+ * **Usage:**
+ * ```typescript
+ * import { createPluginBus } from '@dschz/solid-uplot';
+ * import { cursor, focusSeries, type CursorPluginMessageBus, type FocusSeriesPluginMessageBus } from '@dschz/solid-uplot/plugins';
+ *
+ * const bus = createPluginBus<CursorPluginMessageBus & FocusSeriesPluginMessageBus>();
+ *
+ * <SolidUplot
+ *   // ... other props
+ *   plugins={[cursor(), focusSeries({ pxThreshold: 10 })]}
+ *   pluginBus={bus}
+ * />
+ * ```
+ *
+ * @param options - Configuration options for focus behavior
+ * @returns A plugin factory function that creates the focus series plugin instance
+ */
+declare const focusSeries: (options?: FocusSeriesPluginOptions) => PluginFactory<CursorPluginMessageBus & FocusSeriesPluginMessageBus>;
+
+/**
+ * Simple legend placement options - only top corners to avoid axis conflicts
+ */
+type LegendPlacement = "top-left" | "top-right";
+type LegendProps = {
+    readonly u: uPlot;
+    readonly seriesData: SeriesDatum[];
+    readonly bus: SolidUplotPluginBus<CursorPluginMessageBus & FocusSeriesPluginMessageBus>;
+};
+type LegendRootProps = {
+    /**
+     * HTML id attribute for the legend root
+     * @default "solid-uplot-legend-root"
+     */
+    readonly id?: string;
+    /**
+     * CSS class name for the legend root
+     */
+    readonly class?: string;
+    /**
+     * Inline styles for the legend root
+     */
+    readonly style?: JSX.CSSProperties;
+    /**
+     * The z-index of the legend root
+     * @default 10
+     */
+    readonly zIndex?: number;
+};
+type LegendConfigOptions = {
+    /**
+     * Legend placement within the chart area
+     * @default "top-left"
+     */
+    readonly placement?: LegendPlacement;
+    /**
+     * Pixel offset from the chart edges
+     * @default 8
+     */
+    readonly pxOffset?: number;
+};
+type LegendPluginOptions = LegendRootProps & LegendConfigOptions;
+/**
+ * Creates a simple, opinionated legend plugin that displays custom legend content
+ * overlaid on the chart's drawing area.
+ *
+ * **Design Philosophy:**
+ * - Opinionated positioning: only top-left or top-right corners
+ * - Size-constrained: legend cannot exceed chart drawing area dimensions
+ * - Layout-agnostic: user controls internal layout and styling
+ * - Non-interfering: designed to work harmoniously with chart interactions
+ *
+ * **Features:**
+ * - Positioned within u.over element (chart drawing area)
+ * - Automatic size constraints to prevent overflow
+ * - Scroll handling for overflowing content
+ * - Plugin bus integration for reactive updates
+ *
+ * @param Component - SolidJS component to render as the legend content
+ * @param options - Configuration options for legend behavior and styling
+ * @returns A plugin factory function that creates the legend plugin instance
+ */
+declare const legend: (Component: Component<LegendProps>, options?: LegendPluginOptions) => PluginFactory<CursorPluginMessageBus & FocusSeriesPluginMessageBus>;
+
+/**
+ * Defines the preferred placement of the tooltip relative to the cursor position.
+ */
+type TooltipCursorPlacement = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+/**
+ * Props passed to the custom tooltip SolidJS component.
+ *
+ * The tooltip plugin automatically provides these props to your custom component,
+ * ensuring it always receives the latest cursor data from the cursor plugin via
+ * the plugin bus system. This creates a reactive data flow where cursor movements
+ * immediately trigger tooltip updates with fresh position and data information.
+ */
+type TooltipProps = {
+    /** The uPlot instance for accessing chart configuration and data */
+    readonly u: uPlot;
+    /**
+     * Current cursor data including position and data index, automatically updated
+     * by the cursor plugin and passed via the plugin bus system
+     */
+    readonly cursor: CursorData;
+    /** Array of series metadata for all series in the chart */
+    readonly seriesData: SeriesDatum[];
+    /**
+     * Optional focus series data from the focusSeries plugin.
+     *
+     * This is automatically updated by the focusSeries plugin and passed via the plugin bus system.
+     * You can use this to determine if a series is focused and apply different styling for content
+     * in your tooltip component.
+     */
+    readonly focusedSeries?: FocusSeriesPluginMessage;
+};
+/**
+ * Container styling and accessibility props for the tooltip wrapper.
+ */
+type TooltipRootProps = {
+    /**
+     * HTML id attribute for the tooltip root
+     *
+     * @default "solid-uplot-tooltip-root"
+     */
+    readonly id?: string;
+    /**
+     * CSS class name for the tooltip root
+     *
+     * @default undefined
+     */
+    readonly class?: string;
+    /**
+     * Inline styles for the tooltip root
+     *
+     * @default {}
+     */
+    readonly style?: JSX.CSSProperties;
+    /**
+     * The z-index of the tooltip root
+     * @default 20
+     */
+    readonly zIndex?: number;
+};
+/**
+ * Configuration options for tooltip behavior.
+ */
+type TooltipConfigOptions = {
+    /**
+     * Preferred corner of the tooltip (relative to the cursor)
+     * @default "top-left"
+     */
+    readonly placement?: TooltipCursorPlacement;
+};
+/**
+ * Combined options for the tooltip plugin including container props and behavior config.
+ */
+type TooltipPluginOptions = TooltipRootProps & TooltipConfigOptions;
+/**
+ * Creates a tooltip plugin that displays custom content when hovering over charts.
+ *
+ * This plugin renders a custom SolidJS component as a tooltip that follows the cursor
+ * and displays contextual information about the data point being hovered.
+ *
+ * **Features:**
+ * - Custom SolidJS component rendering
+ * - Automatic positioning with edge detection and flipping
+ * - Scroll-aware positioning that works with page scrolling
+ * - Configurable placement preferences
+ * - Accessible tooltip with proper ARIA attributes
+ * - Automatic cleanup and memory management
+ *
+ * **Requirements:**
+ * - Requires the cursor plugin to be active for position tracking
+ * - Needs a plugin bus for cursor data communication
+ *
+ * **Usage:**
+ * ```typescript
+ * import { createPluginBus } from '@dschz/solid-uplot';
+ * import { cursor, tooltip, type CursorPluginMessageBus, type TooltipProps } from '@dschz/solid-uplot/plugins';
+ * import type { Component } from 'solid-js';
+ *
+ * const bus = createPluginBus<CursorPluginMessageBus>();
+ *
+ * // Custom tooltip component MUST accept TooltipProps
+ * const MyTooltip: Component<TooltipProps> = (props) => {
+ *   const xDate = () => new Date(props.cursor.xValue * 1000).toLocaleDateString();
+ *
+ *   return (
+ *     <div style={{
+ *       background: "white", border: "1px solid #ccc", padding: "8px",
+ *       "border-radius": "4px", "box-shadow": "0 2px 4px rgba(0,0,0,0.1)"
+ *     }}>
+ *       <div style={{ "font-weight": "bold", "margin-bottom": "8px" }}>
+ *         {xDate()}
+ *       </div>
+ *       <For each={props.seriesData}>
+ *         {(series) => {
+ *           // Fetch data value using series index and cursor position
+ *           const value = () => props.u.data[series.seriesIdx]?.[props.cursor.idx];
+ *
+ *           return (
+ *             <Show when={series.visible}>
+ *               <div style={{ display: "flex", "align-items": "center", "margin-bottom": "4px" }}>
+ *                 <div style={{
+ *                   width: "10px", height: "10px", "border-radius": "50%",
+ *                   "background-color": series.stroke, "margin-right": "6px"
+ *                 }} />
+ *                 <span style={{ color: series.stroke }}>
+ *                   {series.label}: {value()?.toFixed(2)}
+ *                 </span>
+ *               </div>
+ *             </Show>
+ *           );
+ *         }}
+ *       </For>
+ *     </div>
+ *   );
+ * };
+ *
+ * <SolidUplot
+ *   // ... other props
+ *   plugins={[cursor(), tooltip(MyTooltip, { placement: "top-right" })]}
+ *   pluginBus={bus}
+ * />
+ * ```
+ *
+ * **Custom Tooltip Component Requirements:**
+ * - Must accept `TooltipProps` as props type (exported from '@dschz/solid-uplot/plugins')
+ * - Must be a valid SolidJS Component
+ * - Receives: `u` (uPlot instance), `cursor` (position/data), `seriesData` (series metadata)
+ * - Use `props.u.data[series.seriesIdx][props.cursor.idx]` to fetch data values
+ *
+ * @param Component - SolidJS component to render as the tooltip content
+ * @param options - Configuration options for tooltip behavior and styling
+ * @returns A plugin factory function that creates the tooltip plugin instance
+ */
+declare const tooltip: (Component: Component<TooltipProps>, options?: TooltipPluginOptions) => PluginFactory<CursorPluginMessageBus & FocusSeriesPluginMessageBus>;
+
+export { type CursorPluginMessage, type CursorPluginMessageBus, type FocusSeriesPluginMessage, type FocusSeriesPluginMessageBus, type LegendProps, type TooltipProps, cursor, focusSeries, legend, tooltip };