fix: exports missing UplotPluginFactory type for plugin authoring

Author: thedanchez

README.md

@@ -42,7 +42,11 @@ Core components and plugin system:
 
 ```tsx
 import { SolidUplot, createPluginBus } from "@dschz/solid-uplot";
-import type { PluginFactory, SolidUplotPluginBus } from "@dschz/solid-uplot";
+import type {
+  SolidUplotPluginBus,
+  UplotPluginFactory,
+  UplotPluginFactoryContext,
+} from "@dschz/solid-uplot";
 ```
 
 ### `@dschz/solid-uplot/plugins`
@@ -376,7 +380,7 @@ const MyChart = () => {
 The plugin system is open to extension. When authoring plugins for public consumption, follow this pattern:
 
 ```tsx
-import type { PluginFactory } from "@dschz/solid-uplot";
+import type { UplotPluginFactory } from "@dschz/solid-uplot";
 import type { CursorPluginMessageBus } from "@dschz/solid-uplot/plugins";
 
 // 1. Define your plugin's message type
@@ -393,7 +397,7 @@ export type MyPluginMessageBus = {
 // 3. Export your plugin factory
 export const myPlugin = (
   options = {},
-): PluginFactory<CursorPluginMessageBus & MyPluginMessageBus> => {
+): UplotPluginFactory<CursorPluginMessageBus & MyPluginMessageBus> => {
   return ({ bus }) => {
     if (!bus) {
       console.warn("[my-plugin]: A plugin bus is required");
@@ -457,73 +461,67 @@ const MyDashboard = () => {
 ### SolidUplot Component
 
 ```tsx
-type SolidUplotProps<T extends VoidStruct = VoidStruct> = {
-  // Chart data (required)
-  data: uPlot.AlignedData;
+// Main component props (extends all uPlot.Options except plugins, width, height)
+type SolidUplotProps<T extends VoidStruct = VoidStruct> = SolidUplotOptions<T> & {
+  // Ref callback to access the chart container element
+  ref?: (el: HTMLDivElement) => void;
+
+  // Callback fired when the uPlot instance is created
+  onCreate?: (u: uPlot, meta: { seriesData: SeriesDatum[] }) => void;
+
+  // Whether to reset scales when chart data is updated (default: true)
+  resetScales?: boolean;
 
+  // CSS styles for the chart container (position is managed internally)
+  style?: Omit<JSX.CSSProperties, "position">;
+
+  // Where to place children components relative to the chart (default: "top")
+  childrenPlacement?: "top" | "bottom";
+
+  // Enable automatic resizing to fit container (default: false)
+  autoResize?: boolean;
+};
+
+// Configuration options extending uPlot.Options with SolidJS enhancements
+type SolidUplotOptions<T extends VoidStruct = VoidStruct> = Omit<
+  uPlot.Options,
+  "plugins" | "width" | "height"
+> & {
   // Chart dimensions
   width?: number; // default: 600
   height?: number; // default: 300
 
-  // Responsive sizing
-  autoResize?: boolean; // default: false
-
   // Plugin configuration
   plugins?: SolidUplotPlugin<T>[];
   pluginBus?: SolidUplotPluginBus<T>;
-
-  // Chart options (all uPlot.Options except plugins, width, height)
-  series?: uPlot.Series[];
-  scales?: uPlot.Scales;
-  axes?: uPlot.Axis[];
-  // ... other uPlot options
-
-  // Chart behavior
-  resetScales?: boolean; // default: true
-
-  // Callbacks
-  onCreate?: (u: uPlot, meta: { seriesData: SeriesDatum[] }) => void;
-
-  // Container styling
-  style?: JSX.CSSProperties;
-  class?: string;
-  id?: string;
-  ref?: (el: HTMLDivElement) => void;
-
-  // Children placement
-  childrenPlacement?: "top" | "bottom"; // default: "top"
 };
+
+// Plugin type (can be standard uPlot plugin or factory function)
+type SolidUplotPlugin<T extends VoidStruct = VoidStruct> = uPlot.Plugin | UplotPluginFactory<T>;
 ```
 
 ### Plugin Bus
 
 ```tsx
-type SolidUplotPluginBus<T extends VoidStruct = VoidStruct> = {
-  data: T;
-  setData: <K extends keyof T>(key: K, value: T[K]) => void;
-  setData: <K extends keyof T, P extends keyof T[K]>(
-    key: K,
-    path: P,
-    value: T[K][P]
-  ) => void;
-};
+// Plugin bus type (derived from createPluginBus return type)
+type SolidUplotPluginBus<T extends VoidStruct = VoidStruct> = ReturnType<typeof createPluginBus<T>>;
 
 // Create a plugin bus
-const createPluginBus = <T extends VoidStruct = VoidStruct>(
-  initialData?: Partial<T>
-): SolidUplotPluginBus<T>;
+const createPluginBus: <T extends VoidStruct = VoidStruct>(
+  initialData?: T,
+) => SolidUplotPluginBus<T>;
 ```
 
 ### Built-in Plugin Options
 
 ```tsx
 // Cursor Plugin
-const cursor = (): PluginFactory<CursorPluginMessageBus>;
+const cursor = (): UplotPluginFactory<CursorPluginMessageBus>;
 
 // Focus Series Plugin
 const focusSeries = (options?: {
   pxThreshold?: number; // default: 15
-}): PluginFactory<CursorPluginMessageBus & FocusSeriesPluginMessageBus>;
+}): UplotPluginFactory<CursorPluginMessageBus & FocusSeriesPluginMessageBus>;
 
 // Tooltip Plugin
 const tooltip = (
@@ -535,7 +533,7 @@ const tooltip = (
     style?: JSX.CSSProperties;
     zIndex?: number; // default: 20
   }
-): PluginFactory<CursorPluginMessageBus & FocusSeriesPluginMessageBus>;
+): UplotPluginFactory<CursorPluginMessageBus & FocusSeriesPluginMessageBus>;
 
 // Legend Plugin
 const legend = (
@@ -548,7 +546,7 @@ const legend = (
     style?: JSX.CSSProperties;
     zIndex?: number; // default: 10
   }
-): PluginFactory<CursorPluginMessageBus & FocusSeriesPluginMessageBus>;
+): UplotPluginFactory<CursorPluginMessageBus & FocusSeriesPluginMessageBus>;
 ```
 
 ## 📚 Examples

src/SolidUplot.tsx

@@ -13,7 +13,7 @@ import {
 } from "solid-js";
 import uPlot from "uplot";
 
-import type { PluginFactory, SolidUplotPluginBus, VoidStruct } from "./createPluginBus";
+import type { SolidUplotPluginBus, UplotPluginFactory, VoidStruct } from "./createPluginBus";
 import { getSeriesData, type SeriesDatum } from "./utils/getSeriesData";
 
 /** Placement options for children components relative to the chart */
@@ -25,7 +25,9 @@ type ChildrenPlacement = "top" | "bottom";
  *
  * @template T - The type of the plugin bus data structure
  */
-export type SolidUplotPlugin<T extends VoidStruct = VoidStruct> = uPlot.Plugin | PluginFactory<T>;
+export type SolidUplotPlugin<T extends VoidStruct = VoidStruct> =
+  | uPlot.Plugin
+  | UplotPluginFactory<T>;
 
 /**
  * Configuration options for the SolidUplot component, extending uPlot.Options

src/createPluginBus.tsx

@@ -1,17 +1,36 @@
 import { createStore, type SetStoreFunction, type Store } from "solid-js/store";
 
+/** Base constraint for plugin bus data structures */
 export type VoidStruct = Record<string, unknown>;
 
+/**
+ * Internal type representing the plugin store structure
+ * @internal
+ */
 type PluginStore<T> = {
   readonly data: Store<T>;
   readonly setData: SetStoreFunction<T>;
 };
 
 /**
- * Represents a reactive store shared across SolidUplot plugins.
+ * Creates a reactive store shared across SolidUplot plugins.
  *
  * This store acts as a message bus, allowing plugins to publish and
  * subscribe to typed messages based on agreed-upon keys (e.g., `tooltip`, `highlight`).
+ *
+ * @template T - The type of the plugin bus data structure
+ * @param initialData - Initial data for the plugin bus
+ * @returns A reactive store with data and setData functions
+ *
+ * @example
+ * ```tsx
+ * type MyBusData = {
+ *   tooltip?: { x: number; y: number; visible: boolean };
+ *   highlight?: { seriesIndex: number };
+ * };
+ *
+ * const bus = createPluginBus<MyBusData>();
+ * ```
  */
 export const createPluginBus = <T extends VoidStruct = VoidStruct>(
   initialData: T = {} as T,
@@ -20,14 +39,100 @@ export const createPluginBus = <T extends VoidStruct = VoidStruct>(
   return { data, setData };
 };
 
+/**
+ * Type representing a SolidUplot plugin bus instance
+ *
+ * @template T - The type of the plugin bus data structure
+ */
 export type SolidUplotPluginBus<T extends VoidStruct = VoidStruct> = ReturnType<
   typeof createPluginBus<T>
 >;
 
-export type PluginFactoryContext<T extends VoidStruct = VoidStruct> = {
+/**
+ * Context object passed to plugin factory functions
+ *
+ * @template T - The type of the plugin bus data structure
+ */
+export type UplotPluginFactoryContext<T extends VoidStruct = VoidStruct> = {
+  /** The plugin communication bus for sharing data between plugins */
   readonly bus?: SolidUplotPluginBus<T>;
 };
 
-export type PluginFactory<T extends VoidStruct = VoidStruct> = (
-  ctx: PluginFactoryContext<T>,
+/**
+ * Factory function type for creating uPlot plugins with access to the SolidUplot plugin bus
+ *
+ * This allows plugins to communicate with each other and share state reactively through
+ * the SolidJS store system. Plugin factories receive a context object containing the
+ * plugin bus and return a standard uPlot plugin.
+ *
+ * When authoring plugins for public consumption, follow this pattern:
+ * 1. Define your plugin's message type
+ * 2. Define your plugin's message bus type
+ * 3. Export your plugin factory with proper type constraints
+ * 4. Include bus validation and warning messages
+ *
+ * @template T - The type of the plugin bus data structure for type-safe communication
+ *
+ * @param ctx - Context object containing the plugin bus and other shared resources
+ * @returns A standard uPlot plugin object with hooks
+ *
+ * @example
+ * ```tsx
+ * import type { UplotPluginFactory } from '@dschz/solid-uplot';
+ * import type { CursorPluginMessageBus } from '@dschz/solid-uplot/plugins';
+ *
+ * // 1. Define your plugin's message type
+ * export type MyPluginMessage = {
+ *   value: number;
+ *   timestamp: number;
+ * };
+ *
+ * // 2. Define your plugin's message bus type
+ * export type MyPluginMessageBus = {
+ *   myPlugin?: MyPluginMessage;
+ * };
+ *
+ * // 3. Export your plugin factory with proper type constraints
+ * export const myPlugin = (
+ *   options = {},
+ * ): UplotPluginFactory<CursorPluginMessageBus & MyPluginMessageBus> => {
+ *   return ({ bus }) => {
+ *     // 4. Include bus validation and warning
+ *     if (!bus) {
+ *       console.warn("[my-plugin]: A plugin bus is required");
+ *       return { hooks: {} };
+ *     }
+ *
+ *     return {
+ *       hooks: {
+ *         ready: (u) => {
+ *           // Initialize plugin state
+ *           bus.setData("myPlugin", {
+ *             value: 0,
+ *             timestamp: Date.now(),
+ *           });
+ *         },
+ *         setData: (u) => {
+ *           // Update plugin state reactively
+ *           bus.setData("myPlugin", "value", (prev) => prev + 1);
+ *         },
+ *       },
+ *     };
+ *   };
+ * };
+ *
+ * // Usage with proper typing
+ * const bus = createPluginBus<CursorPluginMessageBus & MyPluginMessageBus>();
+ *
+ * <SolidUplot
+ *   data={data}
+ *   pluginBus={bus}
+ *   plugins={[cursor(), myPlugin()]}
+ * />
+ * ```
+ *
+ * @see {@link https://github.com/leeoniya/uPlot/tree/master/docs#plugins} uPlot Plugin Documentation
+ */
+export type UplotPluginFactory<T extends VoidStruct = VoidStruct> = (
+  ctx: UplotPluginFactoryContext<T>,
 ) => uPlot.Plugin;

src/index.tsx

@@ -1,2 +1,7 @@
-export { createPluginBus } from "./createPluginBus";
+export {
+  createPluginBus,
+  type SolidUplotPluginBus,
+  type UplotPluginFactory,
+  type UplotPluginFactoryContext,
+} from "./createPluginBus";
 export { SolidUplot } from "./SolidUplot";

src/plugins/cursor.ts

@@ -1,6 +1,6 @@
 import type uPlot from "uplot";
 
-import type { PluginFactory } from "../createPluginBus";
+import type { UplotPluginFactory } from "../createPluginBus";
 import { type CursorData, getCursorData } from "../utils/getCursorData";
 
 /**
@@ -75,7 +75,7 @@ export type CursorPluginMessageBus = {
  * ];
  * ```
  */
-export const cursor = (): PluginFactory<CursorPluginMessageBus> => {
+export const cursor = (): UplotPluginFactory<CursorPluginMessageBus> => {
   return ({ bus }) => {
     if (!bus) {
       console.warn("[solid-uplot]: A plugin bus is required for the cursor plugin");

src/plugins/focusSeries.ts

@@ -1,6 +1,6 @@
 import { createEffect, createRoot } from "solid-js";
 
-import type { PluginFactory } from "../createPluginBus";
+import type { UplotPluginFactory } from "../createPluginBus";
 import type { CursorPluginMessageBus } from "./cursor";
 
 const DEFAULT_UNFOCUSED_ALPHA = 0.1 as const;
@@ -198,7 +198,7 @@ const seriesFocusRedraw = (u: uPlot, options: SeriesFocusRedrawOptions = {}) =>
  */
 export const focusSeries = (
   options: FocusSeriesPluginOptions = {},
-): PluginFactory<CursorPluginMessageBus & FocusSeriesPluginMessageBus> => {
+): UplotPluginFactory<CursorPluginMessageBus & FocusSeriesPluginMessageBus> => {
   return ({ bus }) => {
     if (!bus) {
       console.warn("[solid-uplot]: A plugin bus is required for the focusSeries plugin");

src/plugins/legend.tsx

@@ -2,7 +2,7 @@ import { type Component, type JSX, mergeProps, splitProps } from "solid-js";
 import { render } from "solid-js/web";
 import uPlot from "uplot";
 
-import type { PluginFactory, SolidUplotPluginBus } from "../createPluginBus";
+import type { UplotPluginFactory, SolidUplotPluginBus } from "../createPluginBus";
 import { getSeriesData, type SeriesDatum } from "../utils/getSeriesData";
 import type { CursorPluginMessageBus } from "./cursor";
 import type { FocusSeriesPluginMessageBus } from "./focusSeries";
@@ -84,7 +84,7 @@ type LegendPluginOptions = LegendRootProps & LegendConfigOptions;
 export const legend = (
   Component: Component<LegendProps>,
   options: LegendPluginOptions = {},
-): PluginFactory<CursorPluginMessageBus & FocusSeriesPluginMessageBus> => {
+): UplotPluginFactory<CursorPluginMessageBus & FocusSeriesPluginMessageBus> => {
   return ({ bus }) => {
     if (!bus) {
       console.warn("[solid-uplot]: A plugin bus is required for the Legend plugin");

src/plugins/tooltip.tsx

@@ -2,7 +2,7 @@ import { type Component, type JSX, mergeProps, Show, splitProps } from "solid-js
 import { render } from "solid-js/web";
 import uPlot from "uplot";
 
-import type { PluginFactory } from "../createPluginBus";
+import type { UplotPluginFactory } from "../createPluginBus";
 import type { CursorData } from "../utils/getCursorData";
 import { getSeriesData, type SeriesDatum } from "../utils/getSeriesData";
 import type { CursorPluginMessageBus } from "./cursor";
@@ -224,7 +224,7 @@ export type TooltipPluginOptions = TooltipRootProps & TooltipConfigOptions;
 export const tooltip = (
   Component: Component<TooltipProps>,
   options: TooltipPluginOptions = {},
-): PluginFactory<CursorPluginMessageBus & FocusSeriesPluginMessageBus> => {
+): UplotPluginFactory<CursorPluginMessageBus & FocusSeriesPluginMessageBus> => {
   return ({ bus }) => {
     if (!bus) {
       console.warn("[solid-uplot]: A plugin bus is required for the tooltip plugin");