@dschz/solid-uplot 0.1.2 → 0.1.3

package/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

package/dist/createPluginBus-DdrjQANs.d.ts

@@ -0,0 +1,126 @@
+import { Store, SetStoreFunction } from 'solid-js/store';
+
+/** Base constraint for plugin bus data structures */
+type VoidStruct = Record<string, unknown>;
+/**
+ * Internal type representing the plugin store structure
+ * @internal
+ */
+type PluginStore<T> = {
+    readonly data: Store<T>;
+    readonly setData: SetStoreFunction<T>;
+};
+/**
+ * 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>();
+ * ```
+ */
+declare const createPluginBus: <T extends VoidStruct = VoidStruct>(initialData?: T) => PluginStore<T>;
+/**
+ * Type representing a SolidUplot plugin bus instance
+ *
+ * @template T - The type of the plugin bus data structure
+ */
+type SolidUplotPluginBus<T extends VoidStruct = VoidStruct> = ReturnType<typeof createPluginBus<T>>;
+/**
+ * Context object passed to plugin factory functions
+ *
+ * @template T - The type of the plugin bus data structure
+ */
+type UplotPluginFactoryContext<T extends VoidStruct = VoidStruct> = {
+    /** The plugin communication bus for sharing data between plugins */
+    readonly bus?: SolidUplotPluginBus<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
+ */
+type UplotPluginFactory<T extends VoidStruct = VoidStruct> = (ctx: UplotPluginFactoryContext<T>) => uPlot.Plugin;
+
+export { type SolidUplotPluginBus as S, type UplotPluginFactory as U, type VoidStruct as V, type UplotPluginFactoryContext as a, createPluginBus as c };

package/dist/index/index.d.ts

@@ -1,5 +1,5 @@
-import { V as VoidStruct, S as SolidUplotPluginBus, P as PluginFactory } from '../createPluginBus-B_Gp5BCB.js';
-export { c as createPluginBus } from '../createPluginBus-B_Gp5BCB.js';
+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 } from 'solid-js';
 import uPlot from 'uplot';
 import { S as SeriesDatum } from '../getSeriesData-D1zBqQ9Y.js';
@@ -13,7 +13,7 @@ type ChildrenPlacement = "top" | "bottom";
  *
  * @template T - The type of the plugin bus data structure
  */
-type SolidUplotPlugin<T extends VoidStruct = VoidStruct> = uPlot.Plugin | PluginFactory<T>;
+type SolidUplotPlugin<T extends VoidStruct = VoidStruct> = uPlot.Plugin | UplotPluginFactory<T>;
 /**
  * Configuration options for the SolidUplot component, extending uPlot.Options
  * with SolidJS-specific enhancements
@@ -102,4 +102,4 @@ type SolidUplotProps<T extends VoidStruct = VoidStruct> = SolidUplotOptions<T> &
  */
 declare const SolidUplot: <T extends VoidStruct = VoidStruct>(props: ParentProps<SolidUplotProps<T>>) => JSX.Element;
 
-export { SolidUplot };
+export { SolidUplot, SolidUplotPluginBus, UplotPluginFactory };

package/dist/plugins/index.d.ts

@@ -1,4 +1,4 @@
-import { P as PluginFactory, S as SolidUplotPluginBus } from '../createPluginBus-B_Gp5BCB.js';
+import { U as UplotPluginFactory, S as SolidUplotPluginBus } from '../createPluginBus-DdrjQANs.js';
 import { C as CursorData } from '../getCursorData-2qxURGuZ.js';
 import { Component, JSX } from 'solid-js';
 import uPlot from 'uplot';
@@ -75,7 +75,7 @@ type CursorPluginMessageBus = {
  * ];
  * ```
  */
-declare const cursor: () => PluginFactory<CursorPluginMessageBus>;
+declare const cursor: () => UplotPluginFactory<CursorPluginMessageBus>;
 
 /**
  * Target a series by its label.
@@ -220,7 +220,7 @@ type FocusSeriesPluginOptions = {
  * @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>;
+declare const focusSeries: (options?: FocusSeriesPluginOptions) => UplotPluginFactory<CursorPluginMessageBus & FocusSeriesPluginMessageBus>;
 
 /**
  * Simple legend placement options - only top corners to avoid axis conflicts
@@ -291,7 +291,7 @@ type LegendPluginOptions = LegendRootProps & LegendConfigOptions;
  * @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>;
+declare const legend: (Component: Component<LegendProps>, options?: LegendPluginOptions) => UplotPluginFactory<CursorPluginMessageBus & FocusSeriesPluginMessageBus>;
 
 /**
  * Defines the preferred placement of the tooltip relative to the cursor position.
@@ -445,6 +445,6 @@ type TooltipPluginOptions = TooltipRootProps & TooltipConfigOptions;
  * @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>;
+declare const tooltip: (Component: Component<TooltipProps>, options?: TooltipPluginOptions) => UplotPluginFactory<CursorPluginMessageBus & FocusSeriesPluginMessageBus>;
 
 export { type CursorPluginMessage, type CursorPluginMessageBus, type FocusSeriesPluginMessage, type FocusSeriesPluginMessageBus, type LegendProps, type TooltipProps, cursor, focusSeries, legend, tooltip };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dschz/solid-uplot",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "SolidJS wrapper for uPlot — ultra-fast, tiny time-series & charting library",
   "type": "module",
   "author": "Daniel Sanchez <dsanc89@pm.me>",

package/dist/createPluginBus-B_Gp5BCB.d.ts

@@ -1,21 +0,0 @@
-import { Store, SetStoreFunction } from 'solid-js/store';
-
-type VoidStruct = Record<string, unknown>;
-type PluginStore<T> = {
-    readonly data: Store<T>;
-    readonly setData: SetStoreFunction<T>;
-};
-/**
- * Represents 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`).
- */
-declare const createPluginBus: <T extends VoidStruct = VoidStruct>(initialData?: T) => PluginStore<T>;
-type SolidUplotPluginBus<T extends VoidStruct = VoidStruct> = ReturnType<typeof createPluginBus<T>>;
-type PluginFactoryContext<T extends VoidStruct = VoidStruct> = {
-    readonly bus?: SolidUplotPluginBus<T>;
-};
-type PluginFactory<T extends VoidStruct = VoidStruct> = (ctx: PluginFactoryContext<T>) => uPlot.Plugin;
-
-export { type PluginFactory as P, type SolidUplotPluginBus as S, type VoidStruct as V, createPluginBus as c };